AI Enrichment

Understand Sentra's non-blocking KYC/KYB AI signal pipeline and LLM cache behavior.

Sentra can enrich risk decisions with KYC/KYB document signals. This is intentionally non-blocking: /v1/risk/score returns immediately even when AI signals are not ready.

Why enrichment is async

Payment risk decisions need predictable latency. LLM calls can be slower, unavailable, or require retries. Sentra therefore:

Checks Redis cache for KYC/KYB signals.
Uses cached signals when available.
Returns llm_status: "ready" if signals are available.
Returns llm_status: "pending" if KYC/KYB refs exist but no cache is ready.
Queues a background job to compute AI signals.
Updates the stored risk score once enrichment finishes.

Cache key

LLM cache keys use:

sentra:llm:{doc_hash or entity_id}:{prompt_version}

Cached values are stored for seven days in the current implementation.

LLM output schema

The AI service must return strict JSON:

{
  "signals": [
    {
      "name": "kyb_document_adverse_match",
      "value": 0.93,
      "severity": "high",
      "confidence": 0.92
    }
  ],
  "extracted_fields": {
    "jurisdictions": ["BR", "MX"]
  },
  "rationale": "AI enrichment completed from KYC/KYB materials.",
  "evidence": [
    {
      "source": "kyc_doc",
      "span": "risk_snippet",
      "quote": "Document references adverse ownership or sanctions-related concerns."
    }
  ]
}

Parsing behavior

The backend:

Strips markdown code fences, including JSON-labelled fences.
Parses JSON.
Validates with Pydantic.
Retries once on parse failure.
Falls back to empty signals with rationale: "LLM_PARSE_FAILED" if parsing still fails.
Persists parse errors in risk_scores.llm_error.

Feature contribution

When AI signals are available, Sentra converts them into numeric features:

Feature	Meaning
`llm_signal_count`	Number of extracted signals.
`llm_high_severity_count`	Count of high-severity signals.
`llm_value_sum`	Sum of signal values.
`llm_confidence_mean`	Mean confidence across signals.

Trigger AI manually

Admins can trigger AI from the case detail page or API.

curl "$SENTRA_API_BASE/v1/admin/llm/trigger" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "case_id": "case_abc123" }'

Possible outcomes:

Status	Meaning
`queued`	AI job accepted.
`noop`	Latest score is already ready.
`missing_kyc`	No KYC/KYB references are available for the case.

Demo AI runtime

Local/demo mode can use deterministic AI behavior. It emits signals for patterns such as:

Cross-border mismatch.
Large ticket amount.
Sanctions, UBO mismatch, adverse media, shell-company language, or cash-intensive references.
Otherwise, a low-severity consistent-document signal.