BriefPaws

可审计的盘前/投委会研究简报：输入美股标的（可选研究问题）→ LangGraph 四节点编排 → 工具拉行情、算指标、读 mock 新闻 → 输出 report.md + run.json（数字与证据可回溯；含假设验证与 Reflection 护栏）。

核心能力

• CLI：briefpaws --symbols AAPL,MSFT --profile pm；加 --question 切投委会备忘录
• LangGraph：Supervisor → Data → Analyst → Report 四节点
• 工具链：yfinance 日 K（失败回退 mock）→ 6 项指标 → 隔夜窗 mock 新闻 → pm 披露摘要（get_filing_summary）
• LLM（可选）：有 .env 中 OPENAI_API_KEY 时润色 core_view，无则规则回退
• 校验：hypothesis 假设验证（计入 filing）+ reflection 护栏（含单次措辞 rerun）
• 证据语义：filing_summary 与 filing/official 新闻同等计入官方证据；有披露时不再写「证据不足」
• 落盘：runs/<run_id>/run.json + report.md，含 plan.steps 四步 done、reflection.decision
• 评测：eval/dataset.yaml 4 case + python eval/run_regression.py
• 观测：Langfuse 可选（docs/langfuse_setup.md / scripts/verify_langfuse.py）

环境要求

• Miniconda 或 Anaconda（推荐 Conda 管理 Python 3.11）
• 复制 .env.example → .env；离线演示保持 BRIEFPAWS_DATA=mock（跳过 yfinance）

快速启动

在 Anaconda Prompt 或已 conda init 的终端中，于项目根目录 BriefPaws/ 操作：

conda create -n briefpaws python=3.11 -y   # 首次
conda activate briefpaws

pip install -e ".[dev]"
# 首次：复制环境变量（Windows: Copy-Item .env.example .env）
cp .env.example .env
# 可选 LLM：pip install -e ".[dev,llm]"

briefpaws --symbols AAPL,MSFT --range 3M --profile pm --out runs/

输出目录示例：runs/<run_id>/run.json、runs/<run_id>/report.md

跑简报统一用 briefpaws（需先 pip install -e .）。python run.py ... 参数相同，仅作未装入 PATH 时的备用。

CLI

参数	说明
--symbols	逗号分隔，最多 10 只
--symbol	单只（兼容）
--range	默认 3M
--profile	pm（盘前简报 / 投委会 memo）
--question	研究问题；有则切 pm_memo 模板
--out	输出目录，默认 runs/

PM 演示

推荐先阅读仓库内固定样例，了解产出形态与可审计字段：

产出	说明
report.md	投委会备忘录正文（总览、催化剂、假设验证等）
run.json	落盘契约：plan.steps、filing_summary、hypothesis、reflection

本地复现同一条链路（需已配置 .env，默认 BRIEFPAWS_DATA=mock）：

# 投委会备忘录（写入 runs/）
briefpaws --symbols AAPL,MSFT,NVDA --profile pm --question "隔夜是否有影响开盘的披露？" --out runs/

# 固定样例
python examples/pm_memo/generate_sample.py

完整演示步骤见 examples/pm_memo/DEMO.md。

架构

LangGraph 四节点：Supervisor → Data → Analyst → Report（src/briefpaws/graph/）

• 无 --question：plan_variant=pre_market_brief + report_pre_market.md.j2
• 有 --question：plan_variant=pm_memo + report_pm.md.j2；报告含「假设验证」
• run.json 含 plan.steps、hypothesis、reflection
• Langfuse span 可选（无 key 时 no-op）；密钥见 .env.example

常用命令

目录	命令	说明
根目录	conda activate briefpaws	进入项目环境
根目录	pytest tests/ -q	全量测试（约 20 passed）
根目录	pytest tests/test_pev.py -v	Reflection rerun + filing 证据语义
根目录	pytest tests/test_filings.py -v	filings mock
根目录	python eval/run_regression.py	eval 4/4 硬断言
根目录	pytest tests/test_pm_memo.py -v	pm_memo 回归
根目录	pytest tests/test_reflection_hypothesis.py -v	hypothesis / Reflection
根目录	pytest tests/test_eval_dataset.py -v	eval 4 case 硬断言
根目录	pip install -e ".[dev]"	可编辑安装 + pytest
根目录	pip install -e ".[dev,llm]"	加上 OpenAI 兼容 LLM
根目录	pip install -e ".[dev,obs]"	加上 Langfuse 观测（可选）
根目录	python scripts/verify_langfuse.py	Langfuse 联调（需 key）

仓库结构

BriefPaws/
  run.py
  eval/                  # dataset.yaml + assertions.py + run_regression.py
  docs/                  # langfuse_setup.md
  examples/pm_memo/      # 投委会 demo + 固定样例（见上文「PM 演示」）
  scripts/               # verify_langfuse.py
  src/briefpaws/
    cli.py
    pipeline.py          # LangGraph 入口
    graph/               # 四节点编排
    brief_logic.py       # 工具与章节逻辑、plan
    tools/               # price / news / filings
    schemas/
    storage/
    observability/       # langfuse_tracer（可选）
  templates/             # pre_market + pm_memo
  data/news_mock.jsonl
  data/filings_mock.json
  tests/

许可证

本项目采用 MIT License。