#!/usr/bin/env python3 """Inspect, build, calibrate and verify new robot inputs.""" from __future__ import annotations import argparse import sys from pathlib import Path from typing import Any from mjrl.onboarding._report import atomic_write, json_text, read_object def _parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser(description=__doc__) commands = parser.add_subparsers(dest="command", required=True) inspect = commands.add_parser( "inspect", help="inventory robot inputs and recommend an intake tier" ) inspect.add_argument("source", type=Path, help="file or directory to inspect") inspect.add_argument("--profile", type=Path, help="declarative JSON robot profile") inspect.add_argument("--mesh-root", type=Path, help="alternate URDF mesh or package directory") inspect.add_argument("--policy", type=Path, help="select a policy file") inspect.add_argument("--metadata", type=Path, help="select reviewed metadata or upstream config") build = commands.add_parser("build-mjcf", help="build MJCF from a robot model or mesh") build.add_argument("source", type=Path, help="URDF, MJCF, STL, OBJ, MSH, or asset directory") build.add_argument("--output", "--out", required=True, type=Path, help="destination XML") build.add_argument("--floating-base", action="store_true", help="add a free URDF root joint") build.add_argument("--mesh-root", type=Path) build.add_argument( "--visual-fallback", action="store_true", help="create collision geoms where URDF provides visuals only", ) build.add_argument( "--mesh-scale", type=float, default=1.0, help="standalone mesh scale to metres (default 1)" ) build.add_argument( "--collision-hull-dirs", type=int, default=64, help="fallback mesh hull sampling directions (default 64; 0 keeps the full hull)", ) build.add_argument( "--collision-hull-exclude", action="append", default=[], metavar="MESH", help="preserve a fallback mesh, e.g. a support surface; repeat for multiple meshes", ) build.add_argument("--replace", action="store_true", help="replace an existing destination XML") calibrate = commands.add_parser("calibrate", help="refine a stance and measure native PD hold") verify = commands.add_parser( "verify", help="measure native dynamics and actual control response" ) setup = commands.add_parser("setup-tier2", help="prepare a deterministic simulation controller") for command in (calibrate, verify, setup): command.add_argument("--model", required=True, type=Path, help="input MJCF XML") command.add_argument("--config", required=True, type=Path, help="JSON configuration") setup.add_argument("--output", "--out", required=True, type=Path, help="output directory") extract = commands.add_parser("extract-tier1", help="extract and review upstream policy metadata") extract.add_argument("configs", nargs="*", type=Path, help="YAML, JSON or Python training configs; omit with --model for facts only") extract.add_argument("--output", "--out", required=True, type=Path, help="new draft directory") extract.add_argument("--model", type=Path, help="MJCF model for metadata validation") extract.add_argument("--overrides", type=Path, help="reviewed JSON/YAML field overrides") adapt = commands.add_parser("adapt-tier1", help="adapt a policy using reviewed or upstream metadata") adapt.add_argument("source", type=Path, help="policy graph") inputs = adapt.add_mutually_exclusive_group(required=True) inputs.add_argument("--metadata", type=Path, help="reviewed JSON/YAML policy metadata") inputs.add_argument("--config", action="append", type=Path, help="upstream config; repeat to combine") adapt.add_argument("--overrides", type=Path, help="reviewed JSON/YAML overrides for --config") adapt.add_argument( "--model", type=Path, help="MJCF model to check joint names and limits against" ) adapt.add_argument("--output", "--out", required=True, type=Path, help="output directory") scaffold = commands.add_parser( "scaffold-tier3", help="write a literal legged robot specification" ) scaffold.add_argument("--config", required=True, type=Path, help="JSON RobotSpec") scaffold.add_argument("--calibration", type=Path, help="reuse a passing calibration report") scaffold.add_argument("--tasks-root", type=Path, help="destination tasks directory") for command in (inspect, build, calibrate, verify, setup, extract, adapt, scaffold): command.add_argument("--report", type=Path, help="write the JSON report to a new file") return parser def _run(args: argparse.Namespace) -> dict[str, Any]: if args.command == "inspect": from mjrl.onboarding import inspect_asset profile = read_object(args.profile) if args.profile else None return inspect_asset( args.source, profile=profile, mesh_root=args.mesh_root, policy=args.policy, policy_metadata=args.metadata, ) if args.command == "build-mjcf": from mjrl.onboarding import build_mjcf return build_mjcf( args.source, args.output, floating_base=args.floating_base, mesh_root=args.mesh_root, visual_fallback=args.visual_fallback, collision_hull_dirs=args.collision_hull_dirs, collision_hull_exclude=tuple(args.collision_hull_exclude), mesh_scale=args.mesh_scale, replace=args.replace, ) if args.command == "calibrate": from mjrl.onboarding import calibrate_model return calibrate_model(args.model, read_object(args.config)) if args.command == "verify": from mjrl.onboarding import verify_model return verify_model( args.model, read_object(args.config), base_dir=args.config.resolve().parent ) if args.command == "setup-tier2": from mjrl.controllers import setup_controller setup = setup_controller(args.model, args.config, args.output) return { "schema": "mjrl.onboarding.setup/1", "model": str(setup.model), "config": str(setup.config), "controls": str(setup.controls) if setup.controls else None, } if args.command in {"extract-tier1", "adapt-tier1"}: model = None if args.model: from mjrl.onboarding._physics import load_spec model = load_spec(args.model).compile() overrides = None if args.overrides: from mjrl.onboarding.upstream import load_overrides if args.command == "adapt-tier1" and args.metadata: raise ValueError("--overrides requires --config; review --metadata directly") overrides = load_overrides(args.overrides) if args.command == "extract-tier1": from mjrl.onboarding.policy_intake import extract_to_directory return extract_to_directory(args.configs, args.output, overrides=overrides, model=model) if args.config: from mjrl.onboarding.policy_intake import adapt_from_configs return adapt_from_configs(args.source, args.config, args.output, overrides=overrides, model=model) from mjrl.adapter import adapt_policy policy = adapt_policy(args.source, args.metadata, args.output, model=model) return { "schema": "mjrl.onboarding.adapt/1", "layout": str(policy.layout), "actor": str(policy.actor), "config": str(policy.config), "controls": str(policy.controls) if policy.controls else None, "max_abs_error": policy.max_abs_error, } from mjrl.onboarding import scaffold_task return scaffold_task( read_object(args.config), base_dir=args.config.resolve().parent, calibration=read_object(args.calibration) if args.calibration else None, tasks_root=args.tasks_root, ) def main(argv: list[str] | None = None) -> int: args = _parser().parse_args(argv) try: if args.report is not None and args.report.exists(): raise FileExistsError(f"report already exists: {args.report}") report = _run(args) code = int(report.get("passed", True) is False) except (ImportError, OSError, RuntimeError, TypeError, ValueError) as exc: print(f"{args.command}: {exc}", file=sys.stderr) return 1 try: result = json_text(report) if args.report: atomic_write(args.report, result) except (OSError, ValueError) as exc: print(f"{args.command}: {exc}", file=sys.stderr) return 1 print(result, end="") return code if __name__ == "__main__": raise SystemExit(main())