AGENT SKILL

nemo-relay-instrument-typed-wrappers

Use this skill when adding NeMo Relay typed wrappers, domain types, or provider codecs while preserving JSON middleware semantics and caller-visible behavior.

License 许可
Apache-2.0
所属仓库
dawsonblock/NEMO
最近更新
2026-09-30
Stars
★ 0
Forks
0

01 前言 Front Matter

name
nemo-relay-instrument-typed-wrappers
license
Apache-2.0
metadata
{ "author": "NVIDIA Corporation and Affiliates" }
description
Use this skill when adding NeMo Relay typed wrappers, domain types, or provider codecs while preserving JSON middleware semantics and caller-visible behavior.

02 资源文件 4

03 SKILL.md 正文

Use Typed Wrappers And Codecs

Use this skill when an application wants stronger domain types than raw JSON for tool or LLM integration. Keep typed boundaries explicit so middleware still sees predictable JSON.

Default Guidance

  • Prefer plain JSON first for initial adoption.
  • Reach for typed wrappers when the application already has stable domain models.
  • Keep in mind that middleware still operates on JSON, not typed objects.

Embedded Codec Model

  • A typed value codec is a pure boundary translator. It converts application-facing values to JSON before NeMo Relay emits events or runs middleware, then converts JSON back into the framework callback or caller type.
  • Python exposes JsonPassthrough, DataclassCodec, PydanticCodec, and BestEffortAnyCodec. Node.js exposes JsonPassthrough plus custom Codec<T> implementations.
  • Use BestEffortAnyCodec only at boundaries where strict schemas are not available. Prefer dataclass, Pydantic, or explicit Node.js codecs when the framework owns a stable schema.
  • Provider codecs are different from typed value codecs: they normalize provider-specific LLM requests and responses so middleware and subscribers can inspect messages, tools, model names, generation parameters, and response annotations.
  • Built-in provider codecs include OpenAIChatCodec, OpenAIResponsesCodec, and AnthropicMessagesCodec in Python, Node.js, and Rust. Choose the codec that matches the actual provider payload shape.
  • Response codecs annotate LLM end events with fields such as id, model, message, tool_calls, finish_reason, usage, provider-specific data, and extra unmodeled fields. They do not rewrite the caller-visible response.
  • Request codecs run before LLM request intercepts. Intercepts receive both the raw LLMRequest and optional annotated request; encode merges annotated edits back before execution intercepts and the provider callback run.
  • Built-in request codecs guarantee JSON-value identity for an unchanged annotation. They compare edits with a decoded baseline and patch only changed fields, preserving native representation details and unknown fields.
  • Use instructions, portable messages and components, and the tagged api_specific request surface for normalized edits. Provider-only union members use explicit { provider, kind, value } native components. Reserve top-level extra for unknown future fields.
  • The nemo-relay gateway always supplies matching request codecs on Anthropic Messages, OpenAI Chat Completions, and OpenAI Responses generation routes. On those routes, treat raw request.content as read-only and return body edits through the annotated request. Header edits still use the raw request.

Key Rules

  • Typed wrappers are currently a first-class path for Python and Node.js; Rust uses codec traits directly
  • Request/response conversion belongs in codecs
  • Intercepts and guardrails see JSON values after encoding
  • Changes made by middleware survive into the decode step

Choose A Codec

  • JsonPassthrough for JSON-native values
  • DataclassCodec or PydanticCodec in Python when the models already exist
  • Custom codecs for domain-specific wire shapes
  • BestEffortAnyCodec only when broad flexibility is worth the looser contract
  • Provider codecs for LLM provider payloads, not application domain objects conversion

Validation Checklist

  • [ ] Codec output is JSON-compatible
  • [ ] Required fields survive toJson/fromJson or decode/encode
  • [ ] Middleware sees the expected serialized shape
  • [ ] Provider codecs preserve fields they do not understand
  • [ ] Response codec failures do not break the underlying LLM call
  • [ ] Request codec encode preserves original provider fields unless an intercept intentionally changes them
  • [ ] Provider-native components belong to the codec's provider surface
  • [ ] Gateway generation intercepts do not mutate raw request.content

Related Skills

  • nemo-relay-instrument-calls
  • nemo-relay-plugin-observability
  • nemo-relay-debug-runtime-integration

04 同仓库更多 Skills

dawsonblock
dawsonblock/NEMO

nemo-relay-plugin-observability

Use this skill when choosing or configuring NeMo Relay 0.6 or 0.7 observability through the built-in plugin, subscribers, or exporters, including raw ATOF events, ATIF trajectories, OpenTelemetry, OpenInference, or custom event handling.

★ 0
dawsonblock
dawsonblock/NEMO

nemo-relay-plugin-build

Use this skill when building or packaging reusable NeMo Relay runtime behavior as an embedded configuration component or a manifest-backed `rust_dynamic` native or `worker` gRPC plugin, with deterministic validation and rollback-safe registration.

★ 0
dawsonblock
dawsonblock/NEMO

nemo-relay-plugin-adaptive-tuning

Use this skill when baseline NeMo Relay instrumentation exists and the user wants to configure or evaluate adaptive plugin behavior, including telemetry, state, adaptive_hints, tool_parallelism, ACG, hint consumption, or measured rollout.

★ 0
dawsonblock
dawsonblock/NEMO

nemo-relay-migrate-from-flow

Use this skill when migrating applications, examples, integrations, documentation, manifests, or repository code from NeMo Flow to NeMo Relay across Python, Rust, Node.js, Go, C FFI, CLI, configuration, and observability surfaces.

★ 0
dawsonblock
dawsonblock/NEMO

nemo-relay-integrate-upstream

Use this skill when assessing, extending, or implementing NeMo Relay support in an agent harness or agent framework, including coding agents and orchestration runtimes, when the host lacks Relay support or an existing integration needs deeper coverage. It identifies the host's execution boundaries and extension points, selects an appropriate attachment method for each boundary, and verifies the resulting coverage.

★ 0
dawsonblock
dawsonblock/NEMO

nemo-relay-instrument-context-isolation

Use this skill when concurrent requests, async tasks, threads, workers, goroutines, or agents need independent NeMo Relay scope stacks and correct ancestry propagation.

★ 0