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.

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.

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.

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": ...}).

Bounded timeseries for an entity: price, macro_series, or etf_flows. Returns points oldest-first with an explicit downsampling flag when the raw series exceeded max_points. etf_flows is filing-cadence (one point per SEC filing refresh), NOT per calendar day, so even a wide window yields a handful of points. Times are UTC. Costs 1 unit per call. Args: metric: One of price / macro_series / etf_flows. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}). granularity: Requested point granularity (default "1d"). max_points: Hard cap on returned points (default 500).

List endpoint source families derived from catalog metadata.

List endpoint groups available in the bundled catalog.

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. 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.

Search the bundled Sugra endpoint catalog by natural-language query.

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.