Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
name: CI

on:
push:
branches: [main]
pull_request:

# A new push to a PR makes the in-flight run irrelevant.
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
backend:
name: Backend — pytest
runs-on: ubuntu-latest
defaults:
run:
working-directory: backend
env:
# The suite mocks the database and the embedding service, so no services are
# needed. AUTH_SECRET is required because `from app.main import app` builds
# Settings at import time, and a non-debug Settings refuses the dev default.
AUTH_SECRET: ci-only-secret-not-used-for-any-real-session
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.13"
cache: pip
cache-dependency-path: backend/requirements.txt

- name: Install dependencies
run: pip install -r requirements.txt

- name: Run tests
run: pytest -q

frontend:
name: Frontend — typecheck, lint, build
runs-on: ubuntu-latest
defaults:
run:
working-directory: frontend
steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: "22"
cache: npm
cache-dependency-path: frontend/package-lock.json

- name: Install dependencies
run: npm ci

- name: Typecheck
run: npx tsc --noEmit

- name: Lint
run: npm run lint

- name: Build
run: npm run build
19 changes: 16 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,13 @@
Upload your documents. DocuQuery reads them, indexes them, and answers questions with the
exact page and passage the answer came from — no more skimming a 40-page report for one number.

[**Live demo**](#-see-it-work) · [**Quick start**](#-quick-start) · [**Features**](#-features) · [**API reference**](#-api-reference) · [**Roadmap**](#-roadmap)
### [▶ Try it live at docuqueryvc.vercel.app](https://docuqueryvc.vercel.app)

![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square)
<sub>Frontend on Vercel · API at [`docuqueryprod.up.railway.app`](https://docuqueryprod.up.railway.app/health) on Railway · sign up with any email to upload your own documents</sub>

[**See it work**](#-see-it-work) · [**Quick start**](#-quick-start) · [**Features**](#-features) · [**API reference**](#-api-reference) · [**Roadmap**](#-roadmap)

[![CI](https://github.com/VampiricCyborg/DocuQuery/actions/workflows/ci.yml/badge.svg)](https://github.com/VampiricCyborg/DocuQuery/actions/workflows/ci.yml)
![Version](https://img.shields.io/badge/version-0.1.0-blue?style=flat-square)
![Next.js](https://img.shields.io/badge/Next.js-16.2-black?style=flat-square&logo=next.js)
![React](https://img.shields.io/badge/React-19.2-61dafb?style=flat-square&logo=react)
Expand Down Expand Up @@ -47,6 +51,10 @@ and hands the model only that — then shows you exactly where the answer came f
<img src="docs/screenshots/demo.gif" alt="A question is typed, DocuQuery searches the uploaded documents, streams back an answer, then shows the cited source" width="760">
<br/>
<sub>One question, start to finish — typed, searched, answered, cited. No cuts.</sub>

<br/>

<sub>Rather do it yourself? <a href="https://docuqueryvc.vercel.app">Open the live app</a> and upload a document.</sub>
</div>

<br/>
Expand Down Expand Up @@ -319,7 +327,12 @@ cd frontend && npx tsc --noEmit && npm run lint && npm run build
```

The backend suite covers parsing, chunking, retrieval scoring, citations, prompt construction,
provider abstraction, streaming, password hashing, and session validation.
provider abstraction, streaming, password hashing, and session validation. It needs no database
and no API keys — the database and the embedding service are mocked.

Every push to `main` and every pull request runs the same commands on GitHub Actions
([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) — that is what the CI badge at the top
reports.

---

Expand Down
106 changes: 49 additions & 57 deletions backend/DEPENDENCIES_VERIFIED.md
Original file line number Diff line number Diff line change
@@ -1,101 +1,93 @@
# Dependencies Verification

**Last Verified:** July 29, 2026
**Last Verified:** September 20, 2026

## ✅ All Third-Party Imports Covered
## Scope

This document confirms that all third-party Python packages imported across the codebase are included in `requirements.txt`.
This document records the mapping between third-party Python packages imported
across the backend and the entries in `requirements.txt`. It is a manual audit, so
it is only as current as the date above — re-run the commands at the bottom after
changing dependencies.

### Import → Package Mapping
## Imported directly by the code

| Import Statement | Package in requirements.txt | Version |
| Import statement | Package in requirements.txt | Version |
|---|---|---|
| `import fastapi` | `fastapi` | 0.115.5 |
| `import uvicorn` | `uvicorn[standard]` | 0.32.1 |
| `from fastapi import ...` | `python-multipart` | 0.0.18 |
| `import fastapi` / `from fastapi import ...` | `fastapi` | 0.115.5 |
| `from pydantic import ...` | `pydantic` | 2.10.3 |
| `from pydantic_settings import ...` | `pydantic-settings` | 2.6.1 |
| `from sqlalchemy import ...` | `sqlalchemy[asyncio]` | 2.0.36 |
| `from alembic import ...` | `alembic` | 1.14.0 |
| `import asyncpg` | `asyncpg` | 0.30.0 |
| `import psycopg2` | `psycopg2-binary` | 2.9.10 |
| `from pgvector.sqlalchemy import ...` | `pgvector` | 0.5.0 |
| `import aiofiles` | `aiofiles` | 24.1.0 |
| `import fitz` | `pymupdf` | 1.24.14 |
| `from docx import ...` | `python-docx` | 1.1.2 |
| `from langchain_text_splitters import ...` | `langchain-text-splitters` | 1.1.2 |
| `from sentence_transformers import ...` | `sentence-transformers` | 5.4.1 |
| `import onnxruntime` | `onnxruntime` | 1.30.0 |
| `from tokenizers import ...` | `tokenizers` | 0.23.2 |
| `import numpy` | `numpy` | 2.5.3 |
| `import psutil` | `psutil` | 6.1.1 |
| `from slowapi import ...` | `slowapi` | 0.1.9 |
| `import httpx` | `httpx` | 0.28.1 |
| `from groq import ...` | `groq` | 0.13.1 |
| `from openai import ...` | `openai` | 1.57.4 |
| `from anthropic import ...` | `anthropic` | 0.40.0 |
| `import google.generativeai` | `google-generativeai` | 0.8.3 |
| `import pytest` | `pytest` | 9.1.1 |
| `import pytest_asyncio` | `pytest-asyncio` | 1.4.0 |

### Standard Library (No Installation Required)
`from starlette... import ...` also appears in `app/core/middleware.py`. Starlette is a
direct dependency of FastAPI and is installed with it, so it has no line of its own.

The following imports are from Python's standard library and do not require entries in requirements.txt:
## Required but never imported

- `__future__`, `abc`, `asyncio`, `contextlib`, `dataclasses`, `datetime`, `enum`
- `functools`, `json`, `logging`, `os`, `pathlib`, `re`, `sys`, `tempfile`, `time`
- `typing`, `unittest`, `uuid`
These are real runtime requirements that no source file imports by name, which is why
they cannot be found by grepping for import statements:

### Starlette (Included with FastAPI)
| Package | Why it is needed |
|---|---|
| `uvicorn[standard]` | The ASGI server, invoked as a command by the Dockerfile and `railway.json` |
| `python-multipart` | FastAPI parses `multipart/form-data` uploads through it |
| `asyncpg` | The driver behind the `postgresql+asyncpg://` URL |
| `psycopg2-binary` | `migrations/env.py` swaps to `+psycopg2` to render Alembic's offline SQL |
| `greenlet` | SQLAlchemy's async bridge |
| `python-dotenv` | How `pydantic-settings` reads `.env` |
| `pytest-asyncio` | A pytest plugin, enabled via `asyncio_mode = auto` in `pytest.ini` |

- `from starlette.middleware.base import ...`
- `from starlette.requests import ...`
- `from starlette.responses import ...`
## Embeddings: ONNX Runtime, not sentence-transformers

Starlette is a direct dependency of FastAPI and is automatically installed.
Earlier revisions of this document listed `sentence-transformers` (and, transitively,
PyTorch) as the embedding dependency. **That is no longer true and should not be
reintroduced.** The PyTorch stack was deliberately removed because loading it
exhausted memory on Railway's container and crashed the service on boot.

### Greenlet (SQLAlchemy Dependency)
Embeddings now run through `onnxruntime` and `tokenizers` against a quantised
`BAAI/bge-small-en-v1.5` INT8 model (~35MB), downloaded into the image at build time
by `scripts/download_embedding_model.py`. See `app/ingestion/embeddings.py`.

- `greenlet==3.1.1` — Required by SQLAlchemy for async support
## Coverage summary

### Python-dotenv (Optional but Included)
- **Packages in `requirements.txt`:** 28
- **Imported directly:** 21 (plus Starlette, which ships with FastAPI)
- **Required without being imported:** 7
- **Unaccounted for:** 0

- `python-dotenv==1.0.1` — Used for `.env` file loading in development
## Verification commands

---
Confirm every directly imported package resolves:

## 📋 Coverage Summary

- **Total packages in requirements.txt:** 26
- **Third-party imports found in code:** 21
- **Coverage:** ✅ **100%**
- **Unused packages:** 0 (all are either direct imports or transitive dependencies)

---

## 🔍 Files Scanned

All Python files in:
- `app/` — Core application code
- `tests/` — Test suite
- `migrations/` — Alembic migrations

**Excluded:**
- `__pycache__/` directories
- `.pyc` compiled files
- `node_modules` (frontend)

---

## ✅ Verification Commands

### Check all imports are importable:
```bash
cd backend
pip install -r requirements.txt
python -c "import fastapi, sqlalchemy, pgvector, sentence_transformers, groq, openai, anthropic, google.generativeai"
python -c "import fastapi, sqlalchemy, pgvector, onnxruntime, tokenizers, numpy, psutil, groq, openai, anthropic, google.generativeai"
```

### Run tests to verify runtime dependencies:
Confirm runtime dependencies are satisfied end to end:

```bash
cd backend
pytest tests/ -v
pytest -q
```

All 71 tests passing confirms all runtime dependencies are satisfied.
The suite mocks the database and the embedding service, so it needs no PostgreSQL
instance and no downloaded model — which is what lets CI run it with no services
attached. A green run is the real check here; the count changes too often to record.
Loading
Loading