API Reference

Protocols

`FormatMapper`

One wire format's typed bidirectional mapping to the canonical IR.

Concrete mappers implement the same operations the container-facing RelayMapperProtocol declares; the registry in the relay engine holds FormatMapper implementations.

format

property format() -> RelayFormat

source

The wire format this mapper serves; concrete mappers define it.

request_to_ir

def request_to_ir(
    payload: Any,
    *,
    context: ConversionContext
) -> Result[RelayRequest, RelayError]

source

Convert a source request DTO into canonical RelayRequest.

ir_to_request

def ir_to_request(
    request: RelayRequest,
    *,
    context: ConversionContext
) -> Result[Any, RelayError]

source

Convert a canonical RelayRequest into the target request DTO.

response_to_ir

def response_to_ir(
    payload: Any,
    *,
    context: ConversionContext
) -> Result[RelayResponse, RelayError]

source

Convert a source response DTO into canonical RelayResponse.

ir_to_response

def ir_to_response(
    response: RelayResponse,
    *,
    context: ConversionContext
) -> Result[Any, RelayError]

source

Convert a canonical RelayResponse into the target response DTO.

stream_to_delta

def stream_to_delta(
    event: Any,
    *,
    state: StreamState
) -> Result[tuple[StreamDelta, Ellipsis], RelayError]

source

Convert one source stream event into canonical StreamDeltas.

delta_to_stream

def delta_to_stream(
    delta: StreamDelta,
    *,
    state: StreamState
) -> Result[tuple[Any, Ellipsis], RelayError]

source

Convert one canonical StreamDelta into target stream events.

Classes

`ConversionContext`

source

Per-conversion context with nil-safe callbacks and a loss sink.

Attributes: options: Cross-protocol adaptation options. Zero-value when the host supplied no context. default_max_tokens: Claude max_tokens fallback lookup, always callable. safety_setting: Gemini safety threshold lookup, always callable. supports_image_generation: Gemini image-generation capability lookup, always callable. preserve_thinking_suffix: Thinking-suffix bypass policy lookup, always callable. media_resolver: Resolver for URL media, or None. upstream_model: Host model name substituted when the source payload carries no model; empty when unset. losses: Semantic losses recorded during conversion.

wrap

def wrap(
    cls,
    context: RelayConversionContext | None
) -> ConversionContext

source

Adapt a host context, substituting nil-safe defaults.

Parameters

Parameter	Type	Description
`context`	RelayConversionContext \| None	Host context, or ``None`` when the gateway supplied none.

Returns

Type	Description
ConversionContext	An adapter with callable callbacks and the host's loss list.

max_tokens_for

def max_tokens_for(model: str) -> int | None

source

Return the default max_tokens for model.

Negative callback results are treated as invalid and yield None; mappers apply their own missing-option policy.

Parameters

Parameter	Type	Description
`model`	str	The already-selected upstream model name.

Returns

Type	Description
int \| None	A non-negative default, or ``None`` when absent or invalid.

normalize_model

def normalize_model(model: str) -> str

source

Normalize a model name without selecting a different model.

Parameters

Parameter	Type	Description
`model`	str	Raw model name from the source payload.

Returns

Type	Description
str	The cleaned model name.

resolve_model

def resolve_model(model: str) -> str

source

Normalize a model name, substituting the host upstream model.

Empty source model names (e.g. Gemini responses that carry no model) fall back to the host upstream_model so downstream requests still identify the model.

Parameters

Parameter	Type	Description
`model`	str	Raw model name from the source payload.

Returns

Type	Description
str	The cleaned model name, or the upstream fallback.

`RelayConverterEngine`

source

Explicit source/target conversion over a caller-owned registry.

Parameters

Parameter	Type	Description
`registry`		The registry used when a conversion call does not pass its own ``registry`` override.

__init__

def __init__(registry: RelayRegistryProtocol) -> None

source

Initialise the engine with a default registry.

convert_request

def convert_request(
    payload: RelayRequestPayload,
    source: RelayFormat,
    target: RelayFormat,
    *,
    context: RelayConversionContext | None = None,
    registry: RelayRegistryProtocol | None = None
) -> Result[RelayConvertResult[RelayRequestPayload], RelayError]

source

Convert a request payload from source to target.

convert_response

def convert_response(
    payload: RelayResponsePayload,
    source: RelayFormat,
    target: RelayFormat,
    *,
    context: RelayConversionContext | None = None,
    registry: RelayRegistryProtocol | None = None
) -> Result[RelayConvertResult[RelayResponsePayload], RelayError]

source

Convert a non-stream response payload from source to target.

new_stream_session

def new_stream_session(
    source: RelayFormat,
    target: RelayFormat,
    *,
    options: RelayStreamOptions | None = None,
    context: RelayConversionContext | None = None,
    registry: RelayRegistryProtocol | None = None
) -> Result[RelayStreamSessionProtocol, RelayError]

source

Create a stateful stream session for one upstream stream.

Stateful stream conversion is delivered by the shared stream lifecycle in a later task; every current route reports no stream support.

convert_stream_chunk

def convert_stream_chunk(
    session: RelayStreamSessionProtocol,
    event: Any
) -> tuple[Any, Ellipsis]

source

Convert one source stream event through session.

Raises

Exception	Description
RelayError	Stateful stream conversion is not implemented yet.

finalize

def finalize(session: RelayStreamSessionProtocol) -> tuple[Any, Ellipsis]

source

Close a stream deterministically and return terminal events.

Raises

Exception	Description
RelayError	Stateful stream conversion is not implemented yet.

`RelayConverterRegistry`

source

Caller-owned registry of format mappers with derived routes.

__init__ creates an empty registry; with_defaults prepopulates the four built-in mappers. A caller may build and mutate their own instance without touching the process-global default registry.

__init__

def __init__() -> None

source

Create an empty registry.

with_defaults

def with_defaults(cls) -> RelayConverterRegistry

source

Return a registry prepopulated with the four built-in mappers.

def register(mapper: FormatMapper) -> None

source

Parameters

Parameter	Type	Description
`mapper`	FormatMapper	A mapper exposing a ``format`` RelayFormat attribute.

Raises

Exception	Description
RelayError	With code ``duplicate_registration`` when a mapper is already registered for the format, or ``unsupported_format`` when the mapper does not declare a ``RelayFormat`` ``format`` attribute.

mapper

def mapper(
    source: RelayFormat,
    target: RelayFormat
) -> RelayMapperProtocol | None

source

Return the delegating route for a directed pair, or None.

Same-format pairs return None; the engine treats those as a no-op conversion.

Parameters

Parameter	Type	Description
`source`	RelayFormat	Source wire format.
`target`	RelayFormat	Target wire format.

Returns

Type	Description
RelayMapperProtocol \| None	The route mapper, or ``None`` when no route exists.

converter_routes

def converter_routes() -> tuple[tuple[RelayFormat, RelayFormat], Ellipsis]

source

Return every supported directed route pair.

Returns

Type	Description
tuple[tuple[RelayFormat, RelayFormat], Ellipsis]	Sorted route pairs, excluding same-format no-op pairs.

mapper_ids

def mapper_ids() -> tuple[str, Ellipsis]

source

Return the registered mapper wire-format identifiers.

Returns

Type	Description
tuple[str, Ellipsis]	Sorted mapper ids, one per registered mapper.

converter_version

def converter_version() -> str

source

Return the converter engine version string.

Returns

Type	Description
str	The module-level ``CONVERTER_VERSION`` constant.

route_quality

def route_quality(
    source: RelayFormat,
    target: RelayFormat
) -> ConversionQuality

source

Return the semantic-closeness quality for a directed pair.

Same-format pairs and unconfigured routes fall back to GOOD/DISCOURAGED via the quality matrix.

Parameters

Parameter	Type	Description
`source`	RelayFormat	Source wire format.
`target`	RelayFormat	Target wire format.

Returns

Type	Description
ConversionQuality	The stable quality value for the pair.

route

def route(
    source: RelayFormat,
    target: RelayFormat
) -> RouteSpec | None

source

Return the route spec for a directed pair, or None.

Same-format pairs return None (no-op conversion).

Parameters

Parameter	Type	Description
`source`	RelayFormat	Source wire format.
`target`	RelayFormat	Target wire format.

Returns

Type	Description
RouteSpec \| None	The route spec, or ``None`` when no route exists.

route_by_id

def route_by_id(converter_id: str) -> RouteSpec | None

source

Return the route spec carrying converter_id, or None.

Parameters

Parameter	Type	Description
`converter_id`	str	A stable ``"_to_"`` identifier.

Returns

Type	Description
RouteSpec \| None	The matching route spec, or ``None`` when unknown.

routes

def routes() -> tuple[RouteSpec, Ellipsis]

source

Return specs for every registered directed pair, sorted by id.

`RelayModule`

source

Relay protocol conversion engine module for Oridecon applications.

Provides the caller-owned relay registry and the public conversion engine behind their contract protocols.

Usage

from oridecon.ai.relay import RelayModule

@module(
    imports=[RelayModule.configure()]
)
class AppModule(Module):
    pass

from oridecon.ai.relay import RelayModule

@module(
    imports=[RelayModule.configure()]
)
class AppModule(Module):
    pass

configure

def configure(cls) -> DynamicModule

source

Create a RelayModule with the built-in converter routes.

Returns

Type	Description
DynamicModule	A DynamicModule descriptor.

stub

def stub(
    cls,
    config: Any = None
) -> DynamicModule

source

Create a RelayModule suitable for unit and integration testing.

Uses the same in-memory registry and synchronous engine as configure; no credentials or I/O are involved.

Parameters

Parameter	Type	Description
`config`	Any	Optional test configuration override; the relay module needs no configuration, so it is ignored.

Returns

Type	Description
DynamicModule	A DynamicModule descriptor.

`RouteSpec`

source

Static metadata for one directed conversion route.

Attributes: source: Source wire format. target: Target wire format. quality: Semantic closeness of the conversion. request_supported: Whether request conversion is available. response_supported: Whether response conversion is available. stream_supported: Whether stateful stream conversion is available. feature_loss_policy: Machine-readable loss reasons this route is expected to record, in order.

Properties: converter_id: Stable "<source>_to_<target>" identifier.

converter_id

property converter_id() -> str

source

Stable "<source>_to_<target>" identifier for this route.

Functions

`convert_request_by_id`

convert_request_by_id

def convert_request_by_id(
    registry: RelayConverterRegistry,
    payload: RelayRequestPayload,
    converter_id: str,
    *,
    context: RelayConversionContext | None = None
) -> Result[RelayConvertResult[RelayRequestPayload], RelayError]

source

Convert a request through the route identified by ``converter_id``.

Parameters

Parameter	Type	Description
`registry`	RelayConverterRegistry	The registry carrying the route.
`payload`	RelayRequestPayload	The source request DTO.
`converter_id`	str	A stable ``"_to_"`` identifier.
`context`	RelayConversionContext \| None	Optional host conversion context.

Returns

Type	Description
Result[RelayConvertResult[RelayRequestPayload], RelayError]	A request conversion result, or a relay error.

`convert_request_via`

convert_request_via

def convert_request_via(
    registry: RelayRegistryProtocol,
    payload: RelayRequestPayload,
    source: RelayFormat,
    target: RelayFormat,
    *,
    context: RelayConversionContext | None = None
) -> Result[RelayConvertResult[RelayRequestPayload], RelayError]

source

Convert a request through an explicit registry.

Parameters

Parameter	Type	Description
`registry`	RelayRegistryProtocol	The registry to resolve the route from.
`payload`	RelayRequestPayload	The source request DTO.
`source`	RelayFormat	Source wire format.
`target`	RelayFormat	Target wire format.
`context`	RelayConversionContext \| None	Optional host conversion context.

Returns

Type	Description
Result[RelayConvertResult[RelayRequestPayload], RelayError]	A request conversion result, or a relay error.

`convert_response_by_id`

convert_response_by_id

def convert_response_by_id(
    registry: RelayConverterRegistry,
    payload: RelayResponsePayload,
    converter_id: str,
    *,
    context: RelayConversionContext | None = None
) -> Result[RelayConvertResult[RelayResponsePayload], RelayError]

source

Convert a response through the route identified by ``converter_id``.

Parameters

Parameter	Type	Description
`registry`	RelayConverterRegistry	The registry carrying the route.
`payload`	RelayResponsePayload	The source response DTO.
`converter_id`	str	A stable ``"_to_"`` identifier.
`context`	RelayConversionContext \| None	Optional host conversion context.

Returns

Type	Description
Result[RelayConvertResult[RelayResponsePayload], RelayError]	A response conversion result, or a relay error.

`convert_response_via`

convert_response_via

def convert_response_via(
    registry: RelayRegistryProtocol,
    payload: RelayResponsePayload,
    source: RelayFormat,
    target: RelayFormat,
    *,
    context: RelayConversionContext | None = None
) -> Result[RelayConvertResult[RelayResponsePayload], RelayError]

source

Convert a response through an explicit registry.

Parameters

Parameter	Type	Description
`registry`	RelayRegistryProtocol	The registry to resolve the route from.
`payload`	RelayResponsePayload	The source response DTO.
`source`	RelayFormat	Source wire format.
`target`	RelayFormat	Target wire format.
`context`	RelayConversionContext \| None	Optional host conversion context.

Returns

Type	Description
Result[RelayConvertResult[RelayResponsePayload], RelayError]	A response conversion result, or a relay error.

`malformed_payload`

malformed_payload

def malformed_payload(detail: str) -> RelayError

source

The wire payload did not match the expected shape.

Parameters

Parameter	Type	Description
`detail`	str	Human-readable description of the malformed field.

Returns

Type	Description
RelayError	A ``RelayError`` with code ``malformed_payload``.

`media_resolution_required`

media_resolution_required

def media_resolution_required(detail: str) -> RelayError

source

URL media requires a resolver the host did not supply.

Parameters

Parameter	Type	Description
`detail`	str	The media URL that cannot be resolved.

Returns

Type	Description
RelayError	A ``RelayError`` with code ``media_resolution_required``.

`missing_required_option`

missing_required_option

def missing_required_option(detail: str) -> RelayError

source

A required field or host option is absent.

Parameters

Parameter	Type	Description
`detail`	str	Which required option is missing.

Returns

Type	Description
RelayError	A ``RelayError`` with code ``missing_required_option``.

`record_loss`

record_loss

def record_loss(
    context: ConversionContext,
    *,
    field: str,
    target: RelayFormat,
    reason: str,
    severity: str = 'warning'
) -> None

source

Record a semantic loss on the conversion context.

The engine copies the accumulated losses into the RelayConvertResult and surfaces warning/error losses as warnings.

Parameters

Parameter	Type	Description
`context`	ConversionContext	The per-conversion context holding the loss sink.
`field`	str	Source wire field (or feature) that was dropped or adapted.
`target`	RelayFormat	Target format the loss applies to.
`reason`	str	Machine-readable reason (e.g. ``json_mode_not_supported``).
`severity`	str	``error``, ``warning``, or ``info``.

`route_quality`

route_quality

def route_quality(
    source: RelayFormat,
    target: RelayFormat
) -> ConversionQuality

source

Return the semantic-closeness quality for a directed pair.

Parameters

Parameter	Type	Description
`source`	RelayFormat	Source wire format.
`target`	RelayFormat	Target wire format.

Returns

Type	Description
ConversionQuality	:data:`ConversionQuality.GOOD` for same-format conversion and for routes without a configured quality, otherwise the configured matrix value.

`translate`

translate

def translate(
    exc: Exception,
    *,
    detail: str
) -> RelayError

source

Translate an unexpected exception into a stable error category.

RelayError passes through unchanged. DTO parsing failures (ValueError, TypeError, KeyError) become malformed_payload; any other exception becomes serialization_error.

Parameters

Parameter	Type	Description
`exc`	Exception	The exception raised inside a mapper.
`detail`	str	Context describing what was being translated.

Returns

Type	Description
RelayError	A stable ``RelayError``.

`unsupported_feature`

unsupported_feature

def unsupported_feature(detail: str) -> RelayError

source

The source feature cannot be converted to the target.

Parameters

Parameter	Type	Description
`detail`	str	The feature that could not be converted.

Returns

Type	Description
RelayError	A ``RelayError`` with code ``unsupported_feature``.

`unsupported_format`

unsupported_format

def unsupported_format(detail: str) -> RelayError

source

The payload does not belong to this mapper's wire format.

Parameters

Parameter	Type	Description
`detail`	str	The expected and actual payload shapes.

Returns

Type	Description
RelayError	A ``RelayError`` with code ``unsupported_format``.

`warning_messages`

warning_messages

def warning_messages(losses: Sequence[RelayLoss]) -> tuple[str, Ellipsis]

source

Render losses into stable warning strings.

Parameters

Parameter	Type	Description
`losses`	Sequence[RelayLoss]	Loss records accumulated during conversion.

Returns

Type	Description
tuple[str, Ellipsis]	One ``"field: reason (target, severity)"`` string per loss.