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])

取り込み方法は3つあります。SEC、filings.xbrl.org経由の その他すべて、そして提出書類そのものです。XBRLパッケージやアーカイブ （.zip）、iXBRL文書（.htm）、単独のインスタンス（.xml）、提出書類の ディレクトリ、またはこれらへのhttp(s) URLを指定できます。処理の中核に EDGARも規制当局も必要ありません。どこにも提出されていないレポートも、 提出されたものと同じように解析できます。

出力形式は4つあり、そのうち2つは読み戻しにも対応しているため、SECに 提出されたことのないレポートも同じように扱えます。5つ目の機能では、提出 書類のテキストをプライマリーHTMLから直接読み取るため、Arelleもネットワーク も必要ありません。また、xbrlkit viewを使うと、提出書類を画面に表示できます。

ローカルMCPサーバーとしても動作します。 このパッケージは単体で動作し、 ライブラリとCLIを提供します。一方、xbrlkit serveは提出書類をメモリに保持し、 18個の用途に応じたツールを通じてClaude、ChatGPT、またはあらゆるMCP クライアントに公開します。これにより、提出書類をスクリプトではなく会話で 読み解けます。財務諸表、ある語句に関連する概念、小計の構成要素、セグメント の内訳、添付資料、または本文全体を対象とした正規表現検索を尋ねられます。 インデックスは作成されず、背後にデータベースもありません。回答はすべて、 お使いのマシン上でメモリ内の提出書類から読み取られます。lpgエクストラを 使うと、複数の提出書類を1つのプロパティグラフとして書き出すこともできます。 企業の複数年分や同業他社の書類などをまとめられ、読み取り専用のCypherで クエリできます。 質問できる内容 →

パーサーには引き続きArelleを使います。DTS解決を再実装すべきではありません。 一方、Arelleが提供しないのは、扱いやすく保持できるオブジェクトです。 ModelXbrlは、終了処理が必要なコントローラーに結び付いた、大規模で変更可能な オブジェクトグラフです。その解決策がXbrlModelです。ステートレスで、単一の 提出書類を対象とし、情報を損失せず、あらゆる投影が依拠する共通基盤です。

アーキテクチャ上の唯一のルール： すべての処理はXbrlModelを経由します。 ArelleのModelXbrlに直接アクセスする機能は、この共通基盤を迂回しています。 それこそが、ツールキットを雑多な機能の寄せ集めに変えてしまう変更です。

パッケージの内容

parse	Arelleを入力し、XbrlModelを出力	読み込み、DTSキャッシュポリシー、タクソノミーパッケージ
serialize	4つの投影形式	holon、TAVI（およびその差分レポート）、xBRL-JSON、プロパティグラフ
deserialize	インポーター	holonまたはTAVIをモデルに読み戻し。Arelleは不要
edgar	SEC	1994年以降の情報検索、ダウンロード、全文検索
filings_org	その他すべて	LEIによるESEFおよび各国の制度への対応
text	提出書類の文章	インラインテキストブロック、10-K／10-Qの項目、XML形式
serve	ローカルMCPサーバー	メモリ内の提出書類に対応する18個の用途別ツール。[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）とライブラリを提供します。オプションの追加機能が3つあります。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 クライアントへの提供

実行方法は2通りあります。取得をどのプロセスが行うかが異なるため、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:、ローカルパッケージ、またはパスや URL で指定した holon や TAVI を利用できます。ティッカーまたは cik:accession を指定すると、RoboSystems CDN に公開済みの holon（または TAVI モデル）がある場合は、まずそれを読み込み、なければ EDGAR にフォールバックします。このコピーは提出書類そのものではなく、RoboSystems による提出書類の解析結果です。どちらを読み込んだかは回答の read_from に示されます。--pure または XBRLKIT_ARTIFACTS_URL="" を指定すると、代わりに EDGAR から解析します。エクスポート先は、--out-dir で指定しない限り ~/xbrlkit/output です。次のことができます。

• 財務諸表を表形式で取得する。 損益計算書、貸借対照表、キャッシュフロー計算書、株主資本等変動計算書、または任意の開示ネットワークを、提出者独自の行順とラベルで、各期間を列にして取得します。
• 語句に対応するコンセプトを見つける。 「収益」「オペレーティング・リース負債」などの語句から、提出者が実際に報告している QName（独自の拡張コンセプトも含む）を、ファクト数と出現箇所で順位付けして探します。米国会計基準の名称を推測する必要はありません。
• コンセプトと期間を指定して値を取得する。 デフォルトでは連結合計（ディメンション修飾子なし、重複タグがある場合は最も精度の高いもの）を取得します。または、提出書類に含まれる任意の軸で内訳を取得できます。セグメント、製品、負債性金融商品、買収などが対象です。
• 小計が一致するか確認する。 計算上の子項目とその重み、報告された合計と子項目から計算した合計の比較を、期間ごとの差額とともに取得します。
• 開示をまるごと読む。 注記の行と値、注記独自の軸による同じ行、合計が一致するか確認した計算アーク、数値に対応するタグ付きテキストを取得します。disclosures インデックスを使うと、該当するブロックを効率よく先に見つけられます。
• 文章を検索する。 タグの有無を問わず、文書全体（項目、注記、表紙、署名を含む）を対象に正規表現で検索します。パターンに一致する箇所が回答に収まりきらない場合は、残りが含まれるセクションを件数の多い順に示します。
• その他の文書を読む。 別紙、8-K の EX-99.1 earnings release（非 GAAP 指標や業績見通しが記載されている箇所。XBRL には含まれません）、13F の保有銘柄表などを読めます。
• XBRL がまったくない様式を読む。 Form 4 の取引と保有状況、13F のポジションを、文書のヘッダーフィールドと並べた行として取得します。
• 読む価値のある提出書類を見つける。 EDGAR の全文検索で、フレーズ、様式、日付、提出者を指定してコーパスを検索します。各検索結果には、読み込みに使える ID が含まれます。
• エクスポートまたはレンダリングする。 提出書類を holon、TAVI、xBRL-JSON、ClawDog、LadybugDB グラフ、icebug-disk ツリー、または解析結果そのものとして書き出せます。または、ブラウザーでレンダリングしたレポートを開き、リンクを返せます。
• 複数の提出書類をまとめて横断検索する（lpg エクストラが必要です）。読み込んだ複数の提出書類をひとつのグラフとしてエクスポートし（ある企業の複数年分、または同業他社など）、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 ベンチマークでは、同じ提出書類をあらゆる表現で同じ言語モデルに渡します。このパッケージを使って、2024～2025 年の 10-K と 10-Q を集めた 26 件の提出書類コーパスを構築しました。各投影はラダーの 1 段に相当するため、公開された結果は、モデルがこれらの出力をそれぞれ使って何ができるかを測定したものでもあります。このコーパスは、このパッケージのテストベンチでもあります。26 件すべての提出書類について、テキストセクションを提出書類自身のテキストブロックファクトと照合し、プロパティグラフをプラットフォームのプロセッサと行ごとに照合し、JSON インポーターをラウンドトリップで検証しました。

表示と探索

構築したホロンと TAVI モデルは、ツールキットのブラウザー側を担うリーダーである xbrlkit viewer で表示できます。財務諸表をレンダリングし、AI を使ってレポートに質問できます。

• ホスト版： https://xbrlkit.com/ — holon.jsonld または tavi.json を開いて、財務諸表、注記、ディメンションファクトを探索したり、レポートとチャットしたりできます。
• ソース： https://github.com/RoboFinSystems/xbrlkit-viewer

ビューアーはホロンをすべてクライアント側で読み込むため、単一の holon.jsonld が、完全で、持ち運び可能な自己記述型レポートになります。チャットではレポートに対して直接質問できます（TAVI モデルに対する jq、ホロンに対する SPARQL）。xbrlkit serve はその対となる機能で、同じ提出書類を、構造化されたツールを通じて自分のマシン上で利用できます。

xbrlkit view はこの 2 つをつなぎます。 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 ツールで利用できます。「NVDA を読み込んで」と言ってから、「それを見せて」と言います。

ライセンス

MIT © 2026 RFS LLC — LICENSE を参照してください。