Metadata-Version: 2.4
Name: cadenzalabs
Version: 0.2.0
Summary: CLI platform for physical AI developers to register project repos and clone them on demand.
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: tomli-w>=1.0
Provides-Extra: gym
Requires-Dist: cadenza-lab>=1.5.0; extra == "gym"
Requires-Dist: mujoco; extra == "gym"
Provides-Extra: lora
Requires-Dist: cadenza-lab>=1.5.0; extra == "lora"
Requires-Dist: torch>=2.2; extra == "lora"
Provides-Extra: rl
Requires-Dist: torch>=2.2; extra == "rl"
Provides-Extra: vla
Requires-Dist: cadenza-lab>=1.5.0; extra == "vla"
Requires-Dist: torch>=2.2; extra == "vla"
Requires-Dist: transformers>=4.40; extra == "vla"
Requires-Dist: lerobot; extra == "vla"

<h1 align="center">cadenza-cli</h1>

<p align="center">
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.
</p>

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** — drop the SDK into any
project and drive the hosted [megan-tk](https://api.cadenzalabs.xyz/megantk/version)
symbolic governance directly. No Supabase credentials; the server meters every
call against your account so `usage` (CLI) / `MeganTK.usage()` (SDK) can report it.

```python
from cadenzalabs import MeganTK

tk = MeganTK(api_key="<your-token>")          # or MeganTK() to auto-resolve it

# 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`](examples/megantk_quickstart.py). Run `apikey`
in the CLI for a ready-to-paste snippet.
