Metadata-Version: 2.4
Name: pyros-robotics
Version: 1.0.0
Summary: Validation, repair, and forensics toolchain for ROS 2 workspaces
Author: Pyros Team
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,cli,robotics,ros2,simulation
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: mcp>=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>=0.40
Requires-Dist: trimesh>=3.20
Provides-Extra: all
Requires-Dist: mujoco>=3.0; extra == 'all'
Requires-Dist: openai>=1.0; 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: 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

**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.

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

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

```json
{
  "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`](./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

# 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)

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

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