# Safety & Monitoring

Configure safety policies, create semantic monitoring concepts, and apply regulation-based templates to enforce compliance rules across conversations.

{% @mermaid/diagram content="%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
flowchart TB
subgraph Signals\["Per-Turn Signal Detection"]
S1\["Monitor Concepts\n(semantic similarity)"]
S2\["Regulation Templates\n(compliance rules)"]
end

```
subgraph Triage["Risk Assessment"]
    T1["Per-Turn Triage\n(concern level scoring)"]
    T2["Accumulation Window\n(rolling N-turn evaluation)"]
end

subgraph Escalation["Escalation Levels"]
    E1["No Action\n(below threshold)"]
    E2["Alert\n(log + notify)"]
    E3["Behavior Change\n(agent adapts response)"]
    E4["Immediate Escalation\n(fast-track to operator)"]
end

S1 --> T1
S2 --> T1
T1 -->|"Below mild threshold"| E1
T1 -->|"Mild concern"| T2
T1 -->|"Fast-track level"| E4
T1 -->|"Single-turn threshold"| E3
T2 -->|"Below cumulative threshold"| E1
T2 -->|"Cumulative threshold reached"| E2" %}
```

## Monitor Concepts

Monitor concepts are semantic rules evaluated during conversations. When a concept is detected (via embedding similarity), it can trigger alerts, escalations, or specific agent behaviors.

Set detection thresholds carefully - too low produces false positives, too high misses genuine signals. Start with 0.80-0.85 and tune based on review queue data.

## Regulation Templates

Pre-built safety rule sets that can be applied to a workspace to quickly establish compliance baselines. Applying a template creates individual monitor concepts that you can then customize. Templates are composable - apply multiple templates to a single workspace.

## Per-Service Safety Filters

Safety monitoring can be toggled per-service via the `safety_filters_enabled` field in the service config (defaults to `true`). When disabled, the conversation monitoring pipeline (monitor concepts, triage, accumulation) is bypassed for that service while independent risk scoring remains active. This is useful for non-clinical services (general information lines, internal testing) that do not require clinical safety rules.

See [Services](https://docs.amigo.ai/developer-guide/platform-api/platform-api/services) for configuration details.

## Safety Configuration

Workspace-level safety policy that controls how monitoring signals are aggregated and acted upon, including triage settings, accumulation windows, and escalation thresholds.

Key accumulation fields:

| Field                                | Default | Description                                                            |
| ------------------------------------ | ------- | ---------------------------------------------------------------------- |
| `accumulation_window_size`           | 10      | Number of recent turns evaluated for accumulated concern               |
| `accumulation_single_turn_threshold` | 2       | Concern level that triggers action on a single turn                    |
| `accumulation_cumulative_count`      | 2       | Number of concern signals within the window that triggers action       |
| `accumulation_mild_threshold`        | 1       | Minimum concern level counted toward accumulation                      |
| `accumulation_fast_track_level`      | 3       | Concern level that bypasses accumulation and triggers immediate action |

## Unified Audit Trail

The Platform API maintains a unified audit trail across all services. Every significant action is recorded as an audit event with full context.

### Audit Event Fields

| Field                 | Description                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `service`             | Which service generated the event (platform-api, voice-agent, connector-runner, identity) |
| `actor_entity_id`     | Who performed the action                                                                  |
| `actor_credential_id` | Which credential was used                                                                 |
| `action`              | What was done (e.g., `entity.read`, `call.recording_access`, `session.create`)            |
| `resource_type`       | Type of resource affected                                                                 |
| `resource_id`         | Specific resource affected                                                                |
| `ip_address`          | Source IP                                                                                 |
| `user_agent`          | Client user agent                                                                         |
| `phi_accessed`        | Whether this action accessed PHI                                                          |

### PHI Access Logging

Requests to PHI-sensitive endpoints are automatically detected and flagged. The platform recognizes patterns including entity reads, FHIR patient data, CRM contacts, call recordings, call intelligence, and audit reports themselves. PHI access events are tagged with `phi_accessed: true` for compliance reporting.

Audit events are written asynchronously via a buffered writer - they do not add latency to the request path.

### Audit Query Endpoints

Four endpoints under `/v1/{workspace_id}/audit/` for compliance dashboards and investigation:

| Endpoint                                   | Description                                                                                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /audit`                               | List audit events with filters: service, action, actor, resource type, resource ID, PHI-only, date range. Paginated.                                                     |
| `GET /audit/phi-access`                    | PHI access report - who accessed what patient data, when, from where. Filterable by patient entity and date range. Required for HIPAA breach investigation (164.312(b)). |
| `GET /audit/entity/{entity_id}/access-log` | All audit events for a specific resource.                                                                                                                                |
| `GET /audit/summary`                       | Summary statistics: total events, PHI access events, unique actors, services with activity.                                                                              |

All endpoints require `admin` or `owner` permissions and are workspace-scoped.

## Data Lineage

`GET /world/entities/{entity_id}/lineage` - Full data lineage composing provenance, outbound sync, and review history.

Returns three sections:

| Section          | Contents                                                                                |
| ---------------- | --------------------------------------------------------------------------------------- |
| `provenance`     | Contributing data sources, confidence history over time, entity resolution merge events |
| `outbound_sinks` | External systems that received this entity's data, sync status, timestamps              |
| `review_history` | Review queue items for the entity, verdicts, reviewer actions                           |

Permissions: `viewer+`. Returns 404 if entity not found.

## Retention Policies

`GET /settings/retention` - Get the workspace retention policy. Returns HIPAA-compliant defaults (2190 days / 6 years) for any field not explicitly configured.

`PUT /settings/retention` - Update the workspace retention policy (partial updates supported).

| Field                   | Type    | Default | Range     | Description                                       |
| ----------------------- | ------- | ------- | --------- | ------------------------------------------------- |
| `call_recordings_days`  | integer | 2190    | 365-36500 | Call recording retention                          |
| `call_transcripts_days` | integer | 2190    | 365-36500 | Call transcript retention                         |
| `audit_log_days`        | integer | 2190    | 365-36500 | Audit log retention                               |
| `world_events_days`     | integer | 2190    | 365-36500 | World model event retention                       |
| `phi_data_days`         | integer | 2190    | 365-36500 | PHI data retention                                |
| `legal_hold`            | boolean | false   | -         | Override all retention (no deletion when enabled) |
| `legal_hold_reason`     | string  | null    | -         | Documentation for legal hold                      |

`GET /settings/retention` is available to any authenticated user. `PUT /settings/retention` requires `admin` or `owner`. Retention changes are audit-logged.

{% hint style="info" %}
Retention policies are currently advisory - the policy is stored and displayed but automated deletion is not yet enforced.
{% endhint %}

## Audit Log Export

| Endpoint             | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| `POST /audit/export` | Create a new audit log export for a date range. Returns an export ID. |
| `GET /audit/exports` | List all exports for the workspace with status and download URLs.     |

Exports are generated as NDJSON files and uploaded to secure cloud storage. Each export includes a time-limited download URL (12 hours). Capped at 50,000 events per export.

The export action itself is recorded as an audit event with PHI flag if the export contains PHI access data.

Returns `503` if export storage is not configured for the deployment.

Requires `admin` or `owner` permissions.

## Compliance Reports

Two endpoints under `/v1/{workspace_id}/compliance/` for auditor-facing reports:

| Endpoint                        | Description                                                                                                                                                                               |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /compliance/hipaa`         | HIPAA evidence report: audit statistics, retention policy, encryption status, API key summary for a configurable period (1-365 days, default 90). Returns a compliance status assessment. |
| `GET /compliance/access-review` | SOC 2 access review: all API key credentials with role, status, and activity dates for attestation.                                                                                       |

Both require `admin` or `owner` permissions.

## API Reference

* [Monitor Concepts](https://docs.amigo.ai/api-reference/readme/platform/monitor-concepts)
* [Safety](https://docs.amigo.ai/api-reference/readme/platform/safety)
* [Audit](https://docs.amigo.ai/api-reference/readme/platform/audit)
* [Retention](https://docs.amigo.ai/api-reference/readme/platform/retention)
* [Compliance](https://docs.amigo.ai/api-reference/readme/platform/compliance)