# vishwavardhan33-arch/financial-intelligence-agent architecture

> Architecture diagram of the GitHub repository vishwavardhan33-arch/financial-intelligence-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishwavardhan33-arch/financial-intelligence-agent
- Repository: https://github.com/vishwavardhan33-arch/financial-intelligence-agent

## Overview

The Financial Intelligence Agent accepts a financial question, plans an ordered set of RAG, SQL, and calculation steps, resolves dependent inputs, and synthesizes an answer with validated filing citations. Invoices are loaded into normalized PostgreSQL tables; filings are parsed, chunked, embedded, and indexed for hybrid retrieval. The API and agent graph form the query entry path, with SQL and calculation nodes providing structured-data and metric stages. README documents evaluation capabilities, but their wiring was not sampled, so they are omitted. Some internal links follow documented architecture because their source was not sampled.

Main entry points: [`sql_node/sql_node.py`](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/sql_node.py) (SQL node), [`agent/graph.py`](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/graph.py) (Agent graph), [`retrieval/index_filings.py`](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/index_filings.py) (Filing indexer), [`agent/dispatch.py`](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/dispatch.py) (Step dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Query interface"]
  node_api["Query API<br/>[main.py]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_graph["Agent graph<br/>[graph.py]"]
  node_planner["Plan builder<br/>[planner.py]"]
  node_plan["Plan schema<br/>[plan.py]"]
  node_resolver["Step resolver<br/>[resolve.py]"]
  node_dispatch["Step dispatcher<br/>[dispatch.py]"]
  node_synth["Answer synthesis<br/>[synthesizer.py]"]
end

subgraph group_analysis["Analysis nodes"]
  node_sqlnode["SQL node<br/>[sql_node.py]"]
  node_sqlprompt["SQL prompt<br/>[prompts.py]"]
  node_schema["SQL schema context<br/>[schema_context.py]"]
  node_validator["SQL validator<br/>[validator.py]"]
  node_executor["SQL executor<br/>[executor.py]"]
  node_calcnode["Calculation node<br/>[calc_node.py]"]
  node_metrics["Metric functions<br/>[metrics.py]"]
  node_deterministic["Metric dispatch<br/>[deterministic.py]"]
  node_safeeval["Safe evaluator<br/>[safe_eval.py]"]
end

subgraph group_knowledge["Financial data"]
  node_ingest["Invoice ingestion<br/>[load_invoices.py]"]
  node_db[("Invoice database<br/>[schema.sql]")]
  node_parse["Filing parser<br/>[parse_filing.py]"]
  node_chunker["Filing chunker<br/>[chunker.py]"]
  node_embed["Embeddings<br/>[embeddings.py]"]
  node_indexer["Filing indexer<br/>[index_filings.py]"]
  node_retrieval["Hybrid retrieval<br/>[vector_store.py]"]
  node_qdrant[("Qdrant index")]
end

subgraph group_provider["Model provider"]
  node_provider["Local LLM adapter<br/>[llm_provider.py]"]
end

node_user(("User"))
node_filinginput(("Filing PDFs"))
node_ollama["Ollama"]

node_user -->|"submits query"| node_api
node_api -->|"runs agent"| node_graph
node_graph -->|"requests plan"| node_planner
node_planner -->|"validates against"| node_plan
node_graph -->|"executes steps"| node_dispatch
node_graph -->|"resolves inputs"| node_resolver
node_dispatch -->|"runs SQL"| node_sqlnode
node_dispatch -->|"runs calculation"| node_calcnode
node_dispatch -->|"searches filings"| node_retrieval
node_graph -->|"synthesizes results"| node_synth
node_sqlnode -->|"builds prompt"| node_sqlprompt
node_sqlnode -->|"uses schema"| node_schema
node_sqlnode -->|"validates SQL"| node_validator
node_sqlnode -->|"executes validated SQL"| node_executor
node_executor -->|"reads rows"| node_db
node_calcnode -->|"dispatches metrics"| node_deterministic
node_deterministic -->|"calls functions"| node_metrics
node_calcnode -->|"evaluates expressions"| node_safeeval
node_ingest -->|"writes invoices"| node_db
node_filinginput -->|"provides filings"| node_indexer
node_indexer -->|"parses documents"| node_parse
node_indexer -->|"chunks text"| node_chunker
node_indexer -->|"embeds chunks"| node_embed
node_indexer -->|"builds index"| node_retrieval
node_retrieval -->|"embeds queries"| node_embed
node_retrieval -->|"searches and indexes"| node_qdrant
node_planner -->|"calls model"| node_provider
node_sqlnode -->|"generates SQL"| node_provider
node_synth -->|"generates answer"| node_provider
node_provider -->|"sends prompts"| node_ollama

click node_api "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/api/main.py"
click node_graph "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/graph.py"
click node_planner "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/planner.py"
click node_plan "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/plan.py"
click node_resolver "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/resolve.py"
click node_dispatch "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/dispatch.py"
click node_synth "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/synthesizer.py"
click node_sqlnode "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/sql_node.py"
click node_sqlprompt "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/prompts.py"
click node_schema "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/schema_context.py"
click node_validator "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/validator.py"
click node_executor "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/executor.py"
click node_calcnode "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/calc/calc_node.py"
click node_metrics "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/calc/metrics.py"
click node_deterministic "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/calc/deterministic.py"
click node_safeeval "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/calc/safe_eval.py"
click node_ingest "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/ingestion/load_invoices.py"
click node_db "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/db/schema.sql"
click node_parse "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/parse_filing.py"
click node_chunker "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/chunker.py"
click node_embed "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/embeddings.py"
click node_indexer "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/index_filings.py"
click node_retrieval "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/vector_store.py"
click node_provider "https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/api/llm_provider.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_api,node_user toneBlue
class node_graph,node_planner,node_plan,node_resolver,node_dispatch,node_synth toneAmber
class node_sqlnode,node_sqlprompt,node_schema,node_validator,node_executor,node_calcnode,node_metrics,node_deterministic,node_safeeval toneMint
class node_ingest,node_db,node_parse,node_chunker,node_embed,node_indexer,node_retrieval,node_qdrant toneRose
class node_provider,node_filinginput,node_ollama toneIndigo
```

## Components

### Query interface

- [Query API](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/api/main.py): `api/main.py`

### Agent orchestration

- [Agent graph](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/graph.py): `agent/graph.py`
- [Plan builder](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/planner.py): `agent/planner.py`
- [Plan schema](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/plan.py): `agent/plan.py`
- [Step resolver](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/resolve.py): `agent/resolve.py`
- [Step dispatcher](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/dispatch.py): `agent/dispatch.py`
- [Answer synthesis](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/agent/synthesizer.py): `agent/synthesizer.py`

### Analysis nodes

- [SQL node](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/sql_node.py): `sql_node/sql_node.py`
- [SQL prompt](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/prompts.py): `sql_node/prompts.py`
- [SQL schema context](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/schema_context.py): `sql_node/schema_context.py`
- [SQL validator](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/validator.py): `sql_node/validator.py`
- [SQL executor](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/sql_node/executor.py): `sql_node/executor.py`
- [Calculation node](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/calc/calc_node.py): `calc/calc_node.py`
- [Metric functions](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/calc/metrics.py): `calc/metrics.py`
- [Metric dispatch](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/calc/deterministic.py): `calc/deterministic.py`
- [Safe evaluator](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/calc/safe_eval.py): `calc/safe_eval.py`

### Financial data

- [Invoice ingestion](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/ingestion/load_invoices.py): `ingestion/load_invoices.py`
- [Invoice database](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/db/schema.sql): `db/schema.sql`
- [Filing parser](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/parse_filing.py): `retrieval/parse_filing.py`
- [Filing chunker](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/chunker.py): `retrieval/chunker.py`
- [Embeddings](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/embeddings.py): `retrieval/embeddings.py`
- [Filing indexer](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/index_filings.py): `retrieval/index_filings.py`
- [Hybrid retrieval](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/retrieval/vector_store.py): `retrieval/vector_store.py`
- **Qdrant index**

### Model provider

- [Local LLM adapter](https://github.com/vishwavardhan33-arch/financial-intelligence-agent/blob/main/api/llm_provider.py): `api/llm_provider.py`

### Other components

- **User**
- **Filing PDFs**
- **Ollama**

## Connections

- User → Query API: submits query
- Query API → Agent graph: runs agent
- Agent graph → Plan builder: requests plan
- Plan builder → Plan schema: validates against
- Agent graph → Step dispatcher: executes steps
- Agent graph → Step resolver: resolves inputs
- Step dispatcher → SQL node: runs SQL
- Step dispatcher → Calculation node: runs calculation
- Step dispatcher → Hybrid retrieval: searches filings
- Agent graph → Answer synthesis: synthesizes results
- SQL node → SQL prompt: builds prompt
- SQL node → SQL schema context: uses schema
- SQL node → SQL validator: validates SQL
- SQL node → SQL executor: executes validated SQL
- SQL executor → Invoice database: reads rows
- Calculation node → Metric dispatch: dispatches metrics
- Metric dispatch → Metric functions: calls functions
- Calculation node → Safe evaluator: evaluates expressions
- Invoice ingestion → Invoice database: writes invoices
- Filing PDFs → Filing indexer: provides filings
- Filing indexer → Filing parser: parses documents
- Filing indexer → Filing chunker: chunks text
- Filing indexer → Embeddings: embeds chunks
- Filing indexer → Hybrid retrieval: builds index
- Hybrid retrieval → Embeddings: embeds queries
- Hybrid retrieval → Qdrant index: searches and indexes
- Plan builder → Local LLM adapter: calls model
- SQL node → Local LLM adapter: generates SQL
- Answer synthesis → Local LLM adapter: generates answer
- Local LLM adapter → Ollama: sends prompts