feat(lucebox): guided CLI for buyers and contributors by easel · Pull Request #335 · Luce-Org/lucebox

easel · 2026-06-03T21:29:59Z

Summary

Ship one simple inference CLI for both Lucebox buyers and open-source contributors.

Running lucebox opens the branded ASCII menu. Wi-Fi, Bluetooth, and device provisioning are intentionally outside this PR; this surface is focused on selecting, configuring, and running the inference engine.

Buyer flow

lucebox setup guides backend/image selection, model selection, optimization, background-service installation, and start.
lucebox models select shows a numbered catalog, downloads when needed, and activates factory-preloaded models without contacting Hugging Face.
lucebox optimize explains the decision for DFlash, PFlash, KVFlash, and Spark before applying it.
- Automatic is model-, primary-GPU-, VRAM-, host-RAM-, and installed-asset-aware.
- Advanced lets the user override those four product choices while context, cache, and DDTree details remain safely tuned.
Automatic profiles are replanned when the model changes; direct low-level edits become a preserved Custom profile.
The menu exposes start, stop, status, logs, active model, backend, optimization mode, and engine state.

Safe optimization behavior

DFlash is enabled only when a non-empty matching draft/speculator is installed.
PFlash is automatic only for the validated Qwen3.6 dense long-context path and uses one shared Qwen3-0.6B BF16 scorer.
KVFlash is enabled automatically only under real Qwen-family memory pressure; otherwise exact full-KV execution is preferred.
Spark is enabled automatically only for supported MoE models under VRAM pressure and with at least 32 GB reported host RAM for cold experts.
Automatic profiles leave KV dtype selection to each model family and do not reintroduce the quality-risky blanket tq3_0 fallback.
Zero-byte model/scorer placeholders and incompatible KVFlash + FA-window settings are rejected.

Hardware behavior

NVIDIA CUDA and AMD ROCm image/runtime selection.
RTX 3090 + Strix defaults to CUDA; an explicit ROCm choice retunes against the AMD device facts.
R9700 + Strix selects ROCm and pins the largest-VRAM AMD device with ROCR_VISIBLE_DEVICES.
Strix-only ROCm remains supported.
Automatic tuning uses one selected primary GPU and never sums VRAM across devices. Transparent multi-GPU layer sharding is not claimed by this release.

Contributor flow

The same ./lucebox.sh menu detects a source checkout and adds:

lucebox build [cuda|rocm] — native dflash_server build for the selected accelerator.
lucebox native [cuda|rocm] — run the selected model with the native engine.
lucebox harness — Claude Code, Codex, OpenCode, Hermes, Pi, OpenClaw, and Open WebUI picker.
Native and harness paths receive the same DFlash/PFlash/KVFlash/Spark profile as the buyer container path.

All menu actions keep scriptable equivalents for CI and expert workflows.

Package and installation

install.sh installs the small host wrapper; buyer machines can receive the wrapper, image, models, and shared optimizer scorer preinstalled.
The typed lucebox/ Python package remains the source of truth for TOML config, model downloads, optimization planning, and launch construction.
The package builds as a wheel and source distribution with the lucebox console entry point.

Validation

166 Python tests on macOS and on Lucebox5.
Ruff correctness checks and MyPy (11 typed source modules).
ShellCheck, Bash syntax checks, and the 71-case wrapper/entrypoint/harness integration suite on Lucebox5.
Final wheel + source distribution build; clean isolated wheel install and console-entry-point smoke.
Lucebox5 hardware probe: R9700 gfx1201 + Strix gfx1151, ROCm 7.2.4, 125 GB RAM.
Lucebox5 live offline/preload flow: activate Qwen3.6-27B, apply Automatic, persist DFlash + PFlash at 98,304 context, pin the R9700 by stable ROCm UUID, and render the final launch contract.
All nine findings from Cubic's automated review were handled and regression-tested.
GitHub CI and CUDA/ROCm image jobs for commit 12d1ab51 (running).

Lucebox5 currently has no Docker installation, so this validation covers real hardware detection, CLI/config behavior, and the ROCm launch contract, but not an end-to-end container inference request. Existing GitHub CUDA/ROCm build and GPU jobs provide the engine/image coverage.

Out of scope

Wi-Fi/Bluetooth/Tailscale onboarding.
Transparent automatic multi-GPU layer sharding.
Benchmark sweeps that mutate a user's profile automatically.
A separate GUI.

## What Containerization stack for lucebox-hub. Dockerfile + docker-bake.hcl build the lucebox-hub image (build-env and runtime stages); scripts/build_image.sh drives local builds; server/scripts/entrypoint.sh emits IMAGE_INFO / HOST_INFO sidecars consumed by /props. GitHub Actions add .github/workflows/docker.yml (build & publish), update ci.yml, and add release-luce-bench.yml for tagging. Workspace-root files (pyproject.toml, uv.lock, Makefile, lefthook.yml, .gitignore, README) live here because the Dockerfile uv-syncs the workspace at build time. ## Why Provides the reproducible image and CI pipeline every other split PR deploys into. Centralizing build/publish here keeps Dockerfile, entrypoint, and workspace-root pinning in one reviewable change. ## Dependencies - Luce-Org#335 (lucebox-cli): Dockerfile COPYs lucebox/ into the image - Luce-Org#337 (lucebench-harness): Dockerfile COPYs luce-bench/ into the image

cubic-dev-ai

All reported issues were addressed across 52 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

Containerization stack for lucebox-hub. Dockerfile + docker-bake.hcl build the lucebox-hub image (build-env and runtime stages); scripts/build_image.sh drives local builds; server/scripts/entrypoint.sh emits IMAGE_INFO / HOST_INFO sidecars consumed by /props. GitHub Actions add .github/workflows/docker.yml (build & publish), update ci.yml, and add release-luce-bench.yml for tagging. Workspace-root files (pyproject.toml, uv.lock, Makefile, lefthook.yml, .gitignore, README) live here because the Dockerfile uv-syncs the workspace at build time. Provides the reproducible image and CI pipeline every other split PR deploys into. Centralizing build/publish here keeps Dockerfile, entrypoint, and workspace-root pinning in one reviewable change. - Luce-Org#335 (lucebox-cli): Dockerfile COPYs lucebox/ into the image - Luce-Org#337 (lucebench-harness): Dockerfile COPYs luce-bench/ into the image

…R + personal refs Strip forward-references to lucebox-cli (Luce-Org#335) and luce-bench (Luce-Org#337) plus the contributor's personal repos so the docker stack stands alone: - delete .github/workflows/release-luce-bench.yml (luce-bench PyPI publish; fires only on luce-bench-v* tags, needs a luce-bench/ dir not in this repo) - Makefile: drop test/smoke/bench/profile targets (invoke lucebench/lucebox modules absent here) and their now-unused vars - .gitignore: drop luce-bench/snapshots and external baseline-repo URLs - pyproject.toml / Dockerfile / docker.yml: de-reference Luce-Org#335/Luce-Org#337/luce-bench in comments No functional change: deps, workspace members, ruff config, and every build instruction are untouched, so CI stays green. The siblings re-add their own scaffolding when they land. Co-Authored-By: WOZCODE <contact@withwoz.com>

cubic-dev-ai

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lucebox/src/lucebox/docker_run.py">

<violation number="1" location="lucebox/src/lucebox/docker_run.py:231">
P3: Several newly added helper functions are dead code (defined but never called anywhere in the codebase).</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

…oad core Defer second-order features to follow-up PRs so this PR is just the host wrapper and the CLI needed to install, launch/serve, configure, and download models. Cuts the PR from ~11.2k to ~6.2k added lines. Deferred out of this PR (land as stacked follow-ups): - Agent-client adapters + bench: the entire net-new harness/ package (bench.py, the six clients, run_lucebench.sh) and the client launcher verbs. harness/ reverts to main's loose-scripts state; the root pyproject no longer adds harness as a workspace member/dep. - Autotune sweep + profiles: candidate_configs, the Profile registry and per-arch brackets, sweep.py, and the `autotune` command. The host-derived DFLASH_* heuristic (runtime_from_host) STAYS — config.live_config needs it to bake serve defaults — slimmed into autotune.py. - profile + smoke commands and their modules. Coupling fixes: - recommend_preset moved autotune.py -> download.py (models sub-app uses it). - Wrapper: drop the autotune --sweep exec-routing special case and trim usage/completion/exec-set to the core verbs. Tests/CI follow the surface: deferred-feature tests removed; runtime_from_host heuristic tests kept; new guard asserts the deferred verbs are NOT registered. CI pytest step scoped to lucebox. lucebox 72 passed, wrapper 53 passed, ruff + mypy + shellcheck clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cubic-dev-ai

1 issue found across 37 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lucebox/src/lucebox/docker_run.py">

<violation number="1" location="lucebox/src/lucebox/docker_run.py:231">
P3: Several newly added helper functions are dead code (defined but never called anywhere in the codebase).</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

…oad core Defer second-order features to follow-up PRs so this PR is just the host wrapper and the CLI needed to install, launch/serve, configure, and download models. Cuts the PR from ~11.2k to ~6.2k added lines. Deferred out of this PR (land as stacked follow-ups): - Agent-client adapters + bench: the entire net-new harness/ package (bench.py, the six clients, run_lucebench.sh) and the client launcher verbs. harness/ reverts to main's loose-scripts state; the root pyproject no longer adds harness as a workspace member/dep. - Autotune sweep + profiles: candidate_configs, the Profile registry and per-arch brackets, sweep.py, and the `autotune` command. The host-derived DFLASH_* heuristic (runtime_from_host) STAYS — config.live_config needs it to bake serve defaults — slimmed into autotune.py. - profile + smoke commands and their modules. Coupling fixes: - recommend_preset moved autotune.py -> download.py (models sub-app uses it). - Wrapper: drop the autotune --sweep exec-routing special case and trim usage/completion/exec-set to the core verbs. Tests/CI follow the surface: deferred-feature tests removed; runtime_from_host heuristic tests kept; new guard asserts the deferred verbs are NOT registered. CI pytest step scoped to lucebox. lucebox 72 passed, wrapper 53 passed, ruff + mypy + shellcheck clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cubic-dev-ai

All reported issues were addressed across 33 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 33 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

davide221 · 2026-07-27T11:03:19Z

Cross-vendor Lucebox follow-up is in 23a203e.

RTX 3090 + Strix: detects both vendors, selects :cuda12, and uses --gpus all.
R9700 + Strix: selects :rocm, exposes /dev/kfd + /dev/dri, and chooses the 32 GB R9700 (gfx1201) as the primary tuning device while retaining the Strix (gfx1151) in inventory.
Versioned/PR ROCm tags (for example 0.3.0-rocm) also get the ROCm Docker contract.
Explicit LUCEBOX_VARIANT / config remains higher priority than auto-selection.

Validation:

Python: 95 passed
Ruff: pass
mypy: pass
ShellCheck + wrapper/entrypoint suite on Lucebox5: 57 passed
Real Lucebox5 probe: ROCm 7.2.4, R9700 gfx1201 32624 MiB + Strix gfx1151 512 MiB, /dev/kfd and render nodes accessible, :rocm selected

Lucebox5 does not currently have Docker installed, so full image launch there remains untested; no host packages or services were changed. GitHub CUDA/ROCm image builds and the RTX 3090 jobs are running now.

cubic-dev-ai

All reported issues were addressed across 11 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

davide221 · 2026-07-27T12:02:10Z

Final validation for 21206f6:

102 Python tests passed
60 shell/ShellCheck tests passed on Lucebox5
Ruff and mypy passed
CMake/megakernel build passed
Live RTX 3090 GPU test and speed profile passed
Live Radeon gfx1151/ROCm GPU test passed
CUDA 12 and ROCm images built successfully
Cubic automated re-review passed with all reported issues addressed

Heterogeneous appliance behavior:

RTX 3090 + Strix selects CUDA and uses the RTX 3090; Strix does not override it.
R9700 + Strix selects ROCm, chooses the R9700 as the primary tuning device, and exposes both AMD devices through /dev/kfd and /dev/dri.

Lucebox5 was checked against its real R9700 + Strix hardware and ROCm 7.2.4. Docker is not installed on that host, so a full local container launch was not executed there; real-host detection and launch argument generation were validated, and the ROCm image plus live gfx1151 CI both passed.

All required PR checks are green, and GitHub reports the PR clean and mergeable.

cubic-dev-ai

All reported issues were addressed across 20 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 20 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 18 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

User-facing host wrapper + in-container Python CLI for launching and configuring the lucebox-hub image. Completes the docker-stack (Luce-Org#334) follow-up that intentionally shipped images without the CLI package. Host surface: - install.sh bootstrap + lucebox.sh wrapper (probe host, systemd unit, serve/pull/update/check/logs) - config.toml as system of record (env > file > defaults) In-container package (lucebox/): - check, pull, print-run, print-serve-argv - config {get,set,unset} - models {list,download} with VRAM-tier recommend_preset - VRAM-tier DFLASH_* heuristic (runtime_from_host); seeds config.toml on first models download --activate so 24 GB hosts get 98k/tq3_0 instead of the 16k class default - prefix_cache stays off by default (agent tool-prompt regression) Image/workspace: - COPY lucebox into CUDA and ROCm images; uv workspace member - entrypoint host_info missing-dir guard + pure-bash trim Tests/CI: lucebox pytest, wrapper sandbox scripts, lefthook. Deferred to follow-ups: autotune sweep/profiles, profile/smoke, agent-client harness adapters.

Make the buyer and contributor CLI model-aware and hardware-aware across CUDA, ROCm, and heterogeneous Lucebox builds. Add explainable Automatic/Advanced DFlash, PFlash, KVFlash, and Spark profiles; safe artifact, memory, and cache validation; native harness forwarding; and R9700/Strix device pinning.

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from 91276a7 to 62b21f0 Compare June 4, 2026 02:50

This was referenced Jun 4, 2026

feat(luce-bench): in-tree bench harness + multi-turn agent_recorded + LLM judge #337

Open

build(docker): lucebox-hub container image + CI release pipeline #334

Merged

refactor(server): shared layer-split backend + GGUF inspection + c2-gate plumbing #336

Closed

easel force-pushed the feat/lucebox-cli branch from 62b21f0 to 8732b35 Compare June 4, 2026 05:02

easel mentioned this pull request Jun 4, 2026

feat(lucebox): docker stack + CLI + bench/profile + harness + luce-bench in-tree #285

Closed

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from 6c9078b to 360d332 Compare June 4, 2026 17:17

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from 1d588db to 0d8e1ff Compare June 4, 2026 18:38

easel marked this pull request as ready for review June 4, 2026 19:18

cubic-dev-ai Bot reviewed Jun 4, 2026

View reviewed changes

easel force-pushed the feat/lucebox-cli branch from 0d8e1ff to 73f04f4 Compare June 4, 2026 23:30

easel pushed a commit to easel/lucebox-hub that referenced this pull request Jun 5, 2026

docs: refresh auto-integration manifest for PR Luce-Org#335 probe

0c8511f

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from bb7bb11 to a56b51b Compare June 8, 2026 22:08

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from 5a7e617 to c46e358 Compare June 11, 2026 15:15

cubic-dev-ai Bot reviewed Jun 11, 2026

View reviewed changes

Comment thread scripts/test_lucebox_sh.sh

easel force-pushed the feat/lucebox-cli branch 3 times, most recently from a731f1d to 71139a5 Compare June 16, 2026 17:22

cubic-dev-ai Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread lucebox.sh Outdated

cubic-dev-ai Bot reviewed Jul 21, 2026

View reviewed changes

easel force-pushed the feat/lucebox-cli branch from 32554cc to 7611c28 Compare July 23, 2026 20:15

easel changed the title ~~feat(lucebox): hub CLI + autotune/sweep/profile + harness adapters + shell wrapper~~ feat(lucebox): hub CLI — install, serve, config, models Jul 23, 2026

cubic-dev-ai Bot reviewed Jul 27, 2026

View reviewed changes

Comment thread scripts/test_lucebox_sh.sh

Comment thread lucebox.sh

Comment thread lucebox/src/lucebox/docker_run.py Outdated

cubic-dev-ai Bot reviewed Jul 27, 2026

View reviewed changes

Comment thread lucebox/src/lucebox/docker_run.py Outdated

Comment thread lucebox/src/lucebox/docker_run.py

cubic-dev-ai Bot reviewed Jul 27, 2026

View reviewed changes

Comment thread lucebox/tests/test_config_cli.py Outdated

Comment thread install.sh

Comment thread lucebox/src/lucebox/docker_run.py Outdated

Comment thread lucebox/src/lucebox/docker_run.py

davide221 force-pushed the feat/lucebox-cli branch from 3854101 to 875838c Compare July 28, 2026 14:15

davide221 changed the title ~~feat(lucebox): hub CLI — install, serve, config, models~~ feat(lucebox): guided CLI for buyers and contributors Jul 28, 2026

cubic-dev-ai Bot reviewed Jul 29, 2026

View reviewed changes

davide221 force-pushed the feat/lucebox-cli branch 2 times, most recently from 2fd3744 to 7a458f0 Compare July 30, 2026 16:56

easel and others added 14 commits July 30, 2026 21:50

feat(lucebox): support AMD and heterogeneous GPU builds

a518afb

fix(lucebox): harden config and target-only launches

2dc5cd5

fix(lucebox): align fallback config paths

b006529

fix(lucebox): harden the CLI package

5def447

test(lucebox): validate speculator symlinks

6bdb7b6

refactor(lucebox): tighten package edge cases

180f6b1

feat(lucebox): add guided inference menu

dc8c68a

fix(lucebox): resolve final CLI review findings

0b1d2ce

feat(lucebox): connect installed clients safely

008a4c5

fix(ci): include CMake test discovery in images

fef37c0

feat(lucebox): automate heterogeneous inference placement

bcadfe8

fix(lucebox): keep automatic plans within safe memory

909e74a

davide221 force-pushed the feat/lucebox-cli branch from 7a458f0 to 909e74a Compare July 30, 2026 20:19

Uh oh!

Conversation

easel commented Jun 3, 2026 • edited by davide221 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Buyer flow

Safe optimization behavior

Hardware behavior

Contributor flow

Package and installation

Validation

Out of scope

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davide221 commented Jul 27, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davide221 commented Jul 27, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

easel commented Jun 3, 2026 •

edited by davide221

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading