rlx-pkg 0.2.17

RLX package format (.rlxp) — flat hybrid mmap packs, optional graph, ZIP/dir
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# rlx-pkg

RLX ship format (`.rlxp`): **flat mmap by default** with **hybrid hot / warm /
cold** storage, optional ZIP / directory layouts, and an **optional executable
MIR graph** (ONNX-style graph + weights, or weight-only).

Spec: [`docs/rlxp.md`](../../../docs/rlxp.md).

| Container | Use |
|-----------|-----|
| **Flat** (`.rlxp`) | Deploy / serve — one `RLXPFLAT` mmap, tiny TOC |
| **ZIP** (`.zip`) | Inspect with `unzip -l` |
| **Dir** | Edit as a tree during development |

| Tier | Codec | API |
|------|-------|-----|
| Hot | raw | `tensor_mmap` |
| Warm | `zstd_blocks` | `tensor_bytes` / `tensor_warm_block` |
| Cold | zstd | `sidecar` |

Warm compression is for rarely touched host blobs — **not** a substitute for
GGUF-class quants (`Q4_K`, …). Keep active LLM weights hot + packed.

## Usage

```rust,ignore
use rlx_pkg::{
    Package, PackedWeight, StorageTier, WriteOptions, write_package,
};

let mut opts = WriteOptions {
    name: "model".into(),
    // include_graph: true by default — set false for weight-only packs
    ..WriteOptions::default()
};
opts.sidecars.push(("tokenizer".into(), "application/json".into(), tok));

write_package(
    "model.rlxp",
    &graph,
    &[
        PackedWeight::hot("w", shape, "f32", "row_major", bytes),
        PackedWeight {
            name: "expert".into(),
            tier: StorageTier::Warm,
            ..PackedWeight::hot("expert", eshape, "f32", "row_major", ebytes)
        },
    ],
    &opts,
)?;

let pack = Package::open("model.rlxp")?;
pack.advise_hot_willneed();                 // optional page prefetch
let _ = pack.tensor_mmap("w")?;             // zero-copy hot
let _ = pack.tensor_bytes("expert")?;       // inflate warm (parallel for large)
let g = pack.graph()?;                      // materializes hot Constants by default
```

Runtime compile:

```rust,ignore
use rlx_runtime::{Device, Session};
use rlx_runtime::pkg::compile_rlxp;

let session = Session::new(Device::Cpu);
let compiled = compile_rlxp(&session, "model.rlxp")?;
```

## CLI

```bash
cargo run -p rlx-pkg -- inspect model.rlxp
cargo run -p rlx-pkg -- verify model.rlxp
cargo run -p rlx-pkg -- import-gguf model.gguf -o model.rlxp --no-graph
cargo run -p rlx-pkg -- convert in.zip -o out.rlxp --container flat
cargo run -p rlx-pkg -- tier model.rlxp -o out.rlxp --warm expert --hot tok_embd
```

ONNX → RLXP (optional executable graph) is on **`rlx-bake`**:

```bash
cargo run -p rlx-bake --features onnx -- import-onnx model.onnx -o model.rlxp
cargo run -p rlx-bake --features onnx -- import-onnx model.onnx -o w.rlxp --no-graph
```

## Features

| Feature | Enables |
|---------|---------|
| *(default)* | Flat / ZIP / dir, hybrid tiers, GGUF import, verify, CLI |
| `encrypt` | `seal_bytes` / `unseal_bytes` (`RLXSEAL1`) for cold blobs |
| `remote` | HTTP(S) Range `RemoteFlat` (TOC + on-demand tensors) |

## Benches / examples

```bash
just throttle
RLX_ALLOW_THROTTLE=1 cargo run -p rlx-pkg --example bench_hybrid --release
RLX_ALLOW_THROTTLE=1 cargo run -p rlx-pkg --example bench_compare --release
RLX_ALLOW_THROTTLE=1 cargo bench -p rlx-pkg --bench hybrid_load --bench q4k_compare
# MNIST end-to-end (bake + RLXP load/compile/run):
RLX_ALLOW_THROTTLE=1 cargo run -p rlx-bake --example mnist_bench_rlxp --features runtime --release
```

## Python (`pyrlx`)

```python
import pyrlx
pyrlx.load_rlxp("model.rlxp")
pyrlx.convert_gguf_to_rlxp("m.gguf", "m.rlxp", include_graph=False)
```

## License

MIT OR Apache-2.0.