Skip to main content

Confidence Scoring API

Pillar 1 endpoint that computes a multi-dimensional confidence score for a case's latest investigation. The score is derived from document completeness, OSINT corroboration, discrepancy analysis, officer calibration history, and optional reasoning-template caps.

Endpoints Summary​

MethodPathPurpose
GET/api/cases/{workflow_id}/confidenceCompute confidence score for a case

Get Confidence Score​

GET /api/cases/{workflow_id}/confidence

Computes and returns the confidence score for a case's latest investigation iteration. The score aggregates four dimensions (0-25 each, totaling 0-100):

  1. Document completeness -- ratio of valid documents received vs. required
  2. OSINT corroboration -- number of independently confirmed data points
  3. Discrepancy analysis -- penalty for unresolved discrepancies between sources
  4. Officer calibration -- historical agreement rate for the officer on similar cases

If a Pillar 2 reasoning template applies to the case, it may impose a confidence cap that limits the maximum achievable score when red flag rules are triggered.

Path Parameters:

NameTypeRequiredDescription
workflow_idstringYesTemporal workflow ID of the case

Response 200

{
  "case_id": "case-abc-123",
  "iteration": 2,
  "total": 15,
  "earned_total": 61.5,
  "document_score": 20,
  "corroboration_score": 22,
  "discrepancy_score": 15,
  "calibration_score": 15,
  "reasoning_template_id": "be_psp_aml",
  "confidence_cap": 15,
  "confidence_cap_reason": "Capped by Sanctions match (critical); evidence gated by Missing/expired insurance (high)"
}

The response is a ConfidenceScore object. When no investigation results exist yet, the endpoint returns a score with iteration: 0 and all dimension scores at their defaults.

Two readings: evidence quality vs readiness to decide​

total and earned_total express two different things, and the UI shows both when they diverge:

  • earned_total -- the raw sum of the four dimensions before any rule imposition (an evidence gate or a confidence cap). This is the investigation's earned evidence strength -- how thorough the work was.
  • total -- the readiness to decide: earned_total after every applicable control is applied (evidence gate, then reasoning-template cap, then the ADR-0089 material-check penalty), clamped to 0-100.

When earned_total > total, the score was held back by a control, not weak. A thorough investigation (high earned_total) can still show a low total -- for example a sanctions/criminal cap, or missing professional-liability insurance. The card renders these as two separate meters so a strong case is never misread as a weak one.

confidence_cap_reason names the actual control(s) that reduced the score -- never inferred from document counts (these reductions are adverse-finding- or rule-driven). It carries every active cause together: a material-screen gap, each matched CAP_CONFIDENCE rule, and each matched GATE_EVIDENCE rule -- so no confirmed control is hidden behind another. It is null when nothing reduced the score.

The two-reading behaviour and its rationale are recorded in the confidence card design (issue #8) and hardened across the Codex review of PR #493.

Status Codes:

  • 200 -- Success
  • 404 -- Case not found or workflow not running