# yijia-xiao/financeharness architecture

> Architecture diagram of the GitHub repository yijia-xiao/financeharness, 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/yijia-xiao/financeharness
- Repository: https://github.com/yijia-xiao/financeharness

## Overview

FinanceHarness turns a financial question into a planned, evidence-backed analysis and cited report. The CLI is the one-shot entry point; the optional HTTP/SSE service adds clarification, streaming, and resumable sessions. The runtime agent uses provider profiles and a tool registry to coordinate web research, financial data, and calculations, then attaches citations. The README also documents reference-chaining and skills for reusable workflows. Paths identify the relevant source modules or enclosing directories; some subsystem wiring is based on documented capabilities because those implementations were not sampled.

Main entry points: [`financeharness/runtime/dispatch.py`](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/dispatch.py) (Tool dispatch), [`financeharness/research.py`](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/research.py) (Research entry), [`financeharness/service/app.py`](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/service/app.py) (HTTP/SSE service), [`financeharness/runtime/agent.py`](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/agent.py) (Agent loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_service["HTTP/SSE service<br/>[app.py]"]
  node_sessions[("Session store<br/>[sessions.py]")]
end

subgraph group_runtime["Research runtime"]
  node_clarify["Question scoping<br/>[clarify.py]"]
  node_research_entry["Research entry<br/>[research.py]"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_registry["Tool registry<br/>[tool_registry.py]"]
  node_dispatch["Tool dispatch<br/>[dispatch.py]"]
  node_skills["Skill registry<br/>[skill_registry.py]"]
end

subgraph group_providers["Model providers"]
  node_provider["Provider client<br/>[client.py]"]
end

subgraph group_research["Evidence gathering"]
  node_search["Web search<br/>[search.py]"]
  node_search_backend["Search backend<br/>[search_backends.py]"]
  node_page_research["Page reading<br/>[visit.py]"]
  node_fetch_cache[("Fetch cache<br/>[cache.py]")]
  node_citations["Citation assembly<br/>[citations.py]"]
end

subgraph group_finance["Financial analysis"]
  node_equity_data["Equity and market data"]
  node_compute["Valuation and risk"]
  node_arithmetic["Exact arithmetic<br/>[arithmetic.py]"]
end

node_user(("Researcher"))
node_model{{"Model backbone"}}
node_market_data{{"Market data provider"}}
node_report["Cited report"]

node_user -->|"asks via CLI"| node_cli
node_user -->|"submits request"| node_service
node_cli -->|"runs research"| node_research_entry
node_service -.->|"scopes question"| node_clarify
node_service -->|"runs research"| node_research_entry
node_service -->|"reads or commits"| node_sessions
node_research_entry -->|"starts trajectory"| node_agent
node_research_entry -->|"assembles tools"| node_registry
node_research_entry -->|"loads skills"| node_skills
node_agent -->|"requests completion"| node_provider
node_provider -->|"sends prompt"| node_model
node_model -->|"returns completion"| node_provider
node_agent -->|"dispatches calls"| node_dispatch
node_dispatch -->|"resolves tools"| node_registry
node_dispatch -->|"invokes tool"| node_search
node_dispatch -->|"invokes tool"| node_page_research
node_dispatch -->|"invokes tools"| node_equity_data
node_dispatch -->|"invokes tools"| node_compute
node_dispatch -->|"invokes tool"| node_arithmetic
node_search -->|"searches queries"| node_search_backend
node_search -->|"records results"| node_fetch_cache
node_search_backend -->|"returns hits"| node_search
node_page_research -->|"reads and warms"| node_fetch_cache
node_page_research -->|"records sources"| node_citations
node_equity_data -->|"fetches market data"| node_market_data
node_research_entry -->|"finalizes citations"| node_citations
node_agent -->|"produces answer"| node_report
node_research_entry -->|"attaches citations"| node_report

click node_cli "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/cli.py"
click node_service "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/service/app.py"
click node_sessions "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/service/sessions.py"
click node_clarify "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/clarify.py"
click node_research_entry "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/research.py"
click node_agent "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/agent.py"
click node_registry "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/tool_registry.py"
click node_dispatch "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/dispatch.py"
click node_skills "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/skill_registry.py"
click node_provider "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/providers/client.py"
click node_search "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/search.py"
click node_search_backend "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/search_backends.py"
click node_page_research "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/visit.py"
click node_fetch_cache "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/cache.py"
click node_citations "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/citations.py"
click node_equity_data "https://github.com/yijia-xiao/financeharness/tree/main/financeharness/tools/data"
click node_compute "https://github.com/yijia-xiao/financeharness/tree/main/financeharness/tools/compute"
click node_arithmetic "https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/compute/arithmetic.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_cli,node_service,node_sessions toneBlue
class node_clarify,node_research_entry,node_agent,node_registry,node_dispatch,node_skills toneAmber
class node_provider toneMint
class node_search,node_search_backend,node_page_research,node_fetch_cache,node_citations toneRose
class node_equity_data,node_compute,node_arithmetic,node_user,node_model,node_market_data,node_report toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/cli.py): `financeharness/cli.py`
- [HTTP/SSE service](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/service/app.py): `financeharness/service/app.py`
- [Session store](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/service/sessions.py): `financeharness/service/sessions.py`

### Research runtime

- [Question scoping](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/clarify.py): `financeharness/clarify.py`
- [Research entry](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/research.py): `financeharness/research.py`
- [Agent loop](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/agent.py): `financeharness/runtime/agent.py`
- [Tool registry](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/tool_registry.py): `financeharness/runtime/tool_registry.py`
- [Tool dispatch](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/dispatch.py): `financeharness/runtime/dispatch.py`
- [Skill registry](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/runtime/skill_registry.py): `financeharness/runtime/skill_registry.py`

### Model providers

- [Provider client](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/providers/client.py): `financeharness/providers/client.py`

### Evidence gathering

- [Web search](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/search.py): `financeharness/tools/research/search.py`
- [Search backend](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/search_backends.py): `financeharness/tools/research/search_backends.py`
- [Page reading](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/visit.py): `financeharness/tools/research/visit.py`
- [Fetch cache](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/cache.py): `financeharness/tools/research/cache.py`
- [Citation assembly](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/research/citations.py): `financeharness/tools/research/citations.py`

### Financial analysis

- [Equity and market data](https://github.com/yijia-xiao/financeharness/tree/main/financeharness/tools/data): `financeharness/tools/data`
- [Valuation and risk](https://github.com/yijia-xiao/financeharness/tree/main/financeharness/tools/compute): `financeharness/tools/compute`
- [Exact arithmetic](https://github.com/yijia-xiao/financeharness/blob/main/financeharness/tools/compute/arithmetic.py): `financeharness/tools/compute/arithmetic.py`

### Other components

- **Researcher**
- **Model backbone**
- **Market data provider**
- **Cited report**

## Connections

- Researcher → CLI: asks via CLI
- Researcher → HTTP/SSE service: submits request
- CLI → Research entry: runs research
- HTTP/SSE service → Question scoping: scopes question
- HTTP/SSE service → Research entry: runs research
- HTTP/SSE service → Session store: reads or commits
- Research entry → Agent loop: starts trajectory
- Research entry → Tool registry: assembles tools
- Research entry → Skill registry: loads skills
- Agent loop → Provider client: requests completion
- Provider client → Model backbone: sends prompt
- Model backbone → Provider client: returns completion
- Agent loop → Tool dispatch: dispatches calls
- Tool dispatch → Tool registry: resolves tools
- Tool dispatch → Web search: invokes tool
- Tool dispatch → Page reading: invokes tool
- Tool dispatch → Equity and market data: invokes tools
- Tool dispatch → Valuation and risk: invokes tools
- Tool dispatch → Exact arithmetic: invokes tool
- Web search → Search backend: searches queries
- Web search → Fetch cache: records results
- Search backend → Web search: returns hits
- Page reading → Fetch cache: reads and warms
- Page reading → Citation assembly: records sources
- Equity and market data → Market data provider: fetches market data
- Research entry → Citation assembly: finalizes citations
- Agent loop → Cited report: produces answer
- Research entry → Cited report: attaches citations