ragleap-physical

version — loading live from PyPI…

Status: pre-alpha. Simulation only. Nothing here controls real hardware, and it is not a safety certification. A small library that connects RagLeap AI employees to open-source simulators, so people can build and test safely. Observing comes first. Every action goes through a proposal, an approval and a safety envelope that lives in the bridge, in one place. The model cannot change the limits.

pip install ragleap-physical
pip install "ragleap-physical[mujoco]"   # optional MuJoCo adapter

Python 3.10 or newer. The core has no runtime dependencies. Optional extras: mujoco, test and interop (the MCP SDK, for the interop test).

How it works

1. Observe. The AI lists its sources, reads an observation and reads the safety envelope.
2. Propose. The AI can only propose a change. None of its four tools can approve, apply, stop or change a limit.
3. Approve. A named person approves the exact proposal in the operator console. The approver’s name comes from the token.
4. Check. The bridge runs a dry run and checks the limits again, including the workspace box.
5. Apply and verify. The change is applied in the simulator and the real outcome is checked there. An out-of-range value is refused, not clamped.
6. Stop. A stop needs no approval.

Highlights

• A safety envelope and bridge between an AI agent and a simulator: the AI can only propose a change, a named person approves the exact change, the bridge checks the limits again when it applies it, and the outcome is verified in the simulator. A dry run, runtime monitoring, a stop that needs no approval and an audit log are included
• Exactly four tools for an AI agent: list sources, get an observation, get the envelope, propose an action. None of them can approve, apply, stop or change a limit. A small MCP server (standard library, loopback by default, optional bearer token) serves them, and it was tested against the official MCP Python SDK. RagLeap’s own MCP client was not read or tested
• An operator console (ragleap_physical.console) for the human side: a named person sees the pending proposals, approves the exact digest, applies, and can stop. Loopback only, one token per person, and the approver’s name comes from the token, never from the request. The AI cannot reach it
• Workspace limits: a box in x, y and z that every tracked point must stay inside, checked on the starting state, on the dry run and again on the real motion in short slices. If a workspace is set and the adapter cannot report positions, everything is refused
• Simulators: a built-in one-joint model, a two-link and a three-joint arm model (built-in stand-ins and MuJoCo XML), optional MuJoCo adapters (one observe-only, one servo adapter that follows set_position_target in simulation, only through the bridge), and an offline ROS 2 observe-only mock that needs no ROS install
• Two observe-only industrial mocks with no network and no real meter or machine: a simulated energy site and an MTConnect document reader with strict limits (it refuses DTDs and entities and caps the size)
• A simulated machine tool (tool wear): the AI can only adjust a tool offset, in micrometres, inside an envelope (range, step size, minimum gap between changes). It is a model with invented numbers and says nothing about a real machine
• New in 0.0.3 (from its changelog, 2026-11-03): a second runnable demo, a two-link arm with one accepted and one refused workspace move, contributed by @bhuvanm0981-ctrl; and a fix so the console and the MCP server read and discard a small request body before they refuse a request. A Windows test run reported WinError 10053 on a refused request (found by @Anurag07-crypto). It could not be reproduced on Linux, and a test checks that the body is drained. The changelog says: not yet verified on Windows
• New in 0.0.4 (from its changelog, 2026-11-06): Item can be imported from ragleap_physical.adapters (reported by a reviewer on a clean install of 0.0.3); PowerShell steps in the first-hour guide (PR #1177 by @Anurag07-crypto); review tests for the energy-site adapter, the three-joint arm and the MuJoCo servo adapter. Fixes: after a stop the three-joint arm can be observed again, the three-joint arm refuses NaN, infinity, text, booleans and None, and the MuJoCo servo adapter refuses a target outside the actuator range instead of letting MuJoCo silently clamp it
• New in 0.0.5 (from its changelog, 2026-11-08): still pre-alpha, simulation only. An explicit-state model of the approval flow, with tests that replay every short event sequence (one proposal, up to five events) through the model and through the real Bridge; it is a hand-written abstract model, not a proof about the code, and time, concurrency and adapters are not modelled. Adapter conformance tests: one contract every adapter must pass. Fixes: the stand-in arms and the simulated machine tool refuse NaN, infinity, text, booleans and None when called directly (the Bridge already rejected them); the offline ROS 2 mock can be stopped and then cleared; and MTConnect wording: our adapters are observe-only, and the docs no longer say MTConnect is “not purely read-only” (some agents can be set to accept pushed data, which was not re-checked since 2026-10-30).

Measurements and limits

Our Tests page lists 19 test files and 239 test functions on the main branch (counted from the repository, not a pass count). For 0.0.1 the release notes record 185 tests passing on the published source archive with MuJoCo and the MCP SDK installed (Colab, 2026-11-02), and GitHub CI on Python 3.10, 3.11 and 3.12. Tests that need MuJoCo or the MCP SDK are skipped without those extras, and a skipped test proves nothing. MuJoCo results are repeatable within one installed environment only. The machine-tool and wear numbers are invented. A clean Windows 11 re-test of the published 0.0.3 on 2026-11-04 (issue #1114, Python 3.12.10, PowerShell) still saw intermittent WinError 10053 failures in full-suite runs (first run 207 passed, 1 failed, 27 skipped; second run 2 failed), and the failing tests passed when run alone, so the Windows problem is not yet resolved.

Not claimed, not built

Nothing is claimed about real robots, real machines, safety certification or regulatory compliance. Simulation is not reality: a passing simulation test is not proof for a real machine. Not built: a second simulator, real hardware, Java and npm clients. Out of scope, always: life-safety systems, medical devices, vehicles on public roads, weapons, and anything that could hurt people without an independent hardware safety stop.

Releases

• 0.0.1 (PyPI, 2026-11-02): observation and proposal formats, four capability levels, the safety envelope, approvals bound to the exact proposal, dry run, outcome check and stop, four tools and a small MCP server, MuJoCo adapters and workspace limits
• 0.0.2 (PyPI, 2026-11-02): the operator console, an observe-only energy site mock and an MTConnect document reader, a first-hour guide, an industry guide, a wear-study notebook with a pluggable wear model, and Hindi and Tamil README drafts (not reviewed by native speakers)
• 0.0.3 (PyPI, 2026-11-04; the changelog is dated 2026-11-03): a second runnable demo, project links on the PyPI page, and a fix so refused requests read and discard a small request body first
• 0.0.4 (changelog 2026-11-06): the Item import fix, PowerShell steps in the first-hour guide, review tests and input-refusal fixes for the three-joint arm and the MuJoCo servo adapter
• 0.0.5 (changelog 2026-11-08): the approval-flow model and adapter conformance tests, input refusals in the stand-in adapters, the ROS 2 mock clear-stop fix and the MTConnect wording.

Try it in a few minutes

From a clone of the repository, inside packages/ragleap-physical. These lines are copied from the package README:

pip install -e ".[test]"          # core only, standard library
pip install -e ".[mujoco,test]"   # with the optional MuJoCo adapter
pip install -e ".[test,interop]"  # also runs the MCP SDK interop test
pytest
python examples/demo_fake.py
python examples/two_link_workspace_demo.py

The first-hour guide walks through reading, installing, testing and running the demo, including steps for Windows PowerShell.

Community and credits

• @bhuvanm0981-ctrl: the two-link workspace demo (PR #1153, merged), and the Kannada README translation (issue #1123)
• @Anurag07-crypto: a clean Windows 11 test of the package and the first-hour guide (issue #1114), which led to the request-body fix in 0.0.3, and PowerShell steps for the first-hour guide (PR #1177, merged)
• The release notes label the package AI-assisted, and the README says it was hardened after review by two other AI sessions (see the changelog). Everyone is credited by name unless they opt out

Reviewers wanted

Mechanical, manufacturing and metrology engineers are asked to review the simulated models and say where they are wrong or unrealistic (issue #1139). Real hardware is not open for contributions.