Blame for README.md

---
license: mit
library_name: peft
base_model:
  - Qwen/Qwen3.5-0.8B
  - Qwen/Qwen3.5-2B
  - Qwen/Qwen3.5-9B
tags:
  - networking
  - linux
  - world-model
  - lora
---

# NetOracle: LoRA adapters

LoRA adapters for **NetOracle**, a world model for the Linux kernel network
stack, from the HotNets '26 paper *Toward a World Model for the Linux Kernel
Network Stack* (Luyao Bai and Xiaoguang Wang, University of Illinois Chicago).

Given one measurement of the configuration a host is running and a change to
one knob (congestion control, queueing discipline, or socket buffer preset),
the model predicts whether a performance metric goes up, goes down, or stays
the same, and by roughly how much. It does this without running the new
configuration.

Code, testbed, corpora, and the StackBench benchmark:
https://github.com/sysec-uic/NetOracle

## Files

| Folder | Base model | Seeds | Size each |
|---|---|---|---|
| `netoracle-0.8b/seed{41,42,43}` | `Qwen/Qwen3.5-0.8B` | 3 | 68 MB |
| `netoracle-2b/seed{41,42,43}` | `Qwen/Qwen3.5-2B` | 3 | 103 MB |
| `netoracle-9b/seed41` | `Qwen/Qwen3.5-9B` | 1 | 242 MB |

The 0.8B adapters are the model the paper calls NetOracle. The 2B and 9B
adapters are the scale study in Table 1 of the paper. Each folder holds a
PEFT adapter (`adapter_config.json`, `adapter_model.safetensors`) and the
tokenizer files used in training.

## Training

- LoRA rank 32, alpha 64, on all attention and MLP projections
  (12.8M trainable parameters for the 0.8B model).
- Data: `dataset/ft-all` in the GitHub repository, 726 leakage-filtered
  measured cells from the testbed, about 3,800 examples of two kinds:
  quantitative (predict one metric of one cell) and counterfactual (two
  cells that differ in exactly one knob, one given as the measured anchor).
- Targets are strict JSON: `{"direction": "increase|decrease|same", "ratio": <float>}`
  for counterfactual questions. A change within plus or minus 10% counts as
  `same`.
- About 20 minutes per 0.8B run on one consumer GPU
  (`scripts/train_lora.py --data dataset/ft-all`).

## Results

On the 218 StackBench tasks whose targets are absent from training, averaged
over seeds (Table 1 of the paper):

| Model | Direction, all | Direction, off-grid | Median APE | Within 2x, off-grid |
|---|---|---|---|---|
| NetOracle 0.8B | 0.78 | 0.84 | 0.10 | 0.88 |
| NetOracle 2B | 0.81 | 0.79 | 0.03 | 0.91 |
| NetOracle 9B | 0.82 | 0.68 | 0.03 | 0.86 |
| kNN / GBT / random forest, same data | 0.70 / 0.72 / 0.78 | 0.32 / 0.63 / 0.47 | | |

Off-grid means conditions far outside the training grid (160 ms RTT or
400 Mbit/s). Scores are computed with `scripts/eval_stats.py` in the GitHub
repository.

## Usage

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
from huggingface_hub import snapshot_download

repo = snapshot_download("Haku247/NetOracle", allow_patterns=["netoracle-0.8b/seed41/*"])
adapter = f"{repo}/netoracle-0.8b/seed41"

tok = AutoTokenizer.from_pretrained(adapter)
base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3.5-0.8B", torch_dtype=torch.bfloat16, device_map="auto")
model = PeftModel.from_pretrained(base, adapter).eval()

prompt = "..."  # a StackBench-style prompt: testbed description, the measured anchor, the knob change
msgs = [{"role": "user", "content": prompt}]
ids = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt").to(model.device)
out = model.generate(ids, max_new_tokens=96, do_sample=False)
print(tok.decode(out[0, ids.shape[1]:], skip_special_tokens=True))
```

The prompts the paper evaluates on are produced by `scripts/ft_eval_io.py export`
in the GitHub repository, and `scripts/batch_generate.py` runs them in batch:

```bash
python3 scripts/batch_generate.py --model Qwen/Qwen3.5-0.8B \
    --adapter <path>/netoracle-0.8b/seed41 \
    --prompts dataset/ft/eval_prompts.jsonl --out gen.jsonl
```

The gated policy in the paper samples 5 answers at temperature 0.8 and changes
a knob only if at least 4 agree on a gain of at least 15%.

## Limitations

- Trained only on an emulated testbed (network namespaces, HTB bottleneck,
  netem delay and loss) on one kernel version.
- On real paths whose bottleneck the host cannot observe (the Pantheon
  archive), the emulation-only model barely beats always predicting no change.
  Training on measurements from other real paths raises direction accuracy to
  0.68; those replay models are not part of this release.
- One short measurement cannot predict tail latency dominated by
  retransmission timeouts.

## License

The adapters are released under the MIT license. Use of the base models is
governed by their own licenses.

## Citation

```bibtex
@inproceedings{netoracle2026,
  author    = {Luyao Bai and Xiaoguang Wang},
  title     = {Toward a World Model for the Linux Kernel Network Stack},
  booktitle = {Proceedings of the 25th ACM Workshop on Hot Topics in Networks (HotNets '26)},
  year      = {2026},
  address   = {Salt Lake City, UT, USA},
  publisher = {ACM},
  doi       = {10.1145/3847290.3859973}
}
```