How shubham8kale/financial-research-agent works
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: pipeline.py Ingestion Pipeline · retriever.py Chunk Retrieval · main.py FastAPI · financial_agent.py ReAct Agent
Components 22
Filing Ingestion
- Ingestion Pipeline
ingestion/pipeline.py - Filing Download
ingestion/downloader.py - Filing Cleaning
ingestion/cleaner.py - Text Chunking
ingestion/chunker.py - XBRL Parsing
ingestion/xbrl.py - Embedding Indexing
ingestion/embedder.py
Knowledge Stores
- Chroma Vector Store
ingestion/embedder.py - XBRL Facts Store
retrieval/facts.py - Chunk Retrieval
retrieval/retriever.py - Optional Reranking
retrieval/rerank.py - Sparse Search
retrieval/sparse.py
Research Agent
- ReAct Agent
agent/financial_agent.py - Answer Verification
agent/contract.py - MCP Tool Server
mcp_server/server.py - MCP Agent Adapter
agent/mcp_agent.py
User Interfaces
- FastAPI
api/main.py - Next.js Chat
web/app/page.tsx
Evaluation
- Retrieval Evaluation
eval/run_retrieval_eval.py - Retrieval Metrics
eval/retrieval_metrics.py - Answer Evaluation
eval/run_eval.py
Other components
- Researcher
- SEC EDGAR
Connections 25
- SEC EDGAR → Ingestion Pipeline: provides filings
README.md - Ingestion Pipeline → Filing Download: downloads
ingestion/pipeline.py - Ingestion Pipeline → Filing Cleaning: cleans
ingestion/pipeline.py - Ingestion Pipeline → Text Chunking: chunks
ingestion/pipeline.py - Ingestion Pipeline → Embedding Indexing: indexes chunks
ingestion/pipeline.py - Ingestion Pipeline → XBRL Parsing: builds facts
ingestion/pipeline.py - Embedding Indexing → Chroma Vector Store: writes vectors
ingestion/embedder.py - XBRL Parsing → XBRL Facts Store: stores parsed facts
README.md - Researcher → Next.js Chat: asks question
README.md - Next.js Chat → FastAPI: streams query
README.md - Researcher → FastAPI: queries REST API
README.md - FastAPI → MCP Agent Adapter: tries MCP agent
api/main.py - FastAPI → ReAct Agent: falls back to
README.md - MCP Agent Adapter → MCP Tool Server: calls over HTTP
README.md - MCP Tool Server → Chunk Retrieval: serves search tools
mcp_server/server.py - ReAct Agent → Chunk Retrieval: retrieves chunks
agent/financial_agent.py - ReAct Agent → XBRL Facts Store: looks up facts
agent/financial_agent.py - Chunk Retrieval → Chroma Vector Store: searches vectors
retrieval/retriever.py - Chunk Retrieval → Sparse Search: uses for sparse modes
retrieval/retriever.py - Chunk Retrieval → Optional Reranking: optionally reranks
retrieval/retriever.py - FastAPI → Answer Verification: verifies draft
api/main.py - Retrieval Evaluation → Chunk Retrieval: scores retrieval from
eval/run_retrieval_eval.py - Retrieval Evaluation → Retrieval Metrics: computes metrics
eval/run_retrieval_eval.py - Answer Evaluation → ReAct Agent: evaluates answers from
eval/run_eval.py - Answer Evaluation → Answer Verification: records verification
eval/run_eval.py