Contrats v1

Cette page liste les contrats JSON Schema versionnés (draft 2020-12) de la Navin Platform, explique leurs règles de version et montre comment valider un document avec l'API, chaque SDK et la CLI. Les schémas sont rangés dans contracts/v1/, indexés par contracts/index.json, avec un exemple par contrat dans contracts/examples/. Le Control Plane, le portail, chaque SDK et la CLI utilisent les mêmes fichiers : les modèles en sont générés et les documents sont validés contre eux.

English version: contracts.md

Catalogue

28 contrats, plus common.schema.json pour les définitions partagées. Les documents de type manifest sont appliqués par le Control Plane (GitOps ou API) et portent un kind ; les types document et event sont échangés par les services.

Contrat	Type	Rôle
common	définitions	Briques partagées par chaque contrat v1 : identifiants, horodatages, montants, classification.
agent-manifest	manifeste (Agent)	Identité, version, outils, modèles, permissions, autonomie et budgets d'un agent.
model-manifest	manifeste (Model)	Entrée du Model Registry : fournisseur, modalités, limites, raisonnement, prix et politiques.
tool-manifest	manifeste (Tool)	Schéma, action, scopes et classification d'un outil exécuté par le Tool Gateway.
skill-manifest	manifeste (Skill)	Skill versionnée et signée : instructions, dépendances et permissions.
plugin-manifest	manifeste (Plugin)	Plugin OCI isolé ou pack métier complet installé par la Marketplace.
connector-manifest	manifeste (Connector)	Intégration à un système métier : authentification, scopes, ressources et synchronisation.
channel-manifest	manifeste (Channel)	Canal d'exposition (web, mobile, e-mail, messagerie, voix) : authentification, transport, limites et sessions.
managed-component	manifeste (ManagedComponent)	Un composant de la distribution : version figée, licence, dépendances, secrets par référence, santé.
execution-contract	document	État d'un run d'agent : états, étapes, budgets, erreurs et stratégie de reprise.
context-contract	document	Contexte assemblé pour un appel de modèle : sources, classification, budget de jetons et provenance.
memory-contract	document	Un élément de mémoire : ACL, durée de vie, provenance de l'écriture et règles de suppression.
evaluation-contract	document	Jeu de données, métriques, seuils et résultats d'une évaluation ; une gate bloquante empêche la promotion.
policy-contract	document	Entrée (ressource, action, sujet, contexte) et décision d'une évaluation de politique.
multimodal-contract	document	Média traité par le Multimodal Gateway : type, durée, résolution, stockage, classification, DLP, coûts.
license-entitlement	document	Contenu d'une licence de la plateforme signée par l'éditeur (durée annuelle ou triennale).
execution-context	document	Contexte d'identité, de délégation et de gouvernance d'une exécution, signé par la Context Authority.
action-context	document	Une action gouvernée : demande, sujet, cible, empreinte des arguments, décisions, obligations, approbation.
delegation-context	document	Une délégation de droits à un agent, une application ou un sous-agent, toujours couverte par son parent.
approval-request	document	Une approbation humaine avec quatre yeux et séparation des tâches.
security-incident	document	Un incident SOC : détections corrélées, verdict de risque et réponse.
containment-order	document	Une réaction typée sur une cible typée avec un rayon d'impact maîtrisé et les états du kill switch.
storage-profile	document	Stockage objet du client (S3, Azure Blob, GCS, IBM COS, SeaweedFS) : cible, référence d'identifiant, usages.
usage-event	événement	Un événement de consommation : unités, modèle, prix au moment de l'appel, devise, coût estimé, mesuré et facturé.
audit-event	événement	Qui a fait quoi sur quelle ressource, la décision de politique et la preuve ; chaîné par hachage par tenant.
policy-decision	événement	Une décision d'autorisation : contrôle de relation, décision de politique et permission effective.
tool-invocation	événement	Un appel d'outil ou MCP sous un contexte d'exécution : outil, empreinte des arguments, autorisation, résultat.
llm-invocation	événement	Un appel de modèle par le Model Gateway : modèle, fournisseur, région, classification, consommation et coût.
data-access-context	événement	Un accès aux données ou au RAG : source, filtre de tenant, ACL, plafond de classification, documents renvoyés.

Règles de version

• Chaque document porte schema_version (1.0, 1.1...). Le dossier v1 est la version majeure.
• Les versions mineures n'ajoutent que des champs optionnels ou des valeurs d'énumération ; les objets en additionalProperties: false ne reçoivent jamais de nouveau champ dans une version mineure.
• Retirer ou renommer un champ, changer un type ou rendre un champ obligatoire est un changement majeur : un nouveau dossier contracts/v2/, et l'API continue de servir v1 pendant au moins 12 mois.
• Les ajouts d'énumération (par exemple un nouveau usage_type) sont mineurs ; les consommateurs doivent traiter proprement les valeurs inconnues.
• Un montant est toujours une chaîne décimale plus une devise ISO 4217 ; les horodatages sont en RFC 3339 UTC.
• Les changements passent par une revue, la validation en CI de chaque exemple et une entrée de journal des modifications.

Validation

1. Sur le serveur. GET /v1/contracts liste les schémas, GET /v1/contracts/{name} en renvoie un et POST /v1/contracts/{name}/validate répond {valid, errors[]} ; POST /v1/manifests/apply valide avant toute modification du registre.

2. Avec la CLI, avant un commit ou en CI. Code de sortie 1 quand un document est invalide.

   enterprise-ai validate -f ./manifests/agent.yaml --output json

3. Hors ligne, dans chaque SDK, avec les schémas embarqués dans le paquet (aucun réseau, même résultat que le serveur).

SDK	Appel au serveur	Validation hors ligne	Résultat
Python	client.contracts.validate(name, document)	enterprise_ai.contracts.validate(document, name=None)	ValidationResult (valid, errors, raise_for_errors())
TypeScript	client.contracts.validate(name, document)	validateContract(name, doc, locale), validateManifest(doc)	{ valid, errors: { path, message, keyword }[] }
Go	client.Contracts.ValidateRemote(ctx, name, body)	client.Contracts.Validate(name, doc), eai.ValidateContract(lang, name, doc)	eai.ValidationResult (Contract, Valid, Errors)
Java	client.contracts().validateRemote(name, body)	client.contracts().validate(name, document), validateManifest(manifest)	enregistrement ValidationResult (contract, valid, errors)

from enterprise_ai.contracts import validate

document = {"schema_version": "1.0", "event_id": "use_01J"}
remote = client.contracts.validate("usage-event", document)  # the server answers {valid, errors}
local = validate(document, "usage-event")  # offline, bundled schemas
print(local.valid, [str(issue) for issue in local.errors])

import { validateContract } from "@enterprise-ai/sdk";

const local = validateContract("multimodal-contract", doc);
if (!local.valid) console.log(local.errors.map((e) => `${e.path}: ${e.message}`));

res, err := client.Contracts.Validate("usage-event", doc)
if err != nil {
	return err
}
fmt.Println(res.Valid, res.Errors)

ValidationResult r = client.contracts().validate("evaluation-contract", doc);
if (!r.valid()) { r.errors().forEach(System.out::println); }

Sans nom, les validateurs de manifestes de Python et de TypeScript détectent le contrat à partir du kind du document.

Exemple : Usage Event

{
  "schema_version": "1.0",
  "event_id": "use_01J",
  "occurred_at": "2026-10-29T10:00:01Z",
  "tenant_id": "8f0c2a4e-1b7d-4c55-9a51-2f3e6d7c9b10",
  "agent_id": "agt_ap",
  "session_id": "ses_9",
  "task_id": "tsk_3",
  "usage_type": "llm",
  "provider": "openai",
  "model_id": "gpt-4o-mini",
  "region": "eu-west",
  "units": {"input_tokens": 812, "cached_input_tokens": 512, "output_tokens": 240, "reasoning_tokens": 120},
  "pricing": {"pricing_version": "openai-2026-10-01", "currency": "USD", "effective_at": "2026-10-01T00:00:00Z", "reasoning_billing": "included_in_output"},
  "cost": {"estimated": {"amount": "0.000310", "currency": "USD"}, "measured": null, "billed": null},
  "source": "litellm"
}

Règle FinOps : input_tokens inclut les jetons en cache et output_tokens inclut les jetons de raisonnement.

Référence

• Schémas : contracts/v1/, index contracts/index.json, exemples contracts/examples/.
• API v1 du Control Plane et les guides des SDK (vue d'ensemble).