# vyngo98/financial_analysis_agent architecture

> Architecture diagram of the GitHub repository vyngo98/financial_analysis_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vyngo98/financial_analysis_agent
- Repository: https://github.com/vyngo98/financial_analysis_agent

## Overview

This is a local financial-report PDF analysis application. Users upload a report, which is routed through native-table or scanned-document extraction, chunked with page and financial metadata, and indexed; they then ask questions through the UI or CLI and receive sourced answers, with Python handling supported ratio/growth calculations. The graph also shows document/session persistence, hybrid/adaptive retrieval, and the documented evaluation capability. Some subsystem links are based on README descriptions or source-index references; unsampled implementation details are not inferred.

Main entry points: [`app/ingestion/pdf_ingestion.py`](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/pdf_ingestion.py) (PDF ingestion and chunking), [`app/agent/financial_agent.py`](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/agent/financial_agent.py) (Agent entry and tools), [`app/rag/retrieval.py`](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/rag/retrieval.py) (Hybrid retrieval), [`app/api.py`](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/api.py) (FastAPI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_web["Web UI<br/>[app.js]"]
  node_api["FastAPI<br/>[api.py]"]
  node_cli["CLI<br/>[main.py]"]
  node_registry[("JSON registry and sessions<br/>[storage.py]")]
end

subgraph group_ingest["PDF ingestion"]
  node_ingest["PDF ingestion and chunking<br/>[pdf_ingestion.py]"]
  node_camelot["Native table extraction<br/>[camelot_extract.py]"]
  node_tabula["Tabula extraction<br/>[tabula_extract.py]"]
  node_ocr["Scanned PDF OCR<br/>[ocr.py]"]
end

subgraph group_search["Retrieval and storage"]
  node_vector["Vector store access<br/>[vector_store.py]"]
  node_qdrant[("Qdrant")]
  node_ollama_embed["Ollama embeddings"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_adaptive["Adaptive retrieval<br/>[adaptive.py]"]
end

subgraph group_reason["Agent reasoning"]
  node_rag_tool["PDF search tool<br/>[rag_tool.py]"]
  node_agent["Agent entry and tools<br/>[financial_agent.py]"]
  node_graph["Reasoning graph<br/>[graph.py]"]
  node_repair["Tool-call repair"]
  node_calc["Deterministic calculator<br/>[calc_tool.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Evaluation runner<br/>[run_eval.py]"]
  node_failures["Failure analysis<br/>[dump_failures.py]"]
end

node_user(("User"))

node_user -->|"asks questions"| node_web
node_user -->|"uploads reports"| node_api
node_web -->|"uses API"| node_api
node_api -->|"persists sessions"| node_registry
node_api -->|"ingests uploads"| node_ingest
node_api -->|"invokes agent"| node_agent
node_user -->|"runs commands"| node_cli
node_cli -->|"ingests PDFs"| node_ingest
node_cli -->|"asks questions"| node_agent
node_ingest -->|"extracts native tables"| node_camelot
node_ingest -->|"routes scanned pages"| node_ocr
node_ingest -.->|"supports extraction"| node_tabula
node_ingest -->|"indexes chunks"| node_vector
node_vector -->|"creates embeddings"| node_ollama_embed
node_vector -->|"reads and writes"| node_qdrant
node_retrieval -->|"loads indexed chunks"| node_vector
node_retrieval -->|"dispatches adaptive mode"| node_adaptive
node_rag_tool -->|"retrieves context"| node_retrieval
node_rag_tool -->|"decomposes metrics"| node_adaptive
node_agent -->|"registers search tool"| node_rag_tool
node_agent -->|"registers calculator"| node_calc
node_agent -->|"installs middleware"| node_repair
node_agent -->|"selects graph mode"| node_graph
node_graph -->|"retrieves and rewrites"| node_retrieval
node_graph -->|"decomposes operands"| node_adaptive
node_graph -->|"resolves document"| node_ingest
node_eval -->|"indexes evaluation PDFs"| node_ingest
node_eval -->|"evaluates answers"| node_agent
node_eval -->|"scores retrieval"| node_retrieval
node_eval -->|"dumps failures"| node_failures
node_failures -->|"replays retrieval"| node_retrieval
node_failures -->|"reads gold chunks"| node_vector

click node_web "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/frontend/app.js"
click node_api "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/api.py"
click node_cli "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/main.py"
click node_registry "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/storage.py"
click node_ingest "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/pdf_ingestion.py"
click node_camelot "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/camelot_extract.py"
click node_tabula "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/tabula_extract.py"
click node_ocr "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/ocr.py"
click node_vector "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/rag/vector_store.py"
click node_retrieval "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/rag/retrieval.py"
click node_adaptive "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/rag/adaptive.py"
click node_rag_tool "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/tools/rag_tool.py"
click node_agent "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/agent/financial_agent.py"
click node_graph "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/agent/graph.py"
click node_repair "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/agent/tool_call_repair.py"
click node_calc "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/tools/calc_tool.py"
click node_eval "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/eval/run_eval.py"
click node_failures "https://github.com/vyngo98/financial_analysis_agent/blob/main/app/eval/dump_failures.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_api,node_cli,node_registry,node_user toneBlue
class node_ingest,node_camelot,node_tabula,node_ocr toneAmber
class node_vector,node_qdrant,node_ollama_embed,node_retrieval,node_adaptive toneMint
class node_rag_tool,node_agent,node_graph,node_repair,node_calc toneRose
class node_eval,node_failures toneIndigo
```

## Components

### User interface

- [Web UI](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/frontend/app.js): `app/frontend/app.js`
- [FastAPI](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/api.py): `app/api.py`
- [CLI](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/main.py): `app/main.py`
- [JSON registry and sessions](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/storage.py): `app/storage.py`

### PDF ingestion

- [PDF ingestion and chunking](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/pdf_ingestion.py): `app/ingestion/pdf_ingestion.py`
- [Native table extraction](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/camelot_extract.py): `app/ingestion/camelot_extract.py`
- [Tabula extraction](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/tabula_extract.py): `app/ingestion/tabula_extract.py`
- [Scanned PDF OCR](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/ingestion/ocr.py): `app/ingestion/ocr.py`

### Retrieval and storage

- [Vector store access](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/rag/vector_store.py): `app/rag/vector_store.py`
- **Qdrant**
- **Ollama embeddings**
- [Hybrid retrieval](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/rag/retrieval.py): `app/rag/retrieval.py`
- [Adaptive retrieval](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/rag/adaptive.py): `app/rag/adaptive.py`

### Agent reasoning

- [PDF search tool](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/tools/rag_tool.py): `app/tools/rag_tool.py`
- [Agent entry and tools](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/agent/financial_agent.py): `app/agent/financial_agent.py`
- [Reasoning graph](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/agent/graph.py): `app/agent/graph.py`
- [Tool-call repair](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/agent/tool_call_repair.py): `app/agent/tool_call_repair.py`
- [Deterministic calculator](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/tools/calc_tool.py): `app/tools/calc_tool.py`

### Evaluation

- [Evaluation runner](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/eval/run_eval.py): `app/eval/run_eval.py`
- [Failure analysis](https://github.com/vyngo98/financial_analysis_agent/blob/main/app/eval/dump_failures.py): `app/eval/dump_failures.py`

### Other components

- **User**

## Connections

- User → Web UI: asks questions (evidence: `README.md`)
- User → FastAPI: uploads reports (evidence: `README.md`)
- Web UI → FastAPI: uses API (evidence: `README.md`)
- FastAPI → JSON registry and sessions: persists sessions (evidence: `app/api.py`)
- FastAPI → PDF ingestion and chunking: ingests uploads (evidence: `app/api.py`)
- FastAPI → Agent entry and tools: invokes agent (evidence: `app/api.py`)
- User → CLI: runs commands (evidence: `README.md`)
- CLI → PDF ingestion and chunking: ingests PDFs (evidence: `app/main.py`)
- CLI → Agent entry and tools: asks questions (evidence: `app/main.py`)
- PDF ingestion and chunking → Native table extraction: extracts native tables (evidence: `app/ingestion/pdf_ingestion.py`)
- PDF ingestion and chunking → Scanned PDF OCR: routes scanned pages (evidence: `app/ingestion/pdf_ingestion.py`)
- PDF ingestion and chunking → Tabula extraction: supports extraction (evidence: `app/ingestion/tabula_extract.py`)
- PDF ingestion and chunking → Vector store access: indexes chunks (evidence: `app/ingestion/pdf_ingestion.py`)
- Vector store access → Ollama embeddings: creates embeddings (evidence: `app/rag/vector_store.py`)
- Vector store access → Qdrant: reads and writes (evidence: `app/rag/vector_store.py`)
- Hybrid retrieval → Vector store access: loads indexed chunks (evidence: `app/rag/retrieval.py`)
- Hybrid retrieval → Adaptive retrieval: dispatches adaptive mode (evidence: `app/rag/retrieval.py`)
- PDF search tool → Hybrid retrieval: retrieves context (evidence: `app/tools/rag_tool.py`)
- PDF search tool → Adaptive retrieval: decomposes metrics (evidence: `app/tools/rag_tool.py`)
- Agent entry and tools → PDF search tool: registers search tool (evidence: `app/agent/financial_agent.py`)
- Agent entry and tools → Deterministic calculator: registers calculator (evidence: `app/agent/financial_agent.py`)
- Agent entry and tools → Tool-call repair: installs middleware (evidence: `app/agent/financial_agent.py`)
- Agent entry and tools → Reasoning graph: selects graph mode (evidence: `app/agent/financial_agent.py`)
- Reasoning graph → Hybrid retrieval: retrieves and rewrites (evidence: `app/agent/graph.py`)
- Reasoning graph → Adaptive retrieval: decomposes operands (evidence: `app/agent/graph.py`)
- Reasoning graph → PDF ingestion and chunking: resolves document (evidence: `app/agent/graph.py`)
- Evaluation runner → PDF ingestion and chunking: indexes evaluation PDFs (evidence: `app/eval/run_eval.py`)
- Evaluation runner → Agent entry and tools: evaluates answers (evidence: `app/eval/run_eval.py`)
- Evaluation runner → Hybrid retrieval: scores retrieval (evidence: `app/eval/run_eval.py`)
- Evaluation runner → Failure analysis: dumps failures (evidence: `app/eval/run_eval.py`)
- Failure analysis → Hybrid retrieval: replays retrieval (evidence: `app/eval/dump_failures.py`)
- Failure analysis → Vector store access: reads gold chunks (evidence: `app/eval/dump_failures.py`)
