# lvrged-factory

**GPU infrastructure control for Pi — v2.** Install one package and your
agent can provision, deploy, run, monitor, pause, and destroy GPU video
workloads on RunPod, with **MiniMax H3 on an RTX PRO 6000** as the
zero-friction default lane: Turbo LoRA v4 (8 steps, euler/beta) +
SageAttention2 + INT8 on the cu130 image. Other providers plug in via a table
entry + skill recipe; no release needed.

```bash
pi install npm:@lvrged/lvrged-factory
```

Then, inside Pi:

> Set me up to make H3 videos.

The agent runs the onboarding skill, asks exactly two questions (batch size,
budget), and everything else is preset — GPU, image, disk, ports, workflow
stack, capacity fallback. Every default was verified in a live RunPod
session on 2026-08-12.

## The lane (what you get without choosing anything)

| Layer | Preset |
| --- | --- |
| Provider / GPU | RunPod · RTX PRO 6000 96GB (`--gpu-id "NVIDIA RTX PRO 6000 Blackwell Server Edition"`) |
| Image | `runpod/comfyui:cuda13.0` — official cu130 build, live-verified layout; real SageAttention2 built at install (cu128 runs H3 INT8 ~2x slower) |
| Disk | 80GB container disk, **no network volume** (volumes DC-lock the install) |
| Weights | Comfy-Org/MiniMax-H3 pruned INT8 set + larryvrh Turbo LoRA v4 step600 EMA (~41GB, public) |
| Workflow | Turbo 8 steps · euler (MiniMaxH3TurboSampler, video shift 12 / audio shift 3) · beta scheduler · Sage2 ON |
| Capacity | provision tool tries COMMUNITY across the DC rotation, then SECURE, shrinking disk when a machine doesn't fit — expect secure $2.09/hr in practice |
| Cost | ~$0.25 per finished 480p minute at the 8-step anchor; ~$0.70 of each fresh pod is startup |

## What you get

- **`lvrged_factory_*` tools** — the state machine: `lvrged_factory_setup`,
  eight resource-oriented tools: `lvrged_factory_setup`, `_status`,
  `_ensure` (the idempotent entry point), `_pod` (provision — capacity
  fallback built in — register, pause, resume, destroy), `_job` (run,
  progress, watch — background queue watcher with done/stuck notifications —
  finish), `_ledger` (job queries + cost rollups), `_manifest`
  (model/workflow registry), `_policy` (the spend trust boundary, kept
  deliberately separate).
- **`/lvrged-factory` commands** — the human dashboard (`gpu status`, `gpu
  onboard`, `gpu jobs`, `gpu spend`, ...).
- **`scripts/` — the golden path**, shared by Pi and Claude Code users:
  ```bash
  POD=$(scripts/h3-pod-up.sh)     # provision with capacity fallback
  scripts/h3-install.sh "$POD"    # nodes + weights + sage + pod restart + verify
  scripts/h3-run.py --prompt "..."   # generate; timings recorded
  scripts/h3-benchmark.sh         # benchmark protocol v1 (cold + 5 warm, median)
  ```
- **Skills** — the knowledge, with every hard-won ops lesson folded in:
  the comfyui_args.txt + pod-restart convention (never hand-roll daemons),
  the SageAttention stub trap, the model path-prefix HTTP-400, the SSH
  tunnel fallback, capacity-error decoding, pause/resume semantics.
- **Docs** — `docs/h3-economics.md` (including **benchmark protocol v1**),
  per-provider playbooks, pricing snapshots, architecture.
- **A persistent registry + job ledger** in `<project>/.pi/lvrged-factory/gpu/`
  — the agent restarts tomorrow and still knows what's deployed, what it
  costs per minute, and which workflow version made which video.

## Using the same skills with Claude Code (no Pi)

`claude-skills/` ships the same knowledge adapted to bash-only operation
(no `lvrged_factory_*` tools), sharing the same JSON registry and the same
`scripts/`:

```bash
cp -r claude-skills/* /path/to/your/project/.claude/skills/
```

## Architecture

See `docs/ARCHITECTURE.md`. The rules that matter: the core abstraction is
the **deployment**; the ledger is the source of truth; the extension is
**dumb but strict** (state, spend policy, deterministic command templates —
no reasoning); the agent executes, guided by skills; the golden path is
scripted.

```
                Pi Agent  ──────────  Claude Code
                    │                      │
          lvrged-factory extension      claude-skills (bash)
                    │                      │
             provider capability        scripts/
                  tables                   │
                    └────────┬─────────────┘
                          RunPod
                    (more via adapters)
```

## The spend policy (read this)

Extensions run arbitrary code — this one executes provider CLIs and **spends
real money**. The trust boundary is `.pi/lvrged-factory/gpu/policy.json`:

```json
{ "ceiling_per_job_usd": 5, "ceiling_daily_usd": 40, "ceiling_monthly_usd": 400, "confirm_above_usd": 1, "idle_shutdown_after_min": 30 }
```

Provisioning above `confirm_above_usd` always asks you in the UI (quoting the
secure rate, since community stock-outs are the norm), and ceilings cap what
the agent may do without checking in. The agent cannot weaken these
silently. Review this package's source before installing — it's yours.

Also worth knowing before you spend: pods bill from creation (a stuck image
pull still costs); a $0 RunPod balance kills pods and deletes disks — keep a
$5–10 buffer; and the H3 license excludes US/EU/UK/South Korea — your read.

## Development

```bash
npm install          # dev deps (typescript, pi types)
npx tsc --noEmit     # typecheck
bash -n scripts/*.sh && python3 -m py_compile scripts/h3-run.py
pi -e .              # load the extension from this dir in a scratch session
```

## License

MIT (the package — the H3 model weights carry their own license; see above)