Metadata-Version: 2.5
Name: pyros-robotics
Version: 2.0.0
Summary: A local, cited robotics engineering co-pilot for ROS 2 — kinematics, IK, motor sizing, control & planner selection, ros2_control, BOM, and power budgeting.
Author: Pyros Team
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agent,cli,kinematics,mcp,motion-planning,motor-sizing,robotics,robotics-engineering,ros2,ros2-control,urdf
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.25
Requires-Dist: click>=8.1
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: lxml>=4.9
Requires-Dist: matplotlib>=3.8
Requires-Dist: mcp<2,>=1.0
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: openai>=1.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=1.0
Requires-Dist: trimesh>=3.20
Provides-Extra: all
Requires-Dist: mujoco>=3.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: robot-descriptions>=1.9; extra == 'all'
Requires-Dist: ruamel-yaml>=0.18; extra == 'all'
Requires-Dist: scikit-optimize>=0.9; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: jsonschema>=4.0; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-timeout; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: mujoco
Requires-Dist: mujoco>=3.0; extra == 'mujoco'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: robots
Requires-Dist: robot-descriptions>=1.9; extra == 'robots'
Provides-Extra: tuning-v2
Requires-Dist: scikit-optimize>=0.9; extra == 'tuning-v2'
Provides-Extra: yaml-preserve
Requires-Dist: ruamel-yaml>=0.18; extra == 'yaml-preserve'
Description-Content-Type: text/markdown

# pyros

[![CI](https://github.com/RudranshG07/pyros/actions/workflows/ci.yml/badge.svg)](https://github.com/RudranshG07/pyros/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pyros-robotics)](https://pypi.org/project/pyros-robotics/)
[![Python](https://img.shields.io/pypi/pyversions/pyros-robotics)](https://pypi.org/project/pyros-robotics/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

**Claude Code for robotics engineers.** A local, ROS-native co-pilot that does
the engineering a generic LLM can't fake — sizes the motor, picks the
controller *with gain numbers*, solves the kinematics, generates valid
ros2_control, budgets the battery — and cites a textbook for every answer.

A deep, growing set of deterministic engineering tools an agent orchestrates. Not a chat
wrapper: the numbers come from real computation over a real parts catalog, so
they're reproducible and you can check the source. Pure Python — `pip install`
and go.

```bash
$ pyros size-actuator --peak 5 --rms 2 --speed-rpm 30

  ✓ 71 candidate(s) pass — top pick:
      T-Motor U8 II + planetary 25:1 (η=90%)
      peak margin 92% · thermal 90% · 0.24 kg
  Sizing checks peak (80% stall safety), RMS thermal limit, the
  torque-speed curve at the operating point, and mass budget.
```

Or just talk to it — it orchestrates the tools into a cited design:

```
$ pyros
> design the actuation for a 6-DOF arm that lifts 2 kg

  ● compute_kinematics   reach + manipulability + where the singularities are
  ● static_torques       gravity holding torque per joint (m·g·L, validated)
  ● size_actuator        motor + gearbox from the catalog, with margins
  ● select_controller    computed-torque — Spong §8.2 — with PID gain seeds
  ● power_budget         battery (Wh), discharge C-rating, fuse/bus

  Every number above came from a tool, not the model's memory.
```

## Install

```bash
pip install "pyros-robotics[all]"
```

Then `pyros login`. Sign-in is a browser flow (like `gh auth login`) — it prints
a URL and a short code, you approve in the browser with your Google account, and
on success you land straight in the interactive workspace. Pass
`pyros login --no-workspace` to just sign in without opening the workspace.

Want an isolated install that puts `pyros` on your PATH without touching
your global Python? The bootstrap scripts do that (they pip-install the
same wheel into their own venv under `~/.pyros`) — no Node, no npm:

```bash
# macOS / Linux
curl -fsSL https://getpyros.com/install.sh | bash

# Windows (PowerShell)
irm https://getpyros.com/install.ps1 | iex
```

That's the whole path: **install → `pyros login` (sign in with Google) →
workspace**, one step after another.

```bash
# Design your OWN robot from a spec — writes a usable, dynamics-ready URDF:
pyros design-arm --dof 6 --payload 5 --reach 0.8
# → 12.8 kg anthropomorphic arm; shoulder needs 115 N·m for a 5 kg move

# Or load a REAL robot (real CAD meshes) and engineer it:
pyros load-robot panda          # Franka Panda — or ur5e, ur10e
# → reach 1.27 m · κ(J)=10.2 · joint2 worst-case 56 N·m (65% of its 87 N·m rating)
pyros load-robot panda --sim    # …and open it in the MuJoCo 3D viewer

# Or the 60-second tour of the engineering tools:
pyros robotics-demo             # → 17 cited artifacts in ./pyros-demo-output
```

## Robotics engineering tools — compute, don't guess

Deterministic tools that out-reason any LLM-only assistant on the math
a robotics engineer actually does. Every recommendation cites a textbook.

### `compute_kinematics` &nbsp;·&nbsp; *Lynch & Park §5, Yoshikawa IJRR 1985*
Auto-discovers your URDF, builds the kinematic chain, returns forward
kinematics, the 6×n geometric Jacobian, Yoshikawa manipulability w(q), and
condition number κ(J). Singularities surfaced before the plan blows up.

### `compute_ik` &nbsp;·&nbsp; *damped least squares; Nakamura & Hanafusa 1986*
The complement to FK: solve joint angles for a target tip position via
Levenberg–Marquardt, with joint-limit projection. Reports reachability,
residual error, and manipulability at the solution.

### `analyze_workspace` &nbsp;·&nbsp; *Monte-Carlo reachability*
Samples the joint space to report max reach, the reachable envelope and
volume, and a global dexterity measure (mean manipulability + near-singular
fraction). Reproducible for a fixed seed.

### `static_torques` &nbsp;·&nbsp; *gravity term g(q); validated vs m·g·L*
Per-joint holding torque/force against gravity from link masses — the
dominant *static* input to motor sizing. Feeds `size_actuator` / `generate_bom`
real numbers instead of a guessed effort limit.

### `compute_dynamics` &nbsp;·&nbsp; *recursive Newton–Euler; Craig §6 / Featherstone*
The torque to *move*, not just hold: the full manipulator equation
τ = M(q)q̈ + C(q,q̇)q̇ + g(q), broken into gravity / inertial / Coriolis per
joint. Captures the off-diagonal inertial coupling (accelerating one joint
loads the others) that gravity-only sizing misses on fast or light arms.
Validated against the single-pendulum closed form and the static gravity term.
Its sizing application, `size_for_move`, reports the **worst-case dynamic
torque** per joint for a given acceleration + payload — e.g. a Franka joint 2
needs ~166 N·m for an 8 rad/s² move with 3 kg, **double** the gravity-only
number that static sizing would (under-)spec.

### `size_actuator` &nbsp;·&nbsp; *real datasheet catalog*
Motor × gearbox × ratio trade study across 10 motors (Maxon EC-i 40, Faulhaber
2237, T-Motor U8 II, ODrive D5065, Dynamixel XM430/XH540, RMD-X6, MKS NEMA17,
Moog BN23) and 3 gearbox families. Checks peak (with 80% stall safety),
RMS-thermal limit, torque-speed curve at the operating point, mass budget.
PNG of torque-speed curves for the slide deck.

### `select_controller` &nbsp;·&nbsp; *PID gain seeds from pole placement*
Picks across PID, computed-torque, impedance (Hogan 1985), admittance, hybrid
force/position (Raibert & Craig 1981), LQR, MPC, sliding-mode, feedforward+PID.
For PID picks, computes Kp/Ki/Kd from second-order pole placement at your
desired ω_n and ζ — actual starting numbers, not "tune it yourself".

### `select_planner` &nbsp;·&nbsp; *10-dimension trade study*
RRT vs RRT-Connect vs RRT* vs BIT* vs PRM vs Lazy-PRM vs A* vs Hybrid-A* vs
CHOMP vs STOMP vs TrajOpt. For a 6-DOF arm doing single-query feasibility it
says RRT-Connect (OMPL default). For an Ackermann car: Hybrid-A* (what Apollo
and Autoware use). For a 7-DOF arm in narrow passages with asymptotic-optimal:
BIT*. Cited to Karaman/Frazzoli, Kuffner/LaValle, Gammell et al., Dolgov et al.

### `generate_ros2_control` &nbsp;·&nbsp; *zero drift*
One URDF in, three files out that MUST agree or your robot won't move: the
`<ros2_control>` XML block, `controllers.yaml` with controller_manager and
REP-2014 QoS overrides, and a ROS 2 lifecycle launcher with the right spawn
order. Mock / Gazebo / real-hardware presets.

### `explain_concept` &nbsp;·&nbsp; *33 cited topics*
Curated textbook lookup with TL;DR + math + key insight + pitfalls + citation.
Coverage spans SE(3), Rodrigues, FK/IK, Jacobian, manipulability, singularities,
PID, computed-torque, impedance, admittance, hybrid F/P, LQR, MPC, RRT family,
A* family, EKF, UKF, particle filter, SLAM, ICP, hand-eye calibration, pinhole
camera, URDF anatomy, ros2_control, DDS QoS, tf2/REP-105, lifecycle nodes,
trajectory profiles, inverse dynamics. Not LLM-synthesized — every formula was
author-checked.

### `generate_bom` &nbsp;·&nbsp; *parts list from a URDF*
Sizes an actuator for every joint from its effort/velocity limits — rotary
(motor + gearbox) and prismatic (rotary motor + lead screw) — then emits a
bill of materials: parts, total mass, and a safety-aware wiring/build
checklist (e-stop, power-bus sizing, encoders). Design → procurement.

### `power_budget` &nbsp;·&nbsp; *battery + bus sizing*
From the sized actuators, estimates peak and continuous current/power, then
recommends a battery (Wh/Ah), minimum discharge C-rating, and fuse/bus
rating for a target runtime. Flags mixed-voltage rails. Design → power.

All twelve are also exposed via MCP — drop into Claude Desktop / Cursor /
Windsurf and any agent can drive them.

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

Pyros ships an MCP server, so the engineering brain is available *inside* the
agent you already use. All twelve robotics tools — `kinematics`,
`inverse_kinematics`, `analyze_workspace`, `static_torques`, `compute_dynamics`,
`size_actuator`, `select_controller`, `select_planner`, `generate_ros2_control`,
`generate_bom`, `power_budget`, `explain_concept` — plus the workspace primitives
(`validate_urdf`, `fix_urdf`, `ci`, …) are callable from any MCP-aware client.

Add to your client's MCP config:

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

Then in Claude Desktop / Cursor / Windsurf: *"Size the actuators for the arm
in `~/work/robot_ws` and pick a controller."* The agent calls `size_actuator`
and `select_controller` and reasons over the catalog-grounded, cited results —
not its own guesses.

## Drop into CI

Copy [`templates/github-actions/pyros-ci.yml`](./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.

```yaml
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)

```bash
# 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

# Persist workspace defaults for profile, simulator, ROS distro, and container fallback
pyros project init -w ./my_robot_ws --profile full --sim-backend auto
pyros project show -w ./my_robot_ws

# Capture a portable issue report for Pyros/ROS/simulation/toolchain state
pyros report -w ./my_robot_ws
pyros report -w ./my_robot_ws --json -o pyros-report.json

# Launch MuJoCo viewer offline (no auth, no LLM, no network)
pyros sim-offline -w ./my_robot_ws
pyros sim -w ./my_robot_ws --backend mujoco --json -o sim-report.json

# Forensics on running / past systems
pyros doctor                 # environment health
pyros doctor --install-plan  # OS-specific setup plan for ROS/Gazebo/MuJoCo
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
pyros scan ./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.

## Cross-platform setup

Pyros core runs on macOS, Windows, and Linux — the full test suite runs on all
three in CI, so this is a verified claim, not a hope. ROS 2 and Gazebo remain
native-stack dependencies with different platform support. Use the planner
before simulation:

```bash
pyros doctor --install-plan --profile full
pyros bootstrap --profile mujoco          # installs the lightweight MuJoCo path
pyros bootstrap --profile gazebo --container --pull
pyros sim -w ./my_robot_ws --container    # Gazebo path with Docker fallback
```

Profiles: `core`, `mujoco`, `ros2`, `gazebo`, `full`. ROS/Gazebo native installs are
shown as explicit OS-specific commands; the container path is the recommended fallback
for macOS/Windows and non-Ubuntu Linux. Set `PYROS_GAZEBO_IMAGE` to pin an internal
registry image; Pyros tags it locally as `pyros-gazebo` for runtime use.

Simulation and CI commands run preflight checks by default. Use
`pyros report --json -o pyros-report.json` when filing issues so OS, Python,
ROS, MuJoCo, Gazebo, Docker, workspace contents, and preflight results are all
captured in one file. Use `pyros sim --json -o sim-report.json` to attach the
actual simulation backend, metrics, preflight result, and failure reason.

## What it does (LLM optional)

```bash
# 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.

## Example workflows

See [`examples/README.md`](./examples/README.md) for professional validation paths:
mobile base + Nav2, seeded broken workspace diagnostics, generated manipulator,
and Gazebo container simulation.

## 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/RudranshG07/pyros>.

## License

Apache-2.0
