Kyrodata — Brazil Trade, Crop & Commodity Data

Compares Brazil's exports or imports between two equal-length windows (like-for-like), in value (USD FOB) and in volume (kg). `mode` changes the reading: quarterly, semestral, annual, ytd and rolling_3m/6m/12m look a year back and hold the season constant, while monthly and semestral_sequential compare against the period immediately before and cross one. `codes` and `countryIds` filter both windows alike and combine: together they isolate one product to one partner (1201 soybean to 160 China); omitted, every product and partner counts. The result carries both windows, the % change of each metric, the window label, whether it crosses a season, and the monthly series spanning both, capped at 24 months. This returns the FIGURES of a comparison — kyrodata_resolve_comparison_window only names the window, and kyrodata_list_trade_series hands over raw monthly points without comparing them. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).

Explains the pyramid's arithmetic for one commodity and horizon: the seven levels side by side (label, push %, weight share, confidence, contribution %) and, for the levels that did not enter, the reason with its ruler (hit rate vs base rate, number of origins). `horizon` fixes the month and shows the seven levels; `levelKey` flips the cut, following one level across all four horizons instead. This is the drill-down of kyrodata_get_hub_summary — the 'por quê?' behind a verdict that tool already gave. A question about the physical harvest rather than the arithmetic belongs to kyrodata_get_climate_reading. Credit class: level (any level tool in a 60-second session = 2 credits; a session is capped at 3).

Opens ONE public foreign-trade document by id and returns it as prose to quote: title, body text and a public URL for citation. `id` is not free text — it is an id kyrodata_search returned, shaped `heading:1201` (an HS heading) or `country:160` (a partner country); anything else is refused rather than guessed. The body carries the measured figures of the latest published year, Brazilian exports and imports in USD FOB and kg, plus the window, the source and its caveats. Public government trade data only. The output here is a citable DOCUMENT with a URL, and this is the only tool that returns one. A heading as structured figures and a monthly series to reason over is kyrodata_get_heading_overview; free text to find an id in the first place is kyrodata_search. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).

Current climate reading for a commodity: risk level, the measured production shock in % of the harvest, and the projected physical loss in tonnes per horizon (1, 3, 6 and 12 months) with its range. `scope` sets the geographic cut — 'br' (the default) reads the country, 'region:SE' a macro-region (N, NE, CW, SE, S), 'uf:MG' a single state — and moves only the risk level and the shock: the loss in tonnes stays national at any scope. A commodity without a validated model returns a descriptive reading with no verdict, and a season not yet measurable returns the previous one, each flagged in the caveats. Climate here predicts PRODUCTION. The price question for the same hub is kyrodata_get_hub_summary, and the published season-by-season balance sheet is kyrodata_get_supply_demand_balance. Credit class: level (any level tool in a 60-second session = 2 credits; a session is capped at 3).

Reports the credit balance and the limits of the API key making the request: credits left in the current cycle and when it resets, the daily credit and daily call ceilings of the key, and which tools the key reaches. `response_format` is the only input and it changes verbosity, not scope — there is no argument that selects another key, since the answer describes whichever key authenticated this call. It reads no market data, so it answers a question about the ACCOUNT, never about trade, climate or a commodity. A question about how far the data itself goes is kyrodata_get_data_coverage. Credit class: free (0 credits).

Returns the calendar of the trade data: first and last published month (YYYYMM), whether the current year is partial, the last fully closed month, and when the aggregates were last refreshed. `response_format` is the only input; the answer covers the whole dataset, so there is no window or product to narrow it with. This answers 'até quando tem dado?' and 'qual o último mês?' — the CALENDAR, never figures. Turning that calendar into a like-for-like window is kyrodata_resolve_comparison_window; reading the figures inside it is kyrodata_get_heading_overview. Credit class: free (0 credits).

Structured read of ONE HS heading (SH4, 4 digits) for exports or imports: totals of the published year (USD FOB, kg), the last closed month against the previous one (average price per kg and volume), and a monthly price-by-volume series. `year` centres the overview and defaults to the most recent published year, with coverage starting in 2000; `months` sets only how far the series reaches back from the last published month, and leaves the totals untouched. A caveat states that US$/kg is an average unit value, not a quoted price. Public data. The output here is FIGURES and a series to reason over. The same heading as a citable document with a URL is kyrodata_fetch, and a comparison between two windows is kyrodata_compare_trade. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).

Reads the Kyrodata pyramid verdict for a commodity hub: direction of the leading horizon, expected move in % per horizon (1, 3, 6 and 12 months), the 80% band as a half-width in percentage points, which levels drive the verdict and the measured accuracy. A horizon without an arrow names the reason, and an empty one means no level passed the confidence gate: no signal, not a stable price. `horizon` re-centres the verdict on the month given; omitted, it centres on the horizon the model leads with, and all four come back either way. It also carries the month-over-month and year-over-year % change of the reference price and its kind (doméstico, mundial or paridade de exportação), never the price level. This is the tool for where a hub's price is heading. The arithmetic behind the verdict is kyrodata_explain_pyramid_level, and the physical harvest of the same hub is kyrodata_get_climate_reading. Credit class: level (any level tool in a 60-second session = 2 credits; a session is capped at 3).

Published supply and demand balance (physical, in tonnes) for one agricultural hub, season by season: production, imports, exports, consumption, initial and final stock, whether the season is still an estimate, and how many months a partial season measures. `hub` accepts only the hubs that have a published balance sheet, which is fewer than the hubs the forecast tools cover; `closedOnly` drops the current season, which is a projection and still moves. The source is a Brazilian government body and is named in the result. This is the physical BALANCE of a season. The price verdict for the same hub is kyrodata_get_hub_summary, and the weather risk behind production is kyrodata_get_climate_reading. Credit class: level (any level tool in a 60-second session = 2 credits; a session is capped at 3).

Ranks Brazil's partner countries for exports or imports, one row per country with value (USD FOB), volume (kg), price per kg and share of the window. `from`/`to` are YYYYMM and default to the last 12 published months; `codes` narrows to HS codes (4, 6 or 8 digits) so the ranking answers 'who buys THIS product'; `withGrowth` adds the last 12 months against the previous 12, which is the only way growth enters the answer. The country is the OUTPUT of this tool, so it takes no country filter — a question about one known country is a filter on kyrodata_compare_trade or kyrodata_list_trade_series instead. This ranks partners inside one window; comparing two windows is kyrodata_compare_trade. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).

Returns Brazil's monthly export or import series as rows — one row per month, with value (USD FOB), volume (kg) and the implied price per kg. `from`/`to` are YYYYMM and default to the last 24 published months; the span is capped at 200 months and a wider one is refused rather than silently truncated. A month with nothing published is ABSENT from the series rather than present as zero, so gaps stay visible instead of reading as collapse. `codes` and `countryIds` narrow the same series and can combine, which is how a single product-and-partner line is drawn. This hands over the POINTS. A question about them — two equal windows compared — is kyrodata_compare_trade, and a ranking of partners inside one window is kyrodata_list_trade_partners. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).

Resolves an equal-length comparison window (like-for-like) for the trade data, anchored on the last fully published month, and returns ONLY the window metadata — from, to, label, months and whether it crosses a season. No figures. `mode` splits into two families, and the split is what matters: quarterly, semestral, annual, ytd and rolling_3m/6m/12m compare against the same period a year earlier and hold the season constant, while monthly and semestral_sequential compare against the period immediately before and therefore cross one. `ytd` runs January to the last published month, in both years. This exists to NAME a window in prose before it is described. The same window resolved internally and answered with value and volume in one call is kyrodata_compare_trade. Credit class: free (0 credits).

Resolves a free-text name into platform identifiers for FILTERING other tools: commodity hubs (slug plus anchor SH4), HS headings (SH4), NCM codes (8 digits) and partner countries (country id). 'soja' resolves to the soybean hub and SH4 1201; 'China' to country id 160. `query` takes a name already known rather than a topic to explore, and up to 10 matches per kind come back — an ambiguous term returns the candidates instead of one guess, so the caller picks. The output is an ID to pass to another tool, and it carries no document and no URL. Finding what exists in the public catalog, and getting a citable document back, is kyrodata_search. Credit class: free (0 credits).

Runs one of the product's pre-built catalogue reports by id and returns its rows, up to 50. `reportId` is an enum of the catalogue's ids, so the whole catalogue travels in this schema and no lookup call is needed; `params` carries the values the chosen report declares, and `columnIds` narrows the projection — omitted, the report's default columns come back, and the columns that identify each row are included either way. Columns locked behind a paid plan are declared, with a header stating what an upgrade unlocks, while their values stay out. Rows count against the account's export quota. This serves a report that already exists as a product. An ad-hoc question about trade is kyrodata_compare_trade or kyrodata_list_trade_series, and a citable public document is kyrodata_fetch. Credit class: comex (up to 2 comex tools per 60-second session = 1 credit).

Searches the public Brazilian foreign-trade catalogue and returns document ids for kyrodata_fetch — HS headings (SH4, 4 digits) and partner countries — each with a public URL. `query` is free text in Portuguese or a code, and both reach the same place: 'soja' and '1201' land on the soybean heading, 'China' on the partner country. This is DISCOVERY: it finds what exists when the caller has words rather than an id. Turning a name already known into an id for filtering another tool is kyrodata_resolve_entity, which returns no document and no URL. Credit class: free (0 credits).