xbrlkit

xbrlkit

Work with XBRL filings above Arelle: fetch a filing, parse it once into a neutral typed model, and project that model into whichever portable representation you need — or hand it one of those representations and get the model back.

  EDGAR ───────────┐

filings.xbrl.org ├──▶ Arelle ──▶ XbrlModel ──┬──▶ holon.jsonld (RDF / JSON-LD) XBRL zip / iXBRL ┘ ▲ ├──▶ TAVI (compiled model) │ ├──▶ xBRL-JSON (OIM) │ ├──▶ ClawDog (authored-report JSON-LD) holon, TAVI, ClawDog ──────┘ └──▶ 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])

Three ways in — the SEC, everyone else through filings.xbrl.org, and the filing itself: an XBRL package or archive (.zip), an iXBRL document (.htm), a bare instance (.xml), a filing directory, or an http(s) URL to any of them. Nothing about the middle of this requires EDGAR, or a regulator at all — a report that was never filed with anybody parses like one that was.

Five projections out, and three of those read back, so a report that was never an SEC filing gets the same treatment. Another surface, the filing's text, reads the primary HTML directly and needs neither Arelle nor the network. And xbrlkit view puts a filing on screen.

It is also a local MCP server. The package stands alone — a library and a CLI — but xbrlkit serve holds filings in memory and exposes them to Claude, ChatGPT or any MCP client through eighteen shaped tools, which makes reading a filing a conversation instead of a script: ask for a statement, the concepts behind a phrase, what foots to a subtotal, a segment breakdown, an exhibit, or a regex across the prose. Nothing is indexed and no database sits behind it — every answer is read from the filing in memory, on your machine. With the lpg extra it also writes several filings as one property graph — a company's years, or its peers — and answers read-only Cypher over it. [What you can ask it →](#what-you-can-ask-it)

Arelle stays the parser — nobody should reimplement DTS resolution. What it does not give you is anything ergonomic to *hold*: ModelXbrl is a large mutable object graph tied to a controller you have to close. XbrlModel is the answer to that — stateless, single-filing, lossless, and the waist every projection hangs off.

The one architectural rule: everything goes through XbrlModel. A feature that reaches into Arelle's ModelXbrl directly is bypassing the waist, and that is the change that turns a kit into a junk drawer.

What's in the box

model.py is the waist itself, schema/ declares the property graph's tables, query.py runs SPARQL over a built holon, cypher.py runs read-only Cypher over a built .lbdb or icebug-disk tree, and view.py is the loopback server behind xbrlkit view and the view_filing tool.

Install

pip install xbrlkit

Exposes the xbrlkit CLI (build, fetch, query, view, cache, serve) and the library. Three optional extras: xbrlkit[lpg] for the property graph as a LadybugDB database and for querying it (pyarrow, LadybugDB), xbrlkit[icebug] for the same graph as an experimental icebug-disk tree (pyarrow only) and xbrlkit[mcp] for the MCP server. Install xbrlkit[mcp,lpg] for the server's graph tools.

From a source checkout:

brew install uv just

just install # dependencies, and .env from the template

SEC User-Agent

SEC fair access asks for a User-Agent identifying you with contact info. EDGAR works out of the box under a default that names the project, and the first unattributed fetch says so once — SEC rate limits per IP, so the shared default costs nobody else their budget. Identifying yourself is a courtesy, and one worth extending. just install already created your .env:

# .env

SEC_GOV_USER_AGENT="Your Name your@email.com"

.env is loaded automatically by every command run from a checkout of this repo — the lookup is relative to the installed code, not your working directory, so a uvx or pip install never picks one up. There, use export SEC_GOV_USER_AGENT=…, --user-agent (before the command), or an MCP env block (see Serve to an MCP client). Nothing outside EDGAR needs it — a local file, a JSON report and filings.xbrl.org all load without.

Usage

# 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,

ClawDog, the property graph (lpg: a .lbdb to query, needs the lpg extra; icebug:

an experimental directory any LadybugDB reads in place), or all for every one

of them but the graph

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 10-K 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

From a source checkout, just wraps the same CLI: just build 320193 0000320193-23-000106 and just fetch NVDA.

As a library, a FilingSession resolves a filing the way view and serve do, with no extra installed:

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

A host running its own Arelle goes a level down: xbrlkit.parse.load_model returns the ModelXbrl, and to_xbrl_model(mx, filing) walks it into the same model, given the filing's FilingMeta (CIK and accession).

Serve to an MCP client

Two ways to run it. They differ in which process does the fetching, and so in where your SEC identity goes.

stdio — the client launches the server. The identity belongs in the server's own env block:

{

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

HTTP — you start the server, the client only points at a URL. An env block in the client config would reach nothing here; set it on the command:

pip install "xbrlkit[mcp]"

SEC_GOV_USER_AGENT="Your Name you@example.com" xbrlkit serve

→ MCP at http://127.0.0.1:8765/mcp

or without installing anything

SEC_GOV_USER_AGENT="Your Name you@example.com" \ uvx --from "xbrlkit[mcp]@latest" xbrlkit serve

with the graph tools: stacked lpg / icebug exports and run_cypher

SEC_GOV_USER_AGENT="Your Name you@example.com" \ uvx --from "xbrlkit[mcp,lpg]@latest" xbrlkit serve

{

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

or, equivalently:

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

A .env file is not a channel for either of these. The lookup is relative to the installed code rather than your working directory, so it resolves only inside a checkout of this repo — a uvx or pip install never sees one. Use the environment, the env block, or --user-agent before the command.

Both are optional: EDGAR works unattributed under the default, saying so once. And filings.xbrl.org, local packages and TAVI/holon JSON need no identity at all.

What you can ask it

Load a filing from the chat — a ticker, an EDGAR cik:accession, a lei: for ESEF and the national regimes, a local package, or a holon or TAVI by path or URL. A ticker or cik:accession loads the filing's published holon (or its TAVI model) first when the RoboSystems CDN has one, falling back to EDGAR. That copy is RoboSystems' parse of the filing, not the filing as filed, and the answer's read_from says which one you have; --pure or XBRLKIT_ARTIFACTS_URL="" parses it from EDGAR instead. Exports go to ~/xbrlkit/output unless --out-dir says otherwise. Then:

• Pull a statement as a table. The income statement, balance sheet, cash flow or equity statement — or any disclosure network — as rows in the filer's own order and labels, values per period column.
• Find the concept behind a phrase. "Revenue", "operating lease liability" → the qnames *this* filer actually reports, its own extension concepts included, ranked with fact counts and where each appears. You never have to guess a US-GAAP name.
• Get values by concept and period. Consolidated totals by default — no dimensional qualifier, the most precise of duplicate tags — or broken out by any axis the filing carries: segment, product, debt instrument, acquisition.
• Check whether a subtotal foots. The calculation children with their weights, the reported total against the sum computed from them, per period, with the difference.
• Read one disclosure whole. A note's rows with values, the same rows by its own axes, its calculation arcs footed, and its tagged text beside the numbers. The disclosures index finds the right block first, cheaply.
• Search the prose. Regex over the whole primary document — Items, the notes, the cover, the signatures, tagged or not