xippios-usda-psd 0.1.0__tar.gz

xippios_usda_psd-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_usda_psd-0.1.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# 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-24
+
+### Added
+
+- Scaffold from [sdk-template](https://github.com/xippios/sdk-template): configured
+  client for USDA FAS PSD Online, MCP server and FastAPI router wired to the task
+  layer, test harness, CI and publishing.
+- Upstream documentation snapshot in `docs/upstream/` (2026-10-23): the PSD part of
+  the FAS Open Data Services Swagger 2.0 document as the portal loads it
+  (`openapi/portal-document.json`) and as the API serves it itself
+  (`openapi/backend-docs-v1.json`), nine `/api/psd/` operations each, the
+  ESR and GATS paths left out. `FETCHED.md` records the full documents' sizes and
+  sha256 and the pages that hold no documentation text.
+- `scripts/refresh_upstream.py`: regenerates the snapshot reproducibly, stdlib only and
+  without a key (`uv run scripts/refresh_upstream.py`).
+- Endpoint wrappers for the nine PSD operations, named after the snapshot's
+  operationIds: the five reference lists (`PSDData_GetCommodities`, `PSDData_GetCountries`,
+  `PSDData_GetRegions`, `PSDData_GetUnitsOfMeasure`, `PSDData_GetCommodityAttributes`),
+  the data by country, for every country and for the world
+  (`PSDData_GetCountryCommodityDataByYear`, `PSDData_GetCommodityDataByYear`,
+  `PSDData_GetWorldCommodityDataByYear`) and the release dates
+  (`PSDData_GetDataReleaseInfo`). Models mirror the recorded records: `CommodityData`
+  with `value` as `Decimal` and attribute and unit ids as plain `int`, so a new upstream
+  id never fails an answer, and `DataReleaseInfo`.
+- Tasks `get_data(commodity_code, market_year, country_code=None)` (one country, or every
+  country through the `country/all` path), `get_world_data(commodity_code, market_year)`
+  and `get_release_dates(commodity_code, market_year=None, country_code=None)`, as MCP
+  tools `usda_psd_get_data`, `usda_psd_get_world_data`, `usda_psd_get_release_dates`
+  and HTTP routes. Codes and the market year are checked before any call. The data
+  tasks set `meta.vintage` to the PSD release that last revised the result, the latest
+  `calendarYear`-`month` of its records (`"2026-07"`), and leave `meta.published_at`
+  empty: PSD gives a month, no day. A market year without data is `NoDataForYear`,
+  a `NotFoundError`, naming commodity, country and year. `get_release_dates` filters
+  upstream's full list by market year and country, for polling over MCP.
+- Tasks `list_commodities(search=None)`, `list_countries(region_code=None, search=None)`,
+  `list_regions()`, `list_units_of_measure()` and `list_commodity_attributes(search=None)`,
+  as MCP tools `usda_psd_list_*` and HTTP routes. They answer from the packaged lists
+  without an upstream call, records in upstream order and unchanged; `meta.endpoint` is
+  the operation the list was fetched from, `meta.vintage` the day it was fetched
+  (`"2026-10-23"`), `meta.retrieved_at` when the task answered, `meta.request` the
+  filters. `search` keeps records whose code or name (for countries also the GENC code)
+  contains the text, ignoring case;
+  `region_code` keeps the countries of one region, exactly (`"R15"`, which
+  `PSDData_GetRegions` lacks, included; an unknown region is an empty list), so agents
+  can see past the MCP cap of 200 rows (251 countries). Live tests check each packaged
+  list against the live one.
+- Slices, as MCP tools `usda_psd_get_*` and HTTP routes, composing the existing
+  wrappers and packaged lists, records unchanged (ADR-0003):
+  `get_balance_sheet(commodity_code, country_code, market_year)` pivots one country-year
+  into one `BalanceSheet` record, lossless, its `attributes` keyed by the packaged
+  attribute name (with the id for an id whose name the list gives to several ids, so a key
+  is the same in every answer of a package version; `"attribute <id>"` for an id the list
+  lacks), each `BalanceSheetEntry` with its own `unit_id`; an empty answer is
+  `NotFoundError`. `get_time_series(commodity_code, country_code, attribute_id,
+  start_year, end_year)` makes one request per market year from 1960 on, at most 100
+  market years per call, oldest first, and leaves a year without data (`NoDataForYear`)
+  or without the attribute out, no gap filled; any other error is raised.
+  `get_top_countries(commodity_code, market_year, attribute_id, n=10)` ranks the
+  `country/all` records of one attribute by value, ties in upstream order, groupings
+  such as `E4` included; `meta.vintage` is the latest release among every record ranked.
+  `get_latest_release(commodity_code)` keeps the records of the newest release, with
+  that release as `meta.vintage`; over MCP at most 200 rows, `get_release_dates` serves
+  any part of the list in full.
+- `errors.NoDataForYear`, a `NotFoundError`: `classify` raises it for PSD's empty
+  `text/plain` 404 on a data path, the answer for a market year without data, and the
+  data tasks raise it again naming commodity, country and year; the gateway's
+  `NOT_FOUND` stays a plain `NotFoundError` and reaches the caller unchanged.
+- `params.validate_attribute_id` and `params.attribute_names`: attribute ids are checked
+  against the packaged `commodityAttributes` list before any call; `UnknownCode` names
+  the closest ids and takes an integer value and its own reason.
+- Client (ADR-0010): `classify` maps api.data.gov's `API_KEY_*` answers to `AuthError`
+  naming the code and `DATA_GOV_API_KEY`, a 429 to `RateLimitError` (`Retry-After`, else
+  one hour), the gateway's `NOT_FOUND` to `NotFoundError` and PSD's empty-body 404 to
+  `NoDataForYear`, a `NotFoundError`. The
+  client keeps 60 requests per minute, one at a time, asks for JSON, and records the
+  gateway's `x-ratelimit-*` headers in `quota()`, never from a cache hit. Once the
+  hourly quota is spent it waits before the next request when the wait is within
+  `RetryPolicy.backoff_max`, and otherwise raises `RateLimitError` with `retry_after`
+  without sending; a request the cache can answer is never delayed or refused.
+- Packaged reference data: the five lists under `reference/` with provenance, written by
+  `scripts/refresh_reference.py` through `api/`; `enums.AttributeId` and `enums.UnitId`
+  (`IntEnum`, named after upstream's names); `params.validate_commodity_code`,
+  `validate_country_code` (raising `errors.UnknownCode` with the closest packaged codes,
+  or a hint for `"all"` and `"00"`) and `validate_market_year`.
+- Recorded fixtures: the five lists; wheat US, wheat and corn for every country, wheat
+  and soybeans world, all 2023; wheat US 2021 and 2022 for the time series; the wheat
+  release dates; an unknown commodity, country and market year; valid codes without
+  data (wheat, Bermuda, 2023: 200 `[]`); market year 1900 for every country and the
+  world (404, empty body); an invalid key; and the gateway's 429 (`OVER_RATE_LIMIT`,
+  `Retry-After: 3151`, `x-ratelimit-remaining: 0`), recorded after spending the hourly
+  quota. `CLAUDE.md` records what each answered.
+- `scripts/check-siblings.sh` and the CI job `siblings`: this wheel and
+  `xippios-usda-nass` install side by side, import, pass `uv pip check`, and add no
+  `__init__.py` to `xippios/` or `xippios/usda/` (ADR-0006).
+
+### Removed
+
+- The template's live reachability test `test_upstream_answers`: it sent the key to `/`,
+  which the gateway answers 404, spending a quota call. Each task has its own live smoke
+  test instead, twelve in all.

xippios_usda_psd-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_usda_psd-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: xippios-usda-psd
+Version: 0.1.0
+Summary: Typed client, MCP tools and HTTP routes for USDA FAS PSD Online
+Project-URL: Homepage, https://github.com/xippios/sdk-usda-psd
+Project-URL: Upstream, https://apps.fas.usda.gov/psdonline/
+Project-URL: Changelog, https://github.com/xippios/sdk-usda-psd/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/xippios/sdk-usda-psd/issues
+Author: XIPPIOS GmbH
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agriculture,httpx,mcp,pydantic,sdk,usda-psd
+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-usda-psd
+
+Typed Python client, MCP server and FastAPI routes for
+[USDA FAS PSD Online](https://apps.fas.usda.gov/psdonline/), 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-usda-psd            # client only
+uv add "xippios-usda-psd[mcp]"     # + MCP server
+uv add "xippios-usda-psd[http]"    # + FastAPI router
+```
+
+Set `DATA_GOV_API_KEY` in the environment. Nothing is read from files.
+
+## 30-second example
+
+```python
+from xippios.usda.psd import get_data
+from xippios.usda.psd.enums import AttributeId
+
+result = get_data("0410000", 2023, "US")  # wheat, market year 2023, United States
+production = next(r for r in result.data if r.attribute_id == AttributeId.PRODUCTION)
+production.value, production.unit_id  # Decimal('49095.0'), 8 (UnitId._1000_MT)
+result.meta.vintage  # "2026-07": the PSD release that last revised these figures
+result.meta.published_at  # None: PSD gives a month, no day
+result.meta.retrieved_at, result.meta.request
+```
+
+Codes are PSD's own (commodity `0410000` wheat, `0440000` corn, `2222000` soybeans;
+country `US`, `BR`, `E4`), checked against the lists packaged in `reference/` before any
+call. Leave out the country for every country at once, or use `get_world_data` for the
+world total. `attribute_id` and `unit_id` are PSD's integer ids; `enums.AttributeId` and
+`enums.UnitId` name the packaged ones and compare equal to them. The MCP server returns
+at most 200 rows per call, and every country at once is up to about 1,900 rows, so pass a
+country there. `get_release_dates` tells when PSD last revised each country and market
+year; compare it with a stored `meta.vintage` to fetch only what changed.
+
+The `list_*` tasks look codes up in the packaged lists, without a call:
+
+```python
+from xippios.usda.psd import list_commodities, list_countries
+
+result = list_countries(region_code="R01")  # PSD's region North America (list_regions)
+[c.country_code for c in result.data]  # ["CA", "GL", "MX", "SB", "US"], upstream order
+result.meta.endpoint, result.meta.vintage  # "PSDData_GetCountries", "2026-10-23" (fetched)
+list_countries(search="united").data  # TC, UK, US: code, name or GENC code, ignoring case
+list_countries(search="usa").data  # US United States, by its GENC code "USA"
+list_commodities(search="soybean").data  # meal, oil and oilseed, each also "(Local)"
+```
+
+`meta.vintage` of a list is the day the package fetched it (upstream gives these lists no
+version), `meta.retrieved_at` when the task answered. Over MCP `usda_psd_list_countries`
+stops at 200 of its 251 countries, before the United States; pass `region_code` or
+`search` there.
+
+The slices answer the common questions from the same operations. They select, order or
+pivot upstream's records and change none: no derived totals, no unit conversion, no gap
+filling.
+
+```python
+from xippios.usda.psd import (
+    get_balance_sheet,
+    get_latest_release,
+    get_time_series,
+    get_top_countries,
+)
+from xippios.usda.psd.enums import AttributeId
+
+sheet = get_balance_sheet("0410000", "US", 2023).data  # wheat, United States, one request
+list(sheet.attributes)  # ["Area Harvested", "Beginning Stocks", "Production", ...], 15
+sheet.attributes["Production"]  # attribute_id=28, unit_id=8 (1000 MT), value=Decimal("49095.0")
+
+series = get_time_series("0440000", "US", AttributeId.PRODUCTION, 2021, 2023)  # 3 requests
+[(r.market_year, r.value) for r in series.data]  # one record per year with data, oldest first
+
+top = get_top_countries("2222000", 2023, AttributeId.PRODUCTION, n=5)  # soybeans, one request
+[r.country_code for r in top.data]  # largest first; "E4" (EU) and aggregates rank too
+
+latest = get_latest_release("0410000")  # the countries and market years of the newest release
+latest.meta.vintage  # "2026-10", comparable with get_data's meta.vintage
+```
+
+`get_balance_sheet` keys each entry by the attribute's upstream name; an id whose name
+upstream gives to several ids (`"Total Disappearance"` is 126 and 173) always carries the
+id, `"Total Disappearance (126)"`, and each entry keeps its own `unit_id`.
+`get_time_series` starts at 1960 at the earliest, spans at most 100 market years per
+call, spends one request per market year,
+leaves a year without data out, and counts against the hourly quota like every other
+request.
+`get_top_countries` excludes nothing: PSD's groupings (`E4` European Union, `T3` Africa,
+NEC, ...) rank alongside countries; filter with `list_countries` if you must.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "usda-psd": {
+      "command": "uvx",
+      "args": ["--from", "xippios-usda-psd[mcp]", "xippios-usda-psd-mcp"],
+      "env": { "DATA_GOV_API_KEY": "..." }
+    }
+  }
+}
+```
+
+Tools are read-only and named `usda_psd_<verb>_<noun>`. Results are capped at
+200 rows or 64 KB with a note on how to narrow the query. `--http` serves streamable
+HTTP instead of stdio.
+
+## Status
+
+| Upstream operation | Task function | MCP tool | Status |
+| --- | --- | --- | --- |
+| `PSDData_GetCountryCommodityDataByYear` (`commodity/{commodityCode}/country/{countryCode}/year/{marketYear}`) | `get_data(commodity_code, market_year, country_code)` | `usda_psd_get_data` | alpha |
+| `PSDData_GetCommodityDataByYear` (`commodity/{commodityCode}/country/all/year/{marketYear}`) | `get_data(commodity_code, market_year)` | `usda_psd_get_data` | alpha |
+| `PSDData_GetWorldCommodityDataByYear` (`commodity/{commodityCode}/world/year/{marketYear}`) | `get_world_data(commodity_code, market_year)` | `usda_psd_get_world_data` | alpha |
+| `PSDData_GetDataReleaseInfo` (`commodity/{commodityCode}/dataReleaseDates`) | `get_release_dates(commodity_code, market_year, country_code)` | `usda_psd_get_release_dates` | alpha |
+| `PSDData_GetCommodities` (`commodities`) | `list_commodities(search)` | `usda_psd_list_commodities` | packaged; `list_*` task |
+| `PSDData_GetCountries` (`countries`) | `list_countries(region_code, search)` | `usda_psd_list_countries` | packaged; `list_*` task |
+| `PSDData_GetRegions` (`regions`) | `list_regions()` | `usda_psd_list_regions` | packaged; `list_*` task |
+| `PSDData_GetUnitsOfMeasure` (`unitsOfMeasure`) | `list_units_of_measure()` | `usda_psd_list_units_of_measure` | packaged; `list_*` task |
+| `PSDData_GetCommodityAttributes` (`commodityAttributes`) | `list_commodity_attributes(search)` | `usda_psd_list_commodity_attributes` | packaged; `list_*` task |
+
+The slices: task-shaped functions over the operations above, no new endpoint.
+
+| Upstream operation | Task function | MCP tool | Example | Status |
+| --- | --- | --- | --- | --- |
+| `PSDData_GetCountryCommodityDataByYear`, one request | `get_balance_sheet(commodity_code, country_code, market_year)` | `usda_psd_get_balance_sheet` | `get_balance_sheet("0410000", "US", 2023)`: wheat US 2023 as one record, 15 attributes | alpha |
+| `PSDData_GetCountryCommodityDataByYear`, one request per market year | `get_time_series(commodity_code, country_code, attribute_id, start_year, end_year)` | `usda_psd_get_time_series` | `get_time_series("0440000", "US", 28, 2021, 2023)`: US corn production, three years | alpha |
+| `PSDData_GetCommodityDataByYear`, one request | `get_top_countries(commodity_code, market_year, attribute_id, n=10)` | `usda_psd_get_top_countries` | `get_top_countries("2222000", 2023, 28, n=5)`: the five largest soybean producers | alpha |
+| `PSDData_GetDataReleaseInfo`, one request | `get_latest_release(commodity_code)` | `usda_psd_get_latest_release` | `get_latest_release("0410000")`: what wheat's newest release revised; MCP returns at most 200 rows, a release adding a market year can exceed that (wheat 2026-10: 146), `get_release_dates(commodity_code, market_year=..., country_code=...)` returns any part in full | alpha |
+
+All twelve tasks are covered in 0.1.0, the first release. Alpha: the public surface may
+change in a minor version before 1.0 (conventions §12); `CHANGELOG.md` lists every change.
+
+Every request counts against api.data.gov's quota of 1,000 requests per hour per key,
+shared by every package using the same `DATA_GOV_API_KEY`; the `list_*` tasks spend none.
+The client keeps its own pace of one request per second; once the quota is spent it waits
+for the quota to come back when that takes at most 30 s, and otherwise raises
+`RateLimitError` with `retry_after` instead of sending.
+
+## Upstream terms and attribution
+
+Data comes from USDA FAS PSD Online (https://apps.fas.usda.gov/psdonline/) under its own terms of use;
+this package adds no rights to it. Documentation snapshot: `docs/upstream/`.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).