FinRobot Documentation

Technical Documentation: AI4Finance-Foundation/FinRobot

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

FinRobot: An Open-Source AI Agent Platform for Financial Applications using Large Language Models

FinRobot is an open-source agentic AI framework for financial decision intelligence. It combines foundation models with financial tools, quantitative models, deterministic computation, and multi-agent workflows to build decision-grade financial applications.

Its core principle is simple: models reason, software computes, agents orchestrate, and systems verify. Models can be replaced; the surrounding financial infrastructure — tools, workflows, validation, provenance, and evaluation — is what makes the system reliable.

Unlike the single-model paradigm of FinGPT, FinRobot supports end-to-end agentic workflows for equity research, quantitative trading, risk analysis, investment banking, private equity, wealth management, and other high-stakes financial decisions.

Whitepaper on arXiv · Official Academic Page

Where to start Copy Chapter

FinRobot is three projects sharing one financial domain layer. They are not three versions of the same thing competing for your attention — they serve different purposes.

pip install finrobot installs the V0 package. Its source moved into finrobot_autogen/, but the import name did not change — every existing from finrobot... import ... keeps working.

🧬 Architecture Evolution Copy Chapter

FinRobot evolves alongside the rapid development of AI-agent frameworks. Rather than being tied to a single agent stack, each generation explores how emerging agent architectures can improve financial analysis, research, and decision-making.

All three are open source. V2 is the production system — the deterministic compute engine, the provenance guarantees, and the agent orchestration described below all live there. V0 is kept because it is small enough to read and learn from, not because it is the recommended way to run research today.

Our philosophy: FinRobot is not defined by any single agent framework. We continuously adopt, evaluate, and evolve with state-of-the-art agent architectures while keeping the financial domain layer — tools, workflows, deterministic computation, and decision-making capabilities — at the core.

🧮 Deterministic compute, LLM narration Copy Chapter

A design principle that runs through every generation: deterministic financial computation and LLM-based narration stay strictly separate.

All financial numbers are produced by pure-Python compute operators, not by the language model. The LLM handles reasoning, synthesis, explanation, and report writing, while valuation outputs — DCF, DDM, LBO, WACC, comparable-company analysis, Monte Carlo simulation — are calculated through deterministic code paths with full provenance.

Numbers are code-calculated.
Narratives are LLM-assisted.
Every output is provenance-tracked.

🚀 FinRobot Desktop v0.1.0 Copy Chapter

A native desktop equity research cockpit powered by a production-grade multi-agent architecture. It takes analysts from market data and company filings to valuation, debate, synthesis, and investment-committee-style reports in one traceable workflow.

👉 Latest release: FinRobot Desktop v0.1.0

For macOS Apple Silicon (M1/M2/M3 or later), download FinRobot_0.1.0_aarch64.dmg and drag FinRobot into Applications. Intel Mac builds are not available in this release.

The app is not yet Apple-notarized, so on first launch macOS may report that it is "damaged." Run this once in Terminal, then open it normally:

xattr -cr /Applications/FinRobot.app

Multi-agent architecture Copy Section

A Lead Agent orchestrates specialized research agents through a pipeline-driven execution engine: five role-based sub-agents for data, analysis, modeling, synthesis, and reporting, plus three debate agents for the bull case, bear case, and judgment.

User Research Request
        ↓
Lead Agent / Orchestrator
        ↓
Data Agent → Analysis Agent → Modeling Agent → Synthesis Agent → Report Agent
        ↓
Bull Agent ↔ Bear Agent → Judge Agent
        ↓
Traceable Investment Research Output

Codebase snapshot Copy Section

Full details in finrobot_desktop/README.md.

Getting started Copy Chapter

V2 — the desktop app, a local web UI, or the CLI Copy Section

Three ways to run the same engine.

Desktop app — download the release (macOS Apple Silicon).

Local web UI — the same interface in a browser, no .dmg and no Rust toolchain, so it also works on Intel Macs, Linux, and Windows:

cd finrobot_desktop
uv sync                        # backend dependencies
(cd desktop && npm install)    # frontend dependencies — one time

./dev.sh                       # → open http://localhost:5173

dev.sh runs the FastAPI backend on :8321 and a Vite server on :5173 that proxies the API to it; Ctrl+C stops both. Note that it first frees those two ports, so quit FinRobot.app if it is open, and that the local API is unauthenticated in browser mode — details in finrobot_desktop/README.md.

CLI — after uv sync in finrobot_desktop/:

finrobot research AAPL          # full 13-chapter research artifact
finrobot dcf MSFT               # DCF valuation (auto-switches to DDM where appropriate)
finrobot comps NVDA --peers AMD,INTC
finrobot ic-memo TSLA
finrobot ask AAPL "How exposed is the gross margin to tariffs?"

Building the Tauri desktop shell is covered in finrobot_desktop/README.md.

V1 — the equity research web app Copy Section

cp finrobot_equity/core/config/config.ini.example finrobot_equity/core/config/config.ini
# edit config.ini: fmp_api_key, openai_api_key, (optional) adanos_api_key

chmod +x finrobot_equity/deploy.sh
./finrobot_equity/deploy.sh start          # → http://127.0.0.1:8001

If deploy.sh doesn't work in your environment:

python3 -m venv venv && source venv/bin/activate
pip install -r finrobot_equity/requirements.txt
python finrobot_equity/run_web_app.py

A two-step CLI pipeline is available as well — see finrobot_equity/README.md.

Example reports:
NVDA ·
MSFT ·
TSLA ·
META ·
COP

V0 — the AutoGen framework Copy Section

1. Create an environment (Python 3.10 or 3.11):

conda create --name finrobot python=3.10
conda activate finrobot

2. Install — from PyPI, or from source at the repository root (setup.py maps the finrobot package to finrobot_autogen/finrobot, so installing from inside that directory won't work):

git clone https://github.com/AI4Finance-Foundation/FinRobot.git
cd FinRobot
pip install -e .          # or: pip install -U finrobot

3. Configure keys — both files go in finrobot_autogen/, which is where the notebooks look for them. Copy rather than rename: the *_sample files are tracked, and your filled-in copies are gitignored.

cd finrobot_autogen
cp OAI_CONFIG_LIST_sample OAI_CONFIG_LIST     # OpenAI / Azure OpenAI endpoints
cp config_api_keys_sample config_api_keys     # Finnhub, FMP, SEC, Reddit, …

4. Run a tutorial from finrobot_autogen/tutorials_beginner/ or tutorials_advanced/:

agent_annual_report.ipynb        # 10-K → formatted PDF annual report
agent_fingpt_forecaster.ipynb    # market forecast from news + financials
agent_trade_strategist.ipynb     # strategy writing and backtesting
lmm_agent_mplfinance.ipynb       # multimodal agent reading a candlestick chart
lmm_agent_opt_smacross.ipynb     # multimodal SMA-crossover tuning

The agent library, workflow types, and full tutorial index are in finrobot_autogen/README.md.

Repository layout Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

🎬 FinRobot Pro — your personal AI-powered equity research assistant Copy Chapter

🌐 https://finrobot.ai/

https://github.com/user-attachments/assets/93ec0f1e-e28b-4474-a0bf-a79e0c12f0ff

FinRobot Pro is an AI-powered equity research platform that automates professional stock analysis using large language models and AI agents:

• Automated report generation — professional equity research reports on demand
• Financial analysis — income statements, balance sheets, and cash flows
• Valuation analysis — P/E, EV/EBITDA multiples, and peer comparison
• Risk assessment — comprehensive investment risk evaluation

Research foundation Copy Chapter

The FinRobot ecosystem Copy Section

The overall framework is organized into four layers, each addressing a specific aspect of financial AI processing:

1. Financial AI Agents Layer — includes Financial Chain-of-Thought (CoT) prompting to strengthen complex analysis and decision-making. Market Forecasting Agents, Document Analysis Agents, and Trading Strategies Agents use CoT to break financial problems into logical steps, aligning their algorithms and domain expertise with evolving market dynamics.
2. Financial LLMs Algorithms Layer — configures and applies models tuned to specific domains and global market analysis.
3. LLMOps and DataOps Layers — a multi-source integration strategy that selects the most suitable LLM for each financial task across a range of state-of-the-art models.
4. Multi-source LLM Foundation Models Layer — supports plug-and-play use of general and specialized LLMs.

Agent workflow Copy Section

1. Perception — captures and interprets multimodal financial data from market feeds, news, and economic indicators, structuring it for analysis.
2. Brain — the core processing unit: consumes perception output with LLMs and applies Financial CoT to generate structured instructions.
3. Action — executes those instructions with tools, turning analysis into outcomes: trades, portfolio adjustments, reports, or alerts.

Smart Scheduler Copy Section

The Smart Scheduler ensures model diversity and selects the most appropriate LLM for each task.

• Director Agent — orchestrates task assignment, allocating work based on performance metrics and task suitability.
• Agent Registration — manages registration and tracks agent availability for efficient allocation.
• Agent Adaptor — tailors agent functionality to specific tasks.
• Task Manager — stores and manages general and fine-tuned LLM-based agents for different financial tasks, updated periodically.

AI Agent papers Copy Chapter

• [Stanford University + Microsoft Research] Agent AI: Surveying the Horizons of Multimodal Interaction
• [Stanford University] Generative Agents: Interactive Simulacra of Human Behavior
• [Fudan NLP Group] The Rise and Potential of Large Language Model Based Agents: A Survey
• [Fudan NLP Group] LLM-Agent-Paper-List
• [Tsinghua University] Large Language Models Empowered Agent-based Modeling and Simulation: A Survey and Perspectives
• [Renmin University] A Survey on Large Language Model-based Autonomous Agents
• [Nanyang Technological University] FinAgent: A Multimodal Foundation Agent for Financial Trading: Tool-Augmented, Diversified, and Generalist

AI Agent open-source frameworks & tools Copy Chapter

• AutoGPT (183k stars): autonomous AI agent platform.
• Dify (134k stars): LLM app development platform with workflow orchestration and RAG.
• LangChain (130k stars): framework for building context-aware LLM applications.
• MetaGPT (65.6k stars): multi-agent framework with role-based collaboration.
• AutoGen (56k stars): framework for multi-agent LLM applications with tools and human interaction.
• CrewAI (46.6k stars): framework for orchestrating collaborative AI agents.
• ChatDev (31.7k stars): multi-agent framework for software development tasks.
• FastGPT (27.4k stars): knowledge-based LLM platform with workflow support.
• Langfuse (23.4k stars): open-source LLM observability and evaluation platform.
• BabyAGI (22.2k stars): task-driven experimental autonomous agent framework.
• SuperAGI (17.3k stars): developer-focused autonomous agent framework.
• CAMEL (16.4k stars): framework for cooperative and communicative AI agents.
• Bisheng (11.2k stars): enterprise open-source LLM application platform.

Citing FinRobot Copy Chapter

@article{yang2024finrobot,
  title   = {FinRobot: An Open-Source AI Agent Platform for Financial Applications using Large Language Models},
  author  = {Yang, Hongyang and Zhang, Boyu and Wang, Neng and Guo, Cheng and Zhang, Xiaoli and Lin, Likun and Wang, Junlin and Zhou, Tianyu and Guan, Mao and Zhang, Runjia and Wang, Christina Dan},
  journal = {arXiv preprint arXiv:2405.14767},
  year    = {2024},
  doi     = {10.48550/arXiv.2405.14767},
  url     = {https://arxiv.org/abs/2405.14767}
}

@inproceedings{zhou2024finrobot,
  title     = {FinRobot: {AI} Agent for Equity Research and Valuation with Large Language Models},
  author    = {Tianyu Zhou and Pinqiao Wang and Yilin Wu and Hongyang Yang},
  booktitle = {ICAIF 2024: The 1st Workshop on Large Language Models and Generative AI for Finance},
  year      = {2024}
}

@inproceedings{han2024enhancing,
  title     = {Enhancing Investment Analysis: Optimizing AI-Agent Collaboration in Financial Research},
  author    = {Han, Xuewen and Wang, Neng and Che, Shangkun and Yang, Hongyang and Zhang, Kunpeng and Xu, Sean Xin},
  booktitle = {ICAIF 2024: Proceedings of the 5th ACM International Conference on AI in Finance},
  pages     = {538--546},
  year      = {2024}
}

License Copy Chapter

Apache 2.0 — see LICENSE. Trademark usage is covered by TRADEMARK_POLICY.md.

Disclaimer: The code and documents provided here are released under the Apache-2.0 license. They should not be construed as financial advice or recommendations for live trading. Exercise caution and consult qualified financial professionals before any trading or investment decisions.

Overview (`finrobot_autogen/README.md`) Copy Section

FinRobot V0 — AutoGen Multi-Agent Framework

Educational. The original FinRobot: a library of role-based financial agents, data-source wrappers, and analysis tools built on Microsoft AutoGen.

This is the codebase behind the FinRobot whitepaper, kept in the repository for learning and reference — teaching, coursework, reproducing the paper, and understanding how financial agents are wired together. The agent definitions, the tool-registration pattern, and the data plumbing are all small enough to read end to end, which is exactly why it is worth keeping.

It is not the production system. There is no deterministic compute layer here, no provenance tracking, and no guarantee that a number in the output was computed rather than generated — the agents call tools and the LLM writes the result. For research you intend to act on, use finrobot_desktop/ (V2), where financial figures come from pure-Python operators and every one is traceable. For a self-hosted report-generating web service, use finrobot_equity/ (V1).

What's in here Copy Chapter

Agent roles Copy Section

agent_library.library is a dict keyed by role name. Each entry carries a profile (system message) and a toolkits list:

Software_Developer    Data_Analyst      Programmer       Accountant
Statistician          IT_Specialist     Financial_Analyst
Artificial_Intelligence_Engineer        Market_Analyst   Expert_Investor

Expert_Investor is the most fully equipped — it carries the SEC-report, charting, text-length and PDF-building toolkits used by the annual-report tutorial.

Workflows Copy Section

finrobot/agents/workflow.py wraps AutoGen's ConversableAgent plumbing so you don't hand-roll group chats:

Tool registration Copy Section

register_toolkits is the seam between plain Python and the agent layer. It takes a list of functions — or a class, via register_tookits_from_cls — and binds them to a caller/executor pair, so the LLM proposes the call and a separate proxy actually executes it:

from finrobot.toolkits import register_toolkits
from finrobot.data_source import FMPUtils

register_toolkits([FMPUtils.get_sec_report], assistant, user_proxy)

Data sources Copy Section

FinNLP/ is a git submodule. Fetch it with git submodule update --init --recursive if the directory is empty.

Install Copy Chapter

The package is published and imported as finrobot, but its source now lives under finrobot_autogen/. setup.py at the repository root maps the two, so install from the root — not from this directory:

conda create --name finrobot python=3.10   # 3.10 or 3.11
conda activate finrobot

cd /path/to/FinRobot      # repo root
pip install -e .

Or from PyPI:

pip install -U finrobot

Either way the import name is unchanged:

from finrobot.agents.workflow import SingleAssistant

Configure Copy Chapter

Both config files live in this directory (finrobot_autogen/) — that's where the tutorial notebooks look for them (../OAI_CONFIG_LIST relative to tutorials_*/).

1. LLM endpoints — copy the sample and fill in your key:

cp OAI_CONFIG_LIST_sample OAI_CONFIG_LIST

It is an AutoGen config list, so it holds several entries — OpenAI and Azure OpenAI deployments — and agents select one by model name.

2. Data API keys:

cp config_api_keys_sample config_api_keys

{
  "FINNHUB_API_KEY": "...",
  "FMP_API_KEY": "...",
  "SEC_API_KEY": "...",
  "REDDIT_CLIENT_ID": "...",
  "REDDIT_CLIENT_SECRET": "...",
  "TWITTER_BEARER_TOKEN": "..."
}

Load them into the environment with finrobot.utils.register_keys_from_json("config_api_keys"). Only fill in the keys for the data sources you actually use — the others can stay as placeholders.

Both OAI_CONFIG_LIST and config_api_keys are gitignored. The *_sample files are the ones under version control; never commit the filled-in copies.

Tutorials Copy Chapter

Run these from their own directory so the ../OAI_CONFIG_LIST paths resolve.

Beginner — `tutorials_beginner/` Copy Section

Advanced — `tutorials_advanced/` Copy Section

The two lmm_* notebooks need a vision-capable model configured in OAI_CONFIG_LIST.

Experiments Copy Chapter

experiments/ holds less polished multi-agent studies — treat them as research code, not a supported API:

• investment_group.py — a group of analyst agents debating a position
• multi_factor_agents.py — factor construction and evaluation
• portfolio_optimization.py — portfolio construction agent
• quantitative_investment_group_config.json — the group configuration those scripts read

agent_builder_demo.py at this level shows AutoGen's agent-builder generating a team from a task description, and test_module.py is a smoke test over the data-source wrappers.

report/ contains sample inputs and generated outputs (Microsoft's 2023 annual report and 10-K, an NVDA report) used by the tutorials.

Status Copy Chapter

V0 is stable and kept working, but it is maintained as teaching material, not as a product — active development happens in V1 and V2. Read this generation for the concepts, then build on:

• finrobot_desktop/ — production: desktop app and CLI, PydanticAI, deterministic compute engine
• finrobot_equity/ — web app: self-hosted equity research report generator

License Copy Chapter

Apache 2.0 — see LICENSE.

Overview (`finrobot_desktop/README.md`) Copy Section

FinRobot Desktop — V2

The production FinRobot. Investment-bank-grade equity research in a desktop app: deterministic finance numbers plus LLM narrative, with every figure traceable back to a function call.

FinRobot Desktop is an open-source equity research workstation for analysts, quantitative researchers, and active investors. A single research run produces a 13-chapter artifact — Cover, Investment Thesis, Company Overview, Financial Analysis, Valuation, Recent News, Sensitivity, Catalysts, Technical & Advanced, Competitive Landscape, Financial Data, Ownership & Governance, Disclaimer.

The core bet: numbers are computed by code, judgment is supplied by the LLM. The model never emits a figure that cannot be traced back to a call in finrobot/engine/compute/.

This is V2 in the FinRobot version lineage, and it is the generation meant for real work. What makes it the production system rather than a larger demo:

• 32 deterministic operators compute every financial figure in pure Python — the LLM narrates them, it does not produce them.
• 6 audit operators check the narrative back against the numbers and flag drift before a report ships.
• A typed pipeline runtime with per-step validators and retry, rather than an open-ended agent conversation.
• 7 data providers behind failover, with response validation that rejects malformed payloads before they reach the compute layer.
• 237 test files, property-based tests, and CI across Python 3.11/3.12 and Node 22/24.

The other two generations serve different purposes: finrobot_equity/ (V1) is a self-hosted web app for browser-based report generation, and finrobot_autogen/ (V0) is the educational AutoGen library behind the whitepaper.

How it works Copy Chapter

The app ships as a single .app containing two binaries that talk over local HTTP:

• finrobot-desktop — the Tauri shell: native window, menu bar, and the React UI.
• finrobot-server — a self-contained Python backend (FastAPI + PydanticAI + the deterministic compute engine), launched automatically in the background on 127.0.0.1:8321.

You never start anything by hand. Opening the app boots the backend; quitting it shuts the backend down. No Python, no uv, and no source tree are required on the user's machine.

Architecture Copy Chapter

Tauri shell (Rust) ── React 19 UI
                                 │  HTTP  127.0.0.1:8321
                       FastAPI routes ── PydanticAI agents
                                 │
          ┌──────────────────────┼──────────────────────┐
     pipelines              compute engine          data layer
  (7 workflows)      (32 pure-Python operators)   (7 providers,
                                                   with failover)
                                 │
                          artifact store (SQLite)

Agents Copy Section

Nine agents, each defined by a markdown instruction file in finrobot/engine/agents/instructions/:

Because instructions are plain markdown, changing an agent's behavior does not require touching Python.

Pipelines Copy Section

Seven workflows in finrobot/engine/pipelines/, each a sequence of typed steps with validators and retry:

finrobot dcf automatically falls back to DDM for companies where a dividend model is the more defensible approach; pass --force-dcf to override.

Deterministic compute Copy Section

finrobot/engine/compute/ is the part the LLM is not allowed to improvise around:

• 26 operators — dcf, ddm, lbo, multiples, monte_carlo, sotp, residual_income, peer_screen, forward_estimates, fx_normalize, ownership, catalyst, signal, and their seed variants.
• 6 audit operators — currency_caliber, ev_bridge, narrative_divergence, narrative_numeric_grounding, sector_sign, ttm_period. These check the narrative against the numbers and flag drift.
• 7 coordinators — assemble operator inputs from the data layer (extractor, historical_extractor, segment_extractor, market, news, dcf_seed, technical_payload).

Everything here is pure Python with no model in the loop, which is what makes the numbers reproducible and the provenance checkable.

Data layer Copy Section

Seven providers in finrobot/engine/data/providers/, behind a common interface with health tracking and automatic failover:

yfinance · edgar (SEC) · fmp · finnhub · adanos (retail sentiment) · news_aggregator · fx

Supporting pieces: response caching, a symbol index, quote batching, SEC holdings sync, and a validator that rejects malformed provider payloads before they reach the compute engine.

Skills Copy Section

skills/ holds 56 analyst playbooks as SKILL.md files, grouped by desk:

Browse them from the CLI with finrobot skill list and finrobot skill search <query>. Attribution for third-party material is in skills/ATTRIBUTION.md.

Install (macOS, Apple Silicon) Copy Chapter

1. Download FinRobot_<version>_aarch64.dmg from the Releases page (or build it yourself — see below).
2. Open the .dmg and drag FinRobot into Applications.
3. First open — the app is not yet code-signed, so Gatekeeper will block a plain double-click. Either right-click the app → Open → Open, or clear the quarantine flag once:
   bash Copy

   xattr -dr com.apple.quarantine /Applications/FinRobot.app

4. First run — open Settings and paste your own LLM API key (DeepSeek / OpenAI / Anthropic). FinRobot orchestrates your LLM account; it does not ship a key. Until a key is set, the app opens fine but analysis requests return a "configure your API key" notice instead of running.

Running an analysis needs internet access (market data from yfinance / SEC EDGAR / optional FMP, plus your LLM provider). Launching the app and browsing existing reports does not.

Intel Macs, Windows, and Linux are not covered by the current release; on those platforms, run from source.

Use from the command line Copy Chapter

Installing the Python package gives you a finrobot CLI independent of the desktop shell:

uv sync                          # or: pip install -e .
finrobot research AAPL           # full research artifact
finrobot dcf MSFT                # DCF (auto-switches to DDM where appropriate)
finrobot comps NVDA --peers AMD,INTC
finrobot ic-memo TSLA
finrobot ask AAPL "How exposed is the gross margin to tariffs?"
finrobot backtest ...            # needs the `backtest` extra
finrobot serve                   # run the backend on its own

Most commands accept --model to pick the LLM (e.g. anthropic:claude-sonnet-4-6) and --lang en|zh to set the output language.

Four notebooks in tutorials/ cover the same ground interactively: equity research, DCF valuation, backtesting, and RAG Q&A.

Run in a browser Copy Chapter

The same backend and the same UI can run as a local web service, with no .dmg and no Rust toolchain — useful on Intel Macs, Linux, and Windows, where there is no desktop build.

Prerequisites: uv and Node 20+. Python 3.11+.

cd finrobot_desktop
uv sync                        # backend dependencies
(cd desktop && npm install)    # frontend dependencies — one time

./dev.sh                       # → open http://localhost:5173

A bare uv sync installs the base dependencies and removes any extras already in the environment, so if you have been working with --extra dev or --extra package, sync with those flags instead of dropping them:

uv sync --extra dev            # keeps pytest / ruff / mypy installed

dev.sh starts two processes and wires them together:

Vite dev server  :5173   ← you open this in the browser
        │  proxies /api, /chat, /health, /openapi.json
        ▼
  finrobot serve   :8321   ← FastAPI backend, run from source

It waits for the backend's /openapi.json to answer before starting the frontend, and prints the backend log path (/tmp/finrobot-backend.log) if startup fails. Ctrl+C stops both. Backend edits need a restart of the script; frontend edits hot-reload.

Configure your LLM API key from the Settings page in the browser UI, exactly as in the desktop app — keys are stored in the OS keychain, not in a .env file.

Two things to know before you run it:

• dev.sh first kills whatever is listening on :8321 and :5173. If FinRobot.app is open, that includes its bundled backend. Quit the app first.
• In browser mode the local API is unauthenticated. The desktop shell mints a per-launch capability token and the backend enforces it; a plain browser has no Tauri IPC to read that token from, so the backend starts with the auth middleware as a no-op (see finrobot/auth.py). It still binds loopback only, but any other process on the machine can reach :8321 while it runs — including /api/settings, which holds your keys. Prefer the desktop app on a shared machine.

finrobot serve on its own exposes only the JSON API — it does not serve the UI, so the Vite server is what makes the browser version work. There is currently no static production build for browser use either: npm run build emits assets for the desktop bundle, and npm run preview has no proxy configured, so its /api calls would not reach the backend.

Build from source Copy Chapter

Prerequisites: uv, Node 20+, a Rust toolchain, and the Tauri CLI (cargo install tauri-cli → cargo tauri). Python 3.11+.

uv sync --extra package            # backend deps + pyinstaller (for the sidecar)
bash desktop/src-tauri/sidecar/build.sh
                                   # freeze finrobot-server into desktop/src-tauri/binaries/

cd desktop
cargo tauri dev                    # run the desktop app (debug)
cargo tauri build                  # produce FinRobot.app + .dmg under desktop/src-tauri/target/release/bundle/

build.sh freezes the backend into a PyInstaller sidecar, so a plain cd desktop && cargo tauri dev runs against that frozen binary — backend edits won't show up until you re-run build.sh. For a live edit loop (backend source + frontend HMR, no re-freezing) use dev.sh:

./dev.sh            # browser shell  → http://localhost:5173  (see "Run in a browser")
./dev.sh --app      # desktop shell  → Tauri native window, live backend

--app sets FINROBOT_DEV_LIVE_BACKEND=1 so the Tauri shell skips spawning the bundled sidecar; the WebView then talks through the Vite proxy to the source-tree backend dev.sh started. Or run just the backend with hot reload: finrobot serve --reload.

Development Copy Chapter

uv sync --extra dev
pytest tests/                                          # 237 test files; live-network tests are skipped by default
pytest tests/ --cov=finrobot --cov-report=term-missing
ruff check . && mypy finrobot                          # also wired into .pre-commit-config.yaml

Layout:

finrobot_desktop/
├── finrobot/              # Python backend
│   ├── engine/            #   agents, pipelines, compute, data, skills
│   ├── routes/            #   FastAPI endpoints (runs, artifacts, valuation, …)
│   ├── artifact/          #   report storage, contracts, semantic diff (SQLite)
│   ├── audit/ obs/        #   provenance checks and observability
│   ├── cli.py server.py   #   CLI and ASGI entry points
│   └── sdk.py             #   programmatic API
├── desktop/               # Tauri shell + React 19 / Vite 6 / Zustand / Recharts
├── skills/                # 56 analyst playbooks (SKILL.md)
├── tutorials/             # 4 notebooks
├── tests/                 # pytest suite, incl. Hypothesis property tests
└── scripts/               # maintenance and build tooling

CI (.github/workflows/desktop-ci.yml) runs the backend on Python 3.11 / 3.12 and the frontend on Node 22 / 24.

For deeper reference: finrobot/engine/instructions.md describes the engine's contracts, finrobot/engine/agents/instructions/*.md holds each agent's brief, and finrobot/sdk.py is the programmatic entry point.

License Copy Chapter

Apache 2.0 — see LICENSE.

Overview (`finrobot_equity/README.md`) Copy Section

FinRobot Equity — V1

A self-hosted web app. AI-powered equity research report generator: fetches financial data, runs LLM-based analysis, and produces professional multi-page HTML/PDF reports — from a browser or a single command.

This is V1 in the FinRobot version lineage. It is a web service you deploy, not a desktop application and not a framework — you run ./deploy.sh start, open a browser, and people on your network get a form that turns a ticker into a report. That narrow shape is the point: one job, done through a UI.

Where it sits relative to the others:

• finrobot_desktop/ (V2) is the production agent system — a deeper research pipeline, a deterministic compute engine, and full numeric provenance. Choose it when the analysis itself matters most.
• This project (V1) is the choice when browser access matters most: a shared internal tool, a demo, a hosted deployment behind your own auth.
• finrobot_autogen/ (V0) is educational — the AutoGen library behind the whitepaper.

Example output Copy Section

NVDA ·
MSFT ·
TSLA ·
META ·
COP

The same files are checked in under core/output/.

Quick start Copy Chapter

1. Configure API keys Copy Section

From the repository root:

cp finrobot_equity/core/config/config.ini.example finrobot_equity/core/config/config.ini

[API_KEYS]
fmp_api_key    = YOUR_FMP_API_KEY       # https://financialmodelingprep.com/developer
openai_api_key = YOUR_OPENAI_API_KEY    # https://platform.openai.com/account/api-keys
adanos_api_key = YOUR_ADANOS_API_KEY    # optional — enables Retail Sentiment Insights

config.ini is gitignored; config.ini.example is the file under version control.

With adanos_api_key set, the pipeline adds an optional Retail Sentiment Insights layer on top of the news workflow — structured snapshots of public retail activity across Reddit, X.com, and Polymarket.

2. Run the web app Copy Section

From this directory:

chmod +x deploy.sh
./deploy.sh start

Then open http://127.0.0.1:8001.

If deploy.sh doesn't work in your environment, start it by hand:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python run_web_app.py           # --host / --port / --no-reload are available

3. Or run the two-step CLI pipeline Copy Section

# Step 1 — fetch data, forecast, and generate the narrative sections
python finrobot_equity/core/src/generate_financial_analysis.py \
    --company-ticker NVDA \
    --company-name "NVIDIA Corporation" \
    --config-file finrobot_equity/core/config/config.ini \
    --peer-tickers AMD INTC \
    --generate-text-sections

# Step 2 — render the HTML report from step 1's outputs
python finrobot_equity/core/src/create_equity_report.py \
    --company-ticker NVDA \
    --company-name "NVIDIA Corporation" \
    --analysis-csv output/NVDA/analysis/financial_metrics_and_forecasts.csv \
    --ratios-csv   output/NVDA/analysis/ratios_raw_data.csv \
    --tagline-file             output/NVDA/analysis/tagline.txt \
    --company-overview-file    output/NVDA/analysis/company_overview.txt \
    --investment-overview-file output/NVDA/analysis/investment_overview.txt \
    --valuation-overview-file  output/NVDA/analysis/valuation_overview.txt \
    --risks-file               output/NVDA/analysis/risks.txt \
    --competitor-analysis-file output/NVDA/analysis/competitor_analysis.txt \
    --major-takeaways-file     output/NVDA/analysis/major_takeaways.txt \
    --peer-ev-ebitda-csv       output/NVDA/analysis/peer_ev_ebitda_comparison.csv \
    --enable-text-regeneration \
    --config-file finrobot_equity/core/config/config.ini

generate_pdf_report.py turns the HTML into a PDF as an optional third step. core/src/Run.ipynb walks the same pipeline in a notebook.

How it works Copy Chapter

┌─────────────────────────────────┐     ┌──────────────────────────────┐
│  generate_financial_analysis.py │     │  create_equity_report.py     │
│                                 │     │                              │
│  1. Fetch data from FMP API     │────>│  1. Load analysis outputs    │
│  2. Process financial metrics   │     │  2. Auto-fetch market data   │
│  3. Generate 3-year forecasts   │     │  3. Generate charts          │
│  4. Run peer comparison         │     │  4. Render HTML report       │
│  5. AI text generation          │     │  5. Validate & regenerate    │
│                                 │     │                              │
│  Output: CSV + JSON + TXT       │     │  Output: multi-page HTML     │
└─────────────────────────────────┘     └──────────────────────────────┘

Step 1 is deterministic up to the last stage: the statements, ratios, forecasts, and peer multiples are computed from FMP data before any model is called. Step 2 can optionally re-run the narrative agents (--enable-text-regeneration) when a section fails validation.

The agents Copy Section

Eight section writers in core/src/modules/equity_agents/, coordinated by agent_manager.py:

Each agent receives the already-computed numbers as context, so the narrative describes the model's output rather than inventing figures.

Layout Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Reference Copy Chapter

Deployment commands Copy Section

Run from this directory, or from the repo root as ./finrobot_equity/deploy.sh … — the script resolves its own paths either way.

deploy.gcloud.sh covers Google Cloud Run deployment. The Dockerfile and .dockerignore stay at the repo root: the container imports the app as finrobot_equity.web_app.main, so the build context has to be the root with finrobot_equity/ as a subdirectory under it.

Environment variables Copy Section

External services Copy Section

Tests Copy Section

pytest finrobot_equity/core/tests/

License Copy Chapter

Apache 2.0 — see LICENSE.

Overview (`finrobot_desktop/finrobot/engine/data/datasets/README.md`) Copy Section

Damodaran Industry Datasets

DCF input fallback when ticker-level data is missing — keyed on yfinance
industry strings, with industry_defaults.py doing the lookup.

Files Copy Chapter

industry_medians.csv is the runtime artifact — industry_defaults.py loads
it and never touches the raw xls files. Keep the xls files in-repo so the CSV
is reproducible.

Updating Copy Chapter

Damodaran refreshes datasets twice a year (Jan + Jul). To refresh:

cd finrobot/engine/data/datasets

# 1. Download the new xls files (rename TAG to the new date)
for n in capex margin taxrate betas; do
  curl -sLo damodaran_${n}_YYYY-MM.xls \
    https://pages.stern.nyu.edu/~adamodar/pc/datasets/${n}.xls
done

# 2. Update TAG constant in build_industry_medians.py

# 3. Regenerate the CSV
uv run python build_industry_medians.py

# 4. Verify against last release
git diff industry_medians.csv | head

# 5. Re-run the test suite — schema regressions surface in test_industry_defaults.py
uv run pytest tests/unit/test_industry_defaults.py -v

Derived ratios in `industry_medians.csv` Copy Chapter

All values are clipped to DCF-sane ranges (e.g. tax 5–40%, beta 0.3–2.5) in
the build script. See header comment in build_industry_medians.py.

Why xls files instead of just the CSV? Copy Chapter

Damodaran publishes xls only — the CSV is our derived artifact. Keeping the
raw files in-repo means:

1. The CSV is reproducible from primary sources.
2. Reviewers can audit which column we used (e.g. accrual vs cash tax rate).
3. Future refreshes can diff the xls files first to spot Damodaran schema
   changes before re-running the build script.

The four xls files total ≈230 KB — tolerable.

--- METRICS ---

• Files Extracted: 5
• Estimated Token Budget: ~14261 tokens
• Canonical Reference: https://codewiki.google/github.com/AI4Finance-Foundation/FinRobot