xbrlkit

xbrlkit

在 Arelle 之上处理 XBRL 文件：获取文件，将其一次性解析为中立的类型化模型，再将该模型投影为所需的可移植表示形式；也可以传入其中一种表示形式，取回模型。

  EDGAR ───────────┐
  filings.xbrl.org ├──▶ Arelle ──▶ XbrlModel ──┬──▶ holon.jsonld    (RDF / JSON-LD)
  XBRL zip / iXBRL ┘                 ▲         ├──▶ TAVI            (compiled model)
                                     │         ├──▶ xBRL-JSON       (OIM)
                   holon, TAVI ──────┘         └──▶ property graph  (parquet, .lbdb, icebug-disk)

                   primary HTML ──▶ xbrlkit.text ──▶ sections (text blocks, Items, tables)

                   holon, TAVI ──▶ xbrlkit view ──▶ the report, rendered in a browser

                   any of the above ──▶ xbrlkit serve ──▶ MCP client (18 shaped tools, + Cypher with [lpg])

三种入口：SEC、通过 filings.xbrl.org 获取的其他所有文件，以及文件本身：XBRL 包或归档文件（.zip）、iXBRL 文档（.htm）、裸实例（.xml）、文件目录，或指向以上任一内容的 http(s) URL。整个流程中间环节不需要 EDGAR，甚至不需要监管机构——一份从未向任何机构提交的报告，解析起来和已提交的报告一样。

四种输出投影，其中两种支持读回，因此从未提交给 SEC 的报告也能得到同样的处理。第五种接口可读取文件正文，直接读取主 HTML，无需 Arelle 或网络。xbrlkit view 则会在屏幕上显示文件。

它也是一个本地 MCP 服务。 该包可独立使用——既是库，也是命令行工具——而 xbrlkit serve 会在内存中保存文件，并通过十八种经过设计的工具向 Claude、ChatGPT 或任何 MCP 客户端开放。这样，阅读文件就变成了对话，而不再是脚本：你可以询问某项报表、某个短语背后的概念、哪些项目加总得出某个小计、某个分部的明细、一份附件，或在正文中进行正则表达式搜索。系统不会建立索引，也不会使用数据库——每个答案都直接从你机器上内存中的文件读取。添加 lpg 扩展后，还能将多个文件写入同一属性图——例如同一家公司的不同年份，或同业公司——并对其执行只读 Cypher 查询。 你可以这样提问 →

Arelle 仍然负责解析——不应该有人重新实现 DTS 解析。它没有提供的是便于操作的承载对象：ModelXbrl 是一个庞大的可变对象图，依赖于必须关闭的控制器。XbrlModel 正是为此而生——它无状态、单文件、无损，是所有投影共同依托的核心。

**唯一的架构规则：**所有操作都必须通过 XbrlModel。直接访问 Arelle 的 ModelXbrl 的功能绕过了这个核心，而这种做法会让工具包变成杂物抽屉。

包含内容

parse	输入 Arelle，输出 XbrlModel	加载、DTS 缓存策略、分类标准包
serialize	四种投影	holon、TAVI（及其差异报告）、xBRL-JSON、属性图
deserialize	导入器	将 holon 或 TAVI 读回模型，无需 Arelle
edgar	SEC	发现、下载、全文搜索，涵盖 1994 年起的文件
filings_org	其他所有文件	按 LEI 获取 ESEF 和各国家监管体系的文件
text	文件正文	内联文本块、10-K/10-Q 项目、XML 表单
serve	本地 MCP 服务	面向内存中文件的十八种专用工具；使用 [lpg] 时，可对导出的图执行 Cypher 查询

model.py 本身就是这个核心，schema/ 声明属性图的表，query.py 对构建好的 holon 执行 SPARQL，cypher.py 对构建好的 .lbdb 或 icebug-disk 树执行只读 Cypher 查询，而 view.py 是 xbrlkit view 和 view_filing 工具背后的回环服务器。

安装

pip install xbrlkit

提供 xbrlkit CLI（build、fetch、query、view、cache、serve）和库。提供三个可选扩展：xbrlkit[lpg] 将属性图作为 LadybugDB 数据库，并支持查询（pyarrow、LadybugDB）；xbrlkit[icebug] 将同一张图作为实验性的 icebug-disk 树（仅需 pyarrow）；xbrlkit[mcp] 提供 MCP 服务。安装 xbrlkit[mcp,lpg] 即可使用该服务的图工具。

从源代码检出目录安装：

brew install uv just
just install     # dependencies, and .env from the template

SEC User-Agent

SEC 的公平访问政策要求 User-Agent 标明你的身份和联系信息。EDGAR 使用默认设置（其中包含项目名称），开箱即用；首次未注明身份的抓取会提示一次——SEC 按 IP 限速，因此共享默认设置不会占用其他人的额度。表明身份是出于礼貌，也值得推广。just install 已创建你的 .env：

# .env
SEC_GOV_USER_AGENT="Your Name [email protected]"

从此仓库的检出目录运行的每条命令都会自动加载 .env ——查找路径相对于已安装的代码，而非你的工作目录，因此通过 uvx 或 pip 安装时不会加载该文件。在这种情况下，可使用 export SEC_GOV_USER_AGENT=…、--user-agent 或 MCP env 块（参见向 MCP 客户端提供服务）。EDGAR 以外的内容都不需要它——本地文件、JSON 报告和 filings.xbrl.org 均可直接加载。

用法

# Build a holon.jsonld from a specific filing (-> ./output/)
xbrlkit build --cik 320193 --accno 0000320193-23-000106

# The other projections: TAVI (plus its .tavi.gaps.json sidecar), xBRL-JSON,
# the property graph (lpg: a .lbdb to query, needs the lpg extra; icebug: an
# experimental directory any LadybugDB reads in place), or every one of them
xbrlkit build --cik 320193 --accno 0000320193-23-000106 --format tavi
xbrlkit build --cik 320193 --accno 0000320193-23-000106 --format lpg
xbrlkit build --cik 320193 --accno 0000320193-23-000106 --format all

# Fetch the latest filing for a ticker (-> ./output/); --form and --n filter
xbrlkit fetch --ticker NVDA

# Query consolidated facts in a built holon (in-memory SPARQL)
xbrlkit query --in output/0000320193-23-000106.holon.jsonld --element us-gaap:Assets

# Open a filing as a rendered report in the browser — no account, no download
xbrlkit view NVDA

# The filing itself needs no EDGAR and no network — an XBRL .zip, an iXBRL
# .htm, a bare instance .xml, a filing directory. `serve` and `view` take any
# source; `build` and `fetch` are the EDGAR path
xbrlkit view ./report.zip
xbrlkit serve ./mmm-20241231.htm

在源代码检出目录中，just 会封装同一个 CLI：just build 320193 0000320193-23-000106 和 just fetch NVDA。

作为库使用时，FilingSession 会像 view 和 serve 一样解析申报文件，无需额外安装：

from xbrlkit.deserialize import from_holon_json
from xbrlkit.serialize import to_holon, to_tavi_report
from xbrlkit.serve import FilingSession

session = FilingSession()
model = session.load("NVDA").model  # or "NVDA 10-Q", "cik:accession", "lei:…", a path
holon = to_holon(model)             # holon.jsonld text
tavi, gaps = to_tavi_report(model)  # the TAVI model, and what it could not carry
model = from_holon_json(holon)      # and back again
session.close()

使用自有 Arelle 的宿主可再深入一层：xbrlkit.parse.load_model 会返回 ModelXbrl，而 to_xbrl_model(mx, filing) 会在提供申报文件的 FilingMeta（CIK 和 accession）的情况下，将其遍历并转换为同一模型。

向 MCP 客户端提供服务

有两种运行方式。它们的区别在于由哪个进程执行抓取，因此 SEC 身份的设置位置也不同。

stdio — 客户端启动服务。 身份信息应放在服务自身的 env 块中：

{
  "mcpServers": {
    "xbrlkit": {
      "command": "uvx",
      "args": [
        "--from", "xbrlkit[mcp]@latest",
        "xbrlkit", "serve", "--transport", "stdio"
      ],
      "env": { "SEC_GOV_USER_AGENT": "Your Name [email protected]" }
    }
  }
}

HTTP — 你启动服务，客户端只需指向一个 URL。 客户端配置中的 env 块在这里不起作用；请在命令中设置：

pip install "xbrlkit[mcp]"
SEC_GOV_USER_AGENT="Your Name [email protected]" xbrlkit serve
# → MCP at http://127.0.0.1:8765/mcp

# or without installing anything
SEC_GOV_USER_AGENT="Your Name [email protected]" \
  uvx --from "xbrlkit[mcp]@latest" xbrlkit serve

# with the graph tools: stacked lpg / icebug exports and run_cypher
SEC_GOV_USER_AGENT="Your Name [email protected]" \
  uvx --from "xbrlkit[mcp,lpg]@latest" xbrlkit serve

{
  "mcpServers": {
    "xbrlkit": { "type": "http", "url": "http://127.0.0.1:8765/mcp" }
  }
}

或者，等价地：

claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp

.env 文件不能作为上述两种方式的配置渠道。查找路径相对于已安装的代码，而非你的工作目录，因此只有在此仓库的检出目录中才能找到该文件——通过 uvx 或 pip 安装时不会读取它。请使用环境变量、env 块或 --user-agent。

这两种方式都不是必需的：EDGAR 在默认设置下可不注明身份使用，并会提示一次。filings.xbrl.org、本地软件包以及 TAVI/holon JSON 完全不需要身份信息。

你可以询问它什么

在聊天中加载一份申报文件——股票代码、EDGAR cik:accession、用于 ESEF 和各国监管制度的 lei:、本地 package，或按路径或 URL 指定的 holon 或 TAVI。如果 RoboSystems CDN 上有股票代码或 cik:accession 对应的已发布 holon（或其 TAVI 模型），则会优先加载；否则回退到 EDGAR。该副本是 RoboSystems 对申报文件的解析结果，并非实际提交的申报文件；答案中的 read_from 会说明你拿到的是哪一种；使用 --pure 或 XBRLKIT_ARTIFACTS_URL="" 则会改为从 EDGAR 解析。除非通过 --out-dir 指定其他位置，否则导出文件会保存到 ~/xbrlkit/output。接下来你可以：

• 以表格形式提取报表。 利润表、资产负债表、现金流量表或权益变动表——也可以是任何披露网络——按申报方自己的顺序和标签列出各行，并按期间列出数值。
• 查找短语背后的概念。 “收入”“经营租赁负债” → 该申报方实际报告的 qname，包括其自定义扩展概念，并按事实数量和出现位置排序。你无需猜测 US-GAAP 名称。
• 按概念和期间获取数值。 默认提供合并总额——不带维度限定符，并选取重复标签中最精确的一个——也可以按申报文件包含的任意轴拆分：分部、产品、债务工具、收购。
• 检查小计是否勾稽。 查看计算子项及其权重、各期间报告的总额与根据子项计算出的总和，以及两者之间的差额。
• 完整读取一项披露。 查看附注中的行及其数值、按附注自身的轴拆分后的相同行、勾稽后的计算弧，以及数值旁标记的文本。disclosures 索引会先快速找到正确的内容块。
• 搜索正文。 使用正则表达式搜索整个主要文档——项目、附注、封面、签名，无论是否带有标记。如果匹配结果过多，无法全部放入答案，则会列出其余结果所在的章节，并按结果最多的章节优先排列。
• 读取其他文档。 附件、8-K 的 EX-99.1 业绩公告——非 GAAP 指标和业绩指引都在其中，因为 XBRL 不包含这些内容——或 13F 的持仓表。
• 读取完全不含 XBRL 的表格。 将 Form 4 的交易和持仓、13F 的头寸与文档的标题字段一同列为行。
• 查找值得阅读的申报文件。 在 EDGAR 全文语料库中按短语、表格类型、日期和申报方搜索；每条结果都带有可用于加载该文件的 ID。
• 导出或渲染。 将申报文件写出为 holon、TAVI、xBRL-JSON、ClawDog、LadybugDB 图或 icebug-disk 树，也可以写出解析结果本身；或者在浏览器中打开渲染后的报告并返回链接。
• 汇总多份申报文件并跨文件查询（需安装 lpg extra）。将多个已加载的申报文件导出为一个图——例如某家公司的历年文件或同行公司的文件——然后使用 run_cypher 执行只读 Cypher 查询：例如按报告和期间查询收入，或查询某一年的比较数据重述的数值。

以上功能背后没有图或数据库：每个关于申报文件的答案都直接读取自该文件；run_cypher 唯一读取的图，是你要求 export_filing 写出的图。唯一的外部调用是 search_filings，它会查询 EDGAR 自己的全文索引，以确定要读取哪些申报文件。完整详情，包括工具表和 --pure 配置文件，请参阅 serve/。

运行位置

RoboSystems。 RoboSystems 平台的 SEC 管道基于此软件包构建：使用 xbrlkit.parse 解析申报文件（它自带 Arelle 控制器，并支持 register_sec_transforms 和 configure_webcache 中的缓存策略），再通过 to_holon、to_tavi_report 和属性图表进行投影；共享的 sec 图谱由 xbrlkit.schema 声明，文档搜索背后的全文索引则由 xbrlkit.text 构建。

Filing Ladder。 Filing Ladder 基准测试——将一份申报文件以每种表示形式交给同一个大模型——使用此软件包构建了包含 26 份 2024–2025 年 10-K 和 10-Q 的语料库。每种投影都是阶梯上的一阶，因此其已发布结果也衡量了模型使用这些输出时的能力。该语料库也是此软件包的测试平台：在全部 26 份申报文件中，文本章节均与申报文件自身的文本块事实进行了核对；属性图逐行与平台的处理器进行核对；JSON 导入器则通过往返测试进行核对。

查看与探索

构建的 holon 和 TAVI 模型可在 xbrlkit 查看器中渲染——这是工具包的浏览器端阅读器，可渲染财务报表，并让你使用 AI 提问报告：

• 托管版： https://xbrlkit.com/ — 打开 holon.jsonld 或 tavi.json，探索报表、附注和维度事实，或与报告对话。
• 源代码： https://github.com/RoboFinSystems/xbrlkit-viewer

查看器完全在客户端读取 holon，因此，单个 holon.jsonld 就是一份完整、可移植且自描述的报告。它的对话功能可以直接向报告提问（对 TAVI 模型使用 jq，对 holon 使用 SPARQL）；xbrlkit serve 则是这套组合的另一端——在你自己的机器上，通过封装好的工具访问同一份申报文件。

xbrlkit view 将两者结合起来。 它像 serve 一样解析申报文件，将其序列化，然后把这份文档交给查看器：

xbrlkit view NVDA                       # the latest 10-K, rendered in a browser tab
xbrlkit view "NVDA 10-Q" --as tavi      # a different form, a different serialization
xbrlkit view 320193:0000320193-23-000106
xbrlkit view lei:549300E9PC51EN656011   # a filer outside EDGAR
xbrlkit view output/x.holon.jsonld      # a document you already have, verbatim
xbrlkit view NVDA --no-open             # print the link instead of opening it

无需安装任何内容：

uvx xbrlkit view NVDA

浏览器无法接收本地路径——https 页面无法访问 file://，而文件输入也无法预先填充——因此，这会通过临时回环端口和无法猜测的路径提供文档，并打开指向该文档的 xbrlkit.com/view?url=…（早期版本会打开 xbrlkit.com/?url=…，该方式仍然有效）。http://127.0.0.1 是一个可能可信的来源，因此 https 页面可以读取它；CORS 标头只允许查看器的来源，不允许其他来源。按下 Ctrl-C 前，该来源都可以读取此处的文档。--viewer 可指向不同的构建版本。

在 MCP 客户端中，同样的功能是 view_filing 工具："load NVDA"，然后 "show me it"。

许可证

MIT © 2026 RFS LLC — 参见 LICENSE。