# ahmedgh970/finqa-engine architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedgh970/finqa-engine
- Repository: https://github.com/ahmedgh970/finqa-engine

## Overview

FinQA Engine is a financial-document question-answering and benchmarking system. Its main workflow is offline filing ingestion and indexing, followed by online requests through the API into a configurable retrieval-and-answer graph; the response includes sources. The graph’s grading, neighboring-chunk expansion, and verified calculation support the documented advanced workflow, while a naive baseline and a separate tool-using agent provide alternatives. Evaluation covers retrieval metrics, LLM judging, and Ragas. Some connections are documented only at the product level because their implementation files were not excerpted.

Main entry points: [`src/workflow/nodes.py`](https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/nodes.py) (Workflow Nodes), [`src/indexing/runner.py`](https://github.com/ahmedgh970/finqa-engine/blob/main/src/indexing/runner.py) (Indexing Runner), [`src/api/main.py`](https://github.com/ahmedgh970/finqa-engine/blob/main/src/api/main.py) (FastAPI), [`src/workflow/graph.py`](https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/graph.py) (Workflow Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Ingestion and Indexing"]
  node_parsers["Parse and Chunk"]
  node_ingestion_runner["Ingestion Runner<br/>[runner.py]"]
  node_chunk_schema["Chunk Contract<br/>[schema.py]"]
  node_chunk_storage[("Chunk JSONL<br/>[storage.py]")]
  node_indexer["Indexing Runner<br/>[runner.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
end

subgraph group_serving["Serving"]
  node_ui["Demo UI<br/>[app.js]"]
  node_api["FastAPI<br/>[main.py]"]
end

subgraph group_workflow["Answer Workflow"]
  node_workflow_graph["Workflow Graph<br/>[graph.py]"]
  node_workflow_nodes["Workflow Nodes<br/>[nodes.py]"]
  node_workflow_state["Workflow State<br/>[state.py]"]
  node_expansion["Chunk Expansion<br/>[expansion.py]"]
  node_calculator["Verified Calculator<br/>[calculator.py]"]
  node_prompting["Grounded Prompts<br/>[prompts.py]"]
  node_llm_client["Ollama Client<br/>[client.py]"]
end

subgraph group_retrieval["Retrieval"]
  node_qdrant[("Qdrant<br/>[qdrant_store.py]")]
  node_retriever_registry["Retriever Registry<br/>[registry.py]"]
  node_retrieval_strategies["Search Strategies"]
end

subgraph group_evaluation["Agents and Evaluation"]
  node_agent_runner["Agent Runner<br/>[runner.py]"]
  node_agent_rag["Tool-Using RAG<br/>[agent_rag.py]"]
  node_agent_tools["Agent Tools<br/>[tools.py]"]
  node_evaluation_runs["Evaluation Runs<br/>[run_retrieval.py]"]
  node_retrieval_eval["Retrieval Metrics"]
  node_ragas_eval["Ragas Evaluation<br/>[run_ragas.py]"]
  node_ragas_config["Ragas Config<br/>[config.py]"]
  node_judge_eval["LLM Judge<br/>[run_judge.py]"]
  node_eval_schema["Evaluation Schema<br/>[schema.py]"]
end

node_filings(("SEC Filings"))
node_browser(("Web User"))
node_llm_service["Ollama"]

node_browser -->|"uses"| node_ui
node_ui -->|"calls demo API"| node_api
node_api -->|"runs graph"| node_workflow_graph
node_api -->|"streams results"| node_ui
node_filings -->|"provides documents"| node_parsers
node_parsers -->|"emits chunks"| node_chunk_schema
node_ingestion_runner -.->|"dispatches parsing"| node_parsers
node_ingestion_runner -.->|"persists chunks"| node_chunk_storage
node_chunk_storage -->|"serializes chunks"| node_chunk_schema
node_indexer -->|"reads chunks"| node_chunk_storage
node_indexer -->|"embeds text"| node_embeddings
node_indexer -->|"indexes vectors"| node_qdrant
node_retriever_registry -->|"builds strategy"| node_retrieval_strategies
node_retriever_registry -->|"builds dense client"| node_qdrant
node_retrieval_strategies -.->|"searches vectors"| node_qdrant
node_workflow_graph -->|"routes nodes"| node_workflow_nodes
node_workflow_graph -->|"tracks state"| node_workflow_state
node_workflow_nodes -.->|"retrieves passages"| node_retriever_registry
node_workflow_nodes -->|"expands passages"| node_expansion
node_workflow_nodes -->|"verifies calculations"| node_calculator
node_workflow_nodes -->|"builds answer prompt"| node_prompting
node_workflow_nodes -->|"grades and generates"| node_llm_client
node_prompting -->|"formats chunk context"| node_chunk_schema
node_llm_client -->|"requests completion"| node_llm_service
node_agent_runner -->|"runs agent"| node_agent_rag
node_agent_rag -->|"invokes tools"| node_agent_tools
node_agent_tools -->|"retrieves chunks"| node_retrieval_strategies
node_evaluation_runs -->|"evaluates retrieval"| node_retrieval_eval
node_ragas_eval -->|"loads settings"| node_ragas_config
node_ragas_eval -.->|"uses evaluation data"| node_eval_schema
node_judge_eval -.->|"judges answers"| node_eval_schema
node_evaluation_runs -.->|"uses benchmark schema"| node_eval_schema

click node_ui "https://github.com/ahmedgh970/finqa-engine/blob/main/src/api/static/app.js"
click node_api "https://github.com/ahmedgh970/finqa-engine/blob/main/src/api/main.py"
click node_parsers "https://github.com/ahmedgh970/finqa-engine/tree/main/src/ingestion/parsers"
click node_ingestion_runner "https://github.com/ahmedgh970/finqa-engine/blob/main/src/ingestion/runner.py"
click node_chunk_schema "https://github.com/ahmedgh970/finqa-engine/blob/main/src/ingestion/schema.py"
click node_chunk_storage "https://github.com/ahmedgh970/finqa-engine/blob/main/src/ingestion/storage.py"
click node_indexer "https://github.com/ahmedgh970/finqa-engine/blob/main/src/indexing/runner.py"
click node_embeddings "https://github.com/ahmedgh970/finqa-engine/blob/main/src/vectorstore/embeddings.py"
click node_qdrant "https://github.com/ahmedgh970/finqa-engine/blob/main/src/vectorstore/qdrant_store.py"
click node_retriever_registry "https://github.com/ahmedgh970/finqa-engine/blob/main/src/retrieval/registry.py"
click node_retrieval_strategies "https://github.com/ahmedgh970/finqa-engine/tree/main/src/retrieval"
click node_workflow_graph "https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/graph.py"
click node_workflow_nodes "https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/nodes.py"
click node_workflow_state "https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/state.py"
click node_expansion "https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/expansion.py"
click node_calculator "https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/calculator.py"
click node_prompting "https://github.com/ahmedgh970/finqa-engine/blob/main/src/llm/prompts.py"
click node_llm_client "https://github.com/ahmedgh970/finqa-engine/blob/main/src/llm/client.py"
click node_agent_runner "https://github.com/ahmedgh970/finqa-engine/blob/main/src/agents/runner.py"
click node_agent_rag "https://github.com/ahmedgh970/finqa-engine/blob/main/src/agents/agent_rag.py"
click node_agent_tools "https://github.com/ahmedgh970/finqa-engine/blob/main/src/agents/tools.py"
click node_evaluation_runs "https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/run_retrieval.py"
click node_retrieval_eval "https://github.com/ahmedgh970/finqa-engine/tree/main/src/evaluation/retrieval"
click node_ragas_eval "https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/run_ragas.py"
click node_ragas_config "https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/ragas/config.py"
click node_judge_eval "https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/run_judge.py"
click node_eval_schema "https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/common/schema.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_parsers,node_ingestion_runner,node_chunk_schema,node_chunk_storage,node_indexer,node_embeddings,node_browser toneBlue
class node_ui,node_api toneAmber
class node_workflow_graph,node_workflow_nodes,node_workflow_state,node_expansion,node_calculator,node_prompting,node_llm_client toneMint
class node_qdrant,node_retriever_registry,node_retrieval_strategies toneRose
class node_agent_runner,node_agent_rag,node_agent_tools,node_evaluation_runs,node_retrieval_eval,node_ragas_eval,node_ragas_config,node_judge_eval,node_eval_schema,node_filings,node_llm_service toneIndigo
```

## Components

### Ingestion and Indexing

- [Parse and Chunk](https://github.com/ahmedgh970/finqa-engine/tree/main/src/ingestion/parsers): `src/ingestion/parsers`
- [Ingestion Runner](https://github.com/ahmedgh970/finqa-engine/blob/main/src/ingestion/runner.py): `src/ingestion/runner.py`
- [Chunk Contract](https://github.com/ahmedgh970/finqa-engine/blob/main/src/ingestion/schema.py): `src/ingestion/schema.py`
- [Chunk JSONL](https://github.com/ahmedgh970/finqa-engine/blob/main/src/ingestion/storage.py): `src/ingestion/storage.py`
- [Indexing Runner](https://github.com/ahmedgh970/finqa-engine/blob/main/src/indexing/runner.py): `src/indexing/runner.py`
- [Embeddings](https://github.com/ahmedgh970/finqa-engine/blob/main/src/vectorstore/embeddings.py): `src/vectorstore/embeddings.py`

### Serving

- [Demo UI](https://github.com/ahmedgh970/finqa-engine/blob/main/src/api/static/app.js): `src/api/static/app.js`
- [FastAPI](https://github.com/ahmedgh970/finqa-engine/blob/main/src/api/main.py): `src/api/main.py`

### Answer Workflow

- [Workflow Graph](https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/graph.py): `src/workflow/graph.py`
- [Workflow Nodes](https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/nodes.py): `src/workflow/nodes.py`
- [Workflow State](https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/state.py): `src/workflow/state.py`
- [Chunk Expansion](https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/expansion.py): `src/workflow/expansion.py`
- [Verified Calculator](https://github.com/ahmedgh970/finqa-engine/blob/main/src/workflow/calculator.py): `src/workflow/calculator.py`
- [Grounded Prompts](https://github.com/ahmedgh970/finqa-engine/blob/main/src/llm/prompts.py): `src/llm/prompts.py`
- [Ollama Client](https://github.com/ahmedgh970/finqa-engine/blob/main/src/llm/client.py): `src/llm/client.py`

### Retrieval

- [Qdrant](https://github.com/ahmedgh970/finqa-engine/blob/main/src/vectorstore/qdrant_store.py): `src/vectorstore/qdrant_store.py`
- [Retriever Registry](https://github.com/ahmedgh970/finqa-engine/blob/main/src/retrieval/registry.py): `src/retrieval/registry.py`
- [Search Strategies](https://github.com/ahmedgh970/finqa-engine/tree/main/src/retrieval): `src/retrieval`

### Agents and Evaluation

- [Agent Runner](https://github.com/ahmedgh970/finqa-engine/blob/main/src/agents/runner.py): `src/agents/runner.py`
- [Tool-Using RAG](https://github.com/ahmedgh970/finqa-engine/blob/main/src/agents/agent_rag.py): `src/agents/agent_rag.py`
- [Agent Tools](https://github.com/ahmedgh970/finqa-engine/blob/main/src/agents/tools.py): `src/agents/tools.py`
- [Evaluation Runs](https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/run_retrieval.py): `src/evaluation/run_retrieval.py`
- [Retrieval Metrics](https://github.com/ahmedgh970/finqa-engine/tree/main/src/evaluation/retrieval): `src/evaluation/retrieval`
- [Ragas Evaluation](https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/run_ragas.py): `src/evaluation/run_ragas.py`
- [Ragas Config](https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/ragas/config.py): `src/evaluation/ragas/config.py`
- [LLM Judge](https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/run_judge.py): `src/evaluation/run_judge.py`
- [Evaluation Schema](https://github.com/ahmedgh970/finqa-engine/blob/main/src/evaluation/common/schema.py): `src/evaluation/common/schema.py`

### Other components

- **SEC Filings**
- **Web User**
- **Ollama**

## Connections

- Web User → Demo UI: uses
- Demo UI → FastAPI: calls demo API
- FastAPI → Workflow Graph: runs graph (evidence: `src/api/main.py`)
- FastAPI → Demo UI: streams results (evidence: `src/api/main.py`)
- SEC Filings → Parse and Chunk: provides documents
- Parse and Chunk → Chunk Contract: emits chunks (evidence: `src/ingestion/schema.py`)
- Ingestion Runner → Parse and Chunk: dispatches parsing
- Ingestion Runner → Chunk JSONL: persists chunks
- Chunk JSONL → Chunk Contract: serializes chunks (evidence: `src/ingestion/storage.py`)
- Indexing Runner → Chunk JSONL: reads chunks (evidence: `src/indexing/runner.py`)
- Indexing Runner → Embeddings: embeds text (evidence: `src/indexing/runner.py`)
- Indexing Runner → Qdrant: indexes vectors (evidence: `src/indexing/runner.py`)
- Retriever Registry → Search Strategies: builds strategy (evidence: `src/retrieval/registry.py`)
- Retriever Registry → Qdrant: builds dense client (evidence: `src/retrieval/registry.py`)
- Search Strategies → Qdrant: searches vectors (evidence: `src/retrieval/registry.py`)
- Workflow Graph → Workflow Nodes: routes nodes (evidence: `src/workflow/graph.py`)
- Workflow Graph → Workflow State: tracks state (evidence: `src/workflow/graph.py`)
- Workflow Nodes → Retriever Registry: retrieves passages
- Workflow Nodes → Chunk Expansion: expands passages (evidence: `src/workflow/nodes.py`)
- Workflow Nodes → Verified Calculator: verifies calculations (evidence: `src/workflow/nodes.py`)
- Workflow Nodes → Grounded Prompts: builds answer prompt (evidence: `src/workflow/nodes.py`)
- Workflow Nodes → Ollama Client: grades and generates (evidence: `src/workflow/nodes.py`)
- Grounded Prompts → Chunk Contract: formats chunk context (evidence: `src/llm/prompts.py`)
- Ollama Client → Ollama: requests completion (evidence: `src/llm/client.py`)
- Agent Runner → Tool-Using RAG: runs agent (evidence: `src/agents/runner.py`)
- Tool-Using RAG → Agent Tools: invokes tools (evidence: `src/agents/agent_rag.py`)
- Agent Tools → Search Strategies: retrieves chunks (evidence: `src/agents/tools.py`)
- Evaluation Runs → Retrieval Metrics: evaluates retrieval (evidence: `src/evaluation/run_retrieval.py`)
- Ragas Evaluation → Ragas Config: loads settings (evidence: `src/evaluation/run_ragas.py`)
- Ragas Evaluation → Evaluation Schema: uses evaluation data
- LLM Judge → Evaluation Schema: judges answers
- Evaluation Runs → Evaluation Schema: uses benchmark schema
