Upload README.md

README.md

@@ -0,0 +1,155 @@
+# 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