Using Codecs

Use this guide when a framework integration needs typed application values at its public boundary while NeMo Relay still records JSON-compatible payloads.

What You Build

You will choose typed value codecs for framework-facing wrappers so that:

• Application code can pass native objects to framework callbacks
• NeMo Relay can emit JSON-compatible lifecycle payloads
• Middleware and subscribers receive predictable serialized values
• The framework callback still receives the application type it expects

For provider-native LLM payload normalization, use Provider Codecs.

Before You Start

You need:

• A stable framework callback boundary.
• Application request and response types that can be projected into JSON.
• A managed wrapper that accepts codecs, such as the typed tool or typed LLM helpers.
• A validation path that confirms the returned value still matches framework expectations.

What Codecs Are

A typed value codec is a pure data translator at the NeMo Relay boundary. It converts application-facing values to JSON before NeMo Relay emits events or runs JSON-based middleware, then converts JSON back into the type expected by the framework callback or caller.

Typed value codecs are different from provider codecs:

Use this page for typed value codecs. Use Provider Codecs when middleware needs normalized LLM messages, tools, model names, generation parameters, or provider response annotations.

How Typed Value Codecs Work

When a managed typed wrapper receives a codec:

1. The wrapper converts the application input into JSON before entering the NeMo Relay runtime.
2. NeMo Relay emits lifecycle events and runs middleware against JSON-compatible payloads.
3. The wrapper converts JSON back into the callback type before invoking framework-owned code when needed.
4. The wrapper converts the callback result back through the result codec before returning to the caller.

Keep codecs deterministic and side-effect free. A codec should not open network connections, mutate framework state, or hide provider I/O.

Typed Value Codecs

Python exposes:

• JsonPassthrough
• DataclassCodec
• PydanticCodec
• BestEffortAnyCodec

Node.js exposes JsonPassthrough and custom Codec<T> implementations.

1
from dataclasses import dataclass
2
3
from pydantic import BaseModel
4
5
from nemo_relay.typed import DataclassCodec, JsonPassthrough, PydanticCodec
6
7
@dataclass
8
class SearchArgs:
9
    query: str
10
11
class SearchResult(BaseModel):
12
    hits: int
13
14
args_codec = DataclassCodec(SearchArgs)
15
result_codec = PydanticCodec(SearchResult)
16
passthrough = JsonPassthrough()

Use BestEffortAnyCodec only at boundary code where strict schemas are unavailable. Prefer dataclass, Pydantic, or explicit Node.js codecs when the framework owns a stable schema.

Example: Typed Tool Boundary

Use typed value codecs when the framework wants native objects but NeMo Relay should emit JSON payloads.

1
from dataclasses import dataclass
2
3
import nemo_relay
4
from nemo_relay.typed import DataclassCodec, JsonPassthrough, tool_execute
5
6
@dataclass
7
class SearchArgs:
8
    query: str
9
10
async def invoke(args: SearchArgs) -> dict[str, str]:
11
    return {"echo": args.query}
12
13
result = await tool_execute(
14
    "search",
15
    SearchArgs("weather"),
16
    invoke,
17
    args_codec=DataclassCodec(SearchArgs),
18
    result_codec=JsonPassthrough(),
19
)

Validation Checklist

Use this checklist to confirm the implementation preserves the expected runtime contract.

• Codec output is JSON-compatible.
• Required fields are preserved by toJson and fromJson.
• Middleware sees the expected serialized shape.
• The framework callback receives the expected application type.
• Error paths report conversion failures close to the framework boundary.

Next Steps

Use these links to continue from this workflow into the next related task.

• Use Provider Codecs when provider payloads need normalized request or response annotations.
• Use Handle Non-Serializable Data when framework objects cannot pass through JSON payloads.
• Use Integrate into Frameworks Code Examples for explicit fallback APIs.