openmhp 0.3.0__tar.gz

openmhp-0.3.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: openmhp
+Version: 0.3.0
+Summary: OpenMHP: reference implementation of the Open Model Hardware Protocol (MHP), an open protocol for AI agents to operate physical devices safely.
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6
+Provides-Extra: discovery
+Requires-Dist: zeroconf>=0.130; extra == "discovery"
+
+# OpenMHP
+
+Reference implementation of the **Open Model Hardware Protocol (MHP)**: an
+open protocol through which an AI agent finds a physical device among
+thousands, learns how to operate it safely, reads from it, writes to it, and
+runs long actions on it.
+
+MHP is to instruments and machines what MCP is to software tools, with two
+lessons from MCP's first year built in from the start: the agent's context
+stays flat as the lab grows, and safety is enforced on the device side of the
+wire.
+
+| Primitive | Verb | Example |
+|---|---|---|
+| **Directory** | `directory/search` | "something idle that can heat a 96-well plate to 95 °C in bay 12" → 5 cards |
+| **Describe** | `device/describe {detail, select}` | card (~40 tokens) → summary (~200) → full spec of the two items you'll use |
+| **Signals** | `signals/read`, `signals/subscribe` | block temperature, arm position, lid state |
+| **Settings** | `settings/write` | target temperature = 95 °C, refused above 105 |
+| **Actions** | `actions/invoke` → job | run PCR protocol, pick plate; device does the work |
+| **Safety** | `safety/limits`, `safety/estop`, `safety/reset` | limits, interlocks, approval levels, e-stop, watchdog |
+
+Python ≥ 3.10; PyYAML is the only dependency.
+
+**Docs:** [openmhp.com](https://openmhp.com) · [Quickstart](https://openmhp.com/quickstart) · [Add an instrument](https://openmhp.com/add-a-device) · [Adapters](https://openmhp.com/adapters) · [Specification](https://openmhp.com/spec). The site's source is [kushalsinha/openMHP-website](https://github.com/kushalsinha/openMHP-website); `SPEC.md` here is the specification's source of truth.
+
+## For scientists: one command
+
+```bash
+npx openmhp setup
+```
+
+That installs the runtime into `~/.openmhp`, puts the three Agent Skills where your harness
+looks for them, and registers the MCP server with Claude Code and Codex (other harnesses get a
+one-line config to paste). Then talk to your agent:
+
+- *"find the instruments on my network"*: the agent scans for devices that speak MHP and lists them
+- *"add the thermocycler"*: it joins your lab and is searchable from then on
+- *"onboard my hotplate"*: the agent interviews you, writes the device package, validates it, adds it
+- *"run a 30-cycle PCR at 95/58/72 and hold at 4 °C"*: find, read the owner's instructions, dry-run, run, verify
+
+Try it without hardware: `npx openmhp demo` adds two simulated instruments. Until the npm and PyPI packages are published, point the launcher at this checkout:
+`OPENMHP_SOURCE=/path/to/openmhp npx ./npm setup`.
+
+## For developers: try it in 60 seconds
+
+```bash
+pip install -e ".[discovery]"
+
+# 1. code file: orchestrate a robot arm and a thermocycler
+python examples/pcr_run.py
+
+# 2. scale: 2,000 devices, find the right one for 1,087 tokens instead of 937,845
+python examples/scale_demo.py
+
+# 3. CLI: run devices and a directory over HTTP
+mhp serve local:openmhp.devices.sim_thermocycler:SimThermocycler --http 18921 &
+mhp serve local:openmhp.devices.sim_arm:SimArm --http 18922 &
+mhp serve-directory thermo=http://localhost:18921 arm=http://localhost:18922 --http 18900 &
+mhp http://localhost:18900 find pick plates                 # directory search
+curl localhost:18921/mhp.json                               # discovery document
+mhp http://localhost:18921 describe card                    # card | summary | full
+mhp http://localhost:18921 write target_temperature 200     # refused: LimitViolation
+mhp http://localhost:18921 invoke run_protocol '{"steps":[{"temp":95,"hold_s":5}],"cycles":3}' --wait
+mhp http://localhost:18921 estop
+
+# 4. MCP: expose the whole lab to any agent harness through eight tools, whatever its size
+mhp-mcp --directory http://localhost:18900                # stdio
+mhp-mcp --directory http://localhost:18900 --http 18800   # MCP Streamable HTTP at /mcp
+
+# 5. adapters + live directory, verified against fakes (no hardware)
+python tests/test_adapters.py
+```
+
+## Already running SiLA 2, PyLabRobot, MADSci, OPC UA or ROS 2?
+
+Each device is a few lines with the matching adapter; every gate, tier and job comes for free:
+
+```python
+from openmhp.adapters.sila2 import sila_device            # also: pylabrobot.plr_device,
+DEVICE = sila_device("10.0.0.12", 50052,                  # madsci.madsci_node, opcua.opcua_device,
+    device={"id": "arm-01", "class": "robot_arm", "location": "bay 3", "tags": ["plates"],   # ros2.ros2_device
+            "notes": "PF400 plate mover. Light curtain trips safe_zone_clear."},
+    signals={"position": "RobotController.Position", "safe_zone_clear": ("SafetyController.SafeZoneClear", "boolean")},
+    settings={"speed": ("RobotController.SetSpeed.Speed", {"min": 1, "max": 100})},
+    actions={"move_to": ("RobotController.MoveTo", {"observable": True, "interlocks": ["safe_zone_clear"]})},
+    estop="RobotController.EmergencyStop")
+```
+
+Anything else with a Python callable goes through `BoundDriver(Signal, Setting, Action)` directly.
+
+## Agent Skills
+
+`openmhp/skills/` holds three [Agent Skills](https://agentskills.io) any skills-capable harness can load (`mhp skills install` copies them into place):
+
+| Skill | Use it to |
+|---|---|
+| `openmhp-onboard-device` | interview a device owner and write a validated descriptor + driver |
+| `openmhp-adapt-fleet` | bring a SiLA 2 / PyLabRobot / MADSci / OPC UA / ROS 2 fleet under MHP, build the directory, publish `mhp-mcp` |
+| `openmhp-operate` | run experiments safely through the eight tools: find → describe → check → dry-run → act → verify |
+
+`npx openmhp setup` or `mhp skills install` installs them into `~/.claude/skills`, `~/.codex/skills` and any other harness skills folder that exists.
+
+Claude Desktop / Claude Code config for the bridge:
+
+```json
+{"mcpServers": {"lab": {"command": "mhp-mcp", "args": ["--directory", "http://directory:18900"]}}}
+```
+
+The bridge exposes `mhp_find`, `mhp_describe`, `mhp_read`, `mhp_write`,
+`mhp_invoke`, `mhp_job`, `mhp_estop`, `mhp_run` (run a script against the
+lab, get back only what it prints) and `mhp_lab` (scan the network, add and
+onboard devices). Every tool carries `input_examples`. There are never
+per-device tools.
+
+## A device is a package, like a skill
+
+```
+devices/thermocycler-01/
+├── DEVICE.md          Level 1: YAML frontmatter = the card (~40 tokens in search results)
+│                      Level 2: Markdown body = operating instructions (loaded when chosen)
+├── descriptor.yaml    Level 3: limits, interlocks, params, examples (loaded per item)
+├── driver.py          Level 3: code
+├── references/        Level 3: SOPs, manual excerpts
+└── scripts/           Level 3: tested mhp_run scripts
+```
+
+```bash
+mhp serve pkg:openmhp/devices/thermocycler-01 --http 18921
+mhp http://localhost:18921 describe card        # level 1
+mhp http://localhost:18921 describe summary     # level 2, with instructions
+mhp http://localhost:18921 resources scripts/pcr.py   # level 3
+```
+
+## Writing a driver
+
+A driver is a package plus three hooks. Everything else (limit checks,
+interlocks, approval gating, leases, jobs, e-stop, notifications, detail
+tiers) is inherited.
+
+```python
+from openmhp.driver import Driver
+
+class MyHotplate(Driver):
+    descriptor = {
+        "device":   {"id": "hotplate-01", "class": "hotplate", "make": "IKA", "model": "C-MAG",
+                     "location": "fume hood 2", "tags": ["heating", "stirring"],
+                     "notes": "Fume hood 2. Stir bar rattles above 800 rpm with 50 mL flasks."},
+        "physical": {"mass_kg": 3.2, "notes": "Plate surface reaches 500 °C; keep solvents capped."},
+        "signals":  [{"name": "plate_temperature", "type": "number", "unit": "degC"}],
+        "settings": [{"name": "target_temperature", "type": "number", "unit": "degC",
+                      "limits": {"min": 20, "max": 300}, "approval": "auto"},
+                     {"name": "stir_rpm", "type": "number", "limits": {"min": 0, "max": 1500}}],
+        "actions":  [{"name": "shutdown", "duration": "short", "approval": "confirm"}],
+        "safety":   {"estop": True, "watchdog_s": 5},
+    }
+    def setup(self):                    self.dev = serial.Serial("/dev/ttyUSB0")
+    def on_read(self, name):            return float(self.dev.query("IN_PV_1"))
+    def on_write(self, name, value):    self.dev.write(f"OUT_SP_1 {value}")
+    def on_invoke(self, job):           self.dev.write("STOP")
+    def on_estop(self):                 self.dev.write("STOP")
+```
+
+```bash
+mhp serve mypkg.hotplate:MyHotplate --http 18921
+```
+
+## Layout
+
+```
+openmhp/driver.py        Driver base class: primitives, safety gates, jobs, leases, detail tiers, resources
+openmhp/package.py       device packages: DEVICE.md frontmatter + body, descriptor.yaml, resources
+openmhp/directory.py     Directory: card index + BM25 search + live state pings; serves directory/*
+openmhp/fleet.py         the lab's device list (~/.openmhp/fleet.json); in-process hosting of packages
+openmhp/discovery.py     mDNS advertise/browse (optional zeroconf) and HTTP probe of /mhp.json
+openmhp/validate.py      device package validator (`mhp validate`)
+openmhp/skills_install.py  copies bundled skills into harness skill dirs (`mhp skills install`)
+npm/                     the `npx openmhp` launcher (Node, no deps): runtime bootstrap, setup, scan/add
+openmhp/adapters/        BoundDriver bindings; sila2, pylabrobot, madsci, opcua, ros2 adapters
+openmhp/skills/          Agent Skills: onboard-device, adapt-fleet, operate (bundled)
+tests/test_adapters.py   adapters and live directory against injected fakes
+openmhp/transport.py     stdio and HTTP(+SSE) transports; /mhp.json discovery
+openmhp/client.py        Device / Lab client SDK (local, stdio, http); Lab is lazy and directory-aware
+openmhp/cli.py           `mhp` command, incl. serve and serve-directory
+openmhp/mcp_bridge.py    `mhp-mcp`: eight tools, constant in device count; mhp_run
+openmhp/devices/         simulated thermocycler and robot arm, each as a device package
+examples/pcr_run.py      cross-device orchestration script
+examples/scale_demo.py   2,000 devices; context cost old way vs MHP way
+SPEC.md                  the specification, Markdown
+```

openmhp-0.3.0/README.md

@@ -0,0 +1,189 @@
+# OpenMHP
+
+Reference implementation of the **Open Model Hardware Protocol (MHP)**: an
+open protocol through which an AI agent finds a physical device among
+thousands, learns how to operate it safely, reads from it, writes to it, and
+runs long actions on it.
+
+MHP is to instruments and machines what MCP is to software tools, with two
+lessons from MCP's first year built in from the start: the agent's context
+stays flat as the lab grows, and safety is enforced on the device side of the
+wire.
+
+| Primitive | Verb | Example |
+|---|---|---|
+| **Directory** | `directory/search` | "something idle that can heat a 96-well plate to 95 °C in bay 12" → 5 cards |
+| **Describe** | `device/describe {detail, select}` | card (~40 tokens) → summary (~200) → full spec of the two items you'll use |
+| **Signals** | `signals/read`, `signals/subscribe` | block temperature, arm position, lid state |
+| **Settings** | `settings/write` | target temperature = 95 °C, refused above 105 |
+| **Actions** | `actions/invoke` → job | run PCR protocol, pick plate; device does the work |
+| **Safety** | `safety/limits`, `safety/estop`, `safety/reset` | limits, interlocks, approval levels, e-stop, watchdog |
+
+Python ≥ 3.10; PyYAML is the only dependency.
+
+**Docs:** [openmhp.com](https://openmhp.com) · [Quickstart](https://openmhp.com/quickstart) · [Add an instrument](https://openmhp.com/add-a-device) · [Adapters](https://openmhp.com/adapters) · [Specification](https://openmhp.com/spec). The site's source is [kushalsinha/openMHP-website](https://github.com/kushalsinha/openMHP-website); `SPEC.md` here is the specification's source of truth.
+
+## For scientists: one command
+
+```bash
+npx openmhp setup
+```
+
+That installs the runtime into `~/.openmhp`, puts the three Agent Skills where your harness
+looks for them, and registers the MCP server with Claude Code and Codex (other harnesses get a
+one-line config to paste). Then talk to your agent:
+
+- *"find the instruments on my network"*: the agent scans for devices that speak MHP and lists them
+- *"add the thermocycler"*: it joins your lab and is searchable from then on
+- *"onboard my hotplate"*: the agent interviews you, writes the device package, validates it, adds it
+- *"run a 30-cycle PCR at 95/58/72 and hold at 4 °C"*: find, read the owner's instructions, dry-run, run, verify
+
+Try it without hardware: `npx openmhp demo` adds two simulated instruments. Until the npm and PyPI packages are published, point the launcher at this checkout:
+`OPENMHP_SOURCE=/path/to/openmhp npx ./npm setup`.
+
+## For developers: try it in 60 seconds
+
+```bash
+pip install -e ".[discovery]"
+
+# 1. code file: orchestrate a robot arm and a thermocycler
+python examples/pcr_run.py
+
+# 2. scale: 2,000 devices, find the right one for 1,087 tokens instead of 937,845
+python examples/scale_demo.py
+
+# 3. CLI: run devices and a directory over HTTP
+mhp serve local:openmhp.devices.sim_thermocycler:SimThermocycler --http 18921 &
+mhp serve local:openmhp.devices.sim_arm:SimArm --http 18922 &
+mhp serve-directory thermo=http://localhost:18921 arm=http://localhost:18922 --http 18900 &
+mhp http://localhost:18900 find pick plates                 # directory search
+curl localhost:18921/mhp.json                               # discovery document
+mhp http://localhost:18921 describe card                    # card | summary | full
+mhp http://localhost:18921 write target_temperature 200     # refused: LimitViolation
+mhp http://localhost:18921 invoke run_protocol '{"steps":[{"temp":95,"hold_s":5}],"cycles":3}' --wait
+mhp http://localhost:18921 estop
+
+# 4. MCP: expose the whole lab to any agent harness through eight tools, whatever its size
+mhp-mcp --directory http://localhost:18900                # stdio
+mhp-mcp --directory http://localhost:18900 --http 18800   # MCP Streamable HTTP at /mcp
+
+# 5. adapters + live directory, verified against fakes (no hardware)
+python tests/test_adapters.py
+```
+
+## Already running SiLA 2, PyLabRobot, MADSci, OPC UA or ROS 2?
+
+Each device is a few lines with the matching adapter; every gate, tier and job comes for free:
+
+```python
+from openmhp.adapters.sila2 import sila_device            # also: pylabrobot.plr_device,
+DEVICE = sila_device("10.0.0.12", 50052,                  # madsci.madsci_node, opcua.opcua_device,
+    device={"id": "arm-01", "class": "robot_arm", "location": "bay 3", "tags": ["plates"],   # ros2.ros2_device
+            "notes": "PF400 plate mover. Light curtain trips safe_zone_clear."},
+    signals={"position": "RobotController.Position", "safe_zone_clear": ("SafetyController.SafeZoneClear", "boolean")},
+    settings={"speed": ("RobotController.SetSpeed.Speed", {"min": 1, "max": 100})},
+    actions={"move_to": ("RobotController.MoveTo", {"observable": True, "interlocks": ["safe_zone_clear"]})},
+    estop="RobotController.EmergencyStop")
+```
+
+Anything else with a Python callable goes through `BoundDriver(Signal, Setting, Action)` directly.
+
+## Agent Skills
+
+`openmhp/skills/` holds three [Agent Skills](https://agentskills.io) any skills-capable harness can load (`mhp skills install` copies them into place):
+
+| Skill | Use it to |
+|---|---|
+| `openmhp-onboard-device` | interview a device owner and write a validated descriptor + driver |
+| `openmhp-adapt-fleet` | bring a SiLA 2 / PyLabRobot / MADSci / OPC UA / ROS 2 fleet under MHP, build the directory, publish `mhp-mcp` |
+| `openmhp-operate` | run experiments safely through the eight tools: find → describe → check → dry-run → act → verify |
+
+`npx openmhp setup` or `mhp skills install` installs them into `~/.claude/skills`, `~/.codex/skills` and any other harness skills folder that exists.
+
+Claude Desktop / Claude Code config for the bridge:
+
+```json
+{"mcpServers": {"lab": {"command": "mhp-mcp", "args": ["--directory", "http://directory:18900"]}}}
+```
+
+The bridge exposes `mhp_find`, `mhp_describe`, `mhp_read`, `mhp_write`,
+`mhp_invoke`, `mhp_job`, `mhp_estop`, `mhp_run` (run a script against the
+lab, get back only what it prints) and `mhp_lab` (scan the network, add and
+onboard devices). Every tool carries `input_examples`. There are never
+per-device tools.
+
+## A device is a package, like a skill
+
+```
+devices/thermocycler-01/
+├── DEVICE.md          Level 1: YAML frontmatter = the card (~40 tokens in search results)
+│                      Level 2: Markdown body = operating instructions (loaded when chosen)
+├── descriptor.yaml    Level 3: limits, interlocks, params, examples (loaded per item)
+├── driver.py          Level 3: code
+├── references/        Level 3: SOPs, manual excerpts
+└── scripts/           Level 3: tested mhp_run scripts
+```
+
+```bash
+mhp serve pkg:openmhp/devices/thermocycler-01 --http 18921
+mhp http://localhost:18921 describe card        # level 1
+mhp http://localhost:18921 describe summary     # level 2, with instructions
+mhp http://localhost:18921 resources scripts/pcr.py   # level 3
+```
+
+## Writing a driver
+
+A driver is a package plus three hooks. Everything else (limit checks,
+interlocks, approval gating, leases, jobs, e-stop, notifications, detail
+tiers) is inherited.
+
+```python
+from openmhp.driver import Driver
+
+class MyHotplate(Driver):
+    descriptor = {
+        "device":   {"id": "hotplate-01", "class": "hotplate", "make": "IKA", "model": "C-MAG",
+                     "location": "fume hood 2", "tags": ["heating", "stirring"],
+                     "notes": "Fume hood 2. Stir bar rattles above 800 rpm with 50 mL flasks."},
+        "physical": {"mass_kg": 3.2, "notes": "Plate surface reaches 500 °C; keep solvents capped."},
+        "signals":  [{"name": "plate_temperature", "type": "number", "unit": "degC"}],
+        "settings": [{"name": "target_temperature", "type": "number", "unit": "degC",
+                      "limits": {"min": 20, "max": 300}, "approval": "auto"},
+                     {"name": "stir_rpm", "type": "number", "limits": {"min": 0, "max": 1500}}],
+        "actions":  [{"name": "shutdown", "duration": "short", "approval": "confirm"}],
+        "safety":   {"estop": True, "watchdog_s": 5},
+    }
+    def setup(self):                    self.dev = serial.Serial("/dev/ttyUSB0")
+    def on_read(self, name):            return float(self.dev.query("IN_PV_1"))
+    def on_write(self, name, value):    self.dev.write(f"OUT_SP_1 {value}")
+    def on_invoke(self, job):           self.dev.write("STOP")
+    def on_estop(self):                 self.dev.write("STOP")
+```
+
+```bash
+mhp serve mypkg.hotplate:MyHotplate --http 18921
+```
+
+## Layout
+
+```
+openmhp/driver.py        Driver base class: primitives, safety gates, jobs, leases, detail tiers, resources
+openmhp/package.py       device packages: DEVICE.md frontmatter + body, descriptor.yaml, resources
+openmhp/directory.py     Directory: card index + BM25 search + live state pings; serves directory/*
+openmhp/fleet.py         the lab's device list (~/.openmhp/fleet.json); in-process hosting of packages
+openmhp/discovery.py     mDNS advertise/browse (optional zeroconf) and HTTP probe of /mhp.json
+openmhp/validate.py      device package validator (`mhp validate`)
+openmhp/skills_install.py  copies bundled skills into harness skill dirs (`mhp skills install`)
+npm/                     the `npx openmhp` launcher (Node, no deps): runtime bootstrap, setup, scan/add
+openmhp/adapters/        BoundDriver bindings; sila2, pylabrobot, madsci, opcua, ros2 adapters
+openmhp/skills/          Agent Skills: onboard-device, adapt-fleet, operate (bundled)
+tests/test_adapters.py   adapters and live directory against injected fakes
+openmhp/transport.py     stdio and HTTP(+SSE) transports; /mhp.json discovery
+openmhp/client.py        Device / Lab client SDK (local, stdio, http); Lab is lazy and directory-aware
+openmhp/cli.py           `mhp` command, incl. serve and serve-directory
+openmhp/mcp_bridge.py    `mhp-mcp`: eight tools, constant in device count; mhp_run
+openmhp/devices/         simulated thermocycler and robot arm, each as a device package
+examples/pcr_run.py      cross-device orchestration script
+examples/scale_demo.py   2,000 devices; context cost old way vs MHP way
+SPEC.md                  the specification, Markdown
+```

openmhp-0.3.0/openmhp/__init__.py

@@ -0,0 +1,9 @@
+"""OpenMHP - reference implementation of the Open Model Hardware Protocol (MHP).
+
+MHP is to physical devices what MCP is to software tools: a small JSON-RPC
+protocol through which an AI agent discovers a device, learns how to use it
+safely, reads from it, writes to it, and runs long-running actions on it.
+"""
+
+PROTOCOL_VERSION = "2026-09-09"
+__version__ = "0.3.0"

openmhp-0.3.0/openmhp/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""Adapters: put hardware already controlled by another layer behind MHP.
+
+    from openmhp.adapters import BoundDriver, Signal, Setting, Action   # any Python callable
+    from openmhp.adapters.sila2 import sila_device                      # SiLA 2 servers
+    from openmhp.adapters.pylabrobot import plr_device                  # PyLabRobot machines
+    from openmhp.adapters.madsci import madsci_node                     # MADSci nodes
+    from openmhp.adapters.opcua import opcua_device                     # OPC UA servers / PLCs
+    from openmhp.adapters.ros2 import ros2_device                       # ROS 2 nodes
+
+Each returns a Driver; serve it with `mhp serve`, register it in a Directory,
+or expose it through `mhp-mcp` like any native MHP device.
+"""
+from .base import Action, BoundDriver, Setting, Signal, params_from_signature
+
+__all__ = ["Action", "BoundDriver", "Setting", "Signal", "params_from_signature"]

openmhp-0.3.0/openmhp/adapters/base.py

@@ -0,0 +1,140 @@
+"""Bindings: the few-lines way to put any controllable thing behind MHP.
+
+An adapter author describes a device as three small lists of *bindings*, each
+pairing an MHP name with a callable into the underlying control layer. The
+BoundDriver turns them into a full MHP driver with every safety gate, the
+detail tiers, jobs and notifications inherited from Driver.
+
+    dev = BoundDriver(
+        device={"id": "hotplate-01", "class": "hotplate", "notes": "Fume hood 2."},
+        signals=[Signal("plate_temperature", read=lambda: plc.read(0x10), unit="degC")],
+        settings=[Setting("target_temperature", write=lambda v: plc.write(0x20, v),
+                          unit="degC", limits={"min": 20, "max": 300})],
+        actions=[Action("shutdown", run=lambda job, p: plc.write(0x21, 0), approval="confirm")],
+        estop=lambda: plc.write(0x21, 0),
+    )
+
+Ecosystem adapters (sila2, pylabrobot, madsci, opcua, ros2) are just functions
+that build these bindings by introspecting their layer.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from ..driver import Driver, Job
+
+
+@dataclass
+class Signal:
+    name: str
+    read: Callable[[], Any]
+    type: str = "number"
+    unit: str | None = None
+    notes: str | None = None
+
+    def spec(self) -> dict:
+        return _clean({"name": self.name, "type": self.type, "unit": self.unit, "notes": self.notes})
+
+
+@dataclass
+class Setting:
+    name: str
+    write: Callable[[Any], None]
+    read: Callable[[], Any] | None = None
+    type: str = "number"
+    unit: str | None = None
+    limits: dict | None = None
+    approval: str = "auto"
+    interlocks: list[str] = field(default_factory=list)
+    notes: str | None = None
+
+    def spec(self) -> dict:
+        return _clean({"name": self.name, "type": self.type, "unit": self.unit, "limits": self.limits,
+                       "approval": self.approval, "interlocks": self.interlocks or None, "notes": self.notes})
+
+
+@dataclass
+class Action:
+    name: str
+    run: Callable[[Job, dict], Any]          # run(job, params) -> result; may call driver.progress(job, x)
+    duration: str = "short"
+    approval: str = "auto"
+    interlocks: list[str] = field(default_factory=list)
+    params: dict | None = None
+    limits: dict | None = None
+    examples: list[dict] | None = None
+    concurrent: bool = False
+    notes: str | None = None
+
+    def spec(self) -> dict:
+        return _clean({"name": self.name, "duration": self.duration, "approval": self.approval,
+                       "interlocks": self.interlocks or None, "params": self.params, "limits": self.limits,
+                       "examples": self.examples, "concurrent": self.concurrent or None, "notes": self.notes})
+
+
+def _clean(d: dict) -> dict:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+class BoundDriver(Driver):
+    """A Driver assembled from bindings. Works with every transport and the directory."""
+
+    def __init__(self, device: dict, signals: list[Signal] = (), settings: list[Setting] = (),
+                 actions: list[Action] = (), *, physical: dict | None = None, safety: dict | None = None,
+                 estop: Callable[[], None] | None = None, setup: Callable[[], None] | None = None,
+                 extra: dict | None = None):
+        self._signals = {s.name: s for s in signals}
+        self._settings = {s.name: s for s in settings}
+        self._actions = {a.name: a for a in actions}
+        self._estop_fn, self._setup_fn = estop, setup
+        interlocks = sorted({i for b in [*settings, *actions] for i in b.interlocks})
+        self.descriptor = {
+            "device": device,
+            "physical": physical or {},
+            "signals": [s.spec() for s in signals],
+            "settings": [s.spec() for s in settings],
+            "actions": [a.spec() for a in actions],
+            "safety": {"estop": estop is not None, "interlocks": interlocks, **(safety or {})},
+            **(extra or {}),
+        }
+        super().__init__()
+
+    def setup(self):
+        if self._setup_fn:
+            self._setup_fn()
+
+    def on_read(self, name):
+        if name in self._signals:
+            return self._signals[name].read()
+        s = self._settings.get(name)
+        if s and s.read:
+            return s.read()
+        raise KeyError(name)
+
+    def on_write(self, name, value):
+        self._settings[name].write(value)
+
+    def on_invoke(self, job: Job):
+        return self._actions[job.action].run(job, job.params)
+
+    def on_estop(self):
+        if self._estop_fn:
+            self._estop_fn()
+
+
+def params_from_signature(fn: Callable, skip: tuple[str, ...] = ("self",)) -> dict:
+    """Best-effort MHP `params` doc from a Python signature."""
+    import inspect
+    out = {}
+    try:
+        sig = inspect.signature(fn)
+    except (TypeError, ValueError):
+        return out
+    for n, p in sig.parameters.items():
+        if n in skip or p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD):
+            continue
+        ann = "" if p.annotation is inspect._empty else getattr(p.annotation, "__name__", str(p.annotation))
+        dflt = "" if p.default is inspect._empty else f" (default {p.default!r})"
+        out[n] = (ann + dflt).strip() or "any"
+    return out

openmhp-0.3.0/openmhp/adapters/madsci.py

@@ -0,0 +1,111 @@
+"""MADSci node -> MHP.
+
+    from openmhp.adapters.madsci import madsci_node
+    dev = madsci_node("http://192.168.1.40:2000",
+                      device={"id": "pf400-01", "class": "robot_arm", "location": "bay 2",
+                              "notes": "MADSci-managed PF400."})
+
+MADSci nodes already speak REST with an action vocabulary, so the adapter
+reads the node's own description and needs no hand-written bindings:
+
+    GET  {url}/info          node info incl. actions and their args   -> MHP actions
+    GET  {url}/state         node state dict                          -> MHP signals (one per key)
+    GET  {url}/status        node status (busy, errored, ...)         -> MHP state
+    POST {url}/action        {"action_name", "args"}                  <- actions/invoke
+    GET  {url}/action/{id}   action result / status                    -> jobs/progress
+    POST {url}/admin/{cmd}   safety_stop, reset                        <- safety/estop, safety/reset
+
+Path names are class attributes so a lab can adjust them if its MADSci
+version differs. `http` may be injected (any object with get/post returning
+JSON-able dicts) for tests.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+
+from .base import Action, BoundDriver, Signal
+
+
+class _Http:
+    def __init__(self, base: str, timeout: float = 30):
+        self.base, self.timeout = base.rstrip("/"), timeout
+
+    def _req(self, method, path, body=None):
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(self.base + path, data=data, method=method,
+                                     headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=self.timeout) as r:
+            raw = r.read()
+            return json.loads(raw) if raw else {}
+
+    def get(self, path):        return self._req("GET", path)
+    def post(self, path, body=None): return self._req("POST", path, body or {})
+
+
+class MadsciPaths:
+    info, state, status, action, action_result, admin = "/info", "/state", "/status", "/action", "/action/{id}", "/admin/{cmd}"
+
+
+def madsci_node(url: str, *, device: dict, http=None, paths: type = MadsciPaths, poll_s: float = 0.5,
+                approval: dict | None = None, physical: dict | None = None) -> BoundDriver:
+    http = http or _Http(url)
+    info = http.get(paths.info)
+    approval = approval or {}
+    node_actions = info.get("actions") or {}
+    if isinstance(node_actions, list):                     # some versions return a list of {name, args, description}
+        node_actions = {a["name"]: a for a in node_actions}
+
+    state_keys = list((http.get(paths.state) or {}).keys())
+
+    def sig(key):
+        return Signal(key, read=lambda: (http.get(paths.state) or {}).get(key), type="string")
+
+    def action(name, meta):
+        def run(job, params):
+            res = http.post(paths.action, {"action_name": name, "args": params})
+            aid = res.get("action_id") or res.get("id")
+            status = res.get("status")
+            while aid and status not in ("succeeded", "failed", "cancelled", None):
+                time.sleep(poll_s)
+                res = http.get(paths.action_result.format(id=aid))
+                status = res.get("status")
+                if job.cancel_requested:
+                    break
+            if status == "failed":
+                raise RuntimeError(res.get("errors") or res.get("error") or "MADSci action failed")
+            return res
+        args = meta.get("args") or {}
+        params = {k: (v.get("description") or v.get("type") or "any") if isinstance(v, dict) else str(v) for k, v in args.items()} or None
+        return Action(name, run=run, duration="long", params=params, approval=approval.get(name, "auto"),
+                      notes=meta.get("description"))
+
+    dev = dict(device)
+    dev.setdefault("make", "MADSci")
+    dev.setdefault("model", info.get("node_type") or info.get("module_name") or "node")
+
+    driver = BoundDriver(
+        device=dev, physical=physical,
+        signals=[sig(k) for k in state_keys],
+        actions=[action(n, m if isinstance(m, dict) else {}) for n, m in node_actions.items()],
+        estop=lambda: http.post(paths.admin.format(cmd="safety_stop")),
+        extra={"madsci": {"url": url, "node_id": info.get("node_id")}},
+    )
+
+    # MADSci also knows whether it is busy: fold that into the MHP state on ping.
+    _ping = driver.rpc_ping
+
+    def rpc_ping(p, client):
+        out = _ping(p, client)
+        try:
+            st = http.get(paths.status) or {}
+            if st.get("errored"):
+                out["madsci"] = "errored"
+            elif st.get("busy") and out["state"] == "idle":
+                out["state"] = "busy"
+        except Exception:                                    # noqa: BLE001
+            pass
+        return out
+    driver.rpc_ping = rpc_ping
+    return driver