xbrlkit 0.7.2__tar.gz → 0.7.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/PKG-INFO +62 -10
  2. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/README.md +61 -9
  3. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/pyproject.toml +1 -1
  4. xbrlkit-0.7.4/tests/conftest.py +25 -0
  5. xbrlkit-0.7.4/tests/test_config.py +117 -0
  6. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_serialize.py +31 -0
  7. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_serve.py +35 -0
  8. xbrlkit-0.7.4/xbrlkit/config.py +154 -0
  9. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/deserialize/holon.py +4 -0
  10. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/client.py +1 -1
  11. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/efts.py +1 -1
  12. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/context.py +6 -2
  13. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/graph.py +8 -4
  14. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/server.py +41 -1
  15. xbrlkit-0.7.2/tests/conftest.py +0 -13
  16. xbrlkit-0.7.2/tests/test_config.py +0 -51
  17. xbrlkit-0.7.2/xbrlkit/config.py +0 -68
  18. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/.gitignore +0 -0
  19. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/LICENSE +0 -0
  20. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/pytest.ini +0 -0
  21. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/ruff.toml +0 -0
  22. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/__init__.py +0 -0
  23. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_arelle_cache.py +0 -0
  24. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_deserialize.py +0 -0
  25. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_documents.py +0 -0
  26. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_edgar.py +0 -0
  27. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_efts.py +0 -0
  28. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_lpg.py +0 -0
  29. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_oim.py +0 -0
  30. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_parity.py +0 -0
  31. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_parse.py +0 -0
  32. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_query.py +0 -0
  33. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_tavi.py +0 -0
  34. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_text_ixbrl.py +0 -0
  35. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_text_narrative.py +0 -0
  36. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_text_parts.py +0 -0
  37. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/tests/test_text_tables.py +0 -0
  38. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/__init__.py +0 -0
  39. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/__init__.py +0 -0
  40. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/__init__.py +0 -0
  41. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/README.md +0 -0
  42. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/extractTestcase.sh +0 -0
  43. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/extractTestcase.xsl +0 -0
  44. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/runIxtSecTests.sh +0 -0
  45. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/saxon9.jar +0 -0
  46. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/testcase.xml +0 -0
  47. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/tests.xml +0 -0
  48. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/conf/tests.xsd +0 -0
  49. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/text2num.py +0 -0
  50. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-boolballotbox.xml +0 -0
  51. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-countrynameen.xml +0 -0
  52. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-datequarterend.xml +0 -0
  53. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durday.xml +0 -0
  54. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durhour.xml +0 -0
  55. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durmonth.xml +0 -0
  56. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durweek.xml +0 -0
  57. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-durwordsen.xml +0 -0
  58. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-duryear.xml +0 -0
  59. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-edgarprovcountryen.xml +0 -0
  60. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-entityfilercategoryen.xml +0 -0
  61. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-exchnameen.xml +0 -0
  62. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-numwordsen.xml +0 -0
  63. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-stateprovnameen.xml +0 -0
  64. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/ixt-sec-yesnoballotbox.xml +0 -0
  65. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/registry/transform-registry.xml +0 -0
  66. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/arelle_plugins/EDGAR/transform/transformationRegistry/schema/inlinexbrl-sec-transformation.xsd +0 -0
  67. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/ontology/v1/context.jsonld +0 -0
  68. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/_vendor/ontology/v1/shapes.ttl +0 -0
  69. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/cli.py +0 -0
  70. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/deserialize/README.md +0 -0
  71. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/deserialize/__init__.py +0 -0
  72. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/deserialize/tavi.py +0 -0
  73. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/README.md +0 -0
  74. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/__init__.py +0 -0
  75. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/download.py +0 -0
  76. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/filing_index.py +0 -0
  77. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/rate_limit.py +0 -0
  78. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/edgar/submission.py +0 -0
  79. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/filings_org/README.md +0 -0
  80. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/filings_org/__init__.py +0 -0
  81. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/filings_org/client.py +0 -0
  82. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/filings_org/download.py +0 -0
  83. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/model.py +0 -0
  84. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/namespaces.py +0 -0
  85. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/README.md +0 -0
  86. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/__init__.py +0 -0
  87. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/arelle_load.py +0 -0
  88. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/cache.py +0 -0
  89. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/ids.py +0 -0
  90. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/parse/to_model.py +0 -0
  91. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/periods.py +0 -0
  92. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/py.typed +0 -0
  93. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/query.py +0 -0
  94. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/schema/__init__.py +0 -0
  95. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/README.md +0 -0
  96. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/__init__.py +0 -0
  97. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/__init__.py +0 -0
  98. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/bundle.py +0 -0
  99. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/holon.py +0 -0
  100. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_kernel/jsonld.py +0 -0
  101. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/_values.py +0 -0
  102. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/classify.py +0 -0
  103. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/holon.py +0 -0
  104. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/lpg.py +0 -0
  105. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/oim.py +0 -0
  106. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serialize/tavi.py +0 -0
  107. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/README.md +0 -0
  108. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/__init__.py +0 -0
  109. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/session.py +0 -0
  110. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/serve/tools.py +0 -0
  111. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/README.md +0 -0
  112. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/__init__.py +0 -0
  113. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/ixbrl.py +0 -0
  114. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/narrative.py +0 -0
  115. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/parts.py +0 -0
  116. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/tables.py +0 -0
  117. {xbrlkit-0.7.2 → xbrlkit-0.7.4}/xbrlkit/text/xml.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: xbrlkit
3
- Version: 0.7.2
3
+ Version: 0.7.4
4
4
  Summary: Work with XBRL filings above Arelle: one parse, portable models
5
5
  Project-URL: Repository, https://github.com/RoboFinSystems/xbrlkit
6
6
  Project-URL: Homepage, https://github.com/RoboFinSystems/xbrlkit#readme
@@ -125,19 +125,29 @@ just install # dependencies, and .env from the template
125
125
 
126
126
  ### SEC User-Agent
127
127
 
128
- SEC EDGAR requires a descriptive `User-Agent` on every request, or it throttles
129
- you (empty responses / HTTP 429). `just install` already created your `.env` —
130
- set your details there:
128
+ SEC fair access asks for a `User-Agent` identifying you with contact info.
129
+ EDGAR works out of the box under a default that names the project, and the
130
+ first unattributed fetch says so once — SEC rate limits per IP, so the shared
131
+ default costs nobody else their budget. Identifying yourself is a courtesy,
132
+ and one worth extending. `just install` already created your `.env`:
131
133
 
132
134
  ```bash
133
135
  # .env
134
136
  SEC_GOV_USER_AGENT="Your Name your@email.com"
135
137
  ```
136
138
 
137
- `.env` is loaded automatically by every command. Outside the `just` workflow,
138
- `export SEC_GOV_USER_AGENT=…` or pass `--user-agent`. Nothing outside EDGAR
139
+ `.env` is loaded automatically by every command **run from a checkout of this
140
+ repo** — the lookup is relative to the installed code, not your working
141
+ directory, so a `uvx` or `pip` install never picks one up. There, use
142
+ `export SEC_GOV_USER_AGENT=…`, `--user-agent`, or an MCP `env` block (see
143
+ [Serve to an MCP client](#serve-to-an-mcp-client)). Nothing outside EDGAR
139
144
  needs it — a local file, a JSON report and filings.xbrl.org all load without.
140
145
 
146
+ > **Do not put a GitHub URL in it.** EDGAR answers `403` to any `User-Agent`
147
+ > containing `github.com`, whatever else the header says, and the failure
148
+ > looks like a permissions problem rather than a header problem. A name and
149
+ > an email is the shape that works.
150
+
141
151
  ## Usage
142
152
 
143
153
  ```bash
@@ -172,20 +182,62 @@ model = from_holon_json(holon) # and back again
172
182
 
173
183
  ## Serve to an MCP client
174
184
 
185
+ Two ways to run it. They differ in which process does the fetching, and so in
186
+ where your SEC identity goes.
187
+
188
+ **stdio — the client launches the server.** The identity belongs in the
189
+ server's own `env` block:
190
+
191
+ ```json
192
+ {
193
+ "mcpServers": {
194
+ "xbrlkit": {
195
+ "command": "uvx",
196
+ "args": [
197
+ "--from", "xbrlkit[mcp]@latest",
198
+ "xbrlkit", "serve", "--transport", "stdio"
199
+ ],
200
+ "env": { "SEC_GOV_USER_AGENT": "Your Name you@example.com" }
201
+ }
202
+ }
203
+ }
204
+ ```
205
+
206
+ **HTTP — you start the server, the client only points at a URL.** An `env`
207
+ block in the client config would reach nothing here; set it on the command:
208
+
175
209
  ```bash
176
210
  pip install "xbrlkit[mcp]"
177
- xbrlkit serve
211
+ SEC_GOV_USER_AGENT="Your Name you@example.com" xbrlkit serve
178
212
  # → MCP at http://127.0.0.1:8765/mcp
179
213
 
180
- claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp
214
+ # or without installing anything
215
+ SEC_GOV_USER_AGENT="Your Name you@example.com" \
216
+ uvx --from "xbrlkit[mcp]@latest" xbrlkit serve
181
217
  ```
182
218
 
183
- Or without installing anything:
219
+ ```json
220
+ {
221
+ "mcpServers": {
222
+ "xbrlkit": { "type": "http", "url": "http://127.0.0.1:8765/mcp" }
223
+ }
224
+ }
225
+ ```
226
+
227
+ or, equivalently:
184
228
 
185
229
  ```bash
186
- uvx --from "xbrlkit[mcp]@latest" xbrlkit serve
230
+ claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp
187
231
  ```
188
232
 
233
+ A `.env` file is **not** a channel for either of these. The lookup is relative
234
+ to the installed code rather than your working directory, so it resolves only
235
+ inside a checkout of this repo — a `uvx` or `pip` install never sees one. Use
236
+ the environment, the `env` block, or `--user-agent`.
237
+
238
+ Both are optional: EDGAR works unattributed under the default, saying so once.
239
+ And filings.xbrl.org, local packages and Tavi/holon JSON need no identity at all.
240
+
189
241
  Then load filings from the chat — a ticker, an EDGAR `cik:accession`, a
190
242
  `lei:`, a local package, or a holon or Tavi by path or URL — and ask for
191
243
  statements, facts by concept and period, calculations, exhibits and text.
@@ -69,19 +69,29 @@ just install # dependencies, and .env from the template
69
69
 
70
70
  ### SEC User-Agent
71
71
 
72
- SEC EDGAR requires a descriptive `User-Agent` on every request, or it throttles
73
- you (empty responses / HTTP 429). `just install` already created your `.env` —
74
- set your details there:
72
+ SEC fair access asks for a `User-Agent` identifying you with contact info.
73
+ EDGAR works out of the box under a default that names the project, and the
74
+ first unattributed fetch says so once — SEC rate limits per IP, so the shared
75
+ default costs nobody else their budget. Identifying yourself is a courtesy,
76
+ and one worth extending. `just install` already created your `.env`:
75
77
 
76
78
  ```bash
77
79
  # .env
78
80
  SEC_GOV_USER_AGENT="Your Name your@email.com"
79
81
  ```
80
82
 
81
- `.env` is loaded automatically by every command. Outside the `just` workflow,
82
- `export SEC_GOV_USER_AGENT=…` or pass `--user-agent`. Nothing outside EDGAR
83
+ `.env` is loaded automatically by every command **run from a checkout of this
84
+ repo** — the lookup is relative to the installed code, not your working
85
+ directory, so a `uvx` or `pip` install never picks one up. There, use
86
+ `export SEC_GOV_USER_AGENT=…`, `--user-agent`, or an MCP `env` block (see
87
+ [Serve to an MCP client](#serve-to-an-mcp-client)). Nothing outside EDGAR
83
88
  needs it — a local file, a JSON report and filings.xbrl.org all load without.
84
89
 
90
+ > **Do not put a GitHub URL in it.** EDGAR answers `403` to any `User-Agent`
91
+ > containing `github.com`, whatever else the header says, and the failure
92
+ > looks like a permissions problem rather than a header problem. A name and
93
+ > an email is the shape that works.
94
+
85
95
  ## Usage
86
96
 
87
97
  ```bash
@@ -116,20 +126,62 @@ model = from_holon_json(holon) # and back again
116
126
 
117
127
  ## Serve to an MCP client
118
128
 
129
+ Two ways to run it. They differ in which process does the fetching, and so in
130
+ where your SEC identity goes.
131
+
132
+ **stdio — the client launches the server.** The identity belongs in the
133
+ server's own `env` block:
134
+
135
+ ```json
136
+ {
137
+ "mcpServers": {
138
+ "xbrlkit": {
139
+ "command": "uvx",
140
+ "args": [
141
+ "--from", "xbrlkit[mcp]@latest",
142
+ "xbrlkit", "serve", "--transport", "stdio"
143
+ ],
144
+ "env": { "SEC_GOV_USER_AGENT": "Your Name you@example.com" }
145
+ }
146
+ }
147
+ }
148
+ ```
149
+
150
+ **HTTP — you start the server, the client only points at a URL.** An `env`
151
+ block in the client config would reach nothing here; set it on the command:
152
+
119
153
  ```bash
120
154
  pip install "xbrlkit[mcp]"
121
- xbrlkit serve
155
+ SEC_GOV_USER_AGENT="Your Name you@example.com" xbrlkit serve
122
156
  # → MCP at http://127.0.0.1:8765/mcp
123
157
 
124
- claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp
158
+ # or without installing anything
159
+ SEC_GOV_USER_AGENT="Your Name you@example.com" \
160
+ uvx --from "xbrlkit[mcp]@latest" xbrlkit serve
125
161
  ```
126
162
 
127
- Or without installing anything:
163
+ ```json
164
+ {
165
+ "mcpServers": {
166
+ "xbrlkit": { "type": "http", "url": "http://127.0.0.1:8765/mcp" }
167
+ }
168
+ }
169
+ ```
170
+
171
+ or, equivalently:
128
172
 
129
173
  ```bash
130
- uvx --from "xbrlkit[mcp]@latest" xbrlkit serve
174
+ claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp
131
175
  ```
132
176
 
177
+ A `.env` file is **not** a channel for either of these. The lookup is relative
178
+ to the installed code rather than your working directory, so it resolves only
179
+ inside a checkout of this repo — a `uvx` or `pip` install never sees one. Use
180
+ the environment, the `env` block, or `--user-agent`.
181
+
182
+ Both are optional: EDGAR works unattributed under the default, saying so once.
183
+ And filings.xbrl.org, local packages and Tavi/holon JSON need no identity at all.
184
+
133
185
  Then load filings from the chat — a ticker, an EDGAR `cik:accession`, a
134
186
  `lei:`, a local package, or a holon or Tavi by path or URL — and ask for
135
187
  statements, facts by concept and period, calculations, exhibits and text.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "xbrlkit"
3
- version = "0.7.2"
3
+ version = "0.7.4"
4
4
  description = "Work with XBRL filings above Arelle: one parse, portable models"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -0,0 +1,25 @@
1
+ """Shared pytest fixtures for the xbrlkit test suite."""
2
+
3
+ from pathlib import Path
4
+
5
+ import pytest
6
+
7
+
8
+ @pytest.fixture
9
+ def sample_output_dir(tmp_path: Path) -> Path:
10
+ """Return a temporary directory for tests that write output artifacts."""
11
+ out = tmp_path / "output"
12
+ out.mkdir()
13
+ return out
14
+
15
+
16
+ @pytest.fixture(autouse=True)
17
+ def declared_sec_identity(monkeypatch):
18
+ """Give every test a SEC identity of its own.
19
+
20
+ The EDGAR and EFTS clients refuse to start without one. Setting a fixed
21
+ test value here keeps the suite hermetic: it neither depends on the
22
+ developer's ``SEC_GOV_USER_AGENT`` nor sends their address anywhere. Tests
23
+ that exercise the absent case delete it themselves.
24
+ """
25
+ monkeypatch.setenv("SEC_GOV_USER_AGENT", "xbrlkit tests tests@example.com")
@@ -0,0 +1,117 @@
1
+ """The SEC User-Agent / ``.env`` config contract.
2
+
3
+ The CLI calls ``load_dotenv()`` at startup and then builds a fresh ``Config``,
4
+ so a ``SEC_GOV_USER_AGENT`` set in a local ``.env`` reaches the EDGAR client.
5
+ These tests exercise that env -> ``Config`` path without any network access.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ from pathlib import Path
12
+
13
+ from dotenv import load_dotenv
14
+
15
+ import pytest
16
+
17
+ import xbrlkit.config as config_module
18
+ from xbrlkit.config import DEFAULT_USER_AGENT, Config
19
+
20
+
21
+ def test_env_user_agent_overrides_default(monkeypatch):
22
+ monkeypatch.setenv("SEC_GOV_USER_AGENT", "Acme Corp ops@acme.com")
23
+ cfg = Config()
24
+ assert cfg.user_agent == "Acme Corp ops@acme.com"
25
+ assert cfg.headers["User-Agent"] == "Acme Corp ops@acme.com"
26
+
27
+
28
+ def test_no_identity_when_unset(monkeypatch):
29
+ """Unset means unset — the config never invents an identity."""
30
+ monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
31
+ assert Config().user_agent is None
32
+
33
+
34
+ def test_generic_headers_name_the_software_not_an_operator(monkeypatch):
35
+ """Every host gets a default whose address is reserved, so it reaches nobody."""
36
+ monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
37
+ agent = Config().headers["User-Agent"]
38
+ assert agent == DEFAULT_USER_AGENT
39
+ assert agent.endswith("@example.com")
40
+
41
+
42
+ def test_sec_headers_fall_back_to_the_default(monkeypatch):
43
+ """EDGAR still works undeclared — the default is a courtesy, not a gate."""
44
+ monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
45
+ monkeypatch.setattr(config_module, "_warned_undeclared", False)
46
+ assert Config().sec_headers == {"User-Agent": DEFAULT_USER_AGENT}
47
+
48
+
49
+ @pytest.mark.parametrize("blank", ["", " "])
50
+ def test_a_blank_identity_is_no_identity(monkeypatch, blank):
51
+ monkeypatch.setenv("SEC_GOV_USER_AGENT", blank)
52
+ monkeypatch.setattr(config_module, "_warned_undeclared", False)
53
+ assert Config().sec_headers == {"User-Agent": DEFAULT_USER_AGENT}
54
+
55
+
56
+ def test_undeclared_identity_warns_exactly_once(monkeypatch, caplog):
57
+ """Behind every EDGAR request, so a repeat per call would be pure noise."""
58
+ monkeypatch.delenv("SEC_GOV_USER_AGENT", raising=False)
59
+ monkeypatch.setattr(config_module, "_warned_undeclared", False)
60
+ cfg = Config()
61
+ with caplog.at_level("WARNING", logger="xbrlkit.config"):
62
+ for _ in range(3):
63
+ cfg.sec_headers
64
+ warnings = [r for r in caplog.records if "SEC_GOV_USER_AGENT" in r.getMessage()]
65
+ assert len(warnings) == 1
66
+
67
+
68
+ def test_a_declared_identity_never_warns(monkeypatch, caplog):
69
+ monkeypatch.setenv("SEC_GOV_USER_AGENT", "Acme Corp ops@acme.com")
70
+ monkeypatch.setattr(config_module, "_warned_undeclared", False)
71
+ with caplog.at_level("WARNING", logger="xbrlkit.config"):
72
+ Config().sec_headers
73
+ assert not caplog.records
74
+
75
+
76
+ def test_sec_headers_pass_a_declared_identity_through(monkeypatch):
77
+ monkeypatch.setenv("SEC_GOV_USER_AGENT", "Acme Corp ops@acme.com")
78
+ assert Config().sec_headers == {"User-Agent": "Acme Corp ops@acme.com"}
79
+
80
+
81
+ def test_dotenv_file_populates_config(tmp_path):
82
+ """A ``.env`` loaded via ``load_dotenv`` flows into a fresh ``Config``."""
83
+ # load_dotenv mutates os.environ directly, so save/restore around it rather
84
+ # than relying on monkeypatch (which can't unwind that external mutation).
85
+ original = os.environ.pop("SEC_GOV_USER_AGENT", None)
86
+ try:
87
+ env = tmp_path / ".env"
88
+ env.write_text('SEC_GOV_USER_AGENT="Dotenv User dev@example.com"\n')
89
+ load_dotenv(dotenv_path=env, override=True)
90
+ assert Config().user_agent == "Dotenv User dev@example.com"
91
+ finally:
92
+ if original is None:
93
+ os.environ.pop("SEC_GOV_USER_AGENT", None)
94
+ else:
95
+ os.environ["SEC_GOV_USER_AGENT"] = original
96
+
97
+
98
+ def test_env_example_template_is_tracked_and_documents_user_agent():
99
+ """The tracked template must survive the ``.env*`` gitignore un-ignore."""
100
+ example = Path(__file__).resolve().parent.parent / ".env.example"
101
+ assert example.exists()
102
+ assert "SEC_GOV_USER_AGENT" in example.read_text()
103
+
104
+
105
+ def test_default_identity_carries_no_personal_contact():
106
+ """The fallback names the project and a reserved address, nobody's inbox."""
107
+ assert DEFAULT_USER_AGENT == "xbrlkit xbrlkit@example.com"
108
+ assert "github.com" not in DEFAULT_USER_AGENT
109
+
110
+
111
+ def test_a_github_user_agent_warns(monkeypatch, caplog):
112
+ """EDGAR 403s any User-Agent mentioning github.com, with no hint why."""
113
+ monkeypatch.setenv("SEC_GOV_USER_AGENT", "xbrlkit (+https://github.com/acme/x)")
114
+ monkeypatch.setattr(config_module, "_warned_github", False)
115
+ with caplog.at_level("WARNING", logger="xbrlkit.config"):
116
+ Config().sec_headers
117
+ assert any("github.com" in r.getMessage() for r in caplog.records)
@@ -27,6 +27,7 @@ from xbrlkit.model import (
27
27
  )
28
28
  from rdflib import RDF
29
29
 
30
+ from xbrlkit.serialize._kernel import context
30
31
  from xbrlkit.serialize import (
31
32
  build_holon_graph,
32
33
  classify_network,
@@ -472,3 +473,33 @@ def test_holon_serialization_is_deterministic() -> None:
472
473
  if isinstance(entry, dict) and isinstance(entry.get("@graph"), list):
473
474
  ids = [n.get("@id", "") for n in entry["@graph"] if isinstance(n, dict)]
474
475
  assert ids == sorted(ids)
476
+
477
+
478
+ def test_the_canonical_context_declares_each_term_once() -> None:
479
+ """A repeated key in the context silently rebinds a term.
480
+
481
+ `serialize/_kernel/` is a vendored fork and is excluded from ruff, so F601 —
482
+ which is enabled and does catch this — never runs on it. That is how a second
483
+ `"label"` key shipped in 0.7.0 and shadowed `rdfs:label` with `rs:label`,
484
+ leaving one term meaning two predicates across two documents that both call
485
+ themselves holons. Lint cannot reach the file; this can.
486
+ """
487
+ import ast
488
+ from pathlib import Path
489
+
490
+ source = Path(context.__file__).read_text()
491
+ tree = ast.parse(source)
492
+ for node in ast.walk(tree):
493
+ if not isinstance(node, ast.Dict):
494
+ continue
495
+ keys = [k.value for k in node.keys if isinstance(k, ast.Constant)]
496
+ duplicates = {k for k in keys if keys.count(k) > 1}
497
+ assert not duplicates, f"repeated context keys: {sorted(duplicates)}"
498
+
499
+
500
+ def test_the_standard_label_term_does_not_shadow_rdfs_label() -> None:
501
+ """`label` is `rdfs:label` — the platform's holon context binds it that way
502
+ too, and the two must not disagree. XBRL's standard-role label is written
503
+ under its own name."""
504
+ assert context.CANONICAL_CONTEXT["label"] == "rdfs:label"
505
+ assert context.CANONICAL_CONTEXT["standardLabel"]["@id"].endswith("standardLabel")
@@ -13,6 +13,7 @@ from __future__ import annotations
13
13
 
14
14
  import json
15
15
  import os
16
+ import textwrap
16
17
  from datetime import date
17
18
  from pathlib import Path
18
19
 
@@ -1023,3 +1024,37 @@ def test_real_filing_round_trip() -> None:
1023
1024
  assert tools.search_text(lf, "item 7")["total"] > 0
1024
1025
  finally:
1025
1026
  session.close()
1027
+
1028
+
1029
+ class TestStartupBanner:
1030
+ """What ``xbrlkit serve`` tells the operator on the way up."""
1031
+
1032
+ def test_the_json_is_valid_and_tracks_the_live_url(self):
1033
+ """Built from the running url, so a non-default port stays copy-pasteable."""
1034
+ from xbrlkit.serve.server import startup_banner
1035
+
1036
+ url = "http://127.0.0.1:9000/mcp"
1037
+ banner = startup_banner(url, "Acme Corp ops@acme.com")
1038
+ block = banner[banner.index("{") : banner.rindex("}") + 1]
1039
+ parsed = json.loads(textwrap.dedent(block))
1040
+ assert parsed == {"mcpServers": {"xbrlkit": {"type": "http", "url": url}}}
1041
+
1042
+ def test_it_offers_the_claude_code_command(self):
1043
+ from xbrlkit.serve.server import startup_banner
1044
+
1045
+ banner = startup_banner("http://127.0.0.1:8765/mcp", None)
1046
+ assert "claude mcp add --transport http xbrlkit http://127.0.0.1:8765/mcp" in banner
1047
+
1048
+ def test_an_undeclared_identity_names_the_default_and_the_fix(self):
1049
+ from xbrlkit.config import DEFAULT_USER_AGENT
1050
+ from xbrlkit.serve.server import identity_lines
1051
+
1052
+ text = "\n".join(identity_lines(None))
1053
+ assert DEFAULT_USER_AGENT in text
1054
+ assert "SEC_GOV_USER_AGENT=" in text
1055
+
1056
+ def test_a_declared_identity_is_echoed_without_advice(self):
1057
+ from xbrlkit.serve.server import identity_lines
1058
+
1059
+ lines = identity_lines("Acme Corp ops@acme.com")
1060
+ assert lines == ["SEC identity: Acme Corp ops@acme.com"]
@@ -0,0 +1,154 @@
1
+ """Standalone configuration — replaces the robosystems ``config.env`` coupling.
2
+
3
+ The SEC adapter reads user-agent / base URLs / cache dirs from the platform's
4
+ central env config. This package is platform-free, so those settings live here
5
+ (env-overridable, or constructed explicitly by the CLI) instead.
6
+
7
+ SEC fair-access asks for a ``User-Agent`` that identifies you with contact
8
+ info. Set ``SEC_GOV_USER_AGENT`` (e.g. ``"Acme Corp ops@acme.com"``) and your
9
+ traffic is attributed to you. Leave it unset and EDGAR still works, under a
10
+ default that names the project: SEC rate limits per IP, so the shared string
11
+ costs no one else their budget. It is a courtesy worth extending anyway, so
12
+ the first unattributed EDGAR fetch of a process says so once, on stderr.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import logging
18
+ import os
19
+ from dataclasses import dataclass, field
20
+ from pathlib import Path
21
+
22
+ # The fallback identity: the project name and a placeholder address, carrying
23
+ # nobody's real contact details — a default holding a person's address would
24
+ # put it on every install's traffic. ``example.com`` is reserved (RFC 2606),
25
+ # so it can never reach a stranger's inbox. Reaching a real one is what
26
+ # SEC_GOV_USER_AGENT is for, and the warning below asks for it.
27
+ #
28
+ # Deliberately no repository URL: EDGAR answers 403 to any User-Agent
29
+ # containing "github.com" (see GITHUB_UA_HELP), whatever else it says.
30
+ DEFAULT_USER_AGENT = "xbrlkit xbrlkit@example.com"
31
+
32
+ GITHUB_UA_HELP = (
33
+ "SEC_GOV_USER_AGENT contains 'github.com', which EDGAR refuses with HTTP "
34
+ "403 no matter what else the header says. Use a name and email instead, "
35
+ "e.g. 'Acme Corp ops@acme.com'."
36
+ )
37
+
38
+ SEC_IDENTITY_HELP = (
39
+ "xbrlkit is fetching from sec.gov under its default User-Agent. SEC fair "
40
+ "access asks you to identify yourself with contact info; set "
41
+ "SEC_GOV_USER_AGENT to a name and email you control:\n"
42
+ " export SEC_GOV_USER_AGENT='Acme Corp ops@acme.com'\n"
43
+ "or pass --user-agent. For an MCP client the server's own env block carries "
44
+ "it; see the README. Nothing outside EDGAR needs it."
45
+ )
46
+
47
+
48
+ def _default_cache_dir() -> Path:
49
+ override = os.environ.get("XBRL_HOLON_CACHE_DIR")
50
+ if override:
51
+ return Path(override)
52
+ return Path.home() / ".cache" / "xbrlkit"
53
+
54
+
55
+ @dataclass(frozen=True)
56
+ class Config:
57
+ """Runtime settings. Immutable; the CLI builds one per invocation."""
58
+
59
+ # The operator's own identity, or ``None`` until they declare one. Only the
60
+ # SEC clients care; everything else is happy with the default.
61
+ user_agent: str | None = field(
62
+ default_factory=lambda: os.environ.get("SEC_GOV_USER_AGENT") or None
63
+ )
64
+ sec_base_url: str = "https://www.sec.gov"
65
+ sec_data_url: str = "https://data.sec.gov"
66
+ # XBRL International's public index of filings outside EDGAR — ESEF and the
67
+ # national regimes that publish through it. Open, and it asks for no key.
68
+ filings_base_url: str = "https://filings.xbrl.org"
69
+ request_timeout: int = 30
70
+ rate_limit_per_sec: float = 5.0
71
+ # EDGAR answers a throttled client with an empty 200 as often as a 429;
72
+ # this is the wait before the one retry either gets.
73
+ throttle_backoff_s: float = field(
74
+ default_factory=lambda: float(os.environ.get("XBRLKIT_THROTTLE_BACKOFF", "45"))
75
+ )
76
+ cache_dir: Path = field(default_factory=_default_cache_dir)
77
+ # Arelle's DTS fetches: per-fetch timeout, and whether to fetch at all.
78
+ arelle_timeout: int = field(
79
+ default_factory=lambda: int(os.environ.get("XBRLKIT_ARELLE_TIMEOUT", "30"))
80
+ )
81
+ arelle_offline: bool = field(
82
+ default_factory=lambda: (
83
+ os.environ.get("XBRLKIT_ARELLE_OFFLINE", "").lower() in ("1", "true", "yes")
84
+ )
85
+ )
86
+
87
+ @property
88
+ def arelle_cache_dir(self) -> Path:
89
+ override = os.environ.get("XBRLKIT_ARELLE_CACHE_DIR")
90
+ return Path(override) if override else self.cache_dir / "arelle"
91
+
92
+ def identity(self) -> str | None:
93
+ """The declared identity, or ``None``.
94
+
95
+ Falls back to the environment so an identity set after this config was
96
+ built still counts — the module-level ``CONFIG`` is created at import,
97
+ which is often before a host has loaded its env.
98
+ """
99
+ declared = self.user_agent or os.environ.get("SEC_GOV_USER_AGENT")
100
+ if not declared or not declared.strip():
101
+ return None
102
+ declared = declared.strip()
103
+ if "github.com" in declared.lower():
104
+ warn_github_user_agent()
105
+ return declared
106
+
107
+ @property
108
+ def headers(self) -> dict[str, str]:
109
+ """Headers for hosts that require no declared identity."""
110
+ return {"User-Agent": self.identity() or DEFAULT_USER_AGENT}
111
+
112
+ @property
113
+ def sec_headers(self) -> dict[str, str]:
114
+ """Headers for sec.gov, warning once when no identity has been declared."""
115
+ identity = self.identity()
116
+ if identity is None:
117
+ warn_undeclared_sec_identity()
118
+ return {"User-Agent": DEFAULT_USER_AGENT}
119
+ return {"User-Agent": identity}
120
+
121
+
122
+ CONFIG = Config()
123
+
124
+
125
+ logger = logging.getLogger(__name__)
126
+ _warned_undeclared = False
127
+
128
+
129
+ def warn_undeclared_sec_identity() -> None:
130
+ """Say once per process that EDGAR is being fetched unattributed.
131
+
132
+ Once, because this sits behind every EDGAR request and a warning repeated a
133
+ few hundred times through a corpus run is noise the reader learns to skip.
134
+ """
135
+ global _warned_undeclared
136
+ if _warned_undeclared:
137
+ return
138
+ _warned_undeclared = True
139
+ logger.warning("%s", SEC_IDENTITY_HELP)
140
+
141
+
142
+ _warned_github = False
143
+
144
+
145
+ def warn_github_user_agent() -> None:
146
+ """Say once that a github.com User-Agent is refused by EDGAR.
147
+
148
+ The failure is otherwise a bare 403 with nothing pointing at the header.
149
+ """
150
+ global _warned_github
151
+ if _warned_github:
152
+ return
153
+ _warned_github = True
154
+ logger.warning("%s", GITHUB_UA_HELP)
@@ -81,6 +81,10 @@ LABEL_TERM_ROLES: dict[str, str] = {
81
81
  label_type.split(":", 1)[-1]: role for role, label_type in LABEL_ROLE_TYPES.items()
82
82
  }
83
83
  STANDARD_LABEL_ROLE_URI = "http://www.xbrl.org/2003/role/label"
84
+ # The emitter names the standard-role label `standardLabel`; `label` is read as
85
+ # well, because holons written by 0.7.0-0.7.2 used it.
86
+ LABEL_TERM_ROLES["standardLabel"] = STANDARD_LABEL_ROLE_URI
87
+ LABEL_TERM_ROLES["label"] = STANDARD_LABEL_ROLE_URI
84
88
  DOCUMENTATION_LABEL_ROLE = "http://www.xbrl.org/2003/role/documentation"
85
89
 
86
90
  PARENT_CHILD_ARCROLE = "http://www.xbrl.org/2003/arcrole/parent-child"
@@ -83,7 +83,7 @@ class EdgarClient:
83
83
  def __init__(self, config: Config = CONFIG) -> None:
84
84
  self.config: Config = config
85
85
  self._session: requests.Session = requests.Session()
86
- self._session.headers.update(config.headers)
86
+ self._session.headers.update(config.sec_headers)
87
87
  self._limiter: RateLimiter = RateLimiter(config.rate_limit_per_sec)
88
88
  self._ticker_map: dict[str, str] | None = None
89
89
 
@@ -82,7 +82,7 @@ class EftsClient:
82
82
  def __init__(self, config: Config = CONFIG, per_sec: float | None = None) -> None:
83
83
  self.config: Config = config
84
84
  self._session: requests.Session = requests.Session()
85
- self._session.headers.update(config.headers)
85
+ self._session.headers.update(config.sec_headers)
86
86
  self._limiter: RateLimiter = RateLimiter(
87
87
  config.rate_limit_per_sec if per_sec is None else per_sec
88
88
  )
@@ -140,8 +140,12 @@ CANONICAL_CONTEXT: dict = {
140
140
  "prefLabel": "skos:prefLabel",
141
141
  "documentation": "rdfs:comment",
142
142
  # The standard-role label, written beside `skos:prefLabel` because only
143
- # this one can carry the language the label was authored in.
144
- "label": {"@id": f"{RS_VOCAB}label"},
143
+ # this one can carry the language the label was authored in. Named
144
+ # `standardLabel` — XBRL's own name for the role — because `label` is bound
145
+ # to `rdfs:label` by the platform's holon context, and one key meaning two
146
+ # predicates across two documents that both call themselves holons is worse
147
+ # than a longer name.
148
+ "standardLabel": {"@id": f"{RS_VOCAB}standardLabel"},
145
149
  # Every other XBRL label role, one term each. A label is a literal with a
146
150
  # role, so it is one triple rather than a node: reifying them would add a
147
151
  # node per label, half again as many nodes as a report has.