An intelligent AI-powered document analysis platform enabling users to query large document repositories in natural language and receive sourced, citable answers with full citation traceability.
Document Copilot is a full-stack AI application designed for research professionals, analysts, and knowledge workers who spend significant time extracting insights from document repositories. The platform eliminates manual document intake workflows by enabling natural language queries across entire document corpora and providing intelligent, sourced answers with complete citation trails.
Research analysts at investment firms can query financial documents (10-Ks, 10-Qs, earnings reports) in plain English and receive citable answers, allowing them to skip tedious document review and jump directly to generating original research insights.
- Natural Language Querying — Ask questions in conversational English; receive intelligent answers from document corpus
- Citation & Traceability — Every response includes source document references and exact passage citations for verification
- Hybrid Retrieval System — Combines vector-based semantic search (pgvector) with PostgreSQL full-text search for comprehensive results
- Persistent Chat History — Maintain conversation threads with complete message history and citation metadata
- Enterprise Authentication — Email-based authentication powered by Supabase Auth with JWT tokens
- Streaming Chat Interface — Real-time streaming responses for responsive, interactive user experience
- Type-Safe LLM Orchestration — Backend uses PydanticAI for robust, typed interactions with language models
- Scalable Architecture — Clean separation of concerns with frontend SPA, Python backend, and managed database
Document Copilot implements a three-layer architecture with clear separation of concerns:
| Layer | Technology | Responsibility |
|---|---|---|
| Frontend | Vite + React + TypeScript | User interface, local state, authenticated requests to backend |
| Backend | Python 3.12+ + FastAPI | Authorization, document retrieval, LLM orchestration, persistence |
| Database | Supabase Postgres + pgvector | Users, authentication, chat threads, documents, embeddings, citations |
Frontend Responsibilities:
- User authentication state management
- Chat UI rendering and local message state
- HTTP requests to backend with bearer tokens
- Never holds service credentials or calls external APIs directly
Backend Responsibilities:
- JWT token verification and authorization
- Document retrieval and semantic search
- LLM prompt construction and execution
- Citation validation and response streaming
- Durable persistence of messages and metadata
Database Responsibilities:
- User authentication and session management
- User-scoped data access control
- Full-text search vector maintenance
- Embedding storage for semantic search
1. User signs in with email → Supabase Auth (JWT issued)
2. Frontend stores JWT from Supabase session
3. User opens chat thread → Frontend loads history from FastAPI
4. User submits message → Frontend sends to /chat/stream with JWT
5. Backend verifies JWT with Supabase Auth
6. FastAPI creates request context (user, thread, Supabase client, LLM settings)
7. PydanticAI agent retrieves relevant chunks via hybrid search
8. Agent generates grounded answer with citations
9. Backend streams response to browser in AI SDK format
10. Backend persists messages, citations, and usage metrics to Supabase
For detailed architecture documentation, see ARCHITECTURE.md.
| Component | Technology | Purpose |
|---|---|---|
| Framework | FastAPI + Uvicorn | Async HTTP server with automatic OpenAPI docs |
| Validation | Pydantic v2 + pydantic-settings | Request/response validation and config management |
| LLM Orchestration | PydanticAI + OpenAI SDK | Type-safe agent framework for model interactions |
| Database ORM | SQLAlchemy | SQL toolkit and ORM for data models |
| Migrations | Alembic | Database schema versioning and migrations |
| Vector Search | Supabase pgvector | Semantic similarity search on embeddings |
| Full-Text Search | PostgreSQL FTS | Lexical keyword search for hybrid retrieval |
| Logging | structlog | Structured JSON logging for production monitoring |
| HTTP Client | httpx | Async HTTP client for outbound requests |
| Component | Technology | Purpose |
|---|---|---|
| Framework | React 18+ | Component-based UI library |
| Language | TypeScript | Type-safe JavaScript development |
| Build Tool | Vite | Lightning-fast frontend development server |
| Routing | React Router | Client-side navigation and route management |
| UI Components | shadcn/ui + Tailwind CSS | Pre-built accessible components with utility CSS |
| Auth Client | @supabase/supabase-js | Browser-based Supabase authentication |
| Chat State | Vercel AI SDK | React hooks and streaming client for chat UX |
| Component | Technology | Purpose |
|---|---|---|
| Database | Supabase Postgres | Managed PostgreSQL with pgvector extension |
| Authentication | Supabase Auth | Email-based authentication with JWT |
| Embeddings | OpenAI API | Text embedding generation for semantic search |
| LLM Provider | OpenAI API | GPT models for answer generation |
| Hosting | Railway | Application deployment and management |
document-copilot/
│
├── 📄 ARCHITECTURE.md # Detailed system design & data flow diagrams
├── 📄 AGENTS.md # LLM agent instructions & prompt design
├── 📄 README.md # This file
│
├── 📂 data/ # Document corpus management
│ ├── download.py # Script to fetch and process documents
│ └── corpus/ # Local document storage (gitignored)
│
├── 📂 docs/ # Documentation
│ ├── client-brief.md # Client requirements & business context
│ └── API.md # Backend API documentation
│
├── 📂 backend/ # FastAPI application
│ ├── app/
│ │ ├── api/
│ │ │ ├── chat.py # Chat streaming & thread endpoints
│ │ │ └── documents.py # Document management endpoints
│ │ ├── auth/
│ │ │ └── dependencies.py # Supabase JWT verification
│ │ ├── retrieval/
│ │ │ ├── search.py # Hybrid semantic + FTS search
│ │ │ └── chunking.py # Document chunking strategy
│ │ ├── models/
│ │ │ ├── user.py # User ORM model
│ │ │ ├── chat.py # Chat thread & message models
│ │ │ └── document.py # Document & chunk models
│ │ ├── schema/
│ │ │ ├── chat.py # Pydantic request/response models
│ │ │ └── document.py # Document schemas
│ │ ├── agents/
│ │ │ └── answer_agent.py # PydanticAI agent for answer generation
│ │ ├── settings.py # Environment configuration
│ │ └── main.py # FastAPI app initialization
│ ├── migrations/ # Alembic database migrations
│ ├── requirements.txt # Python dependencies
│ ├── .env.example # Environment template
│ └── pyproject.toml # uv project configuration
│
└── 📂 frontend/ # React Vite SPA
├── src/
│ ├── lib/
│ │ ├── env.ts # Environment variable validation
│ │ ├── supabase.ts # Supabase client initialization
│ │ ├── http.ts # HTTP client with auth & error handling
│ │ └── api.ts # Product API calls (threads, messages)
│ ├── pages/
│ │ ├── auth/ # Authentication pages
│ │ └── chat/ # Chat interface pages
│ ├── components/
│ │ ├── chat/ # Chat components (messages, input, citations)
│ │ ├── common/ # Reusable components (buttons, modals)
│ │ └── layout/ # Layout components (header, sidebar)
│ ├── hooks/
│ │ └── useChat.ts # Custom chat hook wrapper
│ ├── types/ # TypeScript type definitions
│ ├── styles/ # Global styles and Tailwind config
│ └── App.tsx # Main app component
├── index.html # HTML entry point
├── vite.config.ts # Vite build configuration
├── tailwind.config.js # Tailwind CSS configuration
├── .env.example # Environment template
└── package.json # Node.js dependencies
Before starting, ensure you have the following installed:
| Tool | Version | Purpose | Installation |
|---|---|---|---|
| Python | 3.12+ | Backend runtime | python.org or OS package manager |
| uv | latest | Python package manager | curl -LsSf https://astral.sh/uv/install.sh | sh |
| Node.js | 18+ | Frontend tooling | nodejs.org or nvm |
| Git | latest | Version control | git-scm.com |
-
Clone and navigate to backend:
git clone <repository-url> cd document-copilot/backend
-
Install dependencies with uv:
uv sync
-
Configure environment variables:
cp .env.example .env
Edit
.envand add your credentials:# Supabase Configuration SUPABASE_URL=https://your-project.supabase.co SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs... SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIs... # OpenAI Configuration OPENAI_API_KEY=sk-... OPENAI_EMBED_MODEL=text-embedding-3-small # Server Configuration API_BASE_URL=http://localhost:8000 ENVIRONMENT=development LOG_LEVEL=INFO
-
Run database migrations:
uv run alembic upgrade head
-
Start backend server:
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
✅ Backend available at
http://localhost:8000📖 API docs athttp://localhost:8000/docs
-
Navigate to frontend directory:
cd document-copilot/frontend -
Install dependencies:
npm install # or pnpm install -
Configure environment variables:
cp .env.example .env.local
Edit
.env.local:VITE_API_BASE_URL=http://localhost:8000 VITE_SUPABASE_URL=https://your-project.supabase.co VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
-
Start development server:
npm run dev
✅ Frontend available at
http://localhost:5173
- Backend: Navigate to
http://localhost:8000/docsand verify OpenAPI endpoints are available - Frontend: Navigate to
http://localhost:5173and verify the login page loads - Connection: Sign in with a test email and verify the chat interface renders
-
Authentication
- User navigates to app and clicks "Sign In"
- Enters email address
- Receives verification link
- Clicks link and is authenticated
-
Chat Interface
- User creates new chat thread or opens existing conversation
- Types question about documents in natural language
- System retrieves relevant document chunks
- LLM generates sourced answer with citations
- User can click citations to view exact source passages
-
Citation Verification
- Each answer includes inline citations with source document
- Click citation to view highlighted passage in original document
- Track which documents supported which claims
Q: "What are the primary risk factors mentioned in recent filings?"
→ Returns answer from 10-K documents with citations
Q: "How has revenue changed year-over-year?"
→ Extracts financial metrics with source references
Q: "Summarize the management discussion for Q3"
→ Synthesizes MD&A sections with proper citations
- All user endpoints require Supabase JWT token in
Authorization: Bearer <token>header - Backend verifies token with Supabase before processing requests
- Service role key used only for privileged operations with explicit user binding
- Frontend uses
VITE_SUPABASE_ANON_KEYfor limited browser access - Backend uses service role key only for server-side writes
- All user-scoped queries filtered by authenticated user ID
- Environment variables never leaked to frontend except public keys
- Never commit
.envfiles; use.env.exampletemplates - Rotate API keys regularly in production
- Use HTTPS in production environments
- Implement rate limiting on backend endpoints
- Monitor logs for suspicious authentication attempts
- users — User accounts with email and profile data
- chat_threads — Conversation threads owned by users
- chat_messages — Individual messages with role (user/assistant) and content
- documents — Source documents with metadata and chunking info
- document_chunks — Individual text chunks with embeddings
- embeddings — Vector embeddings for semantic search (pgvector)
- citations — Links between messages and source chunks for traceability
See ARCHITECTURE.md for detailed schema design.
- Generation: GPT-4 / GPT-4 Turbo for answer generation (configurable)
- Embeddings: text-embedding-3-small for semantic search
- Context Window: Default 4K tokens (adjustable per request)
- PydanticAI agent retrieves relevant chunks based on user query
- Constructs prompt with chunk context and citation requirements
- Generates structured output: answer text + cited passages
- Validates citations exist in retrieved documents before responding
See AGENTS.md for detailed prompt engineering guidelines.
# Backend tests
cd backend
uv run pytest tests/ -v
# Frontend tests
cd frontend
npm run test- Backend: Follow PEP 8, use type hints, format with
black - Frontend: Use Prettier for formatting, ESLint for linting
- Database: Migrations tracked in Alembic with descriptive names
- Commits: Use conventional commit messages (feat:, fix:, docs:, etc.)
# Create new migration
uv run alembic revision --autogenerate -m "description"
# Review migration before applying
uv run alembic upgrade head- Retrieval: Hybrid search (vector + FTS) balances precision and recall
- Streaming: Chat responses streamed to browser for perceived speed
- Caching: Consider caching frequent document chunks and embeddings
- Pagination: Load chat history in pages, not all at once
- Backend logs all LLM calls, retrieval time, and token usage
- Track citation accuracy and user satisfaction metrics
- Monitor database query performance, especially on large corpora
- ARCHITECTURE.md — System design, data flow, request lifecycle
- AGENTS.md — LLM agent configuration and prompt design
- docs/client-brief.md — Business requirements and use cases
- docs/API.md — Backend endpoint documentation
We welcome contributions! Please follow these guidelines:
-
Fork the repository and create a feature branch
git checkout -b feature/your-feature-name
-
Make your changes following code standards above
-
Write tests for new functionality
-
Submit a pull request with clear description of changes
-
Code review — Address feedback from maintainers
- Additional LLM models and providers
- Enhanced retrieval algorithms
- Document processing improvements
- Frontend UI/UX enhancements
- Performance optimizations
- Documentation and examples
- Citation accuracy depends on chunking strategy and retrieval quality
- Large document corpora may require optimization of vector indices
- Streaming responses may timeout on very long answers
- Email-only authentication (future: add OAuth providers)
This project is licensed under the MIT License — see LICENSE file for details.
- ✅ Core chat interface
- ✅ Hybrid retrieval system
- ✅ Citation tracking
- ✅ Supabase auth
- 📋 Document upload UI
- 📋 Advanced search filters
- 📋 Conversation export
- 📋 Multi-user collaboration
- 📋 Custom LLM fine-tuning
- 📋 Knowledge graph construction
- 📋 Analytics dashboard
- 📋 Enterprise SSO
Q: Can I use different LLM providers?
A: Yes. Modify the backend LLM client in app/agents/answer_agent.py to use Claude, Anthropic, or other providers.
Q: How do I add new documents?
A: Use the document upload endpoint (frontend) or batch import via data/download.py script.
Q: What's the maximum document corpus size? A: No hard limit, but performance depends on embedding index optimization. Test with your scale.
Q: How are embeddings updated? A: Automatically when documents are chunked. See migration pipeline in backend.
For issues, feature requests, or questions:
- GitHub Issues: Report a bug
- Discussions: Ask a question
- Email: team@example.com
- Built with FastAPI, React, and Supabase
- LLM orchestration via PydanticAI
- UI components from shadcn/ui
Document Copilot — Turning documents into insights through AI. 🚀