Construire un Plugin

Utilisez cette compétence quand un utilisateur souhaite empaqueter un comportement réutilisable du runtime NeMo Relay derrière une configuration de plugin. Gardez le comportement réutilisable du plugin séparé du code de démarrage d'application ponctuel.

Utiliser Ceci Quand

Utilisez cette compétence quand le comportement doit être activé par une config partagée et réutilisé entre les applications, équipes, ou chemins de démarrage de processus.

Cas courants :

Enregistrer des subscribers, guardrails, intercepts, ou un petit ensemble de comportements runtime associés.
Valider la config fournie par l'opérateur avant de modifier le comportement runtime.
Donner à un comportement réutilisable un kind de plugin stable et un cycle de vie d'activation.
Empaqueter un comportement qui doit être activé, désactivé, ou déployé via la config du plugin plutôt que par du code de démarrage d'application répété.

Ne Pas Utiliser Ceci Quand

Ne construisez pas de plugin quand une surface NeMo Relay plus étroite suffit :

Une seule requête ou tenant a besoin d'un comportement temporaire -> utilisez un middleware local au scope.
L'utilisateur a seulement besoin des premiers scopes, tool calls, ou LLM calls -> nemo-relay-instrument-calls.
L'utilisateur a seulement besoin de choisir un chemin d'exporter -> nemo-relay-plugin-observability.
Le comportement dépend de callables vivants, clients de provider, file handles, credentials, ou objets framework à l'intérieur de la config.

Modèle de Plugin Embarqué

Les plugins empaquettent un comportement réutilisable au niveau du processus.
Un plugin expose une chaîne kind stable et reçoit une config locale au composant depuis un document de plugin partagé.
La config du plugin doit être compatible JSON sur Rust, Python, Node.js, fichiers, tests, et systèmes de déploiement.
La validation est déterministe et sans effets secondaires. Elle inspecte la config et retourne des diagnostiques structurés avant que le comportement runtime change.
L'enregistrement s'exécute après la validation et installe un comportement réel via PluginContext, tel que des subscribers, guardrails, request intercepts, execution intercepts, ou stream execution intercepts.
PluginContext donne au système de plugins suffisamment de propriété pour qualifier les noms runtime et revenir en arrière lors d'une activation partielle échouée.
Les composants désactivés doivent toujours valider quand possible pour que les opérateurs puissent trouver des problèmes de config avant le déploiement.

Chemin par Défaut

Décidez si un plugin est vraiment nécessaire. Préférez l'instrumentation directe ou le comportement local au scope quand le cas d'usage n'est pas un comportement réutilisable au niveau du processus.
Choisissez une première surface runtime : export orienté subscriber, guardrail de sanitization, guardrail conditionnel, request intercept, execution intercept, ou stream execution intercept.
Choisissez un kind de plugin stable et la plus petite shape de config compatible JSON.
Définissez des diagnostiques pour les champs manquants, valeurs non supportées, champs inconnus, config non sûre, et combinaisons de champs invalides.
Validez la config avant l'initialisation. La validation ne doit pas ouvrir de connexions réseau, créer de clients, enregistrer du middleware, ou muter l'état du processus.
Si la validation retourne des diagnostiques d'erreur, retournez-les et arrêtez sans initialisation ou enregistrement.
Enregistrez le comportement runtime via PluginContext, pas en enregistrant à la main un comportement global à l'intérieur du démarrage de l'application.
Testez l'activation, les composants désactivés, les échecs de validation, et la restauration d'échec d'enregistrement.
Documentez comment activer le plugin, quels champs de config sont supportés, et comment restaurer le composant.
Pour un plugin dynamique qui devrait fournir des champs structurés dans nemo-relay plugins edit, déclarez la capacité config_schema et référencez un fichier JSON Schema Draft 7 ou Draft 2020-12 local depuis [config_schema].path dans relay-plugin.toml. Les plugins sans schema restent éditables en tant qu'objets JSON bruts.

Shape de Config

Le document de plugin de haut niveau contient version, components, et policy. Chaque composant fournit le plugin kind, enabled, et la config locale au composant :

{
  "version": 1,
  "components": [
    {
      "kind": "redaction-policy",
      "enabled": true,
      "config": {
        "preset": "strict"
      }
    }
  ],
  "policy": {
    "unknown_component": "warn",
    "unknown_field": "warn",
    "unsupported_value": "error"
  }
}

Gardez la logique métier dans le code du plugin, pas dans la config. Utilisez des références à des secrets ou endpoints plutôt que d'embarquer des valeurs sensibles.

Pointeurs de Binding

Python : nemo_relay.plugin
Node.js : nemo-relay-node/plugin
Rust : nemo_relay::plugin
Go et raw FFI sont des surfaces source-first ou avancées.

Utilisez les mêmes clés de config snake_case canoniques sur les bindings et fichiers. Les fonctions helper Node peuvent être camelCase, mais les objets de config du plugin restent snake_case.

Modes d'Échec à Éviter

Ne mettez pas de callables, clients, credentials, objets framework, file handles, ou caches dans la config du plugin.
Ne faites pas d'enregistrement runtime pendant la validation.
Ne sautez pas la validation pour les composants désactivés.
Ne vous enregistrez pas directement via le code de démarrage global quand PluginContext doit posséder le comportement runtime.
Ne combinez pas des subscribers, transforms de requête, et vérifications de policy non liés dans le premier plugin sauf si un document de config possède clairement le bundle.
N'exportez pas de payloads ou secrets de production bruts. Ajoutez une sanitization de télémétrie avant que les données ne quittent le processus.
N'ignorez pas les échecs d'activation partielle. Restaurez ou surfacez un diagnostic clair.

Liste de Contrôle de Validation

[ ] Plugin kind stable choisi.
[ ] La shape de config est compatible JSON et utilise snake_case.
[ ] Les champs requis et valeurs non supportées produisent des diagnostiques stables.
[ ] Les champs inconnus suivent la policy configurée.
[ ] Les composants désactivés rapportent toujours les problèmes de config où possible.
[ ] L'initialisation installe le comportement via PluginContext.
[ ] Un échec d'enregistrement forcé ne laisse pas de comportement runtime partiel actif.
[ ] Les docs ou exemples montrent comment activer et restaurer le plugin.
[ ] Les plugins dynamiques qui ont besoin d'une édition CLI structurée empaquettent un JSON Schema local valide et déclarent config_schema dans relay-plugin.toml.

Utiliser une Autre Compétence Quand

Vous avez seulement besoin de wrapper des tool ou LLM calls directs -> nemo-relay-instrument-calls
Vous avez besoin de configurer des traces ou exporters sans empaqueter un plugin -> nemo-relay-plugin-observability
Vous avez besoin de déboguer l'activation du plugin, événements manquants, ou échecs de chargement -> nemo-relay-debug-runtime-integration

nemo-relay-plugin-build