pyshal 0.1.0__py3-none-any.whl

pyshal-0.1.0.dist-info/METADATA

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: pyshal
+Version: 0.1.0
+Summary: System/Software Hardware Abstraction Layer — device-tree-inspired, dynamic, user-space, network-capable
+Author: SHAL contributors
+License: MIT
+Project-URL: Documentation, https://github.com/determlab/shal#readme
+Project-URL: Changelog, https://github.com/determlab/shal/blob/main/CHANGELOG.md
+Project-URL: Source, https://github.com/determlab/shal
+Keywords: hardware,hal,device-tree,i2c,spi,ssh,embedded,lab-automation,robotics,instrumentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# SHAL
+
+### Give an AI agent real hardware — gated, so it asks before it moves.
+
+Describe your whole lab — sensors, instruments, robots, services — in **one YAML
+file**, and hand it to an LLM as **typed, permission-gated tools**: writes stop
+for approval before they reach the device; reads don't. No transport code, no glue.
+
+> In a blind test, an agent wrote working, safety-checked drivers for **4 of 4**
+> devices from documentation alone — then drove a **real robot, gated**.
+
+<!-- BADGES -->
+[![GitHub stars](https://img.shields.io/github/stars/determlab/shal?style=social)](https://github.com/determlab/shal)
+[![PyPI](https://img.shields.io/badge/PyPI-coming_soon-blue)](#install)
+[![Python](https://img.shields.io/badge/python-3.10+-blue)](#install)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#roadmap)
+
+<picture>
+  <source srcset="docs/assets/SHAL_banner.webp" type="image/webp">
+  <img alt="SHAL turns your lab and services into one YAML topology — controlled from Python or exposed to an AI agent as typed, gated tools" src="docs/assets/SHAL_banner.png" width="100%">
+</picture>
+
+
+### [→ Try it in 60 seconds — no hardware required](#quick-start)
+
+</div>
+
+**Built for:**
+
+✓ AI agent builders &nbsp;·&nbsp; ✓ Validation & test engineers &nbsp;·&nbsp;
+✓ Hardware-in-the-loop automation &nbsp;·&nbsp; ✓ Labs with mixed hardware + software
+
+---
+
+## From glue scripts to agent tools — in three steps
+
+**Step 1 · Today, without SHAL** — a separate library, address, and retry per device:
+
+```python
+sensor  = TMP102(i2c_bus, 0x48)
+supply  = SCPIPowerSupply("10.0.0.50:5025")
+results = RESTClient("https://mes.lab.internal")
+# ...and you wire each one's retries, logging, and tool-wrapper by hand
+```
+
+**Step 2 · With SHAL** — describe the rack once, then call devices by name:
+
+```python
+hal = shal.load("lab.yaml")
+
+hal.get_device("ambient_temp").read_celsius()       # I²C sensor
+hal.get_device("dut_power").set_voltage(3.3)        # SCPI supply
+hal.get_device("results_db").record(status="pass")  # HTTP service
+```
+
+> **Validation & test engineers can stop here.** One model for the whole rack —
+> no agent needed, no transport code, no glue.
+
+**Step 3 · Hand the same rack to an agent** — the tool catalog is generated for you:
+
+```python
+tools = hal.tool_schemas()                           # one typed tool per device op
+hal.call_tool("dut_power__set_voltage", {"volts": 3.3})
+```
+
+> Writes are gated, reads aren't. The agent never sees SCPI, I²C, or an address.
+
+---
+
+## Why existing agent frameworks fall short
+
+Most agent tooling assumes **software-only** tools: APIs, databases, functions.
+The moment a tool is a *physical* device — a sensor on I²C, an instrument over a
+raw socket, a robot behind a network hop — you're on your own.
+
+SHAL exposes physical devices, remote labs, instruments, **and** software
+services as the *same* kind of tool — with the safety rails physical actions
+need: gated writes, honest failure, a full audit trail.
+
+---
+
+## One model for hardware *and* software
+
+The core idea is small:
+
+> **A bus is just a node that provides a transport to its children.**
+
+A sensor on I²C and an HTTP service are the same kind of node. Your code — and
+your agent — calls **capabilities** (`read_celsius()`, `set_voltage()`), never
+transports. `[core]` ships with SHAL; `[pkg]` is a driver you install or write.
+
+```yaml
+# lab.yaml — hardware and software in ONE graph
+shal_version: 1
+root:
+  bench:                         # one SSH hop to the bench controller       [core]
+    driver: shal,ssh-host
+    address: ${BENCH_SSH}        # secrets resolve from the environment, never logged
+    children:
+      i2c0:                      # I²C rendered as argv over the SSH hop      [core]
+        driver: shal,i2c-cli
+        address: /dev/i2c-1
+        children:
+          ambient: { id: ambient_temp, driver: ti,tmp102, address: 0x48 }   # [core]
+
+  instruments:                   # raw-socket SCPI bus                        [pkg]
+    driver: acme,scpi
+    address: 10.0.0.50:5025
+    children:
+      supply: { id: dut_power, driver: keysight,e36312, address: ch1 }       # [pkg]
+
+  services:                      # HTTPS to internal services                [core]
+    driver: shal,http
+    address: https://mes.lab.internal
+    children:
+      results: { id: results_db, driver: acme,mes-results, address: api/v2 } # [pkg]
+```
+
+Every node is reached the same way — `hal.get_device("dut_power").set_voltage(3.3)`
+— sensor or database, local or across the network. Same retries, same logs. Swap
+any node for its sim and **nothing in your code changes**.
+
+---
+
+## Features
+
+- **Agent-native** — every device op becomes a gated LLM tool.
+- **Asks before it moves** — actuator & destructive/config ops stop for a
+  host-supplied approver (CLI prompt, an agent, or auto in sim/CI); the gate is
+  pre-I/O and unbypassable.
+- **Hardware + software, one graph** — a sensor and an HTTP service are the same node.
+- **Capabilities, not wires** — call `read_celsius()`, never I²C.
+- **Retry you can trust** — reads auto-retry; risky writes never silently repeat.
+- **Sim-first** — test the whole rack with zero hardware.
+- **Recursive** — muxes, jumpboxes, nested buses: one primitive, no special cases.
+- **Drivers as plugins** — add a device in one small class.
+- **Secure by default** — no shell strings, TLS on, secrets via `${ENV}`.
+- **Observable** — structured logs, one `txn` id per call.
+
+---
+
+## Install
+
+> SHAL is in **alpha** (Phase 1). A PyPI release is coming; for now install from
+> source:
+
+```bash
+pip install git+https://github.com/determlab/shal
+
+# or, for development
+git clone https://github.com/determlab/shal && cd shal
+pip install -e ".[dev]"                                  # pytest, ruff
+```
+
+Requires **Python ≥ 3.10**. Dependencies: `pyyaml`, `jsonschema`.
+
+---
+
+## Quick Start
+
+Runs with **zero hardware** — the simulated bus ships with SHAL. New to hardware?
+This is the whole setup, and it's just Python and a YAML file.
+
+```yaml
+# sim.yaml
+shal_version: 1
+root:
+  bus:
+    driver: shal,sim-i2c
+    address: sim0
+    children:
+      temp0:
+        id: ambient_temp
+        driver: ti,tmp102
+        address: 0x48
+```
+
+```python
+import shal
+
+with shal.load("sim.yaml") as hal:
+    print(hal.get_device("ambient_temp").read_celsius())   # 25.0
+```
+
+```bash
+$ python quickstart.py
+25.0
+```
+
+When the real board arrives, change `shal,sim-i2c` → `shal,i2c-cli`. **Your
+Python doesn't change.**
+
+---
+
+## Write a driver in 30 seconds
+
+Need a device SHAL doesn't have yet? A driver is one small class. This is the
+*entire* bundled temperature-sensor driver:
+
+```python
+from shal import Driver, TemperatureSensor, registry, idempotent, op, ByteTransport, Read, Write
+
+@registry.register
+class Tmp102(Driver, TemperatureSensor):
+    compatible = "ti,tmp102"          # matched against the YAML `driver:` field
+    kind = ByteTransport
+    llm_ready = True
+
+    @idempotent                        # a read: safe to auto-retry across drops
+    @op("Read the ambient temperature now.", unit="celsius", side_effect="none")
+    def read_celsius(self) -> float:
+        raw = self.bus.txn(self.addr, [Write(b"\x00"), Read(2)])
+        return ((raw[0] << 4) | (raw[1] >> 4)) * 0.0625
+```
+
+That's it — register the `compatible`, implement the capability. The `@op`
+metadata is what makes it show up as a gated agent tool. SHAL discovers your
+driver via the `shal.drivers` entry point.
+
+---
+
+## How It Works
+
+A topology is a tree, and **every edge is a bus** — itself a node that carries
+traffic to its children. You call a capability; SHAL translates it down the stack
+to the wire and hands the result back up. No layer leaks into the one above.
+
+```mermaid
+sequenceDiagram
+    participant U as Your code
+    participant T as tmp102 driver
+    participant I as i2c-cli bus
+    participant S as ssh-host bus
+    U->>T: read_celsius()
+    T->>I: read register 0x00
+    I->>S: i2ctransfer 0x48 … (argv)
+    Note over S: runs on lab_server
+    S-->>I: raw bytes
+    I-->>T: raw bytes
+    T-->>U: 22.5 °C
+```
+
+Because every hop is the same primitive, an SSH jumpbox, an I²C mux, and an
+in-process sim all compose — no special cases.
+
+---
+
+## Core Concepts
+
+| Concept | What it means |
+|---|---|
+| **Node** | Anything in the tree: a device, a bus, a board. |
+| **Bus** | A node that provides a transport to its children (I²C, SSH, HTTP…). |
+| **Driver** | Bound to a node by its `compatible` string. Implements a capability. |
+| **Capability** | The typed API your code calls (`read_celsius()`), independent of transport. |
+| **id vs path** | `id` is a stable name for lookup; `path` is where it sits. Move a device, keep its `id`. |
+
+```python
+hal.get_device("ambient_temp").read_celsius()   # by semantic id — no wires leak in
+```
+
+---
+
+## Real-World Use Cases
+
+- **AI agents with real-world access** — expose a lab or robot to an LLM as
+  gated tools; every actuator call stops for a human (or policy) to approve
+  before it fires, and a delivery-unknown write is never silently retried.
+- **Validation & test racks** — one model for eval boards, instruments, and the
+  results database; test against sims in CI before hardware.
+- **Manufacturing lines** — same capability calls across stations; one audit
+  trail (`shal.audit`) for every actuator command.
+- **Remote & distributed setups** — drive hardware behind an SSH jumpbox with
+  nothing on the far side but standard CLI tools.
+- **Robotics bringup** — start against a sim, swap in transports as boards land,
+  without rewriting control code.
+
+---
+
+## FAQ
+
+**Why not just wrap Python libraries as agent tools myself?**
+You can — until there are ten devices on four transports, some behind an SSH hop,
+some not. Then you're hand-maintaining a tool wrapper, address, retry policy, and
+audit log *per device*. SHAL generates all of it from one topology.
+
+**Is it production-ready?**
+It's **alpha** (Phase 1). The synchronous core — topology, drivers, buses, retry
+policy, and the agent tool surface — is real and tested. Async/streaming, the
+actuator watchdog, and route failover are Phase 2 ([roadmap](#roadmap)).
+
+**Do I need real hardware to try it?**
+No. The bundled simulated bus runs the [Quick Start](#quick-start) with zero
+hardware — swap in a real transport later, and your code doesn't change.
+
+---
+
+## Roadmap
+
+**Shipped — Phase 1 (synchronous core, v0.1.0):**
+
+- ✅ Declarative YAML topology: JSON-Schema validation, `id`/`path`/`$ref`,
+  `${ENV}` secrets, reusable `template:` includes
+- ✅ Bundled buses: `sim-i2c`, `local`, `ssh-host`, `i2c-cli`, `spi-cli`,
+  `tcp` (TLS), `http`, `nxp,pca9548` mux
+- ✅ Capability model, driver plugin registry, trustworthy retry policy
+- ✅ Agent tool surface: `tool_schemas()` / `tool_catalog()` / `call_tool()`
+- ✅ Human-in-the-loop actuation gate: actuator ops stop for an injectable
+  `Approver` (pre-I/O, unbypassable, every decision audited)
+- ✅ Structured observability + `capture()` flight recorder
+
+**Designed, in progress — Phase 2:**
+
+- 🚧 Async / streaming (`subscribe`, held channels) — [spec](docs/DESIGN%20-%20PHASE%202%20ASYNC.md)
+- 🚧 Actuator watchdog & safe-state (timeouts, auto safe-state on disconnect)
+- 🚧 Route failover for multi-path devices
+
+---
+
+## Documentation
+
+- [Architecture & locked decisions](docs/DESIGN%20V2.md)
+- [Phase 1 implementation decisions](docs/DECISIONS%20-%20V2.1.md)
+- [Phase 2 async + watchdog spec](docs/DESIGN%20-%20PHASE%202%20ASYNC.md)
+- Build guides: write a [driver](.claude/skills/shal-build-driver/SKILL.md),
+  a [bus](.claude/skills/shal-build-bus/SKILL.md), or a
+  [topology](.claude/skills/shal-build-yaml/SKILL.md)
+
+---
+
+## Contributing
+
+Contributions welcome — **new drivers and buses especially**. A driver is one
+small class (see [above](#write-a-driver-in-30-seconds)); SHAL discovers it via
+the `shal.drivers` entry point.
+
+```bash
+pip install -e ".[dev]"
+python -m pytest          # test suite
+ruff check src tests      # lint
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+---
+
+## License
+
+[MIT](LICENSE).

pyshal-0.1.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+pyshal-0.1.0.dist-info/licenses/LICENSE,sha256=tdL5yHCYzaznc1F7JtcuLha1ygaVGwEk3XBgL_HOUfs,1074
+shal/__init__.py,sha256=5R7SUSSTGranj_4tGejYo13kU3JiyHviLicpEhwfW88,1711
+shal/approval.py,sha256=5sydRVaTpKqzh-w4e_amPXHZD7nWB7XGEV1Y7tEsxFU,5341
+shal/capabilities.py,sha256=qf4vLhiuCpace1nG7auEW5x-tQW7A3gcls2sihq3JZY,2232
+shal/conformance.py,sha256=JpOcciSo-Os-oyjYEdMIdQVPKiKTU3985SI4JP6NBH0,10514
+shal/driver.py,sha256=AdrQrIfCjUDwHEYA7np-RCPvZh_9gHxmQIfMaNvg_04,15500
+shal/errors.py,sha256=0vreTxdOOq8lHpZ8n5d2S8qsVUdMb2h5W4XtgMrVL6w,2944
+shal/hal.py,sha256=UFLeqgkL9CVCC05d3mpIugJHz9-uS0C5kYlgJPQAVY0,9785
+shal/limits.py,sha256=i4l_7linn0Nptf-JaHoE04Aybp8njgRXOrYkjNHeeug,8806
+shal/loader.py,sha256=RMFuoOlDk3bA1zPrnHI3D06RjWKHZKTZv7YlwdpCWaQ,9890
+shal/log.py,sha256=y1UR2GLnbIQQupHRTrgdyNHys3XPMQ1FqZm6TEhwYAk,2958
+shal/logging.py,sha256=FZsiawuvJJrkABwT1MP5z8mwo4PYckG3BDJsBIRBkm0,4313
+shal/node.py,sha256=UfqFsAkHYrOGCZmrlNCuiOnmwA8WnhKMCyDyt1y0pcc,2503
+shal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+shal/registry.py,sha256=e10azuG4aqT95AWxpIFqRN7VyU_fScvVRh1B5TUa8oI,8624
+shal/transport.py,sha256=zomnaUkc-2JPhP2k6wxaijQtuXKsoml7E7DeQm5JTDo,3312
+shal/buses/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+shal/buses/http_bus.py,sha256=EkkbxAUrVJh3-G-9hi4lKYnLJe5U725bV4lGRoLc4X4,3390
+shal/buses/i2c_cli.py,sha256=ZoqNj6Jfgq1IlT_1CvOMy5ppNIZt4Evsrinf93md3IM,3612
+shal/buses/local.py,sha256=Tqv6tiKI_B5wJtwk8BJFKCz74c3SE_-6RjBREL9Nc00,2113
+shal/buses/mux.py,sha256=Yw1xQXD5gNBRAw913ALmH4vcm0zQg4CEF1XhOjwGuNg,3031
+shal/buses/scpi_raw.py,sha256=9VwrMq_-8XxEuYBXzcJutCnJXjyZLWcJdjpQFMh1sls,4694
+shal/buses/sim.py,sha256=9n7L6QeVh_ifEUDLBPlVCQ5aiQLn751sa1zwH1_apEA,8555
+shal/buses/sim_msg.py,sha256=SIHUsn9X2Vnl9ETmPLtfz6QvvDRn00isP8HcMyCBGa8,4072
+shal/buses/sim_scpi.py,sha256=t7hGEZu8K-mu4ZsLGB7OoB0Dr941Dc0VSzzRBeEKwN4,5355
+shal/buses/spi_cli.py,sha256=CBvxbeXge0LzbfRASd4MjgZOiwxQIIb7X1uoo9AMZQ4,2554
+shal/buses/ssh.py,sha256=JWBgu24H5ALYzv7AvAfXHHtj-efJRcasM4mQqJ1Dd6o,3254
+shal/buses/tcp.py,sha256=GuwKtIDGrigtaN7_FSHOugdFJsYRGb4yymtiZUGNX4g,4008
+shal/drivers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+shal/drivers/ads1115.py,sha256=9advweCf_rio2WP2tr44gktwA-X4epcHUFzCdKRL7tM,1824
+shal/drivers/ina219.py,sha256=366uXJQlQovQzGhIomByMQ6uSRaKMZfGoxbPPY9wgsM,2109
+shal/drivers/keysight_34461a.py,sha256=4qJmLQfaAbVgW-_OhbhCPrbpfAp-8ITPggUnGbs6m84,1549
+shal/drivers/mcp23017.py,sha256=GnncKWhhK1pv7WjTw14kgMIpWJ79kCcp6tz3DPN-Jww,2064
+shal/drivers/mcp9808.py,sha256=jrQM38T_hm02K7LxujtLxTBlvdUnfOMeScEvqNh0fmE,1423
+shal/drivers/rigol_dp832.py,sha256=0LeJ6l57lAD69YPsKm0TGnykIwdBKaukPbm7mz9YdpM,2327
+shal/drivers/tmp102.py,sha256=7bHigCQeBsf89-vvJzKpDhN7X4CNlCa_1A6c-WBNCOI,1198
+shal/schema/shal-v1.schema.json,sha256=tavFK3gzhvkWBjO-LFC28X6RfzvZqnLE9vjBnj380C0,5083
+pyshal-0.1.0.dist-info/METADATA,sha256=wneLnQ77fVdh9WOZ1whHUiaIiWlWSdkHOU8UFE8gn9s,14056
+pyshal-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pyshal-0.1.0.dist-info/entry_points.txt,sha256=ZZAbTDE3HcMCZ2IjLpPXM8EEXlAKe9JSGGIOIVNtH3g,801
+pyshal-0.1.0.dist-info/top_level.txt,sha256=229u67H27LrLF5xo7mG607l1XRGqy4gjYx5dHPtRvXk,5
+pyshal-0.1.0.dist-info/RECORD,,

pyshal-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyshal-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,19 @@
+[shal.drivers]
+keysight,34461a = shal.drivers.keysight_34461a:Keysight34461a
+microchip,mcp23017 = shal.drivers.mcp23017:Mcp23017
+microchip,mcp9808 = shal.drivers.mcp9808:Mcp9808
+nxp,pca9548 = shal.buses.mux:Pca9548
+rigol,dp832 = shal.drivers.rigol_dp832:RigolDp832
+shal,http = shal.buses.http_bus:HttpBus
+shal,i2c-cli = shal.buses.i2c_cli:I2cCliBus
+shal,local = shal.buses.local:LocalBus
+shal,scpi-raw = shal.buses.scpi_raw:ScpiRawBus
+shal,sim-i2c = shal.buses.sim:SimI2cBus
+shal,sim-msg = shal.buses.sim_msg:SimMsgBus
+shal,sim-scpi = shal.buses.sim_scpi:SimScpiBus
+shal,spi-cli = shal.buses.spi_cli:SpiCliBus
+shal,ssh-host = shal.buses.ssh:SshBus
+shal,tcp = shal.buses.tcp:TcpBus
+ti,ads1115 = shal.drivers.ads1115:Ads1115
+ti,ina219 = shal.drivers.ina219:Ina219
+ti,tmp102 = shal.drivers.tmp102:Tmp102

pyshal-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SHAL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyshal-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+shal

shal/__init__.py

@@ -0,0 +1,65 @@
+"""SHAL — System/Software Hardware Abstraction Layer.
+
+    import shal
+    with shal.load("setup.yaml") as hal:
+        print(hal.get_device("ambient_temp").read_celsius())
+"""
+from . import logging  # opt-in observability: shal.logging.{Console,JSON}Formatter, capture
+from .approval import (
+    ApprovalRequest,
+    Approver,
+    AutoApprove,
+    CallableApprover,
+    ConsoleApprover,
+    DenyAll,
+    approver,
+    get_approver,
+    set_approver,
+)
+from .capabilities import (
+    ADC,
+    DigitalMultimeter,
+    GPIOExpander,
+    PowerMonitor,
+    PowerSupply,
+    TemperatureSensor,
+)
+from .driver import Driver, idempotent, op
+from .errors import (
+    ApprovalDenied,
+    Busy,
+    Error,
+    Gap,
+    HopError,
+    HopTimeout,
+    LimitError,
+    LoadError,
+)
+from .hal import Hal, load
+from .node import Node
+from .registry import catalog, register
+from .transport import (
+    ByteTransport,
+    CommandTransport,
+    Completed,
+    MessageTransport,
+    Op,
+    Read,
+    Stream,
+    Transport,
+    Write,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "load", "Hal", "Node", "Driver", "idempotent", "op", "register", "catalog", "logging",
+    "Approver", "ApprovalRequest", "AutoApprove", "DenyAll", "CallableApprover",
+    "ConsoleApprover", "set_approver", "get_approver", "approver",
+    "Error", "LoadError", "HopError", "HopTimeout", "LimitError", "ApprovalDenied",
+    "Busy", "Gap",
+    "Transport", "ByteTransport", "CommandTransport", "MessageTransport",
+    "Stream", "Op", "Read", "Write", "Completed",
+    "TemperatureSensor", "PowerMonitor", "PowerSupply", "DigitalMultimeter",
+    "ADC", "GPIOExpander", "__version__",
+]

shal/approval.py

@@ -0,0 +1,143 @@
+"""Human-in-the-loop actuation gate (issue #14).
+
+SHAL's promise — "it asks permission before it moves" — is enforced HERE, at the
+same capability-wrapper chokepoint where limits and audit already fire. For an op
+whose effective ``side_effect`` is ``"actuator"`` (physical motion), the wrapper
+consults the active :class:`Approver` AFTER the limit check and BEFORE any bus
+I/O. Because the gate lives in the wrapper, NO call path can bypass it — the tool
+surface (``hal.call_tool``) and the raw path (``get_device().method()``) go
+through the exact same enforcement.
+
+SHAL ships the *mechanism* and a *safe default* (ask on the terminal when
+interactive; deny when there is no one to ask — a pipe, a cron job, CI). The host
+injects the *decision*:
+
+    import shal
+    shal.set_approver(shal.AutoApprove())          # sim / CI / tests
+    with shal.approver(MyNanoClawApprover()):       # scoped policy
+        ...
+
+Order is always **limits -> approval -> I/O**: an impossible call is rejected by
+limits before anyone is asked to approve it. Every decision (allow or deny) is
+written to ``shal.audit`` so runs stay deterministic and replayable.
+"""
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class ApprovalRequest:
+    """What the wrapper hands an Approver. Immutable, fully self-describing so a
+    decision can be made (and logged) without reaching back into framework state."""
+    op: str
+    path: str
+    id: str
+    side_effect: str
+    params: dict
+    txn: str
+
+
+@runtime_checkable
+class Approver(Protocol):
+    """A policy that decides whether a side-effecting op may proceed.
+
+    Return ``True`` to allow, ``False`` to deny. Raising is treated by the caller
+    as a hard failure (not a denial) — return ``False`` to refuse cleanly."""
+
+    def approve(self, request: ApprovalRequest) -> bool: ...
+
+
+class AutoApprove:
+    """Allow every actuation. For sim, CI, and tests — never production."""
+
+    def approve(self, request: ApprovalRequest) -> bool:
+        return True
+
+
+class DenyAll:
+    """Refuse every actuation. The safest possible policy."""
+
+    def approve(self, request: ApprovalRequest) -> bool:
+        return False
+
+
+class CallableApprover:
+    """Adapt a plain ``fn(request) -> bool`` into an Approver (e.g. a NanoClaw
+    callback, a queue handoff, a custom prompt)."""
+
+    def __init__(self, fn: Callable[[ApprovalRequest], bool]) -> None:
+        self._fn = fn
+
+    def approve(self, request: ApprovalRequest) -> bool:
+        return bool(self._fn(request))
+
+
+class ConsoleApprover:
+    """Ask on the terminal. The shipped default.
+
+    If the input stream is not a TTY (a pipe, cron, CI), there is no one to
+    answer, so it DENIES — never block a headless run on an unanswerable prompt.
+    Inject :class:`AutoApprove` for those environments.
+    """
+
+    def __init__(self, *, stream=None, prompt: Callable[[str], str] = input) -> None:
+        self._stream = stream
+        self._prompt = prompt
+
+    def approve(self, request: ApprovalRequest) -> bool:
+        stream = self._stream or sys.stdin
+        if not getattr(stream, "isatty", lambda: False)():
+            return False  # no one to ask -> don't move
+        args = ", ".join(f"{k}={v!r}" for k, v in request.params.items())
+        who = request.id or request.path
+        banner = (f"\n  SHAL approval required [{request.side_effect}]\n"
+                  f"    {who}.{request.op}({args})\n"
+                  f"  Allow this actuation? [y/N] ")
+        try:
+            answer = self._prompt(banner)
+        except EOFError:
+            return False
+        return answer.strip().lower() in ("y", "yes")
+
+
+# The active policy. The default is safe: prompt when interactive, deny otherwise.
+# (ContextVar default must be immutable per flake8-bugbear; resolve the singleton
+# in get_approver() so an unset context falls back to ConsoleApprover.)
+_DEFAULT: Approver = ConsoleApprover()
+_current: ContextVar[Approver | None] = ContextVar("shal_approver", default=None)
+
+
+def get_approver() -> Approver:
+    """The Approver the wrapper will consult for the current context."""
+    return _current.get() or _DEFAULT
+
+
+def set_approver(approver: Approver) -> Token:
+    """Install ``approver`` as the active policy. Returns a token for ``reset``.
+
+    Note: the policy lives in a :class:`~contextvars.ContextVar`. A newly spawned
+    OS thread does NOT inherit the caller's context, so it falls back to the safe
+    default (deny-when-headless) until you call ``set_approver`` inside that
+    thread. ``asyncio`` tasks created with the running loop DO inherit it."""
+    return _current.set(approver)
+
+
+def reset(token: Token) -> None:
+    """Undo a :func:`set_approver`, restoring the previous policy."""
+    _current.reset(token)
+
+
+@contextmanager
+def approver(a: Approver):
+    """Scope an Approver to a ``with`` block; the previous policy is restored on exit."""
+    token = _current.set(a)
+    try:
+        yield a
+    finally:
+        _current.reset(token)