Disclosure Alpha

Disclosure Alpha

确定性的 SEC 文件分析——解析、评分、比较。无需大模型。
提取章节、衡量语气和套话、检测同比变化，并筛选同行公司。

• 快速入门
• 项目简介
• 集成方式
• OpenBB Workspace
• 文件审阅界面
• 功能
• 输出示例
• 研究支持
• 文档

快速入门

需要 Python 3.11+。

1. 从 PyPI 安装

pip install "disclosure-alpha"

如需 HTTP API 和 MCP：pip install "disclosure-alpha[api,mcp]"。完整选项请参阅：安装。

2. 设置 SEC User-Agent（仅在使用 --ticker / EDGAR 时需要；对本地 --html 评分可跳过）

export SEC_USER_AGENT="YourName [email protected]"

请参阅 SEC EDGAR 设置。

3. 对文件评分

disclosure-alpha score --ticker AAPL --fiscal-year 2025 --form 10-K \
  | jq '.scores.overall_disclosure_risk_score'

from disclosure_alpha import score_filing_ticker
result = score_filing_ticker("AAPL", 2025, form_type="10-K")
print(result.scores.overall_disclosure_risk_score)

项目简介

面向 10-K 和 10-Q HTML 的开源、确定性 SEC 文件分析。基于文本指标、布尔风险标记和章节差异生成可复现的 JSON 评分；CLI、Python SDK、HTTP API、OpenBB Workspace 和 MCP 共用同一条处理流程。8-K 仅支持通过本地 --html 或 MCP Builder bundle 处理（不支持 --ticker、EDGAR 或 HTTP 股票代码路由）。

本项目不是什么：

• 不是投资建议或交易信号
• 不能替代阅读文件

完整范围和限制：范围与声明。

集成入口

七个入口，一个确定性流水线。不确定该选哪个？请参阅选择你的入口。

你是……	入口	额外安装
终端 / 脚本用户	disclosure-alpha	（基础）
笔记本 / 应用用户	import disclosure_alpha	（基础）
REST 筛选器或仪表板用户	disclosure-alpha-api	[api]
文件审阅分析师	disclosure-alpha-api → /app/	[api]
OpenBB Workspace 分析师	disclosure-alpha-api + OpenBB 指南	[api,mcp]
AI Agent（股票代码评分）	disclosure-alpha-mcp-analyst	[mcp]
使用原始 HTML 的 Agent	disclosure-alpha-mcp-builder	[mcp]

HTTP 矩阵层级仅适用于单股票代码 GET GET /v1/company/{ticker}/disclosure-matrix：tier=lite（概览评分）、tier=standard（组成部分 + 指标）、tier=analyst（用于审计的溯源信息）。面板 POST /v1/panel/disclosure-matrix 没有 tier 参数——请使用 include / fields。请参阅 HTTP 指南。

disclosure-alpha-api              # HTTP + OpenBB Workspace backend on :8000
disclosure-alpha-mcp-analyst      # MCP analyst bundle

指南、Postman 集合和 MCP 参考：指南。

文件审阅界面

可自托管的分析师视图将 OpenBB 风格的评分卡与文件阅读器相结合。选择检测到的标记后，系统会在用于分析的清理后文件章节中高亮显示其对应的确切短语。

pip install "disclosure-alpha[api]"
export SEC_USER_AGENT="YourName [email protected]"
disclosure-alpha-api

打开 http://127.0.0.1:8000/app/。原始 SEC 文件的链接位于审阅页眉中。开发和 API 详情请参阅文件审阅指南。

OpenBB Workspace

在 OpenBB Workspace 中，使用可自托管的后端为文件评分——在一个小组件中查看总体评分、组成部分、活跃标记和章节变化。

pip install "disclosure-alpha[api,mcp]"
export SEC_USER_AGENT="YourName [email protected]"
disclosure-alpha-api

在 Workspace 中：Apps → Connect backend → http://127.0.0.1:8000 → My Apps → Disclosure Alpha → Company → Run。从应用页面连接 Disclosure Alpha Analyst MCP，即可使用 Copilot 评分工具。

OpenBB Copilot 可以总结该小组件；这是 OpenBB 的功能，不属于 Disclosure Alpha。

快速入门：OpenBB Workspace · 完整指南：OpenBB 指南

功能

确定性评分 — 十个计算得出的组成项（九个按重要性加权，评分范围为 0–100）、章节提取、同比变化检测。规范组成项列表：评分目录。评分范围：了解评分。

任务	方法
为一家公司的文件评分	disclosure-alpha score --ticker AAPL --fiscal-year 2025 --form 10-K
在 OpenBB Workspace 中评分	disclosure-alpha-api + Workspace connect → OpenBB 快速入门
筛选最多 25 个股票代码	HTTP POST /v1/panel/disclosure-matrix（无需 tier；使用 include / fields）
比较同比变化	--prior-html prior.html 或 HTTP compare=prior
离线工作（不使用 EDGAR）	disclosure-alpha score --html filing.html --form 10-K
检查原始信号	disclosure-alpha metrics … 或 GET /disclosure-metrics
提取布尔风险标记	GET /disclosure-flags

# Screen a peer set (start disclosure-alpha-api first)
curl -s -X POST "http://localhost:8000/v1/panel/disclosure-matrix" \
  -H "Content-Type: application/json" \
  -d '{"tickers": ["AAPL", "MSFT", "GOOGL"], "fiscal_year": 2025, "form_type": "10-K"}'

# Year-over-year from local HTML (no network)
disclosure-alpha score --html current.html --form 10-K --prior-html prior.html

复制粘贴即可使用的配方：工作流。流程概览：方法论。

输出示例

单份申报文件评分（合成的 10-K）：

{
  "scores": {
    "overall_disclosure_risk_score": 17.84,
    "score_coverage_ratio": 0.7778,
    "components": {
      "risk_factor_intensity_score": 8.62,
      "boilerplate_risk_score": 42.53,
      "legal_regulatory_risk_score": 25.34
    }
  },
  "versions": {
    "parser_version": "section_extractor_v1",
    "metrics_engine_version": "text_metrics_v4",
    "dictionary_version": "built_in_dictionaries_v3",
    "scoring_model_version": "deterministic_scoring_v2",
    "analytics_config_id": "builtin_default"
  }
}

更多示例：示例集和工作流。

有研究依据

S&P 500 FY2025 Item 1A · deterministic_scoring_v2 · 完整证据 →

检验	结果
分析样本	478 家公司（503 家公司的总体）
特异性与 NER 对比	Spearman ρ ≈ 0.87（n=478）
模板化文本与 LS4-gram 代理指标对比	Spearman ρ ≈ 0.92（n=478）
申报后波动率（90 天）	Q5/Q1 ≈ 1.15（n=435）

构念检验使用独立参考数据。波动率关联仅作描述之用，不构成投资建议或超额收益信号。范围：适用范围与声明。

文档

我想……	从这里开始
五分钟内验证它是否可用	首次成功运行
评估是否值得信任	证据与验证
了解这些数字	了解评分
在终端中评分	CLI 快速入门
构建筛选器	HTTP 指南 → 工作流
在 Python 中使用	Python 快速入门
在 OpenBB Workspace 中评分	OpenBB 快速入门
查看复制粘贴示例	示例集

许可证

Apache-2.0。请参阅 LICENSE。更新日志 · 发行版本

贡献者

有关开发环境设置、测试和文档构建，请参阅 CONTRIBUTING.md。请通过 SECURITY.md 报告安全问题。