Skip to content
Back to search

docqa-agent

Ask questions about your documents and get cited answers. RAG (BM25) + Claude citations + FastAPI + MCP server, in Python.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hassan227227--docqa-agent/badge.svg)](/listings/hassan227227--docqa-agent)

HTML

<a href="/listings/hassan227227--docqa-agent"><img src="/api/listings/hassan227227--docqa-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
export ANTHROPIC_API_KEY=...                         # Windows: set ANTHROPIC_API_KEY=...

# CLI
python answer.py "What is the early termination fee?"

# HTTP API
uvicorn api:app --reload
curl "localhost:8000/search?q=credit+score+approval"
curl -X POST localhost:8000/ask -H "Content-Type: application/json" \
     -d '{"question": "Which documents does an applicant need?"}'

# Tests (no API key needed)
pytest -q

Docker

docker build -t docqa-agent .
docker run -p 8000:8000 -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY docqa-agent

The image runs as a non-root user and has a health check on `/health`. Tests run on every push via GitHub Actions (`.github/workflows/ci.yml`).

Point it at your own files with `DOCQA_DOCS=/path/to/folder` (`.md` and `.txt`). The sample documents in `sample_docs/` are fictional policies.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 91 lines
  1. # DocQA Agent
  2. ![tests](https://github.com/hassan227227/docqa-agent/actions/workflows/ci.yml/badge.svg)
  3. Ask questions about your own documents and get answers that cite the exact passages they came from. Built with Python, BM25 retrieval, Claude (with citations), FastAPI and an MCP server.
  4. ```
  5. documents ──► chunker ──► BM25 index ──┬──► /search (FastAPI)
  6. ├──► /ask ──► Claude + citations ──► grounded answer
  7. └──► MCP tools: search_docs, get_passage, list_documents
  8. ```
  9. ## Why
  10. Fintech and operations teams answer the same policy questions every day: lease terms, credit thresholds, required documents. DocQA retrieves the relevant passages and has Claude answer **only** from them, with a citation for every claim, so an analyst can check the answer in seconds. If the documents don't contain the answer, it says so.
  11. ## Features
  12. - **Retrieval (RAG):** paragraph-aware chunking with overlap and an Okapi BM25 index in pure Python. No vector database needed to get started, and it's fully unit-tested.
  13. - **Grounded answers with citations:** retrieved chunks go to Claude as `document` blocks with citations enabled; the response carries the quoted source text.
  14. - **Safety fallback:** if the model declines a request, the API retries on a fallback model automatically.
  15. - **HTTP API:** `GET /search` for retrieval only and `POST /ask` for answers (FastAPI, validated inputs).
  16. - **MCP server:** exposes the index to any MCP client (Claude Desktop, Claude Code, your own agents) as `search_docs`, `get_passage` and `list_documents`.
  17. - **CLI:** `python answer.py "question"`.
  18. ## Quick start
  19. ```bash
  20. python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
  21. pip install -r requirements.txt
  22. export ANTHROPIC_API_KEY=... # Windows: set ANTHROPIC_API_KEY=...
  23. # CLI
  24. python answer.py "What is the early termination fee?"
  25. # HTTP API
  26. uvicorn api:app --reload
  27. curl "localhost:8000/search?q=credit+score+approval"
  28. curl -X POST localhost:8000/ask -H "Content-Type: application/json" \
  29. -d '{"question": "Which documents does an applicant need?"}'
  30. # Tests (no API key needed)
  31. pytest -q
  32. ```
  33. ### Docker
  34. ```bash
  35. docker build -t docqa-agent .
  36. docker run -p 8000:8000 -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY docqa-agent
  37. ```
  38. The image runs as a non-root user and has a health check on `/health`. Tests run on every push via GitHub Actions (`.github/workflows/ci.yml`).
  39. Point it at your own files with `DOCQA_DOCS=/path/to/folder` (`.md` and `.txt`). The sample documents in `sample_docs/` are fictional policies.
  40. ## Use it from Claude Desktop (MCP)
  41. Add this to your Claude Desktop config:
  42. ```json
  43. {
  44. "mcpServers": {
  45. "docqa": {
  46. "command": "python",
  47. "args": ["/absolute/path/to/docqa-agent/mcp_server.py"],
  48. "env": { "DOCQA_DOCS": "/absolute/path/to/your/docs" }
  49. }
  50. }
  51. }
  52. ```
  53. ## Project layout
  54. | File | What it does |
  55. |---|---|
  56. | `retrieval.py` | Tokenizer, chunker, BM25 index, folder loader |
  57. | `answer.py` | Calls Claude with retrieved passages and returns the answer plus citations; also the CLI |
  58. | `api.py` | FastAPI app: `/health`, `/search`, `/ask` |
  59. | `mcp_server.py` | MCP server with `search_docs`, `get_passage`, `list_documents` |
  60. | `test_retrieval.py` | Unit tests for chunking and ranking |
  61. ## Roadmap
  62. - Embedding search (pgvector) alongside BM25, with rank fusion
  63. - PDF ingestion
  64. - An evaluation set measuring answer accuracy and citation coverage, using [llm-eval-kit](https://github.com/hassan227227/llm-eval-kit)
  65. ## Author
  66. Hassan Raza · [Portfolio](https://hassan227227.github.io) · [LinkedIn](https://www.linkedin.com/in/iamhassan890)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.