# shubham8kale/financial-research-agent architecture

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

- Interactive diagram: https://gitdiagram.com/shubham8kale/financial-research-agent
- Repository: https://github.com/shubham8kale/financial-research-agent

## Overview

Financial Research Agent ingests SEC 10-K filings into searchable text chunks and structured XBRL facts, then answers user questions through a tool-using research agent with citations and answer verification. The main path runs from the web chat or API through agent retrieval and fact tools to the stores, then returns a verified answer and sources. The README also documents MCP access and retrieval/answer evaluation. Some implementation details are unsampled, so edges are limited to excerpted source references and explicit README descriptions.

Main entry points: [`ingestion/pipeline.py`](https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/pipeline.py) (Ingestion Pipeline), [`retrieval/retriever.py`](https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/retriever.py) (Chunk Retrieval), [`api/main.py`](https://github.com/shubham8kale/financial-research-agent/blob/main/api/main.py) (FastAPI), [`agent/financial_agent.py`](https://github.com/shubham8kale/financial-research-agent/blob/main/agent/financial_agent.py) (ReAct Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Filing Ingestion"]
  node_ingest_pipeline["Ingestion Pipeline<br/>[pipeline.py]"]
  node_filing_download["Filing Download<br/>[downloader.py]"]
  node_filing_clean["Filing Cleaning<br/>[cleaner.py]"]
  node_filing_chunk["Text Chunking<br/>[chunker.py]"]
  node_xbrl_parse["XBRL Parsing<br/>[xbrl.py]"]
  node_embedding["Embedding Indexing<br/>[embedder.py]"]
end

subgraph group_knowledge["Knowledge Stores"]
  node_chroma[("Chroma Vector Store<br/>[embedder.py]")]
  node_facts_db[("XBRL Facts Store<br/>[facts.py]")]
  node_retriever["Chunk Retrieval<br/>[retriever.py]"]
  node_reranker["Optional Reranking<br/>[rerank.py]"]
  node_sparse["Sparse Search<br/>[sparse.py]"]
end

subgraph group_research["Research Agent"]
  node_agent["ReAct Agent<br/>[financial_agent.py]"]
  node_answer_verify["Answer Verification<br/>[contract.py]"]
  node_mcp_server["MCP Tool Server<br/>[server.py]"]
  node_mcp_agent["MCP Agent Adapter<br/>[mcp_agent.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_api["FastAPI<br/>[main.py]"]
  node_web_chat["Next.js Chat<br/>[page.tsx]"]
end

subgraph group_evaluation["Evaluation"]
  node_retrieval_eval["Retrieval Evaluation"]
  node_retrieval_metrics["Retrieval Metrics"]
  node_answer_eval["Answer Evaluation<br/>[run_eval.py]"]
end

node_user(("Researcher"))
node_sec["SEC EDGAR"]

node_sec -->|"provides filings"| node_ingest_pipeline
node_ingest_pipeline -->|"downloads"| node_filing_download
node_ingest_pipeline -->|"cleans"| node_filing_clean
node_ingest_pipeline -->|"chunks"| node_filing_chunk
node_ingest_pipeline -->|"indexes chunks"| node_embedding
node_ingest_pipeline -->|"builds facts"| node_xbrl_parse
node_embedding -->|"writes vectors"| node_chroma
node_xbrl_parse -->|"stores parsed facts"| node_facts_db
node_user -->|"asks question"| node_web_chat
node_web_chat -->|"streams query"| node_api
node_user -->|"queries REST API"| node_api
node_api -->|"tries MCP agent"| node_mcp_agent
node_api -->|"falls back to"| node_agent
node_mcp_agent -->|"calls over HTTP"| node_mcp_server
node_mcp_server -->|"serves search tools"| node_retriever
node_agent -->|"retrieves chunks"| node_retriever
node_agent -->|"looks up facts"| node_facts_db
node_retriever -->|"searches vectors"| node_chroma
node_retriever -.->|"uses for sparse modes"| node_sparse
node_retriever -.->|"optionally reranks"| node_reranker
node_api -->|"verifies draft"| node_answer_verify
node_retrieval_eval -->|"scores retrieval from"| node_retriever
node_retrieval_eval -->|"computes metrics"| node_retrieval_metrics
node_answer_eval -->|"evaluates answers from"| node_agent
node_answer_eval -->|"records verification"| node_answer_verify

click node_ingest_pipeline "https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/pipeline.py"
click node_filing_download "https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/downloader.py"
click node_filing_clean "https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/cleaner.py"
click node_filing_chunk "https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/chunker.py"
click node_xbrl_parse "https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/xbrl.py"
click node_embedding "https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/embedder.py"
click node_chroma "https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/embedder.py"
click node_facts_db "https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/facts.py"
click node_retriever "https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/retriever.py"
click node_reranker "https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/rerank.py"
click node_sparse "https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/sparse.py"
click node_agent "https://github.com/shubham8kale/financial-research-agent/blob/main/agent/financial_agent.py"
click node_answer_verify "https://github.com/shubham8kale/financial-research-agent/blob/main/agent/contract.py"
click node_mcp_server "https://github.com/shubham8kale/financial-research-agent/blob/main/mcp_server/server.py"
click node_mcp_agent "https://github.com/shubham8kale/financial-research-agent/blob/main/agent/mcp_agent.py"
click node_api "https://github.com/shubham8kale/financial-research-agent/blob/main/api/main.py"
click node_web_chat "https://github.com/shubham8kale/financial-research-agent/blob/main/web/app/page.tsx"
click node_retrieval_eval "https://github.com/shubham8kale/financial-research-agent/blob/main/eval/run_retrieval_eval.py"
click node_retrieval_metrics "https://github.com/shubham8kale/financial-research-agent/blob/main/eval/retrieval_metrics.py"
click node_answer_eval "https://github.com/shubham8kale/financial-research-agent/blob/main/eval/run_eval.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_ingest_pipeline,node_filing_download,node_filing_clean,node_filing_chunk,node_xbrl_parse,node_embedding toneBlue
class node_chroma,node_facts_db,node_retriever,node_reranker,node_sparse toneAmber
class node_agent,node_answer_verify,node_mcp_server,node_mcp_agent toneMint
class node_api,node_web_chat toneRose
class node_retrieval_eval,node_retrieval_metrics,node_answer_eval,node_user,node_sec toneIndigo
```

## Components

### Filing Ingestion

- [Ingestion Pipeline](https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/pipeline.py): `ingestion/pipeline.py`
- [Filing Download](https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/downloader.py): `ingestion/downloader.py`
- [Filing Cleaning](https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/cleaner.py): `ingestion/cleaner.py`
- [Text Chunking](https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/chunker.py): `ingestion/chunker.py`
- [XBRL Parsing](https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/xbrl.py): `ingestion/xbrl.py`
- [Embedding Indexing](https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/embedder.py): `ingestion/embedder.py`

### Knowledge Stores

- [Chroma Vector Store](https://github.com/shubham8kale/financial-research-agent/blob/main/ingestion/embedder.py): `ingestion/embedder.py`
- [XBRL Facts Store](https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/facts.py): `retrieval/facts.py`
- [Chunk Retrieval](https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/retriever.py): `retrieval/retriever.py`
- [Optional Reranking](https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/rerank.py): `retrieval/rerank.py`
- [Sparse Search](https://github.com/shubham8kale/financial-research-agent/blob/main/retrieval/sparse.py): `retrieval/sparse.py`

### Research Agent

- [ReAct Agent](https://github.com/shubham8kale/financial-research-agent/blob/main/agent/financial_agent.py): `agent/financial_agent.py`
- [Answer Verification](https://github.com/shubham8kale/financial-research-agent/blob/main/agent/contract.py): `agent/contract.py`
- [MCP Tool Server](https://github.com/shubham8kale/financial-research-agent/blob/main/mcp_server/server.py): `mcp_server/server.py`
- [MCP Agent Adapter](https://github.com/shubham8kale/financial-research-agent/blob/main/agent/mcp_agent.py): `agent/mcp_agent.py`

### User Interfaces

- [FastAPI](https://github.com/shubham8kale/financial-research-agent/blob/main/api/main.py): `api/main.py`
- [Next.js Chat](https://github.com/shubham8kale/financial-research-agent/blob/main/web/app/page.tsx): `web/app/page.tsx`

### Evaluation

- [Retrieval Evaluation](https://github.com/shubham8kale/financial-research-agent/blob/main/eval/run_retrieval_eval.py): `eval/run_retrieval_eval.py`
- [Retrieval Metrics](https://github.com/shubham8kale/financial-research-agent/blob/main/eval/retrieval_metrics.py): `eval/retrieval_metrics.py`
- [Answer Evaluation](https://github.com/shubham8kale/financial-research-agent/blob/main/eval/run_eval.py): `eval/run_eval.py`

### Other components

- **Researcher**
- **SEC EDGAR**

## Connections

- SEC EDGAR → Ingestion Pipeline: provides filings (evidence: `README.md`)
- Ingestion Pipeline → Filing Download: downloads (evidence: `ingestion/pipeline.py`)
- Ingestion Pipeline → Filing Cleaning: cleans (evidence: `ingestion/pipeline.py`)
- Ingestion Pipeline → Text Chunking: chunks (evidence: `ingestion/pipeline.py`)
- Ingestion Pipeline → Embedding Indexing: indexes chunks (evidence: `ingestion/pipeline.py`)
- Ingestion Pipeline → XBRL Parsing: builds facts (evidence: `ingestion/pipeline.py`)
- Embedding Indexing → Chroma Vector Store: writes vectors (evidence: `ingestion/embedder.py`)
- XBRL Parsing → XBRL Facts Store: stores parsed facts (evidence: `README.md`)
- Researcher → Next.js Chat: asks question (evidence: `README.md`)
- Next.js Chat → FastAPI: streams query (evidence: `README.md`)
- Researcher → FastAPI: queries REST API (evidence: `README.md`)
- FastAPI → MCP Agent Adapter: tries MCP agent (evidence: `api/main.py`)
- FastAPI → ReAct Agent: falls back to (evidence: `README.md`)
- MCP Agent Adapter → MCP Tool Server: calls over HTTP (evidence: `README.md`)
- MCP Tool Server → Chunk Retrieval: serves search tools (evidence: `mcp_server/server.py`)
- ReAct Agent → Chunk Retrieval: retrieves chunks (evidence: `agent/financial_agent.py`)
- ReAct Agent → XBRL Facts Store: looks up facts (evidence: `agent/financial_agent.py`)
- Chunk Retrieval → Chroma Vector Store: searches vectors (evidence: `retrieval/retriever.py`)
- Chunk Retrieval → Sparse Search: uses for sparse modes (evidence: `retrieval/retriever.py`)
- Chunk Retrieval → Optional Reranking: optionally reranks (evidence: `retrieval/retriever.py`)
- FastAPI → Answer Verification: verifies draft (evidence: `api/main.py`)
- Retrieval Evaluation → Chunk Retrieval: scores retrieval from (evidence: `eval/run_retrieval_eval.py`)
- Retrieval Evaluation → Retrieval Metrics: computes metrics (evidence: `eval/run_retrieval_eval.py`)
- Answer Evaluation → ReAct Agent: evaluates answers from (evidence: `eval/run_eval.py`)
- Answer Evaluation → Answer Verification: records verification (evidence: `eval/run_eval.py`)
