Loggetta owns the Planner, the ExecutionPlan, and the ExecutionReceipt. Its current focus is single-GPU MoE training and serving through experts4bit-qlora, with grouped-nf4-gemm providing the packed low-bit kernel and residency primitives beneath that runtime.

The loop

flowchart LR
    I["Workload + machine<br/>constraints + evidence"] --> P["Loggetta Planner"]
    P --> X["ExecutionPlan<br/>what should run + why"]
    X --> E["experts4bit-qlora<br/>executes the plan"]
    E --> G["grouped-nf4-gemm<br/>kernels + primitives"]
    E --> R["ExecutionReceipt<br/>what actually happened"]
    R -. "measured feedback" .-> P

The ownership split is deliberate:

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

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

Quick start

# What machine am I actually on?
python -m loggetta inspect

# Produce the artifact Loggetta exists to produce
python -m loggetta plan Qwen/Qwen3-30B-A3B --seq 2048

# Constrain the planner deliberately
python -m loggetta plan allenai/OLMoE-1B-7B-0924 --experts device --vram 6

# Keep the plan as a file, then execute that plan through the backend; the receipt lands in receipts/
python -m loggetta plan allenai/OLMoE-1B-7B-0924 --seq 512 --micro-batch 2 --steps 12 --out plan.json
python -m loggetta execute plan.json --out receipts/

# Plan again from what was measured
python -m loggetta plan allenai/OLMoE-1B-7B-0924 --seq 512 --micro-batch 2 --observations receipts/

train MODEL ... is plan and execute in one step. Serving is planned with plan MODEL --workload serve --context T --concurrency N. The plan's Why carries the server's exact environment; execute does not start servers yet.

Three levels of control

plan() is pure policy: for the same inputs it returns the same serializable ExecutionPlan, without loading weights or touching the device. The plan includes the winner, every relevant loser and why it lost, budget sources, evidence labels, warnings, and explicit “not modeled” items.

execute(plan) is intentionally thin. It validates the plan, delegates execution to the selected backend, and constructs an ExecutionReceipt from the backend result. It does not reimplement the runtime. 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.

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.

Install

For planning plus the current experts4bit-qlora backend:

python -m pip install "loggetta[experts4bit]"

For the planner core only:

python -m pip install loggetta

The released backend floor is:

• experts4bit-qlora >= 0.48.0
• grouped-nf4-gemm >= 0.41.0

Those releases support training plans and execution plus serving plans. The newest serving-estimate refinements in RESULTS 6b–6e depend on APIs that are newer than e4b 0.48.0; reproducing those specific measurements currently requires experts4bit-qlora main. Loggetta labels unsupported or unavailable mechanisms rather than pretending they exist.

Source installs remain useful for development:

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

Why a separate planner?

Kernel selection belongs with kernels. Model topology and QLoRA mechanisms belong with the runtime. The decision which combination should run on this machine, under this budget, for this objective is a separate concern, and the ExecutionPlan is the durable artifact of that decision.

Keeping that boundary clean means:

• backend packages remain independently useful;
• planning stays deterministic and inspectable;
• the plan can explain both selection and refusal before weight loading;
• the runtime can evolve without absorbing cross-machine policy;
• receipts can improve future policy without contaminating kernel or model code;
• a second backend can earn a general abstraction instead of forcing one prematurely.

Documentation

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