README.md

---
license: apache-2.0
language:
  - en
  - fr
  - de
  - ro
library_name: transformers
pipeline_tag: text-generation
base_model: Qwen/Qwen3-4B
tags:
  - lora
  - regulatory
  - compliance
  - ontology-extraction
  - information-extraction
  - mlx
  - gguf
  - flowx
model-index:
  - name: semantic-mapper
    results:
      - task:
          type: text-generation
          name: Regulatory ontology extraction (held-out, document-disjoint, EN/FR/DE/RO)
        metrics:
          - type: f1
            name: concepts F1 (controlled 252-concept vocab)
            value: 0.54
          - type: f1
            name: concepts F1 (fuzzy / semantic match)
            value: 0.58
          - type: f1
            name: domain_tags F1 (free-text)
            value: 0.55
          - type: accuracy
            name: entities field-accuracy
            value: 0.53
          - type: accuracy
            name: JSON validity
            value: 1.0
          - type: accuracy
            name: all-3-facets present
            value: 1.0
---

## Inference contract

Running this model correctly requires its **frozen inference contract**: the exact
system prompt, user-turn format, decode settings, and output JSON schema it was
trained against. See [`inference_contract/`](./inference_contract):

- [`INFERENCE.md`](./inference_contract/INFERENCE.md): wiring guide: system prompt, user turn (`Extract ontology from this chunk:\n\nCHUNK:\n<text>`), decode settings (`enable_thinking=False`, greedy/temp 0, `max_new_tokens` ~1024), and the note that `semantic.concepts` is constrained to the **252-concept controlled vocabulary** (`concept_taxonomy.yaml`, shipped at repo root).
- [`prompt_mapper_sys_v1.txt`](./inference_contract/prompt_mapper_sys_v1.txt): the system prompt, verbatim.
- [`schema_mapper_v1.json`](./inference_contract/schema_mapper_v1.json): output JSON Schema (structural / semantic / governance).

Prompt version `mapper_sys_v1`. Do not edit the prompt/schema; the weights are trained against them.

# FlowX Semantic Mapper (4B): the regulation-to-ontology tagger

**Reads one chunk of regulatory or legal text and emits a structured ontology JSON: where the clause sits in its source, what it is about, and how it maps to policy and escalation.** Languages: EN, FR, DE, RO. Domains: banking, insurance, logistics, labor.

Given a single clause (a subsection of a state insurance code, an EU regulation article, a labor-code paragraph, an ADR packing rule), the Mapper returns three facets: a **structural** locator (source id, document type, and the full hierarchy path), a **semantic** payload (free-text `domain_tags`, controlled-vocabulary `concepts`, and an actor/action/object/constraint entity triple), and a **governance** payload (`PDP.<domain>.<rule>` policy references plus a single `if ... THEN escalate` guard clause).

The product insight that shapes everything: **an ontology field is only useful if it is consistent enough to join on.** The first version emitted `concepts` as open free text and produced 1062 unique ids, 88% of them singletons: unlearnable for the model and unmeasurable for us (concepts F1 sat at 0.24). Collapsing that to a **252-concept controlled taxonomy** (`concept_taxonomy.yaml`) is the central design choice of this release: it made `concepts` both learnable and scoreable (F1 0.24 → 0.54), and gave downstream policy code a stable key to join on. `domain_tags` stay free-text on purpose (for recall and human browsing) and are honestly noisier as a result.

The Mapper is the first stage of a pipeline, not a standalone product: **Mapper tags a chunk → a policy layer → the [`flowxai/sentinel-gate`](https://huggingface.co/flowxai/sentinel-gate) escalation model decides DECIDE vs ESCALATE.** It is part of the FlowX on-device model family alongside [`flowxai/sentinel-gate`](https://huggingface.co/flowxai/sentinel-gate), [`flowxai/caveat`](https://huggingface.co/flowxai/caveat), and the consumer scam detectors [`flowxai/scam-guard-qwen06b`](https://huggingface.co/flowxai/scam-guard-qwen06b) / [`flowxai/scam-guard-qwen17b`](https://huggingface.co/flowxai/scam-guard-qwen17b).

LoRA-fine-tuned from Apache-2.0 **`Qwen/Qwen3-4B`**. Formats: fp16 safetensors (transformers / CUDA / vLLM), **MLX-quantized** int4 + int8 (Apple Silicon), and **GGUF** `Q8_0` + `Q4_K_M` (llama.cpp / CPU / Ollama).

---

## How do I use it?

Two copy-pasteable ways to turn a regulatory chunk into ontology JSON, plus a note.

Real example input (a real clause from the California Insurance Code, section 790.03(h)(2)):

```
Failing to acknowledge and act reasonably promptly upon communications with respect
to claims arising under insurance policies.
```

The user turn wraps it in the fixed template (see the inference contract):

```
Extract ontology from this chunk:

CHUNK:
Failing to acknowledge and act reasonably promptly upon communications with respect to claims arising under insurance policies.
```

### (a) transformers / CUDA (fp16 safetensors)

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

SYSTEM_PROMPT = (
    "You are a legal and regulatory ontology extractor.\n"
    "Extract structured tags from document chunks. Output ONLY valid JSON."
)

tok = AutoTokenizer.from_pretrained("flowxai/semantic-mapper")
model = AutoModelForCausalLM.from_pretrained("flowxai/semantic-mapper", device_map="cuda")

chunk = ("Failing to acknowledge and act reasonably promptly upon communications "
         "with respect to claims arising under insurance policies.")
user = f"Extract ontology from this chunk:\n\nCHUNK:\n{chunk}"

prompt = tok.apply_chat_template(
    [{"role": "system", "content": SYSTEM_PROMPT},
     {"role": "user", "content": user}],
    add_generation_prompt=True, enable_thinking=False, tokenize=False,
)
ids = tok(prompt, return_tensors="pt").to(model.device)
out = model.generate(**ids, max_new_tokens=1024, do_sample=False, temperature=0.0)
raw = tok.decode(out[0][ids.input_ids.shape[1]:], skip_special_tokens=True)
```

### (b) MLX (Apple Silicon)

Off the MLX-quantized weights (int4 / int8):

```bash
mlx_lm.generate --model flowxai/semantic-mapper-mlx-int4 --temp 0 --max-tokens 1024 \
  --system-prompt "$(printf 'You are a legal and regulatory ontology extractor.\nExtract structured tags from document chunks. Output ONLY valid JSON.')" \
  --prompt "$(printf 'Extract ontology from this chunk:\n\nCHUNK:\nFailing to acknowledge and act reasonably promptly upon communications with respect to claims arising under insurance policies.')"
```

```python
from mlx_lm import load, generate

SYSTEM_PROMPT = (
    "You are a legal and regulatory ontology extractor.\n"
    "Extract structured tags from document chunks. Output ONLY valid JSON."
)

model, tok = load("flowxai/semantic-mapper-mlx-int4")
chunk = ("Failing to acknowledge and act reasonably promptly upon communications "
         "with respect to claims arising under insurance policies.")
user = f"Extract ontology from this chunk:\n\nCHUNK:\n{chunk}"
prompt = tok.apply_chat_template(
    [{"role": "system", "content": SYSTEM_PROMPT},
     {"role": "user", "content": user}],
    add_generation_prompt=True, enable_thinking=False,
)
raw = generate(model, tok, prompt=prompt, max_tokens=1024, verbose=False)
```

Either backend returns the **same JSON** for this chunk (this is the real held-out target for the example above):

```json
{
  "structural": {
    "source_id": "US_CA_INS_790_03_h_2",
    "hierarchy": [
      "state_code", "california_insurance_code",
      "section", "790.03",
      "subdivision", "h",
      "paragraph", "2"
    ],
    "document_type": "state_insurance_code"
  },
  "semantic": {
    "domain_tags": ["insurance_regulation", "claims", "unfair_claims_practices", "settlement"],
    "concepts": ["claim_acknowledgement", "prompt_communication", "settlement_timeline"],
    "entities": {
      "actor": "insurer",
      "action": "acknowledge and act reasonably promptly upon communications",
      "object": "claim_communication",
      "constraint": { "condition": "reasonably_prompt" }
    }
  },
  "governance": {
    "policy_references": ["PDP.insurance.claims_settlement", "PDP.insurance.unfair_practices"],
    "escalation_trigger": "if !claim_communication_acknowledged_promptly THEN escalate"
  }
}
```

### (c) A short note on decoding

`enable_thinking=False` is not optional. Qwen3-4B is a thinking model, but this
adapter was trained on pure JSON with no reasoning block, so the default template
yields empty output. Decode greedily (temperature 0), one chunk per call, and cap
at ~1024 new tokens. GGUF (`Q8_0` / `Q4_K_M`) runs the same contract on
llama.cpp / Ollama. Full wiring is in [`inference_contract/INFERENCE.md`](./inference_contract/INFERENCE.md).

---

## How it works

```
regulatory
text chunk  ---> FlowX Semantic Mapper 4B ---> structural  (source_id, hierarchy, document_type)
                                          |
                                          +--> semantic    (domain_tags, concepts, entities)
                                          |
                                          +--> governance  (policy_references, escalation_trigger)
```

Pipeline line:

```
chunk --> Semantic Mapper (this model) --> policy layer --> Sentinel Gate --> DECIDE | ESCALATE
```

Under the hood the Mapper is: `tokenizer → Qwen3-4B (LoRA fine-tuned) → greedy JSON
decode (thinking disabled) → parse against schema_mapper_v1.json`. The
`semantic.concepts` field targets the 252-concept controlled taxonomy
(`concept_taxonomy.yaml`), so downstream code can filter out-of-vocabulary ids and
join the rest straight into the policy layer.

---

## Output schema

A single JSON object with three facets (full schema:
[`schema_mapper_v1.json`](./inference_contract/schema_mapper_v1.json)):

**`structural`**: where the clause lives.
- `source_id`: stable id for the chunk, usually an uppercased normalization of the citation path (e.g. `US_CA_INS_790_03_h_2`).
- `hierarchy`: ordered flat array of alternating `[level, value]` pairs from the outermost container down to the leaf.
- `document_type`: snake_case document class (e.g. `state_insurance_code`, `eu_regulation`, `labor_code`, `adr_agreement`).

**`semantic`**: what the clause is about.
- `domain_tags`: free snake_case topic tags (**open vocabulary**; noisier by design, tuned for recall/browsing).
- `concepts`: concept ids from the **252-concept controlled taxonomy** (`concept_taxonomy.yaml`). Treat any id not in the taxonomy as out-of-vocabulary.
- `entities`: `{actor, action, object, constraint}`: who the obligation falls on, what must/may be done, on what, and a free key/value `constraint` map of qualifying conditions (e.g. `{"condition":"reasonably_prompt"}`).

**`governance`**: how it maps to policy and escalation.
- `policy_references`: ids in the form `PDP.<domain>.<rule>` (e.g. `PDP.insurance.claims_settlement`).
- `escalation_trigger`: a single guard clause `if <condition> THEN escalate`, consumed by the Sentinel Gate.

The controlled taxonomy holds **252 canonical concepts** across 6 categories
(money, rights_waived, time_renewal, lease, insurance, data), each with an `id`, a
`definition`, and a `primary_domain`. It ships as `concept_taxonomy.yaml` at the
repo root.

---

## Evaluation

Held-out set: **n = 112**, **document-disjoint** from training, multilingual
(EN / FR / DE / RO). Read the honest numbers first, then the caveat.

| Metric | Value |
| --- | --- |
| JSON validity | **1.00** |
| all-3-facets present | **1.00** |
| `domain_tags` F1 (free-text) | 0.55 |
| `concepts` F1 (controlled 252-concept vocab) | **0.54** |
| `concepts` F1 (fuzzy / semantic match) | 0.58 |
| `entities` field-accuracy | 0.53 |

**The headline improvement, quantified.** Adopting the controlled 252-concept
vocabulary plus a real-regulation data expansion moved `concepts` F1 from **0.24**
(open free-text vocab) to **0.54**, and `entities` from **unmeasured** (the facet
was empty in the first corpus) to **0.53**. The format facets are saturated: JSON
validity and all-three-facets-present are both 1.00, so the model reliably produces
a parseable, structurally-complete object every time.

**Honest reading.**
- `concepts` is **partial** at ~0.54: it surfaces many of the right controlled ids, not all of them. Use it as a strong signal, not a complete tagging.
- `domain_tags` are **free-text** and therefore less consistent than the controlled `concepts` (this is the intended trade: recall/browsability over join-stability).
- `entities` field-accuracy of 0.53 reflects a genuinely hard four-slot extraction (actor/action/object/constraint), now measurable where before it was not.
- **EN is strongest.** FR, DE, RO are supported and evaluated, but a bit weaker.

> **Home-field caveat (read before citing these numbers).** The held-out set is
> **document-disjoint** (no shared source document leaks between train and test),
> which is the right discipline. But the annotations across train and test share a
> **lineage**: the same controlled taxonomy and the same frontier-model-assisted
> annotation style. The scores above measure how well the model reproduces *that
> annotation convention* on unseen documents, which is exactly the deployment task,
> but they are **not** a claim of agreement with an independent human legal
> annotator. Treat 0.54 concepts F1 as "reproduces the FlowX taxonomy convention on
> held-out documents at ~0.54", not "a legal-grade ontology at 0.54".

---

## Formats

| Format | Path | Runtime | Notes |
| --- | --- | --- | --- |
| fp16 safetensors | repo root | transformers / CUDA / vLLM | full precision |
| MLX int4 | `mlx-int4/` | Apple Silicon (MLX) | smallest Apple footprint |
| MLX int8 | `mlx-int8/` | Apple Silicon (MLX) | higher-fidelity Apple path |
| GGUF `Q8_0` | `gguf/` | llama.cpp / CPU / Ollama | recommended GGUF quant |
| GGUF `Q4_K_M` | `gguf/` | llama.cpp / CPU / Ollama | smallest GGUF |

All formats run the same frozen inference contract (system prompt, user-turn
template, `enable_thinking=False`, greedy decode).

---

## Intended use & limitations

**Intended use.** A **first-stage extractor** in a regulatory-compliance pipeline:
it turns a clause of legislation into a structured ontology record that a policy
layer and the [`flowxai/sentinel-gate`](https://huggingface.co/flowxai/sentinel-gate)
escalation model can act on. It is meant to run over a knowledge base of regulatory
chunks and produce consistent, joinable tags, with a human reviewing anything the
Sentinel routes for escalation.

**Out of scope & limitations.**
- **Not legal advice.** The Mapper labels the structure and topic of a text; it does not interpret the law, give a legal opinion, or determine compliance. A human with legal responsibility owns any decision.
- **Extraction is partial.** `concepts` F1 ~0.54 and `entities` accuracy ~0.53: expect misses and the occasional wrong slot. Do not treat the output as an exhaustive or authoritative tagging.
- **Controlled vocab, not free-form.** `semantic.concepts` targets the 252-concept taxonomy. Filter out-of-vocabulary ids before joining. `domain_tags` are free-text and inherently noisier.
- **Language skew.** EN is strongest; FR / DE / RO are supported but weaker.
- **One chunk at a time.** Trained on single-chunk turns; batching multiple clauses into one user turn degrades output.
- **Domain coverage.** Banking, insurance, logistics, labor. Text outside these domains is out of distribution.
- **Annotation-lineage caveat** (see Evaluation): scores measure reproduction of the FlowX annotation convention, not agreement with an independent legal annotator.

---

## Training data

- **763 records total**, split **651 train / 112 held-out**, **document-disjoint** (no source document appears in both splits).
- **Real, verbatim regulatory / legislative text** from official public sources: US eCFR & state codes, EU EUR-Lex, France Légifrance, Germany Gesetze im Internet, Romania legislatie.just.ro, and UNECE/ADR. Every record carries a source URL. Official legislation is reproduced with source acknowledgement.
- Annotated to the **controlled 252-concept taxonomy** with frontier-model assistance, then validated: concepts checked in-vocabulary, entities checked populated, source URL required per record.
- Coverage spans four domains (banking / insurance / logistics / labor) and four languages (EN / FR / DE / RO).

The controlled taxonomy (`concept_taxonomy.yaml`) is the pivot of this dataset:
open free-text concepts (1062 unique, 88% singletons) were collapsed to 252
canonical ids, which is what made the `concepts` facet learnable and measurable.

---

## Fine-tuning

**LoRA** on **`Qwen/Qwen3-4B`** with **MLX-LM on Apple Silicon**.

| Hyperparameter | Value |
| --- | --- |
| method | LoRA |
| rank | 32 |
| scale (alpha) | 16 |
| dropout | 0.05 |
| layers | `num_layers -1` (all) |
| epochs | ~3 |
| LR schedule | cosine 1e-4 → 1e-5 |
| max_seq_length | 2048 |
| seed | 42 |
| thinking | disabled |

The assistant turn in training is the exact ontology JSON the model must emit (no
reasoning block), which is why inference must set `enable_thinking=False`.

---

## Not legal advice

This model extracts structure and topic tags from legal/regulatory text. It does
not provide legal advice, does not interpret the law, and does not determine
compliance. Its output is an aid to a compliance pipeline under human ownership,
not a substitute for a qualified professional.

## Links

- **Sibling (escalation gate):** [`flowxai/sentinel-gate`](https://huggingface.co/flowxai/sentinel-gate): consumes a case (with the Mapper's governance facet) and decides DECIDE vs ESCALATE.
- **FlowX on-device family:** [`flowxai/caveat`](https://huggingface.co/flowxai/caveat), [`flowxai/scam-guard-qwen06b`](https://huggingface.co/flowxai/scam-guard-qwen06b), [`flowxai/scam-guard-qwen17b`](https://huggingface.co/flowxai/scam-guard-qwen17b).

## License

Apache-2.0 (weights and code). Base model `Qwen/Qwen3-4B` is Apache-2.0. Copyright
2026 FlowX.AI; see the `NOTICE` file. Author: Bogdan Răduță, Head of Research,
FlowX.AI.