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

The same guides live in-repo under docs/ (no internet required):

• docs/quickstart.md — install → build a controller from TOML → run a scenario → trace/lower. Start here.
• docs/how-it-works.md — the five ABCs, the dataflow, and each layer (factories, sim, backends, codegen, MCP).
• docs/components.md — catalog of every registered component (class, registered name, file, config).
• docs/codegen.md — tracing → composition → interpretation → Zig lowering to a .so.
• docs/mcp_server.md — running the shinro-mcp server and its tool reference.
• docs/testing.md — how the suite is organized and run.

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

• src/shinro/ — the package. components.py holds the five ABCs; subpackages implement them (controllers/, plants/, estimators/, trajectories/), plus factories/ (registry + config-driven construction), simulation/, physics_engine/, mcp/, utils/, and codegen/ (trace → lower pipeline). The full annotated catalog is in docs/components.md.
• src/shinro/runtime/ — the Zig comptime VM that executes lowered graphs (see src/shinro/runtime/README.md).
• demos/ — runnable example scenarios (python -m demos.demo_*).
• tests/ — pytest suite (see docs/testing.md).
• lab-notes/daily/ — dated engineering notes and design narrative.
• scripts/ — codegen and config-generation helpers (scripts/gen_base.py, scripts/generate_robot_config.py).

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.