Les contrats qui relient la plateforme

La séparation des dépôts n'est utile que si leurs accords sont explicites. Un contrat décrit les données, leur version, les erreurs et la compatibilité attendue.

Corpus vers API

yisin-ia/data/processed/manifest.json annonce la version du corpus, ses sorties, compteurs et empreintes. Avant indexation, yisin-api vérifie : schéma supporté, confinement des chemins, empreintes, identifiants, admissions et nombre de lignes.

Chaque collection Qdrant physique correspond à un couple version du corpus / modèle d'embeddings. Les identifiants de points sont déterministes. L'alias stable n'est déplacé qu'après concordance exacte du nombre de points ; une construction interrompue ne devient jamais active.

API vers interface utilisateur

Le contrat initial POST /api/v1/rag/query accepte une question, un choix sur les sources partielles et un top_k. La réponse contient : texte, citations, version du corpus, indicateur d'abstention et avertissement.

Une citation expose au minimum chunk_id, unit_id, référence, extrait, chemins sources et statut de complétude. Le navigateur affiche ces informations ; il ne reconstruit pas lui-même une citation depuis le texte du LLM.

API vers administration

Les futures routes /api/v1/admin/* exigeront un jeton OIDC, un rôle serveur et un journal d'audit. Une mutation sensible accepte une clé d'idempotence. L'existence d'un écran administratif ne constitue pas l'activation d'une capacité.

API vers fournisseur LLM

Un adaptateur isole le fournisseur du domaine. Le contrat transmet un dossier de preuves et exige une sortie structurée ; il enregistre modèle, révision, paramètres et consommation. Changer de fournisseur ne doit pas modifier le format public des citations.

Compatibilité

Une évolution additive reste dans la version courante. La suppression ou modification sémantique d'un champ impose une nouvelle version d'API ou d'artefact, une période de migration et un test de contrat entre producteurs et consommateurs.