roar-sdk 0.2.0__tar.gz

roar_sdk-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.eggs/
+dist/
+build/

roar_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: roar-sdk
+Version: 0.2.0
+Summary: ROAR Protocol — Python SDK. Standalone implementation of the 5-layer agent communication standard.
+Project-URL: Homepage, https://github.com/ProwlrBot/roar-protocol
+Project-URL: Repository, https://github.com/ProwlrBot/roar-protocol
+Project-URL: Specification, https://github.com/ProwlrBot/roar-protocol/blob/main/ROAR-SPEC.md
+Author-email: kdairatchi <kdairatchi@users.noreply.github.com>
+License: Apache-2.0
+Keywords: a2a,agents,ai,did,mcp,protocol,roar
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: cryptography>=41.0; extra == 'dev'
+Requires-Dist: httpx>=0.25; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: websockets>=12.0; extra == 'dev'
+Provides-Extra: ed25519
+Requires-Dist: cryptography>=41.0; extra == 'ed25519'
+Provides-Extra: http
+Requires-Dist: httpx>=0.25; extra == 'http'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.104; extra == 'server'
+Requires-Dist: httpx>=0.25; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.24; extra == 'server'
+Provides-Extra: websocket
+Requires-Dist: websockets>=12.0; extra == 'websocket'
+Description-Content-Type: text/markdown
+
+# roar-sdk
+
+**ROAR Protocol** — standalone Python SDK. 5-layer agent communication standard.
+
+Design by [@kdairatchi](https://github.com/kdairatchi) — [ProwlrBot/roar-protocol](https://github.com/ProwlrBot/roar-protocol)
+
+## Install
+
+```bash
+git clone https://github.com/ProwlrBot/roar-protocol.git
+pip install -e ./python          # types + client + server (pydantic only)
+pip install -e './python[http]'  # + httpx for HTTP transport
+pip install -e './python[server]'  # + fastapi + uvicorn for serving
+```
+
+## Quick Start
+
+```python
+from roar_sdk import AgentIdentity, ROARMessage, MessageIntent, ROARClient, ROARServer
+
+# Layer 1: identity
+agent = AgentIdentity(display_name="my-agent", capabilities=["code"])
+
+# Layer 4: message
+msg = ROARMessage(
+    **{"from": agent, "to": other},
+    intent=MessageIntent.DELEGATE,
+    payload={"task": "review"},
+)
+msg.sign("shared-secret")
+```
+
+See [examples/python/](https://github.com/ProwlrBot/roar-protocol/tree/main/examples/python) for runnable server + client.
+See [ROAR-SPEC.md](https://github.com/ProwlrBot/roar-protocol/blob/main/ROAR-SPEC.md) for the full protocol specification.

roar_sdk-0.2.0/README.md

@@ -0,0 +1,34 @@
+# roar-sdk
+
+**ROAR Protocol** — standalone Python SDK. 5-layer agent communication standard.
+
+Design by [@kdairatchi](https://github.com/kdairatchi) — [ProwlrBot/roar-protocol](https://github.com/ProwlrBot/roar-protocol)
+
+## Install
+
+```bash
+git clone https://github.com/ProwlrBot/roar-protocol.git
+pip install -e ./python          # types + client + server (pydantic only)
+pip install -e './python[http]'  # + httpx for HTTP transport
+pip install -e './python[server]'  # + fastapi + uvicorn for serving
+```
+
+## Quick Start
+
+```python
+from roar_sdk import AgentIdentity, ROARMessage, MessageIntent, ROARClient, ROARServer
+
+# Layer 1: identity
+agent = AgentIdentity(display_name="my-agent", capabilities=["code"])
+
+# Layer 4: message
+msg = ROARMessage(
+    **{"from": agent, "to": other},
+    intent=MessageIntent.DELEGATE,
+    payload={"task": "review"},
+)
+msg.sign("shared-secret")
+```
+
+See [examples/python/](https://github.com/ProwlrBot/roar-protocol/tree/main/examples/python) for runnable server + client.
+See [ROAR-SPEC.md](https://github.com/ProwlrBot/roar-protocol/blob/main/ROAR-SPEC.md) for the full protocol specification.

roar_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roar-sdk"
+version = "0.2.0"
+description = "ROAR Protocol — Python SDK. Standalone implementation of the 5-layer agent communication standard."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [{ name = "kdairatchi", email = "kdairatchi@users.noreply.github.com" }]
+keywords = ["agents", "ai", "protocol", "roar", "did", "a2a", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "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",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = ["pydantic>=2.0"]
+
+[project.optional-dependencies]
+http = ["httpx>=0.25"]
+websocket = ["websockets>=12.0"]
+ed25519 = ["cryptography>=41.0"]
+server = ["fastapi>=0.104", "uvicorn[standard]>=0.24", "httpx>=0.25"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.23", "httpx>=0.25", "websockets>=12.0", "cryptography>=41.0"]
+
+[project.urls]
+Homepage = "https://github.com/ProwlrBot/roar-protocol"
+Repository = "https://github.com/ProwlrBot/roar-protocol"
+Specification = "https://github.com/ProwlrBot/roar-protocol/blob/main/ROAR-SPEC.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roar_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

roar_sdk-0.2.0/src/roar_sdk/__init__.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""ROAR Protocol — Python SDK.
+
+Standalone implementation of the 5-layer agent communication standard.
+Design: @kdairatchi — https://github.com/ProwlrBot/roar-protocol
+
+Quick start::
+
+    from roar_sdk import AgentIdentity, ROARMessage, MessageIntent, ROARClient, ROARServer
+
+    # Layer 1: Identity
+    identity = AgentIdentity(display_name="my-agent", capabilities=["code"])
+    print(identity.did)  # did:roar:agent:my-agent-a1b2c3d4...
+
+    # Layer 4: Exchange — build and sign a message
+    msg = ROARMessage(
+        **{"from": identity, "to": other_identity},
+        intent=MessageIntent.DELEGATE,
+        payload={"task": "review"},
+    )
+    msg.sign("shared-secret")
+
+    # Layer 3: Connect — send over HTTP
+    client = ROARClient(identity, signing_secret="shared-secret")
+    response = await client.send_remote(
+        to_agent_id=other_identity.did,
+        intent=MessageIntent.DELEGATE,
+        content={"task": "review"},
+    )
+"""
+
+__version__ = "0.2.0"
+__author__ = "kdairatchi"
+__spec_version__ = "0.2.0"
+
+from .types import (
+    # Layer 1
+    AgentIdentity,
+    AgentCapability,
+    AgentCard,
+    # Layer 2
+    DiscoveryEntry,
+    AgentDirectory,
+    # Layer 3
+    TransportType,
+    ConnectionConfig,
+    # Layer 4
+    MessageIntent,
+    ROARMessage,
+    # Layer 5
+    StreamEventType,
+    StreamEvent,
+    # Adapters
+    MCPAdapter,
+    A2AAdapter,
+)
+from .client import ROARClient
+from .server import ROARServer
+from .streaming import EventBus, StreamFilter, Subscription
+from .signing import generate_keypair, sign_ed25519, verify_ed25519
+from .delegation import DelegationToken, issue_token, verify_token
+from .adapters import ACPAdapter
+from .adapters.detect import detect_protocol, ProtocolType
+from .hub import ROARHub
+from .did_document import DIDDocument, VerificationMethod, ServiceEndpoint
+from .did_key import DIDKeyMethod, DIDKeyIdentity
+from .did_web import DIDWebMethod, DIDWebIdentity
+from .sqlite_directory import SQLiteAgentDirectory
+from .discovery_cache import DiscoveryCache
+from .dedup import IdempotencyGuard
+from .autonomy import AutonomyLevel, CapabilityDelegation, RuntimeToken
+
+__all__ = [
+    # Layer 1
+    "AgentIdentity",
+    "AgentCapability",
+    "AgentCard",
+    # Layer 2
+    "DiscoveryEntry",
+    "AgentDirectory",
+    # Layer 3
+    "TransportType",
+    "ConnectionConfig",
+    # Layer 4
+    "MessageIntent",
+    "ROARMessage",
+    # Layer 5
+    "StreamEventType",
+    "StreamEvent",
+    # Adapters
+    "MCPAdapter",
+    "A2AAdapter",
+    "ACPAdapter",
+    "detect_protocol",
+    "ProtocolType",
+    # Client / Server / Hub
+    "ROARClient",
+    "ROARServer",
+    "ROARHub",
+    # Streaming
+    "EventBus",
+    "StreamFilter",
+    "Subscription",
+    # Ed25519 signing
+    "generate_keypair",
+    "sign_ed25519",
+    "verify_ed25519",
+    # Delegation tokens (cryptographic, portable)
+    "DelegationToken",
+    "issue_token",
+    "verify_token",
+    # DID methods
+    "DIDDocument",
+    "VerificationMethod",
+    "ServiceEndpoint",
+    "DIDKeyMethod",
+    "DIDKeyIdentity",
+    "DIDWebMethod",
+    "DIDWebIdentity",
+    # Persistent discovery
+    "SQLiteAgentDirectory",
+    "DiscoveryCache",
+    # Autonomy model (runtime policy enforcement)
+    "AutonomyLevel",
+    "CapabilityDelegation",
+    "RuntimeToken",
+    # Deduplication
+    "IdempotencyGuard",
+]

roar_sdk-0.2.0/src/roar_sdk/_compat.py

@@ -0,0 +1,11 @@
+# Python 3.10 compatibility shim for StrEnum (added in 3.11)
+try:
+    from enum import StrEnum
+except ImportError:
+    from enum import Enum
+
+    class StrEnum(str, Enum):  # type: ignore[no-redef]
+        """Backport of Python 3.11 StrEnum for Python 3.10."""
+
+        def __str__(self) -> str:
+            return self.value

roar_sdk-0.2.0/src/roar_sdk/adapters/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""ROAR Protocol — protocol adapters for backward compatibility.
+
+Available adapters:
+  MCPAdapter  — translate MCP tool calls ↔ ROARMessage (in roar_sdk.types)
+  A2AAdapter  — translate A2A tasks ↔ ROARMessage (in roar_sdk.types)
+  ACPAdapter  — translate ACP sessions ↔ ROARMessage (in roar_sdk.adapters.acp)
+"""
+
+from .acp import ACPAdapter
+
+__all__ = ["ACPAdapter"]

roar_sdk-0.2.0/src/roar_sdk/adapters/acp.py

@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+"""ROAR ACP Adapter — translate between ACP (Agent Communication Protocol) and ROAR.
+
+ACP (IBM/BeeAI) is a session-based HTTP protocol for IDE-to-agent communication.
+It defines sessions, messages, and responses but has no identity, signing, or
+federation layer.
+
+Mapping:
+  ACP session start   → ROARMessage(intent=NOTIFY, payload={"event": "session.start"})
+  ACP message         → ROARMessage(intent=ASK)    if awaiting human input
+                      → ROARMessage(intent=UPDATE)  if reporting progress
+  ACP response        → ROARMessage(intent=RESPOND)
+  ACP session end     → ROARMessage(intent=NOTIFY, payload={"event": "session.end"})
+
+ACP wire format (simplified):
+  POST /sessions            → create session, returns session_id
+  POST /sessions/{id}/runs  → send message, returns run_id + response stream
+  GET  /sessions/{id}       → get session state
+
+Usage::
+
+    from roar_sdk.adapters import ACPAdapter
+    from roar_sdk import AgentIdentity, MessageIntent
+
+    ide = AgentIdentity(display_name="vscode", agent_type="ide")
+    agent = AgentIdentity(display_name="my-agent")
+
+    # Translate an incoming ACP message to a ROARMessage
+    acp_msg = {"content": "Explain this function", "role": "user"}
+    roar_msg = ACPAdapter.acp_to_roar(acp_msg, from_agent=ide, to_agent=agent)
+
+    # Translate a ROARMessage back to ACP response format
+    acp_response = ACPAdapter.roar_to_acp(roar_msg)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..types import AgentIdentity, MessageIntent, ROARMessage
+
+
+class ACPAdapter:
+    """Translate between ACP sessions/messages and ROAR messages."""
+
+    # ── ACP → ROAR ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def acp_message_to_roar(
+        acp_message: Dict[str, Any],
+        from_agent: AgentIdentity,
+        to_agent: AgentIdentity,
+        session_id: str = "",
+    ) -> ROARMessage:
+        """Translate an ACP message dict to a ROARMessage.
+
+        ACP message format::
+
+            {
+                "role": "user" | "assistant",
+                "content": str | list,
+                "attachments": [...]  # optional
+            }
+
+        The intent is derived from role:
+          - "user" → ASK (user is requesting something from the agent)
+          - "assistant" → RESPOND (agent is replying)
+        """
+        role = acp_message.get("role", "user")
+        content = acp_message.get("content", "")
+        attachments = acp_message.get("attachments", [])
+
+        intent = MessageIntent.ASK if role == "user" else MessageIntent.RESPOND
+
+        payload: Dict[str, Any] = {"content": content}
+        if attachments:
+            payload["attachments"] = attachments
+
+        context: Dict[str, Any] = {"protocol": "acp"}
+        if session_id:
+            context["session_id"] = session_id
+
+        return ROARMessage(
+            **{"from": from_agent, "to": to_agent},
+            intent=intent,
+            payload=payload,
+            context=context,
+        )
+
+    @staticmethod
+    def acp_session_event_to_roar(
+        event: str,  # "start" | "end"
+        from_agent: AgentIdentity,
+        to_agent: AgentIdentity,
+        session_id: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> ROARMessage:
+        """Translate an ACP session lifecycle event to a ROARMessage."""
+        return ROARMessage(
+            **{"from": from_agent, "to": to_agent},
+            intent=MessageIntent.NOTIFY,
+            payload={"event": f"session.{event}", **(metadata or {})},
+            context={"protocol": "acp", "session_id": session_id},
+        )
+
+    # ── ROAR → ACP ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def roar_to_acp_message(msg: ROARMessage) -> Dict[str, Any]:
+        """Translate a ROARMessage to an ACP message dict.
+
+        Maps intent to ACP role:
+          RESPOND → "assistant"
+          ASK     → "user" (agent asking human for input)
+          UPDATE  → "assistant" with status metadata
+          NOTIFY  → "assistant" with event metadata
+          *       → "assistant"
+        """
+        intent_to_role = {
+            MessageIntent.RESPOND: "assistant",
+            MessageIntent.ASK: "user",
+            MessageIntent.UPDATE: "assistant",
+            MessageIntent.NOTIFY: "assistant",
+        }
+        role = intent_to_role.get(msg.intent, "assistant")
+
+        # Prefer a "content" field, fall back to full payload as string
+        content = msg.payload.get("content") or msg.payload.get("result") or msg.payload
+
+        acp: Dict[str, Any] = {"role": role, "content": content}
+
+        # Carry attachments through if present
+        if "attachments" in msg.payload:
+            acp["attachments"] = msg.payload["attachments"]
+
+        return acp
+
+    @staticmethod
+    def roar_to_acp_run(msg: ROARMessage, run_id: str = "") -> Dict[str, Any]:
+        """Translate a ROARMessage to an ACP run response (richer format)."""
+        import time
+
+        return {
+            "run_id": run_id or msg.id,
+            "session_id": msg.context.get("session_id", ""),
+            "status": "completed" if msg.intent == MessageIntent.RESPOND else "in_progress",
+            "output": ACPAdapter.roar_to_acp_message(msg),
+            "metadata": {
+                "roar_intent": msg.intent,
+                "roar_message_id": msg.id,
+                "from_did": msg.from_identity.did,
+                "timestamp": msg.timestamp,
+            },
+            "created_at": time.time(),
+        }
+
+    # ── Agent Card ↔ ACP Agent ───────────────────────────────────────────────
+
+    @staticmethod
+    def well_known_agent_to_card(
+        well_known: Dict[str, Any],
+        endpoint: str = "",
+    ) -> Dict[str, Any]:
+        """Convert an A2A/ACP /.well-known/agent.json to a ROAR AgentCard dict.
+
+        Returns a dict suitable for constructing an AgentCard + AgentIdentity.
+        """
+        name = well_known.get("name", "unknown-agent")
+        description = well_known.get("description", "")
+        skills: List[str] = [
+            s.get("name", "") for s in well_known.get("skills", []) if s.get("name")
+        ]
+
+        return {
+            "identity": {
+                "did": "",  # will be auto-generated
+                "display_name": name,
+                "agent_type": "agent",
+                "capabilities": skills,
+                "version": well_known.get("version", "1.0"),
+                "public_key": None,
+            },
+            "description": description,
+            "skills": skills,
+            "channels": well_known.get("supportedModes", []),
+            "endpoints": {"http": endpoint or well_known.get("url", "")},
+            "declared_capabilities": [],
+            "metadata": {
+                "protocol": "acp",
+                "original": well_known,
+            },
+        }

roar_sdk-0.2.0/src/roar_sdk/adapters/detect.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+"""Protocol auto-detection — sniff incoming messages to identify their format.
+
+Examines the structure of an incoming JSON message to determine whether
+it's ROAR native, MCP (JSON-RPC 2.0), A2A, or ACP protocol format, then
+routes to the appropriate adapter.
+
+Usage::
+
+    from roar_sdk.adapters.detect import detect_protocol, ProtocolType
+
+    msg = json.loads(raw_body)
+    protocol = detect_protocol(msg)
+
+    if protocol == ProtocolType.ROAR:
+        roar_msg = ROARMessage.model_validate(msg)
+    elif protocol == ProtocolType.MCP:
+        roar_msg = MCPAdapter.mcp_to_roar(...)
+    elif protocol == ProtocolType.A2A:
+        roar_msg = A2AAdapter.a2a_task_to_roar(...)
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict
+
+
+class ProtocolType(str, Enum):
+    """Detected protocol type."""
+
+    ROAR = "roar"
+    MCP = "mcp"
+    A2A = "a2a"
+    ACP = "acp"
+    UNKNOWN = "unknown"
+
+
+_MCP_METHOD_PREFIXES = (
+    "tools/",
+    "resources/",
+    "prompts/",
+    "completion/",
+    "initialize",
+    "notifications/",
+)
+
+_A2A_METHOD_PREFIXES = ("tasks/", "agent/")
+
+
+def detect_protocol(message: Dict[str, Any]) -> ProtocolType:
+    """Detect the protocol of an incoming message.
+
+    Detection heuristics (in priority order):
+    1. ROAR: Has "roar" version field and "intent" field
+    2. ACP: Has "role" field and "content" field (ACP message body)
+    3. MCP: JSON-RPC 2.0 with MCP method prefix
+    4. A2A: JSON-RPC 2.0 with tasks/ or agent/ method prefix, or task envelope
+
+    Args:
+        message: The raw JSON message dict.
+
+    Returns:
+        The detected ProtocolType.
+    """
+    # ROAR native
+    if "roar" in message and "intent" in message:
+        return ProtocolType.ROAR
+
+    # ACP message (session-based, role/content structure)
+    if "role" in message and "content" in message:
+        return ProtocolType.ACP
+
+    # JSON-RPC based protocols
+    if message.get("jsonrpc") == "2.0":
+        method = message.get("method", "")
+
+        if any(method.startswith(p) for p in _A2A_METHOD_PREFIXES):
+            return ProtocolType.A2A
+
+        if any(method.startswith(p) for p in _MCP_METHOD_PREFIXES):
+            return ProtocolType.MCP
+
+        # Infer from result structure
+        result = message.get("result", {})
+        if isinstance(result, dict):
+            if "status" in result and "id" in result:
+                return ProtocolType.A2A
+            if "tools" in result or "resources" in result:
+                return ProtocolType.MCP
+
+    # A2A task envelope (no jsonrpc wrapper)
+    if "status" in message and "id" in message and "artifacts" in message:
+        return ProtocolType.A2A
+
+    return ProtocolType.UNKNOWN