nmp-protocol 1.0.0__tar.gz

nmp_protocol-1.0.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: nmp-protocol
+Version: 1.0.0
+Summary: NMP (NeuroMessage Protocol) — Open communication protocol for multi-agent systems with behavioral modulation signals.
+Project-URL: Homepage, https://nmp-protocol.org
+Project-URL: Documentation, https://nmp-protocol.org
+Project-URL: Repository, https://github.com/AIP-Labs/nmp-protocol
+Project-URL: Specification, https://nmp-protocol.org
+Project-URL: Bug Tracker, https://github.com/AIP-Labs/nmp-protocol/issues
+Author-email: Renato Aparecido Gomes <renato@koloni.dev>
+License-Expression: Apache-2.0
+Keywords: a2a,active-inference,agent-communication,behavioral-signals,mcp,multi-agent,neuro-message-protocol,nmp,protocol,somatic-markers
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# NMP — NeuroMessage Protocol
+
+**Open communication protocol for multi-agent AI systems with behavioral modulation.**
+
+NMP is to agent communication what HTTP is to web communication — but with built-in behavioral signals. While MCP handles tool access and A2A handles agent coordination, NMP carries **intention**, **modulation**, and **accountability** alongside data.
+
+## Quick Start
+
+```bash
+pip install nmp-protocol
+```
+
+```python
+from nmp import create_message, TrustLevel, validate_message
+
+# Create an NMP message with behavioral signals
+msg = create_message(
+    from_agent="router",
+    to_agent="legal-analyzer",
+    content="Analyze this contract for risk clauses",
+    trust=TrustLevel.VERIFIED,
+)
+
+# Modulate behavioral signals
+msg.signals.urgency = 0.7      # Time-critical
+msg.signals.quality = 0.9      # High analysis depth needed
+msg.signals.inhibition = 0.0   # No blocking needed
+
+# Validate
+errors = validate_message(msg)
+assert not errors
+
+# Serialize
+json_str = msg.to_json()
+```
+
+## 6 Behavioral Signals
+
+| Signal | Range | Biological Analog | Purpose |
+|--------|-------|-------------------|---------|
+| `urgency` | [0, 1] | Noradrenaline | Processing speed (Yerkes-Dodson curve) |
+| `quality` | [0, 1] | Serotonin | Analysis depth |
+| `inhibition` | [0, 1] | GABA | Blocking / pausing |
+| `activation` | [0, 1] | Glutamate | Processing intensity |
+| `focus` | [0, 1] | Acetylcholine | Context narrowing |
+| `reward` | [-0.5, 1] | Dopamine | Feedback signal |
+
+## Trust Levels
+
+Trust can only decrease through a pipeline: `min(current_trust, source_trust)`
+
+| Level | Value | Meaning |
+|-------|-------|---------|
+| `HOSTILE` | 0 | Known malicious source |
+| `UNTRUSTED` | 1 | Unknown / unverified |
+| `VERIFIED` | 2 | Authenticated but not fully trusted |
+| `TRUSTED` | 3 | Fully trusted internal agent |
+
+## Specification
+
+Full spec: [nmp-protocol.org](https://nmp-protocol.org)
+
+Reference implementations: Python (this package), [TypeScript](https://www.npmjs.com/package/nmp-protocol), [Go](https://pkg.go.dev/github.com/AIP-Labs/nmp-protocol)
+
+## License
+
+Apache 2.0. Spec licensed under CC BY-SA 4.0.

nmp_protocol-1.0.0/README.md

@@ -0,0 +1,67 @@
+# NMP — NeuroMessage Protocol
+
+**Open communication protocol for multi-agent AI systems with behavioral modulation.**
+
+NMP is to agent communication what HTTP is to web communication — but with built-in behavioral signals. While MCP handles tool access and A2A handles agent coordination, NMP carries **intention**, **modulation**, and **accountability** alongside data.
+
+## Quick Start
+
+```bash
+pip install nmp-protocol
+```
+
+```python
+from nmp import create_message, TrustLevel, validate_message
+
+# Create an NMP message with behavioral signals
+msg = create_message(
+    from_agent="router",
+    to_agent="legal-analyzer",
+    content="Analyze this contract for risk clauses",
+    trust=TrustLevel.VERIFIED,
+)
+
+# Modulate behavioral signals
+msg.signals.urgency = 0.7      # Time-critical
+msg.signals.quality = 0.9      # High analysis depth needed
+msg.signals.inhibition = 0.0   # No blocking needed
+
+# Validate
+errors = validate_message(msg)
+assert not errors
+
+# Serialize
+json_str = msg.to_json()
+```
+
+## 6 Behavioral Signals
+
+| Signal | Range | Biological Analog | Purpose |
+|--------|-------|-------------------|---------|
+| `urgency` | [0, 1] | Noradrenaline | Processing speed (Yerkes-Dodson curve) |
+| `quality` | [0, 1] | Serotonin | Analysis depth |
+| `inhibition` | [0, 1] | GABA | Blocking / pausing |
+| `activation` | [0, 1] | Glutamate | Processing intensity |
+| `focus` | [0, 1] | Acetylcholine | Context narrowing |
+| `reward` | [-0.5, 1] | Dopamine | Feedback signal |
+
+## Trust Levels
+
+Trust can only decrease through a pipeline: `min(current_trust, source_trust)`
+
+| Level | Value | Meaning |
+|-------|-------|---------|
+| `HOSTILE` | 0 | Known malicious source |
+| `UNTRUSTED` | 1 | Unknown / unverified |
+| `VERIFIED` | 2 | Authenticated but not fully trusted |
+| `TRUSTED` | 3 | Fully trusted internal agent |
+
+## Specification
+
+Full spec: [nmp-protocol.org](https://nmp-protocol.org)
+
+Reference implementations: Python (this package), [TypeScript](https://www.npmjs.com/package/nmp-protocol), [Go](https://pkg.go.dev/github.com/AIP-Labs/nmp-protocol)
+
+## License
+
+Apache 2.0. Spec licensed under CC BY-SA 4.0.

nmp_protocol-1.0.0/nmp/__init__.py

@@ -0,0 +1,7 @@
+"""NMP — NeuroMessage Protocol. Standalone reference implementation."""
+__version__ = "1.0.0"
+from .message import (
+    NMPMessage, NMPSignals, TrustLevel, SystemMode,
+    Budget, TraceEntry,
+    create_message, validate_message,
+)

nmp_protocol-1.0.0/nmp/message.py

@@ -0,0 +1,277 @@
+"""NMP v1.0 — Standalone Python Reference Implementation."""
+from __future__ import annotations
+import json, math, uuid, time
+from dataclasses import dataclass, field, asdict
+from enum import IntEnum
+from typing import Any
+
+class TrustLevel(IntEnum):
+    HOSTILE = 0
+    UNTRUSTED = 1
+    VERIFIED = 2
+    TRUSTED = 3
+
+class SystemMode(IntEnum):
+    REFLEX = 0
+    FAST = 1
+    STANDARD = 2
+    DEEP = 3
+
+@dataclass
+class NMPSignals:
+    urgency: float = 0.5
+    quality: float = 0.5
+    inhibition: float = 0.0
+    activation: float = 0.5
+    focus: float = 0.5
+    reward: float = 0.0
+
+    def __post_init__(self):
+        self.urgency = max(0.0, min(1.0, self.urgency))
+        self.quality = max(0.0, min(1.0, self.quality))
+        self.inhibition = max(0.0, min(1.0, self.inhibition))
+        self.activation = max(0.0, min(1.0, self.activation))
+        self.focus = max(0.0, min(1.0, self.focus))
+        self.reward = max(-0.5, min(1.0, self.reward))
+
+    def validate(self) -> list[str]:
+        errors = []
+        for field_name in ("urgency", "quality", "inhibition", "activation", "focus"):
+            val = getattr(self, field_name)
+            if not 0.0 <= val <= 1.0:
+                errors.append(f"{field_name} must be 0.0-1.0, got {val}")
+        if not -0.5 <= self.reward <= 1.0:
+            errors.append(f"reward must be -0.5-1.0, got {self.reward}")
+        return errors
+
+    def urgency_performance(self) -> float:
+        """Yerkes-Dodson inverted-U curve: peak at urgency=0.5."""
+        return math.exp(-((self.urgency - 0.5) ** 2) / (2 * 0.15 ** 2))
+
+    def detect_conflicts(self) -> list[str]:
+        """Detect signal conflicts per NMP spec."""
+        conflicts = []
+        if self.urgency > 0.7 and self.quality > 0.7:
+            conflicts.append("urgency_vs_quality")
+        if self.inhibition > 0.5 and self.activation > 0.5:
+            conflicts.append("inhibition_vs_activation")
+        if self.urgency > 0.7 and self.reward > 0.7:
+            conflicts.append("impulsive_decision")
+        return conflicts
+
+    def to_dict(self) -> dict[str, float]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, float]) -> NMPSignals:
+        return cls(**{k: v for k, v in d.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class Budget:
+    max_tokens: int = 5000
+    tokens_used: int = 0
+    system_mode: int = 1  # SystemMode value
+
+    @property
+    def usage_ratio(self) -> float:
+        return self.tokens_used / max(1, self.max_tokens)
+
+    @property
+    def exhausted(self) -> bool:
+        return self.tokens_used >= self.max_tokens * 0.95
+
+    def consume(self, tokens: int) -> None:
+        self.tokens_used += tokens
+
+
+@dataclass
+class TraceEntry:
+    agent: str = ""
+    action: str = ""
+    tokens: int = 0
+    timestamp: str = field(default_factory=lambda: time.strftime("%Y-%m-%dT%H:%M:%SZ"))
+    signals_snapshot: dict[str, float] = field(default_factory=dict)
+
+
+@dataclass
+class NMPMessage:
+    version: str = "1.0"
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    trace_id: str = field(default_factory=lambda: uuid.uuid4().hex[:16])
+    timestamp: str = field(default_factory=lambda: time.strftime("%Y-%m-%dT%H:%M:%SZ"))
+    from_agent: str = ""
+    to_agent: str = ""
+    tenant_id: str = "default"
+    trust_level: int = 3
+    trust_source: str = "user_input"
+    payload_type: str = "task"
+    content: str = ""
+    context: dict[str, Any] = field(default_factory=dict)
+    signals: NMPSignals = field(default_factory=NMPSignals)
+    budget: Budget = field(default_factory=Budget)
+    trace: list[TraceEntry] = field(default_factory=list)
+    results: dict[str, Any] = field(default_factory=dict)
+
+    def add_trace(self, agent: str, action: str, tokens: int = 0):
+        entry = TraceEntry(
+            agent=agent, action=action, tokens=tokens,
+            signals_snapshot=self.signals.to_dict(),
+        )
+        self.trace.append(entry)
+        self.budget.consume(tokens)
+
+    def lower_trust(self, new_level: int | TrustLevel) -> None:
+        new_val = int(new_level)
+        if new_val > self.trust_level:
+            raise ValueError(f"Cannot raise trust from {self.trust_level} to {new_val}")
+        self.trust_level = new_val
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2, ensure_ascii=False, default=str)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "version": self.version,
+            "id": self.id,
+            "trace_id": self.trace_id,
+            "timestamp": self.timestamp,
+            "from": self.from_agent,
+            "to": self.to_agent,
+            "tenant_id": self.tenant_id,
+            "trust": {
+                "level": self.trust_level,
+                "source": self.trust_source,
+            },
+            "payload": {
+                "type": self.payload_type,
+                "content": self.content,
+                "context": self.context,
+            },
+            "signals": self.signals.to_dict(),
+            "budget": {
+                "max_tokens": self.budget.max_tokens,
+                "tokens_used": self.budget.tokens_used,
+                "system_mode": self.budget.system_mode,
+            },
+            "trace": [
+                {"agent": t.agent, "action": t.action, "tokens": t.tokens,
+                 "timestamp": t.timestamp, "signals_snapshot": t.signals_snapshot}
+                for t in self.trace
+            ],
+            "results": self.results,
+        }
+
+    @classmethod
+    def from_json(cls, data: str) -> NMPMessage:
+        d = json.loads(data)
+        return cls.from_dict(d)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> NMPMessage:
+        trust_data = d.get("trust", {})
+        payload_data = d.get("payload", {})
+        signals_data = d.get("signals", {})
+        budget_data = d.get("budget", {})
+        trace_data = d.get("trace", [])
+
+        msg = cls(
+            version=d.get("version", "1.0"),
+            id=d.get("id", uuid.uuid4().hex[:12]),
+            trace_id=d.get("trace_id", uuid.uuid4().hex[:16]),
+            timestamp=d.get("timestamp", time.strftime("%Y-%m-%dT%H:%M:%SZ")),
+            from_agent=d.get("from", ""),
+            to_agent=d.get("to", ""),
+            tenant_id=d.get("tenant_id", "default"),
+            trust_level=trust_data.get("level", 3) if isinstance(trust_data, dict) else 3,
+            trust_source=trust_data.get("source", "user_input") if isinstance(trust_data, dict) else "user_input",
+            payload_type=payload_data.get("type", "task") if isinstance(payload_data, dict) else "task",
+            content=payload_data.get("content", "") if isinstance(payload_data, dict) else "",
+            context=payload_data.get("context", {}) if isinstance(payload_data, dict) else {},
+            signals=NMPSignals(**{k: v for k, v in signals_data.items() if k in NMPSignals.__dataclass_fields__}),
+            budget=Budget(
+                max_tokens=budget_data.get("max_tokens", 5000) if isinstance(budget_data, dict) else 5000,
+                tokens_used=budget_data.get("tokens_used", 0) if isinstance(budget_data, dict) else 0,
+                system_mode=budget_data.get("system_mode", 1) if isinstance(budget_data, dict) else 1,
+            ),
+            results=d.get("results", {}),
+        )
+        for t in trace_data:
+            if isinstance(t, dict):
+                msg.trace.append(TraceEntry(
+                    agent=t.get("agent", ""),
+                    action=t.get("action", ""),
+                    tokens=t.get("tokens", 0),
+                    timestamp=t.get("timestamp", ""),
+                    signals_snapshot=t.get("signals_snapshot", {}),
+                ))
+        return msg
+
+
+def create_message(content: str = "", from_agent: str = "", trust: int | None = None,
+                   system_mode: int = 1, max_tokens: int = 5000,
+                   trust_level: int | None = None, trust_source: str = "user_input",
+                   **kwargs) -> NMPMessage:
+    effective_trust = trust_level if trust_level is not None else (trust if trust is not None else 3)
+    return NMPMessage(
+        content=content, from_agent=from_agent,
+        trust_level=effective_trust, trust_source=trust_source,
+        budget=Budget(max_tokens=max_tokens, system_mode=system_mode),
+        **kwargs,
+    )
+
+
+def validate_message(msg_or_dict) -> list[str]:
+    """Validate an NMPMessage or a dict representation."""
+    errors = []
+    if isinstance(msg_or_dict, NMPMessage):
+        errors.extend(msg_or_dict.signals.validate())
+        if msg_or_dict.version != "1.0":
+            errors.append(f"Unsupported version: {msg_or_dict.version}")
+        if not 0 <= msg_or_dict.trust_level <= 3:
+            errors.append(f"Invalid trust_level: {msg_or_dict.trust_level}")
+        if msg_or_dict.payload_type not in ("task", "response", "feedback", "alert", "pain", "reflex"):
+            errors.append(f"Invalid payload_type: {msg_or_dict.payload_type}")
+        if msg_or_dict.budget.tokens_used > msg_or_dict.budget.max_tokens:
+            errors.append("Budget exceeded")
+        return errors
+
+    # Dict validation (schema compliance)
+    d = msg_or_dict
+    if not isinstance(d, dict):
+        return ["Input must be NMPMessage or dict"]
+
+    if "version" not in d:
+        errors.append("Missing required field: version")
+    elif d["version"] != "1.0":
+        errors.append(f"Unsupported version: {d['version']}")
+
+    trust = d.get("trust", {})
+    if isinstance(trust, dict):
+        level = trust.get("level", 3)
+        if not 0 <= level <= 3:
+            errors.append(f"Invalid trust.level: {level}")
+
+    payload = d.get("payload", {})
+    if isinstance(payload, dict):
+        ptype = payload.get("type", "task")
+        if ptype not in ("task", "response", "feedback", "alert", "pain", "reflex"):
+            errors.append(f"Invalid payload.type: {ptype}")
+
+    signals = d.get("signals", {})
+    if isinstance(signals, dict):
+        for fname in ("urgency", "quality", "inhibition", "activation", "focus"):
+            val = signals.get(fname, 0.5)
+            if not 0.0 <= val <= 1.0:
+                errors.append(f"{fname} must be 0.0-1.0, got {val}")
+        reward = signals.get("reward", 0.0)
+        if not -0.5 <= reward <= 1.0:
+            errors.append(f"reward must be -0.5-1.0, got {reward}")
+
+    budget = d.get("budget", {})
+    if isinstance(budget, dict):
+        sm = budget.get("system_mode", 1)
+        if not isinstance(sm, int) or sm not in (0, 1, 2, 3):
+            errors.append(f"Invalid budget.system_mode: {sm}")
+
+    return errors

nmp_protocol-1.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nmp-protocol"
+version = "1.0.0"
+description = "NMP (NeuroMessage Protocol) — Open communication protocol for multi-agent systems with behavioral modulation signals."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "Renato Aparecido Gomes", email = "renato@koloni.dev" },
+]
+keywords = [
+    "nmp", "neuro-message-protocol", "multi-agent", "protocol",
+    "behavioral-signals", "agent-communication", "mcp", "a2a",
+    "somatic-markers", "active-inference",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Networking",
+]
+
+[project.urls]
+Homepage = "https://nmp-protocol.org"
+Documentation = "https://nmp-protocol.org"
+Repository = "https://github.com/AIP-Labs/nmp-protocol"
+Specification = "https://nmp-protocol.org"
+"Bug Tracker" = "https://github.com/AIP-Labs/nmp-protocol/issues"
+
+[tool.hatch.build.targets.sdist]
+include = ["nmp/"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["nmp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]