Utiliser des Wrappers Typés et des Codecs

Utilisez cette skill quand une application souhaite des types métier plus robustes que du JSON brut pour l'intégration d'outils ou de LLM. Maintenez les frontières typées explicites afin que les middlewares voient toujours du JSON prévisible.

Guidance par défaut

• Privilégiez d'abord du JSON simple pour l'adoption initiale.
• Recourez aux wrappers typés quand l'application possède déjà des modèles métier stables.
• Gardez à l'esprit que les middlewares fonctionnent sur du JSON, pas sur des objets typés.

Modèle Codec Embarqué

• Un codec de valeur typée est un traducteur de frontière pur. Il convertit les valeurs exposées à l'application en JSON avant que NeMo Relay n'émette des événements ou n'exécute des middlewares, puis reconvertit le JSON en type de callback ou d'appelant du framework.
• Python expose JsonPassthrough, DataclassCodec, PydanticCodec, et BestEffortAnyCodec. Node.js expose JsonPassthrough plus des implémentations Codec<T> personnalisées.
• Utilisez BestEffortAnyCodec uniquement aux frontières où des schémas stricts ne sont pas disponibles. Préférez dataclass, Pydantic, ou des codecs Node.js explicites quand le framework possède un schéma stable.
• Les codecs de fournisseur sont différents des codecs de valeur typée : ils normalisent les requêtes et réponses LLM spécifiques au fournisseur afin que les middlewares et souscripteurs puissent inspecter les messages, outils, noms de modèle, paramètres de génération, et annotations de réponse.
• Les codecs de fournisseur intégrés incluent OpenAIChatCodec, OpenAIResponsesCodec, et AnthropicMessagesCodec en Python, Node.js, et Rust. Choisissez le codec qui correspond à la forme de payload du fournisseur réel.
• Les codecs de réponse annotent les événements de fin LLM avec des champs tels que id, model, message, tool_calls, finish_reason, usage, données spécifiques au fournisseur, et champs supplémentaires non modélisés. Ils ne réécrivent pas la réponse visible par l'appelant.
• Les codecs de requête s'exécutent avant les intercepts de requête LLM. Les intercepts reçoivent à la fois la LLMRequest brute et la requête annotée optionnelle ; encode fusionne les édits annotés avant les intercepts d'exécution et l'exécution du callback du fournisseur.

Règles Clés

• Les wrappers typés sont actuellement un chemin de première classe pour Python et Node.js ; Rust utilise directement les traits codec
• La conversion requête/réponse appartient aux codecs
• Les intercepts et guardrails voient les valeurs JSON après encodage
• Les modifications effectuées par les middlewares survivent à l'étape de décodage

Choisir un Codec

• JsonPassthrough pour les valeurs JSON-natives
• DataclassCodec ou PydanticCodec en Python quand les modèles existent déjà
• Codecs personnalisés pour les formes de fil métier spécifiques au domaine
• BestEffortAnyCodec uniquement quand la large flexibilité vaut le contrat plus souple
• Codecs de fournisseur pour les payloads de fournisseur LLM, pas pour la conversion d'objets métier d'application

Checklist de Validation

• [ ] La sortie du codec est compatible JSON
• [ ] Les champs obligatoires survivent à toJson/fromJson ou decode/encode
• [ ] Les middlewares voient la forme sérialisée attendue
• [ ] Les codecs de fournisseur préservent les champs qu'ils ne comprennent pas
• [ ] Les défaillances du codec de réponse ne cassent pas l'appel LLM sous-jacent
• [ ] L'encode du codec de requête préserve les champs de fournisseur originaux sauf si un intercept les modifie intentionnellement

Skills Associées

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