financial-analyst 1.0.6

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. 24 AI agents. A 股深度研究.

Turn a 6-digit stock code into a 16-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

🐣 Brand-new to Python / command line? Step-by-step beginner guide (Chinese, 30 min from zero): 小白上手指南 →

pip install financial-analyst==1.0.3    # 1 minute, no [serve] flag needed
fa start                                 # zero-config: wizard + backend + web UI + browser auto-opens

That's it. The first run: language picker → workspace picker (escape your system drive — point data at D:\fa-workspace or wherever) → LLM key → HF dataset pick → buddy backend on :9999 → web UI on :5173 → browser opens. Ctrl+C stops everything cleanly. Next fa start skips straight to the browser (services already healthy).

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

fa init                # wizard only (workspace + LLM key + data pack)
fa report SH600519     # one-shot deep-dive (~10 min, no UI)
fa update              # check PyPI + pip install -U (refuses editable installs)
fa data refresh        # smart refresh — skip if everything <24h fresh

🆕 v1.0.3 highlights (2026-05-25)

• 零 extras 安装 — pip install financial-analyst 即装即用, fastapi + uvicorn 并入 core, 不再需要 [serve] 后缀
• fa start — 新的零配置启动入口 (fa launch 保留为别名). 二次启动自动 fast-path 跳到浏览器, 不重启子进程
• Workspace pinning — 数据可以挂到 D:\fa-workspace 等任意盘, 不再绑死系统盘. 通过 fa init 一次性配
• 数据刷新按钮 — 状态栏新增 ✓ / ⏳ 盘中 / ⚠ / ↻ 四态徽章, 一键拉日线 + 5min + 估值
• fa update + fa data refresh — PyPI 自升级 (editable 安装会拒绝) + 智能增量刷新 (24h 内已更新自动跳过)

Full CHANGELOG.

---

💡 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

🎯 16-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.3
fa start                   # interactive wizard (LLM key + workspace + HF dataset)
                           # then auto-starts backend + UI + browser
# or non-interactive:
fa init --yes --preset demo --workspace D:/fa-workspace   # CI / scripted
fa report SH600519                                         # first deep-dive (~10 min)

B. 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 24 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.

🇨🇳 CN users: cloud-drive download (Aliyun / Quark)

HuggingFace is slow / frequently breaks from mainland China. We provide cloud-drive mirrors (Aliyun Drive + Quark, same data, MD5-verified). Two-step setup:

:: 1. Download zip from cloud drive (link below), extract to e.g. D:\fa-data
:: 2. Wire it into your workspace:
fa data link --src D:\fa-data

Bundle	Size	Aliyun Drive	Quark
demo (CSI300)	~155 MB	[link TBD]	[link TBD]
lite (CSI800 + 5min)	~3 GB	[link TBD]	[link TBD]
full (all A-share + 5min + F10)	~14 GB	[link TBD]	[link TBD]

fa data link writes config/loaders.yaml to point at your extracted directory — no copy, no symlink. Full walkthrough: docs/setup/data_offline.md.

Auto-acceleration since v1.0.6: fa init defaults HF_ENDPOINT=https://hf-mirror.com + enables hf_transfer multi-connection downloads (3-10× speedup) — no flag needed. Override either by setting your own env var. Power users outside CN: FA_DATA_SOURCE=hf fa init forces canonical hf.co.

Native ModelScope (魔搭) path: if the maintainer has mirrored data there (check HF_PACKAGES.*.modelscope_id), use FA_DATA_SOURCE=modelscope + pip install 'financial-analyst[modelscope]' for full-speed CN CDN downloads.

---

🔧 Optional · OpenCLI (news / xueqiu / THS F10)

Some sub-agents and buddy tools fetch live data from sites that need a browser session or scraping bridge — OpenCLI is that bridge. It's a Node.js CLI: npm install -g @jackwener/opencli. Optional but recommended.

Feature	Needs OpenCLI?	What happens without it
fa report SH600519 core report (valuation / technical / quant / debate)	❌	Works fully — uses local Qlib bin data + pytdx
News section in fa report	✅	Section renders empty (no crash)
fa news-collect (eastmoney / sinafinance kuaixun)	✅	Errors with install hint
fa news-collect --sources xueqiu-* (Xueqiu retail sentiment)	✅ + Chrome ext	Needs the OpenCLI Chrome extension and a xueqiu.com login
UI buddy tools: xueqiu watchlist / fund flow / THS iwencai	✅	Tool returns "opencli not installed" with install command

# Bare minimum (Node ≥ 21 prerequisite from nodejs.org)
npm install -g @jackwener/opencli
opencli --version              # verify

# THS-extra plugin (F10 / fund-flow / iwencai). Either path:
opencli plugin install https://github.com/jesson-hh/financial-analyst.git#main:opencli-plugin-ths-extra  # for pip-installed users
opencli plugin install file:///path/to/repo/opencli-plugin-ths-extra                                     # for source clones

# Chrome extension for cookie-mode collectors (xueqiu)
# https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk

# First test
fa news-collect                # default sources, ~200 items
fa doctor                      # verify all bridges OK

Step-by-step zh guide: beginner_zh.md Step 8. Xueqiu cookie-mode setup: xueqiu_setup.md.

---

🔌 LLM Providers

financial-analyst is a tool-heavy 24-agent system — Tier-1 calls buddy tools, Tier-2 joins cross-stock data, Tier-3 writes structured reports with [V#]/[F#] anchors, and report-writer is the only agent allowed to touch disk. Your LLM choice decides whether the swarm uses its tools or fabricates answers from training data.

Environment Variables

Set one provider's *_API_KEY in .env (the fa init wizard prompts for it). Defaults are loaded from config/llm.yaml.

Variable	Required	Description
DASHSCOPE_API_KEY	for qwen (default)	Aliyun Bailian — qwen3.5-plus / qwen3-coder-plus
DEEPSEEK_API_KEY	for deepseek	deepseek-chat / deepseek-reasoner
OPENAI_API_KEY	for openai	gpt-4o / gpt-4-turbo
ANTHROPIC_API_KEY	for anthropic	claude-opus / claude-sonnet / claude-haiku
TUSHARE_TOKEN	No	A-share data; without it the system falls back to pytdx main-stations + Tencent realtime (free, no token)

🎯 Recommended Models

Tier	Examples	When to use
Best	deepseek-reasoner · claude-opus-4-7 · gpt-4o · qwen3-max (requires general endpoint)	Tier-3 decision agents (bull / bear / risk-officer / report-writer / introspector), market-level swarms (overseas-radar / mainline / morning-brief writer)
Sweet spot (default)	qwen3.5-plus · qwen3-coder-plus · deepseek-chat	Daily driver — reliable tool-calling at low cost; Tier-1 data agents + Tier-2 analysts run here
Avoid for agent use	claude-haiku-4-5 · qwen-flash · qwen-turbo · *-mini · small / distilled variants	Tool-calling unreliable — agents skip D.features() / TDX-F10 lookups and hallucinate factor scores from training data instead of loading them from disk

Default ships with qwen3.5-plus. Aliyun Bailian gives 1M free token credit on signup — roughly 150 stock-deep-dive reports before you pay anything.

Network Profiles

network_profile decides how each provider connects through Chinese network conditions (Clash fake-ip, MITM, etc.):

Provider	Profile	Detail
qwen	domestic	trust_env=False, direct to aliyuncs.com — bypasses Clash fake-ip (which routes to overseas nodes and 10s-timeouts)
deepseek · openai · openrouter	intl_clash	Honours HTTPS_PROXY (default 127.0.0.1:7890) with verify=False — Clash MITMs HTTPS via its root cert
anthropic	litellm fallback	Anthropic SDK isn't OpenAI-compatible; the routing layer falls back to litellm

Hot-Swap

> /model deepseek-reasoner    # in TUI, no restart, in-flight session preserved
> /model qwen3-coder-plus     # bare name resolves provider; or use provider/model form
> /model                      # list configured models

Or change the default_provider / default_model in config/llm.yaml. See docs/llm_routing.md for the multi-provider AsyncOpenAI client design.

---

🤝 Issues & Feedback

Personal project, single maintainer. File issues at github.com/jesson-hh/financial-analyst/issues.

• VERSIONING.md — N-2 LTS, semver policy
• docs/journey.md — bilingual build journey (empty repo → 440 alphas + 24 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.3 · 2026-05-25 · made by @jesson-hh · bilingual zh/en}