Sémantique des scores

L'API rend une vingtaine de nombres compris entre 0 et 1, sous trois noms : confidence, strength et value. Ils ressemblent à des confiances ; aucun n'en est une. Cette page dit ce que chacun mesure, avec quoi il se compare, et sur quoi décider à la place.

Ce que ces nombres ne sont pas

Aucun nombre rendu par l'API n'est une probabilité. Un confidence.entity à 0,85 ne signifie pas « 85 % de chances que l'entité soit la bonne » ; un match_strength.value à 0,5 ne signifie pas « une chance sur deux ». Le contrat le dit de deux façons :

• le champ calibration, porté par chaque objet de score (confidence, match_strength, provenance, cadence_detail, calendar_pattern, lifecycle), vaut toujours non_calibree : aucune de ces valeurs n'a été rapportée à une fréquence observée sur un corpus de référence ;
• l'extension x-noryo-score, portée par chaque nombre du contrat qui ressemble à une confiance, déclare toujours sa class, calibration: non_calibree et is_probability: false, et selon le nombre comparable_within, not_comparable_with, formula, source ou duplicate_of.

non_calibree est la seule valeur que le contrat admet dans cette version, et c'est une contrainte, pas une convention. Ces annotations se lisent sur https://api.noryo.app/openapi.json ou dans la référence générée.

Les six classes

Les classes sont décrites dans components.x-noryo-score-classes du contrat, telles qu'elles sont servies :

Où chaque classe s'applique

lifecycle.cadence_strength et lifecycle.calendar_anchor ne sont pas des scores supplémentaires : ce sont des copies (duplicate_of dans le contrat), rendues pour que le cycle de vie se lise seul. Le nom confidence sous resolution est conservé pour la compatibilité de ti_v1 : lisez-le comme « force déclarée du motif », jamais comme une confiance.

Comparer : dans une classe et un type seulement

Un nombre ne se compare qu'à un autre nombre de la même classe, produit pour le même type d'objet, par la même version de détecteur. Prenez evidence_ratio : la valeur est present / possible, et le dénominateur dépend du type (5 signaux possibles pour refund_of, 4 pour reversal_of, 2 pour transfer_pair, 5 critères hétérogènes pour une série). Un même 0.5 vaut donc un signal sur deux pour une paire de virement et deux sur quatre pour une contre-passation :

{
  "type": "transfer_pair",
  "match_strength": {
    "value": 0.5,
    "calibration": "non_calibree",
    "corroborations": { "present": 1, "possible": 2 }
  }
}

{
  "type": "reversal_of",
  "match_strength": {
    "value": 0.5,
    "calibration": "non_calibree",
    "corroborations": { "present": 2, "possible": 4 }
  }
}

C'est pourquoi corroborations est rendu à côté de value : sans present et possible, le nombre ne se lit pas. Le match_strength d'une série compte cinq critères (cadence calendaire, montant fixe ou étroit, au moins trois occurrences, entité connue, type spécialisé) : même nom, autre mesure.

Les autres classes suivent la même logique :

• calendar_fill : entre séries de même cadence. Une hebdomadaire sur huit semaines et une annuelle sur deux ans ne se comparent pas. 0 signifie « aucune hypothèse calendaire retenue » (cadence irregular_recurring), pas « faible ».
• anchor_stability : entre séries de même type d'ancrage et de même cadence. Un 0.33 en fixed_day_of_month et un 0.3 en flexible_calendar_window ne disent pas la même chose, et flexible_calendar_window change de règle avec la cadence. 0 correspond au type unknown.
• authority_tiebreak : après la nature d'autorité seulement. L'ordre curated, deterministic, provider, inferred, participant est déclaré, pas déduit d'un nombre : un 0.95 de nature inferred ne l'emporte pas sur un 0.90 de nature curated. strength ne départage que deux sources de même nature.
• text_coverage : une propriété du texte, la part du libellé utile couverte par le motif (coverage) ou la part d'un motif compact recouverte par un fragment tronqué (covered, voie tronque). Comparable entre libellés, ce n'est pas une preuve d'identité.

Décider avec policy.outcome, pas avec un seuil

La classe declared_constant est la plus tentante comme seuil. Les cinq nombres de resolution.confidence sont des constantes posées par la personne qui a écrit le motif ou la règle : toute transaction qui touche le même motif reçoit le même nombre. Leur classe est marquée monotonic: false dans le contrat : la précision mesurée, documentée dans la description de la classe, n'est pas monotone en ce nombre, et un seuil dessus ne sépare pas le juste du faux.

Lisez à la place resolution.policy :

• outcome vaut resolved (toutes les dimensions exigées par l'archétype sont là), partial (la nature est connue, une dimension exigée manque, ou des signaux se contredisent) ou unresolved (la nature même de la transaction est inconnue) ;
• missing nomme les dimensions absentes : counterparty_entity, counterparty_type, transaction_type ou resolution_policy ;
• archetype dit ce que « résolu » exige ici : un virement à une personne est resolved sans entité, un retrait d'espèces sans marchand, un achat carte exige sa contrepartie.

{
  "policy": {
    "outcome": "partial",
    "archetype": "achat_carte",
    "missing": ["counterparty_entity"],
    "policy_version": "ti_resolution_v1"
  },
  "counterparty": null,
  "transaction_type": { "canonical": "card_purchase", "evidence": "rail_rule", "contradiction": null },
  "confidence": {
    "entity": 0,
    "counterparty": 0,
    "transaction_type": 0.95,
    "category": 0,
    "location": 0,
    "calibration": "non_calibree"
  }
}

Ici confidence.transaction_type vaut 0.95 alors que la transaction n'est pas résolue : le type est connu par une règle de rail, la contrepartie ne l'est pas. Ce sont policy.outcome et policy.missing qui le disent, pas les nombres.

0 a un sens précis par champ : abstention pour entity, rôle inconnu pour counterparty, conflit sans ancêtre commun pour transaction_type ; location vaut toujours 0 dans cette version. Quand signal_conflicts n'est pas vide, outcome est partial : le moteur refuse de conclure. Une abstention d'identité (identity_abstention) laisse en revanche outcome à resolved si l'archétype n'exigeait pas d'entité.

Conserver un nombre : la version à côté

Si vous stockez une valeur, stockez la version qui l'a produite : resolution.versions (engine, resolution_policy, calibration) pour la résolution, detector_version pour une relation ou une série. La même valeur, sous une autre version, peut ne plus mesurer la même chose.

Calibration statistique : indisponible

Aucune calibration statistique n'est disponible dans cette version. Le jour où une calibration réelle existera, elle entrera par une migration déclarée, avec le corpus qui la défend. D'ici là, les valeurs confidence et strength sont des forces d'évidence déterministes : mêmes motif, signaux et version donnent toujours le même nombre. Décidez sur policy.outcome, sur les enums (status, lifecycle.state, identity.status) et sur les preuves (evidence, corroborations, signals.used).

Pour aller plus loin

• Enrichir une transaction
• Relations
• Séries récurrentes
• Contreparties et entités
• Référence générée, chaque champ avec son x-noryo-score