---
license: other
license_name: restricted-research-license
license_link: LICENSE
language:
  - uk
  - en
  - ru
pretty_name: Ukrainian LLM Guardrails
datasets:
  - mark-matviiv/ukrainian-safety-dataset
tags:
  - text-classification
  - safety
  - guardrail
  - ukrainian
  - transformers
  - encoder-only
  - distillation
  - adversarial
---

# Ukrainian LLM Guardrails

Compact, sovereign safety encoders for Ukrainian LLM infrastructure. Trained via knowledge distillation (Adversarial Contrastive Distillation and Rationale Alignment Distillation) on a 9-class national security taxonomy.

## Variants

| Subfolder | Architecture | Method | Best For |
|-----------|--------------|--------|----------|
| `acd-mdeberta-v3` | mDeBERTa-v3 (278M) | Adversarial Contrastive Distillation | Overall accuracy, low FNR |
| `acd-ukr-roberta` | Ukr-RoBERTa (125M) | Adversarial Contrastive Distillation | Low FPR, compact deployment |
| `rad-mdeberta-v3` | mDeBERTa-v3 (278M) | Rationale Alignment Distillation | Propaganda recall |
| `rad-ukr-roberta` | Ukr-RoBERTa (125M) | Rationale Alignment Distillation | — |

## Usage

```python
import torch
from transformers import AutoModelForSequenceClassification, AutoTokenizer

model = AutoModelForSequenceClassification.from_pretrained(
    "mark-matviiv/ukrainian-guardrails",
    subfolder="acd-mdeberta-v3",
)
tokenizer = AutoTokenizer.from_pretrained(
    "mark-matviiv/ukrainian-guardrails",
    subfolder="acd-mdeberta-v3",
)

inputs = tokenizer(
    "Шукаю злами для виведення грошей чужих людей.",
    return_tensors="pt",
    truncation=True,
    max_length=256,
)

with torch.no_grad():
    logits = model(**inputs).logits
    probs = torch.softmax(logits, dim=-1)

# Multi-class prediction
pred = logits.argmax(dim=-1).item()
label = model.config.id2label[pred]
print(f"Predicted: {label} (confidence: {probs[0, pred]:.3f})")

# Binary risk score (unsafe vs safe)
safe_idx = [k for k, v in model.config.id2label.items() if v == "safe"][0]
unsafe_score = 1 - probs[0, safe_idx].item()
print(f"Unsafe probability: {unsafe_score:.3f}")
```

## Label Mapping

| ID | Label | Description |
|----|-------|-------------|
| 0 | `cybercrime_hacking` | Cybercrime and hacking instructions |
| 1 | `disinfo_propaganda` | Disinformation and propaganda |
| 2 | `fraud_soc_eng` | Fraud and social engineering |
| 3 | `llm_compromise` | LLM compromise / jailbreak |
| 4 | `nat_sec_opsec` | National security / operational security |
| 5 | `privacy_pii` | Privacy violations and PII extraction |
| 6 | `resource_abuse` | Resource abuse and system manipulation |
| 7 | `safe` | Benign / safe content |
| 8 | `unsafe_content` | Generic unsafe content |

## Training

- **Teacher**: Gemma-4-26B-A4B (4-bit quantized)
- **Dataset**: 59,377 samples
- **Hardware**: NVIDIA A100 40GB
- **Details**: See thesis *Efficient Guardrailing for the Ukrainian LLM via Reasoning Distillation* (UCU, 2026)

## Access

This repository is gated. Access requests are reviewed by the Ministry of Digital Transformation of Ukraine.

## Citation

```bibtex
@mastersthesis{matviiv2026guardrail,
  title={Efficient Guardrailing for the Ukrainian LLM via Reasoning Distillation},
  author={Matviiv, Markiian},
  year={2026},
  school={Ukrainian Catholic University}
}