xbrlkit 0.2.0__tar.gz

xbrlkit-0.2.0/.gitignore

@@ -0,0 +1,144 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+scripts/
+var/
+src/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+data/
+data/input/
+data/output/
+notebooks/
+uv.lock
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+Dockerfile
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env*
+!.env.example
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# MacOS
+.DS_STORE
+
+# Node.js
+node_modules/
+package-lock.json
+
+# npm package files
+*.tgz
+
+# AI - Claude Code
+.claude/settings.local.json
+CLAUDE.local.md
+
+.gemini/
+GEMINI.md

xbrlkit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RFS LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xbrlkit-0.2.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: xbrlkit
+Version: 0.2.0
+Summary: Work with XBRL filings above Arelle: one parse, portable models
+Project-URL: Repository, https://github.com/RoboFinSystems/xbrlkit
+Project-URL: Homepage, https://github.com/RoboFinSystems/xbrlkit#readme
+Project-URL: Bug Tracker, https://github.com/RoboFinSystems/xbrlkit/issues
+Author: RFS LLC
+License: MIT
+License-File: LICENSE
+Keywords: arelle,edgar,financial,holon,jsonld,oim,rdf,sec,tavi,xbrl
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: arelle-release
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.11
+Requires-Dist: pyshacl
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rdflib
+Requires-Dist: regex
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.21; extra == 'dev'
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.26; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# xbrlkit
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Work with XBRL filings above [Arelle](https://arelle.org): fetch a filing, parse
+it **once** into a neutral typed model, and project that model into whichever
+portable representation you need.
+
+```
+EDGAR ──▶ Arelle ──▶ XbrlModel ──┬──▶ holon.jsonld   (RDF / JSON-LD)
+                                 ├──▶ Tavi           (compiled model)
+                                 └──▶ …
+```
+
+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.
+
+## Projections
+
+| Target | Status | Notes |
+| --- | --- | --- |
+| **holon** (`.holon.jsonld`) | shipped | RDF/JSON-LD, renders in the [Holon Viewer](https://holon.robosystems.ai/) |
+| **Tavi** (`.tavi.json`) | shipped | [Project Tavi](https://www.xbrl.org/Specification/tavi/PWD-2026-09-01/tavi-PWD-2026-09-01.html) compiled model, PWD-2026-09-01 |
+| OIM (xBRL-JSON / xBRL-CSV) | planned | Arelle already emits these; a native writer is a fidelity check on `XbrlModel` |
+| property graph / Parquet | planned | see `model.py` |
+
+Tavi is a **public working draft** and its name is explicitly a working title,
+so treat that projection as tracking a moving target. `--format tavi` also
+writes a `.tavi.gaps.json` sidecar recording what the filing carries that the
+model has nowhere to put — that file is the point of the projection, not a
+by-product of it.
+
+## Install
+
+### As a package
+
+```bash
+pip install xbrlkit
+```
+
+Exposes the `xbrlkit` CLI (`xbrlkit build …`, `xbrlkit fetch …`, `xbrlkit query …`)
+and the library — use this to consume it from another project. Set your SEC
+User-Agent via the environment (see [SEC User-Agent](#sec-user-agent)).
+
+### From source (development)
+
+```bash
+# Install the toolchain
+brew install uv just
+
+# Install dependencies and provision .env from the template
+just install
+```
+
+`just install` creates `.env` from `.env.example` on first run — then set your
+SEC User-Agent in it.
+
+## SEC User-Agent
+
+SEC EDGAR requires a descriptive `User-Agent` on every request, or it throttles
+you (empty responses / HTTP 429). `just install` already created your `.env` —
+set your details there:
+
+```bash
+# .env
+SEC_GOV_USER_AGENT="Your Name your@email.com"
+```
+
+`.env` is loaded automatically by every command. Outside the `just` workflow,
+`export SEC_GOV_USER_AGENT="Your Name your@email.com"` or pass `--user-agent`.
+
+## Usage
+
+```bash
+# Build a holon.jsonld from a specific filing (-> ./output/)
+xbrlkit build --cik 320193 --accno 0000320193-23-000106
+
+# Fetch the latest filing for a ticker (-> ./output/)
+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
+```
+
+From a source checkout, `just` wraps the same CLI as a shorthand:
+`just build 320193 0000320193-23-000106` and `just fetch NVDA`.
+
+## View & explore
+
+Built holons render in the **RoboSystems Holon Viewer** — a browser-based reader
+that renders the financial statements and lets you ask questions of the report
+with AI:
+
+- **Hosted:** <https://holon.robosystems.ai/> — open a `holon.jsonld` and explore
+  the statements, notes, and dimensional facts, or chat with the report.
+- **Source:** <https://github.com/RoboFinSystems/robosystems-holon-viewer> — run
+  it locally or self-host.
+
+The viewer reads a holon entirely client-side, so a single `holon.jsonld` is a
+complete, portable, self-describing report.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+MIT © 2026 RFS LLC

xbrlkit-0.2.0/README.md

@@ -0,0 +1,113 @@
+# xbrlkit
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Work with XBRL filings above [Arelle](https://arelle.org): fetch a filing, parse
+it **once** into a neutral typed model, and project that model into whichever
+portable representation you need.
+
+```
+EDGAR ──▶ Arelle ──▶ XbrlModel ──┬──▶ holon.jsonld   (RDF / JSON-LD)
+                                 ├──▶ Tavi           (compiled model)
+                                 └──▶ …
+```
+
+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.
+
+## Projections
+
+| Target | Status | Notes |
+| --- | --- | --- |
+| **holon** (`.holon.jsonld`) | shipped | RDF/JSON-LD, renders in the [Holon Viewer](https://holon.robosystems.ai/) |
+| **Tavi** (`.tavi.json`) | shipped | [Project Tavi](https://www.xbrl.org/Specification/tavi/PWD-2026-09-01/tavi-PWD-2026-09-01.html) compiled model, PWD-2026-09-01 |
+| OIM (xBRL-JSON / xBRL-CSV) | planned | Arelle already emits these; a native writer is a fidelity check on `XbrlModel` |
+| property graph / Parquet | planned | see `model.py` |
+
+Tavi is a **public working draft** and its name is explicitly a working title,
+so treat that projection as tracking a moving target. `--format tavi` also
+writes a `.tavi.gaps.json` sidecar recording what the filing carries that the
+model has nowhere to put — that file is the point of the projection, not a
+by-product of it.
+
+## Install
+
+### As a package
+
+```bash
+pip install xbrlkit
+```
+
+Exposes the `xbrlkit` CLI (`xbrlkit build …`, `xbrlkit fetch …`, `xbrlkit query …`)
+and the library — use this to consume it from another project. Set your SEC
+User-Agent via the environment (see [SEC User-Agent](#sec-user-agent)).
+
+### From source (development)
+
+```bash
+# Install the toolchain
+brew install uv just
+
+# Install dependencies and provision .env from the template
+just install
+```
+
+`just install` creates `.env` from `.env.example` on first run — then set your
+SEC User-Agent in it.
+
+## SEC User-Agent
+
+SEC EDGAR requires a descriptive `User-Agent` on every request, or it throttles
+you (empty responses / HTTP 429). `just install` already created your `.env` —
+set your details there:
+
+```bash
+# .env
+SEC_GOV_USER_AGENT="Your Name your@email.com"
+```
+
+`.env` is loaded automatically by every command. Outside the `just` workflow,
+`export SEC_GOV_USER_AGENT="Your Name your@email.com"` or pass `--user-agent`.
+
+## Usage
+
+```bash
+# Build a holon.jsonld from a specific filing (-> ./output/)
+xbrlkit build --cik 320193 --accno 0000320193-23-000106
+
+# Fetch the latest filing for a ticker (-> ./output/)
+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
+```
+
+From a source checkout, `just` wraps the same CLI as a shorthand:
+`just build 320193 0000320193-23-000106` and `just fetch NVDA`.
+
+## View & explore
+
+Built holons render in the **RoboSystems Holon Viewer** — a browser-based reader
+that renders the financial statements and lets you ask questions of the report
+with AI:
+
+- **Hosted:** <https://holon.robosystems.ai/> — open a `holon.jsonld` and explore
+  the statements, notes, and dimensional facts, or chat with the report.
+- **Source:** <https://github.com/RoboFinSystems/robosystems-holon-viewer> — run
+  it locally or self-host.
+
+The viewer reads a holon entirely client-side, so a single `holon.jsonld` is a
+complete, portable, self-describing report.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+MIT © 2026 RFS LLC

xbrlkit-0.2.0/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "xbrlkit"
+version = "0.2.0"
+description = "Work with XBRL filings above Arelle: one parse, portable models"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "RFS LLC"},
+]
+license = {text = "MIT"}
+keywords = ["xbrl", "sec", "edgar", "financial", "arelle", "tavi", "oim", "holon", "jsonld", "rdf"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Framework :: Pydantic",
+    "Framework :: Pydantic :: 2",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "arelle-release",
+    "httpx>=0.28",
+    "pydantic>=2.11",
+    "python-dotenv>=1.0",
+    "rdflib",
+    "pyshacl",
+    "requests>=2.31",
+    # Required by the vendored EDGAR ixt-sec transform registry
+    # (_vendor/arelle_plugins/EDGAR/transform).
+    "regex",
+]
+
+[project.optional-dependencies]
+dev = [
+    "basedpyright>=1.21",
+    "ruff>=0.12",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.26",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+xbrlkit = "xbrlkit.cli:main"
+
+[project.urls]
+Repository = "https://github.com/RoboFinSystems/xbrlkit"
+Homepage = "https://github.com/RoboFinSystems/xbrlkit#readme"
+"Bug Tracker" = "https://github.com/RoboFinSystems/xbrlkit/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["xbrlkit"]
+
+# Keep internal dev tooling out of the sdist uploaded to PyPI. Hatchling
+# defaults to "everything not in .gitignore", which would drag along
+# `.claude/`, `.vscode/`, `.githooks/`, and other repo-local config. The
+# wheel target above is unaffected — it only includes the package dir.
+[tool.hatch.build.targets.sdist]
+include = [
+    "/xbrlkit",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+    "/pytest.ini",
+    "/ruff.toml",
+]
+
+[tool.basedpyright]
+include = ["xbrlkit"]
+exclude = ["tests", "xbrlkit/serialize/_kernel", "xbrlkit/_vendor"]
+extraPaths = ["."]
+pythonVersion = "3.13"
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "standard"
+reportAttributeAccessIssue = "none"
+reportArgumentType = "none"
+reportGeneralTypeIssues = "none"
+reportOptionalMemberAccess = "none"
+reportReturnType = "none"
+reportInvalidTypeForm = "none"
+reportMissingImports = "none"

xbrlkit-0.2.0/pytest.ini

@@ -0,0 +1,21 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+
+markers =
+    integration: marks integration tests
+    unit: marks unit tests
+    asyncio: marks tests that use asyncio
+
+# Configure test output
+console_output_style = progress
+log_cli = true
+log_cli_level = INFO
+log_cli_format = %(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)
+log_cli_date_format = %Y-%m-%d %H:%M:%S
+
+# Configure asyncio
+asyncio_mode = strict
+asyncio_default_fixture_loop_scope = function

xbrlkit-0.2.0/ruff.toml

@@ -0,0 +1,47 @@
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+    "xbrlkit/serialize/_kernel",
+    "xbrlkit/_vendor",
+]
+
+line-length = 88
+indent-width = 2
+target-version = "py311"
+
+[lint]
+select = ["E4", "E7", "E9", "F"]
+ignore = []
+fixable = ["ALL"]
+unfixable = []
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"

xbrlkit-0.2.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Test package."""

xbrlkit-0.2.0/tests/conftest.py

@@ -0,0 +1,13 @@
+"""Shared pytest fixtures for the xbrlkit test suite."""
+
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def sample_output_dir(tmp_path: Path) -> Path:
+  """Return a temporary directory for tests that write output artifacts."""
+  out = tmp_path / "output"
+  out.mkdir()
+  return out

xbrlkit-0.2.0/tests/test_config.py

@@ -0,0 +1,51 @@
+"""The SEC User-Agent / ``.env`` config contract.
+
+The CLI calls ``load_dotenv()`` at startup and then builds a fresh ``Config``,
+so a ``SEC_GOV_USER_AGENT`` set in a local ``.env`` reaches the EDGAR client.
+These tests exercise that env -> ``Config`` path without any network access.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from xbrlkit.config import DEFAULT_USER_AGENT, Config
+
+
+def test_env_user_agent_overrides_default(monkeypatch):
+  monkeypatch.setenv("SEC_GOV_USER_AGENT", "Acme Corp ops@acme.com")
+  cfg = Config()
+  assert cfg.user_agent == "Acme Corp ops@acme.com"
+  assert cfg.headers["User-Agent"] == "Acme Corp ops@acme.com"
+
+
+def test_default_user_agent_when_unset(monkeypatch):
+  monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
+  assert Config().user_agent == DEFAULT_USER_AGENT
+
+
+def test_dotenv_file_populates_config(tmp_path):
+  """A ``.env`` loaded via ``load_dotenv`` flows into a fresh ``Config``."""
+  # load_dotenv mutates os.environ directly, so save/restore around it rather
+  # than relying on monkeypatch (which can't unwind that external mutation).
+  original = os.environ.pop("SEC_GOV_USER_AGENT", None)
+  try:
+    env = tmp_path / ".env"
+    env.write_text('SEC_GOV_USER_AGENT="Dotenv User dev@example.com"\n')
+    load_dotenv(dotenv_path=env, override=True)
+    assert Config().user_agent == "Dotenv User dev@example.com"
+  finally:
+    if original is None:
+      os.environ.pop("SEC_GOV_USER_AGENT", None)
+    else:
+      os.environ["SEC_GOV_USER_AGENT"] = original
+
+
+def test_env_example_template_is_tracked_and_documents_user_agent():
+  """The tracked template must survive the ``.env*`` gitignore un-ignore."""
+  example = Path(__file__).resolve().parent.parent / ".env.example"
+  assert example.exists()
+  assert "SEC_GOV_USER_AGENT" in example.read_text()