> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hue.run/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up Hue in an application, fetch https://docs.hue.run/guides/agent-setup.md and follow it.
> Hue's project-data MCP server is https://mcp.hue.run/mcp. https://docs.hue.run/mcp only searches these docs and cannot read a Hue project.
> Never ask the user to paste a Hue API key into chat; they store it as HUE_API_KEY themselves.
> Install the exact SDK versions pinned on the page you're following, or on https://docs.hue.run/quickstart.md. Run the latest CLI without a project install as `npx -y @hue-run/sdk@latest`. In a project with `@hue-run/sdk` installed, use `npx hue`. Pin an exact version for reproducible CI runs.
> Use Hue product terms: eval set, case, evaluator, run and scoring run. Older APIs may say dataset, scorer or experiment; prefer the current SDK methods. See https://docs.hue.run/concepts.md.

# Python API reference

> Use the Python SDK to trace, evaluate, score, and drive simulated instances.

This reference covers `hue-run` **0.15.1** on Python 3.10 or later, tested on 3.10 and 3.14 with OpenTelemetry 1.45.1 and on 3.10 and 3.12 with OpenTelemetry 1.40.0; the accepted range is `>=1.40,<2`. Start with the [Python guide](https://docs.hue.run/sdks/python.md) for installation and a runnable trace, and [compatibility](https://docs.hue.run/sdks/compatibility.md) for supported runtimes and instrumentation. Use [Quickstart](https://docs.hue.run/quickstart.md#2-install-the-sdk) for the available package release.

## Imports

| Module | Public exports |
| - | - |
| `hue_sdk` | `Hue`, `create_hue_safe`, `HueSpan`, `Attachment`, `Project`, `ProjectValidationError`, `Redactor`, `ExportStatus`, `TraceReceipt`, `TraceReceiptField`, `TraceReceiptFields`, `TraceVerificationError`, `TraceVerificationResult`. |
| `hue_sdk.evals` | `EvaluationClient`, `HueApiError`, `is_transient_api_error`, `run_experiment`, `rescore`, `builtin_scorers` (with `builtins` as an alias), `define_local_scorer`, `score_locally`, `MISSING`, `TraceEvidence`, `TargetContext`, `ScoreContext`, `Score`, `LocalScorer`, `RunnerReport`, `LocalFile`, `CaseFileWrite`, `CaseFileError`, `ArtifactSizeError`, the [recorded media](#recorded-media) exports (`MediaClient`, `MediaFile`, `MediaFetchError`, `MediaResolveFailure`, `ResolvedMedia`, `rehydrate_media`) and the recovery errors. |
| `hue_sdk.world` | `WorldClient`, `WorldModelClient`, the [world handoff](#world-handoff) helpers and the canonical World and instance types. |
| `hue_sdk.environment` | `EnvironmentClient`, `HueEnvironmentError`, the [world handoff](#world-handoff) helpers and the simulated-environment types. |
| `hue_sdk.managed` | `ManagedTargetHandler`, `ManagedTargetContext`, `ManagedInputFile`, `ManagedOutputFile`, `ManagedTargetResult`, `ManagedResponse`. |

The SDK sends OpenTelemetry traces and correlated logs. Your application remains responsible for provider calls and the instrumentation that observes them. The tracing core depends only on the OpenTelemetry packages and `requests`.

## Create a tracing client

```python theme={null}
import os
from hue_sdk import Hue

hue = Hue(
    api_key=os.environ["HUE_API_KEY"],
    capture_content=True,  # Record supported input/output content.
    capture_http=os.getenv("HUE_CAPTURE_HTTP", "true") != "false",
    capture_http_bodies=os.getenv("HUE_CAPTURE_HTTP_BODIES", "true") != "false",
    service_name="my-agent",
)
```

```python theme={null}
Hue(
    base_url: str = "https://app.hue.run",
    api_key: str | None = None,
    *,
    capture_content: bool = True,
    capture_http: bool = True,
    capture_http_bodies: bool | None = None,
    service_name: str = "hue-python-agent",
    tracer_provider: TracerProvider | None = None,
    logger_provider: LoggerProvider | None = None,
    redactor: Redactor | None = None,
    export_timeout_seconds: float = 10,
    enabled: bool = True,
    max_queue_size: int = 2048,
    max_queue_bytes: int = 8388608,
    live_spans: bool = True,
)
```

| Option | Behavior |
| - | - |
| `base_url` | Optional origin; defaults to `https://app.hue.run`. Do not append an API path. HTTPS is required except for loopback HTTP; credentials, query strings and fragments are rejected. |
| `api_key` | Required project service key. Use **Read and write** for tracing, known-trace receipts and evaluation APIs. Keep it in the server environment. |
| `capture_content` | Optional; defaults to `True`. `True`, the recommended setting, records supported content; `False` sends metadata only. See [content policy](#content-policy). |
| `capture_http` | Default `True`. Records supported outbound HTTP CLIENT spans. `False` disables HTTP capture. |
| `capture_http_bodies` | Default `None`, which follows `capture_content`. `False` retains HTTP identity without request or response content. `capture_content=False` always disables HTTP content. See [app HTTP exchanges](https://docs.hue.run/guides/traces.md#app-http-exchanges). |
| `service_name` | Default `"hue-python-agent"`; configures the resource when Hue creates both providers. |
| `tracer_provider` | Optional OpenTelemetry SDK `TracerProvider` to borrow. Hue adds its span processor without replacing the global provider. |
| `logger_provider` | Optional OpenTelemetry SDK `LoggerProvider` to borrow for correlated logs. Hue adds its log record processor without replacing the global provider. |
| `redactor` | Optional `Callable[[str, Any], Any]`: receives a field name and helper content, and returns a JSON-serializable replacement. |
| `export_timeout_seconds` | Default `10`; positive finite number. Configures export HTTP I/O and project validation; it is distinct from a flush wait budget. |
| `enabled` | Default `True`; must be a boolean. `False` creates a disabled client without requiring a key or attaching to a supplied provider. |
| `max_queue_size` | Default `2048`; positive integer limiting pending records per signal, including admissions and active export batches. |
| `max_queue_bytes` | Default `8388608`; positive integer limiting encoded queue bytes per signal, including active export batches. |
| `live_spans` | Default `True`; must be a boolean. Sends placeholders for open Hue and AI spans. A span still open when its placeholder is exported, usually about 1.5 s after it starts, shows as running. Setup keys never send placeholders. See [live spans](#live-spans). |

Use the `api_key=` keyword when omitting the origin. The first positional parameter is `base_url`, so `Hue("<key>")` raises `TypeError` naming `api_key=`; existing `Hue(base_url, api_key, ...)` calls are unchanged. When enabled, the key is required and validated even though the signature permits `None`. Disabled clients do not require a key. The constructor does not load environment variables or an environment file automatically. Invalid options raise `TypeError` or `ValueError`.

With a borrowed tracer or logger provider, your application owns that provider's resource and other processors, and the provider Hue creates for the other signal reuses the borrowed provider's resource, so spans and correlated logs report one `service.name`. Borrowed providers are not shut down by the client. Use one Hue instance for its provider lifecycle; OpenTelemetry has no public processor-removal API. See [existing OpenTelemetry](https://docs.hue.run/integrations/opentelemetry.md).

## Spans and context

Use `with` for the context managers below. They are ordinary synchronous context managers that may surround work inside an async function.

```python theme={null}
with hue.context(session_id="conversation-1", user_id="application-user"):
    with hue.span("request") as run:
        with hue.tool("uppercase") as tool:
            tool.set_input("hello")
            result = "hello".upper()
            tool.set_output(result)
        run.set_output(result)
```

| Method | Parameters and behavior |
| - | - |
| `hue.context(*, session_id=None, user_id=None, workspace_id=None)` | Adds task-local identifiers inherited by nested Hue helpers. Maps to `gen_ai.conversation.id`, `user.id` and `hue.workspace.id` (the application workspace or tenant); does not modify global baggage. |
| `hue.span(name, *, attributes=None, kind=SpanKind.INTERNAL, parent_context=None)` | Yields `HueSpan`, activates its OpenTelemetry context and ends it on exit. Explicit attributes override inherited attributes with the same name. |
| `hue.model(model, *, provider, operation="chat", name=None, system_instructions=..., tools=...)` | Yields a client span with model/provider/operation attributes. Default name is `"{operation} {model}"`. Optional `system_instructions` and `tools` (any JSON value, ideally in the GenAI shapes) are recorded as `gen_ai.system_instructions` and `gen_ai.tool.definitions` when content is captured; omit them to record nothing. It does not invoke a model or estimate usage. |
| `hue.tool(name, *, call_id=None, mcp=None, endpoint=None)` | Yields a tool span named `"execute_tool {name}"`, with an optional tool-call identifier. `mcp` is a mapping with optional `name`, `version`, `provider` and `surface`, recorded as `mcp.server.name`, `mcp.server.version`, `hue.mcp.provider` and `hue.mcp.surface`; an invalid value is omitted and counted as an instrumentation failure. |
| `Hue.inject(headers)` | Adds the active W3C trace context to a mutable string mapping. Does not insert the Hue key or baggage. |
| `Hue.extract(headers)` | Returns an OpenTelemetry `Context` to pass as `parent_context`. |

`endpoint` takes the exported `ToolEndpoint` typed dictionary. Required fields are `url: str` and `source: Literal["request", "client_config", "receipt"]`. Optional fields are `method: str` and `capture_query_parameters: list[str]`.

The URL must be the actual HTTP(S) endpoint used by the tool. With content capture enabled, Hue records it through the configured redactor, removing credentials, fragments and query parameters unless their non-secret names are allowlisted. The optional method has no default. This records application-supplied routing evidence without making a request or inferring a URL from labels.

An exception escaping a Hue span records error type/status, then propagates unchanged. Python helpers always omit exception messages and stacks, including when capture is enabled. Initialize the client once, keep spans open until their work ends, and shut down when the process stops.

### HueSpan

| Member | Behavior |
| - | - |
| `trace_id` / `span_id` | Hexadecimal OpenTelemetry identifiers. |
| `otel_span` | Underlying OpenTelemetry span for standard attributes, events and context APIs. |
| `record_provider_tool_calls(response, *, provider=None, request=None, servers=None)` | Records up to 1,024 supported provider-executed tool items as child `execute_tool` spans. Additional items are skipped and counted; call it on a `model()` span. |
| `set_attribute(name, value)` | Sets caller-owned OpenTelemetry metadata. Here and in `span(attributes=...)`, a list or tuple subclass, or a list or tuple of 65,536 or more items, is omitted and counted as an instrumentation failure. |
| `set_input(value)` / `set_output(value)` | Captures JSON helper content according to `capture_content` and the redactor. Model/tool helpers choose their corresponding GenAI field names. |
| `set_usage(*, input_tokens=None, output_tokens=None)` | Sets known nonnegative integer token counts. `None` omits a count; booleans and negative counts are rejected. |
| `record_error(error)` | Records error type and status without exception text. Does not raise the supplied error itself. |
| `record_file(*, role, media_type, sha256=None, data=None, byte_size=None, name=None, upload=False, path=None)` | Adds a `hue.file` event for a file the work read, received or produced. `role` is `input`, `attachment` or `output`. `data` up to 25 MiB is hashed and measured locally (a `str` is hashed as UTF-8); pass `sha256` and `byte_size` instead when you already have them. `path`, in place of `data` (not both), names a regular file up to 1 GB: up to 25 MiB it is read as `data` is, and a larger file is hashed now and, with `upload=True`, streamed from disk when it uploads, only if it still has its recorded size and SHA-256. A path that is not a regular file, or a file over 1 GB, is omitted and counted. `upload` defaults to `False`. With `upload=True`, supplied `data` or `path`, content capture and an ordinary project key, export adds a `hue.blobs` entry to the same span, keyed `event:hue.file:<sha256>`, and the bytes upload in the background; an upload that is not made counts in `export_status.upload_fallbacks` and the event remains. The event carries `hue.file.sha256`, `hue.file.role`, `hue.file.media_type`, `hue.file.size` when known and, only when content is captured, `hue.file.name`. A name must be nonblank after trimming, at most 256 UTF-16 code units and well-formed Unicode, with no C0 control characters (U+0000–U+001F) or DEL (U+007F); an invalid name is omitted and counted, and the event remains (before 0.10.0 tabs, newlines and DEL were accepted). The event is recorded in both capture modes; an invalid record is omitted and counted. |
| `log_inference(...)` | Accepts optional keyword-only `input`, `output`, `operation`, `provider`, `model` and `system_instructions`. Emits an inference-details log correlated to this span, even outside its active scope, with a structured body and `gen_ai.*` request attributes from the enclosing `model()` block or those keywords plus `gen_ai.conversation.id` from `context()`. Omit a content keyword for an absent field; passing `None` keeps the key with an empty value. Nothing is emitted when `capture_content` is False. |

`Attachment(data=None, *, path=None, content_type, name=None)` from `hue_sdk` places a file in any value Hue records: a `span()` input or output, `model()` messages, a tool's arguments or result, `log_inference()` messages, or a span attribute passed to `span(attributes=...)` or `set_attribute`. Give exactly one of `data` (bytes, or a base64 string or `data:` URL, up to 25 MiB) and `path` (a regular file up to 1 GB; over 25 MiB it is hashed when the attachment is created and streamed from disk when it uploads, only if it still has its recorded size and SHA-256). It is recorded as a GenAI `blob` part in digest form and its bytes upload after its record is sent; an invalid attachment is recorded as `None` and counted. See [Attach a file anywhere](https://docs.hue.run/guides/media.md#attach-a-file).

Choose logs or span attributes for the same content event to avoid duplicate storage. `log_inference` emits no record when content capture is disabled. `hue.tracer`, `hue.tracer_provider` and `hue.logger_provider` expose the configured OpenTelemetry objects for integrations that accept explicit instances.

## Content policy

See [Data privacy](https://docs.hue.run/guides/redaction.md) for runnable email-masking examples and the correct attachment point for each integration.

`capture_content=False` omits input/output content from Hue's helpers **before it enters an OpenTelemetry queue** and, at export, strips recognized GenAI, OpenInference, OpenLLMetry, Langfuse and Vercel AI SDK content attributes, legacy `gen_ai.*` message events, log bodies and status descriptions from every record on Hue's export path, including spans from third-party instrumentors on a borrowed provider. The key list is identical to TypeScript's `contentPrefixes` and is reproduced in the [compatibility matrix](https://docs.hue.run/sdks/compatibility.md). `True` permits that content. The policy does not classify arbitrary attribute names, span names, session identifiers or another exporter's records; unrecognized custom keys pass through. Configure an external instrumentor's own content policy before enabling it.

When content is captured, export scrubs hosted-tool credentials (such as `authorization`, `authorization_token`, `headers` and `api_key`) in recorded tool definitions and raw requests. A span's own string attributes over Hue's inline limit upload separately, up to 1,000,000,000 bytes, and keep a 16 KiB prefix. Captured HTTP bodies follow the [HTTP capture limit](https://docs.hue.run/guides/redaction.md#http-content) instead. Inline media in the span attributes and log records that [automatic capture](https://docs.hue.run/guides/media.md#automatic-capture) reads uploads and leaves its digest in place; text media over 64 KiB keeps a 16 KiB UTF-8 prefix. Resources, links and span events never upload: inline media there up to 64 KiB stays as recorded and larger media becomes its digest. An `Attachment` (up to 25 MiB) uploads at its position, and `record_file` uploads supplied data up to 25 MiB only with `upload=True`. Uploads run in the background after their record is sent. A value refused when its record is exported falls back to a cut, to the digest without a `hue.blobs` entry in recorded messages, or to the inline bytes elsewhere; one whose upload fails afterwards keeps its prefix or digest and its entry. Both count in `export_status.upload_fallbacks`. Nothing uploads with `capture_content=False` or a setup credential. When metadata-only capture removes tool definitions, the record keeps `hue.tool.names` and `hue.tool.definitions.sha256`.

`redactor(field, value)` receives a bounded, detached content snapshot before helper JSON serialization. Supported inputs are ordinary built-in JSON-compatible scalars, dictionaries and lists, plus built-in tuples and scalar dictionary keys accepted by Python's JSON encoder. Container shape and nested values are preserved without sharing mutable application containers. When uploads are available, helper snapshots and redactors accept supported values up to 1 GB and 1,048,576 visited values and keys. Otherwise, the snapshot is bounded to 4 MiB, depth 64 and 65,536 values and keys. The budget counts UTF-8 string bytes plus value overhead; it is not a process-memory limit. The initial snapshot also runs when no redactor is configured. A redactor's returned value passes through a fresh snapshot with the same bounds before JSON encoding.

For supported HTTP CLIENT spans, `redactor` also handles URL identity in Hue's export copy, including metadata-only capture and spans from other instrumentation. Valid full URLs use `url.full` and any present `http.url` callback. Present `http.target` and `url.path` callbacks receive the pathname. Hue sanitizes callback results and omits URI attributes if a result fails or is invalid. Other exporters keep their original records.

A snapshot, redaction or serialization failure omits that field and increments `export_status.instrumentation_failures` without raising into application work. A redactor may mutate its copy without changing application inputs or results, but must not mutate globals or objects obtained through captured references. When uploads are unavailable, fields over Hue's inline value limit are cut to a UTF-8 prefix and listed under `hue.truncated`. JSON `None`, `False`, `0` and `""` remain distinct from omitted content. Received content is stored by Hue; the SDK does not set a retention timer.

## Delivery and shutdown

```python theme={null}
hue.validate_project() -> Project
hue.force_flush(timeout_millis: int = 30_000) -> bool
hue.shutdown(timeout_millis: int = 30_000) -> bool
hue.export_status -> ExportStatus
```

`validate_project()` returns a frozen `Project` with `id`, `name`, `slug` and `organization_id`. Authentication, connection or invalid-response failures raise `ProjectValidationError`; the exception does not contain the key. Validation sends no trace.

`force_flush()` sends traces and logs, then waits within the same deadline for pending uploads. It returns `False` on timeout, a processor failure, a closed client, or **any recorded failed export batch, dropped record or instrumentation failure during this client's lifetime**. Inspect `export_status.failed_trace_batches`, `failed_log_batches`, `uploaded_values`, `upload_fallbacks` and `ok`; upload fallbacks are warnings and do not make a flush fail.

A flush timeout bounds how long the caller waits; it does not cancel network work already running in the background. Timeout values must be positive integers. Queues are bounded and in memory; termination or overflow can lose telemetry. A successful flush does not prove that every operation was instrumented or that all parents have arrived.

`shutdown()` stops new helpers, drains and closes Hue-owned resources, then gives pending uploads up to 30 seconds more and abandons the rest, counted in `upload_fallbacks`. Borrowed tracer and logger providers and their other processors remain usable. A timeout returns `False` while shutdown continues; repeated calls wait for the same shutdown work. A `with Hue(...) as hue:` block calls `shutdown_safe(timeout_millis=1000)` on exit, but does not raise if that boolean is false. Use a checked flush when command success must require delivery:

```python theme={null}
if not hue.force_flush():
    raise RuntimeError("Hue did not acknowledge all telemetry.")
```

Exports use the official OTLP HTTP/protobuf exporters and their retry policy. Request bodies are gzip-compressed and carry a `hue-sdk-python/<version>` User-Agent ahead of the exporter's own token. HTTP errors, malformed acknowledgements and OTLP partial rejections count as failed batches. Partial rejections are not resent as a whole batch. Stop producing spans before shutdown; shared server clients should remain alive between requests.

## Live spans

OpenTelemetry exports a span only when it ends, so a long agent turn or model call would otherwise stay invisible until it finishes. When a Hue helper span or an AI span is still open at the export worker's next 0.5 s tick, Hue queues a placeholder: a standard OTLP span whose parent is the running span, with its name, kind, start time and current attributes and an end time of `0`. Hue shows the span, and its trace, as running and replaces the placeholder when the finished span arrives. Input set right after entering, such as `set_input`, is included. A placeholder whose span ends before it is exported is not sent.

A placeholder usually reaches Hue about 1.5 s after its span starts: up to 0.5 s until the next tick, then about 1 s while the export worker batches it. It arrives sooner when a batch is already scheduled and later while an earlier export is still in flight, because the worker runs the next tick and starts the next 1 s batch only after that export returns. A span shorter than about 1.5 s therefore usually never shows as running and appears only when it ends.

* Only spans from `hue.tracer` (every helper) and spans with a `gen_ai.`, `ai.`, `llm.` or `traceloop.` attribute at start, or a name starting with `ai.`, are announced. HTTP, database and other framework spans are not.
* Placeholders follow the same `capture_content` policy as finished spans. Tool definitions, system instructions and any value over 64 KiB are left out; the finished span still carries them.
* Placeholders carry the running span's name and attributes as set when the export worker builds them, so a value you overwrite before the span ends can still reach Hue. `capture_content=False` strips recognized content keys from them, and `redactor` rewrites helper content before the helper sets it on the span. Scrub any other sensitive attribute where you record it, or pass `live_spans=False`.
* Placeholders are advisory. A placeholder is queued only while the queue is under a quarter of its record and byte budgets and is skipped silently otherwise. While queued they count in `queued_trace_records` and `queued_trace_bytes`, but never as dropped or failed telemetry.
* Export hands placeholders to a separate delivery slot, which holds at most 64 placeholders and 1 MiB outside the queue counters and sends one request at a time. Export skips placeholders while the slot is busy. `force_flush()` and `shutdown()` never wait for it, so a slow placeholder request cannot delay completed spans, and a successful flush does not confirm that a span showed as running.
* Completed spans are exported in separate requests before placeholders, so their rejections stay visible. If the first trace acknowledgement lacks `Hue-Pending-Spans: 1`, the SDK sets `export_status.live_spans_rejected`, a warning that does not affect `ok`, and stops announcing spans; the receiver gets at most one placeholder request.
* Pass `live_spans=False` to send none.
* The SDK registers its span processor on the tracer provider itself and exports no processor to wrap. A provider that wraps it anyway never sees placeholders, so Hue still receives the running span's name and attributes even when the wrapper later drops or edits the span; such a wrapper should forward `on_end` for every span whose `on_start` it forwarded. A placeholder already sent for a span whose finished record never reaches Hue, for example because the span never ends, a wrapper withholds its end or the process exits before flushing it, leaves the span shown as running until Hue marks the trace stalled.

## Trace verification

```python theme={null}
confirmation = hue.verify_trace(
    trace_id,
    expected_span_ids=[request_span_id],
    required_fields=["model"],
    timeout_millis=10_000,
)
```

Returns a typed `TraceVerificationResult` with `verified`, `receipt: TraceReceipt | None` and `project: Project | None`, set when Hue reported the trace missing to name the project the key searched. A `TraceReceipt` has `trace_id`, `span_count`, `revision`, `fields`, `matched_span_ids`, `missing_span_ids`, and `trace_url`. `fields` is a `TraceReceiptFields` dataclass with `input`, `output`, `model`, `usage` and `session` booleans; it reports the presence of received fields without exposing their captured values. `verified` requires a stored receipt, every supplied expected span, and every required field. Timeout returns `verified=False` with the latest partial receipt, or `None` if none arrived; a `None` receipt with `project` means no trace with that ID exists in that project, so check which key the process loaded. Other failures raise exported `TraceVerificationError`, with `code` and optional `status_code`, without response bodies or credentials.

`expected_span_ids` and `required_fields` accept sequences. `required_fields` takes `TraceReceiptField` names: `"input"`, `"output"`, `"model"`, `"usage"` and `"session"`.

Trace IDs are 32 lowercase hexadecimal characters; expected span IDs are 16. All IDs must be nonzero. Supply at most 100 unique expected span IDs and unique required field names. The timeout defaults to 10,000 ms and must be positive, finite, and at most 60,000 ms. The receipt response is limited to 64 KiB.

Missing spans or required fields keep polling until the deadline. Only recognized trace-not-found responses, HTTP 429, and HTTP 503 are retried; connection failures, unsupported endpoints, redirects, and malformed responses raise a safe typed error. Verification reads stored normalized field presence across the trace, including supported correlated logs. It does not inspect values or prove that unlisted application operations were instrumented.

[Flush the owning providers before verification](https://docs.hue.run/sdks/python.md#verify); this method never flushes implicitly. An in-flight network read may finish in the background after the caller times out.

## Evaluation client

```python theme={null}
from hue_sdk.evals import EvaluationClient

client = EvaluationClient(
    api_key=os.environ["HUE_API_KEY"],
    timeout_seconds=10,
)
```

`EvaluationClient(base_url: str = "https://app.hue.run", api_key: str | None = None, *, timeout_seconds: float = 10, max_attempts: int = 4)` requires a valid **Read and write** project service key. Use `api_key=` for Hue Cloud or retain `EvaluationClient(base_url, api_key)` for an explicit origin; a bare key in the first position raises `TypeError` naming `api_key=`. Timeouts must be positive and finite.

Client methods are synchronous and return dictionaries. **Arguments use snake\_case; response fields and low-level completion payloads use HTTP camelCase.** `check_connection()` returns the current project. List methods accept keyword-only `after=None, limit=100`; limits are 1–100. Responses contain `items` and `nextCursor`. `list_eval_sets`, `list_evaluators`, `list_datasets` and `list_scorers` also accept `tags`, which keeps items carrying any of the named [tags](#tags).

Evaluation responses are limited to **4 MiB**. `list_cases(version_id, ...)` includes case content, so a valid row limit can still produce an oversized response when cases are large. Request a smaller page, such as `limit=1`, and pass each non-null `nextCursor` as `after`. The client does not automatically split or retry an oversized page.

### Eval sets, evaluators, runs and scoring

Use these product-named methods in new code. They call the same v1 endpoints as the dataset, scorer, experiment and evaluation-run methods in the next sections, accept product-named arguments such as `eval_set_version_id` and `evaluator_version_ids`, and return dictionaries with product fields, such as `evalSetId`, `evalSetVersionId`, `evaluatorVersionId`, `runId` and `scoringId`, alongside the v1 fields. The earlier method names are deprecated but remain callable for at least two more `0.MINOR` releases.

| Method | Parameters and result |
| - | - |
| `create_eval_set(*, name, slug, description="", tags=None)` / `get_eval_set(eval_set_id)` / `list_eval_sets(...)` | Eval set with initial `versions` / an eval set / page of summaries. |
| `update_eval_set(eval_set_id, *, name=None, slug=None, description=None, tags=None)` | Rename an eval set or replace its tags; omitted fields stay. |
| `create_eval_set_version(eval_set_id, *, from_version_id=None)` / `get_eval_set_version(version_id)` | New editable version / a version. |
| `list_eval_set_cases(version_id, ...)` / `add_eval_set_case(version_id, *, expected_revision, external_key, inputs, expected=MISSING, metadata=None, files=None)` | Page of cases / `{ "item": ..., "version": ... }`; retain the updated revision. `files` pins input files as on `add_case`. |
| `freeze_eval_set_version(version_id, expected_revision)` | Frozen eval set version. |
| `create_evaluator(*, name, slug, description="", tags=None)` / `get_evaluator(evaluator_id)` / `list_evaluators(...)` | Register or retrieve evaluator identities. |
| `update_evaluator(evaluator_id, *, name=None, description=None, tags=None)` | Rename an evaluator or replace its tags; omitted fields stay. |
| `publish_evaluator_version(evaluator_id, definition)` / `get_evaluator_version(version_id)` | Publish or retrieve an immutable evaluator version. |
| `create_run(*, idempotency_key, name, eval_set_version_id, evaluator_version_ids, config, tags=None)` | `{ "id": ..., "scoringId": ..., "evaluationRunId": ... }`. |
| `update_run(run_id, *, name=None, tags=None)` | Rename a run or replace its own tags → `{ "id", "name", "tags", "evalSetTags" }`. |
| `get_run(run_id)` / `list_run_items(run_id, ...)` / `get_run_case(run_id, case_id)` | Read pinned configuration and cases. |
| `start_run_execution(run_id, case_id, *, idempotency_key, ...)` / `get_run_execution(execution_id)` / `complete_run_execution(execution_id, payload)` | Start or recover an attempt / retrieve it / acknowledge its terminal outcome. |
| `finish_run(run_id, idempotency_key)` | `{ "id": ..., "finishedAt": ... }`. |
| `create_scoring(*, idempotency_key, name, subject_ids, evaluator_version_ids)` | `{ "id": ... }` for scoring saved subjects. |
| `get_scoring(scoring_id)` / `list_scorings(...)` / `list_scoring_items(scoring_id, ...)` / `get_scoring_subject(subject_id)` | Read a scoring pass, the project's scoring passes, its items and immutable saved evidence. |
| `submit_scoring_results(scoring_id, *, idempotency_key, results)` | `{ "ids": [...] }`; each result names its `evaluatorVersionId`. |
| `list_scoring_results(scoring_id, ...)` / `get_scoring_result(result_id)` | Result summaries / a stored result. |
| `list_tags()` | `{ "items": [...] }`, the project's tags in its order: as people arranged them in Hue, then newer tags. |

A run ID and a scoring ID identify different records.

### CI evaluation invocations

An invocation freezes the selected cases, evaluator versions, configuration and gate policy for one CI check. Use the [CI runner](https://docs.hue.run/evaluations/run-your-agent.md) for the complete execution and recovery flow. The same CLI can launch a Python agent; it ships in the TypeScript npm package. These low-level client methods require a Hue server with invocation support.

| Method | Parameters and result |
| - | - |
| `create_eval_invocation(*, idempotency_key, deadline_at, ...)` | Create or recover the invocation with its frozen manifest. Supply exactly one of `eval_set_id` or `eval_set_version_id`. |
| `get_eval_invocation_by_key(idempotency_key)` | Recover the saved invocation before resolving versions or choosing a new deadline. |
| `get_eval_invocation(invocation_id)` | Read the saved invocation and original receipt without running agents. Also accepts its candidate run ID. |
| `create_eval_baseline(invocation_id, *, idempotency_key, ci)` | Clone the candidate's frozen inputs for the base commit. `ci` must include `commitSha`; this call does not resolve newer versions. |
| `finalize_eval_invocation(invocation_id, *, idempotency_key, execution_ids=None)` | Freeze the server's gate receipt after execution and scoring settle. Calling early freezes an incomplete result. |
| `cancel_eval_invocation(invocation_id, *, idempotency_key, reason)` | Durably cancel execution and scoring. `reason` is `interrupted`, `deadline` or `runner_error`. |

Creation requires a key of 1–128 characters and `deadline_at`, an ISO 8601 timestamp with a timezone. Other keyword arguments are `name`, `evaluator_ids`, `evaluator_version_ids`, `config`, `policy`, `ci` and `baseline_run_id`. The `policy` dictionary carries absolute `thresholds` and optional `baselineComparisons`, each naming a pinned evaluator version and metric. The `ci` dictionary has `provider: "github"` or `"local"` and optional repository, commit and workflow identifiers. These nested dictionaries use camelCase keys.

Use a stable key for each control operation. Retry with the original key and body, including the original deadline. Every method returns a dictionary with `id`, `runId`, `runUrl`, `deadlineAt`, `state`, `manifest` and `receipt`. The manifest holds the frozen inputs and their digest. `receipt` is `None` until the server records an authoritative decision; otherwise its `verdict` is `pass`, `fail`, `incomplete`, `error` or `cancelled`, with the original scoring pass, execution IDs, results and reasons. Read that saved verdict instead of deriving a new one from later scores.

### Tags

Tags group eval sets, evaluators and runs, for example by the area of the agent they test. Methods take tag names: a name the project has no tag for creates one, and names match without case. `create_eval_set`, `create_evaluator` and `create_run` accept `tags`; `update_eval_set`, `update_evaluator` and `update_run` replace an item's tags with the names you pass (`[]` clears them); `list_eval_sets` and `list_evaluators` keep items carrying any of the named `tags`; and `list_tags()` returns the project's tags, each with `id`, `name` and `color`. Responses carry each item's `tags`. A run also shows its eval set's tags in `evalSetTags`; they are not its own, so `update_run` leaves them unchanged. The dataset, scorer and experiment methods take the same `tags`.

```python theme={null}
client.create_eval_set(name="Refunds", slug="refunds", tags=["billing"])
client.update_evaluator(evaluator_id, tags=["billing", "regression"])
billing = client.list_eval_sets(tags=["billing"])
```

### Datasets and scorer definitions

| Method | Parameters and result |
| - | - |
| `create_dataset(*, name, slug, description="", tags=None)` | Dataset with initial `versions`. |
| `update_dataset(dataset_id, *, name=None, slug=None, description=None, tags=None)` | Rename a dataset or replace its tags; omitted fields stay. |
| `get_dataset(dataset_id)` / `list_datasets(...)` | Retrieve a dataset / page of summaries. |
| `create_dataset_version(dataset_id, *, from_version_id=None)` | New editable version. |
| `get_dataset_version(version_id)` / `list_cases(version_id, ...)` | Retrieve a version / page of cases. |
| `add_case(version_id, *, expected_revision, external_key, inputs, expected=MISSING, metadata=None, files=None)` | `{ "item": ..., "version": ... }`; retain the updated revision. `files` pins up to 32 input files as `CaseFileWrite(role=..., artifact_id=...)`, or `CaseFileWrite(role=..., filename=..., content_type=..., data=... or path=...)`, which the client checks against the artifact policy (one of the 22 artifact content types, a name of 1–255 UTF-16 code units, 1 byte to 25 MiB) and uploads first; a file outside the policy raises `ValueError` before any request. A `path` file is hashed when the case is checked and read again for its upload, one file at a time; one that changed or can no longer be read raises `ValueError` and the case is not written. |
| `freeze_dataset_version(version_id, expected_revision)` | Frozen dataset version. |
| `create_scorer(*, name, slug, description="", tags=None)` / `get_scorer(scorer_id)` / `list_scorers(...)` | Register or retrieve scorer identities. |
| `update_scorer(scorer_id, *, name=None, description=None, tags=None)` | Rename a scorer or replace its tags; omitted fields stay. |
| `publish_scorer_version(scorer_id, definition)` / `get_scorer_version(version_id)` | Publish or retrieve an immutable scorer version. |

Use `MISSING` or omit `expected` to declare no reference. `None` is a present JSON-null reference. Freeze the dataset and publish scorer definitions before creating an experiment.

#### Scorer declarations and metrics

Scorer `definition` dictionaries use **camelCase** keys, even when supplied to a Python method.

| Definition | Required fields |
| - | - |
| Built-in | Use `builtin_scorers.exact_match()`, `builtin_scorers.includes(case_sensitive)` or `builtin_scorers.json_schema(schema)` for the exact versioned declaration. |
| Local code | `kind: "local_code"`, `language: "python"` or `"typescript"`, `entrypoint`, `sourceDigest`, `metrics`. `define_local_scorer` creates the Python declaration and binds the callback. |
| Manual | `kind: "manual"`, `metrics`. Completion requires the platform's human workflow. |
| Hosted judge | `kind: "llm_judge"`, `metrics`, `config`. Hosted dispatch is separate from a local run. |

Import the built-in bundle as `from hue_sdk.evals import builtin_scorers`. `builtins` remains an alias, but it shadows the standard-library module of the same name in any file that imports it. `builtin_scorers.json_schema` needs the optional `hue-run[evals]` extra (`jsonschema` and `referencing`); without it the helper raises `ImportError` and stored schema scorers report `SchemaValidatorUnavailable`.

Each metric definition has a `name` and `type`: `boolean`, `text`, `number` (optional `min`/`max`), or `category` (required `categories`, a list of strings). An optional `description` (1–500 characters) is shown with the metric's check in Hue's run view. Results must match the pinned definitions exactly.

Hosted `config` requires `model`, `provider`, `rubric`, `bindings` (a list of dictionaries with `name`, `path`, `required`), `maxOutputTokens` and `timeoutMs`; `temperature` is optional. The declaration states the requested policy; the server validates supported values and project execution settings when it is used.

### Experiments, saved subjects and results

| Method | Parameters and result |
| - | - |
| `create_experiment(*, idempotency_key, name, dataset_version_id, scorer_version_ids, config, tags=None)` | `{ "id": ..., "evaluationRunId": ... }`. |
| `update_experiment(experiment_id, *, name=None, tags=None)` | Rename an experiment or replace its own tags → `{ "id", "name", "tags", "evalSetTags" }`. |
| `get_experiment(experiment_id)` / `list_experiment_items(experiment_id, ...)` / `get_experiment_case(experiment_id, case_id)` | Read pinned configuration and cases. |
| `start_execution(experiment_id, case_id, *, idempotency_key, trace_external_id=None, previous_execution_id=None, allow_uncertain_retry=False)` | Start or recover an execution attempt. |
| `get_execution(execution_id)` / `complete_execution(execution_id, payload)` | Retrieve an attempt / acknowledge its terminal outcome. |
| `finish_experiment(experiment_id, idempotency_key)` | `{ "id": ..., "finishedAt": ... }`. |
| `create_evaluation_run(*, idempotency_key, name, subject_ids, scorer_version_ids)` | `{ "id": ... }` for rescoring saved subjects. |
| `get_evaluation_run(run_id)` / `list_evaluation_items(run_id, ...)` / `get_subject(subject_id)` | Read a run, its items and immutable saved evidence. |
| `submit_results(run_id, *, idempotency_key, results)` | `{ "ids": [...] }`. |
| `list_results(run_id, ...)` / `get_result(result_id)` | Result summaries / a stored result. |

`complete_execution` accepts a camelCase payload: required `idempotencyKey` and terminal `state` (`succeeded`, `error` or `cancelled`), with optional `output`, `error`, `expectedTraceRevision`, `traceEvidence` (`required` or `omit`) and `omissionReason`. It returns `executionId`, `subjectId`, `traceSnapshotId` and `evaluationItemId`.

Each submitted result requires `evaluationItemId`, `scorerVersionId` and the `Score` fields described below; a local-code result also carries `sourceDigest`. A scored result has `metrics` entries with `name`, `value` and optional `passed`, plus a nonempty `explanation` or an `evidence` value. Error results contain `error` with `type` and optional `message`; skipped results contain an `explanation`.

A read, an update that sets given fields (`update_eval_set`, `update_evaluator`, `update_run` and their dataset, scorer and experiment forms), or a mutation the server deduplicates by the `idempotencyKey` in its body, is sent again after a connection failure, a timeout or a 408 or 5xx without `Retry-After`, up to `max_attempts` (default 4, range 1–10) times with a jittered backoff; `is_transient_api_error(error)` names those failures. Any other mutation is sent once: preserve idempotency keys and returned IDs across retries after a lost response. `HueApiError.status` is the HTTP status when available, `HueApiError.diagnostic` Hue's `X-Hue-Diagnostic` code when it sent one, and `HueApiError.reason` is `malformed_response` for a body the client refused; errors do not echo server bodies. The client rejects invalid JSON before writes, does not follow redirects, and limits request/response bodies to 1 MiB/4 MiB.

Runner target outputs and built-in JSON Schema declarations are limited to 200,000 serialized bytes. JSON validation also enforces nesting depth 32 and 20,000 nodes; for an HTTP write, those structural limits apply to the complete request body. Values must use finite JSON numbers, valid Unicode without NUL, string dictionary keys, lists and dictionaries without cycles. Python integers outside `-(2**53 - 1)` through `2**53 - 1` are rejected; use strings for larger exact integers. The server can apply additional field-specific limits.

### Hosted judge jobs

`get_judge_budget()` reads the hosted judge configuration and the organization's [monthly AI budget](https://docs.hue.run/guides/redaction.md#monthly-ai-budget). Call `create_judge_jobs(run_id, *, idempotency_key, jobs)` with `jobs` entries containing `evaluationItemId` and `scorerVersionId`; the result contains `ids`. Inspect `list_judge_jobs(run_id, ...)` or `get_judge_job(job_id)`, and request cancellation with `cancel_judge_job(job_id, *, reason)`.

Submitting hosted jobs is explicit and draws on that budget. Method availability does not establish that the project has a configured provider or that the budget has room. Local runners leave hosted and manual pins for their owning workflows.

### Recorded media

`client.media` is a `MediaClient` that reads recorded files back by SHA-256 with a **Read** or **Read and write** key; a snapshot's pinned copy needs **Read and write**. See [Read recorded media back](https://docs.hue.run/guides/media.md#read-files-back).

| Member | Behavior |
| - | - |
| `fetch(*, sha256, trace_id=None, span_id=None, snapshot_id=None, max_bytes=67108864)` | Downloads one file through `GET /api/v1/traces/{traceId}/blobs/{sha256}` (or the snapshot's copy with `snapshot_id`), without the project key, and checks its SHA-256 → `MediaFile` with `data`, `sha256`, `size`, `content_type` and `file_name` (both `None` for a snapshot's copy). `max_bytes` is at most 1 GB. |
| `resolve(value, *, trace_id=None, span_id=None, snapshot_id=None, as_="data_url", concurrency=4, max_bytes=67108864, blobs=None)` | Writes the bytes of every digest part in `value` back into the part's own field, as a `data:` URL or base64 (`"data_url"`) or as `bytes` → `ResolvedMedia` with a new `value`, the count `resolved` and `failures`. `concurrency` is 1–16. `blobs` takes the record's `hue.blobs` entries in any form Hue reads. |
| `MediaFetchError` | Raised by `fetch`, with `reason`: `not_found`, `missing`, `unavailable`, `forbidden`, `too_large`, `digest_mismatch` or `failed`. A `forbidden` read of a snapshot's copy says that it needs a **Read and write** key; the keyword-only `snapshot` argument selects that message. An unavailable answer, a lost connection or a timeout is asked once more, after a `Retry-After` of up to 10 seconds. |
| `MediaResolveFailure` | A part `resolve` or `rehydrate_media` left unchanged: `pointer` (RFC 6901), `sha256` and `reason`, a `MediaFetchError` reason, `not_found` for no matching local file, or `prefix_only` for a part holding only the first 16 KiB of its file. |
| `rehydrate_media(value, files, *, as_="data_url")` | Writes case files (`LocalFile`, `ManagedInputFile`, or any object with `sha256`, `data` or `path`, and optional `content_type`) back into the digest parts of `value` by SHA-256 → `ResolvedMedia`. |

The client also exposes the artifact methods that case files use: `reserve_artifact`, `request_artifact_upload`, `upload_artifact_bytes`, `complete_artifact`, `get_artifact` and `download_artifact`, which raises `ArtifactSizeError` for bytes past the size its caller expected.

## Run locally and rescore

```python theme={null}
run_experiment(
    *, client, hue, experiment_id, target,
    checkpoint_directory, persist_result_content, trace_evidence,
    scorers=None, concurrency=20, schema_timeout_millis=2000, files_directory=None,
) -> RunnerReport

rescore(
    *, client, run_id, checkpoint_directory, persist_result_content,
    scorers=None, concurrency=20, schema_timeout_millis=2000, files_directory=None,
) -> RunnerReport
```

Both are exported from `hue_sdk.evals` and are synchronous entry points. They support sync or async target/scorer callbacks inside worker threads. From an async application, call the runner through `asyncio.to_thread`.

| Option | Behavior |
| - | - |
| `checkpoint_directory` | Required `str` or `Path`, dedicated to this run. Preserve it for upload recovery; keep it out of Git. Checkpoint guarantees require a POSIX filesystem with private permissions and no-follow opens. |
| `persist_result_content` | Required boolean, independent of telemetry capture. |
| `trace_evidence` | Required for `run_experiment`: `TraceEvidence("required")`, `TraceEvidence("omit", "reason")` or `TraceEvidence("pending")`. With `"pending"`, a case whose export `force_flush` did not acknowledge completes in its true state with its trace evidence pending and the count of spans it ended; Hue attaches the trace once it holds every span, or records the evidence as omitted a day later. Only `"omit"` carries a reason. |
| `target` | Receives `(inputs, TargetContext)` and returns a JSON output, or an awaitable of one. `TargetContext` has `config`, `item`, `span` and `files`, a tuple of `LocalFile` copies of the case's agent-visible input files (`artifact_id`, `role`, `filename`, `content_type`, `byte_size`, `sha256`, `path`). |
| `files_directory` | Default `<checkpoint_directory>/files`. Before an execution starts, the runner downloads the case's pinned input files here and checks each one's size and SHA-256; a mismatch raises `CaseFileError` without spending the execution. Evaluator-only files reach local code scorers only after the target finishes and are removed when the case ends. |
| `scorers` | Optional list of bound `LocalScorer` objects. |
| `concurrency` | Default `20`; positive safe integer. |
| `schema_timeout_millis` | Default `2000`; integer `100–60000`; bounds JSON Schema validation, not arbitrary callbacks. |

Telemetry and evaluation clients must use the same project and origin. `rescore` requires an evaluation run created from saved subject IDs and has **no target callback**. `RunnerReport` exposes `run_id`, `subject_ids`, `result_ids` and `deferred_scorer_version_ids`.

The native Python local runner downloads pinned input files but does not automatically upload files its target generates or provide a `with_files` result helper. For generated documents, use the [shared CLI](https://docs.hue.run/sdks/cli.md#run-an-evaluation) with a Python command, or the separate [managed target adapter](#managed-target-adapter) with `ManagedOutputFile`. Rescoring can read files already attached to saved subjects.

Returning `MISSING` means unavailable output; returning `None` is JSON null. With `persist_result_content=False`, completions and local checkpoints omit raw output, target error messages, scorer evidence and arbitrary explanations. Typed metric values, including custom text values, remain stored. Existing dataset inputs/references are independent of this setting. Historical scoring skips unavailable output without invoking a scorer callback.

### Local scorer exports

| Export | Behavior |
| - | - |
| `builtin_scorers.exact_match()` | Publishable typed JSON equality definition. |
| `builtin_scorers.includes(case_sensitive=True)` | Publishable string-inclusion definition. |
| `builtin_scorers.json_schema(schema)` | Publishable JSON Schema draft 2020-12 definition; requires the `hue-run[evals]` extra. |
| `define_local_scorer(*, source, entrypoint, metrics, score)` | Returns `LocalScorer`; source is text or bytes. |
| `score_locally(version, context, *, scorers=None, schema_timeout_millis=2000)` | Returns `Score` without uploading it. |

`ScoreContext` contains `inputs`, `has_output`, `has_expected`, optional `output`/`expected`, `metadata`, `execution_state` and, when the case or subject has files, `files`. A `Score` is `scored` with declared metrics and explanation/evidence, `error` with a typed error, or `skipped` with an explanation. A false quality verdict remains a scored result, with `passed: False`.

The source digest binds an explicitly supplied source declaration to the local scorer; it does not attest closures or installed dependencies. Custom callbacks have no general execution timeout or side-effect cancellation. JSON Schema uses an isolated subprocess with a deadline and no remote schema fetches. Hosted pins require judge-job dispatch; `score_locally` does not run a hosted judge.

### Recovery errors

| Error | Meaning |
| - | - |
| `UncertainExecutionError` | No durable outcome is available. Exposes `case_id` and optional `execution_id`; the runner refuses to repeat potentially completed work. |
| `OutcomeSerializationError` | The target returned, but its outcome could not be saved as JSON. Exposes `execution_id`; the runner does not invoke the target again. |
| `TelemetryExportError` | A saved target outcome lacks required trace acknowledgement. Exposes `execution_id`; a new empty exporter cannot prove prior receipt. |

Use one checkpoint directory per experiment or rescore run. Checkpoint files contain allowed result content and are private local files, not encrypted storage. Resume an upload failure with the same run, directory and options so saved payloads and idempotency keys are reused. After a process crash, confirm its recorded owner has stopped before removing `.lock`; removing the lock never authorizes another target invocation.

For uncertain work, investigate side effects before starting another attempt. The low-level `start_execution` method requires the latest `previous_execution_id` for a replacement attempt and `allow_uncertain_retry=True` to replace a still-started attempt. Restarting a runner does not grant either permission or automatically adopt an externally created attempt. Use a new experiment for an intentional fresh target run after investigating.

Required evidence waits for both signals after the root span ends. Omission is an explicit policy, never an automatic fallback after export failure. For a runnable example, see the public [Local evaluations](https://docs.hue.run/evaluations/first-evaluation.md).

## World client

`hue_sdk.world.WorldClient` uses the canonical World and instance routes; `hue_sdk.environment.EnvironmentClient` below keeps the original routes. Both require a Hue deployment serving their routes. `create_instance` accepts `world_version_id` where the compatible `create_run` accepts `environment_version_id`; `get_instance` and `finish_instance` read and finish that runtime instance.

`WorldInstance` and `WorldCoverage` are canonical names for `EnvironmentRun` and `EnvironmentCoverage`. `HueWorldError` is the same class as `HueEnvironmentError`. `WorldCreationError` identifies a failed instance creation before the agent acts. `WorldSealTimeoutError` and the compatible `EnvironmentSealTimeoutError` identify a `wait_for_seal` timeout after the completion grace.

### Reconstructed Worlds

`hue_sdk.world.WorldModelClient` reads the retained history of a `WorldEntity`, a dictionary with `namespace` and full `id`, scoped to the project key. A `WorldModel` records that identity, its committed `evidenceCutoff` and its status. `WorldModelAccount` describes one app account binding, including its full `accountId`, connection `generation` and optional `scope`; multiple accounts can belong to the same app. Results are typed dictionaries with the API's camelCase keys.

| Method | Result |
| - | - |
| `create_model(*, entity, name=None)` / `get_model(model_id)` | `WorldModelResult`, `{"worldModel": WorldModel}`. |
| `list_models(*, after=None, limit=None)` / `list_accounts(model_id, *, after=None, limit=None)` | `WorldModelPage` / `WorldModelAccountPage`, each with `items` and optional `nextCursor`; `limit` is 1–100. |
| `materialize(model_id, *, at, cancel_event=None)` | `StartingWorldResult`, `{"world": StartingWorld}`, without a running instance. `StartingWorld` pins the represented time, evidence cutoff and immutable digest. |
| `start_instance(model_id, *, idempotency_key, at, ttl_seconds=None, cancel_event=None)` | `WorldInstanceResult`, `{"world": StartingWorld, "instance": WorldHandoff}`, containing the starting World and a fresh handoff. |
| `reproduce_instance(instance_id, *, idempotency_key, ttl_seconds=None, cancel_event=None)` | A fresh instance from the original immutable starting World. |
| `erase_model(model_id)` | `ErasedWorldModel`, `{"erased": True}`. Erased starting Worlds cannot be reproduced. |

When Hue reports progress, `WorldModel.processing` contains `WorldModelProcessing`: its indexing state, retained and ready evidence cutoffs, and whether evidence is pending. `StartingWorldResult.preparation` and `HueWorldError.preparation` optionally contain `WorldPreparationProgress`, whose `state` is a `WorldPreparationState` and which also names the selected evidence cutoff. These dictionaries retain the API's camelCase keys. Error progress includes only validated fields from at most 16 KiB of response data; unrelated response content is discarded.

If a response carries `world_insufficient_evidence` or `world_processing_limit`, the client stops retrying that request. Other transient diagnostics retain the retry behavior below.

Materialization, instance creation and reproduction wait up to 120 seconds only after HTTP `503` with `X-Hue-Diagnostic: world_preparing`, separately from ordinary `max_attempts`. Retries preserve the serialized body and idempotency identity. Pass a `threading.Event` as `cancel_event` to cancel the wait or an active HTTP read. Other failures retain the configured attempt limit; a preparing or incomplete World is not a usable starting state.

### Compatible environment client

```python theme={null}
import os

from hue_sdk.environment import EnvironmentClient

environments = EnvironmentClient(api_key=os.environ["HUE_API_KEY"])
```

`hue_sdk.environment` is a synchronous client for Hue's simulated instances. Pass a **Read and write** project service key as `api_key=`; `base_url` defaults to Hue Cloud, and a bare key in the first position raises `TypeError`. `timeout_seconds` (default `10`) bounds each request and `max_attempts` (default `4`, integer `1–10`) bounds retries. It creates, drives, seals and reads instances of published World versions; it does not publish Worlds, bind tools or run your agent. `run_simulation` has no Python counterpart.

| Method | Result or purpose |
| - | - |
| `create_run(*, idempotency_key, environment_version_id, execution_id=None, seed=None, max_steps=None, ttl_seconds=None, traceparent=None, agent_revision=None)` | `EnvironmentRun`. Creates or replays one fresh isolated instance. `traceparent` is the case span's version-00 W3C trace context, whose trace ID must be the trace the execution declared; `agent_revision` (1–256 characters) joins the instance's fingerprint. |
| `get_run(run_id)` | `RunState`, the current or sealed instance. Missing coverage fields read as `validity: "not_assessed"` and `coverageGap: None`. |
| `act(run_id, *, invocation_id, action, args=None)` | `ActionResult`. Repeat the same UUID invocation ID and arguments to replay a recorded result. |
| `list_steps(run_id, *, after=None, limit=None)` | `StepPage`. Pages the journal by step ordinal; `limit` is 1–100. |
| `finish_run(run_id, *, idempotency_key, status)` | `SealedRun`. Seals the instance as `"completed"` or `"abandoned"`. |
| `record_coverage_gap(run_id, *, idempotency_key, provider, operation, code, args, description)` | `CoverageGapResult`. Records a known coverage gap; `idempotency_key` is a UUID and `args` at most 16,000 JSON bytes. |
| `get_evidence(run_id, *, section="all", bodies=True)` | A dictionary with the sealed instance's evaluator-only evidence. `section` is `"all"`, `"start"`, `"end"`, `"diff"` or `"ledger"`; `bodies` includes ledger request and response bodies. |

Responses are typed dictionaries that keep the API's camelCase keys, with the same fields as the [TypeScript types](https://docs.hue.run/reference/typescript.md#runs-actions-and-journals): `EnvironmentRun`, `RunState`, `ActionResult`, `ActionDefinition`, `ActionParameter`, `ActionSchema`, `Observation` (`OkObservation` or `ErrorObservation`), `Effect`, `Step`, `StepPage`, `SealedRun`, `CoverageGap`, `CoverageGapReporter`, `CoverageGapResult` and `EnvironmentCoverage`. `Json`, `RunStatus` and `FinishStatus` are the matching aliases.

Unlike `EvaluationClient`, this client retries every call, including mutations, because each carries an identity Hue deduplicates. It retries transport failures and HTTP 408, 429, 500, 502, 503 and 504 with backoff, and waits Hue's `Retry-After` on 429 and 503, at most 10 seconds. Failures raise `HueEnvironmentError`, whose message never includes response text or credentials; `status` is the HTTP status or `None`, and `retry_after` is the bounded wait in seconds. Responses are limited to 4 MiB and request bodies to 1 MiB.

### World handoff

Where Hue's simulation gateway serves an instance, `create_run` also returns its handoff: a world token, one mirror URL per pinned provider surface, environment variables and an MCP configuration. Hand these to the agent instead of the project key. `world_handoff` returns `None` for an instance created while a deployment's gateway is off.

```python theme={null}
import subprocess

from hue_sdk.environment import agent_environment, mcp_config_file, world_handoff

run = environments.create_run(
    idempotency_key=f"execution:{execution_id}",
    environment_version_id=version_id,
    execution_id=execution_id,
    traceparent=f"00-{trace_id}-{span_id}-01",
    agent_revision="my-agent@1.4.2",
)
status = "abandoned"
try:
    world = world_handoff(run)  # None when the world has no handoff
    if world is None:
        raise RuntimeError("This deployment does not serve gateway worlds.")
    with mcp_config_file(world) as path:  # removed after the block
        child = {**agent_environment(world), "MCP_CONFIG": path}
        subprocess.run(agent_command, env=child, check=True)
    status = "completed"
finally:
    # Seal a failed or unrun attempt as abandoned, never as completed.
    environments.finish_run(
        run["id"], idempotency_key=f"execution:{execution_id}:{status}", status=status
    )
```

| Function | Behavior |
| - | - |
| `world_handoff(run)` | The `WorldHandoff` of a create or replay response, or `None` for an instance without one. Keeps only `HUE_WORLD_*`, `BAGGAGE`, `TRACEPARENT`, and each surface's `HUE_SIM_*_URL`, `HUE_SIM_*_ALIAS` or `HUE_SIM_*_TOKEN` from the server's `env`; other names are dropped. |
| `agent_environment(world, *, parent=None, include_hue_credentials=False, legacy_mcp_variables=True)` | Environment variables for the agent's child process: `parent` (default `os.environ`) without Hue control-plane credentials or instance variables, then the instance's `env`, which wins. Use the filtered handoff from `world_handoff`. `legacy_mcp_variables` also sets `HUE_MCP_URL`, `HUE_MCP_TOKEN` and `HUE_MCP_EXPIRES_AT` from the first MCP mirror. |
| `mcp_config_file(world, *, directory=None)` | Context manager that writes `mcpConfig` to an owner-only `mcp.json` in a private directory, yields its path and removes the directory afterwards. |
| `legacy_mcp_capability(world)` | `LegacyMcpCapability`, `{"url", "token", "expiresAt"}` for the first MCP mirror, or `None` without an MCP surface. |
| `world_now(source=None)` | The instance's clock as an aware `datetime`, from a handoff's `now` or from `HUE_WORLD_NOW` in the given environment (`os.environ` by default); `None` when neither names it, so fall back explicitly with `world_now() or datetime.now(timezone.utc)`. |
| `strip_hue_control_plane_credentials(parent)` | A copy of `parent` without Hue control-plane credentials. |
| `without_world_variables(environment)` | A copy without `HUE_WORLD_*`, `HUE_SIM_*_URL`, `HUE_SIM_*_ALIAS`, `HUE_SIM_*_TOKEN` and legacy `HUE_MCP_CONFIG`, `HUE_MCP_URL`, `HUE_MCP_TOKEN` and `HUE_MCP_EXPIRES_AT` variables. |
| `is_hue_control_plane_credential(name, value)` | `True` for a name in `HUE_CONTROL_PLANE_VARIABLES` (`HUE_API_KEY`, `HUE_MCP_KEY`, `HUE_PROJECT_KEY`, `HUE_SERVICE_KEY`) or a value carrying a prefix from `HUE_CONTROL_PLANE_CREDENTIAL_PREFIXES` (`hue_sk_`, `hue_attempt_`, `hue_mcp_`, `hue_setup_`, `hue_inv_`, `hue_install_`, `hue_at_`, `hue_rt_`, `hue_oauth_`) anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. A world token or `hue_sim_` capability is not one. |

`world_handoff` and `mcp_config_file` accept HTTP MCP server entries only. They retain each entry's `type`, `url` and `headers`, drop other fields, and reject a non-HTTP transport with `ValueError`.

`WorldHandoff` has `id`, `token` (a `hue_world_` credential that lives as long as the instance), `expiresAt`, `lifecycle` (`WorldLifecycle`: `pending`, `live`, `completing` or `sealed`), `completingUntil`, `traceparent`, `baggage`, `surfaces` (`WorldSurface` entries with `provider`, `surface`, `providerInstanceKey`, `url` and `alias`), `env` (`HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `BAGGAGE`, `TRACEPARENT` and one `HUE_SIM_<SURFACE ID>_URL` per surface) and `mcpConfig` (`WorldMcpConfig`, the common `mcpServers` shape of `WorldMcpServer` entries with the token as a bearer). `RunState` of a gateway instance adds advisory `flags` (`WorldFlag`: `no_calls` or `fingerprint_differs`) and never returns the token; `WorldEvidenceSection` names the evidence sections.

A `WorldSurface` may add an account-scoped `token` and `connection: WorldSurfaceConnection`. Prefer the surface token when present. The connection describes `root` (`url`, optional `replaces`), accepted `auth` placements (`header`, `scheme`, `format`) and optional `replaces`, `accountIds`, `versions`, `headers` and `clients`. Token placeholders refer to the surface token when present, otherwise the world token. Older servers may omit `connection`.

`WorldClientHint` entries in `clients` identify the client `package`, `language`, credential option `credential` and `options` (`name` and `value`). Optional `note` and `unavailable` (`alias_host`, `account_id` or `https_only`) explain why a configuration cannot be used.

Finishing a gateway instance answers `lifecycle: "completing"` with `sealedAt: None`; the seal follows a 5-second grace. `get_evidence` needs the project key, and an open instance answers `409` until it is sealed. Nothing in these helpers logs the token. Keep the handoff out of your own logs and checkpoints.

## Managed target adapter

`ManagedTargetHandler` from `hue_sdk.managed` requires `machine_credential`, a synchronous `target` callback and `flush_telemetry`. Optional arguments are `tracer`, `base_url`, `max_execution_millis` (default 90000, at most 90000) and `finalization_millis` (default 30000, at most 30000). Pass `tracer=hue.tracer` with a Hue-owned client; without it the handler falls back to the global tracer, its span is not recorded and every invocation returns `uncertain`.

`handle(payload, headers)` accepts bounded raw JSON bytes or a dictionary and returns `ManagedResponse` with `status_code`, `body` and `headers`. The target receives a `ManagedTargetContext` with `execution_id`, `attempt`, `input`, `config`, `input_files`, the `cancelled` event, `deadline_monotonic` and `trace_id`; `input_files` is a tuple of `ManagedInputFile` entries with `artifact_id`, `filename`, `content_type`, `byte_size`, `sha256`, `role` and the verified `data` bytes. It returns `ManagedTargetResult`; generated files use `ManagedOutputFile`, with one of the 22 content types TypeScript lists as [`outputContentTypes`](https://docs.hue.run/reference/typescript#file-based-cases). Any other type, such as `audio/pcm`, records the invocation as an error before any upload; before 0.10.0 Python accepted any valid media type. Calls use the existing tracing providers. A false flush result leaves telemetry pending. See [managed runs](https://docs.hue.run/evaluations/managed-runs.md) for framework integration, cancellation and recovery.

## Serving lifecycle

Import `create_hue_safe` from `hue_sdk`. It accepts the same constructor arguments as `Hue`, catches ordinary initialization failures and returns a disabled client with an instrumentation failure. `enabled=False` needs no API key and does not attach to a supplied provider. Initialize once per serving process after fork; inherited clients no-op instead of reusing parent worker locks.

`force_flush_safe(timeout_millis=1000)` and `shutdown_safe(timeout_millis=1000)` return booleans without raising. Observe `export_status`; it includes `instrumentation_failures`, `dropped_trace_records`, `dropped_log_records`, `queued_trace_records`, `queued_log_records`, `queued_trace_bytes`, `queued_log_bytes`, `uploaded_values` and `upload_fallbacks`. Queued counts include in-flight records; health is cumulative.

Constructor options `max_queue_size=2048` and `max_queue_bytes=8388608` bound each signal's retained telemetry; up to 128 MiB of large values and inline files can be held separately while awaiting upload. Encoded bytes are not total process RSS. HTTP acknowledgements are capped at 64 KiB; 429 and Retry-After are honored within the transport budget. One retained network worker per signal, and one for [live-span placeholders](#live-spans), bound blocked network work, although Python cannot forcibly cancel every blocked system call. After a request timeout, each worker may retain up to 1 MiB of encoded request data outside queue counters. Later batches stay queued within their limits until transport recovery; shutdown counts any queued records it must discard. See [Python production setup](https://docs.hue.run/sdks/python.md#production-setup).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.