Shinro Python Modules

A clean, modular Python control framework built on five abstract base classes — Controller, Plant, StateEstimator, TrajectoryGenerator, and PhysicsEngine — with registry-based factories that compose them from TOML config. The architecture is robot-agnostic: LeKiwi (holonomic base + 6-DOF arm) is the current reference robot used in the demos below, not a framework constraint.

Naming note: this repo was previously scoped and named for LeKiwi only (lerobot-mpc-lekiwi). It was renamed to shinro-python-modules because the registry/factory/ABC pattern generalized beyond one robot.

Documentation

Conceptual and operational documentation lives in docs.shinro.xyz:

• Control Architecture — why the five ABCs exist, how they compose, sim/hardware parity
• Python Modules — the operational guide: install, run, extend, component catalog

This README stays limited to repo-local setup and contributor pointers.

Install

From a source checkout (recommended for development):

pip install -e .            # core (numpy, scipy, osqp, mcp)
pip install -e ".[mujoco]"  # add MuJoCo physics backend
pip install -e ".[torch]"   # add torch backend
pip install -e ".[lerobot]" # add learned-policy adapter

Once published, consumers can install from a git ref or an index without a checkout:

pip install "shinro[mujoco,torch] @ git+https://github.com/<org>/shinro-python-modules@v0.1.0"

The MCP server is installed as a console command: shinro-mcp.

Releases

Versions are derived from git tags via setuptools-scm. A release is a vX.Y.Z tag pushed to origin; the .github/workflows/release.yml workflow builds the wheel + sdist, smoke-tests them, and attaches them to a GitHub Release with auto-generated notes.

CHANGELOG.md is auto-generated by git cliff from commit history. To keep it useful, commits must follow Conventional Commits:

• feat: ... → Added
• fix: ... → Fixed
• perf: ..., refactor: ... → Changed
• docs:, test:, build:, ci:, style: → grouped separately
• chore: ... → skipped

Non-conforming commits land under Other (or are dropped). chore: release vX.Y.Z commits are skipped automatically.

Semantic versioning:

• patch — backwards-compatible fix (v0.1.0 → v0.1.1)
• minor — backwards-compatible feature (v0.1.1 → v0.2.0)
• major — incompatible API change (v0.2.0 → v1.0.0)

To cut a release:

# Regenerates CHANGELOG.md with the new version section and stages it
make release-patch   # or release-minor / release-major

# Commit the changelog, then push main + the tag to trigger the release
git commit -m "chore: release vX.Y.Z"
git push origin main
git push origin vX.Y.Z

Preview the changelog without cutting a release:

make changelog   # git cliff --unreleased --output CHANGELOG.md

Development builds between tags are auto-numbered (0.1.2.devN+g<sha>). Local build + install sanity: make install and make build.

Run a demo

python -m demos.demo_simple                              # terminal-only, no viewer
python -m demos.demo_arm_trajectory                       # arm trajectory + live viewer
python -m demos.demo_base_tracking                        # base tracking, LQR + observer
python -m demos.demo_base_tracking --controller mpc       # base tracking, MPC
python -m demos.demo_pick_and_place                       # full pick-and-place sequence

Auto-generate a robot config from a MuJoCo model:

python scripts/generate_robot_config.py lekiwi-sim/mjcf_lcmm_robot.xml > robot_config.toml

Repo structure

See Python Modules for the annotated architecture and component catalog. For the raw file tree, browse the repo on GitHub rather than reading it out of this README — it drifts.

Contributing / agent instructions

See AGENTS.md for the codebase index (Hermes) and lab-notes workflow used by agents working in this repo.

Status

See the Roadmap for what's shipped vs. planned, including Shinro Studio integration status.