inference_contract/INFERENCE.md

# Inference contract: FlowX Semantic Mapper

Prompt version: `mapper_sys_v1`.

This model was trained against a **frozen inference contract**: an exact system
prompt, an exact user-turn format, a fixed decode setting, and a fixed output
schema. Reproduce all four or the outputs drift. Do not edit the prompt or schema;
the weights are trained against them.

Files in this directory:

- [`prompt_mapper_sys_v1.txt`](./prompt_mapper_sys_v1.txt): the system prompt, verbatim.
- [`schema_mapper_v1.json`](./schema_mapper_v1.json): JSON Schema for the output object (structural / semantic / governance).

Referenced from the repo root:

- `concept_taxonomy.yaml`: the 252-concept controlled vocabulary the `concepts` field is drawn from.

---

## 1. System prompt (verbatim)

The exact contents of [`prompt_mapper_sys_v1.txt`](./prompt_mapper_sys_v1.txt):

```
You are a legal and regulatory ontology extractor.
Extract structured tags from document chunks. Output ONLY valid JSON.
```

Send it as the `system` turn. No trailing whitespace, no extra lines.

## 2. User turn format

One regulatory/legal text chunk per request, wrapped exactly like this:

```
Extract ontology from this chunk:

CHUNK:
<the regulatory text>
```

- The literal header `Extract ontology from this chunk:`, a blank line, then
  `CHUNK:`, a newline, then the raw chunk text.
- One chunk per call. The model was trained on single-chunk turns; do not batch
  multiple clauses into one user turn.
- Pass the chunk verbatim (the source language is fine: EN, FR, DE, RO). Do not
  pre-summarize or translate it.

## 3. Decode settings

| Setting | Value | Why |
| --- | --- | --- |
| `enable_thinking` | **`False`** | Qwen3 is a thinking model, but the adapter was trained on pure JSON with no reasoning block. Leaving thinking on yields an empty or malformed object. |
| `temperature` | **`0` (greedy)** | The task is deterministic extraction; sampling only adds drift. |
| `max_new_tokens` | **~1024** | A full three-facet object fits comfortably; 1024 leaves headroom for long hierarchies. |
| stop | end-of-turn | The model emits a single JSON object and stops. |

Apply the chat template with `add_generation_prompt=True, enable_thinking=False`.

## 4. Output

A single JSON object with three top-level facets (`structural`, `semantic`,
`governance`), conforming to [`schema_mapper_v1.json`](./schema_mapper_v1.json).
Parse it strictly. On held-out data JSON validity is 1.00 and all three facets are
present 1.00, so a parse failure means the contract above was not reproduced (most
often `enable_thinking` left at its default).

## 5. The controlled concept vocabulary (required for `semantic.concepts`)

`semantic.concepts` is **not** free text. It is drawn from a **252-concept
controlled taxonomy** shipped as `concept_taxonomy.yaml` at the repo root (6
categories: money, rights_waived, time_renewal, lease, insurance, data; each entry
has an `id`, a `definition`, and a `primary_domain`).

This is the model's central design choice. Open free-text concepts (1062 unique in
the first corpus, 88% of them singletons) were unlearnable and unmeasurable;
collapsing to 252 canonical ids made the `concepts` facet both learnable and
scoreable (F1 0.24 → 0.54). At integration time you should:

- Treat any concept id **not** present in `concept_taxonomy.yaml` as
  out-of-vocabulary and drop or flag it. The model targets the controlled set but
  can still surface an occasional near-miss id.
- Use the taxonomy `id` as the join key into your policy layer.

`domain_tags`, by contrast, are a **free snake_case** vocabulary and are expected
to be noisier / less consistent than `concepts`.

## 6. Downstream

The `governance.escalation_trigger` (`if <condition> THEN escalate`) and
`policy_references` (`PDP.<domain>.<rule>`) are consumed by the sibling
**[`flowxai/sentinel-gate`](https://huggingface.co/flowxai/sentinel-gate)**
escalation model: Mapper tags a chunk → policy layer → Sentinel decides
DECIDE vs ESCALATE. Keep the field names stable so the pipeline lines up.