cadenzalabs 0.3.0

The client for physical AI developers: register/clone project repos and drive the hosted megan governance (import `megan`) via api.cadenzalabs.xyz.

cadenza-cli

A command-line platform for physical-AI developers: scaffold a robot project, describe a multi-phase mission as JSON, run it in simulation, and turn the rollouts into fine-tuning data for a vision-language-action policy.

Run cadenza with no arguments for an interactive shell, or pass a command to run it once (cadenza env run my-project --headless).

Commands

Command	Description
mkdir <name>	Scaffold a project: env.json + main.py + requirements.txt + README.
env init <name>	Light scaffold — env.json only.
env show <name>	Render the mission's zones, objects, and phases.
env run <name> [--headless] [--policy scripted|lora] [--xml <path>]	Execute the mission, log every tick, and run the LLM judge.
env stats <name>	Motion + reward analytics across cached runs.
env cache <name> [--keep-last <n>] [--older-than <dur>] [--clear]	Show or prune the project's .cadenza-env/ runs.
env finetune <name> <log> [-o <file>]	Emit (prompt, action, reward) records from a run log for VLA training.
env train <name>	Groq LLM-as-Judge rewrites the project's system prompt (needs GROQ_API_KEY).
env action create <project> <name> [--group --steps '<a,b,c>'] [--custom --frames-file <file>] [--robot <name>]	Build an action (group macro or custom keyframes); saved locally + synced to your account. Requires login.
env action list	List your account's actions. Requires login.
env action show <project> <name>	Inspect a local action.
env action remove <project> <name>	Delete a local action.
env lora add <project> "<goal>" --steps '<...>' [--image <path>]	Add a goal→action training example.
env lora data <project> [--finetune <path>]	Show the training dataset.
env lora finetune <project> [--epochs <n>] [--lr <lr>] [--rank <r>] [--gate]	Fine-tune the LoRA action head; --gate runs the governance scorecard.
env lora eval <project> [--promote]	Run the governance scorecard on the trained adapter.
env lora decode <project> "<goal>"	Decode a goal into actions via the trained adapter.
login <name> <token>	Sign in; saves a session to ~/.cadenza/config.json.
logout	Forget the saved session.
whoami	Show the signed-in account.
apikey [--reveal]	Show your token as a megan-tk API key + a snippet to use cadenza as an API in your project. Requires login.
usage [--days <n>]	Show your megan-tk API usage: per-route calls + a session/anticipator rollup. Requires login.
help	Show the command table.
clear	Clear the screen.
--version	Print the version and check for updates.

Use cadenza as an API (megan-tk SDK)

Your Cadenza sign-in token doubles as an API key — pip install cadenzalabs, drop the SDK into any project, and drive the hosted megan-tk governance directly. No Supabase credentials; the server meters every call against your account so usage (CLI) / megan.usage() (SDK) can report it. Three surfaces:

• tk.governor() — the progress-guided governor: feed it live scalar progress each control step and apply the corrective action-frame rotation phi it returns (the whole bandit + gating runs server-side as the real megantk).
• tk.session(...) — the milestone / perception governance token (continue vs. adapt).
• tk.anticipator(...) — learn a periodic disturbance and pick a protective action.

from cadenzalabs import megan

tk = megan(api_key="<your-token>")            # or megan() to auto-resolve it
# (MeganTK is the same class, kept as a back-compat alias.)

# progress-guided governor — recover an execution shift on-device, no retraining
g = tk.governor(n_candidates=9, patience=6, eval_window=6)
for episode in episodes:
    g.episode_start()                          # imposes the learned correction
    for step in episode:
        phi = g.step(progress_now)             # radians; apply to your action's (x, y)
        env.step(rotate_xy(action, phi))
g.close()

# milestone path — act where the token is focused
with tk.session("pick up the red cube", ["reach", "grasp", "lift"]) as s:
    d = s.step(reached=[0], obstacles=[{"id": "wall", "milestone": 1}])
    if d.adapt:
        handle(d.frontier)

# disturbance anticipator — learn a rhythm, pick a protective action
a = tk.anticipator(actions=["brace", "dodge"])
a.disturbance(t=1.2); a.outcome("brace", saved=True)
p = a.protect(t=3.4)                          # p.should_protect, p.best_action

print(tk.usage())                             # your metered consumption

The key is resolved from the api_key argument, CADENZA_API_KEY / CADENZA_TOKEN, or the signed-in CLI session. See examples/megantk_quickstart.py. Run apikey in the CLI for a ready-to-paste snippet.