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

# Policies

> Define, assign, and evaluate governance rules. Bundle rules into packs. Track compliance across apps.

Policies are the rules your runtime has to obey. Observatory's policy engine defines those rules, assigns them to apps, evaluates them against actual runs, and rolls the results up into a compliance score per app and per policy.

***

## Concepts

| Model                | What it represents                                                                                   |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| **Policy**           | A single rule. Carries severity (`low`, `medium`, `high`, `critical`) and an evaluator expression.   |
| **PolicyPack**       | A named bundle of policies that ship together (e.g. "PII basics", "EU AI Act high-risk app").        |
| **PolicyAssignment** | A pack assigned to one app.                                                                          |
| **PolicyEvaluation** | One evaluation of one policy against one run. Stores the outcome and any captured violation context. |

```mermaid theme={"system"}
flowchart LR
    Policy[Policy] --> Pack[PolicyPack]
    Pack --> Assignment[PolicyAssignment]
    App[App] --> Assignment
    Run[Run] --> Eval[PolicyEvaluation]
    Assignment --> Eval
    Policy --> Eval
```

***

## Severities

| Severity     | Use for                                                       | Default behaviour                  |
| ------------ | ------------------------------------------------------------- | ---------------------------------- |
| **critical** | Things that must never happen — PII leak, credential exposure | Page on first violation.           |
| **high**     | Serious deviations from expected behaviour                    | Alert, surfaces on Risk Dashboard. |
| **medium**   | Quality issues — refusals, low confidence                     | Counted, no immediate alert.       |
| **low**      | Style or formatting                                           | Counted only.                      |

***

## Creating a policy

<Steps>
  <Step title="Open Policies → Policies">
    Click **Add policy**.
  </Step>

  <Step title="Name and describe">
    The description is what reviewers see during an audit. Be specific.
  </Step>

  <Step title="Pick a severity">
    Critical and high contribute to the **Compliance** roll-up score; medium and low are reported but don't block.
  </Step>

  <Step title="Define the evaluator">
    Built-in evaluators cover PII detection, toxicity, prompt-injection patterns, and a few model-specific checks. Custom evaluators are user-defined Python predicates.
  </Step>

  <Step title="Test against past runs">
    Use **Evaluate** to dry-run the policy against the last N runs of a chosen app. The preview shows which runs would have violated.
  </Step>
</Steps>

***

## Bundling into packs

Policies travel in packs. A pack is what you assign — never an individual policy.

Typical packs:

* **PII basics** — emails, phone numbers, government IDs.
* **EU AI Act high-risk** — full set of obligations for high-risk apps.
* **Internal data hygiene** — no production data in development environments.
* **Customer-facing assistant** — refusal patterns, escalation triggers.

Create a pack from **Policies → Packs**, add policies to it, then assign the pack to one or more apps under **Assignments**.

***

## Compliance roll-up

The **Compliance** tab scores each app against the policies assigned to it. The score weights by severity — critical violations dominate, low violations contribute proportionally.

```http theme={"system"}
GET /api/policies/compliance?app_id=...
```

Returns:

* `score` — 0–100
* `violations_by_severity`
* `top_violated_policies` — useful for prioritising remediation

***

## API

| Endpoint                         | Use                                    |
| -------------------------------- | -------------------------------------- |
| `GET /api/policies`              | List policies.                         |
| `POST /api/policies`             | Create.                                |
| `GET /api/policies/packs`        | List packs.                            |
| `POST /api/policies/packs`       | Create.                                |
| `POST /api/policies/assignments` | Assign a pack to an app.               |
| `POST /api/policies/evaluate`    | Run evaluation against a run or batch. |
| `GET /api/policies/compliance`   | Roll-up score.                         |

<Warning>
  FastAPI route ordering matters. Static routes (`/evaluate`, `/compliance`) must be defined before the `/{org_id}` catch-all. If you fork the router, keep that order.
</Warning>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Evidence" icon="folder-open" href="./evidence">
    Capture the artefacts that prove policy enforcement.
  </Card>

  <Card title="Risk Dashboard" icon="triangle-exclamation" href="./risk-dashboard">
    See how policy compliance feeds the per-app risk score.
  </Card>
</CardGroup>