EZLookUp

EZLookUp is a full-stack RAG (Retrieval-Augmented Generation) app for asking questions over your own files. It supports:

• PDF ingestion and semantic search
• Audio ingestion (lecture/podcast style files) with Whisper transcription
• Streaming LLM responses from Groq
• User auth and metadata/history via Supabase
• Per-user document isolation with Chroma metadata filtering

Tech Stack

• Frontend: Next.js (App Router), TypeScript, Tailwind CSS
• Backend: FastAPI, Python 3.11
• Vector DB: ChromaDB (persistent local data directory or mounted Docker volume)
• LLM + STT: Groq (llama-3.1-8b-instant, whisper-large-v3)
• Auth + metadata: Supabase

Project Structure

• frontend/ - Next.js UI and API proxy routes
• backend/ - FastAPI ingestion/query/voice endpoints
• data/chroma/ - persisted local Chroma data (when using Docker volume mapping)
• supabase/ - local Supabase config
• docker-compose.yml - backend container setup

Features

• Fast ingestion pipeline
  • PDF/audio chunking with batched collection.add() inserts (batch size 50)
  • Content hash deduplication using SHA-256
• Low-latency retrieval
  • Chroma semantic search with user_id filter
  • Streaming query endpoint (/query/stream)
• Voice-first querying
  • /voice-query accepts .m4a and .wav
  • Audio transcription through Groq Whisper
• User-aware data
  • Supabase stores document metadata and chat history
  • Queries scoped to each user's indexed chunks

Requirements

Install these locally:

• Node.js 18+ (20+ recommended)
• npm
• Python 3.11+
• pip
• (Optional) Docker Desktop for containerized backend

You also need active keys/services for:

• Groq API
• Supabase project (URL + keys)

Environment Variables

Create two env files:

backend/.env

GROQ_API_KEY=your_groq_api_key
SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_KEY=your_supabase_service_role_or_server_key
CHROMA_PERSIST_DIR=./chroma_data

# Optional: protects POST /admin/nuke-all
NUCLEAR_SECRET=your_admin_secret

frontend/.env.local

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Run Locally (Recommended: two terminals)

1) Start Backend (FastAPI)

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Backend health check:

curl http://localhost:8000/

Expected response:

{"status":"ok"}

2) Start Frontend (Next.js)

cd frontend
npm install
npm run dev

Open:

• http://localhost:3000

Run Backend with Docker (Optional)

If you prefer containerized backend only:

docker compose up --build backend

This maps:

• local ./data/chroma -> container /data/chroma
• backend on http://localhost:8000

Then run frontend normally with NEXT_PUBLIC_API_URL=http://localhost:8000.

API Endpoints (Backend)

• GET / - health check
• POST /upload - upload and index PDF
• POST /upload/audio - upload/transcribe/index long-form audio
• POST /query - non-streaming text answer
• POST /query/stream - streaming text answer
• POST /voice-query - ask by audio input (.m4a/.wav)
• POST /admin/nuke-all - admin-only destructive reset (requires X-Admin-Secret)

Typical User Flow

1. Sign up / sign in via Supabase auth.
2. Upload a PDF or audio file.
3. Backend extracts/transcribes, chunks, embeds, and indexes to Chroma.
4. Ask a question by text or voice.
5. Receive a response grounded in retrieved chunks; chat/history metadata is saved in Supabase.

Notes

• No .env example files are currently committed; use the templates above.
• Voice recording/upload from the browser may require microphone permissions and HTTPS in some environments.
• Make sure your Supabase project has the documents and chat_history tables used by the app.