Score semantics

The API returns around twenty numbers between 0 and 1, under three names: confidence, strength and value. They look like confidence levels; none of them is one. This page explains what each number measures, what it may be compared with, and what to read instead when you need to decide.

What these numbers are not

No number returned by the API is a probability. A confidence.entity of 0.85 does not mean "an 85 % chance that the entity is right"; a match_strength.value of 0.5 does not mean "one chance in two". The contract says so in two ways:

• the calibration field, carried by every score object (confidence, match_strength, provenance, cadence_detail, calendar_pattern, lifecycle), is always non_calibree: none of these values has been related to an observed frequency on a reference corpus;
• the x-noryo-score extension, carried by every number in the contract that looks like a confidence, always declares its class, calibration: non_calibree and is_probability: false, and depending on the number comparable_within, not_comparable_with, formula, source or duplicate_of.

non_calibree is the only value the contract admits in this version, and that is a constraint, not a convention. These annotations can be read at https://api.noryo.app/openapi.json or in the generated reference.

The six classes

The classes are described under components.x-noryo-score-classes in the contract, exactly as served:

Where each class applies

lifecycle.cadence_strength and lifecycle.calendar_anchor are not additional scores: they are copies (duplicate_of in the contract), returned so that the lifecycle can be read on its own. The name confidence under resolution is kept for ti_v1 compatibility: read it as "declared strength of the pattern", never as a confidence.

Comparing: only within a class and a type

A number may only be compared with another number of the same class, produced for the same kind of object, by the same detector version. Take evidence_ratio: the value is present / possible, and the denominator depends on the type (5 possible signals for refund_of, 4 for reversal_of, 2 for transfer_pair, 5 heterogeneous criteria for a series). The same 0.5 is therefore one signal out of two for a transfer pair and two out of four for a reversal:

{
  "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 }
  }
}

This is why corroborations is returned next to value: without present and possible, the number cannot be read. A series match_strength counts five criteria (calendar cadence, fixed or narrow amount, at least three occurrences, known entity, specialised type): same name, different measure.

The other classes follow the same logic:

• calendar_fill: between series of the same cadence. A weekly series over eight weeks and a yearly one over two years cannot be compared. 0 means "no calendar hypothesis was retained" (cadence irregular_recurring), not "weak".
• anchor_stability: between series of the same anchor type and the same cadence. A 0.33 on fixed_day_of_month and a 0.3 on flexible_calendar_window do not say the same thing, and flexible_calendar_window changes its rule with the cadence. 0 corresponds to the unknown type.
• authority_tiebreak: only after the nature of authority. The order curated, deterministic, provider, inferred, participant is declared, not derived from a number: a 0.95 of nature inferred does not beat a 0.90 of nature curated. strength only separates two sources of the same nature.
• text_coverage: a property of the text, the share of the useful descriptor covered by the pattern (coverage) or the share of a compact pattern covered by a truncated fragment (covered, the tronque route). Comparable between descriptors, it is not proof of identity.

Decide with policy.outcome, not with a threshold

The declared_constant class is the most tempting one to use as a threshold. The five numbers under resolution.confidence are constants set by the person who wrote the pattern or the rule: every transaction that hits the same pattern receives the same number. Their class is marked monotonic: false in the contract: the measured precision, documented in the class description, is not monotone in this number, and a threshold on it does not separate right from wrong.

Read resolution.policy instead:

• outcome is resolved (every dimension the archetype requires is present), partial (the nature is known, a required dimension is missing, or signals contradict each other) or unresolved (even the nature of the transaction is unknown);
• missing names the absent dimensions: counterparty_entity, counterparty_type, transaction_type or resolution_policy;
• archetype says what "resolved" requires here: a transfer to a person is resolved without any entity, a cash withdrawal without a merchant, a card purchase requires its counterparty.

{
  "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"
  }
}

Here confidence.transaction_type is 0.95 even though the transaction is not resolved: the type is known from a rail rule, the counterparty is not. It is policy.outcome and policy.missing that tell you so, not the numbers.

0 has a precise meaning per field: abstention for entity, unknown role for counterparty, conflict with no common ancestor for transaction_type; location is always 0 in this version. When signal_conflicts is not empty, outcome is partial: the engine declines to conclude. An identity abstention (identity_abstention), by contrast, leaves outcome at resolved if the archetype did not require an entity.

Keeping a number: keep the version with it

If you store a value, store the version that produced it: resolution.versions (engine, resolution_policy, calibration) for the resolution, detector_version for a relationship or a series. The same value, under another version, may no longer measure the same thing.

Statistical calibration: not available

No statistical calibration is available in this version. When a real calibration exists, it will enter through a declared migration, together with the corpus that supports it. Until then, the confidence and strength values are deterministic evidence strengths: the same pattern, signals and version always give the same number. Decide on policy.outcome, on the enums (status, lifecycle.state, identity.status) and on the evidence (evidence, corroborations, signals.used).

Further reading

• Enrich a transaction
• Relationships
• Recurring series
• Counterparties and entities
• Generated reference, every field with its x-noryo-score