> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Research

> Trigger AI-powered research on alerts, understand confidence scores, and configure the auto-disposition pipeline.

# AI Research

Zenoo integrates AI-powered research to help compliance analysts evaluate screening matches faster and with greater accuracy. The AI analyzes alert data against public sources, produces structured assessments, and can automatically resolve high-confidence false positives.

## How it works

When AI research is triggered on an alert, the system:

1. **Builds a research prompt** with the alert details, entity context, and screening match data
2. **Submits to Perplexity AI** (sonar-pro model) for live web research
3. **Parses the structured response** into assessment fields
4. **Updates the alert** with the AI analysis results
5. **Optionally chains to auto-disposition** if configured for the alert category

```mermaid theme={null}
sequenceDiagram
    participant A as Analyst / System
    participant Z as Zenoo
    participant AI as Perplexity AI
    A->>Z: Trigger AI research
    Z->>AI: Research prompt + alert context
    AI-->>Z: Structured assessment
    Z->>Z: Update alert fields
    Z->>Z: Evaluate auto-disposition
    Z-->>A: Notification (complete)
```

## Triggering AI research

### Manual trigger (API)

```bash theme={null}
curl -X POST "https://api.zenoo.com/v1/alerts/alt_001/ai-research" \
  -H "Authorization: Bearer your-api-key"
```

**Response:**

```json theme={null}
{
  "status": "processing",
  "message": "AI research initiated. Results will be available shortly.",
  "estimated_seconds": 15
}
```

### Automatic trigger (auto-triage)

When auto-triage is enabled, new alerts are automatically sent for AI research based on configuration rules:

| Configuration       | Description                                       |
| ------------------- | ------------------------------------------------- |
| Allowed alert types | Which types trigger auto-triage (e.g., Screening) |
| Excluded categories | Categories to skip (e.g., Sanctions Hit)          |
| Batch size          | Maximum alerts processed per trigger              |

<Info>
  Auto-triage runs asynchronously. For large batches, the system uses Platform Events to distribute the workload across multiple async processes.
</Info>

## AI assessment structure

After research completes, the alert is updated with the following fields:

| Field                        | Type   | Description                                                  |
| ---------------------------- | ------ | ------------------------------------------------------------ |
| `ai_assessment`              | string | Detailed narrative analysis of the screening match           |
| `ai_confidence`              | number | AI confidence in the assessment (0-100%)                     |
| `false_positive_probability` | number | Estimated probability the match is a false positive (0-100%) |
| `ai_recommended_action`      | string | Suggested resolution: `Approve`, `Decline`, `Escalate`       |
| `ai_sources`                 | array  | URLs and titles of sources consulted                         |
| `ai_researched_at`           | string | ISO 8601 timestamp of research completion                    |

### Retrieving AI results

```bash theme={null}
curl -X GET "https://api.zenoo.com/v1/alerts/alt_001/ai-research" \
  -H "Authorization: Bearer your-api-key"
```

**Response:**

```json theme={null}
{
  "status": "completed",
  "assessment": "The matched entity 'J. Smith' on the OFAC SDN list was designated in 2019 for activities related to Iranian oil exports. The subject 'John Smith' is a UK national with no connection to the sanctioned individual. Different date of birth (1975 vs 1960) and different country of residence.",
  "confidence": 92,
  "false_positive_probability": 95,
  "recommended_action": "Approve",
  "sources": [
    {
      "title": "OFAC SDN List",
      "url": "https://sanctionssearch.ofac.treas.gov/"
    },
    {
      "title": "Companies House",
      "url": "https://find-and-update.company-information.service.gov.uk/"
    }
  ],
  "researched_at": "2026-02-16T10:05:30Z"
}
```

## Confidence scores

The AI produces two related but distinct scores:

| Score                          | What it measures                               |
| ------------------------------ | ---------------------------------------------- |
| **AI Confidence**              | How certain the AI is about its own assessment |
| **False Positive Probability** | How likely the match is a false positive       |

A high confidence score with a high false positive probability means the AI is very sure this is not a true match. A high confidence score with a low false positive probability means the AI is very sure this is a genuine match that requires action.

| Confidence      | FP Probability  | Interpretation                          |
| --------------- | --------------- | --------------------------------------- |
| High (above 80) | High (above 80) | Strong evidence of false positive       |
| High (above 80) | Low (below 30)  | Strong evidence of true positive        |
| Low (below 50)  | Any             | Insufficient data -- needs human review |

## Auto-disposition pipeline

Alerts that meet category-specific thresholds can be automatically resolved as false positives:

```mermaid theme={null}
flowchart TD
    A[AI Research Complete] --> B{Config enabled?}
    B -->|No| C[Leave for human review]
    B -->|Yes| D{FP probability >= threshold?}
    D -->|No| C
    D -->|Yes| E[Auto-resolve as False Positive]
    E --> F{QA sampling enabled?}
    F -->|Yes| G[Flag for QA review]
    F -->|No| H[Done]
    G --> H
```

### Configuration per category

| Category        | Auto-Disposition | FP Threshold | QA Sample Rate |
| --------------- | ---------------- | ------------ | -------------- |
| `PEP Match`     | Enabled          | 90%          | 10%            |
| `Adverse Media` | Enabled          | 90%          | 15%            |
| `Sanctions Hit` | Disabled         | N/A          | N/A            |
| `Name Mismatch` | Enabled          | 85%          | 5%             |
| `DOB Mismatch`  | Enabled          | 85%          | 5%             |

<Warning>
  Sanctions hits are never auto-disposed by default. Automated resolution of sanctions matches may violate regulatory requirements. Always configure Sanctions Hit with auto-disposition disabled.
</Warning>

### QA sampling

A configurable percentage of auto-disposed alerts are flagged for quality assurance review. QA-flagged alerts are resolved but marked with `qa_sample: true`, allowing compliance officers to periodically review the AI's accuracy.

## Company research

AI research can also be used for KYB (Know Your Business) company research:

```bash theme={null}
curl -X POST "https://api.zenoo.com/v1/entities/ent_abc123/ai-research" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "research_type": "company",
    "include": ["registration", "directors", "financials", "media"]
  }'
```

This returns a structured company profile with registry data, director information, financial overview, and recent media mentions.

## Next steps

* [Alert Management](/guides/alert-management). Full alert lifecycle and resolution options.
* [Alert Review Quickstart](/use-cases/alert-review). Hands-on alert triage walkthrough.
* [Alerts Data Model](/data-model/alerts). Full field reference including AI fields.