aroha 1.0.0__py3-none-any.whl

aroha/__init__.py

@@ -0,0 +1,33 @@
+"""
+aroha — Aroha Protocol, Python SDK
+
+    aroha.identity    → Layer 1 (DID, Ed25519, Verifiable Credentials)
+    aroha.crypto      → Signing, verification, encryption
+    aroha.messages    → Layer 3 (envelope builder/validator, all message types)
+    aroha.transport   → Layer 0 (HTTP + WebSocket server/client)
+    aroha.orchestrator→ Layer 4 (saga engine, agent selector)
+    aroha.csn         → Capability Specification Notation
+    aroha.mandate     → Spending mandates / RBAC
+    aroha.reputation  → Stake-weighted reputation engine
+
+Framework bridges (optional — install extras):
+    aroha.bridges.langchain  (pip install aroha[langchain])
+    aroha.bridges.crewai     (pip install aroha[crewai])
+    aroha.bridges.autogen    (pip install aroha[autogen])
+"""
+
+from aroha.identity import generate_did, AgentKeyPair, DIDDocument
+from aroha.messages import build_envelope, validate_envelope, ArohaEnvelope
+from aroha.transport import ArohaServer, ArohaClient
+
+__version__ = "1.0.0"
+__all__ = [
+    "generate_did",
+    "AgentKeyPair",
+    "DIDDocument",
+    "build_envelope",
+    "validate_envelope",
+    "ArohaEnvelope",
+    "ArohaServer",
+    "ArohaClient",
+]

aroha/bridges/__init__.py

@@ -0,0 +1,5 @@
+# Framework bridges — optional, installed via extras:
+#   pip install aroha[langchain]   → aroha.bridges.langchain_bridge
+#   pip install aroha[crewai]      → aroha.bridges.crewai_bridge
+#   pip install aroha[autogen]     → aroha.bridges.autogen_bridge
+

aroha/bridges/autogen_bridge.py

@@ -0,0 +1,122 @@
+"""
+Aroha ↔ AutoGen Bridge
+
+Wraps Aroha capabilities as AutoGen FunctionTool objects so AutoGen agents
+(including AssistantAgent, ConversableAgent) can call Aroha capabilities as
+part of their conversations.
+
+Usage:
+    from aroha.bridges.autogen_bridge import aroha_tools_for_autogen
+    from autogen import AssistantAgent, UserProxyAgent
+
+    tools = aroha_tools_for_autogen(
+        agents=discovered_agents,
+        capability_ids=["search-flights", "book-flight"],
+        orchestrator_did=identity.did,
+        private_key=identity.private_key,
+        client=ArohaClient(),
+    )
+
+    assistant = AssistantAgent("assistant", llm_config={"tools": tools})
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from aroha.messages import build_envelope, new_correlation_id
+from aroha.transport import ArohaClient
+
+try:
+    from autogen import FunctionTool
+except ImportError:
+    raise ImportError("Install AutoGen support: pip install aroha[autogen]")
+
+
+def aroha_tools_for_autogen(
+    agents: list[dict[str, Any]],   # [{"did", "endpoint", "manifest"}]
+    capability_ids: list[str],
+    orchestrator_did: str,
+    private_key: Any,               # Ed25519PrivateKey
+    client: ArohaClient,
+) -> list[FunctionTool]:
+    """
+    Convert discovered Aroha agent capabilities into AutoGen FunctionTool objects.
+
+    Args:
+        agents:           List of discovered Aroha agents
+        capability_ids:   Which capabilities to expose as tools
+        orchestrator_did: DID of the orchestrating agent
+        private_key:      Ed25519PrivateKey of the orchestrator
+        client:           ArohaClient instance
+
+    Returns:
+        List of FunctionTool objects ready to pass as ``llm_config["tools"]``
+    """
+    tools: list[FunctionTool] = []
+    correlation_id = new_correlation_id()
+
+    for agent in agents:
+        manifest = agent.get("manifest", {})
+        for cap in manifest.get("capabilities", []):
+            if cap["id"] not in capability_ids:
+                continue
+
+            # Capture loop variables for closure
+            cap_id        = cap["id"]
+            agent_did     = agent["did"]
+            agent_endpoint = agent["endpoint"]
+            description   = cap.get("description", f"Aroha capability: {cap_id}")
+
+            def make_func(
+                _cap_id: str,
+                _agent_did: str,
+                _endpoint: str,
+                _corr_id: str,
+                _priv: Any,
+                _client: ArohaClient,
+            ):
+                async def _call_capability(**kwargs: Any) -> str:
+                    envelope = build_envelope(
+                        "ArohaRequest",
+                        orchestrator_did,
+                        _agent_did,
+                        {"capability": _cap_id, "params": kwargs},
+                        _corr_id,
+                        _priv,
+                    )
+                    response = await _client.send(_endpoint, envelope)
+                    if response is None:
+                        return "Request accepted (async)"
+                    if response.get("type") == "ArohaError":
+                        return f"Error: {response['body'].get('message')}"
+                    return json.dumps(response["body"].get("result", {}), indent=2)
+
+                def call_capability(**kwargs: Any) -> str:
+                    """Synchronous wrapper for AutoGen's function calling."""
+                    return asyncio.run(_call_capability(**kwargs))
+
+                call_capability.__name__ = "aroha_" + _cap_id.replace("-", "_")
+                call_capability.__doc__  = description
+                return call_capability
+
+            func = make_func(
+                cap_id, agent_did, agent_endpoint,
+                correlation_id, private_key, client,
+            )
+
+            # Build a minimal JSON Schema for the input params from the manifest
+            input_schema = cap.get("inputSchema", {"type": "object", "properties": {}})
+
+            tool = FunctionTool(
+                func,
+                description=description,
+                name="aroha_" + cap_id.replace("-", "_"),
+                input_schema=input_schema,
+            )
+            tools.append(tool)
+
+    return tools
+

aroha/bridges/crewai_bridge.py

@@ -0,0 +1,87 @@
+"""
+Aroha ↔ CrewAI Bridge
+
+Wraps a Aroha provider agent as a CrewAI Tool so CrewAI agents
+can call Aroha capabilities as part of their crew workflows.
+
+Usage:
+    from aroha.bridges.crewai_bridge import ArohaCrewTool
+    from crewai import Agent, Task, Crew
+
+    flight_tool = ArohaCrewTool(
+        capability_id="search-flights",
+        agent_did="did:aroha:expedia-flights-v2",
+        agent_endpoint="https://agents.expedia.com/aroha/v1",
+        orchestrator_did=identity.did,
+        private_key=identity.private_key,
+    )
+
+    researcher = Agent(role="Travel Researcher", tools=[flight_tool], ...)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from aroha.messages import build_envelope, new_correlation_id
+from aroha.transport import ArohaClient
+
+try:
+    from crewai.tools import BaseTool as CrewBaseTool
+except ImportError:
+    raise ImportError("Install CrewAI support: pip install aroha[crewai]")
+
+
+class ArohaCrewTool(CrewBaseTool):
+    """CrewAI tool backed by a Aroha capability."""
+
+    name: str
+    description: str
+    agent_did: str
+    agent_endpoint: str
+    capability_id: str
+    orchestrator_did: str
+    _private_key: Any
+    _client: ArohaClient
+
+    def __init__(
+        self,
+        capability_id: str,
+        agent_did: str,
+        agent_endpoint: str,
+        orchestrator_did: str,
+        private_key: Any,
+        description: str = "",
+    ) -> None:
+        super().__init__(
+            name=f"aroha_{capability_id.replace('-', '_')}",
+            description=description or f"Aroha capability: {capability_id}",
+        )
+        self.capability_id = capability_id
+        self.agent_did = agent_did
+        self.agent_endpoint = agent_endpoint
+        self.orchestrator_did = orchestrator_did
+        self._private_key = private_key
+        self._client = ArohaClient()
+
+    def _run(self, **kwargs: Any) -> str:
+        return asyncio.run(self._execute(kwargs))
+
+    async def _execute(self, params: dict[str, Any]) -> str:
+        envelope = build_envelope(
+            "ArohaRequest",
+            self.orchestrator_did,
+            self.agent_did,
+            {"capability": self.capability_id, "params": params},
+            new_correlation_id(),
+            self._private_key,
+        )
+        response = await self._client.send(self.agent_endpoint, envelope)
+        if response is None:
+            return "Request accepted (async)"
+        if response.get("type") == "ArohaError":
+            return f"Error: {response['body'].get('message')}"
+        return json.dumps(response["body"].get("result", {}), indent=2)
+

aroha/bridges/langchain_bridge.py

@@ -0,0 +1,114 @@
+"""
+Aroha ↔ LangChain Bridge
+
+Exposes Aroha capabilities as LangChain Tools so any LangChain/LangGraph
+agent can call them without knowing about the Aroha protocol.
+
+Usage:
+    from aroha.bridges.langchain_bridge import aroha_tools_for_agent
+
+    tools = await aroha_tools_for_agent(
+        discovery=discovery,
+        capability_ids=["search-flights", "book-flight"],
+        orchestrator_did=identity.did,
+        private_key=identity.private_key,
+        client=ArohaClient(),
+    )
+    agent = create_react_agent(llm, tools)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from typing import Any, Optional, Type
+
+from aroha.messages import build_envelope, new_correlation_id
+from aroha.transport import ArohaClient
+
+try:
+    from langchain_core.tools import BaseTool
+    from pydantic import BaseModel, Field
+except ImportError:
+    raise ImportError("Install langchain support: pip install aroha[langchain]")
+
+
+class ArohaCapabilityTool(BaseTool):
+    """A LangChain Tool backed by a Aroha capability."""
+
+    name: str
+    description: str
+    agent_did: str
+    agent_endpoint: str
+    capability_id: str
+    orchestrator_did: str
+    correlation_id: str
+    _private_key: Any  # Ed25519PrivateKey
+    _client: Any       # ArohaClient
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def _run(self, **kwargs: Any) -> str:
+        """Synchronous wrapper — runs the async send in a new event loop."""
+        return asyncio.run(self._arun(**kwargs))
+
+    async def _arun(self, **kwargs: Any) -> str:
+        envelope = build_envelope(
+            "ArohaRequest",
+            self.orchestrator_did,
+            self.agent_did,
+            {"capability": self.capability_id, "params": kwargs},
+            self.correlation_id,
+            self._private_key,
+        )
+        response = await self._client.send(self.agent_endpoint, envelope)
+        if response is None:
+            return "Agent accepted request (async — check WebSocket stream)"
+        if response.get("type") == "ArohaError":
+            return f"Error: {response['body'].get('message')}"
+        return json.dumps(response["body"].get("result", {}), indent=2)
+
+
+async def aroha_tools_for_agent(
+    agents: list[dict[str, Any]],  # [{"did", "endpoint", "manifest"}]
+    capability_ids: list[str],
+    orchestrator_did: str,
+    private_key: Any,
+    client: ArohaClient,
+) -> list[ArohaCapabilityTool]:
+    """
+    Convert Aroha agent capabilities into LangChain tools.
+
+    Args:
+        agents:           List of discovered Aroha agents
+        capability_ids:   Which capabilities to expose as tools
+        orchestrator_did: DID of the orchestrating agent
+        private_key:      Ed25519PrivateKey of the orchestrator
+        client:           ArohaClient instance
+    """
+    tools = []
+    correlation_id = new_correlation_id()
+
+    for agent in agents:
+        manifest = agent.get("manifest", {})
+        for cap in manifest.get("capabilities", []):
+            if cap["id"] not in capability_ids:
+                continue
+
+            tool = ArohaCapabilityTool(
+                name=f"aroha_{cap['id'].replace('-', '_')}",
+                description=cap.get("description", cap["id"]),
+                agent_did=agent["did"],
+                agent_endpoint=agent["endpoint"],
+                capability_id=cap["id"],
+                orchestrator_did=orchestrator_did,
+                correlation_id=correlation_id,
+            )
+            tool._private_key = private_key
+            tool._client = client
+            tools.append(tool)
+
+    return tools
+

aroha/client.py

@@ -0,0 +1,38 @@
+import uuid
+import httpx
+from .envelope import build_envelope
+
+
+class ArohaClient:
+    """Minimal async HTTP client for sending Aroha messages."""
+
+    def __init__(self, agent: dict, *, timeout: float = 30.0):
+        self.agent = agent
+        self.timeout = timeout
+
+    async def request(
+        self,
+        endpoint: str,
+        to_did: str,
+        capability: str,
+        params: dict,
+        *,
+        correlation_id: str | None = None,
+    ) -> dict:
+        cid = correlation_id or f"saga-{uuid.uuid4()}"
+        envelope = build_envelope(
+            "ArohaRequest",
+            self.agent["did"],
+            to_did,
+            {"capability": capability, "params": params},
+            cid,
+            self.agent["private_key"],
+        )
+        async with httpx.AsyncClient(timeout=self.timeout) as http:
+            res = await http.post(
+                endpoint,
+                json=envelope,
+                headers={"Content-Type": "application/json"},
+            )
+            res.raise_for_status()
+            return res.json()

aroha/crypto.py

@@ -0,0 +1,143 @@
+"""
+Aroha Python SDK — Crypto: Signing + Encryption
+
+Ed25519 signing (per spec: canonical JSON, keys sorted, proof excluded).
+AES-256-GCM encryption for sensitive body fields (DIDComm-style).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+
+# ── Signing ────────────────────────────────────────────────────────────────────
+
+def sign_message(
+    message: dict[str, Any],
+    private_key: Ed25519PrivateKey,
+    verification_method_id: str,
+) -> dict[str, str]:
+    """
+    Sign a Aroha message. Returns a proof dict to embed in the envelope.
+
+    Per spec: signature covers canonical JSON with 'proof' field excluded,
+    all keys sorted lexicographically at every nesting level.
+    """
+    canonical = canonicalize_message(message)
+    signature = private_key.sign(canonical.encode("utf-8"))
+    proof_value = base64.urlsafe_b64encode(signature).rstrip(b"=").decode()
+
+    return {
+        "type": "Ed25519Signature2020",
+        "created": datetime.now(timezone.utc).isoformat(),
+        "verificationMethod": verification_method_id,
+        "proofPurpose": "authentication",
+        "proofValue": proof_value,
+    }
+
+
+def verify_message_signature(
+    message: dict[str, Any],
+    public_key: Ed25519PublicKey,
+) -> bool:
+    """
+    Verify a Aroha message signature.
+    Returns True if valid, False otherwise.
+    """
+    proof = message.get("proof")
+    if not proof or not proof.get("proofValue"):
+        return False
+
+    canonical = canonicalize_message(message)
+    proof_value = proof["proofValue"]
+
+    # Restore base64url padding
+    padding = 4 - len(proof_value) % 4
+    if padding != 4:
+        proof_value += "=" * padding
+    signature = base64.urlsafe_b64decode(proof_value)
+
+    try:
+        public_key.verify(signature, canonical.encode("utf-8"))
+        return True
+    except Exception:
+        return False
+
+
+def canonicalize_message(message: dict[str, Any]) -> str:
+    """
+    Produce canonical JSON string for signing.
+    Excludes 'proof' field, sorts all keys lexicographically.
+    """
+    without_proof = {k: v for k, v in message.items() if k != "proof"}
+    return json.dumps(_sort_keys_deep(without_proof), separators=(",", ":"))
+
+
+def _sort_keys_deep(obj: Any) -> Any:
+    if isinstance(obj, dict):
+        return {k: _sort_keys_deep(v) for k, v in sorted(obj.items())}
+    if isinstance(obj, list):
+        return [_sort_keys_deep(item) for item in obj]
+    return obj
+
+
+# ── Encryption (DIDComm-style AES-256-GCM) ────────────────────────────────────
+
+def encrypt_body(plaintext: dict[str, Any], recipient_pub_bytes: bytes) -> dict[str, str]:
+    """
+    Encrypt a message body for a specific recipient.
+    Uses AES-256-GCM with a random key + IV.
+
+    Returns an EncryptedBody dict with alg, iv, ciphertext, tag.
+
+    Note: In production use full ECDH-ES+A256GCM. This implementation
+    uses a simplified symmetric approach suitable for testing.
+    For full DIDComm v2 compliance use the `didcomm` PyPI package.
+    """
+    key = os.urandom(32)
+    iv = os.urandom(12)
+    aesgcm = AESGCM(key)
+    payload = json.dumps(plaintext).encode("utf-8")
+    encrypted = aesgcm.encrypt(iv, payload, None)
+    ciphertext = encrypted[:-16]
+    tag = encrypted[-16:]
+
+    def b64(b: bytes) -> str:
+        return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+
+    return {
+        "alg": "A256GCM",
+        "iv": b64(iv),
+        "ciphertext": b64(ciphertext),
+        "tag": b64(tag),
+        # In full ECDH-ES: encrypted_key and epk would be included here
+        "_key": b64(key),  # DEV ONLY — remove in production
+    }
+
+
+def decrypt_body(encrypted: dict[str, str], private_key_bytes: bytes) -> dict[str, Any]:
+    """Decrypt an encrypted message body."""
+    def b64d(s: str) -> bytes:
+        s += "=" * (4 - len(s) % 4)
+        return base64.urlsafe_b64decode(s)
+
+    key = b64d(encrypted["_key"])  # DEV ONLY
+    iv = b64d(encrypted["iv"])
+    ciphertext = b64d(encrypted["ciphertext"])
+    tag = b64d(encrypted["tag"])
+
+    aesgcm = AESGCM(key)
+    plaintext = aesgcm.decrypt(iv, ciphertext + tag, None)
+    return json.loads(plaintext.decode("utf-8"))