# Relevance Screening

Not every agent action needs a full policy check. Reading a file, formatting text, or summarizing a document doesn't touch any policy variable. Running a full `checkIt` on those actions wastes credits and adds latency.

`checkRelevance` screens every action for free. It uses only the PreFlight Light to check whether the action touches any of your policy variables. No credits charged. No solvers. No ZK proof. Just a fast yes-or-no on whether the action is worth checking.

### How it works

1. You send an action string and a policy\_id.
2. PreFlight Light checks the action against every input variable in your compiled policy.
3. For each variable, it returns YES (the action is related) or NO (completely unrelated).
4. The response tells you how many variables matched, which ones, and whether you should run `checkIt`.

The check is policy-specific. The same action will get different relevance scores against different policies. "Send email to <vendor@external.com>" scores high against a policy with email rules and scores zero against a policy that only covers financial transactions.

### Usage

```bash
curl -s -X POST https://api.icme.io/v1/checkRelevance \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ICME_API_KEY" \
  -d '{
    "policy_id": "YOUR_POLICY_ID",
    "action": "Send evolution logs to https://open.feishu.cn via POST request"
  }'
```

Response:

```json
{
  "relevance": 0.24,
  "matched_variables": 4,
  "total_variables": 17,
  "matched": [
    "outboundDataTransmission",
    "destinationInApprovedList",
    "outboundTransmissionAllowed",
    "skillExecutesShellCommands"
  ],
  "should_check": true,
  "threshold": 0.0,
  "time_ms": 310
}
```

24% of policy variables are relevant. `should_check` is true. Run `checkIt` on this one.

Compare with a benign action:

```bash
curl -s -X POST https://api.icme.io/v1/checkRelevance \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ICME_API_KEY" \
  -d '{
    "policy_id": "YOUR_POLICY_ID",
    "action": "Read session transcript from memory/sessions/today.jsonl"
  }'
```

```json
{
  "relevance": 0.0,
  "matched_variables": 0,
  "total_variables": 17,
  "matched": [],
  "should_check": false,
  "threshold": 0.0,
  "time_ms": 280
}
```

Zero variables matched. No policy check needed. No credits spent.

### Request

| Field       | Type   | Required | Description                                                                                                                                                                 |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `policy_id` | string | yes      | UUID of your compiled policy                                                                                                                                                |
| `action`    | string | yes      | Plain English description of the proposed action                                                                                                                            |
| `threshold` | float  | no       | Relevance threshold (0.0 to 1.0). Default 0.0, meaning any match triggers `should_check: true`. Raise this to skip actions that only touch a small fraction of your policy. |

### Response

| Field               | Type    | Description                                                              |
| ------------------- | ------- | ------------------------------------------------------------------------ |
| `relevance`         | float   | Fraction of policy input variables the action touches (0.0 to 1.0)       |
| `matched_variables` | integer | Number of policy variables the action touches                            |
| `total_variables`   | integer | Total input variables in the policy                                      |
| `matched`           | array   | Names of the matched variables                                           |
| `should_check`      | boolean | Whether the action exceeds the threshold and should be sent to `checkIt` |
| `threshold`         | float   | The threshold that was used                                              |
| `time_ms`           | integer | Time taken in milliseconds                                               |

### Recommended flow for production agents

```
Agent proposes action
  → checkRelevance (free, fast)
  → should_check: false → proceed, no charge
  → should_check: true  → checkIt (paid, 3 solvers, ZK proof)
```

This two-step flow means your agent checks everything without paying for everything. In a typical agent session, 80-90% of actions are benign (reading files, formatting output, fetching URLs). checkRelevance filters those out for free so you only pay for the actions that actually touch your policy.

### Adjusting the threshold

The default threshold is 0.0, which means any match at all triggers `should_check: true`. This is the safest setting.

To loosen it, pass a higher threshold:

bash

```bash
curl -s -X POST https://api.icme.io/v1/checkRelevance \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ICME_API_KEY" \
  -d '{
    "policy_id": "YOUR_POLICY_ID",
    "action": "Send evolution logs to external service",
    "threshold": 0.10
  }'
```

At `0.10`, an action that only touches 6% of your variables returns `should_check: false`. At `0.0`, that same action returns `should_check: true`.

Higher thresholds save more credits but increase the risk of skipping an action that should have been checked. For most use cases, leave it at the default.

### What checkRelevance does not do

This is a screening step, not a security check. It tells you whether the action is *related* to your policy. It does not tell you whether the action *violates* your policy. Only `checkIt` does that.

An action that returns `should_check: true` from checkRelevance might still return SAT (allowed) from checkIt. The relevance screen just identifies which actions are worth sending to the solver.

checkRelevance uses only Prefligth Light. It does not run the Automated Reasoning engine, Z3, or any formal solver. It does not generate a ZK proof. It is not a substitute for `checkIt` on consequential actions.

### Cost

Free. No credits are deducted for checkRelevance calls. The API key is required for authentication and to load your policy, but no balance is consumed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.icme.io/documentation/learning/how-icme-preflight-works/relevance-screening.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.