nemo-relay-instrument-typed-wrappers

型付きラッパーとコーデックを使用する

アプリケーションで、ツールや LLM との連携に生の JSON よりも強いドメイン型が必要な場合に、このスキルを使用します。 ミドルウェアから予測可能な JSON が引き続き見えるよう、型付きの境界を明示してください。

デフォルトのガイダンス

• 導入時は、まずプレーンな JSON を優先してください。
• アプリケーションに安定したドメインモデルがすでにある場合は、型付きラッパーを使用してください。
• ミドルウェアは引き続き型付きオブジェクトではなく JSON を扱う点に留意してください。

埋め込みコーデックモデル

• 型付き値コーデックは、純粋な境界変換器です。NeMo Relay がイベントを発行したり、ミドルウェアを実行したりする前に、アプリケーション向けの値を JSON に変換し、その後、JSON をフレームワークのコールバック型または呼び出し元の型に戻します。
• Python では JsonPassthrough、DataclassCodec、PydanticCodec、BestEffortAnyCodec を利用できます。Node.js では JsonPassthrough とカスタムの Codec<T> 実装を利用できます。
• BestEffortAnyCodec は、厳密なスキーマを利用できない境界でのみ使用してください。フレームワークで安定したスキーマが定義されている場合は、dataclass、Pydantic、または明示的な Node.js コーデックを優先してください。
• プロバイダーコーデックは型付き値コーデックとは異なります。プロバイダー固有の LLM リクエストとレスポンスを正規化し、ミドルウェアやサブスクライバーがメッセージ、ツール、モデル名、生成パラメーター、レスポンス注釈を確認できるようにします。
• 組み込みのプロバイダーコーデックには、Python、Node.js、Rust の OpenAIChatCodec、OpenAIResponsesCodec、AnthropicMessagesCodec があります。実際のプロバイダーペイロードの形状に合ったコーデックを選択してください。
• レスポンスコーデックは、id、model、message、tool_calls、finish_reason、usage、プロバイダー固有データ、モデル化されていない追加フィールドなどで LLM の終了イベントに注釈を付与します。呼び出し元から見えるレスポンスは書き換えません。
• リクエストコーデックは LLM リクエストインターセプトの前に実行されます。インターセプトは、生の LLMRequest と、任意で注釈付きリクエストの両方を受け取ります。encode は、実行インターセプトとプロバイダーコールバックの実行前に、注釈付きの編集内容をマージします。

主なルール

• 型付きラッパーは現在、Python と Node.js で第一級の方法として利用できます。Rust ではコーデックトレイトを直接使用します。
• リクエストとレスポンスの変換はコーデックで行います。
• インターセプトとガードレールが扱うのは、エンコード後の JSON 値です。
• ミドルウェアが行った変更は、デコード処理まで維持されます。

コーデックを選ぶ

• JSON ネイティブの値には JsonPassthrough
• 既存のモデルがある場合は、Python の DataclassCodec または PydanticCodec
• ドメイン固有のワイヤー形式にはカスタムコーデック
• 幅広い柔軟性と引き換えに契約が緩くなることを許容できる場合にのみ BestEffortAnyCodec
• アプリケーションのドメインオブジェクト変換ではなく、LLM プロバイダーのペイロードにはプロバイダーコーデック

検証チェックリスト

• コーデックの出力が JSON 互換である
• 必須フィールドが toJson/fromJson または decode/encode の処理後も維持される
• ミドルウェアが想定どおりのシリアライズ済みの形状を受け取る
• プロバイダーコーデックが、理解できないフィールドを保持する
• レスポンスコーデックの失敗によって、基盤となる LLM 呼び出しが中断されない
• インターセプトが意図的に変更しない限り、リクエストコーデックの encode が元のプロバイダーフィールドを保持する

関連スキル

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