RAGDocs.

The evolution

Each version started
with a new question.

The first question was simple: can I ask a PDF a question and check my understanding? The later questions were about persistence, retrieval quality, long-running work, and the boundaries between users.

Current system / V3

Separate the responsibilities.
Keep the evidence connected.

FastAPI handles authentication, uploads, scope checks, and queries. Longer indexing jobs run in a Celery worker. PostgreSQL stores both application records and pgvector embeddings; Redis coordinates queued work and status events. V3 stores original files in configurable local object storage.

• FastAPI
• PostgreSQL 16 / pgvector
• Redis / Celery
• Hugging Face embeddings
• Gemini
• React / TanStack Query
• Docker Compose

Engineering / Ingestion

An upload is the start
of a job.

PDF extraction, normalization, embedding requests, and database writes can outlast a normal API request. The upload path returns a queued document record and dispatches indexing to Celery. Users can follow the document state while the worker processes it.

1. Extract pages
2. Clean text
3. Chunk by page
4. Embed
5. Persist

for page_number, text in pages:
    records.extend(
        (chunk, page_number)
        for chunk in _page_chunks(text)
    )

The page number travels with each chunk into persistence. Older documents may need reprocessing to gain this metadata.

Engineering / Retrieval

Meaning and exact terms
are different signals.

Dense search can connect different phrasings of an idea. Lexical search can recover exact names, IDs, numbers, and phrases. V3 exposes both, plus hybrid and smart modes, so retrieval strategy is an explicit part of the experience.

Dense

Embed the query and order scoped chunks by pgvector L2 distance.

Lexical

Use PostgreSQL full-text search to rank exact-term matches.

Hybrid

Merge dense and lexical candidates using reciprocal-rank-fusion-style ranking.

Smart

Choose lexical search for certain short, exact-looking queries; use hybrid otherwise.

Retrieve candidates, then refine the order.

Hybrid search combines rank positions rather than comparing raw vector-distance and lexical scores. Hybrid and lexical results then receive a lightweight rerank that blends retrieval score with query-term overlap. The current heuristic is intentionally simple; it is not a transformer cross-encoder.

overlap = len(terms & words) / max(len(terms), 1)
item["rerank_score"] = round(
    item.get("retrieval_score", item.get("score", 0)) * 0.7
    + overlap * 0.3,
    6,
)

A ranking technique is an implementation choice, not a measured quality result. A labeled query set is still needed to evaluate its effect.

Engineering / Grounding

The answer should carry
its sources with it.

Retrieved passages reach the language model with filename, page number when available, chunk ID, and rank. The response also exposes evidence and citations for the frontend, so an answer can be inspected alongside the passages that informed it.

if not evidence:
    return {
        "answer": "I don't have enough information in the selected documents to answer that.",
        "model": None,
    }

When retrieval returns no evidence, the query path abstains. When evidence exists, the prompt instructs the model to answer from it. That does not independently verify every generated claim; the default lightweight path does not run full claim-level verification.

Engineering / Scope & access

Relevance comes after
the access boundary.

V3 organizes documents into knowledge bases inside workspaces. A query may target the workspace, a knowledge base, or selected documents. The backend checks membership, roles, and scope consistency before exposing records or retrieving evidence.

1. User
2. Workspace
3. Knowledge base
4. Documents
5. Chunks

Authentication identifies the user; authorization determines which workspace operations they can perform. The authorization module ↗ enforces those membership and role checks.

Engineering / The product experience

Make the system’s state
visible to the person using it.

The separate React and TypeScript application coordinates authentication, workspaces, uploads, and search through a shared Axios client and TanStack Query.

Sessions that can be revoked.

JWT access tokens identify API requests. Refresh sessions are hashed in the backend, rotated on refresh, and revocable. The frontend attempts a refresh after ordinary API calls return 401 and clears the session if refreshing fails.

Know when indexing is ready.

Redis publishes document status events that FastAPI relays over authorized WebSockets. Query refreshes and status endpoints remain useful because Redis Pub/Sub is transient.

Observe before claiming improvement.

Query traces record strategy, latency, source counts, model usage, and errors. This makes the system easier to inspect and gives future experiments a starting point. Runtime telemetry does not establish retrieval accuracy.