---

FinanceHarness: Autonomous Financial Deep Research Framework

Overview

FinanceHarness is an autonomous financial deep research framework. Ask a question; FinanceHarness plans, gathers evidence, runs the analysis, and writes a cited report.

• Research and compute. Web search and reading, company and market data, and valuation and risk computed from the gathered data, not guessed.
• Reference-chaining. One tool’s output feeds the next by reference (prev:.), so a price series becomes a correlation with no retyping.
• Progressive disclosure. The core loop stays in the prompt; everything else waits in a catalog and loads on request, so breadth costs nothing until used.
• Extensible without code. A SKILL.md file composes existing tools into a reusable workflow. Drop one in and it is discovered.
• Grounded. Every figure traces back to the tool or source it came from.

Get Started

Prerequisites

FinanceHarness needs uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install

git clone https://github.com/Yijia-Xiao/FinanceHarness.git
cd FinanceHarness
uv tool install .  # installs the `financeharness` command (alias `fh`)

From a source checkout, uv sync sets up the environment and uv run python main.py ... (or uv run fh ...) runs the same CLI without installing.

Configure a backbone

Backbones are named by the provider or runtime that serves them. The default is gemini (a cloud backbone that requires only an API key). Configure whichever suits the machine you are on:

export GEMINI_API_KEY=...  # makes the Google/Gemini backbone available
export OPENAI_API_KEY=...  # makes the OpenAI/GPT backbone available

# Or point at an OpenAI-compatible vLLM stack you serve yourself:
export FH_QWEN_BASE_URL=http://gpu-box:8000/v1
export FH_QWEN_READER_BASE_URL=http://gpu-box:8001/v1   # the long-document reader

Pick a backbone per run with --profile NAME, or change the default in configs/providers.json (or via FH_PROFILE).

Run

One-shot research. The cited report goes to stdout, progress to stderr, so stdout stays pipeable:

fh -p "Estimate NVDA's intrinsic value with a DCF."
fh -p "Apple's competitive position in 2026?" --mode research
fh -p "..." --profile gpt --save run.json  # switch backbone; persist trajectory
echo "What's AAPL's P/E?" | fh -p          # question piped via stdin
fh --list                                  # backbones + skills; confirms the install

Options: --mode {auto|research|analytical}, --profile NAME, --reader NAME, --save PATH, --quiet. Exit code is 0 when the agent produced an answer, 1 otherwise.

Modes

Modes are prompt variants over a constant tool registry, so switching never strands a trajectory. Set with --mode.

A -p one-shot defaults to research.

Tools

Seven tools are always visible; the rest sit in a catalog and are loaded on demand with load_tool.

Company and market data are sourced through yfinance.

Extend with skills

A skill is a SKILL.md (YAML frontmatter + a markdown body) that orchestrates the existing tools into a reusable workflow, no code required. The model loads one with load_skill when it fits the task. Bundled:

Discovery runs in increasing precedence: bundled financeharness/skills/ → a project ./skills/ → FH_SKILLS_DIR. A project skill overrides a built-in by name, and a malformed one is skipped rather than fatal.

HTTP + SSE service (optional)

The package also ships an HTTP+SSE service for a remote client or programmatic use; it is entirely separate from the CLI:

fh serve  # HTTP+SSE on 127.0.0.1:8080

Benchmark

The FinanceGym benchmark and leaderboard are maintained at google-research/finance_harness.

Citation

If you find FinanceHarness helpful, please cite our work.

@misc{xiao2026financeharnessautonomousfinancialdeep,
      title={FinanceHarness: Autonomous Financial Deep Research Framework}, 
      author={Yijia Xiao and Rujun Han and Yanfei Chen and Zifeng Wang and Ke Jiang and Zhongying CuiZhu and Vishy Tirumalashetty and Wei Wang and Burak Gokturk and Tomas Pfister and Chen-Yu Lee},
      year={2026},
      eprint={2607.27853},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2607.27853}, 
}