HOLCO MCP · Documentation développeur

Données, provenance et contrôles

La spécification commune de collecte pour relier les données financières et documentaires sans perdre leur périmètre ni leur origine.

Portée du contrat

Cette page définit le modèle HOLCO cible pour les adaptateurs et leur recette. Les noms de champs ci-dessous sont une proposition de normalisation HOLCO, pas le schéma de réponse actuel de chaque outil MCP ni celui des éditeurs. La référence d’exécution reste le catalogue authentifié et la réponse de l’outil appelé.

Objets normalisés

Organisation / dossier : identifiant HOLCO, logiciel et identifiant source, pays, identité légale, rattachement au cabinet, périmètre autorisé.
Exercice / période : dates de début et de fin, état de clôture, origine de la définition, inclusion ou exclusion des brouillons.
Compte / journal : identifiant source, code conservé comme chaîne, libellé, type, relation auxiliaire et devise lorsqu’elle existe.
Écriture / ligne : identifiants propres, relation ligne–écriture, date comptable, date de pièce, débit, crédit, devise, compte, journal et références documentaires.
Tiers / facture : identité, fournisseur ou client, numéro, dates, échéance, HT, TVA, TTC, état, avoir, lignes et relations aux règlements.
Compte bancaire / transaction : identité du compte et du mouvement, montant, devise, sens, dates, statut, labels et pièces associées.
Document / extrait : identité, rattachement métier, type MIME, empreinte, version, date de récupération ; pour un extrait, page ou position et référence au document parent.
Contrôle / résultat : périmètre, règle et version, données utilisées, valeurs calculées, écart, qualification et limites de couverture.

Les champs absents restent inconnus. Un zéro n’est jamais une valeur de remplacement pour un montant manquant. Les identifiants légaux ne suffisent pas à fusionner automatiquement deux périmètres comptables.

Exemple d’enveloppe cible

Exemple entièrement fictif, destiné à expliquer la normalisation :

{
  "schema_version": "holco-data-contract/0.1",
  "entity_type": "ledger_line",
  "scope": { "workspace_id": "demo", "dossier_id": "demo-fr" },
  "source": {
    "provider": "example",
    "organization_id": "org-demo",
    "resource_id": "line-demo-001",
    "collected_at": "2026-09-09T10:00:00Z"
  },
  "data": {
    "entry_id": "entry-demo-001",
    "account_code": "606100",
    "accounting_date": "2026-08-31",
    "debit": "120.00",
    "credit": "0.00",
    "currency": "EUR"
  },
  "coverage": { "complete": false, "reason": "illustrative_single_line" }
}

Montants et temporalité

Utiliser un type décimal exact ou des unités monétaires mineures documentées ; éviter les flottants binaires pour les calculs comptables. Garder séparés montant source, devise, montant converti, taux et date de conversion. La convention de signe doit être définie pour chaque famille : débit/crédit comptable et entrée/sortie bancaire ne sont pas interchangeables.

Conserver les dates métier sans leur ajouter artificiellement une heure. Pour les horodatages, garder le fuseau ou normaliser en UTC avec la valeur d’origine. Distinguer date de pièce, date comptable, date de règlement, date de modification source et date de collecte. Les bornes de période doivent rester identiques entre détail et agrégat.

Synchronisation, suppression et complétude

Une collecte initiale fixe le périmètre avant de paginer. Chaque lot conserve le nombre d’objets reçus, rejetés et intégrés, les pages parcourues, la fenêtre et le point de reprise. Le curseur n’avance qu’après persistance réussie. Une reprise doit être idempotente sur une clé incluant le tenant, l’organisation, le type et l’identifiant source.

Une suppression documentée invalide aussi les relations et index dérivés. Une absence dans une page ne prouve pas une suppression. Si le journal de changements a expiré, recharger un état de référence. Pour les sources livrant des fragments, reconstituer l’objet avant d’exécuter un contrôle métier.

La complétude est un résultat de collecte, pas une propriété supposée de l’API. Une page manquante, un téléchargement échoué ou une relation inaccessible doit rester visible jusqu’à résolution.

Documents, RAG et restitution

Le pipeline cible sépare récupération, extraction, segmentation, indexation et recherche. Les segments conservent leur document parent, leur version, leur position et leur périmètre d’accès. Les tableaux doivent préserver les en-têtes et unités ; un nombre sans son contexte n’est pas une preuve exploitable.

Avant de transmettre un extrait au modèle, vérifier l’accès au dossier et la pertinence de la version. La réponse doit relier l’affirmation à l’extrait utilisé. Une référence juridique trouvée n’est pas une validation automatique de son application au dossier. La page architecture HOLCO détaille les mécanismes présents et la trajectoire d’évaluation.

Recette et observabilité

Le contrat de recette combine contrôles déterministes et évaluation des restitutions. Les égalités de montants, relations d’identité et règles d’isolation se vérifient par code. Les juges LLM peuvent évaluer la pertinence d’une réponse, mais ne remplacent pas une validation experte. Le golden set doit distinguer cas synthétiques et cas validés par un professionnel.

Mesurer durée, pages, volumes, erreurs, fraîcheur et complétude de collecte. Pour les appels de modèles côté serveur, tracer modèle réel, tokens et coût lorsqu’ils sont disponibles. La consommation du modèle dans le client de l’utilisateur reste un poste distinct. Une mesure absente demeure absente.