Examples

# scaffold + inspect
cadenza mkdir rescue-dog
cadenza env show rescue-dog

# run headless, score automatically
cadenza env run rescue-dog --headless

# analyze and export training data
cadenza env stats rescue-dog
cadenza env finetune rescue-dog .cadenza-env/<run-id>.log.jsonl -o train.jsonl

{
  "name": "find_victim",
  "goal_prompt": "search the debris interior and stop next to the victim",
  "success_when": {"near_object": {"tag": "victim", "max_distance_m": 0.4, "for_ticks": 3}},
  "fail_when":    {"flipped": true},
  "reward": {
    "step_cost": -0.05,
    "distance_to_tag": {"tag": "victim", "weight": 0.5},
    "contact_with_rubble_penalty": -0.3,
    "phase_success_bonus": 3.0
  },
  "max_ticks": 40
}

cadenza env run rescue-dog --headless

cadenza login ada my-token

# a macro that enters and searches
cadenza env action create rescue-dog enter_and_search \
  --group --steps 'walk_forward,crawl_forward,turn_left'

cadenza env action list        # confirm it synced to your account

# requires the lora extra: pip install -e ".[lora]"
cadenza env lora add rescue-dog "enter the debris field" \
  --steps 'walk_forward 1.0, crawl_forward 0.5'
cadenza env lora finetune rescue-dog --epochs 5 --rank 8 --gate
cadenza env lora eval rescue-dog
cadenza env run rescue-dog --headless --policy lora

# requires the rl extra: pip install -e ".[rl]"
cadenza login ada my-token

# scaffold + profile the residual head on the frozen base
cadenza env residual init rescue-dog --alpha 0.15

# governed PPO (the API steers + returns DEPLOY|BLOCK|NEEDS_DATA)
cadenza env residual train rescue-dog

# prove it beats full RL on compute / cost / accuracy
cadenza env residual bench rescue-dog

# distill into a compact, int8, base-free onboard student + govern it
cadenza env distill rescue-dog --quantize
cadenza env distill eval rescue-dog --promote

# requires the lora extra (and vla for a real model)
cadenza env vla init reach-arm --robot franka --model default
cadenza env vla data reach-arm add "reach the red block" \
  --steps 'move_forward 1.0, lower_arm 0.5, close_gripper'
cadenza env vla grd reach-arm --rounds 4
cadenza env vla eval reach-arm --promote

from pathlib import Path
from cadenzalabs.customenv import CustomEnv, load_config

cfg = load_config(Path("rescue-dog/env.json"))
env = CustomEnv(cfg, headless=True)

obs, info = env.reset()
done = False
while not done:
    action = your_policy(obs, info["goal_prompt"])   # ActionCall, dict, or str
    obs, reward, terminated, truncated, info = env.step(action)
    done = terminated or truncated

env.write_finetune(Path("train.jsonl"))