xippios-comtrade 0.1.0__tar.gz

xippios_comtrade-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# environments and caches
+.venv/
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+
+# build artefacts
+dist/
+build/
+*.egg-info/
+
+# local secrets are never files, but belt and braces
+.env
+.env.*
+.envrc
+.envrc.*
+
+# editors
+.idea/
+.vscode/

xippios_comtrade-0.1.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/) (pre-1.0: breaking changes bump the minor).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-23
+
+### Added
+
+- Four task-shaped slices on `data/v1/get`, MCP tools `comtrade_get_bilateral_flows`,
+  `comtrade_get_commodity_series`, `comtrade_get_world_trade` and
+  `comtrade_get_top_partners`: `get_bilateral_flows(reporter, partner, commodities,
+  periods, flow)`, `get_commodity_series(reporter, commodity, flow, periods)` (partner
+  World, 12 periods per call, at most 120 periods, rows by period),
+  `get_world_trade(commodity, period, flow)` (every reporter, partner World, largest
+  first) and `get_top_partners(reporter, commodity, period, flow, n)` (every partner
+  ranked by `primary_value`, World dropped as the total, `n` in `meta.request`), each
+  with `cl_code="HS"` (EB*, BE and TM accepted but untested with `typeCode` C). Every
+  call pins `typeCode` C, `breakdownMode` classic, `partner2Code` 0, `motCode` 0,
+  `customsCode` C00 and `includeDesc` true (`params.SLICE_PINS`); rows are
+  `TradeFlowRecord`, a projection of `TradeDataRecord` under upstream names with the
+  `is_qty_estimated` and `is_net_wgt_estimated` flags. At TOTAL and chapter level the
+  recorded rows are mostly UNSD aggregates (`is_aggregate` true, `is_reported` false)
+  without a quantity. The slices are bounded by their arguments and make no count call;
+  a bound over 100,000 raises `QueryTooLarge` before the call (`bound=True`, kept on the
+  exception).
+- `params.validate_slice`: a reporter or partner as UN Comtrade's code or ISO alpha-3
+  (`"CHE"` is 757, `"USA"` as partner 842, `"W00"` World), resolved before the call;
+  periods of one format set `freqCode` (`YYYY` annual, `YYYYMM` monthly); a mix, an
+  unknown code, a level such as `AG2`, a wildcard or a period or product code named twice
+  is refused with the closest value.
+- `search` on `list_reporters`, `list_partners` and `list_commodities`: a case-insensitive
+  substring of the code, the ISO alpha-3 code (reporters, partners) or the text; it goes
+  into `meta.request`. The MCP result cap (200 rows or 64 KB) hides most of each list, so
+  the docstrings tell agents to search.
+- Six recorded fixtures under `tests/fixtures/get/` for the slices (bilateral annual and
+  monthly, the two calls of a 14-year series, world trade, every partner) and four live
+  smoke tests, one keyed call each.
+- `get_data_availability` on `data/v1/getDa`, `get_metadata` on `data/v1/getMetadata` and
+  `get_live_update` on `data/v1/getLiveUpdate`, MCP tools `comtrade_get_data_availability`,
+  `comtrade_get_metadata` and `comtrade_get_live_update`. Rows mirror the spec's schemas
+  under upstream names and carry their own dates (`first_released`/`last_released`,
+  `publication_date`, `started_at`/`completed_at`/`last_updated`/`queued_at`), typed;
+  `meta.published_at` stays `None`. `get_metadata` takes `reporter_code` and `period`,
+  which the spec omits and upstream honours. getLiveUpdate has no `publishedDate`; its
+  times are read without the process locale, and one that does not parse becomes `None`
+  for that field (only Released/Success rows were recorded).
+- Every `clCode` value and `flowCode`'s `XIF` rest on a recorded count
+  (`reference/clCode.json`, `flowCode.json`); `H6` answered HTTP 500 to all five tries.
+  The docstrings of `get_counts` and `get_data` say what the recorded answers established
+  for `breakdownMode` (default `plus`), `aggregateBy`, `includeDesc` and services totals.
+- `list_reporters` and `list_partners`, MCP tools `comtrade_list_reporters` and
+  `comtrade_list_partners`: UN Comtrade's `Reporters.json` (255 rows) and
+  `partnerAreas.json` (310 rows) as packaged with this version, every column under its
+  upstream name, without an upstream call; `meta.vintage` is the day they were fetched.
+- `list_commodities(cl_code)`, MCP tool `comtrade_list_commodities`: the product codes of
+  one classification from upstream's public `<clCode>.json` (no key, no quota), kept for
+  the process by core's GET cache on `reference_client` (`REFERENCE_CACHE`). `cl_code` is
+  checked against the 19 classifications with a file; `BE` and `TM` have none (HTTP 404).
+- Packaged tables `Reporters.csv`, `partnerAreas.csv`, `country_area_code_iso.csv` (UN
+  Comtrade's code to ISO alpha-3) and `TradeDataItems.csv`, written by
+  `scripts/refresh_reference.py` with upstream's columns, their provenance in
+  `reference/tables.json`; packaged lists `mosCode` (`ModeOfSupply.json`) and
+  `qtyUnitCode` (`QuantityUnits.json`) with the StrEnums `MosCode` and `QtyUnitCode`.
+- `api.reference_rows`: a reference file's rows as upstream sent them.
+- `scripts/refresh_reference.py --help` prints usage and fetches nothing. A list can carry
+  a `note`: `mosCode.json` and `MosCode` say they hold `ModeOfSupply.json`'s ids, not
+  proven parameter values (`data/v1/get` refused `Mode 1`).
+- Replay tests check the request that goes out carries the placeholder key, never the
+  shell's (ported from sdk-template).
+- `get_counts` and `get_data` on `data/v1/get/{typeCode}/{freqCode}/{clCode}`, MCP tools
+  `comtrade_get_counts` and `comtrade_get_data`. `get_data` counts first with
+  `countOnly`: zero returns an empty result without a second call, more than 100,000
+  records raises `QueryTooLarge` (an `InvalidRequestError`, HTTP 422) before any data
+  call, because upstream truncates silently at 100,000 rows (observed 2026-10-23).
+  Rows are `TradeDataRecord`, every field of upstream's schema, values and quantities as
+  `Decimal`.
+- Arguments are checked before any call (`params.validate_get`): coded parameters against
+  packaged lists, periods (at most 12) and product codes by shape.
+- Packaged lists `typeCode`, `freqCode`, `clCode`, `flowCode`, `customsCode`, `motCode`,
+  `aggregateBy`, `breakdownMode` in `reference/` with their origin, and the matching
+  StrEnums in `enums.py`, written by `scripts/refresh_reference.py` from the public
+  reference files (fetched without a key through `api.reference`) and the spec snapshot.
+  Where the spec documents more than a reference file, the script reconciles them and
+  records each exception with its evidence: `flowCode` adds the spec's `MIF` and `XIF`;
+  `clCode` adds the spec's `BE` and `TM`, which upstream accepted, and leaves out `BE5`,
+  which upstream refused.
+- `_client.classify`: an HTTP 400 `ErrorResponse` becomes `InvalidRequestError` with
+  upstream's message; a 403 that mentions a quota becomes `RateLimitError` (API
+  Management's text, not observed). The rate limit never bursts. The read
+  timeout is 180 s, since a broad count can take over a minute.
+- Fifteen recorded fixtures under `tests/fixtures/get/` and live smoke tests for both
+  tasks. Replay tests always send a placeholder key, whatever the shell holds.
+- Scaffold from [sdk-template](https://github.com/xippios/sdk-template): configured
+  client for UN Comtrade, empty task layer, MCP server and FastAPI router
+  wired to it, test harness, CI and publishing.
+- Upstream documentation snapshot in `docs/upstream/`: the five ApiDocs product specs
+  (OpenAPI: Public, Comtrade, Comtrade Tools, Comtrade Bulk, Comtrade Async), ten Help
+  Center articles as Markdown and two reference files, listed in `FETCHED.md`.
+  `.gitattributes` marks `docs/upstream/**` as `-text`, so git never converts the line
+  endings of the files kept byte for byte (the CRLF specs, one mixed-endings file).
+- `scripts/refresh_upstream.py`: regenerates the snapshot reproducibly, discovering the
+  ApiDocs products from the page's bundle (`uv run scripts/refresh_upstream.py`).
+
+### Changed
+
+- Calls are spaced 1.5 s apart (`RATE_LIMIT = RateLimit(per_minute=40, burst=1)`): at
+  exactly 1.0 s, 9 of 18 calls drew HTTP 429 "Rate limit is exceeded" (2026-10-23).
+- `reporter_code` is checked against the packaged `Reporters.csv`, `partner_code` and
+  `partner2_code` against `partnerAreas.csv`, each member of a comma-separated list. An
+  unknown code raises `InvalidRequestError` before any call, naming the same area's code
+  where `country_area_code_iso.json` knows it (`756` names `757`, Switzerland), or saying
+  that a code belongs to the other table (`0` World is a partner only). Upstream itself
+  answers a code that is no reporter with an empty result.
+- Template updated to sdk-template v0.1.5 (`/add-endpoint` asks for
+  `Field(validation_alias=...)`, not `alias=`; `/refresh-reference-data` formats the
+  regenerated `enums.py`; `/refresh-upstream` runs `scripts/refresh_upstream.py` where it
+  exists; `.gitignore` covers `.env.*` and `.envrc.*`; the MCP instructions name the
+  `comtrade_list_*` tools; `_client.__all__` exports `auth`). `.copier-answers.yml` now
+  records `rate_limit_per_minute: 40`, the limit `RATE_LIMIT` already applies.

xippios_comtrade-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

xippios_comtrade-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: xippios-comtrade
+Version: 0.1.0
+Summary: Typed client, MCP tools and HTTP routes for UN Comtrade
+Project-URL: Homepage, https://github.com/xippios/sdk-comtrade
+Project-URL: Upstream, https://comtradeplus.un.org
+Project-URL: Changelog, https://github.com/xippios/sdk-comtrade/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/xippios/sdk-comtrade/issues
+Author: XIPPIOS GmbH
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: comtrade,httpx,international-trade,mcp,pydantic,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: xippios-core>=0.1.0
+Provides-Extra: http
+Requires-Dist: xippios-core[http]>=0.1.0; extra == 'http'
+Provides-Extra: mcp
+Requires-Dist: xippios-core[mcp]>=0.1.0; extra == 'mcp'
+Provides-Extra: testing
+Requires-Dist: xippios-core[testing]>=0.1.0; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# xippios-comtrade
+
+Typed Python client, MCP server and FastAPI routes for
+[UN Comtrade](https://comtradeplus.un.org), part of the
+[xippios SDK family](https://github.com/xippios). Names and semantics follow the
+upstream documentation; every response carries release metadata (source, endpoint,
+retrieved_at, published_at, vintage).
+
+## Install
+
+```bash
+uv add xippios-comtrade            # client only
+uv add "xippios-comtrade[mcp]"     # + MCP server
+uv add "xippios-comtrade[http]"    # + FastAPI router
+```
+
+Set `COMTRADE_API_KEY` in the environment. Nothing is read from files.
+
+## 30-second example
+
+```python
+from xippios.comtrade import get_counts, get_data
+
+# Switzerland (reporter 757) exports to the World (partner 0) in 2023, all products.
+query = {
+    "reporter_code": "757",
+    "partner_code": "0",
+    "period": "2023",
+    "cmd_code": "TOTAL",
+    "flow_code": "X",
+}
+get_counts("C", "A", "HS", **query).data  # 32: every customs procedure and mode of transport
+result = get_data("C", "A", "HS", **query)
+total = next(r for r in result.data if (r.customs_code, r.mot_code) == ("C00", 0))
+total.primary_value  # Decimal('419922543423.509'); JSON: a number
+result.meta.endpoint, result.meta.request  # 'data/v1/get', the arguments above
+```
+
+Parameters are upstream's (`typeCode`, `reporterCode`, ...) in snake_case and take
+upstream's codes, several of them comma-separated as upstream takes them (`"757,842"`).
+Reporter and partner codes are UN Comtrade's, not ISO numeric: Switzerland is 757.
+Every argument is checked before the call: coded ones (`type_code`, `cl_code`,
+`flow_code`, `customs_code`, `mot_code`, `aggregate_by`, `breakdown_mode`) against
+the lists packaged from upstream's reference files and spec (`xippios.comtrade.enums`),
+`reporter_code` against the packaged copy of upstream's `Reporters.json`
+(`reference/Reporters.csv`) and `partner_code` and `partner2_code` against that of
+`partnerAreas.json`, the others by shape; a mistake raises
+`InvalidRequestError` naming the closest valid value (`756` names `757`, Switzerland).
+
+```python
+from xippios.comtrade import list_commodities, list_partners, list_reporters
+
+list_reporters().data  # 255 reporters, packaged with this version: no call
+list_reporters(search="switz").data  # code, ISO alpha-3 or name, any case: 757
+list_partners().data  # 310 partner areas, 0 World among them
+list_commodities("HS", search="coffee").data  # from 8,262 HS codes, fetched keyless once
+```
+
+Four task-shaped slices answer the common questions in one call each (the series in one
+call per 12 periods), at the total of every breakdown, one row per reporter × partner ×
+product code × period. Areas are UN Comtrade's codes or ISO alpha-3 codes; `YYYY` periods
+ask for annual data, `YYYYMM` for monthly:
+
+```python
+from xippios.comtrade import (
+    get_bilateral_flows,
+    get_commodity_series,
+    get_top_partners,
+    get_world_trade,
+)
+
+get_bilateral_flows("CHE", "USA", "TOTAL,27", "2022,2023", "X").data  # 4 rows
+years = ",".join(str(year) for year in range(2010, 2024))
+get_commodity_series("757", "27", "X", years).data  # 14 years, two calls, by period
+get_world_trade("27", "2023", "M").data[0].reporter_desc  # 'China': largest first
+[r.partner_desc for r in get_top_partners("CHE", "TOTAL", "2023", "X", 3).data]
+# ['USA', 'Germany', 'China']: World, the total, is dropped
+```
+
+Release dates are per dataset, so they sit on the rows, not in `meta.published_at`:
+
+```python
+from xippios.comtrade import get_data_availability, get_live_update, get_metadata
+
+[dataset] = get_data_availability("C", "A", "HS", reporter_code="757", period="2023").data
+dataset.first_released, dataset.last_released  # first publication and latest revision
+notes = get_metadata("C", "A", "HS", reporter_code="757", period="2023").data[0].notes
+[note.publication_date for note in notes]  # "New Data", then each "Revised Data"
+get_live_update().data  # the 50 most recent releases, newest first
+```
+
+`get_data` counts first with upstream's `countOnly`: a count of zero returns an empty
+result without a second call, and a count above 100,000 raises `QueryTooLarge` with the
+count before anything is fetched, because upstream would cut the answer at 100,000 rows
+without saying so. A free key allows 1 call per second and 500 calls per day, and
+`countOnly` calls count; the client spaces calls 1.5 s apart (upstream's gateway refuses
+some calls spaced exactly 1 s apart), the daily quota is yours to track.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "comtrade": {
+      "command": "uvx",
+      "args": ["--from", "xippios-comtrade[mcp]", "xippios-comtrade-mcp"],
+      "env": { "COMTRADE_API_KEY": "..." }
+    }
+  }
+}
+```
+
+Tools are read-only and named `comtrade_<verb>_<noun>`. Results are capped at
+200 rows or 64 KB with a note on how to narrow the query. Unfiltered,
+`comtrade_list_reporters`, `comtrade_list_partners` and `comtrade_list_commodities` show
+the first rows of their table only (200 of 255 reporters, in upstream's alphabetical
+order), so they take `search`: `{"search": "switz"}` returns 757 Switzerland. `--http`
+serves streamable HTTP instead of stdio.
+
+## Status
+
+| Upstream operation | Task function | MCP tool | Status |
+| --- | --- | --- | --- |
+| `data/v1/get/{typeCode}/{freqCode}/{clCode}` with `countOnly=true` | `get_counts(type_code, freq_code, cl_code, *, reporter_code=, partner_code=, ...)` | `comtrade_get_counts` | alpha |
+| `data/v1/get/{typeCode}/{freqCode}/{clCode}` | `get_data(type_code, freq_code, cl_code, *, reporter_code=, partner_code=, ...)` | `comtrade_get_data` | alpha |
+| `data/v1/getDa/{typeCode}/{freqCode}/{clCode}` | `get_data_availability(type_code, freq_code, cl_code, *, reporter_code=, period=, published_date_from=, published_date_to=)` | `comtrade_get_data_availability` | alpha |
+| `data/v1/getMetadata/{typeCode}/{freqCode}/{clCode}` | `get_metadata(type_code, freq_code, cl_code, *, reporter_code=, period=)` | `comtrade_get_metadata` | alpha |
+| `data/v1/getLiveUpdate` | `get_live_update()` | `comtrade_get_live_update` | alpha |
+| `data/v1/get/C/{A,M}/{clCode}`, total row, one reporter and partner | `get_bilateral_flows(reporter, partner, commodities, periods, flow, *, cl_code="HS")` | `comtrade_get_bilateral_flows` | alpha |
+| `data/v1/get/C/{A,M}/{clCode}`, total row, partner World, 12 periods per call, at most 120 | `get_commodity_series(reporter, commodity, flow, periods, *, cl_code="HS")` | `comtrade_get_commodity_series` | alpha |
+| `data/v1/get/C/{A,M}/{clCode}`, total row, every reporter, partner World | `get_world_trade(commodity, period, flow, *, cl_code="HS")` | `comtrade_get_world_trade` | alpha |
+| `data/v1/get/C/{A,M}/{clCode}`, total row, every partner, ranked | `get_top_partners(reporter, commodity, period, flow, n, *, cl_code="HS")` | `comtrade_get_top_partners` | alpha |
+| `files/v1/app/reference/Reporters.json`, packaged | `list_reporters(search=None)` | `comtrade_list_reporters` | alpha |
+| `files/v1/app/reference/partnerAreas.json`, packaged | `list_partners(search=None)` | `comtrade_list_partners` | alpha |
+| `files/v1/app/reference/{clCode}.json`, keyless | `list_commodities(cl_code, search=None)` | `comtrade_list_commodities` | alpha |
+
+All twelve are covered in 0.1.0, the first release. Alpha: the public surface may change
+in a minor version before 1.0; `CHANGELOG.md` lists every change.
+
+## Upstream terms and attribution
+
+Data comes from UN Comtrade (https://comtradeplus.un.org) under its own terms of use;
+this package adds no rights to it. Documentation snapshot: `docs/upstream/`.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).