financial-analyst 1.0.1

A-share single-stock deep-dive multi-agent research workstation with three-tier trust isolation, FTS5 memory retrieval, dream loop introspection, and BYOM extensibility.

觀瀾 · Financial Analyst

One command. 25 AI agents. A 股深度研究.

Turn a 6-digit stock code into a 14-agent deep-dive report — fundamentals · technicals · whale signals · quant scores · bull/bear/risk debate — in ~10 minutes.

English  ·  中文

What is it  ·  Features  ·  Quick Start  ·  Agents  ·  Memory  ·  Datasets  ·  LLM  ·  Contribute

pip install financial-analyst==1.0.0    # 1 minute
financial-analyst                        # zero-config: wizard + backend + web UI + browser auto-opens

That's it. The first run: detects your config → runs the interactive wizard (LLM key + HF dataset pick) → starts the buddy backend on :9999 → starts the web UI on :5173 → opens your browser. Ctrl+C stops everything.

Power users: financial-analyst --tui for the terminal UI, or pick specific commands:

fa init                # wizard only (LLM key + data pack)
fa report SH600519     # one-shot deep-dive (~10 min, no UI)
fa launch              # explicit one-command launcher

---

💡 What Is It

A-share research workstation that thinks like a buy-side analyst.

Hand it a stock code; 14 specialized AI sub-agents run in 4 trust tiers:

Tier 1 (data, parallel)  →  Tier 2 (analysts, parallel)  →  Tier 3 (decision, serial)  →  Tier 4 (post-mortem)
─────────────────────       ─────────────────────────      ───────────────────────         ─────────────
quote · factors             fundamental                    bull-advocate ─┐
model · news                technical                      bear-advocate ─┤───→ writer    introspector
F10 · overseas              whale-sentiment                risk-officer   ┘
sector-rotation             quant                          (single writer)

Out comes a markdown research report — rated, attributed, falsifiable. The report-writer is the only agent allowed to write report files. Untrusted news/F10 sources are JSON-schema-locked at Tier-1 (no prompt injection). Memory is markdown — edit a .md, next report uses it. FTS5 retrieval cuts prompt cost ~60%.

---

✨ Key Features

🎯 14-agent stock deep-dive Hand it SH600519, get a full research report in ~10 min — fundamentals, technicals, whale signals, quant scores, bull/bear/risk debate, post-mortem self-audit. Only report-writer writes files. fa report SH600519	🌅 Morning brief (5-agent v2) Pre-market scan: overnight US + HK + VIX, A-share 异动, catalyst extraction, sector rotation, AI-written summary. fa brief
🌍 Overseas radar (v1.9.7) International transmission analysis: SPX/NDX/HSI/VIX/USDCNY → A-share follow-through judgment + actionable signals for tomorrow. fa overseas-radar	📈 Monthly mainline radar 5-state industry-chain classifier (mainline / initiation / revival / decay / cold). Catches init → mainline golden signal (+5.54pp fwd_60d, 87% win rate). fa mainline
🧠 Pluggable memory 24 per-agent memory dirs as markdown. Edit risk-officer/hard_rules.md, next report respects it. No code change. _shared/playbook_V1_V10.md cross-agent.	💤 Dream loop (self-improving) After each report, introspector flags quality issues. Aggregator clusters proposals → _proposed/ for human review. No auto-merge (errors compound in quant). fa dream --since 30
🔌 4-provider LLM routing qwen (domestic direct) · deepseek-chat/reasoner (Clash + MITM) · openai · anthropic. Per-provider network profile, no fake-ip hijack. financial-analyst # /model deepseek-reasoner	🧬 BYOM extensibility Drop a .py into config/plugins.yaml. Your private model joins the quant consensus. Your checkpoints never enter the open-source repo. See examples/ for FM cluster / CSV loader / TDX F10 patterns.

---

⚡ Quick Start

A. PyPI (recommended, 1 minute)

pip install financial-analyst==1.0.0
cp .env.example .env       # add DASHSCOPE_API_KEY (qwen default)
fa init                    # interactive wizard — pulls HF dataset
fa report SH600519         # first deep-dive

B. Docker (zero local setup, 2 minutes)

git clone https://github.com/jesson-hh/financial-analyst.git
cd financial-analyst
cp .env.example .env
docker compose up          # → interactive TUI

C. Source (development)

git clone https://github.com/jesson-hh/financial-analyst.git
cd financial-analyst
pip install -e ".[dev]"
pytest tests/              # 712 tests, ~8 min

---

🤖 The 25 Agents

Tier	Agents	Role
Tier 1 (data)	quote-fetcher · factor-computer · model-predictor · news-reader · f10-reader · overseas-market-scanner · sector-rotation-analyzer	Parallel fetch + factor + read untrusted (JSON-schema-locked)
Tier 2 (analysts)	fundamental · technical · whale · quant	Per-perspective structured analysis
Tier 3 (decision)	bull-advocate · bear-advocate · risk-officer · report-writer	Debate then synthesize (only writer can persist)
Tier 4 (audit)	introspector	Post-mortem self-audit + memory proposals
Market	market-scanner · morning-brief-writer · catalyst-extractor (v1.9.7) · global-news-aggregator (v1.9.7) · macro-impact-analyzer (v1.9.7) · mainline-classifier · mainline-writer · intraday-reviewer	Cross-stock and macro pipelines
Meta	ask	Free-form Q&A via tool chain (31 buddy tools)

Full DAG: docs/architecture/14_agents.md

---

🧠 Pluggable Memory

memories/
├── README.md                        # ← directory index, must-read
├── risk-officer/
│   ├── hard_rules.md                # ← edit this → next report uses it
│   └── pitfalls.md                  # FTS5-retrieved (large file)
├── technical-analyst/
│   └── factor_insights.md
└── _shared/
    └── playbook_V1_V10.md           # cross-agent shared

Edit a markdown → next agent run picks it up. No restart, no rebuild.

# Persist a lesson via slash command in TUI:
> /lesson Mega-cap PE>50 + 60d return>30% usually means liquidity-game stock

# Or just write the file:
vim memories/risk-officer/hard_rules.md

See memories/README.md for the 24 dir index and design principles.

---

📊 Datasets

Three preset bundles on HuggingFace, fa init auto-pulls:

Tier	Size	Stocks	5min	Financials	F10 text	TDX zip	Repo
demo	~155 MB	300 (CSI300)	❌	❌	❌	❌	data-demo
lite	~3 GB	800 (CSI800)	✅ ~7d	✅ 735 MB	✅ 1323 codes	❌	data-lite
full	~14 GB	5500+ (all A)	✅	✅	✅	✅ 257 MB	data-full

from huggingface_hub import snapshot_download
snapshot_download(
    repo_id="yifishbossman/financial-analyst-data-lite",
    repo_type="dataset",
    local_dir="~/.financial-analyst/data",
)

Two binary formats: Qlib .bin (time-series, [4-byte float32 start_idx] + [float32 array]) for OHLCV+factors; Parquet (columnar) for financials/events/F10/industry. Compatible with Microsoft Qlib and D.features() API directly.

---

🔌 LLM Providers

Provider	Models	Network profile	Use case
qwen (default)	qwen3.5-plus · qwen3-coder-plus	domestic (direct, no proxy)	国内最快最便宜
deepseek	deepseek-chat · deepseek-reasoner	intl_clash (Clash + verify=False MITM)	strong reasoning, low cost
openai	gpt-4o · gpt-4-turbo	intl_clash	universal fallback
anthropic	claude-opus-4-7 · claude-sonnet-4-6 · claude-haiku-4-5	litellm fallback	top quality (USD pricing)

Switch live in TUI:

> /model deepseek-reasoner    # hot-swap, no restart

Or set default in config/llm.yaml. See docs/llm_routing.md for the network_profile design.

---

🤝 Contributing

PRs welcome. See CONTRIBUTING.md for:

• Development loop (branch / test / lint / changelog / PR)
• Adding a new sub-agent (registry + memory + yaml + tests)
• Adding a new data source (net.py.domestic_session + @rate_limited)
• Conventional commits (angular preset)

Other docs:

• VERSIONING.md — N-2 LTS, semver policy
• SECURITY.md — vuln reporting (private)
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1
• docs/journey.md — bilingual build journey (empty repo → 440 alphas + 25 agents, ~2 weeks)

---

📄 License & Disclaimer

Apache 2.0. Research and educational purposes only. Drafts analyst-grade work product for review by qualified professionals. Does not make investment recommendations, execute transactions, or post to any ledger. You are responsible for compliance with applicable laws.

_{v1.0.0 · 2026-05-25 · made by @jesson-hh · bilingual zh/en}