Sugra API

Call a Sugra API endpoint by operation_id from the bundled catalog. Plan calls with describe_endpoint's agent_hints: duration_class "fast" usually responds in under ~2s, "slow" usually 1-5s and occasionally 15s+ on a cold upstream, "heavy" can exceed the gateway timeout - keep parallel calls within max_concurrency and prefer small batches. Bulk endpoints bill 1 request credit per body item. Failures return structured errors {error, reason, status_code, elapsed_ms, retry_hint}; after "upstream_timeout" a single retry often succeeds because the aborted attempt warms upstream caches.

call_endpoint

Describe one Sugra API endpoint by operation_id. Includes agent_hints (duration_class fast/slow/heavy, max_concurrency, bulk billing) so you can budget timeouts and parallelism before calling. POST endpoints with a JSON body also carry request_body_schema (the resolved JSON schema) - construct the `body` argument from it instead of guessing key names. Call this after search_endpoints and before call_endpoint when you need the exact parameter names and examples.

describe_endpoint

One-step fetch: find the best Sugra endpoint for the query and call it. Combines search_endpoints + call_endpoint into a single round trip. Use this when you want data without manually picking an operation_id. The full search_endpoints + describe_endpoint + call_endpoint dance is still available when you need explicit control, but for most natural-language queries this tool is enough. Behavior: 1. Search the bundled catalog for the query. Top match wins. 2. If the matched endpoint has required parameters and they are all provided in `params`, call it and return the response. 3. If required parameters are missing, return the candidate endpoints and the missing-params list so the LLM can retry with the correct `params` dict on the next call. Examples: - `fetch_data("US CPI inflation", params={"series_id": "CPIAUCSL"})` → calls /api/v1/fred/series/CPIAUCSL, returns observations. - `fetch_data("Bitcoin price", params={"coin_id": "bitcoin"})` → calls /api/v1/crypto/bitcoin/price. - `fetch_data("Latest financial news")` → news_latest has no required params, returns latest news directly.

fetch_data

Composed current view of an entity via a named recipe. Executes a fixed server-side recipe (company_snapshot, etf_snapshot, quote_snapshot, macro_indicator_snapshot, macro_calendar, earnings_snapshot, debt_snapshot) and returns one envelope with freshness, provenance, per-component coverage, and billing. Composed calls charge the recipe's fixed cost (1-2 units) from the daily quota. status "partial" means an optional component was unavailable - the present components are still trustworthy; honor the freshness block (stale=true means the data aged past its budget). Args: recipe: Recipe name from the fixed manifest. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}).

get_snapshot

Bounded timeseries for an entity: price, macro_series, etf_flows or etf_monthly_flows. Returns points oldest-first with an explicit downsampling flag when the raw series exceeded max_points. Times are UTC. Costs 1 unit per call. The two ETF flow metrics answer different questions and are not interchangeable. ``etf_flows`` is an ESTIMATE at filing cadence: one point per SEC filing refresh, so ``t`` is a filing date and even a wide window yields a handful of points. ``etf_monthly_flows`` is the fund's own creations and redemptions from its NPORT-P filing, so ``t`` is a calendar month (``YYYY-MM``) and each point carries the three filed components - sales, reinvestment, redemption - beside the net. Two things to read before quoting etf_monthly_flows. NPORT-P is filed per SERIES, so for a fund with more than one share class the figures cover every class and the payload says so in ``multi_class_series``; where the class count is unknown it says ``class_scope`` instead of staying silent. And a fund that files no NPORT-P at all, such as a commodity trust, is not an error: the call returns status ``partial`` with an empty point list and a ``reason``. Args: metric: One of price / macro_series / etf_flows / etf_monthly_flows. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}). granularity: Requested point granularity (default "1d"). max_points: Hard cap on returned points (default 500).

get_timeseries

List source families in the bundled catalog with endpoint counts. Use the family names as the source filter on search_endpoints. This does not call the Sugra API.

list_sources

List catalog groups with endpoint counts and short descriptions. Use the group names as the toolset filter on search_endpoints. This does not call the Sugra API; it reads the bundled catalog.

list_toolsets

Resolve free text to a canonical market or macro entity. Turns a ticker, company name, macro indicator, coin, or currency pair into the agent plane's ``{namespace, ids}`` entity for use with get_snapshot and get_timeseries. A cross-namespace collision (e.g. a ticker that is both an equity and a coin) returns status "ambiguous" with ranked candidates and NEVER silently picks one; pass type_hint (e.g. "equity", "etf", "coin") to narrow the universe. Crypto aliases resolve too (e.g. "bitcoin" -> the BTC coin entity). Status "low_confidence" means the best match cleared resolution but scored weakly - verify the returned entity before building on it, or re-query with a more specific name or type_hint. For compliance KYB lookups by LEI/VAT or sanctions screening use sugra_entity_lookup / sugra_entity_screen instead - this tool is for market-data entities. Args: query: Free-form text - ticker, company, indicator, coin, or pair. type_hint: Optional namespace hint narrowing resolution.

resolve_entity

Search the bundled Sugra endpoint catalog by natural-language query. Use this to pick an operation_id. It does not fetch data. Typical loop: 1. search_endpoints(query) -> ranked hits with required_parameters 2. describe_endpoint(operation_id) -> params, request_body_schema, agent_hints 3. call_endpoint(operation_id, params=..., body=...) or fetch_data(query, params=...) Filter with toolset or source only after list_toolsets / list_sources; a misspelled filter is an error, not a silent empty result. Examples: - search_endpoints("US CPI inflation") - search_endpoints("AAPL price", toolset="markets") - search_endpoints("container ship AIS", toolset="network")

search_endpoints

Resolve an entity by identifier and return its composed KYB envelope. `anchor` is `lei` (Legal Entity Identifier, resolved via the GLEIF registry) or `vat` (EU VAT number, validated via the EU VIES service). The result weaves identity, a sanctions screening signal, and - on request - ownership and adverse-media slices. The screening verdict is a SCREENING SIGNAL, not a compliance determination, and any PEP / adverse-media content is supplementary and non-comprehensive. The `disclaimer` field carries this and is always present. Output is COMPACT by default to protect the agent context budget: `{entity:{name, anchor, value, status, country}, screening:{status, top_matches:[...3], hit_count}, ids:{...}, disclaimer}`. Pass `include` to opt INTO fuller per-slice detail, e.g. `include=["ownership","adverse_media"]` adds those slices in full form. On a bad anchor or an API error this returns a clean `{error, detail}` dict rather than raising, so the agent can branch on `result.get("error")`. Args: anchor: Identifier type, one of `lei` or `vat`. value: The identifier value (the 20-char LEI code or the VAT number). include: Optional list of fuller slices to add, e.g. `["ownership", "adverse_media"]`. Omit for the compact default.

sugra_entity_lookup