nrprotocol 0.1.0__tar.gz

nrprotocol-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2026 Elmadani SALKA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files, 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.

nrprotocol-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: nrprotocol
+Version: 0.1.0
+Summary: Node Reach Protocol — The universal standard for AI-to-world control.
+Author-email: Elmadani SALKA <Elmadani.SALKA@proton.me>
+License: MIT
+Project-URL: Homepage, https://github.com/ElmadaniS/nrp
+Project-URL: Repository, https://github.com/ElmadaniS/nrp
+Project-URL: Issues, https://github.com/ElmadaniS/nrp/issues
+Keywords: ai,robotics,iot,protocol,mcp,nrp,llm,edge
+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 :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+<img src="logo.svg" width="80" alt="Halyn">
+
+# NRP
+
+### Node Reach Protocol
+
+**The universal standard for AI-to-world control.**
+
+MCP connects LLMs to software.<br>
+**NRP connects LLMs to everything else.**
+
+Servers · Robots · Drones · Sensors · Vehicles · APIs · Factories · Smart Homes
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-green.svg)](https://python.org)
+[![Tests](https://img.shields.io/badge/Tests-48%20passed-brightgreen.svg)]()
+
+</div>
+
+---
+
+## The Problem
+
+Every device speaks a different language. SSH for servers. ROS2 for robots. MQTT for sensors. OPC-UA for factories. REST for APIs. Hundreds of protocols. Thousands of SDKs. No standard.
+
+MCP standardized software integration. NRP does the same for hardware and physical systems.
+
+## The Protocol
+
+3 methods. That is the interface.
+
+```
+OBSERVE  →  read state    (sensors, metrics, cameras, APIs)
+ACT      →  change state  (commands, movements, writes, calls)
+SHIELD   →  safety limits (boundaries the AI cannot cross)
+```
+
+Every device becomes a **node**. Every node has an address:
+
+```
+nrp://factory/robot/arm-7
+nrp://farm/sensor/soil-north
+nrp://cloud/api/stripe
+nrp://home/light/kitchen
+nrp://fleet/vehicle/truck-42
+```
+
+Every node **describes itself**. The AI reads the manifest and knows what to do. Zero configuration. Zero documentation.
+
+## Write a Driver in 100 Lines
+
+```python
+from nrp import NRPDriver, NRPManifest, ChannelSpec, ActionSpec, ShieldSpec
+
+class MyRobot(NRPDriver):
+
+    def manifest(self) -> NRPManifest:
+        return NRPManifest(
+            nrp_id=self._nrp_id,
+            manufacturer="Unitree", model="G1",
+            observe=[
+                ChannelSpec("joints", "float[]", unit="rad", rate="100Hz"),
+                ChannelSpec("battery", "int", unit="percent"),
+                ChannelSpec("camera", "image", rate="30Hz"),
+            ],
+            act=[
+                ActionSpec("walk", {"speed": "float m/s"}, "Walk forward", dangerous=True),
+                ActionSpec("pick", {"target": "string"}, "Pick an object", dangerous=True),
+                ActionSpec("stand", {}, "Stand still"),
+            ],
+            shield=[
+                ShieldSpec("max_speed", "limit", 1.5, "m/s"),
+                ShieldSpec("workspace", "zone", [0, 0, 10, 10], "meters"),
+            ],
+        )
+
+    async def observe(self, channels=None):
+        return {"joints": self.read_joints(), "battery": self.read_battery()}
+
+    async def act(self, command, args):
+        if command == "walk":
+            return self.walk(args["speed"])
+        if command == "pick":
+            return self.pick(args["target"])
+
+    def shield_rules(self):
+        return [ShieldRule("max_speed", ShieldType.LIMIT, 1.5)]
+```
+
+
+
+## What the AI Sees
+
+When a node connects, the AI receives a human-readable description:
+
+```
+Node: nrp://factory/robot/g1-01
+  Device: Unitree G1
+  Observe (read state):
+    joints: float[] (rad) — Joint angles at 100Hz
+    battery: int (percent) — Battery level
+    camera: image — Camera feed at 30Hz
+  Act (commands):
+    walk(speed: float m/s) [DANGEROUS] — Walk forward
+    pick(target: string) [DANGEROUS] — Pick an object
+    stand() — Stand still
+  Shield (safety limits):
+    max_speed: limit = 1.5 m/s
+    workspace: zone = [0, 0, 10, 10] meters
+```
+
+
+
+## Real-Time Events
+
+Nodes push events. The AI reacts without polling.
+
+```python
+# The node pushes
+await driver.emit("battery_low", Severity.WARNING, percent=8)
+await driver.emit("collision", Severity.EMERGENCY, force=45.2)
+
+# The control plane routes
+bus.subscribe("battery_*", alert_handler)
+bus.subscribe("nrp://factory/*", factory_monitor)
+```
+
+**Emergency events bypass all queues** and are processed synchronously.
+
+## Specification
+
+| Document | Description |
+|----------|-------------|
+| [IDENTITY.md](spec/IDENTITY.md) | Universal addressing: `nrp://scope/kind/name` |
+| [MANIFEST.md](spec/MANIFEST.md) | Self-describing nodes: channels, actions, shields |
+| [EVENTS.md](spec/EVENTS.md) | Real-time push: severity levels, emergency bypass |
+| [NRP_SPEC.md](spec/NRP_SPEC.md) | Protocol overview |
+
+## Install
+
+```bash
+pip install nrp
+```
+
+## Examples
+
+- [`hello_ssh.py`](examples/hello_ssh.py) — Connect to a server in 60 lines
+- [`multi_node.py`](examples/multi_node.py) — 3 sensors, 1 conversation
+
+## Built With NRP
+
+| Project | Description |
+|---------|-------------|
+| [Halyn](https://github.com/ElmadaniS/halyn) | NRP control plane with domain-scoped authorization |
+
+## Why Not Just Use MCP?
+
+MCP is brilliant for software. But:
+
+- MCP has no concept of **physical safety** (shield rules)
+- MCP has no concept of **real-time events** (push, not pull)
+- MCP has no concept of **self-describing hardware** (manifests)
+- MCP has no concept of **universal device identity** (`nrp://`)
+- MCP tools are defined by the server. NRP tools are declared by the device.
+
+NRP complements MCP. A control plane exposes NRP nodes as MCP tools — transparent to the LLM.
+
+## Architecture
+
+```
+Any LLM (Claude, GPT, Ollama, local)
+    │
+    │  MCP (software)
+    │
+    ▼
+Control Plane (e.g. Halyn)
+    │
+    │  NRP (physical + digital world)
+    │
+    ├──→ Servers (SSH)
+    ├──→ Robots (ROS2, Unitree, DJI)
+    ├──→ Sensors (MQTT)
+    ├──→ APIs (REST, GraphQL — auto-introspected)
+    ├──→ Containers (Docker)
+    ├──→ Browsers (Chrome CDP)
+    ├──→ Factories (OPC-UA, Modbus)
+    ├──→ Vehicles (CAN, DDS)
+    └──→ Anything with an interface
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). A driver is 4 methods, ~100 lines. If it has an interface, it can be an NRP node.
+
+## License
+
+MIT — Free forever. Use it. Build on it.
+
+## Author
+
+**Elmadani SALKA**

nrprotocol-0.1.0/README.md

@@ -0,0 +1,203 @@
+<div align="center">
+
+<img src="logo.svg" width="80" alt="Halyn">
+
+# NRP
+
+### Node Reach Protocol
+
+**The universal standard for AI-to-world control.**
+
+MCP connects LLMs to software.<br>
+**NRP connects LLMs to everything else.**
+
+Servers · Robots · Drones · Sensors · Vehicles · APIs · Factories · Smart Homes
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-green.svg)](https://python.org)
+[![Tests](https://img.shields.io/badge/Tests-48%20passed-brightgreen.svg)]()
+
+</div>
+
+---
+
+## The Problem
+
+Every device speaks a different language. SSH for servers. ROS2 for robots. MQTT for sensors. OPC-UA for factories. REST for APIs. Hundreds of protocols. Thousands of SDKs. No standard.
+
+MCP standardized software integration. NRP does the same for hardware and physical systems.
+
+## The Protocol
+
+3 methods. That is the interface.
+
+```
+OBSERVE  →  read state    (sensors, metrics, cameras, APIs)
+ACT      →  change state  (commands, movements, writes, calls)
+SHIELD   →  safety limits (boundaries the AI cannot cross)
+```
+
+Every device becomes a **node**. Every node has an address:
+
+```
+nrp://factory/robot/arm-7
+nrp://farm/sensor/soil-north
+nrp://cloud/api/stripe
+nrp://home/light/kitchen
+nrp://fleet/vehicle/truck-42
+```
+
+Every node **describes itself**. The AI reads the manifest and knows what to do. Zero configuration. Zero documentation.
+
+## Write a Driver in 100 Lines
+
+```python
+from nrp import NRPDriver, NRPManifest, ChannelSpec, ActionSpec, ShieldSpec
+
+class MyRobot(NRPDriver):
+
+    def manifest(self) -> NRPManifest:
+        return NRPManifest(
+            nrp_id=self._nrp_id,
+            manufacturer="Unitree", model="G1",
+            observe=[
+                ChannelSpec("joints", "float[]", unit="rad", rate="100Hz"),
+                ChannelSpec("battery", "int", unit="percent"),
+                ChannelSpec("camera", "image", rate="30Hz"),
+            ],
+            act=[
+                ActionSpec("walk", {"speed": "float m/s"}, "Walk forward", dangerous=True),
+                ActionSpec("pick", {"target": "string"}, "Pick an object", dangerous=True),
+                ActionSpec("stand", {}, "Stand still"),
+            ],
+            shield=[
+                ShieldSpec("max_speed", "limit", 1.5, "m/s"),
+                ShieldSpec("workspace", "zone", [0, 0, 10, 10], "meters"),
+            ],
+        )
+
+    async def observe(self, channels=None):
+        return {"joints": self.read_joints(), "battery": self.read_battery()}
+
+    async def act(self, command, args):
+        if command == "walk":
+            return self.walk(args["speed"])
+        if command == "pick":
+            return self.pick(args["target"])
+
+    def shield_rules(self):
+        return [ShieldRule("max_speed", ShieldType.LIMIT, 1.5)]
+```
+
+
+
+## What the AI Sees
+
+When a node connects, the AI receives a human-readable description:
+
+```
+Node: nrp://factory/robot/g1-01
+  Device: Unitree G1
+  Observe (read state):
+    joints: float[] (rad) — Joint angles at 100Hz
+    battery: int (percent) — Battery level
+    camera: image — Camera feed at 30Hz
+  Act (commands):
+    walk(speed: float m/s) [DANGEROUS] — Walk forward
+    pick(target: string) [DANGEROUS] — Pick an object
+    stand() — Stand still
+  Shield (safety limits):
+    max_speed: limit = 1.5 m/s
+    workspace: zone = [0, 0, 10, 10] meters
+```
+
+
+
+## Real-Time Events
+
+Nodes push events. The AI reacts without polling.
+
+```python
+# The node pushes
+await driver.emit("battery_low", Severity.WARNING, percent=8)
+await driver.emit("collision", Severity.EMERGENCY, force=45.2)
+
+# The control plane routes
+bus.subscribe("battery_*", alert_handler)
+bus.subscribe("nrp://factory/*", factory_monitor)
+```
+
+**Emergency events bypass all queues** and are processed synchronously.
+
+## Specification
+
+| Document | Description |
+|----------|-------------|
+| [IDENTITY.md](spec/IDENTITY.md) | Universal addressing: `nrp://scope/kind/name` |
+| [MANIFEST.md](spec/MANIFEST.md) | Self-describing nodes: channels, actions, shields |
+| [EVENTS.md](spec/EVENTS.md) | Real-time push: severity levels, emergency bypass |
+| [NRP_SPEC.md](spec/NRP_SPEC.md) | Protocol overview |
+
+## Install
+
+```bash
+pip install nrp
+```
+
+## Examples
+
+- [`hello_ssh.py`](examples/hello_ssh.py) — Connect to a server in 60 lines
+- [`multi_node.py`](examples/multi_node.py) — 3 sensors, 1 conversation
+
+## Built With NRP
+
+| Project | Description |
+|---------|-------------|
+| [Halyn](https://github.com/ElmadaniS/halyn) | NRP control plane with domain-scoped authorization |
+
+## Why Not Just Use MCP?
+
+MCP is brilliant for software. But:
+
+- MCP has no concept of **physical safety** (shield rules)
+- MCP has no concept of **real-time events** (push, not pull)
+- MCP has no concept of **self-describing hardware** (manifests)
+- MCP has no concept of **universal device identity** (`nrp://`)
+- MCP tools are defined by the server. NRP tools are declared by the device.
+
+NRP complements MCP. A control plane exposes NRP nodes as MCP tools — transparent to the LLM.
+
+## Architecture
+
+```
+Any LLM (Claude, GPT, Ollama, local)
+    │
+    │  MCP (software)
+    │
+    ▼
+Control Plane (e.g. Halyn)
+    │
+    │  NRP (physical + digital world)
+    │
+    ├──→ Servers (SSH)
+    ├──→ Robots (ROS2, Unitree, DJI)
+    ├──→ Sensors (MQTT)
+    ├──→ APIs (REST, GraphQL — auto-introspected)
+    ├──→ Containers (Docker)
+    ├──→ Browsers (Chrome CDP)
+    ├──→ Factories (OPC-UA, Modbus)
+    ├──→ Vehicles (CAN, DDS)
+    └──→ Anything with an interface
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). A driver is 4 methods, ~100 lines. If it has an interface, it can be an NRP node.
+
+## License
+
+MIT — Free forever. Use it. Build on it.
+
+## Author
+
+**Elmadani SALKA**

nrprotocol-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "nrprotocol"
+version = "0.1.0"
+description = "Node Reach Protocol — The universal standard for AI-to-world control."
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Elmadani SALKA", email = "Elmadani.SALKA@proton.me"}]
+readme = "README.md"
+keywords = ["ai", "robotics", "iot", "protocol", "mcp", "nrp", "llm", "edge"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Networking",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ElmadaniS/nrp"
+Repository = "https://github.com/ElmadaniS/nrp"
+Issues = "https://github.com/ElmadaniS/nrp/issues"
+
+[tool.setuptools.packages.find]
+where = ["sdk/python"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

nrprotocol-0.1.0/sdk/python/nrp/__init__.py

@@ -0,0 +1,27 @@
+"""
+NRP — Node Reach Protocol
+
+The universal protocol for AI-to-world control.
+MCP connects LLMs to software. NRP connects LLMs to everything else.
+
+    from nrp import NRPDriver, NRPId, NRPManifest, EventBus
+
+https://github.com/navigia/nrp
+"""
+
+from .identity import NRPId
+from .manifest import NRPManifest, ChannelSpec, ActionSpec, ShieldSpec
+from .events import NRPEvent, EventBus, EventSSE, Severity
+from .driver import NRPDriver, ShieldRule, ShieldType
+
+__version__ = "0.1.0"
+__author__ = "Elmadani SALKA"
+__license__ = "MIT"
+
+__all__ = [
+    "NRPId",
+    "NRPManifest", "ChannelSpec", "ActionSpec", "ShieldSpec",
+    "NRPEvent", "EventBus", "EventSSE", "Severity",
+    "NRPDriver", "ShieldRule", "ShieldType",
+]
+

nrprotocol-0.1.0/sdk/python/nrp/driver.py

@@ -0,0 +1,112 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+NRP Driver v2 — Universal interface with Manifest + Events.
+
+Every device implements:
+  manifest()  — declare what you are and what you can do
+  observe()   — read state
+  act()       — change state
+  on_event()  — push events to the control plane
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Awaitable
+
+from .identity import NRPId
+from .manifest import NRPManifest, ChannelSpec, ActionSpec, ShieldSpec
+from .events import NRPEvent, EventBus, Severity
+
+
+class ShieldType(str, Enum):
+    LIMIT = "limit"
+    ZONE = "zone"
+    THRESHOLD = "threshold"
+    PATTERN = "pattern"
+    COMMAND = "command"
+    CONFIRM = "confirm"
+
+
+@dataclass(frozen=True, slots=True)
+class ShieldRule:
+    name: str
+    type: ShieldType
+    value: Any = None
+    unit: str = ""
+    description: str = ""
+
+
+class NRPDriver(ABC):
+    """
+    Base class for all NRP drivers.
+    
+    Implement this to connect ANY device to AI.
+    Subclass and implement manifest(), observe(), act(), shield_rules().
+    """
+
+    def __init__(self) -> None:
+        self._event_bus: EventBus | None = None
+        self._nrp_id: NRPId | None = None
+
+    def bind(self, nrp_id: NRPId, event_bus: EventBus) -> None:
+        """Called by NRP Bridge at registration. Gives driver access to events."""
+        self._nrp_id = nrp_id
+        self._event_bus = event_bus
+
+    # ─── The 4 core methods ─────────────────────────
+
+    @abstractmethod
+    def manifest(self) -> NRPManifest:
+        """Declare everything about this node. Called once at registration."""
+
+    @abstractmethod
+    async def observe(self, channels: list[str] | None = None) -> dict[str, Any]:
+        """Read node state. Returns {channel_name: data}."""
+
+    @abstractmethod
+    async def act(self, command: str, args: dict[str, Any]) -> Any:
+        """Execute a command. Returns result."""
+
+    @abstractmethod
+    def shield_rules(self) -> list[ShieldRule]:
+        """Safety limits. Enforced by control plane."""
+
+    # ─── Events ─────────────────────────────────────
+
+    async def emit(self, name: str, severity: str = Severity.INFO, **data: Any) -> None:
+        """Push an event to the control plane."""
+        if self._event_bus and self._nrp_id:
+            event = NRPEvent(
+                source=self._nrp_id.uri,
+                name=name,
+                severity=severity,
+                data=data,
+            )
+            await self._event_bus.emit(event)
+
+    async def emit_emergency(self, name: str, **data: Any) -> None:
+        """Push an emergency event. Bypasses all queues."""
+        await self.emit(name, Severity.EMERGENCY, **data)
+
+    # ─── Lifecycle ──────────────────────────────────
+
+    async def connect(self) -> bool:
+        """Establish connection. Override for networked devices."""
+        return True
+
+    async def disconnect(self) -> None:
+        """Clean shutdown."""
+        pass
+
+    async def heartbeat(self) -> dict[str, Any]:
+        """Health check."""
+        try:
+            state = await self.observe(["status"])
+            return {"alive": True, **state}
+        except Exception as e:
+            return {"alive": False, "error": str(e)[:200]}
+

nrprotocol-0.1.0/sdk/python/nrp/events.py

@@ -0,0 +1,234 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+NRP Events — Asynchronous event bus with severity-based routing.
+
+Nodes emit events. The control plane dispatches to subscribers
+based on pattern matching. Emergency events bypass the queue.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Callable, Awaitable
+
+log = logging.getLogger("jarvis.events")
+
+EventHandler = Callable[["NRPEvent"], Awaitable[None] | None]
+
+
+class Severity:
+    """Event severity levels."""
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+    EMERGENCY = "emergency"  # Bypasses all queues
+
+
+@dataclass(frozen=True, slots=True)
+class NRPEvent:
+    """Single event payload."""
+    source: str          # NRP ID or node name
+    name: str            # "temperature_changed", "battery_low", "collision"
+    severity: str        # Severity level
+    data: dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "name": self.name,
+            "severity": self.severity,
+            "data": self.data,
+            "timestamp": self.timestamp,
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), default=str, ensure_ascii=False)
+
+
+class EventBus:
+    """Central event routing. Subscribe by pattern, receive matching events."""
+
+    __slots__ = ("_handlers", "_history", "_max_history", "_queue")
+
+    def __init__(self, max_history: int = 10_000) -> None:
+        self._handlers: dict[str, list[EventHandler]] = defaultdict(list)
+        self._history: list[NRPEvent] = []
+        self._max_history = max_history
+        self._queue: asyncio.Queue[NRPEvent] = asyncio.Queue(maxsize=50_000)
+
+    def subscribe(self, pattern: str, handler: EventHandler) -> None:
+        """
+        Subscribe to events matching a pattern.
+
+        Patterns:
+          "*"                    — all events
+          "battery_low"          — exact event name
+          "nrp://farm/*"         — all events from farm scope
+          "temperature_*"        — wildcard on event name
+        """
+        self._handlers[pattern].append(handler)
+        log.debug("events.subscribe pattern=%s", pattern)
+
+    def unsubscribe(self, pattern: str, handler: EventHandler) -> None:
+        if pattern in self._handlers:
+            self._handlers[pattern] = [h for h in self._handlers[pattern] if h is not handler]
+
+    async def emit(self, event: NRPEvent) -> int:
+        """
+        Emit an event. Routes to all matching handlers.
+        Returns number of handlers that received it.
+
+        EMERGENCY events are processed synchronously (no queue).
+        All others go through the async queue.
+        """
+        self._record(event)
+
+        if event.severity == Severity.EMERGENCY:
+            return await self._dispatch_now(event)
+
+        try:
+            self._queue.put_nowait(event)
+        except asyncio.QueueFull:
+            log.error("events.queue_full dropping=%s", event.name)
+        return 0  # Will be dispatched by process_loop
+
+    async def emit_simple(
+        self, source: str, name: str, severity: str = Severity.INFO, **data: Any
+    ) -> int:
+        """Shorthand for emitting events."""
+        return await self.emit(NRPEvent(source=source, name=name, severity=severity, data=data))
+
+    async def process_loop(self) -> None:
+        """Background loop that processes queued events. Run as asyncio task."""
+        log.info("events.loop_started")
+        while True:
+            try:
+                event = await asyncio.wait_for(self._queue.get(), timeout=1.0)
+                await self._dispatch_now(event)
+            except asyncio.TimeoutError:
+                continue
+            except Exception as exc:
+                log.exception("events.loop_error: %s", exc)
+
+    def recent(self, n: int = 50, source: str = "", name: str = "", severity: str = "") -> list[NRPEvent]:
+        """Query recent events with optional filters."""
+        events = self._history
+        if source:
+            events = [e for e in events if source in e.source]
+        if name:
+            events = [e for e in events if name in e.name]
+        if severity:
+            events = [e for e in events if e.severity == severity]
+        return events[-n:]
+
+    @property
+    def pending(self) -> int:
+        return self._queue.qsize()
+
+    @property
+    def total(self) -> int:
+        return len(self._history)
+
+    # ─── Internal ──────────────────────────────────
+
+    async def _dispatch_now(self, event: NRPEvent) -> int:
+        """Dispatch to all matching handlers immediately."""
+        import fnmatch
+        count = 0
+        for pattern, handlers in self._handlers.items():
+            matched = (
+                pattern == "*"
+                or pattern == event.name
+                or fnmatch.fnmatch(event.name, pattern)
+                or fnmatch.fnmatch(event.source, pattern)
+            )
+            if matched:
+                for handler in handlers:
+                    try:
+                        result = handler(event)
+                        if asyncio.iscoroutine(result):
+                            await result
+                        count += 1
+                    except Exception as exc:
+                        log.error("events.handler_error pattern=%s error=%s", pattern, exc)
+        return count
+
+    def _record(self, event: NRPEvent) -> None:
+        """Store in history ring buffer."""
+        self._history.append(event)
+        if len(self._history) > self._max_history:
+            self._history = self._history[-self._max_history // 2:]
+
+        lvl = {
+            Severity.DEBUG: logging.DEBUG,
+            Severity.INFO: logging.INFO,
+            Severity.WARNING: logging.WARNING,
+            Severity.CRITICAL: logging.ERROR,
+            Severity.EMERGENCY: logging.CRITICAL,
+        }.get(event.severity, logging.INFO)
+        log.log(lvl, "event.%s source=%s data=%s", event.name, event.source, 
+                json.dumps(event.data, default=str)[:200])
+
+
+class EventSSE:
+    """Server-Sent Events endpoint. Streams events to HTTP clients in real-time."""
+
+    def __init__(self, bus: EventBus) -> None:
+        self.bus = bus
+        self._clients: list[asyncio.Queue[str]] = []
+
+    async def handler(self, request: Any) -> Any:
+        """aiohttp SSE handler. Each client gets a queue."""
+        from aiohttp import web
+        from aiohttp.web import StreamResponse
+
+        response = StreamResponse()
+        response.content_type = "text/event-stream"
+        response.headers["Cache-Control"] = "no-cache"
+        response.headers["X-Accel-Buffering"] = "no"
+        await response.prepare(request)
+
+        queue: asyncio.Queue[str] = asyncio.Queue(maxsize=1000)
+        self._clients.append(queue)
+
+        try:
+            while True:
+                try:
+                    data = await asyncio.wait_for(queue.get(), timeout=30.0)
+                    await response.write(f"data: {data}\n\n".encode())
+                except asyncio.TimeoutError:
+                    # Keepalive
+                    await response.write(b": keepalive\n\n")
+        except (ConnectionResetError, asyncio.CancelledError):
+            pass
+        finally:
+            self._clients.remove(queue)
+
+        return response
+
+    async def broadcast(self, event: NRPEvent) -> None:
+        """Send event to all SSE clients."""
+        data = event.to_json()
+        dead: list[asyncio.Queue[str]] = []
+        for client in self._clients:
+            try:
+                client.put_nowait(data)
+            except asyncio.QueueFull:
+                dead.append(client)
+        for d in dead:
+            self._clients.remove(d)
+
+    def wire(self, bus: EventBus) -> None:
+        """Subscribe to all events and broadcast to SSE clients."""
+        async def _forward(event: NRPEvent) -> None:
+            await self.broadcast(event)
+        bus.subscribe("*", _forward)
+

nrprotocol-0.1.0/sdk/python/nrp/identity.py

@@ -0,0 +1,71 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+NRP Identity — Universal node addressing.
+
+Stable addressing: nrp://scope/kind/name
+Survives IP changes, network moves, device replacement.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# nrp://factory-3/robot/arm-7
+# nrp://home/sensor/kitchen-temp
+# nrp://fleet/vehicle/truck-42
+# nrp://farm/drone/survey-1
+_NRP_PATTERN = re.compile(
+    r"^nrp://(?P<scope>[a-z0-9][a-z0-9._-]*)/"
+    r"(?P<kind>[a-z0-9][a-z0-9_-]*)/"
+    r"(?P<name>[a-z0-9][a-z0-9._-]*)$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class NRPId:
+    """Universal node identifier."""
+    scope: str    # Location/org: "factory-3", "home", "fleet", "farm"
+    kind: str     # Type: "robot", "sensor", "server", "vehicle", "drone"
+    name: str     # Instance: "arm-7", "kitchen-temp", "truck-42"
+
+    @property
+    def uri(self) -> str:
+        return f"nrp://{self.scope}/{self.kind}/{self.name}"
+
+    @property
+    def short(self) -> str:
+        """Short form for display: kind/name."""
+        return f"{self.kind}/{self.name}"
+
+    def matches(self, pattern: str) -> bool:
+        """Match against glob patterns. E.g. 'factory-*/robot/*'."""
+        import fnmatch
+        return fnmatch.fnmatch(self.uri, f"nrp://{pattern}")
+
+    @classmethod
+    def parse(cls, uri: str) -> NRPId:
+        """Parse 'nrp://scope/kind/name' into NRPId."""
+        m = _NRP_PATTERN.match(uri.lower().strip())
+        if not m:
+            raise ValueError(
+                f"Invalid NRP ID: {uri!r}. "
+                f"Format: nrp://scope/kind/name (lowercase, alphanumeric, hyphens)"
+            )
+        return cls(scope=m["scope"], kind=m["kind"], name=m["name"])
+
+    @classmethod
+    def create(cls, scope: str, kind: str, name: str) -> NRPId:
+        """Create and validate an NRP ID."""
+        nid = cls(scope=scope.lower(), kind=kind.lower(), name=name.lower())
+        # Validate by roundtripping through parse
+        NRPId.parse(nid.uri)
+        return nid
+
+    def __str__(self) -> str:
+        return self.uri
+
+    def __repr__(self) -> str:
+        return f"NRPId({self.uri!r})"
+

nrprotocol-0.1.0/sdk/python/nrp/manifest.py

@@ -0,0 +1,166 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+NRP Manifest — Self-describing nodes.
+
+Structured capability declaration for NRP nodes.
+Channels (observe), actions (act), and constraints (shield)
+are declared once and consumed by any control plane.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from .identity import NRPId
+
+
+@dataclass(slots=True)
+class ChannelSpec:
+    """One observable channel (sensor, metric, state)."""
+    name: str
+    type: str            # "float", "int", "bool", "string", "float[]", "image", "json"
+    unit: str = ""       # "°C", "rad", "m/s", "percent", "Pa", ""
+    rate: str = ""       # "100Hz", "1Hz", "on_change", "on_request"
+    description: str = ""
+    range: list[float] | None = None  # [min, max] if applicable
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"name": self.name, "type": self.type}
+        if self.unit: d["unit"] = self.unit
+        if self.rate: d["rate"] = self.rate
+        if self.description: d["description"] = self.description
+        if self.range: d["range"] = self.range
+        return d
+
+
+@dataclass(slots=True)
+class ActionSpec:
+    """One action the node can perform."""
+    name: str
+    args: dict[str, str] = field(default_factory=dict)  # arg_name -> "type description"
+    description: str = ""
+    dangerous: bool = False
+    priority: str = "normal"  # "normal", "high", "critical"
+    returns: str = ""         # What it returns
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"name": self.name}
+        if self.args: d["args"] = self.args
+        if self.description: d["description"] = self.description
+        if self.dangerous: d["dangerous"] = True
+        if self.priority != "normal": d["priority"] = self.priority
+        if self.returns: d["returns"] = self.returns
+        return d
+
+
+@dataclass(slots=True)
+class ShieldSpec:
+    """One safety constraint."""
+    name: str
+    type: str       # "limit", "zone", "threshold", "pattern", "confirm"
+    value: Any = None
+    unit: str = ""
+    description: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"name": self.name, "type": self.type}
+        if self.value is not None: d["value"] = self.value
+        if self.unit: d["unit"] = self.unit
+        if self.description: d["description"] = self.description
+        return d
+
+
+@dataclass(slots=True)
+class NRPManifest:
+    """Complete capability descriptor for one NRP node."""
+
+    # Identity
+    nrp_id: NRPId
+    manufacturer: str = ""
+    model: str = ""
+    firmware: str = ""
+
+    # Capabilities
+    observe: list[ChannelSpec] = field(default_factory=list)
+    act: list[ActionSpec] = field(default_factory=list)
+    shield: list[ShieldSpec] = field(default_factory=list)
+
+    # Metadata
+    tags: dict[str, str] = field(default_factory=dict)
+    registered_at: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "nrp_id": self.nrp_id.uri,
+            "manufacturer": self.manufacturer,
+            "model": self.model,
+            "firmware": self.firmware,
+            "observe": [c.to_dict() for c in self.observe],
+            "act": [a.to_dict() for a in self.act],
+            "shield": [s.to_dict() for s in self.shield],
+            "tags": self.tags,
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    def to_llm_description(self) -> str:
+        """Structured text summary suitable for LLM context injection."""
+        lines = [f"Node: {self.nrp_id.uri}"]
+        if self.manufacturer:
+            lines.append(f"  Device: {self.manufacturer} {self.model}")
+
+        if self.observe:
+            lines.append("  Observe (read state):")
+            for ch in self.observe:
+                unit = f" ({ch.unit})" if ch.unit else ""
+                desc = f" — {ch.description}" if ch.description else ""
+                lines.append(f"    {ch.name}: {ch.type}{unit}{desc}")
+
+        if self.act:
+            lines.append("  Act (commands):")
+            for a in self.act:
+                args_str = ", ".join(f"{k}: {v}" for k, v in a.args.items()) if a.args else "none"
+                danger = " [DANGEROUS]" if a.dangerous else ""
+                prio = f" [PRIORITY={a.priority}]" if a.priority != "normal" else ""
+                desc = f" — {a.description}" if a.description else ""
+                lines.append(f"    {a.name}({args_str}){danger}{prio}{desc}")
+
+        if self.shield:
+            lines.append("  Shield (safety limits):")
+            for s in self.shield:
+                unit = f" {s.unit}" if s.unit else ""
+                lines.append(f"    {s.name}: {s.type} = {s.value}{unit}")
+
+        return "\n".join(lines)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> NRPManifest:
+        """Parse a manifest from JSON/dict."""
+        nrp_id = NRPId.parse(data["nrp_id"])
+        return cls(
+            nrp_id=nrp_id,
+            manufacturer=data.get("manufacturer", ""),
+            model=data.get("model", ""),
+            firmware=data.get("firmware", ""),
+            observe=[ChannelSpec(**c) for c in data.get("observe", [])],
+            act=[ActionSpec(
+                name=a["name"],
+                args=a.get("args", {}),
+                description=a.get("description", ""),
+                dangerous=a.get("dangerous", False),
+                priority=a.get("priority", "normal"),
+                returns=a.get("returns", ""),
+            ) for a in data.get("act", [])],
+            shield=[ShieldSpec(**s) for s in data.get("shield", [])],
+            tags=data.get("tags", {}),
+        )
+
+    @classmethod
+    def from_json(cls, text: str) -> NRPManifest:
+        return cls.from_dict(json.loads(text))
+

nrprotocol-0.1.0/sdk/python/nrprotocol.egg-info/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: nrprotocol
+Version: 0.1.0
+Summary: Node Reach Protocol — The universal standard for AI-to-world control.
+Author-email: Elmadani SALKA <Elmadani.SALKA@proton.me>
+License: MIT
+Project-URL: Homepage, https://github.com/ElmadaniS/nrp
+Project-URL: Repository, https://github.com/ElmadaniS/nrp
+Project-URL: Issues, https://github.com/ElmadaniS/nrp/issues
+Keywords: ai,robotics,iot,protocol,mcp,nrp,llm,edge
+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 :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+<img src="logo.svg" width="80" alt="Halyn">
+
+# NRP
+
+### Node Reach Protocol
+
+**The universal standard for AI-to-world control.**
+
+MCP connects LLMs to software.<br>
+**NRP connects LLMs to everything else.**
+
+Servers · Robots · Drones · Sensors · Vehicles · APIs · Factories · Smart Homes
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-green.svg)](https://python.org)
+[![Tests](https://img.shields.io/badge/Tests-48%20passed-brightgreen.svg)]()
+
+</div>
+
+---
+
+## The Problem
+
+Every device speaks a different language. SSH for servers. ROS2 for robots. MQTT for sensors. OPC-UA for factories. REST for APIs. Hundreds of protocols. Thousands of SDKs. No standard.
+
+MCP standardized software integration. NRP does the same for hardware and physical systems.
+
+## The Protocol
+
+3 methods. That is the interface.
+
+```
+OBSERVE  →  read state    (sensors, metrics, cameras, APIs)
+ACT      →  change state  (commands, movements, writes, calls)
+SHIELD   →  safety limits (boundaries the AI cannot cross)
+```
+
+Every device becomes a **node**. Every node has an address:
+
+```
+nrp://factory/robot/arm-7
+nrp://farm/sensor/soil-north
+nrp://cloud/api/stripe
+nrp://home/light/kitchen
+nrp://fleet/vehicle/truck-42
+```
+
+Every node **describes itself**. The AI reads the manifest and knows what to do. Zero configuration. Zero documentation.
+
+## Write a Driver in 100 Lines
+
+```python
+from nrp import NRPDriver, NRPManifest, ChannelSpec, ActionSpec, ShieldSpec
+
+class MyRobot(NRPDriver):
+
+    def manifest(self) -> NRPManifest:
+        return NRPManifest(
+            nrp_id=self._nrp_id,
+            manufacturer="Unitree", model="G1",
+            observe=[
+                ChannelSpec("joints", "float[]", unit="rad", rate="100Hz"),
+                ChannelSpec("battery", "int", unit="percent"),
+                ChannelSpec("camera", "image", rate="30Hz"),
+            ],
+            act=[
+                ActionSpec("walk", {"speed": "float m/s"}, "Walk forward", dangerous=True),
+                ActionSpec("pick", {"target": "string"}, "Pick an object", dangerous=True),
+                ActionSpec("stand", {}, "Stand still"),
+            ],
+            shield=[
+                ShieldSpec("max_speed", "limit", 1.5, "m/s"),
+                ShieldSpec("workspace", "zone", [0, 0, 10, 10], "meters"),
+            ],
+        )
+
+    async def observe(self, channels=None):
+        return {"joints": self.read_joints(), "battery": self.read_battery()}
+
+    async def act(self, command, args):
+        if command == "walk":
+            return self.walk(args["speed"])
+        if command == "pick":
+            return self.pick(args["target"])
+
+    def shield_rules(self):
+        return [ShieldRule("max_speed", ShieldType.LIMIT, 1.5)]
+```
+
+
+
+## What the AI Sees
+
+When a node connects, the AI receives a human-readable description:
+
+```
+Node: nrp://factory/robot/g1-01
+  Device: Unitree G1
+  Observe (read state):
+    joints: float[] (rad) — Joint angles at 100Hz
+    battery: int (percent) — Battery level
+    camera: image — Camera feed at 30Hz
+  Act (commands):
+    walk(speed: float m/s) [DANGEROUS] — Walk forward
+    pick(target: string) [DANGEROUS] — Pick an object
+    stand() — Stand still
+  Shield (safety limits):
+    max_speed: limit = 1.5 m/s
+    workspace: zone = [0, 0, 10, 10] meters
+```
+
+
+
+## Real-Time Events
+
+Nodes push events. The AI reacts without polling.
+
+```python
+# The node pushes
+await driver.emit("battery_low", Severity.WARNING, percent=8)
+await driver.emit("collision", Severity.EMERGENCY, force=45.2)
+
+# The control plane routes
+bus.subscribe("battery_*", alert_handler)
+bus.subscribe("nrp://factory/*", factory_monitor)
+```
+
+**Emergency events bypass all queues** and are processed synchronously.
+
+## Specification
+
+| Document | Description |
+|----------|-------------|
+| [IDENTITY.md](spec/IDENTITY.md) | Universal addressing: `nrp://scope/kind/name` |
+| [MANIFEST.md](spec/MANIFEST.md) | Self-describing nodes: channels, actions, shields |
+| [EVENTS.md](spec/EVENTS.md) | Real-time push: severity levels, emergency bypass |
+| [NRP_SPEC.md](spec/NRP_SPEC.md) | Protocol overview |
+
+## Install
+
+```bash
+pip install nrp
+```
+
+## Examples
+
+- [`hello_ssh.py`](examples/hello_ssh.py) — Connect to a server in 60 lines
+- [`multi_node.py`](examples/multi_node.py) — 3 sensors, 1 conversation
+
+## Built With NRP
+
+| Project | Description |
+|---------|-------------|
+| [Halyn](https://github.com/ElmadaniS/halyn) | NRP control plane with domain-scoped authorization |
+
+## Why Not Just Use MCP?
+
+MCP is brilliant for software. But:
+
+- MCP has no concept of **physical safety** (shield rules)
+- MCP has no concept of **real-time events** (push, not pull)
+- MCP has no concept of **self-describing hardware** (manifests)
+- MCP has no concept of **universal device identity** (`nrp://`)
+- MCP tools are defined by the server. NRP tools are declared by the device.
+
+NRP complements MCP. A control plane exposes NRP nodes as MCP tools — transparent to the LLM.
+
+## Architecture
+
+```
+Any LLM (Claude, GPT, Ollama, local)
+    │
+    │  MCP (software)
+    │
+    ▼
+Control Plane (e.g. Halyn)
+    │
+    │  NRP (physical + digital world)
+    │
+    ├──→ Servers (SSH)
+    ├──→ Robots (ROS2, Unitree, DJI)
+    ├──→ Sensors (MQTT)
+    ├──→ APIs (REST, GraphQL — auto-introspected)
+    ├──→ Containers (Docker)
+    ├──→ Browsers (Chrome CDP)
+    ├──→ Factories (OPC-UA, Modbus)
+    ├──→ Vehicles (CAN, DDS)
+    └──→ Anything with an interface
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). A driver is 4 methods, ~100 lines. If it has an interface, it can be an NRP node.
+
+## License
+
+MIT — Free forever. Use it. Build on it.
+
+## Author
+
+**Elmadani SALKA**

nrprotocol-0.1.0/sdk/python/nrprotocol.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+sdk/python/nrp/__init__.py
+sdk/python/nrp/driver.py
+sdk/python/nrp/events.py
+sdk/python/nrp/identity.py
+sdk/python/nrp/manifest.py
+sdk/python/nrp/py.typed
+sdk/python/nrprotocol.egg-info/PKG-INFO
+sdk/python/nrprotocol.egg-info/SOURCES.txt
+sdk/python/nrprotocol.egg-info/dependency_links.txt
+sdk/python/nrprotocol.egg-info/top_level.txt

nrprotocol-0.1.0/sdk/python/nrprotocol.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nrprotocol-0.1.0/sdk/python/nrprotocol.egg-info/top_level.txt

@@ -0,0 +1 @@
+nrp

nrprotocol-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+