halyn 0.2.2__tar.gz → 0.3.0__tar.gz

halyn-0.3.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: halyn
+Version: 0.3.0
+Summary: Halyn — NRP control plane with domain-scoped authorization.
+Author-email: Elmadani SALKA <contact@halyn.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/ElmadaniS/halyn
+Project-URL: Repository, https://github.com/ElmadaniS/halyn
+Project-URL: Issues, https://github.com/ElmadaniS/halyn/issues
+Keywords: ai,browser,robotics,iot,mcp,nrp,llm,infrastructure,devops
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nrprotocol>=0.1.0
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: enterprise
+Requires-Dist: grpcio>=1.60; extra == "enterprise"
+Requires-Dist: psycopg2-binary; extra == "enterprise"
+Requires-Dist: redis; extra == "enterprise"
+Provides-Extra: robotics
+Requires-Dist: rclpy; extra == "robotics"
+Requires-Dist: unitree-sdk2py; extra == "robotics"
+Provides-Extra: iot
+Requires-Dist: paho-mqtt; extra == "iot"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# Halyn
+
+**The AI control plane. Connect any device to any LLM.**
+
+[![PyPI](https://img.shields.io/pypi/v/halyn?style=flat-square&color=0a6e3f)](https://pypi.org/project/halyn/)
+[![License](https://img.shields.io/badge/license-MIT-0a6e3f?style=flat-square)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10+-0a6e3f?style=flat-square)](https://pypi.org/project/halyn/)
+
+12 drivers · 5 autonomy levels · tamper-evident audit · shield rules
+
+[Website](https://halyn.dev) · [Quickstart](#quickstart) · [Use Cases](#use-cases) · [Docs](docs/)
+
+</div>
+
+---
+
+## The Problem
+
+AI is moving into the physical world. Robots, drones, smart homes, factories, vehicles. But there's no universal way for an LLM to safely control hardware.
+
+MCP connects LLMs to software APIs. **Halyn connects LLMs to everything else** — servers, sensors, robots, serial ports, browsers, Docker containers. With safety built in at the protocol level.
+
+## Quickstart
+
+```bash
+pip install halyn
+```
+
+**Monitor a server in 5 lines:**
+
+```python
+from halyn import ControlPlane, SSHDriver
+
+cp = ControlPlane()
+cp.connect(SSHDriver("192.168.1.10", "admin"))
+print(cp.observe())  # → {"cpu": 23.4, "mem": 67.2, "disk": 45.1, ...}
+```
+
+**Control a Raspberry Pi GPIO:**
+
+```python
+from halyn import ControlPlane, SSHDriver
+
+cp = ControlPlane()
+cp.connect(SSHDriver("raspberrypi.local", "pi"))
+
+# Add a safety rule: never touch GPIO 4 (connected to emergency stop)
+cp.shield("deny gpio write 4")
+
+cp.act("gpio write 17 high")   # ✓ turns on LED
+cp.act("gpio write 4 low")     # ✗ blocked by shield rule
+```
+
+**Let Claude control your home lab:**
+
+```python
+from halyn import ControlPlane, SSHDriver, Autonomy
+
+cp = ControlPlane(autonomy=Autonomy.SUPERVISED)  # AI proposes, human approves
+cp.connect(SSHDriver("homelab.local", "admin"))
+
+# Shield: read-only on production, full access on staging
+cp.shield("deny * write /prod/*")
+cp.shield("allow * * /staging/*")
+
+# AI can now observe and propose actions
+# Human gets a prompt before anything executes
+```
+
+## 12 Drivers
+
+| Driver | What It Connects | Example |
+|--------|-----------------|---------|
+| `SSHDriver` | Any Linux/Mac server | Monitor servers, deploy code |
+| `HTTPDriver` | REST APIs, webhooks | Control smart home APIs |
+| `WebSocketDriver` | Real-time streams | Live sensor data |
+| `SerialDriver` | Arduino, Raspberry Pi, PLCs | Read sensors, control actuators |
+| `MQTTDriver` | IoT networks | Smart agriculture, building automation |
+| `OPCUADriver` | Industrial machines (Industry 4.0) | CNC, SCADA, factory equipment |
+| `ROS2Driver` | Robots (ROS ecosystem) | Robot arms, mobile robots, drones |
+| `DDSDriver` | Real-time distributed systems | Autonomous vehicles, defense |
+| `DockerDriver` | Containers and orchestration | Scale services, manage deployments |
+| `BrowserDriver` | Web automation | Fill forms, scrape data, test UIs |
+| `UnitreeDriver` | Unitree robots | Go2, B2, H1 quadrupeds and humanoids |
+| `SocketDriver` | Raw TCP/UDP | Custom hardware, legacy systems |
+
+## 5 Autonomy Levels
+
+| Level | Name | Who Decides | Use Case |
+|-------|------|-------------|----------|
+| 0 | **Manual** | Human does everything | Learning, debugging |
+| 1 | **Advisory** | AI suggests, human executes | Critical systems |
+| 2 | **Supervised** | AI executes, human approves first | Production ops |
+| 3 | **Monitored** | AI executes freely, human can intervene | Routine tasks |
+| 4 | **Autonomous** | AI decides within shield rules | Fully automated systems |
+
+## Shield Rules — Safety as Physics
+
+Shield rules aren't guidelines. They're constraints enforced at the protocol level. Your AI physically cannot violate them, regardless of its instructions.
+
+```python
+# Industrial safety
+cp.shield("deny actuator write pressure > 150")   # never exceed 150 PSI
+cp.shield("deny motor write speed > 3000")         # RPM limit
+cp.shield("require human_approval for emergency_stop disable")
+
+# Data safety
+cp.shield("deny * read /etc/shadow")
+cp.shield("deny * write /prod/database/*")
+cp.shield("deny * delete *")  # read-only mode
+
+# Rate limiting
+cp.shield("limit actions 10/minute")
+```
+
+## Audit Chain
+
+Every action Halyn executes is recorded in a tamper-evident SHA-256 chain. Nothing can be altered or deleted.
+
+```python
+# View the audit trail
+for entry in cp.audit.chain():
+    print(f"{entry.timestamp} | {entry.action} | {entry.result} | {entry.hash[:12]}")
+
+# 2026-03-17T01:30:00 | observe cpu     | 23.4%      | a3f8c9d1e2b4
+# 2026-03-17T01:30:01 | act restart nginx| success    | 7b2e4f6a8c0d
+# 2026-03-17T01:30:02 | observe cpu     | 12.1%      | e5d7c9b1a3f8
+```
+
+Perfect for compliance (SOC2, ISO 27001, GDPR audit trails).
+
+## Use Cases
+
+### 🏭 Smart Factory
+
+Connect AI to your factory floor. OPC-UA driver reads machine data. Shield rules prevent dangerous operations. Audit chain provides compliance trail.
+
+```python
+cp = ControlPlane(autonomy=Autonomy.MONITORED)
+cp.connect(OPCUADriver("opc.tcp://plc-01:4840"))
+cp.shield("deny * write temperature > 200")
+cp.shield("deny * write pressure > 150")
+
+# AI monitors machines, optimizes parameters within safe bounds
+# Every adjustment is audited
+```
+
+### 🌱 Precision Agriculture
+
+MQTT sensors across your field report soil moisture, temperature, weather. AI decides when to irrigate, which zones need attention.
+
+```python
+cp = ControlPlane()
+cp.connect(MQTTDriver("mqtt://field-gateway:1883"))
+cp.shield("limit irrigation 3/day")  # prevent overwatering
+cp.shield("deny irrigation if wind > 30")  # no sprinklers in wind
+
+data = cp.observe()  # reads all sensors
+# AI analyzes and triggers irrigation for dry zones
+```
+
+### 🏥 Patient Monitoring
+
+Serial connection to medical devices. AI watches vitals 24/7, alerts staff immediately when something changes. Shield rules ensure the AI can never modify device settings.
+
+```python
+cp = ControlPlane(autonomy=Autonomy.ADVISORY)  # AI advises only
+cp.connect(SerialDriver("/dev/ttyUSB0", baudrate=9600))
+cp.shield("deny * write *")  # read-only — AI cannot control the device
+
+vitals = cp.observe()  # heart rate, SpO2, blood pressure
+# AI detects anomaly → alerts nurse station
+```
+
+### 🤖 Robot Fleet
+
+ROS2 driver connects to any robot in the ROS ecosystem. Shield rules define the workspace. Consent protocol ensures robots agree before coordinating.
+
+```python
+cp = ControlPlane()
+cp.connect(ROS2Driver("robot-arm-01"))
+cp.connect(ROS2Driver("robot-arm-02"))
+
+cp.shield("deny movement outside workspace_bounds")
+cp.shield("deny force > 50N")  # collaborative robot limits
+
+# Consent: robots negotiate shared workspace access
+cp.consent("robot-arm-01", "robot-arm-02", scope="shared_zone_A")
+```
+
+### 🏠 Smart Home
+
+Connect every device in your home. Your AI assistant can control lights, thermostat, locks — but shield rules ensure it can never unlock doors at night or set the thermostat below 15°C.
+
+```python
+cp = ControlPlane()
+cp.connect(MQTTDriver("mqtt://home-hub:1883"))
+
+cp.shield("deny lock unlock between 23:00-06:00")
+cp.shield("deny thermostat write < 15")
+cp.shield("deny * * camera")  # AI has no camera access
+
+cp.act("lights living_room dim 40%")
+```
+
+### 🎓 Education
+
+Students learn AI-hardware interaction in 10 lines. Connect an Arduino, read a temperature sensor, make an LED blink based on AI decisions.
+
+```python
+from halyn import ControlPlane, SerialDriver
+
+cp = ControlPlane()
+cp.connect(SerialDriver("/dev/ttyACM0"))
+
+temp = cp.observe()["temperature"]
+if temp > 30:
+    cp.act("led on")   # too hot → warning LED
+else:
+    cp.act("led off")
+```
+
+## Built on NRP
+
+Halyn implements [NRP (Node Reach Protocol)](https://github.com/ElmadaniS/nrp) — 6 primitives that define how AI talks to hardware:
+
+| Primitive | Purpose |
+|-----------|---------|
+| **Manifest** | "I am" — device declares its identity and capabilities |
+| **Observe** | "I see" — read state without side effects |
+| **Act** | "I do" — execute an action on the device |
+| **Shield** | "I cannot" — enforceable constraints |
+| **Audit** | "I did" — tamper-evident action log |
+| **Consent** | "We agree" — mutual permission negotiation |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). We especially welcome new drivers and shield rule patterns.
+
+## License
+
+MIT — use it anywhere, for anything.
+
+---
+
+<div align="center">
+
+**[halyn.dev](https://halyn.dev)** · **contact@halyn.dev** · © 2026 Elmadani SALKA
+
+</div>

halyn-0.3.0/README.md

@@ -0,0 +1,252 @@
+<div align="center">
+
+# Halyn
+
+**The AI control plane. Connect any device to any LLM.**
+
+[![PyPI](https://img.shields.io/pypi/v/halyn?style=flat-square&color=0a6e3f)](https://pypi.org/project/halyn/)
+[![License](https://img.shields.io/badge/license-MIT-0a6e3f?style=flat-square)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10+-0a6e3f?style=flat-square)](https://pypi.org/project/halyn/)
+
+12 drivers · 5 autonomy levels · tamper-evident audit · shield rules
+
+[Website](https://halyn.dev) · [Quickstart](#quickstart) · [Use Cases](#use-cases) · [Docs](docs/)
+
+</div>
+
+---
+
+## The Problem
+
+AI is moving into the physical world. Robots, drones, smart homes, factories, vehicles. But there's no universal way for an LLM to safely control hardware.
+
+MCP connects LLMs to software APIs. **Halyn connects LLMs to everything else** — servers, sensors, robots, serial ports, browsers, Docker containers. With safety built in at the protocol level.
+
+## Quickstart
+
+```bash
+pip install halyn
+```
+
+**Monitor a server in 5 lines:**
+
+```python
+from halyn import ControlPlane, SSHDriver
+
+cp = ControlPlane()
+cp.connect(SSHDriver("192.168.1.10", "admin"))
+print(cp.observe())  # → {"cpu": 23.4, "mem": 67.2, "disk": 45.1, ...}
+```
+
+**Control a Raspberry Pi GPIO:**
+
+```python
+from halyn import ControlPlane, SSHDriver
+
+cp = ControlPlane()
+cp.connect(SSHDriver("raspberrypi.local", "pi"))
+
+# Add a safety rule: never touch GPIO 4 (connected to emergency stop)
+cp.shield("deny gpio write 4")
+
+cp.act("gpio write 17 high")   # ✓ turns on LED
+cp.act("gpio write 4 low")     # ✗ blocked by shield rule
+```
+
+**Let Claude control your home lab:**
+
+```python
+from halyn import ControlPlane, SSHDriver, Autonomy
+
+cp = ControlPlane(autonomy=Autonomy.SUPERVISED)  # AI proposes, human approves
+cp.connect(SSHDriver("homelab.local", "admin"))
+
+# Shield: read-only on production, full access on staging
+cp.shield("deny * write /prod/*")
+cp.shield("allow * * /staging/*")
+
+# AI can now observe and propose actions
+# Human gets a prompt before anything executes
+```
+
+## 12 Drivers
+
+| Driver | What It Connects | Example |
+|--------|-----------------|---------|
+| `SSHDriver` | Any Linux/Mac server | Monitor servers, deploy code |
+| `HTTPDriver` | REST APIs, webhooks | Control smart home APIs |
+| `WebSocketDriver` | Real-time streams | Live sensor data |
+| `SerialDriver` | Arduino, Raspberry Pi, PLCs | Read sensors, control actuators |
+| `MQTTDriver` | IoT networks | Smart agriculture, building automation |
+| `OPCUADriver` | Industrial machines (Industry 4.0) | CNC, SCADA, factory equipment |
+| `ROS2Driver` | Robots (ROS ecosystem) | Robot arms, mobile robots, drones |
+| `DDSDriver` | Real-time distributed systems | Autonomous vehicles, defense |
+| `DockerDriver` | Containers and orchestration | Scale services, manage deployments |
+| `BrowserDriver` | Web automation | Fill forms, scrape data, test UIs |
+| `UnitreeDriver` | Unitree robots | Go2, B2, H1 quadrupeds and humanoids |
+| `SocketDriver` | Raw TCP/UDP | Custom hardware, legacy systems |
+
+## 5 Autonomy Levels
+
+| Level | Name | Who Decides | Use Case |
+|-------|------|-------------|----------|
+| 0 | **Manual** | Human does everything | Learning, debugging |
+| 1 | **Advisory** | AI suggests, human executes | Critical systems |
+| 2 | **Supervised** | AI executes, human approves first | Production ops |
+| 3 | **Monitored** | AI executes freely, human can intervene | Routine tasks |
+| 4 | **Autonomous** | AI decides within shield rules | Fully automated systems |
+
+## Shield Rules — Safety as Physics
+
+Shield rules aren't guidelines. They're constraints enforced at the protocol level. Your AI physically cannot violate them, regardless of its instructions.
+
+```python
+# Industrial safety
+cp.shield("deny actuator write pressure > 150")   # never exceed 150 PSI
+cp.shield("deny motor write speed > 3000")         # RPM limit
+cp.shield("require human_approval for emergency_stop disable")
+
+# Data safety
+cp.shield("deny * read /etc/shadow")
+cp.shield("deny * write /prod/database/*")
+cp.shield("deny * delete *")  # read-only mode
+
+# Rate limiting
+cp.shield("limit actions 10/minute")
+```
+
+## Audit Chain
+
+Every action Halyn executes is recorded in a tamper-evident SHA-256 chain. Nothing can be altered or deleted.
+
+```python
+# View the audit trail
+for entry in cp.audit.chain():
+    print(f"{entry.timestamp} | {entry.action} | {entry.result} | {entry.hash[:12]}")
+
+# 2026-03-17T01:30:00 | observe cpu     | 23.4%      | a3f8c9d1e2b4
+# 2026-03-17T01:30:01 | act restart nginx| success    | 7b2e4f6a8c0d
+# 2026-03-17T01:30:02 | observe cpu     | 12.1%      | e5d7c9b1a3f8
+```
+
+Perfect for compliance (SOC2, ISO 27001, GDPR audit trails).
+
+## Use Cases
+
+### 🏭 Smart Factory
+
+Connect AI to your factory floor. OPC-UA driver reads machine data. Shield rules prevent dangerous operations. Audit chain provides compliance trail.
+
+```python
+cp = ControlPlane(autonomy=Autonomy.MONITORED)
+cp.connect(OPCUADriver("opc.tcp://plc-01:4840"))
+cp.shield("deny * write temperature > 200")
+cp.shield("deny * write pressure > 150")
+
+# AI monitors machines, optimizes parameters within safe bounds
+# Every adjustment is audited
+```
+
+### 🌱 Precision Agriculture
+
+MQTT sensors across your field report soil moisture, temperature, weather. AI decides when to irrigate, which zones need attention.
+
+```python
+cp = ControlPlane()
+cp.connect(MQTTDriver("mqtt://field-gateway:1883"))
+cp.shield("limit irrigation 3/day")  # prevent overwatering
+cp.shield("deny irrigation if wind > 30")  # no sprinklers in wind
+
+data = cp.observe()  # reads all sensors
+# AI analyzes and triggers irrigation for dry zones
+```
+
+### 🏥 Patient Monitoring
+
+Serial connection to medical devices. AI watches vitals 24/7, alerts staff immediately when something changes. Shield rules ensure the AI can never modify device settings.
+
+```python
+cp = ControlPlane(autonomy=Autonomy.ADVISORY)  # AI advises only
+cp.connect(SerialDriver("/dev/ttyUSB0", baudrate=9600))
+cp.shield("deny * write *")  # read-only — AI cannot control the device
+
+vitals = cp.observe()  # heart rate, SpO2, blood pressure
+# AI detects anomaly → alerts nurse station
+```
+
+### 🤖 Robot Fleet
+
+ROS2 driver connects to any robot in the ROS ecosystem. Shield rules define the workspace. Consent protocol ensures robots agree before coordinating.
+
+```python
+cp = ControlPlane()
+cp.connect(ROS2Driver("robot-arm-01"))
+cp.connect(ROS2Driver("robot-arm-02"))
+
+cp.shield("deny movement outside workspace_bounds")
+cp.shield("deny force > 50N")  # collaborative robot limits
+
+# Consent: robots negotiate shared workspace access
+cp.consent("robot-arm-01", "robot-arm-02", scope="shared_zone_A")
+```
+
+### 🏠 Smart Home
+
+Connect every device in your home. Your AI assistant can control lights, thermostat, locks — but shield rules ensure it can never unlock doors at night or set the thermostat below 15°C.
+
+```python
+cp = ControlPlane()
+cp.connect(MQTTDriver("mqtt://home-hub:1883"))
+
+cp.shield("deny lock unlock between 23:00-06:00")
+cp.shield("deny thermostat write < 15")
+cp.shield("deny * * camera")  # AI has no camera access
+
+cp.act("lights living_room dim 40%")
+```
+
+### 🎓 Education
+
+Students learn AI-hardware interaction in 10 lines. Connect an Arduino, read a temperature sensor, make an LED blink based on AI decisions.
+
+```python
+from halyn import ControlPlane, SerialDriver
+
+cp = ControlPlane()
+cp.connect(SerialDriver("/dev/ttyACM0"))
+
+temp = cp.observe()["temperature"]
+if temp > 30:
+    cp.act("led on")   # too hot → warning LED
+else:
+    cp.act("led off")
+```
+
+## Built on NRP
+
+Halyn implements [NRP (Node Reach Protocol)](https://github.com/ElmadaniS/nrp) — 6 primitives that define how AI talks to hardware:
+
+| Primitive | Purpose |
+|-----------|---------|
+| **Manifest** | "I am" — device declares its identity and capabilities |
+| **Observe** | "I see" — read state without side effects |
+| **Act** | "I do" — execute an action on the device |
+| **Shield** | "I cannot" — enforceable constraints |
+| **Audit** | "I did" — tamper-evident action log |
+| **Consent** | "We agree" — mutual permission negotiation |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). We especially welcome new drivers and shield rule patterns.
+
+## License
+
+MIT — use it anywhere, for anything.
+
+---
+
+<div align="center">
+
+**[halyn.dev](https://halyn.dev)** · **contact@halyn.dev** · © 2026 Elmadani SALKA
+
+</div>

{halyn-0.2.2 → halyn-0.3.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "halyn"
-version = "0.2.2"
+version = "0.3.0"
 description = "Halyn — NRP control plane with domain-scoped authorization."
 requires-python = ">=3.10"
 license = {text = "MIT"}
-authors = [{name = "Elmadani SALKA", email = "Elmadani.SALKA@proton.me"}]
+authors = [{name = "Elmadani SALKA", email = "contact@halyn.dev"}]
 readme = "README.md"
 keywords = ["ai", "browser", "robotics", "iot", "mcp", "nrp", "llm", "infrastructure", "devops"]
 classifiers = [
@@ -27,6 +27,7 @@ iot = ["paho-mqtt"]
 dev = ["pytest", "pytest-asyncio", "mypy", "ruff"]
 
 [project.scripts]
+halyn-mcp = "halyn.mcp_serve:main"
 halyn = "halyn.cli:main"
 
 [project.urls]

{halyn-0.2.2 → halyn-0.3.0}/src/halyn/__init__.py

@@ -2,6 +2,6 @@
 # Licensed under the MIT License. See LICENSE file.
 """Halyn — NRP control plane with domain-scoped authorization."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 __author__ = "Elmadani SALKA"
 __license__ = "MIT"