pyros-robotics 1.0.0

Validation, repair, and forensics toolchain for ROS 2 workspaces

pyros

Pyros isn't an AI assistant for robotics engineers. Pyros is the robotics engineer.

Give it a workspace, a CAD export, or a bug. It owns the iteration loop — validate, repair, simulate, build — until the output ships. You review the artifact. Pyros writes it.

$ pyros run "fix examples/broken_arm_ws"
  ✓  scan          1 URDF found
  ✗  validate-urdf 4 errors
  ✓  fix-urdf      2 auto-repaired → robot_fixed.urdf
  ✓  validate-urdf 0 errors      ← convergence
  ✓  colcon-build  passed

artifact: .pyros/runs/run-2026-04-29T11-29-56.json
duration: 0.22s

Install

pip install pyros-robotics

Use it from any agent (Claude Desktop, Cursor, Windsurf, Claude Code)

Pyros ships an MCP server. Every primitive — validate_urdf, fix_urdf, run, ci, analyze_bag, scan_logs, diagnose_qos, build_explain, launch_graph, urdf_diff, controllers_from_urdf — is callable from any MCP-aware agent.

Add to your client's MCP config:

{
  "mcpServers": {
    "pyros": { "command": "pyros-mcp" }
  }
}

Then in your agent: "Fix the URDFs in ~/work/robot_ws and ship a clean build." The agent calls pyros.run, which drives the full validate → fix → build loop and returns a structured report.

Drop into CI

Copy templates/github-actions/pyros-ci.yml to .github/workflows/pyros-ci.yml. Pyros will run on every PR, validate every URDF, comment the verdict on the PR, and upload reports as workflow artifacts. Exit codes propagate, so failing checks block the merge.

name: pyros-ci
on: [pull_request]
jobs:
  pyros:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install pyros-robotics
      - run: pyros ci --json --skip-build > pyros-ci.json

What it does (no LLM required)

# Repair a CAD-exported URDF (zero/missing inertias, wrong mesh paths, joint limits)
pyros fix-urdf robot.urdf --package my_robot_description

# Deep-validate a URDF: kinematic, dynamic, geometry, control checks
pyros validate-urdf robot.urdf
pyros validate-urdf robot.urdf --json   # for CI pipelines

# Run all health checks against a workspace (doctor + URDFs + colcon + log scan)
pyros ci -w ./my_robot_ws
pyros ci -w ./my_robot_ws --json > report.json

# Launch MuJoCo viewer offline (no auth, no LLM, no network)
pyros sim-offline -w ./my_robot_ws

# Forensics on running / past systems
pyros doctor                 # environment health
pyros analyze-bag run.mcap   # rosbag2 summary
pyros scan-logs              # ~/.ros/log error scanner
pyros diagnose-qos           # DDS/QoS mismatch checks
pyros build-explain          # colcon errors → plain English

# Workspace introspection
pyros launch-graph my_pkg/launch/sim.launch.py
pyros graph -w ./my_robot_ws

Exit codes for validate-urdf and ci: 0 clean, 1 warnings, 2 errors. Both emit JSON with --json so they drop into GitHub Actions / GitLab CI directly.

What it does (LLM optional)

# Generate a workspace from a description
pyros                                          # interactive TUI
pyros ask "build a 6-DOF arm with vacuum gripper"

Set ANTHROPIC_API_KEY or OPENAI_API_KEY to enable. Without keys, generation falls back to a deterministic builder that handles common robot types.

Why not just use ChatGPT or Claude?

Task	Chat LLM	Pyros
Write a URDF from a description	✓	✓ (with validation loop)
Detect non-positive-definite inertia tensor	✗	✓
Repair zero-mass links and bad mesh paths in your file	✗	✓ (fix-urdf)
Run colcon build and translate the errors	✗	✓ (build-explain)
Read your running ROS system / DDS state	✗	✓ (diagnose-qos, doctor)
Sit in a CI pipeline with exit codes and JSON	✗	✓ (ci)
Scan rosbags for frequency drops and gaps	✗	✓ (analyze-bag)

Pyros works on the file on disk, the bag on disk, the build output, and the running system. It is a toolchain, not a chat wrapper.

Status

Beta — API stable, used in production by early teams. Report issues at https://github.com/anthropics/pyros.

License

Apache-2.0