theprotocol-sdk 0.1.0__tar.gz

theprotocol_sdk-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# TheProtocol — Root .gitignore
+# Created: 2026-03-09 (§4.1 Credentials Rotation)
+
+# !! NEVER COMMIT PRODUCTION SECRETS !!
+.env.production
+.env.production.*
+
+# Session logs (operational, not source)
+sessionlogs2026/
+
+# Debug/runtime artifacts
+logs/
+*.log
+APEX_PREDATOR_JOBS.log
+
+# Node
+node_modules/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+dist/
+build/
+
+# OS
+.DS_Store
+Thumbs.db

theprotocol_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: theprotocol-sdk
+Version: 0.1.0
+Summary: TheProtocol SDK — Build and call A2A agents. Protocol bridges for ACP, ADK, and more.
+Project-URL: Homepage, https://theprotocol.cloud
+Project-URL: Documentation, https://api.theprotocol.cloud/docs
+Project-URL: Repository, https://github.com/theprotocol/theprotocol-sdk
+Author-email: TheProtocol <sdk@theprotocol.cloud>
+License: Apache-2.0
+Keywords: a2a,agents,ai,mcp,protocol,theprotocol
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.111; extra == 'all'
+Requires-Dist: keyring>=24; extra == 'all'
+Provides-Extra: keyring
+Requires-Dist: keyring>=24; extra == 'keyring'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.111; extra == 'server'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: respx>=0.20; extra == 'test'
+Description-Content-Type: text/markdown
+
+# theprotocol-sdk
+
+Build and call A2A (Agent-to-Agent) agents on [TheProtocol](https://theprotocol.cloud).
+
+## Install
+
+```bash
+pip install theprotocol-sdk           # Client only (call agents)
+pip install theprotocol-sdk[server]   # + FastAPI router (build agents)
+pip install theprotocol-sdk[all]      # Everything
+```
+
+## Build an Agent (10 lines)
+
+```python
+from theprotocol.agent import BaseA2AAgent, create_a2a_router
+from theprotocol.models import Message, TextPart
+from fastapi import FastAPI
+
+class MyAgent(BaseA2AAgent):
+    async def handle_task_send(self, task_id, message):
+        return "task-1"  # Return task ID
+    async def handle_task_get(self, task_id):
+        ...  # Return Task object
+    async def handle_task_cancel(self, task_id):
+        return True
+    async def handle_subscribe_request(self, task_id):
+        yield  # SSE events
+
+app = FastAPI()
+app.include_router(create_a2a_router(MyAgent()))
+```
+
+## Call a Remote Agent
+
+```python
+from theprotocol.client import A2AClient, KeyManager
+from theprotocol.models import Message, TextPart
+
+async with A2AClient() as client:
+    task_id = await client.initiate_task(agent_card, message, key_manager)
+    task = await client.get_task_status(agent_card, task_id, key_manager)
+    print(task.state)  # COMPLETED
+```
+
+## Protocol Bridges (coming soon)
+
+Translate between A2A and other agent protocols:
+
+```python
+from theprotocol.bridges.acp import ACPBridge  # ACP ↔ A2A
+from theprotocol.bridges.adk import ADKBridge  # Google ADK ↔ A2A
+```
+
+## Registry Operations
+
+For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/docs) instead of SDK functions. 19 tools available via Claude Desktop or any MCP client.
+
+## License
+
+Apache-2.0

theprotocol_sdk-0.1.0/README.md

@@ -0,0 +1,61 @@
+# theprotocol-sdk
+
+Build and call A2A (Agent-to-Agent) agents on [TheProtocol](https://theprotocol.cloud).
+
+## Install
+
+```bash
+pip install theprotocol-sdk           # Client only (call agents)
+pip install theprotocol-sdk[server]   # + FastAPI router (build agents)
+pip install theprotocol-sdk[all]      # Everything
+```
+
+## Build an Agent (10 lines)
+
+```python
+from theprotocol.agent import BaseA2AAgent, create_a2a_router
+from theprotocol.models import Message, TextPart
+from fastapi import FastAPI
+
+class MyAgent(BaseA2AAgent):
+    async def handle_task_send(self, task_id, message):
+        return "task-1"  # Return task ID
+    async def handle_task_get(self, task_id):
+        ...  # Return Task object
+    async def handle_task_cancel(self, task_id):
+        return True
+    async def handle_subscribe_request(self, task_id):
+        yield  # SSE events
+
+app = FastAPI()
+app.include_router(create_a2a_router(MyAgent()))
+```
+
+## Call a Remote Agent
+
+```python
+from theprotocol.client import A2AClient, KeyManager
+from theprotocol.models import Message, TextPart
+
+async with A2AClient() as client:
+    task_id = await client.initiate_task(agent_card, message, key_manager)
+    task = await client.get_task_status(agent_card, task_id, key_manager)
+    print(task.state)  # COMPLETED
+```
+
+## Protocol Bridges (coming soon)
+
+Translate between A2A and other agent protocols:
+
+```python
+from theprotocol.bridges.acp import ACPBridge  # ACP ↔ A2A
+from theprotocol.bridges.adk import ADKBridge  # Google ADK ↔ A2A
+```
+
+## Registry Operations
+
+For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/docs) instead of SDK functions. 19 tools available via Claude Desktop or any MCP client.
+
+## License
+
+Apache-2.0

theprotocol_sdk-0.1.0/examples/simple_agent.py

@@ -0,0 +1,64 @@
+"""
+Minimal A2A agent example.
+
+Run: uvicorn simple_agent:app --port 8080
+Then register on TheProtocol via MCP: createAgent(name="My Agent", ...)
+"""
+
+import uuid
+import datetime
+from fastapi import FastAPI
+
+from theprotocol.agent import BaseA2AAgent, create_a2a_router
+from theprotocol.models import Message, Task, TaskState, TextPart
+
+
+class EchoAgent(BaseA2AAgent):
+    """Simple agent that echoes back whatever you send it."""
+
+    def __init__(self):
+        super().__init__(agent_metadata={"name": "Echo Agent"})
+        self.tasks = {}
+
+    async def handle_task_send(self, task_id, message):
+        tid = task_id or f"task-{uuid.uuid4().hex[:8]}"
+        # Echo the first text part
+        text = ""
+        for part in message.parts:
+            if hasattr(part, 'content') and isinstance(part.content, str):
+                text = part.content
+                break
+        self.tasks[tid] = {
+            "state": TaskState.COMPLETED,
+            "response": f"Echo: {text}",
+            "message": message,
+        }
+        return tid
+
+    async def handle_task_get(self, task_id):
+        t = self.tasks.get(task_id)
+        if not t:
+            raise ValueError(f"Task {task_id} not found")
+        now = datetime.datetime.now(datetime.timezone.utc)
+        return Task(
+            id=task_id,
+            state=t["state"],
+            createdAt=now,
+            updatedAt=now,
+            messages=[t["message"]],
+        )
+
+    async def handle_task_cancel(self, task_id):
+        if task_id in self.tasks:
+            self.tasks[task_id]["state"] = TaskState.CANCELED
+            return True
+        return False
+
+    async def handle_subscribe_request(self, task_id):
+        # No streaming for this simple agent
+        return
+        yield  # Make it a generator
+
+
+app = FastAPI(title="Echo Agent")
+app.include_router(create_a2a_router(EchoAgent()), prefix="/a2a")

theprotocol_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "theprotocol-sdk"
+version = "0.1.0"
+description = "TheProtocol SDK — Build and call A2A agents. Protocol bridges for ACP, ADK, and more."
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+authors = [
+    {name = "TheProtocol", email = "sdk@theprotocol.cloud"},
+]
+keywords = ["agents", "a2a", "protocol", "ai", "mcp", "theprotocol"]
+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",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "pydantic>=2.0,<3.0",
+    "httpx[http2]>=0.27",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+server = ["fastapi>=0.111"]
+keyring = ["keyring>=24"]
+all = ["theprotocol-sdk[server,keyring]"]
+test = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.20",
+]
+
+[project.urls]
+Homepage = "https://theprotocol.cloud"
+Documentation = "https://api.theprotocol.cloud/docs"
+Repository = "https://github.com/theprotocol/theprotocol-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/theprotocol"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

theprotocol_sdk-0.1.0/src/theprotocol/__init__.py

@@ -0,0 +1,10 @@
+"""
+TheProtocol SDK — Build and call A2A agents.
+
+Usage:
+    from theprotocol.models import Message, Task, AgentCard
+    from theprotocol.agent import BaseA2AAgent, create_a2a_router
+    from theprotocol.client import A2AClient, KeyManager
+"""
+
+__version__ = "0.1.0"

theprotocol_sdk-0.1.0/src/theprotocol/agent/__init__.py

@@ -0,0 +1,17 @@
+"""Build A2A-compliant agents."""
+
+from .base import BaseA2AAgent
+from .task_store import BaseTaskStore, InMemoryTaskStore, TaskContext
+from .decorators import a2a_method
+
+__all__ = [
+    "BaseA2AAgent", "BaseTaskStore", "InMemoryTaskStore", "TaskContext",
+    "a2a_method",
+]
+
+# Import router factory only if fastapi is available
+try:
+    from .router import create_a2a_router
+    __all__.append("create_a2a_router")
+except ImportError:
+    pass

theprotocol_sdk-0.1.0/src/theprotocol/agent/base.py

@@ -0,0 +1,63 @@
+"""
+BaseA2AAgent — Abstract base class for TheProtocol A2A agents.
+
+Subclass this and implement the handle_* methods to create an agent.
+"""
+
+import logging
+from typing import Optional, Dict, Any, AsyncGenerator
+
+from ..models import Message, Task, A2AEvent
+
+logger = logging.getLogger(__name__)
+
+
+class BaseA2AAgent:
+    """
+    Abstract base class for A2A agents.
+
+    Implement the four handle methods to define your agent's behavior:
+    - handle_task_send: Process incoming messages
+    - handle_task_get: Return current task state
+    - handle_task_cancel: Cancel a running task
+    - handle_subscribe_request: Stream SSE events for a task
+
+    Example::
+
+        class MyAgent(BaseA2AAgent):
+            async def handle_task_send(self, task_id, message):
+                # Process the message and return task ID
+                return "task-123"
+
+            async def handle_task_get(self, task_id):
+                # Return the current task state
+                return Task(id=task_id, state=TaskState.COMPLETED, ...)
+
+            async def handle_task_cancel(self, task_id):
+                return True
+
+            async def handle_subscribe_request(self, task_id):
+                yield TaskStatusUpdateEvent(...)
+    """
+
+    def __init__(self, agent_metadata: Optional[Dict[str, Any]] = None):
+        self.agent_metadata = agent_metadata or {}
+        logger.info(f"Initialized {self.__class__.__name__}")
+
+    async def handle_task_send(self, task_id: Optional[str], message: Message) -> str:
+        """Handle incoming message. Return task ID."""
+        raise NotImplementedError("Implement handle_task_send")
+
+    async def handle_task_get(self, task_id: str) -> Task:
+        """Return current task state."""
+        raise NotImplementedError("Implement handle_task_get")
+
+    async def handle_task_cancel(self, task_id: str) -> bool:
+        """Cancel a task. Return True if accepted."""
+        raise NotImplementedError("Implement handle_task_cancel")
+
+    async def handle_subscribe_request(self, task_id: str) -> AsyncGenerator[A2AEvent, None]:
+        """Yield SSE events for a task."""
+        raise NotImplementedError("Implement handle_subscribe_request")
+        if False:  # pragma: no cover
+            yield  # Make it a generator

theprotocol_sdk-0.1.0/src/theprotocol/agent/decorators.py

@@ -0,0 +1,29 @@
+"""Decorator for custom A2A JSON-RPC methods."""
+
+import asyncio
+from typing import Any, Callable, TypeVar
+
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+def a2a_method(method_name: str) -> Callable[[F], F]:
+    """
+    Mark an agent method as a handler for a custom A2A JSON-RPC method.
+
+    Example::
+
+        class MyAgent(BaseA2AAgent):
+            @a2a_method("custom/analyze")
+            async def analyze(self, data: dict) -> dict:
+                return {"result": "analyzed"}
+    """
+    if not isinstance(method_name, str) or not method_name:
+        raise ValueError("a2a_method requires a non-empty method name string.")
+
+    def _decorator(func: F) -> F:
+        if not asyncio.iscoroutinefunction(func):
+            raise TypeError(f"A2A method handler '{func.__name__}' must be async.")
+        setattr(func, '_a2a_method_name', method_name)
+        return func
+
+    return _decorator

theprotocol_sdk-0.1.0/src/theprotocol/agent/router.py

@@ -0,0 +1,194 @@
+"""FastAPI router factory for A2A agents."""
+
+import json
+import inspect
+import logging
+from typing import Any, Dict, Optional, Union, List, Callable, AsyncGenerator
+
+import pydantic
+from pydantic_core import ValidationError
+from fastapi import APIRouter, Depends, Request, Response, status
+from fastapi.responses import StreamingResponse, JSONResponse
+
+from .base import BaseA2AAgent
+from .task_store import BaseTaskStore, InMemoryTaskStore, TaskContext
+from ..models import (
+    Message, Task, TaskState, A2AEvent,
+    TaskSendParams, TaskSendResult, TaskGetParams, GetTaskResult,
+    TaskCancelParams, TaskCancelResult,
+    TaskStatusUpdateEvent, TaskMessageEvent, TaskArtifactUpdateEvent,
+)
+from ..exceptions import AgentServerError, TaskNotFoundError
+
+logger = logging.getLogger(__name__)
+
+# JSON-RPC error codes
+JSONRPC_PARSE_ERROR = -32700
+JSONRPC_INVALID_REQUEST = -32600
+JSONRPC_METHOD_NOT_FOUND = -32601
+JSONRPC_INVALID_PARAMS = -32602
+JSONRPC_INTERNAL_ERROR = -32603
+JSONRPC_APP_ERROR = -32000
+JSONRPC_TASK_NOT_FOUND = -32001
+
+
+def _jsonrpc_error(req_id: Union[str, int, None], code: int, message: str, data: Optional[Any] = None) -> Dict:
+    err: Dict[str, Any] = {"code": code, "message": message}
+    if data is not None:
+        err["data"] = data
+    return {"jsonrpc": "2.0", "error": err, "id": req_id}
+
+
+def _jsonrpc_success(req_id: Union[str, int, None], result: Any) -> Dict:
+    return {"jsonrpc": "2.0", "result": result, "id": req_id}
+
+
+def _format_sse_bytes(event: A2AEvent) -> Optional[bytes]:
+    event_type = None
+    if isinstance(event, TaskStatusUpdateEvent):
+        event_type = "task_status"
+    elif isinstance(event, TaskMessageEvent):
+        event_type = "task_message"
+    elif isinstance(event, TaskArtifactUpdateEvent):
+        event_type = "task_artifact"
+    if event_type is None:
+        return None
+    try:
+        json_data = event.model_dump_json(by_alias=True)
+        return f"event: {event_type}\ndata: {json_data}\n\n".encode("utf-8")
+    except Exception:
+        return None
+
+
+async def _sse_wrapper(task_id: str, gen: AsyncGenerator[A2AEvent, None]) -> AsyncGenerator[bytes, None]:
+    try:
+        async for event in gen:
+            data = _format_sse_bytes(event)
+            if data:
+                yield data
+    except TaskNotFoundError as e:
+        yield f'event: error\ndata: {json.dumps({"error": "task_not_found", "message": str(e)})}\n\n'.encode()
+    except Exception as e:
+        yield f'event: error\ndata: {json.dumps({"error": "stream_error", "message": str(e)})}\n\n'.encode()
+
+
+def create_a2a_router(
+    agent: BaseA2AAgent,
+    prefix: str = "",
+    tags: Optional[List[str]] = None,
+    task_store: Optional[BaseTaskStore] = None,
+    dependencies: Optional[list] = None,
+) -> APIRouter:
+    """
+    Create a FastAPI router that exposes an A2A agent via JSON-RPC 2.0.
+
+    Example::
+
+        from theprotocol.agent import BaseA2AAgent, create_a2a_router
+        from fastapi import FastAPI
+
+        class MyAgent(BaseA2AAgent):
+            async def handle_task_send(self, task_id, message):
+                return "task-1"
+            ...
+
+        app = FastAPI()
+        app.include_router(create_a2a_router(MyAgent()))
+    """
+    if tags is None:
+        tags = ["A2A Protocol"]
+    if task_store is None:
+        task_store = InMemoryTaskStore()
+    store = task_store
+
+    router = APIRouter(prefix=prefix, tags=tags, dependencies=dependencies or [])
+
+    # Discover @a2a_method decorated handlers
+    decorated: Dict[str, Callable] = {}
+    for name, method in inspect.getmembers(agent, predicate=inspect.iscoroutinefunction):
+        if hasattr(method, '_a2a_method_name'):
+            decorated[getattr(method, '_a2a_method_name')] = method
+
+    @router.post("/", summary="A2A JSON-RPC Endpoint")
+    async def handle_request(request: Request) -> Response:
+        req_id = None
+        try:
+            payload = await request.json()
+        except json.JSONDecodeError:
+            return JSONResponse(_jsonrpc_error(None, JSONRPC_PARSE_ERROR, "Parse error"))
+
+        if not isinstance(payload, dict):
+            return JSONResponse(_jsonrpc_error(None, JSONRPC_INVALID_REQUEST, "Payload must be JSON object"))
+
+        req_id = payload.get("id")
+        method = payload.get("method", "")
+        params = payload.get("params") or {}
+        if isinstance(params, list):
+            params = {}
+
+        if payload.get("jsonrpc") != "2.0":
+            return JSONResponse(_jsonrpc_error(req_id, JSONRPC_INVALID_REQUEST, "'jsonrpc' must be '2.0'"))
+        if not isinstance(method, str) or not method:
+            return JSONResponse(_jsonrpc_error(req_id, JSONRPC_INVALID_REQUEST, "'method' is required"))
+
+        try:
+            # Check decorated methods first
+            if method in decorated:
+                handler = decorated[method]
+                sig = inspect.signature(handler)
+                param_fields: Dict[str, Any] = {}
+                for pname, p in sig.parameters.items():
+                    if pname in ('self', 'cls'):
+                        continue
+                    ann = Any if p.annotation is inspect.Parameter.empty else p.annotation
+                    default = ... if p.default is inspect.Parameter.empty else p.default
+                    param_fields[pname] = (ann, default)
+
+                mapped = dict(params)
+                if "task_id" in [p for p in sig.parameters if p not in ('self', 'cls')] and "id" in params:
+                    mapped['task_id'] = params['id']
+
+                ParamsModel = pydantic.create_model(f'{handler.__name__}Params', **param_fields)
+                validated = ParamsModel.model_validate(mapped).model_dump()
+                result = await handler(**validated)
+                return JSONResponse(_jsonrpc_success(req_id, result))
+
+            elif method == "tasks/send":
+                vp = TaskSendParams.model_validate(params)
+                task_id = await agent.handle_task_send(task_id=vp.id, message=vp.message)
+                return JSONResponse(_jsonrpc_success(req_id, TaskSendResult(id=task_id).model_dump(mode='json')))
+
+            elif method == "tasks/get":
+                vp = TaskGetParams.model_validate(params)
+                task = await agent.handle_task_get(task_id=vp.id)
+                return JSONResponse(_jsonrpc_success(req_id, task.model_dump(mode='json', by_alias=True)))
+
+            elif method == "tasks/cancel":
+                vp = TaskCancelParams.model_validate(params)
+                ok = await agent.handle_task_cancel(task_id=vp.id)
+                return JSONResponse(_jsonrpc_success(req_id, TaskCancelResult(success=ok).model_dump(mode='json')))
+
+            elif method == "tasks/sendSubscribe":
+                task_id = params.get("id", "")
+                if not task_id:
+                    return JSONResponse(_jsonrpc_error(req_id, JSONRPC_INVALID_PARAMS, "'id' is required"))
+                gen = agent.handle_subscribe_request(task_id=task_id)
+                return StreamingResponse(content=_sse_wrapper(task_id, gen), media_type="text/event-stream")
+
+            else:
+                return JSONResponse(_jsonrpc_error(req_id, JSONRPC_METHOD_NOT_FOUND, f"Method not found: {method}"))
+
+        except TaskNotFoundError as e:
+            return JSONResponse(_jsonrpc_error(req_id, JSONRPC_TASK_NOT_FOUND, str(e)))
+        except (ValueError, TypeError, pydantic.ValidationError, ValidationError) as e:
+            return JSONResponse(_jsonrpc_error(req_id, JSONRPC_INVALID_PARAMS, f"Invalid parameters: {e}"))
+        except AgentServerError as e:
+            return JSONResponse(_jsonrpc_error(req_id, JSONRPC_APP_ERROR, f"Agent error: {e}"))
+        except Exception as e:
+            logger.exception(f"Unhandled error in A2A handler: {e}")
+            return JSONResponse(
+                _jsonrpc_error(req_id, JSONRPC_INTERNAL_ERROR, f"Internal error: {type(e).__name__}"),
+                status_code=500,
+            )
+
+    return router