Financial Document Analyzer

A robust financial document analysis system built with CrewAI and FastAPI. This system utilizes a multi-agent crew to verify, analyze, and provide investment insights from corporate financial reports.

🚀 Features

• Automated Verification: Extracts and validates document metadata.
• Deep Financial Analysis: Identifies key metrics (Revenue, EBITDA, etc.) and analyzes trends.
• Risk Assessment: Evaluates market, credit, and operational risks.
• Investment Strategy: Provides data-driven Buy/Hold/Sell recommendations.
• Async Processing: Powered by Celery and Redis for long-running analyses.
• Persistent Storage: PostgreSQL database for users, requests, and results history.
• API-First: Easy integration via FastAPI with interactive docs.

🛠️ Bug Fixes & Improvements

The following "deterministic bugs" and "inefficient prompts" were resolved:

| Category | Issue Found | Fix Implemented | | :--- | :--- | :--- | | Logic | llm = llm self-reference in agents.py | Initialized Ollama config. | | Logic | Wrong param tool= in Agent() | Corrected to tools= keyword argument. | | Logic | read_data_tool was async | CrewAI tools must be synchronous; removed async and added @tool decorator. | | Logic | Hardcoded tool returns (Lazy Tools) | Refactored tools.py to actually process/verify data length instead of fixed strings. | | Logic | Async Anti-patterns in Worker | Refactored Celery task to use dedicated event loops for DB updates, avoiding loop conflicts. | | Crew | Single-agent bottleneck | Re-architected Crew to include all 4 specialized agents and their respective tasks. | | Prompts | "Lazy" task descriptions | Upgraded analyze_financial_document and others to high-fidelity, metrics-focused prompts. | | Validation | Missing timezone handling | Updated Analysis completion logic to use timezone-aware UTC. |

📦 Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd financial-document-analyzer

2. Create a Virtual Environment

python -m venv .venv

# Activate (Windows)
.venv\Scripts\activate

# Activate (macOS/Linux)
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Create a .env file from the template:

cp .env.example .env

5. LLM Setup

Ollama (local, free):

# Install Ollama from https://ollama.com
ollama pull llama3.2:1b  # Or llama3.2:3b/llama3.1

Redis (Broker):

# Start Redis using Docker
docker run -d --name redis -p 6379:6379 -p 8001:8001 redis:latest

6. Database Migrations

Ensure your PostgreSQL/Supabase instance is running and the DATABASE_URL is set in .env.

alembic upgrade head

7. Run the Application

Start the FastAPI Server:

python main.py

Start the Celery Worker (in a new terminal):

# Windows
celery -A celery_app worker --loglevel=info -P solo

# Linux/macOS
celery -A celery_app worker --loglevel=info

The server starts at http://localhost:8000. Interactive API docs are available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

📖 API Documentation

Health Check

• Endpoint: GET /
• Description: Returns 200 OK if the service is running.
• Response:

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

Analyze Document

• Endpoint: POST /analyze
• Content-Type: multipart/form-data
• Parameters:
  • file (required): PDF document (max 20 MB)
  • query (optional): Specific analysis question (max 1000 chars)

Example Request (curl)

curl -X POST http://localhost:8000/analyze \
  -F "[email protected]" \
  -F "query=What are the key revenue trends?"

Success Response 200 OK

{
  "status": "success",
  "query": "What are the key revenue trends?",
  "analysis": "## Executive Summary\n...",
  "file_processed": "report.pdf",
  "output_file": "outputs/analysis_<uuid>.txt"
}

Error Responses

| Status Code | Description | Example | | :--- | :--- | :--- | | 400 | Invalid file type (non-PDF) | { "detail": "Only PDF files are accepted. Received: text/plain" } | | 400 | File too large (>20 MB) | { "detail": "File size exceeds 20 MB limit" } | | 400 | Query too long (>1000 chars) | { "detail": "Query must be 1000 characters or fewer" } | | 422 | Missing required field | { "detail": [{ "msg": "field required", "type": "value_error.missing" }] } | | 500 | Internal processing error | { "detail": "Error processing financial document: ..." } |

📂 Project Structure

• main.py: FastAPI server and Crew orchestration.
• agents.py: Agent definitions (Analyst, Verifier, Advisor, Risk specialist).
• task.py: Structured tasks for each agent.
• tools.py: Custom PDF reader and search tools.
• data/: Temporary storage for uploaded documents.
• outputs/: Permanent storage for generated analysis reports.