README.md

---
title: DocsQA Smart Research Assistant
emoji: 📄
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
app_port: 7860
---

# DocsQA Smart Research Assistant

This is my take-home submission for the ABSTRABIT AI/ML Engineer assignment: a RAG-powered assistant where users upload PDFs, ask questions, and get grounded answers with citations.

## Live Project

- Live app (Railway): `https://docsbot-web-production.up.railway.app`
- GitHub: `https://github.com/KBaba7/DocsBot`
- Loom walkthrough: _add your link here_

## What I Built

The app supports authentication, PDF upload (up to 5 files and 10 pages per file), document chunking + vector indexing, and a chat experience that answers from uploaded documents first.  
If the uploaded documents are not enough, the agent falls back to web search and cites those sources too.

## Stack

- FastAPI + SQLAlchemy
- LangGraph agent
- Groq chat model
- Jina embeddings + Jina reranker
- Supabase Postgres + `pgvector`
- Railway deployment

## How Retrieval Works

Uploaded PDFs are parsed page by page and split into chunks.  
Each chunk is stored with metadata (document, page number, chunk index) and embedded into `pgvector`.

At question time:
1. LLM-based document filtering selects relevant documents from user's library
2. Vector search retrieves relevant chunks from selected documents
3. Jina reranking reorders the retrieved chunks for better final relevance
4. The agent answers from those chunks when possible
5. If evidence is weak, the agent uses web search and cites external URLs

## Chunking Strategy

- Splitter: LangChain `RecursiveCharacterTextSplitter`
- Chunk size: `1000`
- Overlap: `150`

Why this setup:
- It prefers breaking on paragraphs and sentence boundaries before falling back to smaller separators.
- It preserves more coherent chunks for contracts, specs, and structured PDFs.
- A smaller overlap keeps recall while reducing duplicated context in retrieval.

## Retrieval Approach

I use cosine similarity search in `pgvector`, then apply Jina reranking for better final ordering.  
The system uses an LLM-based retrieval planner to choose:

- the final number of chunks to keep
- the candidate pool to rerank

Those values are clamped to safe bounds before retrieval runs.

The UI shows:

- document name
- page number
- chunk excerpt

for retrieved document sources.

## Agent Routing Logic

The agent is prompted to prefer document context first.

- If retrieved document context is sufficient: answer from documents with citations.
- If not sufficient: clearly say docs are insufficient and use web search tool.

This is implemented as tool-based behavior in LangGraph rather than a static fallback message.

## Source Citations

Each turn stores/returns source metadata separately from the answer body.

- Vector source cards include:
  - document name
  - page number
  - snippet (short snippet from retrieved chunk)
- Web source cards include:
  - title
  - URL

## Conversation Memory

Conversation history is maintained within session scope, so follow-ups like “tell me more about that” work as expected.
The frontend also preserves the visible chat thread per session, so upload-triggered page refreshes do not wipe the current conversation view.

## Streaming UX

Answers are streamed into the chat UI progressively.

- the visible response is rendered chunk by chunk
- source cards are attached after the answer completes
- a slight pacing delay is added so the stream feels live to the user

The streaming route is separate from the standard JSON `/ask` response path.

## Bonus Feature

I added hash-based deduplicated ingestion:

- If the same PDF is uploaded again, processing/indexing is reused.
- Access control is still user-scoped via ownership mapping.

Why I chose this:
- saves compute/time,
- avoids duplicate indexing,
- keeps retrieval secure per user.

I also implemented LLM-based document filtering:

- The system sends all user documents (filename, summary, preview) to the LLM
- LLM semantically analyzes and selects only truly relevant documents for the query
- Returns a JSON array of relevant file hashes
- It is not forced to return a capped number of documents
- Fallback returns all candidate document hashes if the LLM call fails

## Challenges I Ran Into

1. Heavy embedding dependencies made deployment images too large.
   - I standardized on Jina API embeddings/reranking to keep the runtime lighter while preserving retrieval quality.
2. Source rendering got messy across multiple chat turns.
   - I separated answer text from source payloads and extracted sources per turn.
3. Intermittent DB DNS/pooler issues during deployment.
   - I improved connection handling and standardized Supabase transaction-pooler config.
4. UI state was getting lost after document uploads.
   - I persisted the active chat thread in session storage so the current conversation remains visible after refresh.

## If I Had More Time

- Add conversation history UI to display past chat sessions
- Add automated citation-faithfulness checks
- Add Alembic migrations for cleaner schema evolution
- Add stronger eval/observability for routing and retrieval quality

## Local Setup

```bash
cp .env.example .env
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
uvicorn app.main:app --reload
```

Open: `http://127.0.0.1:8000`

## Important Environment Variables

Required:
- `GROQ_API_KEY`
- `SECRET_KEY`
- `DATABASE_URL`
- `JINA_API_KEY`

Embeddings:
- `JINA_API_BASE` (default: `https://api.jina.ai/v1/embeddings`)
- `JINA_EMBEDDING_MODEL` (default: `jina-embeddings-v3`)
- `JINA_RERANKER_API_BASE` (default: `https://api.jina.ai/v1/rerank`)
- `JINA_RERANKER_MODEL` (default: `jina-reranker-v3`)
- `EMBEDDING_DIMENSIONS` (default: `1024`)
- `RETRIEVAL_K` (default minimum final context size: `4`)
- `RERANK_CANDIDATE_K` (default minimum rerank candidate pool: `12`)

Storage:
- `STORAGE_BACKEND=local|supabase`
- `SUPABASE_URL`
- `SUPABASE_SERVICE_ROLE_KEY`
- `SUPABASE_STORAGE_BUCKET`
- `SUPABASE_STORAGE_PREFIX`

Web search:
- `WEB_SEARCH_PROVIDER=duckduckgo|tavily`
- `TAVILY_API_KEY` (if using Tavily)

Auth:
- `ACCESS_TOKEN_EXPIRE_MINUTES` (default: `720`)
- For local development, lowering this can make login/logout testing easier

## API Endpoints

- `POST /register`
- `POST /login`
- `POST /logout`
- `POST /upload`
- `GET /documents`
- `DELETE /documents/{document_id}`
- `GET /documents/{document_id}/pdf`
- `POST /ask`
- `POST /ask/stream`

## Sample Documents

As requested in the assignment, sample PDFs are included in `test_documents/`.

## Railway Deployment

```bash
railway login
railway link
railway up
```

Set the same env vars in Railway service settings before deploying.