Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,127 @@
+---
+license: apache-2.0
+library_name: onnx
+pipeline_tag: text-classification
+tags:
+  - guardrails
+  - onnx
+  - multilingual
+  - bias
+language:
+  - az
+  - bg
+  - cs
+  - da
+  - de
+  - el
+  - en
+  - es
+  - et
+  - fi
+  - fr
+  - ga
+  - hr
+  - hu
+  - it
+  - lt
+  - lv
+  - mt
+  - nl
+  - pl
+  - pt
+  - ro
+  - sk
+  - sl
+  - sv
+  - tr
+---
+
+# flowxai/bias
+
+The `bias` detector for [flowx-border](https://github.com/flowx-ai/border), an embeddable library that inspects the text going into and coming out of an LLM and returns a structured decision plus an audit-grade evidence record.
+
+This card is generated from the evaluation and export artifacts of the training run, so every number on it is reproducible from this repository rather than asserted.
+
+## What it is
+
+- **Base model**: FacebookAI/xlm-roberta-base
+- **Head**: multi_label_classification
+- **Labels**: `gender`, `ethnicity`, `religion`, `age`, `disability`
+- **Artifact**: `onnx/model.int8.onnx`, 535 MB, opset 17
+- **Trained at**: 96 tokens
+
+## Operating point
+
+**Threshold 0.57**, calibrated on the validation split against the `macro_f1` objective.
+
+This number is not decoration. Read at the 0.5 default that looked reasonable, several detectors in this family reported F1 0.000 in every language, because their scores separate positives from negatives well below 0.5. One of them went from 0.000 to 0.893 on the threshold alone. Use the value above, or calibrate your own on your own data.
+
+- At the 0.5 default: 0.968
+- At the calibrated 0.57: 0.971
+
+## Per language
+
+Per language rather than an aggregate, because an aggregate across 26 languages hides the tail and the tail is the point.
+
+| Language | Support | P | R | F1 | Note |
+|---|---|---|---|---|---|
+| `cs` Czech | 13 | 1.000 | 1.000 | 1.000 |  |
+| `da` Danish | 9 | 1.000 | 1.000 | 1.000 |  |
+| `de` German | 6 | 1.000 | 1.000 | 1.000 |  |
+| `el` Greek | 8 | 1.000 | 1.000 | 1.000 |  |
+| `en` English | 15 | 1.000 | 1.000 | 1.000 |  |
+| `es` Spanish | 10 | 1.000 | 1.000 | 1.000 |  |
+| `et` Estonian | 10 | 1.000 | 1.000 | 1.000 |  |
+| `fi` Finnish | 7 | 1.000 | 1.000 | 1.000 |  |
+| `fr` French | 10 | 1.000 | 1.000 | 1.000 |  |
+| `hr` Croatian | 13 | 1.000 | 1.000 | 1.000 |  |
+| `hu` Hungarian | 9 | 1.000 | 1.000 | 1.000 |  |
+| `lt` Lithuanian | 11 | 1.000 | 1.000 | 1.000 |  |
+| `nl` Dutch | 10 | 1.000 | 1.000 | 1.000 |  |
+| `pl` Polish | 9 | 1.000 | 1.000 | 1.000 |  |
+| `ro` Romanian | 10 | 1.000 | 1.000 | 1.000 |  |
+| `sl` Slovenian | 11 | 1.000 | 1.000 | 1.000 |  |
+| `tr` Turkish | 12 | 1.000 | 1.000 | 1.000 |  |
+| `it` Italian | 16 | 1.000 | 0.938 | 0.968 |  |
+| `sv` Swedish | 13 | 1.000 | 0.923 | 0.960 |  |
+| `pt` Portuguese | 11 | 0.917 | 1.000 | 0.957 |  |
+| `az` Azerbaijani | 9 | 0.900 | 1.000 | 0.947 |  |
+| `ga` Irish | 9 | 1.000 | 0.889 | 0.941 |  |
+| `sk` Slovak | 8 | 0.889 | 1.000 | 0.941 |  |
+| `bg` Bulgarian | 8 | 1.000 | 0.875 | 0.933 |  |
+| `lv` Latvian | 8 | 1.000 | 0.875 | 0.933 |  |
+| `mt` Maltese | 9 | 0.875 | 0.778 | 0.824 | not in base model pretraining |
+
+### Weakest languages
+
+Published rather than dropped. A coverage table with the bad rows removed is not a coverage table.
+
+- `mt` Maltese: F1 0.824 (absent from XLM-R pretraining, which is a base-model limit)
+- `bg` Bulgarian: F1 0.933
+- `lv` Latvian: F1 0.933
+
+## Quantisation
+
+The published artifact is INT8, and **only the embedding table is quantised**.
+
+Quantising everything is what most examples do and it does not work for this base model. Measured on 300 real test texts at the detector's own threshold:
+
+| Recipe | Size | Mean logit drift | Decisions changed |
+|---|---|---|---|
+| all ops (the usual default) | 279 MB | 0.68 | 51 / 300 |
+| MatMul only | 856 MB | 0.64 | 48 / 300 |
+| **Gather only, what ships here** | **535 MB** | **0.0036** | **0 / 300** |
+
+The embedding table carries the whole size win at no accuracy cost, while quantising the encoder MatMuls changes one decision in six to save 256 MB. XLM-RoBERTa has large activation outliers and per-tensor dynamic quantisation of activations is exactly what they defeat.
+
+For this artifact specifically: **0 of 300 decisions differ** from the fp32 checkpoint, mean logit drift 0.0050, read as `sigmoid_at_threshold`. A quantised model that answers differently is a different detector, so this is measured rather than assumed.
+
+## Limitations
+
+- **Synthetic training data.** Generated natively per language, never translated from English, so the sentence structure is the target language's own. It is still synthetic, and a production distribution will differ.
+- **Maltese is absent from XLM-RoBERTa's pretraining set.** That is a fact about the base model, and it is not an explanation for a weak score. This card said "no amount of data fixes that" until 2026-08-14, which this project's own measurement disproves: the `nsfw` detector scored 0.000 in Maltese, was blamed on the base model, and went to 1.000 with perfect precision and recall when its corpus went from 2 positives per language to 10. Nothing about the model changed. So where a language scores badly here, read the support column first.
+- **This is not a compliance product.** It produces evidence about controls that were applied. It does not make anyone compliant with anything, and the obligations under the EU AI Act sit with the provider or deployer of a system, not with a model or a library.
+
+## Licence
+
+Apache-2.0, declared in the metadata above as well as here, so that a tool reading the repository can attest it rather than a human having to read prose.