Metadata-Version: 2.4
Name: robopilot
Version: 1.4.0
Summary: No-ROS-required static engineering toolchain for ROS-style projects.
Author: J1angJJ
License-Expression: MIT
Project-URL: Homepage, https://github.com/J1angJJ/RoboPilot
Project-URL: Repository, https://github.com/J1angJJ/RoboPilot
Project-URL: Issues, https://github.com/J1angJJ/RoboPilot/issues
Project-URL: Changelog, https://github.com/J1angJJ/RoboPilot/blob/main/CHANGELOG.md
Keywords: robotics,ros,ros1,ros2,developer-tools,code-generation,static-analysis,migration
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.12,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Provides-Extra: llm
Requires-Dist: openai>=1.0.0; extra == "llm"
Dynamic: license-file

# RoboPilot

[English](README.md) | [中文](README.zh-CN.md)

[![Tests](https://github.com/J1angJJ/RoboPilot/actions/workflows/tests.yml/badge.svg)](https://github.com/J1angJJ/RoboPilot/actions/workflows/tests.yml)

RoboPilot is a no-ROS-required static engineering toolchain for ROS-style projects.

It helps robotics learners and developers plan, refine, validate, generate, inspect, update, roll back, document, and review ROS/ROS2-style project structure without installing ROS, ROS2, catkin, colcon, simulator runtimes, or robot hardware.

## What RoboPilot Does

- Creates and validates `ProjectSpec` files from robotics tasks.
- Renders deterministic ROS-style Python package skeletons.
- Refines and diffs specs before generation.
- Previews, exports, applies, backs up, rolls back, and journals safe project updates.
- Inspects projects and exports read-only reports.
- Detects RoboPilot, ROS1, ROS2, mixed, non-ROS, and unknown project types.
- Statically inspects ROS1 catkin packages.
- Analyzes declared and detected dependencies.
- Builds static ROS1-to-ROS2 migration plans, validates/diffs them, and previews file-level migration work.
- Provides small offline utilities for robotics error logs and Mermaid workflow graphs.
- Optionally uses an LLM only to produce or refine validated `ProjectSpec` data.
- Provides a lightweight Python API layer for scripts and future integrations.
- Documents stable top-level JSON keys for integration-oriented `--json` outputs.
- Includes a VSCode extension MVP source tree that wraps the RoboPilot CLI JSON outputs.

RoboPilot does not run ROS, ROS2, launch files, generated code, `catkin_make`, or `colcon`.

## Quick Start

Supported Python versions for this release line are Python 3.10 and 3.11. Package metadata declares `>=3.10,<3.12`; Python 3.12 and 3.13 are not claimed until the test suite passes there.

Install from source for now:

```bash
python -m venv .venv
.venv\Scripts\activate
python -m pip install -U pip
pip install -e ".[dev]"
robopilot --help
```

After PyPI release:

```bash
pip install robopilot
robopilot --help
```

On Windows, if pytest has temporary directory permission issues:

```bash
python -m pytest --basetemp=".pytest_tmp" -p no:cacheprovider
```

## Core Workflows

Spec-first generation:

```bash
robopilot plan --name demo_detector --task "Create an object detection pipeline" --output robopilot.yaml
robopilot validate --spec robopilot.yaml
robopilot generate --spec robopilot.yaml
```

Iterative spec review:

```bash
robopilot refine --spec robopilot.yaml --instruction "Add a tracker node after the detector" --output refined.yaml
robopilot diff --old robopilot.yaml --new refined.yaml
```

Safe project update loop:

```bash
robopilot apply-preview --spec refined.yaml --project outputs/demo_detector
robopilot apply-plan --spec refined.yaml --project outputs/demo_detector --output apply_plan.yaml
robopilot apply --plan apply_plan.yaml
robopilot apply --plan apply_plan.yaml --confirm
robopilot history --project outputs/demo_detector
```

Static project review:

```bash
robopilot inspect examples/generated_projects/demo_detector
robopilot repair-suggest examples/generated_projects/demo_detector
robopilot report examples/generated_projects/demo_detector --output report.md
```

ROS-style static analysis:

```bash
robopilot detect path/to/project
robopilot inspect-ros1 path/to/ros1_package
robopilot deps path/to/project
```

ROS1 to ROS2 migration planning:

```bash
robopilot migrate-plan --from path/to/ros1_package --to ros2 --output migration_plan.yaml
robopilot migrate-plan-validate --plan migration_plan.yaml
robopilot migrate-preview --plan migration_plan.yaml --project path/to/ros1_package
```

## Documentation

- [Command Reference](docs/command_reference.md)
- [Workflows](docs/workflows.md)
- [Architecture](docs/architecture.md)
- [Python API](docs/api.md)
- [JSON Contracts](docs/json_contracts.md)
- [Integration Notes](docs/integration_notes.md)
- [VSCode Extension MVP](docs/vscode_extension.md)
- [Developer Setup](docs/developer_setup.md)
- [Testing](docs/testing.md)
- [Release Process](docs/release_process.md)
- [PyPI Publishing](docs/pypi_publish.md)
- [Compatibility](docs/compatibility.md)
- [Known Limitations](docs/known_limitations.md)
- [Stability Policy](docs/stability_policy.md)
- [Demo Script](docs/demo_script.md)
- [v1.0.0 Scope](docs/v1_scope.md)
- [Changelog](CHANGELOG.md)
- [Roadmap](roadmap.md)

## Safety Model

RoboPilot is designed around static analysis and explicit review:

- Default planning, validation, diff, inspection, report, detection, dependency, and migration commands are read-only.
- `apply` is dry-run by default and writes only with `--confirm`.
- Confirmed updates write only files listed in a validated apply plan.
- Existing files are backed up before updates.
- `rollback` is dry-run by default and restores only files from RoboPilot backup directories.
- Migration planning, validation, diff, and preview do not modify source projects.
- Optional LLM paths are limited to `ProjectSpec` planning/refinement and must pass validation before generation or apply workflows.

## Example Output

A static generated demo project is committed at:

```txt
examples/generated_projects/demo_detector/
```

Transient generated projects should go under `outputs/`, which is intentionally ignored by git.

## Project Status

Current release line: `v1.4.0`.

RoboPilot's no-ROS-required static engineering workflow remains the stable v1 baseline:

```txt
plan -> refine -> diff -> validate -> generate
      -> apply-preview -> apply-plan -> apply -> rollback -> history
      -> inspect -> repair-suggest -> report
      -> detect -> inspect-ros1 -> deps
      -> migrate-plan -> migrate-plan-validate -> migrate-plan-diff -> migrate-preview
```

The Python API layer, documented CLI JSON contracts, and VSCode extension MVP source are available for integration work while the CLI remains the primary user interface.

The VSCode extension lives under `vscode-extension/`, requires the RoboPilot CLI to be installed, and is documented in [docs/vscode_extension.md](docs/vscode_extension.md).

## Development

Run tests:

```bash
python -m pytest
```

Windows fallback:

```bash
python -m pytest --basetemp=".pytest_tmp" -p no:cacheprovider
```

## License

MIT
