Skip to content

About

美股个股自主研究 Agent:DCF + 可比公司 + 引用校验;输入 ticker,输出研报备忘 | Autonomous US equity research: DCF, comps, cited claims.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation


这是什么

alpha-analyst 把「分析师级」个股研究的流程工程化:给它一个美股 ticker,它产出一份九节研究备忘——executive summary / financial snapshot / catalysts / DCF 与可比公司估值 / earnings-call 语气变化 / bull-bear / risks——每一个含数字的主张都绑回一条带来源的引用。

核心原则是「LLM 是写手,不是知道分子」:数字全部来自确定性代码与公开数据源(SEC、Yahoo、FRED、Google News),LLM 只负责行文。默认配置用确定性的 mock 写手 + 仓库自带离线 fixtures,零 API key、零出网就能跑通全流程、跑绿全部测试。

给谁用:想读「数字可追溯」研究产出的投研读者;想把多 agent 流水线工程化的开发者。


功能

  • 🧮 Decimal DCF 引擎 — 显式预测期 + Gordon 终值 + 敏感性表;终值增速 ≥ WACC、负现金流、缺数据均为显式校验与降级,全程 decimal.Decimal。 → src/alpha_analyst/core/dcf.py
  • 📊 可比公司估值 — 同行倍数中位数 + 隐含市值;口径诚实标注(如 ocf_multiple 明示为 EV/EBITDA 代理)。 → src/alpha_analyst/core/comps.py
  • 🌐 统一数据层 — Provider 接口 + 注册表 + 磁盘缓存,超时/重试/退避内建;keyless 源覆盖 SEC companyfacts、SEC EDGAR、Yahoo chart、FRED、Google News,缺失数据集自动降级到离线 fixtures。 → src/alpha_analyst/data/
  • 🤖 五路研究 agent + 恶魔代言人 — news / filings / market / earnings / alt-data 并发执行,随后一轮对抗性质询(质询复用原来源引用,不新造证据)。 → src/alpha_analyst/agents/
  • 🔍 引用纪律单一实现 — 事实表(F1…Fn)→ 逐节校验 → 引用导出 → 审计;正文出现数字必须带 [F#],未知标签或「有数字无引用」判失败并自动降级该小节。 → src/alpha_analyst/core/citations.py
  • 🧪 离线优先、可测 — ALPHA_DATA_MODE=offline + ALPHA_LLM_MODE=mock 全链路可跑;135 条 pytest 全绿,网络调用在传输层用 respx 拦截,测试套件永不出网。 → tests/
  • 🗂️ 配置集中 — 数据集→provider 映射与 SEC CIK 表、任务→模型映射、全部环境变量分别收敛到 configs/ 与 .env.example,业务代码不直接读环境变量。 → configs/
  • 🖥️ CLI 三件套 — research(Markdown 或 --json)/ audit(引用审计,失败退出码 1)/ sources(provider 与 fixture 覆盖)。 → src/alpha_analyst/__main__.py

快速开始

# 0. 克隆并安装(仅 pydantic / pydantic-settings / PyYAML / httpx;Python 3.11+)
git clone https://github.com/lss680455-create/alpha-analyst.git
cd alpha-analyst
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 1. 零 key、零出网跑一份研究备忘(使用仓库自带离线 fixtures)
ALPHA_DATA_MODE=offline ALPHA_LLM_MODE=mock python run.py research AAPL

输出一份九节 Markdown 备忘。落盘与其它命令:

ALPHA_DATA_MODE=offline ALPHA_LLM_MODE=mock python run.py research AAPL > memo.md
ALPHA_DATA_MODE=offline ALPHA_LLM_MODE=mock python run.py audit AAPL

用法

跑研究 / 审引用 / 看数据源

python run.py research AAPL            # 九节备忘(Markdown)
python run.py research AAPL --json     # 结构化 run JSON(含全部 agent 输出与事实表)
python run.py audit AAPL               # 引用审计:失效引用时退出码 1
python run.py sources                  # 已注册 provider、数据集映射、fixture 覆盖

抓取真实数据落成离线 fixtures(需要网络;如走上游代理可用 ALPHA_HTTP_PROXY)

python scripts/fetch_fixtures.py --ticker AAPL --peers MSFT,GOOGL,META,NVDA,DELL

跑测试(离线,无需 key)

python -m pytest -q                    # 135 passed

关键环境变量(完整清单见 .env.example)

变量 取值 说明
ALPHA_DATA_MODE offline / auto / live 数据来源:只读 fixtures / 先 live 后降级 / 只打真实接口
ALPHA_LLM_MODE mock / litellm mock 为确定性模板写手;litellm 接任意 LiteLLM 支持的模型
ALPHA_HTTP_PROXY 如 socks5h://127.0.0.1:10808 出网代理(仅数据抓取;socks5 需 httpx[socks])
ALPHA_EDGAR_USER_AGENT YourApp (you@example.com) SEC 要求的可识别 User-Agent
ALPHA_CACHE_DIR / ALPHA_CACHE_TTL_SECONDS 路径 / 秒 live 抓取的磁盘缓存
ALPHA_MAX_COST_PER_ANALYSIS 美元 成本护栏(仅 litellm 模式生效)

架构

flowchart LR
    A[Yahoo / SEC / FRED / Google News] -->|live| G[DataGateway<br/>provider 注册表 + 缓存]
    F[(离线 fixtures)] -->|offline| G
    G --> N[news] & FI[filings] & M[market] & E[earnings] & AD[alt-data]
    N & FI & M & E & AD --> FACTS[事实表 F1…Fn<br/>core.citations]
    FACTS --> DC[Decimal DCF] & CP[comps]
    DC & CP --> DA[恶魔代言人<br/>对抗性质询]
    DA --> S[合成器<br/>LLM = 写手]
    FACTS --> S
    S --> V{引用校验}
    V -->|通过| R[九节备忘<br/>Markdown / JSON]
    V -->|失败小节| D[显式降级]
    D --> R
Loading

分层职责:

  • data/ — 数据层。Provider 接口 + 注册表 + 磁盘缓存;live 源与离线 fixtures 同构,DataGateway 按 mode 择优并降级。
  • core/ — 纯逻辑层。DCF、comps、引用纪律、展示格式化,无 I/O、无 LLM,全部可单测。
  • agents/ — 研究层。五个数据 agent 只做「抓取 → 找结论」,LLM(或 mock 写手)只出现在需要语言能力的位置;错误不抛出,随输出上报。
  • orchestrator/ — 编排层。依赖注入的流水线:并发跑 agent → 构造事实表 → 情景估值(base / bull / bear)→ 质询 → 合成。
  • report/ — 渲染层。ResearchRun → Markdown(备忘 + 引用清单 + 附录)或结构化 JSON。

仓库目录:

alpha-analyst/
├── src/alpha_analyst/
│   ├── config.py            # 集中配置(env + YAML,含 .env 支持)
│   ├── schemas.py           # 跨层数据模型(Decimal 金额 + Source 溯源)
│   ├── data/                # Provider / 注册表 / 缓存 / fixtures
│   ├── core/                # DCF / comps / 引用纪律 / 格式化(纯逻辑)
│   ├── agents/              # 数据 agent + 恶魔代言人 + 合成器 + MockLLM
│   ├── orchestrator/        # 流水线编排(依赖注入)
│   ├── report/              # Markdown / JSON 渲染
│   └── __main__.py          # CLI:research / audit / sources
├── configs/                 # sources.yaml(数据源 + CIK)/ models.yaml
├── scripts/fetch_fixtures.py
├── examples/                # 离线 demo 产物 + fixture 清单
├── tests/                   # 离线测试(respx 拦截全部网络)
└── docs/assets/hero.svg

成果展示


文档导航

文档 内容
CHANGELOG.md 版本变更、架构重构要点与上游 commit 记录
configs/sources.yaml 数据集 → provider 映射、SEC CIK 表
configs/models.yaml LLM 任务 → 模型映射(litellm 模式)
.env.example 全部环境变量与说明
tests/ 135 条离线测试:DCF/comps/引用纪律/数据层/CLI 的口径即文档

免责声明

本项目为研究与工程示范,不构成任何投资建议。数据来自公开接口(SEC、Yahoo、FRED、Google News),准确性以官方来源为准;sample 数据仅用于演示链路。


许可

Apache-2.0 · 数字可追溯,观点可辩论。

本项目基于开源项目 AlphaAnalyst(Apache-2.0)重构与增强。

About

美股个股自主研究 Agent:DCF + 可比公司 + 引用校验;输入 ticker,输出研报备忘 | Autonomous US equity research: DCF, comps, cited claims.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages