# kualia — full reference for language models

kualia is a web studio for teaching robots new skills with reinforcement learning in MuJoCo simulation: describe a trick in plain language, an AI assistant writes the training task and world, kualia checks and trains it (PPO), you watch it learn in 3D and export an ONNX policy for the real robot.

# How a project works
1. Describe: pick a robot and write the trick in one sentence ("walk forward without falling"). Optional: a success criterion, safety level (relaxed/standard/strict), reward style (dense/sparse), difficulty.
2. Plan & world: kualia's assistant (alia) plans the world (objects such as ball, box, step, ramp, wall, goal, target, knob, button — up to 8), writes a Gymnasium task in Python on a fixed MuJoCo robot (reward, success in info["is_success"], termination), and runs 13 automatic checks (syntax, sandbox safety, reset/step, reward finite and bounded, physics stability, episodes survive the reset, objects start clear, learnability). Failing checks are fixed automatically where possible.
3. Training: PPO (Stable-Baselines3) on kualia's servers. Budgets: 10,000 steps for a first try, 50,000 for more practice, the robot's "learn it" budget for a real skill. Every checkpoint is recorded as MuJoCo state and replayed in 3D in the browser; a live ONNX policy runs in the browser during training.
4. Results: mean reward, success rate, an AI review that proposes the next version, versions side by side, rollback.
5. Export: deterministic ONNX (observation normalisation baked in) plus metadata (observation layout, action scaling, control rate). Run with onnxruntime: action = session.run(None, {"obs": obs[None]})[0][0].

# Credits
Prepaid credits. Building a plan costs cents (LLM usage); training is priced per 1,000 steps; a first 10K-step run is about $1. Failed runs are refunded automatically. See https://kualia.ai/pricing.

# MCP server (for Claude Code, Cursor, Codex and other MCP clients)
URL: https://kualia.ai/api/mcp (Streamable HTTP, JSON responses). Auth: Authorization: Bearer <personal API key "kua_…"> from https://kualia.ai/dashboard/settings?tab=api. A key acts as its owner (credits and plan limits apply) and never grants admin access.
Tools:
- list_robots() → built-in robots (id, kind, tier, actuators, preview) and the caller's uploaded robots (id "custom:<n>").
- create_task(robot, trick, success?, difficulty?) → {task_id, status:"generating", studio}. Building takes ~1–3 minutes.
- get_task(task_id) → status (generating | draft | failed), trick, success_scenario, world_objects, reward, checks "passed/total", failing_checks, ready_to_train, studio link.
- start_training(task_id, steps=10000) → {run_id, status}. Requires all checks to pass.
- get_training(task_id) → latest run: status, progress, mean reward, success rate, error.
- get_policy(task_id) → ONNX and metadata URLs for the latest completed run (download with the same header).

# HTTP API (same key)
Base: https://kualia.ai/api/rlforge
- GET /robots — robot list.
- POST /generate {"description", "robot_model", "difficulty", "async": true} — start building a task; returns {"id", "status":"generating"}.
- GET /envs/{id} — task detail (status, env_spec, test_results).
- POST /train/{id} {"total_timesteps": 10000, "algorithm": "PPO"} — start training.
- GET /train/{id}/status — latest run status; GET /train/{id}/curve — learning curve.
- GET /train/{id}/onnx[?run_id=] — ONNX policy; GET /train/{id}/onnx/meta — its metadata.

# Robots
## Open Duck Mini v2 (Studio id: Duck)
The open-source, 3D-printed duck-shaped biped inspired by Disney's BDX droids. kualia ships its MJCF with a free-floating base and the Open Duck Playground's standing pose, so you can train walking and balance policies in MuJoCo without writing an environment.
- Kind: 3D-printed desk biped; actuators: 16; size: ≈35 cm; model license: Apache-2.0
- Typical PPO budget for a first skill: ~2M steps
- Example tricks: Walk forward without falling; Walk up a small ramp; Turn in place; Recover from a push
- Page: https://kualia.ai/robots/open-duck-mini

## Stanford ToddlerBot (Studio id: Toddlerbot)
Stanford's open-source, 3D-printed humanoid with legs, waist, arms and neck. kualia uses the MuJoCo Menagerie position-controlled model that starts from its home pose.
- Kind: open-source 0.5 m humanoid; actuators: 30; size: ≈50 cm; model license: MIT
- Typical PPO budget for a first skill: ~5M steps
- Example tricks: Stand and balance; Walk forward; Wave an arm while standing
- Page: https://kualia.ai/robots/toddlerbot

## ROBOTIS OP3 (Studio id: OP3)
The 50 cm Dynamixel-powered humanoid used in RoboCup kid-size and university labs, from MuJoCo Menagerie.
- Kind: small hobby humanoid; actuators: 20; size: ≈50 cm; model license: Apache-2.0
- Typical PPO budget for a first skill: ~5M steps
- Example tricks: Walk forward; Kick a ball into a goal; Get up after a fall
- Page: https://kualia.ai/robots/robotis-op3

## SO-101 arm (LeRobot) (Studio id: SO101)
The low-cost desktop arm from Hugging Face LeRobot: five joints and a gripper. Train reach, push and press policies in simulation and export ONNX for the real arm.
- Kind: desktop arm + gripper; actuators: 6; size: ≈40 cm reach; model license: Apache-2.0
- Typical PPO budget for a first skill: ~300K steps
- Example tricks: Press a button on the table; Reach a target; Push a box to a spot
- Page: https://kualia.ai/robots/so-101

## Low-cost robot arm (Studio id: LowCostArm)
The original 3D-printed low-cost arm with Dynamixel servos and a gripper — small, quick to train and forgiving.
- Kind: 3D-printed arm + gripper; actuators: 6; size: ≈25 cm reach; model license: Apache-2.0
- Typical PPO budget for a first skill: ~200K steps
- Example tricks: Reach a target; Press a button; Nudge a small box
- Page: https://kualia.ai/robots/low-cost-robot-arm

## Dynamixel 2R arm (Studio id: Dynamixel2R)
Two Dynamixel servos on a stand — the simplest real arm and a great first reinforcement-learning project; it learns in minutes.
- Kind: 2-link servo arm; actuators: 2; size: ≈36 cm reach; model license: MIT
- Typical PPO budget for a first skill: 50K steps
- Example tricks: Reach a target point; Hold a pose against gravity; Trace a small circle
- Page: https://kualia.ai/robots/dynamixel-2r

## Crazyflie 2 nano quadcopter (Studio id: Crazyflie)
Bitcraze's palm-sized open-source quadcopter: total thrust plus roll, pitch and yaw moments. A zero action holds the hover trim, so hover and waypoint policies train quickly.
- Kind: 27 g quadcopter; actuators: 4; size: 27 g; model license: MIT
- Typical PPO budget for a first skill: ~300K steps
- Example tricks: Hover and hold position; Fly to a target in the air; Recover from a tilt
- Page: https://kualia.ai/robots/crazyflie

## Inverted pendulum (Studio id: InvertedPendulum)
The classic cart-pole from the Gymnasium MuJoCo suite — the gentlest first robot for learning the workflow.
- Kind: cart-pole; actuators: 1
- Typical PPO budget for a first skill: 30K steps
- Example tricks: Balance the pole; Balance while staying near the centre
- Page: https://kualia.ai/robots/inverted-pendulum

## Reacher (Studio id: Reacher)
Gymnasium's planar two-link arm reaching for a target; trains in minutes.
- Kind: planar 2-link arm; actuators: 2
- Typical PPO budget for a first skill: 100K steps
- Example tricks: Reach a target; Press a button
- Page: https://kualia.ai/robots/reacher

## Hopper (Studio id: Hopper)
The single-leg hopper from Gymnasium: hop forward without falling.
- Kind: one-legged hopper; actuators: 3
- Typical PPO budget for a first skill: 300K steps
- Example tricks: Hop forward; Hop over a low step
- Page: https://kualia.ai/robots/hopper

## Walker2d (Studio id: Walker2d)
The classic two-legged planar walker from Gymnasium.
- Kind: planar biped; actuators: 6
- Typical PPO budget for a first skill: 500K steps
- Example tricks: Walk forward; Kick a ball into a goal
- Page: https://kualia.ai/robots/walker2d

## HalfCheetah (Studio id: HalfCheetah)
Cannot fall; pure speed and gait efficiency.
- Kind: planar runner; actuators: 6
- Typical PPO budget for a first skill: 300K steps
- Example tricks: Run forward fast; Run backwards
- Page: https://kualia.ai/robots/halfcheetah

## Ant (Studio id: Ant)
Gymnasium's four-legged walker with contact-rich dynamics.
- Kind: quadruped; actuators: 8
- Typical PPO budget for a first skill: 1M steps
- Example tricks: Walk forward; Walk to a target
- Page: https://kualia.ai/robots/ant

## Humanoid (classic) (Studio id: Humanoid)
Gymnasium's full 3D biped — high-dimensional and unstable.
- Kind: 3D humanoid; actuators: 17
- Typical PPO budget for a first skill: 2M steps
- Example tricks: Stand up; Walk forward
- Page: https://kualia.ai/robots/humanoid

## Unitree Go2 (Studio id: Go2)
Unitree's robot dog from MuJoCo Menagerie (position-controlled variant), starting from its standing pose.
- Kind: consumer quadruped; actuators: 12; size: ≈40 cm tall; model license: BSD-3-Clause
- Typical PPO budget for a first skill: ~3M steps
- Example tricks: Trot forward; Push a ball; Walk up a ramp
- Page: https://kualia.ai/robots/unitree-go2

## Boston Dynamics Spot (Studio id: Spot)
Spot from MuJoCo Menagerie. A preview robot on kualia: plan tasks, run the checks and short capped tries; full training needs GPU runs.
- Kind: industrial quadruped; actuators: 12; size: ≈84 cm tall; model license: BSD-3-Clause
- Typical PPO budget for a first skill: ~3M steps
- Preview robot: simulation-only on kualia's CPU servers, runs capped at 30,000 steps
- Example tricks: Walk forward; Stop before a wall
- Page: https://kualia.ai/robots/boston-dynamics-spot

## Unitree G1 (Studio id: G1)
Unitree's 29-joint humanoid from MuJoCo Menagerie. A preview robot on kualia: plan tasks and run short capped tries; a real gait needs GPU-scale training.
- Kind: full-size humanoid; actuators: 29; size: ≈1.3 m; model license: BSD-3-Clause
- Typical PPO budget for a first skill: ~10M steps
- Preview robot: simulation-only on kualia's CPU servers, runs capped at 30,000 steps
- Example tricks: Stand and balance; Climb stairs
- Page: https://kualia.ai/robots/unitree-g1

## Franka Panda (Studio id: Panda)
The 7-axis research arm with a gripper from MuJoCo Menagerie. A preview robot on kualia with capped runs.
- Kind: research arm + gripper; actuators: 8; size: ≈85 cm reach; model license: Apache-2.0
- Typical PPO budget for a first skill: ~500K steps
- Preview robot: simulation-only on kualia's CPU servers, runs capped at 30,000 steps
- Example tricks: Press a button, then turn a valve; Reach a target
- Page: https://kualia.ai/robots/franka-panda

# Bring your own robot
Upload MJCF or URDF (optionally a .zip with STL/OBJ meshes) at https://kualia.ai/dashboard/robots/import. URDFs are converted by MuJoCo; position actuators are added per joint when missing; massless links get MuJoCo's boundmass/boundinertia. Onshape → onshape-to-robot → kualia works well for 3D-printed robots.