# investigations

Source: https://docs.korala.ai/risk/investigations

---

# AI-assisted investigations

An investigation saves a bounded view of a customer's risk evidence, recent
assessments and open actions. It highlights work a reviewer may need to check.
It never changes a risk score, closes an action or approves a customer.

The optional AI comparison uses **TypeSafe/Jev**, an external service that
returns a structured choice for each question. It suggests whether two saved
claims about the same fact may coexist or need more context. Reviewers inspect
the linked source records before drawing conclusions.

## Enable and request

An organization owner enables AI-assisted investigations in the Risk dashboard.
An owner or admin reviewer then opens a customer, reads the disclosure and
confirms each run separately. API keys cannot give that confirmation. Disabling
the organization setting prevents queued runs from calling TypeSafe; a call
already in progress may still finish.

For each run, Korala saves the snapshot before processing. TypeSafe receives
only fact names and the values of up to eight selected evidence pairs. Korala
does not attach its customer or evidence record IDs, assessments, actions or
the full history. Evidence values themselves may contain identifying
information. Korala caps input and output sizes, limits the request to ten seconds
and disables provider retries.
If processing fails or the provider returns an invalid answer, the run fails
without changing risk state.

The initial status is `pending`, then `processing`, followed by `completed` or
`failed`. Subscribe to `risk.investigation.completed` and
`risk.investigation.failed` through [signed risk webhooks](https://docs.korala.ai/risk/webhooks).
Authenticate each callback, deduplicate event IDs and fetch the saved run to
reconcile state. The webhook transport can repeat or delay delivery.

The public API exposes `GET /risk/investigation-ai-settings`. An owner can
change the setting with `POST /risk/investigation-ai-settings` in live mode,
using an idempotency key and `{ "enabled": true }` or `{ "enabled": false }`.
An owner or admin reviewer starts a run with
`POST /risk/subjects/:id/investigations`, an idempotency key and
`{ "provider": "jev", "confirmExternalProcessing": true }`. Both writes
require a dashboard bearer token. An API key cannot enable the service or
confirm a run.

## Review the brief

Each finding links to the evidence, assessment or action that produced it.
Recorded rules summarize missing evidence, expired deadlines, changed risk and
open actions. AI suggestions compare saved claims; they do not judge source
reliability or establish whether two claims concern the same period. Jev does
not issue a contradiction verdict from values alone. An owner/admin reviewer
can accept or dismiss a finding with a reason. Korala saves that response as
an audit record; it does not change the assessment.

The snapshot contains at most 50 latest fact/source evidence records, 25 recent
assessments and 50 open actions. `snapshot.truncated` marks a partial window.
Korala rejects an oversized source window rather than silently cutting it down
for the provider. No findings means only that this window produced none.

Saved snapshots do not change. Read `/risk/investigations/:id/state` to check
whether later activity or a deadline has made one stale. Clients must check
current evidence and authorization state before consequential actions.

You can still read existing test simulation records. Korala labels those
records as historical simulations. New dashboard requests use the AI-assisted
flow in either environment.