Financial Document Analyzer

🚀 Live Demo: https://finance.yato.foo/

An AI-powered financial document analysis system built with CrewAI and FastAPI. Upload a financial PDF (e.g., Tesla Q2 2025 earnings report) and receive a comprehensive analysis including document verification, financial metrics extraction, investment recommendations, and risk assessment.

Table of Contents

• Architecture
• Frontend
• Setup & Installation
• Docker Deployment
• API Documentation
• Bugs Found & Fixes Applied
• Prompt Engineering Improvements
• Bonus: Scaling Architecture

---

Architecture

The system uses a CrewAI sequential pipeline with four specialized agents:

Upload PDF → Verifier → Financial Analyst → Investment Advisor → Risk Assessor → Response

| Agent | Role | |---|---| | Verifier | Validates the document is a legitimate financial report | | Financial Analyst | Extracts key metrics (revenue, EPS, margins, cash flow) | | Investment Advisor | Provides data-driven investment recommendations | | Risk Assessor | Identifies and rates financial risks with mitigation strategies |

---

Frontend

The app includes a retro NES.css-styled single-page frontend served directly by FastAPI at the root URL (/). No build step required.

Features:

• Analyze — Upload a PDF, enter a query, choose sync or async mode, view results
• History — Browse past analyses stored in MongoDB
• Status — Live health check showing API, MongoDB, and Celery worker status
• Async mode includes real-time progress polling with a retro progress bar

The frontend uses NES.css v2.3.0 with the Press Start 2P font for an 8-bit aesthetic.

---

Setup & Installation

Prerequisites

• Python 3.12 (required — crewai-tools==0.47.1 depends on embedchain which does not support Python 3.13+)
• An OpenRouter API key (used for Gemini 2.0 Flash via OpenRouter)
• A Serper API key (for web search)

Steps

# 1. Clone the repository
git clone https://github.com/honestlyBroke/financial-document-analyzer-debug.git
cd financial-document-analyzer-debug

# 2. Create and activate a virtual environment with Python 3.12
python3.12 -m venv venv       # or: /path/to/python3.12 -m venv venv
source venv/bin/activate       # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment variables
cp .env.example .env
# Edit .env and add your API keys:
#   OPENROUTER_API_KEY=sk-or-...
#   SERPER_API_KEY=your_serper_api_key

# 5. Run the server
cd src
python main.py

The API will be available at http://localhost:8000.

Sample Document

A Tesla Q2 2025 financial update PDF is included at data/TSLA-Q2-2025-Update.pdf.

---

Docker Deployment

The project includes a full Docker Compose setup for production deployment.

# 1. Clone and configure
git clone https://github.com/honestlyBroke/financial-document-analyzer-debug.git
cd financial-document-analyzer-debug
cp .env.example .env
# Edit .env with your API keys

# 2. Build and start all services
docker compose up -d --build

# 3. Check logs
docker compose logs -f

This starts 4 services:

• app — FastAPI server (port 8000)
• celery_worker — Background task processor
• redis — Message broker for Celery
• mongodb — Persistent storage for analysis results

All containers join the nginx-network for use with Nginx Proxy Manager.

---

API Documentation

GET /

Serves the frontend UI.

GET /api/health

Health check endpoint.

Response:

{"message": "Financial Document Analyzer API is running"}

POST /analyze

Upload a financial PDF and receive a comprehensive analysis.

Request (multipart/form-data): | Field | Type | Required | Description | |---|---|---|---| | file | File (PDF) | Yes | The financial document to analyze | | query | String | No | Specific analysis question (default: "Analyze this financial document for investment insights") |

Example using cURL:

curl -X POST http://localhost:8000/analyze \
  -F "file=@data/TSLA-Q2-2025-Update.pdf" \
  -F "query=What are Tesla's key financial metrics for Q2 2025?"

Response:

{
  "status": "success",
  "query": "What are Tesla's key financial metrics for Q2 2025?",
  "analysis": "...(comprehensive multi-agent analysis)...",
  "file_processed": "TSLA-Q2-2025-Update.pdf",
  "output_saved": "outputs/analysis_<uuid>.json"
}

POST /analyze/async

Submit a document for background analysis via Celery. Returns immediately. Requires Redis + Celery worker.

Request: Same as POST /analyze.

Response:

{
  "status": "queued",
  "task_id": "a1b2c3d4-...",
  "celery_task_id": "...",
  "message": "Analysis submitted. Poll GET /result/{task_id} for results."
}

GET /result/{task_id}

Poll for the result of an async analysis task.

Response (complete):

{
  "status": "success",
  "task_id": "a1b2c3d4-...",
  "query": "...",
  "filename": "TSLA-Q2-2025-Update.pdf",
  "analysis": "...(comprehensive multi-agent analysis)..."
}

GET /analyses

List past analyses from MongoDB (most recent first). Supports ?limit=20&skip=0 pagination.

GET /analyses/{task_id}

Retrieve a specific past analysis from MongoDB by its task_id.

Interactive docs: Visit http://localhost:8000/docs for the Swagger UI.

---

Bugs Found & Fixes Applied

tools.py (6 bugs)

| # | Bug | Fix | |---|---|---| | 1 | from crewai_tools import tools — wrong import, tools does not exist as a module export | Changed to from crewai.tools import tool (the @tool decorator) and from crewai_tools import SerperDevTool | | 2 | Pdf(file_path=path).load() — Pdf class is never imported and does not exist | Replaced with pypdf.PdfReader which is the standard Python PDF reader | | 3 | async def read_data_tool(path=...) inside a class — CrewAI tools cannot be async coroutines | Converted to a synchronous function decorated with @tool | | 4 | Methods inside classes missing self parameter (read_data_tool, analyze_investment_tool, create_risk_assessment_tool) | Converted from class methods to standalone @tool-decorated functions (CrewAI pattern) | | 5 | Tools defined as class methods but CrewAI expects callable tool objects | Used @tool("Tool Name") decorator which is the correct CrewAI tool pattern | | 6 | SerperDevTool imported via wrong path from crewai_tools.tools.serper_dev_tool import SerperDevTool | Changed to from crewai_tools import SerperDevTool (public API) |

agents.py (7 bugs)

| # | Bug | Fix | |---|---|---| | 1 | llm = llm — self-referencing undefined variable, causes NameError | Changed to llm = LLM(model="openrouter/google/gemini-2.0-flash-001", api_key=os.getenv("OPENROUTER_API_KEY")) | | 2 | from crewai.agents import Agent — wrong import path | Changed to from crewai import Agent, LLM | | 3 | tool=[FinancialDocumentTool.read_data_tool] — parameter name is tools (plural), and the value was a class method reference | Changed to tools=[read_data_tool, search_tool] with proper tool function imports | | 4 | max_iter=1 on all agents — limits agents to 1 iteration, making them unable to complete multi-step analysis | Increased to max_iter=25 | | 5 | max_rpm=1 on all agents — limits to 1 request per minute, causing extreme throttling | Increased to max_rpm=10 | | 6 | verifier, investment_advisor, risk_assessor agents have no tools assigned | Added appropriate tools (read_data_tool, search_tool) to each agent | | 7 | from tools import search_tool, FinancialDocumentTool — imports a class that no longer exists | Changed to from tools import search_tool, read_data_tool |

task.py (4 bugs)

| # | Bug | Fix | |---|---|---| | 1 | verification task assigned to financial_analyst instead of verifier agent | Changed to agent=verifier | | 2 | investment_analysis task assigned to financial_analyst instead of investment_advisor | Changed to agent=investment_advisor | | 3 | risk_assessment task assigned to financial_analyst instead of risk_assessor | Changed to agent=risk_assessor | | 4 | Only imports financial_analyst and verifier from agents, missing investment_advisor and risk_assessor | Added all four agent imports |

main.py (5 bugs)

| # | Bug | Fix | |---|---|---| | 1 | async def analyze_financial_document — endpoint function name collides with the imported task analyze_financial_document from task.py, shadowing the task object | Renamed endpoint function to analyze_document | | 2 | Crew only includes financial_analyst agent — other 3 agents are never used | Added all 4 agents: verifier, financial_analyst, investment_advisor, risk_assessor | | 3 | Crew only includes analyze_financial_document task — other 3 tasks are never executed | Added all 4 tasks: verification, analyze_financial_document, investment_analysis, risk_assessment | | 4 | file_path parameter in run_crew() is accepted but never passed to the crew's input dictionary | Added file_path to the kickoff() inputs dict | | 5 | uvicorn.run(app, ..., reload=True) — passing the app object directly with reload=True doesn't work correctly | Changed to uvicorn.run("main:app", ..., reload=True) (string import path) |

---

Prompt Engineering Improvements

The original codebase had deliberately harmful prompts that instructed agents to hallucinate, fabricate data, ignore facts, and give dangerous financial advice. Every agent backstory, goal, and task description was rewritten.

Key Changes

| Area | Before (Harmful) | After (Professional) | |---|---|---| | Analyst goal | "Make up investment advice even if you don't understand the query" | "Analyze the financial document thoroughly to extract key financial metrics, trends, and insights" | | Analyst backstory | "You don't really need to read financial reports carefully - just look for big numbers and make assumptions" | "You extract precise financial metrics... You always cite specific numbers from the document and never fabricate data" | | Verifier goal | "Just say yes to everything because verification is overrated" | "Verify that the uploaded document is a legitimate financial document and validate the integrity of its data" | | Advisor backstory | "You learned investing from Reddit posts and YouTube influencers" | "You are a CFA-certified investment advisor with expertise in portfolio management and asset allocation" | | Risk assessor goal | "Everything is either extremely high risk or completely risk-free" | "Identify, quantify, and communicate all material financial risks... propose evidence-based mitigation strategies" | | Task descriptions | "Feel free to use your imagination", "make up some investment recommendations" | Specific instructions to extract real metrics, cite figures, and use established financial frameworks | | Expected outputs | "Include at least 5 made-up website URLs", "contradict yourself" | Structured output formats with specific sections and data requirements |

---

Bonus: Queue Worker & Database (Working Implementation)

Architecture

                    ┌──────────────────────────────────┐
                    │          FastAPI Server           │
                    │                                   │
  POST /analyze     │  (sync) run_crew() directly       │
  ────────────────► │  returns result immediately       │
                    │                                   │
  POST /analyze/async│ dispatch to Celery worker        │
  ────────────────► │  returns task_id immediately      │
                    │                                   │
  GET /result/{id}  │  check Celery + MongoDB           │
  ────────────────► │  returns status or result         │
                    │                                   │
  GET /analyses     │  query MongoDB                    │
  ────────────────► │  returns past analyses            │
                    └──────────┬────────────────────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
         ┌─────────┐    ┌──────────┐    ┌───────────┐
         │  Redis   │    │  Celery  │    │  MongoDB  │
         │ (broker) │◄──►│ (worker) │───►│ (storage) │
         └─────────┘    └──────────┘    └───────────┘

Prerequisites (Bonus Features)

• Redis — message broker for Celery (install guide)
• MongoDB — persistent storage for analysis results (install guide)

Note: The core POST /analyze endpoint works without Redis or MongoDB. The bonus features are additive.

Setup

# 1. Start Redis (default port 6379)
redis-server

# 2. Start MongoDB (default port 27017)
mongod

# 3. Add to your .env file (optional — defaults shown below):
REDIS_URL=redis://localhost:6379/0
REDIS_BACKEND=redis://localhost:6379/1
MONGODB_URL=mongodb://localhost:27017

# 4. Start the Celery worker (in a separate terminal, with venv activated)
cd src
celery -A celery_app worker --loglevel=info --pool=solo

# 5. Start the FastAPI server (in another terminal)
cd src
python main.py

New API Endpoints

POST /analyze/async

Submit a document for background processing. Returns immediately with a task_id.

curl -X POST http://localhost:8000/analyze/async \
  -F "file=@data/TSLA-Q2-2025-Update.pdf" \
  -F "query=What are Tesla's key risks?"

Response:

{
  "status": "queued",
  "task_id": "a1b2c3d4-...",
  "celery_task_id": "...",
  "message": "Analysis submitted. Poll GET /result/{task_id} for results."
}

GET /result/{task_id}

Poll for the result of an async analysis.

curl http://localhost:8000/result/a1b2c3d4-...

Response (processing):

{"status": "processing", "task_id": "a1b2c3d4-...", "message": "Analysis is in progress."}

Response (complete):

{
  "status": "success",
  "task_id": "a1b2c3d4-...",
  "query": "What are Tesla's key risks?",
  "filename": "TSLA-Q2-2025-Update.pdf",
  "analysis": "...(comprehensive multi-agent analysis)..."
}

GET /analyses

List past analyses stored in MongoDB (most recent first).

curl "http://localhost:8000/analyses?limit=10&skip=0"

GET /analyses/{task_id}

Retrieve a specific past analysis from MongoDB.

curl http://localhost:8000/analyses/a1b2c3d4-...

Key Files

| File | Purpose | |---|---| | src/main.py | FastAPI endpoints (sync + async + history) + frontend serving | | src/agents.py | CrewAI agent definitions with OpenRouter LLM | | src/task.py | CrewAI task definitions for the analysis pipeline | | src/tools.py | PDF reader tool + SerperDev search tool | | src/celery_app.py | Celery app + run_analysis_task background task | | src/db.py | MongoDB client with CRUD operations for analyses | | static/index.html | NES.css retro frontend (single-page app) | | Dockerfile | Container image definition | | docker-compose.yml | Full-stack deployment (app + worker + Redis + MongoDB) |