README.md

# Telco_Intelligence v2

A 7B parameter language model fine-tuned for telecom network operations, covering RAN anomaly detection, 5G Core root cause analysis, multi-vendor KPI normalisation, and CLI command generation across Ericsson, Nokia, and Huawei.

---

## Model Details

| Property | Value |
|---|---|
| **Base model** | Qwen2.5-7B |
| **Fine-tuning method** | Supervised Fine-Tuning (SFT) with Chain-of-Thought |
| **Model ID** | `mindfossil/telecom-intelligence-model-v2-merged` |
| **Serving** | vLLM OpenAI-compatible endpoint |
| **License** | Apache 2.0 |

---

## Capabilities

- **PM KPI derivation** — computes KPIs from raw PM counter values with explicit step-by-step arithmetic: RRC Success Rate, ERAB SR, Handover SR, PRB Utilisation, Throughput, and vendor-equivalent formulas across Ericsson, Nokia, and Huawei naming conventions
- **RAN anomaly detection** — applies derived KPIs against operational thresholds to classify cell health, identify degraded KPIs, and recommend remediation actions
- **5G Core RCA** — analyses SMF/AMF telemetry (ContextDao latency, PM time series) and classifies faults (CPU fault, IP pool exhaustion, insufficient data)
- **Core network probe / DPI analysis** — interprets passive probe data, xDR records, and interface-level flow telemetry to diagnose subscriber experience and network-side faults
- **NWDAF-style analytics** — processes aggregated network data to identify patterns, predict load, and surface anomalies at the network function level
- **Differential diagnosis** — distinguishes RAN-side vs Core-side faults using cross-KPI reasoning
- **Multi-vendor KPI normalisation** — maps vendor-specific counter names to unified KPI formulas and computes comparable values across vendors
- **SON energy saving** — applies policy gate conditions to produce explicit switch-off decisions
- **NL → CLI** — translates natural language operations requests into valid Ericsson MML and AMOS CLI commands

---

## Evaluation

Evaluated using deterministic scoring (numeric formula accuracy ±3%, keyword matching, reasoning chain validation, and hallucination guards) across 20 functional test cases.

| Domain | Score | % |
|---|---|---|
| RAN anomaly detection | 110/136 | 81% |
| 5G Core RCA | 97/128 | 76% |
| SON policy | 27/44 | 61% |
| NL → CLI | 55/82 | 67% |
| Multi-vendor | 68/76 | 89% |
| **Overall** | **357/466** | **77%** |

Separately evaluated on a structured 5GC telemetry RCA benchmark (7 test cases): **12/14 (86%)**, above the 86% deployment confidence threshold.

---

## Quickstart

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "mindfossil/telecom-intelligence-model-v2-merged"

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained(model_name)

system_prompt = (
    "You are a telecom network intelligence assistant specialising in RAN performance "
    "analysis, 5G Core operations, and multi-vendor troubleshooting. When given raw PM "
    "counters or telemetry data, derive KPIs showing your arithmetic step-by-step, "
    "compare against known thresholds, identify anomalies, and recommend actions."
)

prompt = (
    "TASK: Anomaly Detection\n"
    "DATA TYPE: RAN PM counters (4G LTE)\n"
    "VENDOR: Ericsson | Cell: ENB010-CELL01 | Granularity: 15 min\n\n"
    "RAW PM COUNTERS:\n"
    "  pmRrcConnEstabSucc:    921\n"
    "  pmRrcConnEstabAtt:     948\n"
    "  pmErabEstabSuccInit:   902\n"
    "  pmErabEstabAttInit:    921\n"
    "  pmHoExecSuccLteIntraF: 412\n"
    "  pmHoExecAttLteIntraF:  421\n\n"
    "Analyse these counters. Derive the relevant KPIs showing your arithmetic, "
    "then state the cell health verdict."
)

messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user",   "content": prompt},
]

text = tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)
model_inputs = tokenizer([text], return_tensors="pt").to(model.device)

generated_ids = model.generate(**model_inputs, max_new_tokens=1500, temperature=0.1)
generated_ids = [
    output_ids[len(input_ids):]
    for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
]

response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(response)
```

### Serving with vLLM

```bash
vllm serve mindfossil/telecom-intelligence-model-v2-merged \
    --tensor-parallel-size 1 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.85
```

The model runs on a single **NVIDIA L4 (24 GB)** or equivalent GPU.

---

## Input / Output Format

### RAN PM counter analysis

**Input:**
```
TASK: Anomaly Detection
DATA TYPE: RAN PM counters (4G LTE)
VENDOR: Ericsson | Cell: <cell_id> | Granularity: 15 min

RAW PM COUNTERS:
  pmRrcConnEstabSucc:    <value>
  pmRrcConnEstabAtt:     <value>
  ...

Analyse these counters for anomalies. Derive the relevant KPIs showing your
arithmetic, then state the cell health verdict.
```

**Output:**
```
Step 1: Identify Vendor and Counter Naming Convention
...
Step 2: Derive Relevant KPIs

RRC SR = pmRrcConnEstabSucc / pmRrcConnEstabAtt × 100 = 921 / 948 × 100 = 97.2%
...

Verdict: Healthy — all KPIs above threshold.
```

### 5GC telemetry RCA

**Input:**
```
ContextDao Actor Latency (10-second window):
Tag                          | Avg(ms) | Min(ms) | Max(ms) | 95th(ms)
put-NrSessionContext         |  11.40  |   4.20  |  55.00  |  97.00
...
```

**Output:**
```
[ANOMALY DETECTION] — An anomaly is detected in the put-NrSessionContext operation.
[REASONING] — ...
Anomaly_Class: SMF_CPU_FAULT
[ROOT CAUSE] — CPU starvation causing elevated ContextDao write latency.
[REMEDIATION] — Scale SMF resources; investigate CPU spike root cause.
```

---

## Citation

```bibtex
@misc{telecom-intelligence-v2-2026,
  title  = {Telco\_Intelligence v2: A Telecom Operations Fine-Tuned Language Model},
  author = {mindfossil},
  year   = {2026},
  url    = {https://huggingface.co/mindfossil/telecom-intelligence-model-v2-merged}
}
```