pip install loggetta

That installs the stack: Loggetta, the experts4bit-qlora runtime with its training and fast-kernel dependencies, and grouped-nf4-gemm. No backend extra or separate package assembly is required.

Measured speed

The performance work lives in the runtime and kernel layers that Loggetta installs and dispatches into. These are measured positions for that included stack, not speedups produced by the planner itself.

Evidence: same-stack Unsloth result · second-host replication · matched Axolotl/Unsloth result · H100 bnb comparison

loggetta inspect
loggetta plan Qwen/Qwen3-30B-A3B --seq 2048

Loggetta turns a workload, a machine, constraints, and evidence into an ExecutionPlan. It explains the selected configuration, records why alternatives lost, and refuses unsupported or infeasible plans before loading model weights. For supported training plans, Loggetta dispatches into e4b and records the result as an ExecutionReceipt. Serving placement planning is also included; starting the server remains a separate e4b step in this release.

Quick start

After installation, use the loggetta command throughout:

# Inspect the machine
loggetta inspect

# Choose a supported configuration before loading weights
loggetta plan Qwen/Qwen3-30B-A3B --seq 2048

# Constrain the planner deliberately: device budget is in GiB
loggetta plan allenai/OLMoE-1B-7B-0924 --experts device --vram 6

# Save a training plan
loggetta plan allenai/OLMoE-1B-7B-0924 \
  --seq 512 --micro-batch 2 --steps 12 --out plan.json

# Execute the saved plan through the included runtime and write its receipt
loggetta execute plan.json --out receipts/

# Plan again using measured evidence from earlier runs
loggetta plan allenai/OLMoE-1B-7B-0924 \
  --seq 512 --micro-batch 2 --observations receipts/

For a short training run without a separate save/execute step:

loggetta train allenai/OLMoE-1B-7B-0924 \
  --seq 512 --micro-batch 2 --steps 12 --out receipts/

train combines planning and execution; it does not bypass admission checks. The equivalent python -m loggetta ... commands are also supported.

For serving placement:

loggetta plan Qwen/Qwen3-30B-A3B \
  --workload serve --context 4096 --concurrency 1

The serving plan's Why carries the server environment. loggetta execute does not start servers yet. The runtime and kernels are installed, but not every lower-layer capability has a Loggetta execution command.

Three levels of control

How the stack runs

The CLI/API, planner, plan, execution handoff, and receipt belong to Loggetta. Execution calls the included runtime; the runtime calls its kernels. Backend packages remain separate projects without becoming separate setup chores.

flowchart TB
    U["User: pip install loggetta"] --> P
    I["Workload + machine<br/>constraints + evidence"] --> P
    subgraph L["Loggetta: CLI / API and orchestration"]
        P["Planner"] --> X["ExecutionPlan<br/>what should run + why"]
        X --> O["execute(plan)<br/>validate + dispatch"]
        R["ExecutionReceipt<br/>what actually happened"] -. "measured feedback" .-> P
    end
    O --> E["experts4bit-qlora<br/>runs the selected backend setup"]
    E --> G["grouped-nf4-gemm<br/>kernels + residency primitives"]
    E -. "execution results" .-> R

Installed together. Responsibilities kept separate.

Loggetta -> experts4bit-qlora -> grouped-nf4-gemm

No cycles. No duplicated topology. No plugin framework until a second backend actually earns one.

plan() is pure policy: for the same inputs it returns the same serializable ExecutionPlan, without loading weights or touching the device. Hardware probing and model-description gathering happen before that pure planning step. The plan includes the winner, every relevant loser and why it lost, budget sources, evidence labels, warnings, and explicit "not modeled" items.

execute(plan) validates the plan, dispatches through the selected backend executor, and writes the resulting ExecutionReceipt. Before anything loads, it refuses a refused plan, a workload kind its backend only plans, and a plan made for a different GPU (plan --hardware), whose receipt would name the wrong card. The backend receives its own setup; it does not need to import Loggetta's plan types.

Budget    device  10.65 GiB [reported: free now]   host  23.49 GiB [reported: available now]   headroom   0.53 GiB [policy]

Selected  backend experts4bit: experts on device, grouped_nf4 kernel

Estimated memory (each line says how it is known)
  device frozen expert stacks                    3.38 GiB  [derived]  16 stacks in nf4, blocksize 64 (packed + absmax)
  device dense weights (bf16)                    0.89 GiB  [derived]
  device optimizer state (adamw)                 0.23 GiB  [derived]
  device activations                             0.54 GiB  [heuristic]  16 saved layer inputs (T x H bf16) + ...
  device allocator reserve (cached, unallocated blocks)   1.17 GiB  [measured]  receipt ...173932Z: ... = 0.222
  device CUDA context + library workspaces       0.13 GiB  [measured]  receipt ...173932Z
  device total                                   6.56 GiB   of  10.65 GiB budget

Why
  - experts resident on the device: 6.56 GiB estimated + 0.53 GiB headroom fits the 10.65 GiB budget
  - ordering, expert_kernel: grouped_nf4 before reference: e4b.train.h2h.unsloth.olmoe.5090.2026-09-19 (1.39 vs 14.88 s/step), ...

Performance  not predicted: no performance model is calibrated for this backend yet; ...

Alternatives considered
  [fits ] experts on device, grouped_nf4 kernel, NF4 attention       device   6.10 GiB  host   0.72 GiB  ...
  [fits ] experts on host, grouped_nf4 kernel                        device   2.69 GiB  host   4.10 GiB  ...
  ...

Evidence, not vibes

Loggetta is deliberately not a performance oracle. It records what it knows, labels heuristics, refuses plans it cannot support, and feeds measured receipts back into future planning.

Current checks from docs/RESULTS.md:

An ExecutionReceipt carries provenance, allocator / reserved / driver peaks, correctness checks, engagement evidence, timing, and estimate-vs-measured deltas. That receipt is the measured counterpart to the plan that produced it.

Current scope

Those are roadmap items, not assumptions hidden inside current results.

Installation details

Starting with 0.1.1, the default install includes the runtime and kernel packages. There is no planner-only default that needs an extra to become useful.

Upgrading an earlier installation:

python -m pip install --upgrade loggetta

The old loggetta[experts4bit] spelling remains accepted as a compatibility alias. It is no longer necessary. Both lower packages can still be installed and used independently.

The minimum backend releases support training plans and execution plus serving plans. The newer serving-estimate refinements in RESULTS 6b-6e require APIs beyond e4b 0.48.0; that minimum release is not sufficient to reproduce those specific measurements. See docs/RESULTS.md for the backend revisions used.

Source installation for development:

git clone https://github.com/pjordanandrsn/loggetta
cd loggetta
python -m pip install -e .

Why keep the packages separate?

One install does not require one codebase. Kernel selection belongs with kernels. Model topology and QLoRA mechanisms belong with the runtime. Loggetta brings them together, decides which combination should run on this machine under the user's constraints, and makes that decision inspectable before execution.

The separation lets e4b and gnf4 remain independently useful, keeps backend knowledge with its owner, and allows receipts to improve planning policy without moving model or kernel code into the planner. Users get one starting point; maintainers keep clear boundaries.

Documentation

python -m pip install -e ".[test]"
pytest tests/
python bench/direct_baseline.py --receipt R.json
python bench/validate_register.py
python bench/family_sweep.py --hardware hw.json
python bench/summarize_receipts.py runs/receipts