Build a Full-Stack RAG Document Copilot with FastAPI, React, and Supabase

SEC Filings Data

We download 5 years of 10-K filings for Apple, Microsoft, Nvidia, Amazon, and Google using a Python script that queries the SEC EDGAR API:

1
TICKERS = ["AAPL", "MSFT", "NVDA", "AMZN", "GOOGL"]
2
FILINGS_PER_COMPANY = 5
3

4
COMPANY_CIKS = {
5
    "AAPL": "0000320193",
6
    "MSFT": "0000789019",
7
    "NVDA": "0001045810",
8
    "AMZN": "0001018724",
9
    "GOOGL": "0001652044",
10
}
11

12
# Downloads from SEC EDGAR API
13
submission = get_json(f"https://data.sec.gov/submissions/CIK{cik}.json")
14
# Fetches .htm files from SEC archives
15
source_url = (
16
    "https://www.sec.gov/Archives/edgar/data/"
17
    f"{int(cik)}/{accession_path}/{filing['primary_document']}"
18
)

The output is .htm files (SEC’s quasi-HTML format) organized by year, with a manifest.json mapping tickers to filing dates and local file paths.

Supabase Project

We create a free Supabase project with:

• PostgreSQL database with pgvector extension (for vector embeddings)
• Row-level security enabled
• Session pooler for database connections

FastAPI Config with Pydantic Settings

We use Pydantic Settings as the single source of truth for environment variables:

1
from pydantic_settings import BaseSettings
2

3
class Settings(BaseSettings):
4
    supabase_url: str
5
    supabase_anon_key: str
6
    supabase_service_key: str
7
    database_url: str
8
    openai_api_key: str
9
    allowed_origins: str = "http://localhost:5173"

Pydantic Settings validates on startup — if a required field is missing, you get a clear validation error instead of a cryptic runtime failure. No os.getenv calls scattered through the codebase.

Database Models

We define six tables using SQLAlchemy:

The document_chunks table includes a vector column for pgvector:

1
embedding = Column(Vector(1536))  # text-embedding-3-small dimension

Alembic Migrations

We use Alembic for database migrations — defining models in Python, then syncing to the database. Supabase-specific features (pgvector extension, HNSW indexes, GIN indexes, RLS policies) are written explicitly in migration operations.

Supabase Auth

We use Supabase’s built-in authentication with email/password. For an internal tool, we:

• Disable email confirmation (no verification needed)
• Disable public signups (prevent unauthorized access)
• Manually create users via Supabase dashboard

Frontend Scaffold

We use npm create vite@latest with the React + TypeScript template, then add:

• Supabase JS client (@supabase/supabase-js)
• Tailwind CSS for styling
• shadcn/ui (Radix UI preset) for components

Backend Auth Dependencies

FastAPI dependencies handle auth by verifying the Supabase JWT on each request:

1
async def get_current_user(request: Request) -> User:
2
    token = request.headers.get("Authorization")
3
    # Verify JWT with Supabase, return user or raise HTTPException

Backend API

We create REST endpoints for the chat system:

• POST /api/chat — Create a new chat thread
• POST /api/chat/{thread_id}/message — Send a message
• GET /api/chat/{thread_id}/messages — Retrieve thread history
• GET /api/chats — List user’s chat threads

Frontend Chat UI

We build a Vercel AI SDK-style chat interface with:

• Sidebar showing conversation history
• Chat input area
• Message display with streaming support

The chat component uses the AI SDK’s useChat hook:

1
const { messages, sendMessage, status, error } = useChat({
2
  id: threadId,
3
  messages: initialMessages,
4
  transport: new DefaultChatTransport({
5
    api: `${apiBaseUrl}/chat/stream`,
6
    headers: async () => ({
7
      Authorization: `Bearer ${await getAccessToken()}`,
8
    }),
9
  }),
10
});

Step 1: HTML to Markdown with Docling

We use Docling to convert .htm files to clean Markdown. Docling detects tables, formulas, and structure — far better than naive HTML-to-text conversion.

1
from docling.document_converter import DocumentConverter
2

3
converter = DocumentConverter()
4
result = converter.convert(html_path)
5
# Write structured markdown output

Step 2: Load Source Documents into Database

We ingest the markdown files into the source_documents table — 25 records (5 companies × 5 years):

1
# Loads markdown files, stores ticker, form type, filing date, source URL, full text

Step 3: Chunking with Hierarchical Chunker

Instead of naive token-based splitting, we use Docling’s hybrid hierarchical chunker — it respects document structure (headings, sections) while applying token-aware refinements:

1
from docling.chunking import HierarchicalChunker
2

3
chunker = HierarchicalChunker(
4
    token_counter=token_counter,
5
    max_tokens=300,
6
    overlap=50
7
)
8
# Chunks by document structure, not arbitrary token boundaries

Step 4: Embeddings

We create vector embeddings using OpenAI’s text-embedding-3-small (1536 dimensions) and store them in the document_chunks table alongside the text, page number, section, and search vector.

Reciprocal Rank Fusion

We implement hybrid search combining semantic search (pgvector) and keyword search (PostgreSQL full-text search), then fuse results with Reciprocal Rank Fusion (RRF):

1
# Semantic search via pgvector cosine similarity
2
semantic_results = await query_vector_search(query_embedding, top_k=60)
3
# Keyword search via PostgreSQL full-text search
4
keyword_results = await query_fulltext_search(keywords, top_k=60)
5
# Fuse with RRF
6
fused = reciprocal_rank_fusion([semantic_results, keyword_results], k=60)
7
# Return top 5
8
return fused[:5]

Keyword Extraction for Full-Text Search

A critical insight: you can’t just search the full user query against the database — the exact phrasing won’t match. We extract 3-5 meaningful keywords from the query first:

1
# Extract keywords via LLM call
2
async def extract_keywords(query: str) -> list[str]:
3
    # LLM extracts 3-5 search-relevant terms, removes filler words

Neighbor Chunks

Each retrieved chunk includes 1 neighboring chunk (before and after) for additional context — a simple but effective technique for grounding.

Pydantic AI Agent

Instead of a naive RAG pipeline (retrieve → stuff in context → answer), we build an agentic search system using Pydantic AI:

1
from pydantic_ai import Agent
2

3
agent = Agent(
4
    model=OpenAIModel("gpt-5.5"),
5
    instructions=SYSTEM_PROMPT,
6
    tools=[search_filings, read_chunk, read_surrounding_chunks]
7
)

Typed Dependencies and Outputs

The agent receives explicit dependencies rather than reaching into globals:

1
@dataclass
2
class DocumentAgentDeps:
3
    user_id: str
4
    thread_id: str
5
    retriever: DocumentRetriever
6
    grounding_validator: GroundingValidator
7

8
class GroundedAnswer(BaseModel):
9
    answer: str
10
    citations: list[Citation]
11
    cited_passages: list[SourcePassage]

The Tool Loop

The agent has tools it can call iteratively:

1. search_filings — Runs the hybrid retrieval pipeline
2. read_chunk — Reads a specific chunk by ID
3. read_surrounding_chunks — Reads neighboring chunks for context

The agent decides whether the initial retrieval is sufficient. If not, it can call read_chunk or read_surrounding_chunks to dig deeper — a tool loop that enables course-correction. This is fundamentally different from naive RAG where the LLM gets a one-shot dump of retrieved documents with no way to ask for more.

Grounded Answer Validation

After the agent produces an answer, a validator checks:

• Does the answer have enough evidence?
• Are all citations from actually retrieved chunks?
• Is each excerpt copied from the retrieved chunk?

If validation fails, the agent returns “not enough information” instead of hallucinating.

Chat Interface

We wire the backend API to the frontend using the Vercel AI SDK pattern. The chat UI shows:

• Streaming status updates — “Analyzing → Searching → Reading → Verifying”
• Markdown rendering — Tables, bold, lists
• Inline citations — Clickable [1], [2] links
• Source panel — Slide-out panel showing the retrieved chunks and neighboring context

Citation UX

Clicking an inline citation opens the source panel to the relevant chunk, with neighboring chunks for context. This is what makes the system trustworthy — analysts can immediately verify where an answer came from.

Docker Setup

Both frontend and backend require Docker configurations:

1
# backend/Dockerfile
2
FROM python:3.12-slim
3
WORKDIR /app
4
COPY pyproject.toml uv.lock ./
5
RUN pip install uv && uv sync --frozen
6
COPY . .
7
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

1
# frontend/Dockerfile
2
FROM node:20-slim
3
WORKDIR /app
4
COPY package.json pnpm-lock.yaml ./
5
RUN corepack enable && pnpm install --frozen-lockfile
6
COPY . .
7
RUN pnpm build
8
# Caddy serves the Vite build

Railway Deployment

We deploy both services via Railway:

• Backend — FastAPI on production.up.railway.app
• Frontend — Vite static build served via Caddy

Environment variables (Supabase credentials, OpenAI API key) are configured in Railway’s dashboard.