jolly-cli 0.1.0__py3-none-any.whl

jolly/__init__.py

@@ -0,0 +1,4 @@
+"""Jolly robot-arm simulator."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

jolly/__main__.py

@@ -0,0 +1,4 @@
+from jolly.cli import main
+
+if __name__ == "__main__":
+    main()

jolly/assets/__init__.py

@@ -0,0 +1 @@
+"""Bundled robot models."""

jolly/assets/jolly6.urdf

@@ -0,0 +1,21 @@
+<?xml version="1.0"?><robot name="jolly6">
+<link name="base_link"><inertial><mass value="1.5"/><inertia ixx="0.02" ixy="0" ixz="0" iyy="0.02" iyz="0" izz="0.02"/></inertial><visual><origin xyz="0 0 0.04"/><geometry><cylinder radius="0.075" length="0.08"/></geometry><material name="base"><color rgba="0.12 0.14 0.18 1"/></material></visual><collision><origin xyz="0 0 0.04"/><geometry><cylinder radius="0.075" length="0.08"/></geometry></collision></link>
+<link name="shoulder_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0 0 0.035" rpy="0 0 0"/><geometry><cylinder radius="0.032" length="0.07"/></geometry><material name="m_shoulder_link"><color rgba="0.95 0.55 0.10 1"/></material></visual><collision><origin xyz="0 0 0.035" rpy="0 0 0"/><geometry><cylinder radius="0.032" length="0.07"/></geometry></collision></link>
+<link name="upper_arm_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.1 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.025" length="0.2"/></geometry><material name="m_upper_arm_link"><color rgba="0.15 0.55 0.95 1"/></material></visual><collision><origin xyz="0.1 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.025" length="0.2"/></geometry></collision></link>
+<link name="forearm_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.09 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.022" length="0.18"/></geometry><material name="m_forearm_link"><color rgba="0.12 0.72 0.82 1"/></material></visual><collision><origin xyz="0.09 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.022" length="0.18"/></geometry></collision></link>
+<link name="wrist_pitch_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.045 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.018" length="0.09"/></geometry><material name="m_wrist_pitch_link"><color rgba="0.15 0.55 0.95 1"/></material></visual><collision><origin xyz="0.045 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.018" length="0.09"/></geometry></collision></link>
+<link name="wrist_yaw_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.03 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.017" length="0.06"/></geometry><material name="m_wrist_yaw_link"><color rgba="0.95 0.55 0.10 1"/></material></visual><collision><origin xyz="0.03 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.017" length="0.06"/></geometry></collision></link>
+<link name="wrist_roll_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.0275 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.016" length="0.055"/></geometry><material name="m_wrist_roll_link"><color rgba="0.15 0.55 0.95 1"/></material></visual><collision><origin xyz="0.0275 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.016" length="0.055"/></geometry></collision></link>
+<link name="tool_link"><inertial><mass value="0.08"/><inertia ixx="0.0001" ixy="0" ixz="0" iyy="0.0001" iyz="0" izz="0.0001"/></inertial><visual><origin xyz="0.025 0 0"/><geometry><box size="0.05 0.07 0.025"/></geometry><material name="tool"><color rgba="0.18 0.2 0.24 1"/></material></visual><collision><origin xyz="0.025 0 0"/><geometry><box size="0.05 0.07 0.025"/></geometry></collision></link>
+<link name="left_finger_link"><inertial><mass value="0.025"/><inertia ixx="0.00002" ixy="0" ixz="0" iyy="0.00002" iyz="0" izz="0.00002"/></inertial><visual><origin xyz="0.035 0 0"/><geometry><box size="0.07 0.012 0.018"/></geometry><material name="finger"><color rgba="0.92 0.92 0.95 1"/></material></visual><collision><origin xyz="0.035 0 0"/><geometry><box size="0.07 0.012 0.018"/></geometry></collision></link>
+<link name="right_finger_link"><inertial><mass value="0.025"/><inertia ixx="0.00002" ixy="0" ixz="0" iyy="0.00002" iyz="0" izz="0.00002"/></inertial><visual><origin xyz="0.035 0 0"/><geometry><box size="0.07 0.012 0.018"/></geometry><material name="finger2"><color rgba="0.92 0.92 0.95 1"/></material></visual><collision><origin xyz="0.035 0 0"/><geometry><box size="0.07 0.012 0.018"/></geometry></collision></link>
+<joint name="base_yaw" type="revolute"><parent link="base_link"/><child link="shoulder_link"/><origin xyz="0 0 0.08"/><axis xyz="0 0 1"/><limit lower="-3.14159" upper="3.14159" effort="45" velocity="2.5"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="shoulder_pitch" type="revolute"><parent link="shoulder_link"/><child link="upper_arm_link"/><origin xyz="0 0 0.07"/><axis xyz="0 1 0"/><limit lower="-2.35" upper="2.35" effort="45" velocity="2.5"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="elbow_pitch" type="revolute"><parent link="upper_arm_link"/><child link="forearm_link"/><origin xyz=".20 0 0"/><axis xyz="0 1 0"/><limit lower="-2.6" upper="2.6" effort="45" velocity="2.5"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="wrist_pitch" type="revolute"><parent link="forearm_link"/><child link="wrist_pitch_link"/><origin xyz=".18 0 0"/><axis xyz="0 1 0"/><limit lower="-2.6" upper="2.6" effort="45" velocity="2.5"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="wrist_yaw" type="revolute"><parent link="wrist_pitch_link"/><child link="wrist_yaw_link"/><origin xyz=".09 0 0"/><axis xyz="0 0 1"/><limit lower="-3.14159" upper="3.14159" effort="45" velocity="2.5"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="wrist_roll" type="revolute"><parent link="wrist_yaw_link"/><child link="wrist_roll_link"/><origin xyz=".06 0 0"/><axis xyz="1 0 0"/><limit lower="-3.14159" upper="3.14159" effort="45" velocity="2.5"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="tool_fixed" type="fixed"><parent link="wrist_roll_link"/><child link="tool_link"/><origin xyz=".055 0 0"/></joint>
+<joint name="left_finger" type="prismatic"><parent link="tool_link"/><child link="left_finger_link"/><origin xyz=".025 .012 0"/><axis xyz="0 1 0"/><limit lower="0" upper=".03" effort="20" velocity=".2"/></joint>
+<joint name="right_finger" type="prismatic"><parent link="tool_link"/><child link="right_finger_link"/><origin xyz=".025 -.012 0"/><axis xyz="0 -1 0"/><limit lower="0" upper=".03" effort="20" velocity=".2"/></joint>
+</robot>

jolly/assets/so101.urdf

@@ -0,0 +1,17 @@
+<?xml version="1.0"?><robot name="so101_sim">
+<link name="base_link"><inertial><mass value="0.3"/><inertia ixx="0.001" ixy="0" ixz="0" iyy="0.001" iyz="0" izz="0.001"/></inertial><visual><origin xyz="0 0 .03"/><geometry><box size=".10 .10 .06"/></geometry><material name="yellow"><color rgba="1 .72 .08 1"/></material></visual><collision><origin xyz="0 0 .03"/><geometry><box size=".10 .10 .06"/></geometry></collision></link>
+<link name="shoulder_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0 0 0.035" rpy="0 0 0"/><geometry><cylinder radius="0.022" length="0.07"/></geometry><material name="m_shoulder_link"><color rgba="1 .72 .08 1"/></material></visual><collision><origin xyz="0 0 0.035" rpy="0 0 0"/><geometry><cylinder radius="0.022" length="0.07"/></geometry></collision></link>
+<link name="upper_arm_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.0575 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.018" length="0.115"/></geometry><material name="m_upper_arm_link"><color rgba="1 .72 .08 1"/></material></visual><collision><origin xyz="0.0575 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.018" length="0.115"/></geometry></collision></link>
+<link name="lower_arm_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.0675 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.017" length="0.135"/></geometry><material name="m_lower_arm_link"><color rgba="1 .72 .08 1"/></material></visual><collision><origin xyz="0.0675 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.017" length="0.135"/></geometry></collision></link>
+<link name="wrist_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.0325 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.015" length="0.065"/></geometry><material name="m_wrist_link"><color rgba="0.12 .12 .14 1"/></material></visual><collision><origin xyz="0.0325 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.015" length="0.065"/></geometry></collision></link>
+<link name="gripper_link"><inertial><origin xyz="0 0 0"/><mass value="0.12"/><inertia ixx="0.0004" ixy="0" ixz="0" iyy="0.0004" iyz="0" izz="0.0004"/></inertial><visual><origin xyz="0.04 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.014" length="0.08"/></geometry><material name="m_gripper_link"><color rgba="1 .72 .08 1"/></material></visual><collision><origin xyz="0.04 0 0" rpy="0 1.5708 0"/><geometry><cylinder radius="0.014" length="0.08"/></geometry></collision></link>
+<link name="tool_link"><inertial><mass value=".04"/><inertia ixx=".00005" ixy="0" ixz="0" iyy=".00005" iyz="0" izz=".00005"/></inertial><visual><origin xyz=".02 0 0"/><geometry><box size=".04 .045 .02"/></geometry><material name="black"><color rgba=".1 .1 .12 1"/></material></visual><collision><origin xyz=".02 0 0"/><geometry><box size=".04 .045 .02"/></geometry></collision></link>
+<link name="moving_jaw"><inertial><mass value=".02"/><inertia ixx=".00001" ixy="0" ixz="0" iyy=".00001" iyz="0" izz=".00001"/></inertial><visual><origin xyz=".035 0 0"/><geometry><box size=".07 .012 .016"/></geometry><material name="jaw"><color rgba=".85 .85 .88 1"/></material></visual><collision><origin xyz=".035 0 0"/><geometry><box size=".07 .012 .016"/></geometry></collision></link>
+<joint name="shoulder_pan" type="revolute"><parent link="base_link"/><child link="shoulder_link"/><origin xyz="0 0 .06"/><axis xyz="0 0 1"/><limit lower="-1.91986" upper="1.91986" effort="10" velocity="10"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="shoulder_lift" type="revolute"><parent link="shoulder_link"/><child link="upper_arm_link"/><origin xyz="0 0 .065"/><axis xyz="0 1 0"/><limit lower="-1.74533" upper="1.74533" effort="10" velocity="10"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="elbow_flex" type="revolute"><parent link="upper_arm_link"/><child link="lower_arm_link"/><origin xyz=".115 0 0"/><axis xyz="0 1 0"/><limit lower="-1.69" upper="1.69" effort="10" velocity="10"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="wrist_flex" type="revolute"><parent link="lower_arm_link"/><child link="wrist_link"/><origin xyz=".135 0 0"/><axis xyz="0 1 0"/><limit lower="-1.65806" upper="1.65806" effort="10" velocity="10"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="wrist_roll" type="revolute"><parent link="wrist_link"/><child link="gripper_link"/><origin xyz=".065 0 0"/><axis xyz="1 0 0"/><limit lower="-2.74385" upper="2.84121" effort="10" velocity="10"/><dynamics damping="0.08" friction="0.02"/></joint>
+<joint name="tool_fixed" type="fixed"><parent link="gripper_link"/><child link="tool_link"/><origin xyz=".08 0 0"/></joint>
+<joint name="gripper" type="prismatic"><parent link="tool_link"/><child link="moving_jaw"/><origin xyz=".015 .01 0"/><axis xyz="0 1 0"/><limit lower="0" upper=".035" effort="10" velocity=".2"/></joint>
+</robot>

jolly/benchmark.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import math
+import time
+
+from jolly.challenges import list_challenges
+from jolly.core.models import MODELS
+from jolly.core.physics import PhysicsEngine
+
+
+def run_benchmark() -> dict[str, object]:
+    """Run deterministic engine checks, not an agent policy."""
+    checks: list[dict[str, object]] = []
+    started = time.perf_counter()
+    for model_id in MODELS:
+        case_started = time.perf_counter()
+        try:
+            with PhysicsEngine(model=model_id, scene="empty") as engine:
+                state = engine.state()
+                home = [joint["position_degrees"] for joint in state["joints"]]
+                fk = engine.forward_kinematics(home)
+                finite = all(math.isfinite(value) for value in fk["position"])
+                passed = len(home) == engine.model.dof and finite
+                checks.append(
+                    {
+                        "name": f"{model_id}:load-fk",
+                        "passed": passed,
+                        "duration_ms": round((time.perf_counter() - case_started) * 1000, 3),
+                        "metrics": {"dof": len(home), "end_effector": fk["position"]},
+                    }
+                )
+        except Exception as exc:  # benchmark reports errors instead of hiding remaining cases
+            checks.append(
+                {
+                    "name": f"{model_id}:load-fk",
+                    "passed": False,
+                    "duration_ms": round((time.perf_counter() - case_started) * 1000, 3),
+                    "error": str(exc),
+                }
+            )
+    for scene in ("blocks", "shelf", "obstacles"):
+        case_started = time.perf_counter()
+        try:
+            with PhysicsEngine(scene=scene) as engine:
+                state = engine.state()
+                checks.append(
+                    {
+                        "name": f"scene:{scene}",
+                        "passed": len(state["objects"]) > 0,
+                        "duration_ms": round((time.perf_counter() - case_started) * 1000, 3),
+                        "metrics": {"objects": len(state["objects"])},
+                    }
+                )
+        except Exception as exc:
+            checks.append(
+                {
+                    "name": f"scene:{scene}",
+                    "passed": False,
+                    "duration_ms": round((time.perf_counter() - case_started) * 1000, 3),
+                    "error": str(exc),
+                }
+            )
+    passed = sum(1 for check in checks if check["passed"])
+    return {
+        "ok": passed == len(checks),
+        "benchmark": "jolly-engine-v1",
+        "score": round(100 * passed / len(checks), 2),
+        "passed": passed,
+        "total": len(checks),
+        "duration_ms": round((time.perf_counter() - started) * 1000, 3),
+        "checks": checks,
+        "agent_challenges": list_challenges(),
+    }

jolly/challenges.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from jolly.core.errors import ConfigurationError
+
+
+@dataclass(frozen=True)
+class Challenge:
+    id: str
+    name: str
+    scene: str
+    description: str
+    success: str
+    max_commands: int
+
+
+CHALLENGES: dict[str, Challenge] = {
+    "reach-center": Challenge(
+        id="reach-center",
+        name="Reach Center",
+        scene="empty",
+        description="Move the tool to (0.35, 0.00, 0.18) without a collision.",
+        success="End-effector error <= 3 cm and no collision.",
+        max_commands=3,
+    ),
+    "sort-red": Challenge(
+        id="sort-red",
+        name="Sort Red Block",
+        scene="blocks",
+        description="Place red_block on left_target.",
+        success="Red block center is within 7 cm of the left target center.",
+        max_commands=12,
+    ),
+    "shelf-load": Challenge(
+        id="shelf-load",
+        name="Shelf Load",
+        scene="shelf",
+        description="Place cargo on the shelf surface.",
+        success="Cargo rests inside the shelf bounds above 12 cm.",
+        max_commands=14,
+    ),
+    "obstacle-reach": Challenge(
+        id="obstacle-reach",
+        name="Obstacle Reach",
+        scene="obstacles",
+        description="Reach within 7 cm of goal while remaining collision-free.",
+        success="Tool-to-goal error <= 7 cm and no collision.",
+        max_commands=10,
+    ),
+}
+
+
+def get_challenge(challenge_id: str) -> Challenge:
+    try:
+        return CHALLENGES[challenge_id]
+    except KeyError as exc:
+        available = ", ".join(sorted(CHALLENGES))
+        raise ConfigurationError(f"Unknown challenge '{challenge_id}'. Available: {available}") from exc
+
+
+def list_challenges() -> list[dict[str, object]]:
+    return [vars(CHALLENGES[key]) for key in sorted(CHALLENGES)]
+
+
+def evaluate(challenge_id: str, state: dict[str, object]) -> dict[str, object]:
+    challenge = get_challenge(challenge_id)
+    if state.get("scene") != challenge.scene:
+        raise ConfigurationError(
+            f"Challenge '{challenge_id}' requires scene '{challenge.scene}', not '{state.get('scene')}'. "
+            f"Run 'jolly challenge start {challenge_id}'."
+        )
+    ee = state["end_effector"]["position"]
+    objects = {item["name"]: item for item in state.get("objects", [])}
+    collision = bool(state["collisions"]["collision"])
+    metrics: dict[str, object]
+    success = False
+    if challenge_id == "reach-center":
+        error = math.dist(ee, [0.35, 0.0, 0.18])
+        success = error <= 0.03 and not collision
+        metrics = {"target_error_meters": round(error, 6), "collision_free": not collision}
+    elif challenge_id == "sort-red":
+        position = objects["red_block"]["position"]
+        error = math.dist(position[:2], [0.16, -0.27])
+        success = error <= 0.07 and position[2] <= 0.09
+        metrics = {"target_xy_error_meters": round(error, 6), "block_height_meters": position[2]}
+    elif challenge_id == "shelf-load":
+        position = objects["cargo"]["position"]
+        inside = 0.16 <= position[0] <= 0.40 and 0.10 <= position[1] <= 0.26
+        success = inside and position[2] >= 0.12
+        metrics = {"inside_shelf_xy": inside, "cargo_height_meters": position[2]}
+    else:
+        goal = objects["goal"]["position"]
+        error = math.dist(ee, goal)
+        success = error <= 0.07 and not collision
+        metrics = {"goal_error_meters": round(error, 6), "collision_free": not collision}
+    command_count = int(state.get("challenge_commands", 0))
+    within_budget = command_count <= challenge.max_commands
+    success = success and within_budget
+    metrics["commands"] = command_count
+    metrics["within_command_budget"] = within_budget
+    return {
+        "ok": True,
+        "challenge": vars(challenge),
+        "success": success,
+        "score": 100 if success else 0,
+        "metrics": metrics,
+    }

jolly/cli.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from jolly import __version__
+from jolly.benchmark import run_benchmark
+from jolly.challenges import evaluate, get_challenge, list_challenges
+from jolly.core.errors import ConfigurationError, JollyError
+from jolly.core.models import get_model, list_models
+from jolly.core.physics import PhysicsEngine
+from jolly.core.scenes import get_scene, list_scenes
+from jolly.core.store import load_state, save_state, state_lock
+
+console = Console()
+
+
+def emit(data: Any, *, json_output: bool, message: str | None = None) -> None:
+    if json_output:
+        click.echo(json.dumps(data, indent=2, sort_keys=True))
+    elif message:
+        click.echo(message)
+    elif isinstance(data, dict):
+        click.echo(json.dumps(data, indent=2, sort_keys=True))
+    else:
+        click.echo(str(data))
+
+
+def parse_joints(_: click.Context, __: click.Parameter, value: str | None) -> list[float] | None:
+    if value is None:
+        return None
+    try:
+        values = [float(part.strip()) for part in value.split(",") if part.strip()]
+    except ValueError as exc:
+        raise click.BadParameter("Use comma-separated numbers in degrees.") from exc
+    if not values:
+        raise click.BadParameter("Provide at least one joint angle.")
+    return values
+
+
+@contextmanager
+def current_engine(
+    *, model: str | None = None, scene: str | None = None, gui: bool = False, recover: bool = False
+) -> Iterator[PhysicsEngine]:
+    with state_lock():
+        try:
+            saved = load_state()
+        except ConfigurationError:
+            if not recover:
+                raise
+            saved = None
+        selected_model = model or (str(saved["model"]["id"]) if saved else "jolly6")
+        selected_scene = scene or (str(saved.get("scene", "empty")) if saved else "empty")
+        with PhysicsEngine(model=selected_model, scene=selected_scene, gui=gui, realtime=gui) as engine:
+            if saved and saved.get("model", {}).get("id") == selected_model and saved.get("scene") == selected_scene:
+                engine.restore(saved)
+            yield engine
+
+
+def persist(
+    engine: PhysicsEngine,
+    *,
+    extra: dict[str, object] | None = None,
+    count_challenge_command: bool = False,
+) -> dict[str, object]:
+    state = engine.state()
+    previous = load_state() or {}
+    if "active_challenge" in previous:
+        state["active_challenge"] = previous["active_challenge"]
+        state["challenge_commands"] = int(previous.get("challenge_commands", 0)) + int(count_challenge_command)
+    if extra:
+        state.update(extra)
+    save_state(state)
+    return state
+
+
+def json_error(exc: Exception) -> str:
+    return json.dumps({"ok": False, "error": {"type": exc.__class__.__name__, "message": str(exc)}}, sort_keys=True)
+
+
+class SafeGroup(click.Group):
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        ctx.meta["json_requested"] = "--json" in args or os.environ.get("JOLLY_JSON") == "1"
+        return super().parse_args(ctx, args)
+
+    def invoke(self, ctx: click.Context) -> Any:
+        try:
+            return super().invoke(ctx)
+        except JollyError as exc:
+            if ctx.meta.get("json_requested"):
+                click.echo(json_error(exc))
+                ctx.exit(2)
+            raise click.ClickException(str(exc)) from exc
+
+
+@click.group(cls=SafeGroup, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__)
+def main() -> None:
+    """Jolly: local robot-arm physics for terminal users and LLM agents."""
+
+
+@main.command("models")
+@click.option("json_output", "--json", is_flag=True, help="Return structured JSON.")
+def models_command(json_output: bool) -> None:
+    """List bundled robot models."""
+    data = {"ok": True, "models": list_models()}
+    if json_output:
+        emit(data, json_output=True)
+        return
+    table = Table(title="Jolly robot models")
+    table.add_column("ID")
+    table.add_column("DOF", justify="right")
+    table.add_column("Name")
+    table.add_column("License")
+    for model in data["models"]:
+        table.add_row(str(model["id"]), str(model["dof"]), str(model["name"]), str(model["license"]))
+    console.print(table)
+
+
+@main.command("state")
+@click.option("model", "--model", type=click.Choice([item["id"] for item in list_models()]))
+@click.option("json_output", "--json", is_flag=True, help="Return structured JSON.")
+def state_command(model: str | None, json_output: bool) -> None:
+    """Return joints, tool pose, objects, and collisions."""
+    with current_engine(model=model) as engine:
+        data = persist(engine)
+    emit(data, json_output=json_output, message=f"{data['model']['name']}: tool={data['end_effector']['position']} collision={data['collisions']['collision']}")
+
+
+@main.command("move")
+@click.option("joints", "--joints", required=True, callback=parse_joints, help="Comma-separated joint angles in degrees.")
+@click.option("gripper", "--gripper", type=click.FloatRange(0.0, 1.0))
+@click.option("steps", "--steps", type=click.IntRange(1, 2400), default=120, show_default=True)
+@click.option("allow_collision", "--allow-collision", is_flag=True, help="Do not roll back a colliding motion.")
+@click.option("json_output", "--json", is_flag=True, help="Return structured JSON.")
+def move_command(joints: list[float], gripper: float | None, steps: int, allow_collision: bool, json_output: bool) -> None:
+    """Move to exact joint angles."""
+    with current_engine() as engine:
+        data = engine.move_joints(joints, gripper=gripper, steps=steps, allow_collision=allow_collision)
+        data = persist(
+            engine,
+            extra={"ik": data.get("ik")} if data.get("ik") else None,
+            count_challenge_command=True,
+        )
+    emit(data, json_output=json_output, message=f"Moved {len(joints)} joints. Tool={data['end_effector']['position']}")
+
+
+@main.command("reach")
+@click.option("x", "--x", required=True, type=float)
+@click.option("y", "--y", required=True, type=float)
+@click.option("z", "--z", required=True, type=float)
+@click.option("gripper", "--gripper", type=click.FloatRange(0.0, 1.0))
+@click.option("steps", "--steps", type=click.IntRange(1, 2400), default=160, show_default=True)
+@click.option("allow_collision", "--allow-collision", is_flag=True)
+@click.option("json_output", "--json", is_flag=True, help="Return structured JSON.")
+def reach_command(x: float, y: float, z: float, gripper: float | None, steps: int, allow_collision: bool, json_output: bool) -> None:
+    """Solve inverse kinematics and move the tool."""
+    with current_engine() as engine:
+        data = engine.reach(x, y, z, gripper=gripper, steps=steps, allow_collision=allow_collision)
+        ik = data["ik"]
+        data = persist(engine, extra={"ik": ik}, count_challenge_command=True)
+    emit(data, json_output=json_output, message=f"Reached {data['end_effector']['position']} with {data['ik']['error_meters']:.4f} m error.")
+
+
+@main.command("fk")
+@click.option("joints", "--joints", callback=parse_joints, help="Optional comma-separated angles in degrees.")
+@click.option("json_output", "--json", is_flag=True)
+def fk_command(joints: list[float] | None, json_output: bool) -> None:
+    """Compute forward kinematics without changing saved state."""
+    with current_engine() as engine:
+        data = {"ok": True, "model": engine.model.id, "forward_kinematics": engine.forward_kinematics(joints)}
+    emit(data, json_output=json_output)
+
+
+@main.command("reset")
+@click.option("model", "--model", type=click.Choice([item["id"] for item in list_models()]), default="jolly6")
+@click.option("scene", "--scene", type=click.Choice([item["id"] for item in list_scenes()]), default="empty")
+@click.option("json_output", "--json", is_flag=True)
+def reset_command(model: str, scene: str, json_output: bool) -> None:
+    """Reset the world and home the selected robot."""
+    with current_engine(model=model, scene=scene, recover=True) as engine:
+        data = engine.reset()
+        save_state(data)
+    emit(data, json_output=json_output, message=f"Reset {model} in scene '{scene}'.")
+
+
+@main.command("render")
+@click.option("json_output", "--json", is_flag=True, help="Return pose points instead of a table.")
+def render_command(json_output: bool) -> None:
+    """Render a compact terminal status table and stick figure."""
+    with current_engine() as engine:
+        state = engine.state()
+        points = engine.joint_positions()
+        state = persist(engine)
+    if json_output:
+        emit({"ok": True, "state": state, "skeleton_points": points}, json_output=True)
+        return
+    table = Table(title=f"Jolly · {state['model']['name']} · {state['scene']}")
+    table.add_column("Joint")
+    table.add_column("Angle", justify="right")
+    table.add_column("Limits", justify="right")
+    for joint in state["joints"]:
+        limits = joint["limits_degrees"]
+        table.add_row(joint["name"], f"{joint['position_degrees']:.2f}°", f"{limits[0]:.0f}° … {limits[1]:.0f}°")
+    console.print(table)
+    ee = state["end_effector"]["position"]
+    collision = "COLLISION" if state["collisions"]["collision"] else "clear"
+    console.print(f"base ●──●──●──●──●──◆ tool  xyz=({ee[0]:.3f}, {ee[1]:.3f}, {ee[2]:.3f})")
+    console.print(f"gripper={state['gripper']:.2f}  held={state['held_object'] or 'none'}  collision={collision}")
+
+
+@main.group("scene")
+def scene_group() -> None:
+    """List or load simulation scenes."""
+
+
+@scene_group.command("list")
+@click.option("json_output", "--json", is_flag=True)
+def scene_list_command(json_output: bool) -> None:
+    data = {"ok": True, "scenes": list_scenes()}
+    emit(data, json_output=json_output)
+
+
+@scene_group.command("load")
+@click.argument("scene_id", type=click.Choice([item["id"] for item in list_scenes()]))
+@click.option("json_output", "--json", is_flag=True)
+def scene_load_command(scene_id: str, json_output: bool) -> None:
+    get_scene(scene_id)
+    saved = load_state()
+    model = str(saved["model"]["id"]) if saved else "jolly6"
+    with current_engine(model=model, scene=scene_id) as engine:
+        data = engine.reset()
+        save_state(data)
+    emit(data, json_output=json_output, message=f"Loaded scene '{scene_id}'.")
+
+
+@main.group("challenge")
+def challenge_group() -> None:
+    """Run repeatable manipulation challenges."""
+
+
+@challenge_group.command("list")
+@click.option("json_output", "--json", is_flag=True)
+def challenge_list_command(json_output: bool) -> None:
+    emit({"ok": True, "challenges": list_challenges()}, json_output=json_output)
+
+
+@challenge_group.command("start")
+@click.argument("challenge_id", type=click.Choice([item["id"] for item in list_challenges()]))
+@click.option("model", "--model", type=click.Choice([item["id"] for item in list_models()]), default="jolly6")
+@click.option("json_output", "--json", is_flag=True)
+def challenge_start_command(challenge_id: str, model: str, json_output: bool) -> None:
+    challenge = get_challenge(challenge_id)
+    with current_engine(model=model, scene=challenge.scene) as engine:
+        state = engine.reset()
+        state["active_challenge"] = challenge_id
+        state["challenge_commands"] = 0
+        save_state(state)
+    emit({"ok": True, "challenge": vars(challenge), "state": state}, json_output=json_output, message=f"Started '{challenge.name}' in scene '{challenge.scene}'.")
+
+
+@challenge_group.command("status")
+@click.option("challenge_id", "--challenge", type=click.Choice([item["id"] for item in list_challenges()]))
+@click.option("json_output", "--json", is_flag=True)
+def challenge_status_command(challenge_id: str | None, json_output: bool) -> None:
+    saved = load_state() or {}
+    selected = challenge_id or saved.get("active_challenge")
+    if not selected:
+        raise ConfigurationError("No active challenge. Run 'jolly challenge start ID'.")
+    with current_engine() as engine:
+        state = persist(engine)
+    data = evaluate(str(selected), state)
+    emit(data, json_output=json_output, message=f"{data['challenge']['name']}: {'PASS' if data['success'] else 'IN PROGRESS'} · score={data['score']}")
+
+
+@main.command("benchmark")
+@click.option("json_output", "--json", is_flag=True)
+def benchmark_command(json_output: bool) -> None:
+    """Run the deterministic local engine benchmark."""
+    data = run_benchmark()
+    emit(data, json_output=json_output, message=f"Benchmark score: {data['score']:.1f}/100 ({data['passed']}/{data['total']} checks)")
+
+
+@main.command("viewer")
+@click.option("model", "--model", type=click.Choice([item["id"] for item in list_models()]))
+@click.option("scene", "--scene", type=click.Choice([item["id"] for item in list_scenes()]))
+def viewer_command(model: str | None, scene: str | None) -> None:
+    """Open the native PyBullet 3D window."""
+    with current_engine(model=model, scene=scene, gui=True) as engine:
+        click.echo("Viewer opened. Close the PyBullet window to exit.")
+        engine.run_viewer()
+
+
+@main.command("serve")
+@click.option("host", "--host", default="127.0.0.1", show_default=True)
+@click.option("port", "--port", type=click.IntRange(1, 65535), default=8765, show_default=True)
+@click.option("unsafe_public", "--unsafe-public", is_flag=True, help="Allow a non-loopback bind without authentication.")
+def serve_command(host: str, port: int, unsafe_public: bool) -> None:
+    """Start the optional local web viewer and JSON API."""
+    if host not in {"127.0.0.1", "localhost", "::1"} and not unsafe_public:
+        raise click.ClickException("Non-loopback web control requires explicit --unsafe-public.")
+    try:
+        import uvicorn
+    except ImportError as exc:
+        raise click.ClickException("Install web support with: pip install 'jolly-cli[web]'") from exc
+    uvicorn.run("jolly.web.app:app", host=host, port=port, reload=False)
+
+
+if __name__ == "__main__":
+    main()

jolly/core/__init__.py

@@ -0,0 +1 @@
+"""Physics and simulation primitives for Jolly."""

jolly/core/errors.py

@@ -0,0 +1,10 @@
+class JollyError(Exception):
+    """Base error that can be safely returned to CLI clients."""
+
+
+class ConfigurationError(JollyError):
+    """Raised for an invalid robot or scene configuration."""
+
+
+class MotionError(JollyError):
+    """Raised when a requested motion is invalid or unsafe."""