🏦 Financial Document Analyser

An AI-powered financial document analysis system built with CrewAI, FastAPI, and OpenAI. Upload any financial PDF (10-K, 10-Q, Annual Report, Earnings Release) and get a structured, professional analysis powered by a crew of specialized AI agents.

---

📋 Table of Contents

• What This Does
• Bugs Found & Fixed
• Project Structure
• Setup Instructions
• How to Run
• API Documentation
• Bonus Features
• Architecture

---

What This Does

This system uses a crew of 4 specialized AI agents that work together to analyse financial documents:

| Agent | Role | |-------|------| | 🔍 Verifier | Confirms the uploaded file is a genuine financial document | | 📊 Financial Analyst | Extracts metrics, trends, and investment insights | | 💼 Investment Advisor | Provides compliant, balanced investment perspective | | ⚠️ Risk Assessor | Identifies and evaluates genuine risk factors |

---

🐛 Bugs Found & Fixed

Deterministic Bugs (Code That Crashes or Produces Wrong Output)

| # | File | Bug | Fix | |---|------|-----|-----| | 1 | agents.py | llm = llm — variable assigned to itself, causes NameError on startup | Initialized properly with ChatOpenAI(model="gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY")) | | 2 | agents.py | tool= (singular) — wrong parameter name, CrewAI silently ignores it | Changed to tools= (plural) as required by CrewAI's Agent class | | 3 | tools.py | Pdf class used but never imported — causes NameError at runtime | Replaced with from pypdf import PdfReader and updated read logic | | 4 | tools.py | All tool methods declared async — incompatible with CrewAI's synchronous tool invocation | Removed async keyword from all tool methods | | 5 | tools.py | Missing @tool decorator — CrewAI cannot register or call undecorated tools | Added @tool("Tool Name") decorator to all tool methods | | 6 | tools.py | requirements.txt content was pasted at the bottom of tools.py — causes SyntaxError | Removed from tools.py, placed in proper requirements.txt file | | 7 | main.py | analyze_financial_document imported from task.py AND used as the FastAPI route function name — causes TypeError name collision | Renamed FastAPI handler to analyze_document | | 8 | main.py | file_path parameter accepted by run_crew() but never passed into crew.kickoff() — agents never receive the file | Added file_path to the kickoff() inputs dict | | 9 | main.py | reload=True in uvicorn.run() causes issues when running as __main__ | Changed to reload=False | | 10 | requirements.txt | pydantic==1.10.13 — CrewAI 0.130.0 requires Pydantic v2; v1 causes import failures | Upgraded to pydantic==2.7.1 and pydantic_core==2.18.2 | | 11 | requirements.txt | pypdf missing entirely — required by tools.py to read PDFs | Added pypdf==4.2.0 | | 12 | requirements.txt | uvicorn, python-multipart, python-dotenv, langchain-openai all missing | Added all missing runtime dependencies | | 13 | requirements.txt | pip==24.0 pinned — you should never pin pip itself in requirements.txt | Removed |

---

Inefficient Prompts (AI Instructions That Produce Bad Output)

All 4 agents and all 4 tasks had intentionally harmful prompts that instructed the AI to:

• Make up financial data and statistics
• Fabricate URLs and cite non-existent research
• Ignore uploaded documents entirely
• Recommend unregulated, high-risk investments
• Skip compliance and regulatory guidelines
• Contradict itself within the same response

Each was completely rewritten following prompt engineering best practices:

What was changed in every agent:

• goal now specifies exactly what data to extract and how
• backstory establishes professional credentials and compliance mindset
• Agents are instructed to cite sources, never fabricate, and include disclaimers

What was changed in every task:

• description uses explicit "You MUST" and "You MUST NOT" sections
• expected_output defines a precise, structured format
• Tasks reference {file_path} so agents actually read the uploaded file

---

📁 Project Structure

financial-document-analyser/
├── main.py              # FastAPI app — all HTTP endpoints
├── agents.py            # 4 CrewAI agents with professional prompts
├── task.py              # 4 CrewAI tasks with structured instructions
├── tools.py             # PDF reader + analysis tools
├── database.py          # SQLite/PostgreSQL integration (Bonus)
├── worker.py            # Celery queue worker (Bonus)
├── async_routes.py      # Async endpoints for queue worker (Bonus)
├── requirements.txt     # All dependencies
├── .env.example         # Template for environment variables
├── .gitignore           # Excludes .env, __pycache__, temp files
└── README.md            # This file

---

⚙️ Setup Instructions

Prerequisites

• Python 3.10 or 3.11
• An OpenAI account with API access (needs a small credit balance ~$5)
• A Serper account for web search (free tier: 2,500 searches)

Step 1: Clone the Repository

git clone https://github.com/YOUR_USERNAME/financial-document-analyser.git
cd financial-document-analyser

Step 2: Create a Virtual Environment

# Create virtual environment
python -m venv venv

# Activate it (Windows)
venv\Scripts\activate

# Activate it (Mac/Linux)
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure API Keys

# Copy the example env file
cp .env.example .env

Now open .env in any text editor and fill in your keys:

OPENAI_API_KEY=sk-...your-key-here...
SERPER_API_KEY=...your-key-here...

Get your API keys:

• OpenAI → platform.openai.com
• Serper → serper.dev (free)

---

🚀 How to Run

Standard Mode (Single Requests)

python main.py

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

Visit http://localhost:8000/docs for the interactive Swagger UI where you can test all endpoints directly in your browser.

Queue Worker Mode (Concurrent Requests — Bonus)

Requires Redis installed and running.

# Terminal 1: Start Redis
redis-server

# Terminal 2: Start Celery worker
celery -A worker worker --loglevel=info

# Terminal 3: Start FastAPI
python main.py

---

📖 API Documentation

GET /

Health check. Confirms the server is running.

Response:

{
  "message": "Financial Document Analyzer API is running",
  "version": "1.0.0"
}

---

POST /analyze

Upload a financial document and receive a full AI analysis.

Request (multipart/form-data):

| Field | Type | Required | Description | |-------|------|----------|-------------| | file | PDF file | ✅ Yes | Financial document to analyze | | query | string | ❌ No | Specific question (defaults to general analysis) |

Example using curl:

curl -X POST "http://localhost:8000/analyze" \
  -F "file=@TSLA-Q2-2025.pdf" \
  -F "query=What are the key revenue trends and risks?"

Example using Python:

import requests

with open("TSLA-Q2-2025.pdf", "rb") as f:
    response = requests.post(
        "http://localhost:8000/analyze",
        files={"file": f},
        data={"query": "Summarize the financial health of this company"}
    )
print(response.json())

Success Response (200):

{
  "status": "success",
  "analysis_id": 1,
  "query": "What are the key revenue trends?",
  "analysis": "## Document Summary\n...(full analysis)...",
  "file_processed": "TSLA-Q2-2025.pdf"
}

Error Response (500):

{
  "detail": "Error processing financial document: ..."
}

---

GET /analyses

Retrieve all past analyses stored in the database.

Response:

{
  "status": "success",
  "count": 3,
  "analyses": [
    {
      "id": 1,
      "filename": "TSLA-Q2-2025.pdf",
      "query": "Analyze revenue trends",
      "result": "...",
      "created_at": "2025-07-15T10:30:00"
    }
  ]
}

---

GET /analyses/{id}

Retrieve a single analysis by its ID.

Example:

curl http://localhost:8000/analyses/1

---

POST /async/analyze (Bonus — requires Redis + Celery)

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

Response:

{
  "status": "queued",
  "task_id": "abc123-def456",
  "message": "Document queued for analysis. Poll /async/status/{task_id} for results."
}

---

GET /async/status/{task_id} (Bonus — requires Redis + Celery)

Check the status of a queued analysis.

States: pending → processing → completed / failed

Response (completed):

{
  "task_id": "abc123",
  "status": "completed",
  "result": {
    "status": "success",
    "analysis_id": 2,
    "analysis": "..."
  }
}

---

🎁 Bonus Features

✅ Database Integration (SQLite / PostgreSQL)

Every analysis is automatically saved to a database. By default this uses SQLite (no setup needed — the .db file is created automatically).

To use PostgreSQL instead, update your .env:

DATABASE_URL=postgresql://username:password@localhost:5432/financial_analyzer

What's stored:

• Filename of the uploaded document
• User's query
• Full AI analysis result
• Timestamp of the analysis

✅ Queue Worker Model (Redis + Celery)

For production use where multiple users submit documents simultaneously, the async endpoints use Celery + Redis to queue and process requests in parallel.

How it works:

1. User POSTs to /async/analyze → gets back task_id immediately
2. Request is placed in Redis queue
3. Celery worker picks it up and runs the CrewAI analysis
4. User polls /async/status/{task_id} to get the result when ready

This prevents the API from timing out on long analyses and allows true concurrent processing.

---

🏗️ Architecture

User Request
     │
     ▼
FastAPI (/analyze)
     │
     ├──── Save PDF to /data/
     │
     ▼
CrewAI Crew (Sequential Process)
     │
     ├── Agent 1: Verifier ──────────► Reads PDF ──► Confirms it's financial
     │
     └── Agent 2: Financial Analyst ──► Reads PDF ──► Extracts metrics & insights
     │
     ▼
Result returned to user
     │
     ▼
Database (SQLite/PostgreSQL) ──► Result saved for future retrieval

---

⚠️ Disclaimer

This tool is for educational and research purposes only. All AI-generated financial analysis should be verified by a qualified financial professional before making any investment decisions. This system does not provide personalized financial advice.