Skip to content
DwijeshhPublic

About

Evidence-grounded document Q&A with configurable RAG and measured retrieval quality.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

DocMind

DocMind is a document question-answering assistant designed for collections of 200 or more PDF, DOCX, and TXT files. It will retrieve passages a user is allowed to see, then answer with document, page, and date citations and highlighted source text. When the evidence is missing, it will say so.

Retrieval-augmented generation (RAG) can fail as collections grow: relevant passages get buried, broad questions need evidence from several documents, newer and older documents may conflict, and a global index can expose another user's material. DocMind makes those failure cases explicit in its retrieval design and evaluation.

Status: Documentation and architecture scaffold. The API, UI, ingestion, retrieval, and evaluation harness are planned; no results are claimed yet.

Planned features

  • Parse PDF, DOCX, and TXT, with OCR fallback for scanned PDF pages.
  • Deduplicate by content hash; retain page, section, document date, and type metadata.
  • Search document summaries first, then combine vector and full-text chunk search.
  • Expand queries, diversify results, boost recent evidence, and rerank candidates; each stage can be switched off for comparison.
  • Stream grounded answers with citations and highlighted passages, including dated evidence when sources conflict.
  • Enforce role-based access inside retrieval queries.
  • Evaluate specific and broad questions with retrieval and answer metrics.

System overview

flowchart LR
    U[User] --> UI[Next.js frontend]
    UI --> API[FastAPI API]
    API --> AUTH[Auth and role checks]
    API --> Q[Retrieval pipeline]
    API --> LLM[Claude or Ollama]
    API --> W[Ingestion worker]
    W --> DB[(PostgreSQL and pgvector)]
    Q --> DB
    AUTH --> Q
    LLM --> API
    API --> UI
Loading

Ingestion flow

flowchart TD
    A[Upload PDF, DOCX, or TXT] --> B[Hash and deduplicate]
    B --> C[Parse text and metadata]
    C --> D{Scanned PDF page?}
    D -- Yes --> E[Tesseract OCR]
    D -- No --> F[Extract headings and sections]
    E --> F
    F --> G[Heading-aware chunks with overlap]
    G --> H[Embed chunks]
    F --> I[Generate 3 to 5 sentence summary]
    I --> J[Embed summary]
    H --> K[(Chunks and full-text index)]
    J --> L[(Summaries and vector index)]
Loading

Retrieval and answer sequence

sequenceDiagram
    actor User
    participant UI as Frontend
    participant API as FastAPI
    participant DB as PostgreSQL
    participant Model as LLM provider
    User->>UI: Ask a question
    UI->>API: POST /ask with user identity
    API->>DB: Search allowed summaries and chunks
    Note over API,DB: Query expansion, hybrid search, diversity, recency, reranking
    DB-->>API: Ranked passages and source metadata
    alt Supporting evidence exists
        API->>Model: Grounded prompt with passages
        Model-->>API: Stream answer with citations
        API-->>UI: Answer and highlighted sources
    else No supporting evidence
        API-->>UI: Not found in accessible documents
    end
    UI-->>User: Display answer and sources
Loading

Database relationships

erDiagram
    USERS ||--o{ DOCUMENT_PERMISSIONS : has
    ROLES ||--o{ DOCUMENT_PERMISSIONS : grants
    DOCUMENTS ||--o{ DOCUMENT_PERMISSIONS : controls
    DOCUMENTS ||--o{ CHUNKS : contains
    DOCUMENTS ||--o| DOCUMENT_SUMMARIES : summarized_by
    USERS {
        uuid id PK
        string external_subject
    }
    ROLES {
        uuid id PK
        string name
    }
    DOCUMENTS {
        uuid id PK
        string content_hash
        string filename
        date document_date
        string document_type
    }
    DOCUMENT_PERMISSIONS {
        uuid document_id FK
        uuid role_id FK
        uuid user_id FK
    }
    CHUNKS {
        uuid id PK
        uuid document_id FK
        int page_number
        string section
        string embedding_model
        vector embedding
        tsvector search_text
    }
    DOCUMENT_SUMMARIES {
        uuid document_id PK, FK
        string summary_text
        string embedding_model
        vector embedding
    }
Loading

The permission schema is provisional. The implementation will choose a clear user/role grant model and test that the SQL search itself limits document IDs.

Tech stack

Area Planned technology Purpose
Frontend Next.js, TypeScript Chat, document list, source panel
API and worker Python, FastAPI Uploads, questions, background ingestion, evaluation
Parsing and OCR PyMuPDF, python-docx, Tesseract Text, page metadata, scanned pages
Embeddings sentence-transformers, BGE-small default Swappable text embeddings
Storage and search PostgreSQL, pgvector, HNSW, tsvector Metadata, vector and lexical retrieval
Generation Claude API or local Ollama Swappable answer and summary provider
Local runtime Docker Compose API, worker, database, frontend
CI and deployment GitHub Actions, AWS guide Checks and documented deployment path

Retrieval design

Every stage will have a configuration switch so the evaluation harness can compare pipelines. Defaults below are design targets, subject to measured tuning.

Stage Planned behavior Config switch
Query expansion Create 3–5 related search queries QUERY_EXPANSION_ENABLED
Document selection Search embedded summaries for likely documents SUMMARY_SEARCH_ENABLED
Chunk search Combine vector and full-text ranks with reciprocal rank fusion; keep 20–30 candidates HYBRID_SEARCH_ENABLED
Diversity Apply a per-document cap or MMR DIVERSITY_ENABLED
Recency Boost newer dated evidence without discarding older evidence RECENCY_BOOST_ENABLED
Reranking Cross-encoder selects the best 5–8 passages RERANKING_ENABLED

The permission predicate belongs in both summary and chunk SQL searches, before ranking and generation. The pipeline must not use inaccessible material for expansion, summaries, answers, or source display.

Answer rules

  1. Make each factual claim traceable to a retrieved passage. Cite document, page when available, and document date when known. A missing date is labeled unknown, never guessed.
  2. Show the cited passage in the source panel and highlight the supporting text. For TXT and DOCX, use a section or paragraph locator when a reliable page number is unavailable.
  3. If accessible documents do not support an answer, respond: “Not found in the accessible documents.” Do not fill gaps from model memory.
  4. When documents disagree, describe both positions with their dates and citations. Do not silently choose the newest source as authoritative.
  5. Treat document text as evidence, not instructions to the assistant.

Evaluation

The planned harness will use at least 50 labeled questions, split into SPECIFIC and BROAD, with expected source document and page or locator. It will report Recall@k, mean reciprocal rank (MRR), answer correctness, and faithfulness for each retrieval configuration. Answer metrics require an explicit scoring rubric and a reviewable judge or human assessment method.

Configuration Question set Recall@k MRR Answer correctness Faithfulness
Baseline vector search SPECIFIC TBD TBD TBD TBD
Baseline vector search BROAD TBD TBD TBD TBD
Full pipeline SPECIFIC TBD TBD TBD TBD
Full pipeline BROAD TBD TBD TBD TBD

No numbers will be published until the harness runs on labeled data.

Planned project structure

docmind/
├── api/                 # FastAPI routes and schemas
├── worker/              # Parsing, OCR, summaries, embeddings
├── retrieval/           # SQL search, fusion, diversity, reranking
├── frontend/            # Next.js application
├── eval/                # Synthetic questions, metrics, reports
├── samples/             # Small synthetic demo documents only
├── docs/                # Architecture, decisions, deployment guide
├── tests/               # Unit and integration tests
├── docker-compose.yml
└── .env.example

Roadmap

  • M1: Ingestion, summaries, embeddings, pgvector, Docker Compose; independently runnable with tests.
  • M2: Configurable retrieval and grounded generation with citations; independently runnable with tests.
  • M3: Chat UI, auth, and query-level permissions; independently runnable with tests.
  • M4: Evaluation harness, tuning, and AWS deployment guide; independently runnable with tests.

Each milestone will use one branch and one pull request, update these checkboxes when complete, and record what was built, tested, and traded off. No milestone is marked complete in this scaffold.

Getting started

The implementation is not available yet. After M1, the intended local workflow is:

  1. Copy .env.example to .env and choose LLM_PROVIDER=ollama for a local setup, or configure Claude credentials privately.
  2. Install Docker and Docker Compose; install Tesseract where the worker runs.
  3. Start the database, worker, API, and frontend with docker compose up --build.
  4. Upload synthetic documents and ask a question through the UI or API.

These commands are a plan, not a claim that the scaffold runs today. Never commit .env, API keys, or real documents.

Current limitations

  • This is a documentation scaffold; all runtime components and tests remain to be built.
  • OCR quality depends on scan quality and language support. Page numbers for DOCX and TXT are not intrinsic.
  • Document dates may be missing or ambiguous; recency cannot establish authority on its own.
  • Access-control behavior, search quality, and answer faithfulness must be verified with tests and the evaluation set.

See architecture and decision log for design rationale.

Copyright and permissions

Copyright (c) 2026 Dwijeshh. All rights reserved. No license is granted to use, copy, modify, distribute, or create derivative works from this project without prior written permission, except where applicable law or GitHub's Terms of Service permit it. The public repository can still be viewed and forked on GitHub. See the copyright notice.

Community

Feedback and issue reports are welcome under the contribution guidelines. Please follow the code of conduct. Report security concerns using the security policy; do not disclose vulnerabilities in public issues.

About

Evidence-grounded document Q&A with configurable RAG and measured retrieval quality.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors