# TMF921 Intent-to-Configuration Translation — Training Pipeline

> **The first open-source fine-tuning pipeline for translating natural language network intents into spec-compliant 5G/6G configurations across 6 telecom standards.**

## What This Does

Fine-tunes an LLM (default: Qwen3-8B) via **4-bit QLoRA** on the [TMF921-intent-to-config-augmented](https://huggingface.co/datasets/nraptisss/TMF921-intent-to-config-augmented) dataset (41.8K samples) to translate natural language network intents into structured JSON configurations for:

| Target Standard | Description |
|---|---|
| **TMF921** | TM Forum Intent Management API v4 |
| **3GPP TS 28.312** | Intent-Driven Management (Rel-18) |
| **CAMARA** | GSMA Open Gateway NetworkSliceBooking |
| **ETSI ZSM** | Zero-touch Service Management intents |
| **O-RAN A1 Policy** | Non-RT RIC A1 policy objects |
| **3GPP O1 NRM** | O1 interface NR Network Resource Model |

Plus **TMF921 lifecycle operations** (activate, modify, suspend, resume, terminate, scale, monitor, report) and **adversarial rejection** (ambiguous, out-of-scope, contradictory intents).

## Quick Start

### 1. Clone & Install

```bash
git clone https://huggingface.co/nraptisss/intent-translation-training
cd intent-translation-training
pip install -r requirements.txt
```

### 2. Train (defaults — RTX 6000 Ada 50GB)

```bash
python train.py
```

This will:
- Load Qwen3-8B in 4-bit NF4 quantization
- Apply QLoRA (r=32, alpha=64) to all linear layers
- Train for 3 epochs with cosine LR schedule
- Save checkpoints and best model to `./output/`

### 3. Evaluate

```bash
python evaluate.py --adapter_path ./output --num_samples 200
```

### 4. One-command pipeline

```bash
chmod +x run.sh
./run.sh
```

## Training Configuration

| Parameter | Default | Notes |
|---|---|---|
| Base model | `Qwen/Qwen3-8B` | Any HF causal LM works |
| Quantization | 4-bit NF4 + double quant | ~4.5 GB VRAM for weights |
| LoRA rank | 32 | target_modules="all-linear" |
| LoRA alpha | 64 | 2× rank |
| Batch size | 4 × 8 grad_accum = 32 effective | |
| Learning rate | 1e-4 | 10× base for LoRA |
| Epochs | 3 | ~3,700 steps total |
| Max length | 4096 tokens | Covers 99%+ of samples |
| Loss | assistant_only_loss=True | Train only on config outputs |
| Precision | bf16 | |
| Flash attention | Yes (flash_attention_2) | |
| Gradient checkpointing | Yes | Saves ~40% VRAM |

### VRAM Estimate (RTX 6000 Ada 50GB)

| Component | VRAM |
|---|---|
| Model weights (4-bit) | ~4.5 GB |
| LoRA adapters | ~0.5 GB |
| Activations + gradients (checkpointed) | ~12 GB |
| Optimizer states (AdamW, LoRA params only) | ~1 GB |
| KV cache / batch | ~8 GB |
| **Total estimated** | **~26 GB** |

Leaves ~24 GB headroom. You can increase batch_size to 8 if desired.

## Customization

### Different base model
```bash
python train.py --base_model Qwen/Qwen2.5-7B-Instruct
python train.py --base_model meta-llama/Llama-3.1-8B-Instruct
python train.py --base_model microsoft/phi-4
```

### Push to Hugging Face Hub
```bash
export HF_TOKEN="hf_..."
python train.py --push_to_hub --hub_model_id your-username/model-name
```

### Adjust hyperparameters
```bash
python train.py --lr 2e-4 --epochs 5 --lora_r 64 --lora_alpha 128 --batch_size 2 --grad_accum 16
```

### No flash attention (older GPUs)
```bash
python train.py --no_flash_attn
```

## Evaluation Metrics

The evaluation script measures:

| Metric | Description |
|---|---|
| **JSON Validity Rate** | % of outputs that are valid JSON |
| **Structure Correctness** | % with correct root keys per standard |
| **KPI Field Accuracy** | % containing correct latency, throughput, reliability, UE values |
| **All KPIs Correct** | % where ALL 5 KPI fields match |
| **Adversarial Accuracy** | % of bad intents correctly rejected |

Results are broken down per target layer (TMF921, 3GPP, CAMARA, etc.).

## File Structure

```
├── train.py           # QLoRA fine-tuning script
├── evaluate.py        # Evaluation with per-layer metrics
├── run.sh             # One-command train+eval pipeline
├── requirements.txt   # Python dependencies
└── README.md          # This file
```

## Dataset

[nraptisss/TMF921-intent-to-config-augmented](https://huggingface.co/datasets/nraptisss/TMF921-intent-to-config-augmented) — 41,815 samples:

- **39,153** standard intent→config pairs across 6 target layers
- **1,552** lifecycle operation samples (8 TMF921 operations)
- **141** adversarial samples (ambiguous, out-of-scope, contradictory)
- **18 sectors**, **147 use cases**, **55 regions**
- **6 slice types**: eMBB, URLLC, mMTC, V2X, MPS, HMTC

## References

- [ORION: Intent-Aware Orchestration in Open RAN](https://arxiv.org/abs/2603.03667)
- [TelecomGPT](https://arxiv.org/abs/2407.09424)
- [ORANSight-2.0](https://arxiv.org/abs/2503.05200)
- [NEFMind](https://arxiv.org/abs/2508.09240)
- [TMF921 Intent Management API v5.0](https://www.tmforum.org/resources/specification/tmf921-intent-management-api-rest-specification-r21-0-0/)
- [3GPP TS 28.312 Rel-18](https://www.3gpp.org/dynareport/28312.htm)

## License

Apache 2.0