Structured payload types for inter-stage communication.
Categories under OmniPayload: hidden_states – intermediate / output hidden-state tensors embed – embedding tensors (prefill, decode, special tokens) ids – token-ID sequences codes – codec / audio code tensors meta – scalar metadata, control flags, shapes
Bases: _StructBase
Bases: _StructBase
Bases: _StructBase
Bases: _StructBase
deserialize_payload(
wire: AdditionalInformationPayload,
) -> OmniPayload
Deserialize an AdditionalInformationPayload back to OmniPayload.
Decodes entries to tensors/lists, then uses :func:unflatten_payload to reconstruct the nested structure.
Flatten a nested OmniPayload to dotted keys.
Nested sub-dicts under _NESTED_KEYS are expanded: {"codes": {"audio": tensor}} → {"codes.audio": tensor}. hidden_states["layers"] is expanded to hidden_states.layer_N. Top-level values are kept as-is.
serialize_payload(
payload: OmniPayload,
) -> AdditionalInformationPayload | None
Serialize an OmniPayload for EngineCore transport.
Uses :func:flatten_payload to produce dotted keys, then converts each value to an AdditionalInformationEntry.
to_dict(struct: OmniPayloadStruct) -> dict[str, Any]
Convert OmniPayloadStruct to a plain dict, dropping None fields.
to_struct(payload: dict[str, Any]) -> OmniPayloadStruct
Convert a payload dict into OmniPayloadStruct, validating types.
Raises msgspec.ValidationError on: * unknown top-level keys (typos, legacy flat keys) * unknown sub-keys under any nested category * type mismatches (e.g., meta.left_context_size not an int)
Unflatten dotted keys back to nested dicts.
Reverse of :func:flatten_payload. hidden_states.layer_N keys are collected into hidden_states.layers.
Validate a payload matches the OmniPayload schema, raising on drift.
Wraps :func:to_struct and re-raises msgspec.ValidationError with the call-site context prepended. None is allowed (treated as "no payload to check").