Stream

Typed event model and NDJSON stream wrapper for Arena streaming endpoints. Used internally by the client for real-time progress during validation, profiling, and training submission.

Events

class agilerl.arena.stream.StatusEvent(stage: str, status: str, message: str, detail: dict[str, Any], raw: dict[str, Any], kind: str = 'status', level: str | None = None)

A stage-progression or warning event (kind: "status" or kind: "warning").

Parameters:

  • stage (str) – The stage of the event.

  • status (str) – The status of the event.

  • message (str) – Human-readable message.

  • detail (dict[str, Any]) – Structured payload from the detail envelope field.

  • raw (dict[str, Any]) – The full raw JSON payload.

  • kind (str) – The envelope kind field ("status" or "warning").

  • level (str | None) – The envelope level field. .

class agilerl.arena.stream.CheckEvent(name: str, success: bool | None, warnings: list[str], error: str, raw: dict[str, Any])

An individual validation-check result.

Parameters:

  • name (str) – The name of the check.

  • success (bool | None) – The success of the check.

  • warnings (list[str]) – The warnings of the check.

  • error (str) – The error of the check.

  • raw (dict[str, Any]) – The raw message of the event.

class agilerl.arena.stream.ErrorEvent(message: str, extras: dict[str, ~typing.Any] = <factory>, raw: dict[str, ~typing.Any] = <factory>)

An error returned by the server inside the stream.

Parameters:

  • message – Primary error message.

  • extras – Supplementary context (e.g. available entrypoints).

  • raw – The full raw JSON payload.

class agilerl.arena.stream.LogEvent(text: str)

Fallback event for plain text or unrecognised JSON.

Parameters:

text (str) – The text of the event.

Parsing

agilerl.arena.stream.parse_ndjson_line(line: str) → StatusEvent | CheckEvent | ErrorEvent | LogEvent

Parse a single NDJSON line into a typed StreamEvent.

Every line from the backend is a uniform envelope with a kind field. Dispatch order:

  1. kind:"status" + status:"failed" -> ErrorEvent

  2. kind:"status" (other statuses) -> StatusEvent

  3. kind:"check" -> CheckEvent

  4. Anything else -> LogEvent

Parameters:

line (str) – The NDJSON line to parse.

Returns:

The parsed StreamEvent.

Return type:

StreamEvent

Stream Iterator

class agilerl.arena.stream.NDJsonStream(response: httpx.Response, *, handler: Callable[[StreamEvent], None] | None = None, renderer: SupportsClose | None = None, error_cls: type[ArenaAPIError] | None = None)

Iterator + context-manager over an NDJSON HTTP response.

Yields StreamEvent objects and tracks the final result for convenient access after iteration.

Parameters:

  • response (httpx.Response) – The HTTP response to iterate over.

  • handler (Callable[[StreamEvent], None] | None) – Callback invoked for each event. None means silent.

  • renderer (object | None) – Optional renderer to close when the stream is fully consumed.

Usage:

# Iterate events
with client.validate_environment(name="MyEnv") as stream:
    for event in stream:
        ...
    print(stream.result)

# Or just collect the final result
result = client.validate_environment(name="MyEnv").collect()
close() → None

Close the renderer (if any) and the underlying HTTP response.

collect() → dict[str, Any]

Consume all events and return the final result dict.

Returns:

The final result dict.

Return type:

dict[str, Any]

Raises:

ArenaAPIError – If the server reported a failure inside the stream (the endpoint-specific subclass when one is registered).

property error: ErrorEvent | None

First server-side error event seen in the stream, if any.

Returns:

The first ErrorEvent, or None.

Return type:

ErrorEvent | None

property result: dict[str, Any] | None

Final result payload, populated after a completion event is yielded.

Returns:

The final result dict.

Return type:

dict[str, Any] | None