FALCON

Financial Analysis Copilot for Organizations — An AI assistant that reads dense financial disclosures and gives citation-backed answers for analytical questions using those specific documents as strict, verifiable evidence.

Stack

Layer	Technology
API Framework	FastAPI + Uvicorn
Config	pydantic-settings
Background Tasks	Taskiq + Redis
AI Orchestration	LangGraph (wired in Iteration 2)
Vector Store	ChromaDB (wired in Iteration 2)
Package Manager	uv

---

Prerequisites

Before you start, make sure you have the following installed:

Tool	Purpose	Notes
Python 3.12	Runtime	Required version, as pinned in backend/.python-version
uv	Package/venv manager	Replaces pip + venv. Install via curl -LsSf https://astral.sh/uv/install.sh | sh
Docker (optional)	Containerized setup	Only needed for the Docker path

---

Option A — Local Development (Recommended)

This path runs the API and worker natively on your machine, but still requires Redis and ChromaDB as backing services (easiest via Docker).

1. Start the backing services

# From the repo root — spins up only Redis and ChromaDB
docker compose up redis chromadb -d

This gives you:

• Redis → localhost:6379 (task broker)
• ChromaDB → localhost:8001 (vector store)

2. Set up the Python environment

cd backend

# One-shot: creates .venv + installs all dev dependencies
make setup-dev

3. Configure environment variables

cp backend/.env.example backend/.env

Then open backend/.env and fill in the values. For the current iteration, the minimum required keys are:

APP_NAME=FALCON
DEBUG=true
UPLOAD_DIR=uploads
REDIS_URL=redis://localhost:6379
CHROMA_HOST=localhost
CHROMA_PORT=8001

# Required for Iteration 2 (AI features) — leave blank for now if not needed
GEMINI_API_KEY=
VOYAGE_API_KEY=
LANGSMITH_API_KEY=

4. Run the API server

make run

This starts Uvicorn with hot-reload. The API will be available at:

• API base: http://localhost:8000
• Interactive docs (Swagger): http://localhost:8000/docs

5. Run the background worker (separate terminal)

make worker

This starts the Taskiq worker that processes async tasks (e.g., document ingestion). Requires Redis to be running.

---

Option B — Full Docker Compose (All-in-one)

Runs everything — API, worker, Redis, and ChromaDB — in containers.

1. Create an .env file at the repo root

# docker-compose.yml reads .env from the repo root (not backend/)
cp backend/.env.example .env

2. Build and start all services

# From the repo root
docker compose up --build

Services started:

Service	URL
backend (FastAPI)	http://localhost:8000
chromadb	http://localhost:8001
redis	localhost:6379

---

Development Commands

All commands are run from the backend/ directory:

make run      # Start API server with hot-reload
make worker   # Start Taskiq background worker
make test     # Run pytest
make lint     # Run ruff linter
make format   # Auto-format source files
make clean    # Remove Python/tool caches
make help     # List all available commands

---

Project Structure

backend/
├── app/
│   ├── api/         # FastAPI routers (documents, qa, brief)
│   ├── core/        # Config via pydantic-settings
│   ├── ingestion/   # Docling PDF parsing pipeline (Iteration 2)
│   ├── retrieval/   # ChromaDB vector queries (Iteration 2)
│   ├── workflows/   # LangGraph StateGraphs (Iteration 2)
│   ├── workers/     # Taskiq broker + background tasks
│   └── main.py      # FastAPI app factory + entrypoint
├── .env.example     # Environment variable template
├── Dockerfile.backend
├── Makefile
└── pyproject.toml

API Endpoints

Method	Path	Description
GET	/health	Service health check
POST	/api/v1/documents/upload	Upload a financial PDF
GET	/api/v1/documents	List active documents
GET	/api/v1/documents/{id}/status	Get ingestion status
DELETE	/api/v1/documents/{id}	Remove a document
POST	/api/v1/qa	Ask a financial question
POST	/api/v1/brief/generate	Trigger Intelligence Brief
GET	/api/v1/brief/{task_id}/status	Poll brief generation status