trytet-client 0.2.0__py3-none-any.whl

trytet_client/__init__.py

@@ -0,0 +1,45 @@
+"""Trytet Python SDK — client for the Trytet Engine API, MCP, and telemetry."""
+
+from .client import TrytetClient
+from .models import (
+    AgentManifest,
+    CartridgeInvocation,
+    CartridgeResult,
+    CrashReport,
+    EgressPolicy,
+    ExecutionStatus,
+    FuelVoucher,
+    McpPrompt,
+    McpResource,
+    McpTool,
+    NorthstarReport,
+    SnapshotResponse,
+    StructuredTelemetry,
+    TelemetryEvent,
+    TetExecutionRequest,
+    TetExecutionResult,
+    TopologyEdge,
+)
+from .telemetry import TelemetryStream
+
+__all__ = [
+    "TrytetClient",
+    "TelemetryStream",
+    "AgentManifest",
+    "CartridgeInvocation",
+    "CartridgeResult",
+    "CrashReport",
+    "EgressPolicy",
+    "ExecutionStatus",
+    "FuelVoucher",
+    "McpPrompt",
+    "McpResource",
+    "McpTool",
+    "NorthstarReport",
+    "SnapshotResponse",
+    "StructuredTelemetry",
+    "TelemetryEvent",
+    "TetExecutionRequest",
+    "TetExecutionResult",
+    "TopologyEdge",
+]

trytet_client/client.py

@@ -0,0 +1,169 @@
+"""Trytet API client with retry, MCP support, and cartridge management."""
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .models import (
+    CartridgeInvocation,
+    CartridgeResult,
+    McpPrompt,
+    McpResource,
+    McpTool,
+    NorthstarReport,
+    SnapshotResponse,
+    TetExecutionRequest,
+    TetExecutionResult,
+    TopologyEdge,
+)
+from .telemetry import TelemetryStream
+
+
+class TrytetClient:
+    """Async HTTP client for the Trytet Engine API."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:3000",
+        max_retries: int = 3,
+        initial_delay_ms: int = 100,
+    ):
+        self._base = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._initial_delay = initial_delay_ms / 1000.0
+        self._client = httpx.AsyncClient(timeout=httpx.Timeout(30.0))
+
+    async def __aenter__(self) -> "TrytetClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    # -- retry helper -------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        retry_on_status: Optional[List[int]] = None,
+    ) -> httpx.Response:
+        statuses = retry_on_status or [502, 503, 504]
+        delay = self._initial_delay
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = await self._client.request(
+                    method, f"{self._base}{path}", json=json_body
+                )
+                if resp.status_code in statuses and attempt < self._max_retries:
+                    raise httpx.TransportError(f"Retryable status {resp.status_code}")
+                return resp
+            except (httpx.TransportError, httpx.ConnectError) as e:
+                if attempt == self._max_retries:
+                    raise
+                await asyncio.sleep(delay)
+                delay = min(delay * 2, 5.0)
+
+        raise RuntimeError("unreachable")
+
+    async def _post(self, path: str, body: Any = None) -> httpx.Response:
+        return await self._request("POST", path, json_body=body)
+
+    async def _get(self, path: str) -> httpx.Response:
+        return await self._request("GET", path)
+
+    async def _check(self, resp: httpx.Response) -> Dict[str, Any]:
+        if not resp.is_success:
+            text = resp.text[:500]
+            raise RuntimeError(f"Request failed ({resp.status_code}): {text}")
+        return resp.json()
+
+    # -- Agent lifecycle ----------------------------------------------------
+
+    async def execute(self, req: TetExecutionRequest) -> TetExecutionResult:
+        resp = await self._post("/v1/tet/execute", req.model_dump(exclude_none=True))
+        data = await self._check(resp)
+        return TetExecutionResult(**data)
+
+    async def snapshot(self, tet_id: str) -> SnapshotResponse:
+        resp = await self._post(f"/v1/tet/snapshot/{tet_id}")
+        data = await self._check(resp)
+        return SnapshotResponse(**data)
+
+    async def fork(
+        self, snapshot_id: str, req: TetExecutionRequest
+    ) -> TetExecutionResult:
+        resp = await self._post(
+            f"/v1/tet/fork/{snapshot_id}", req.model_dump(exclude_none=True)
+        )
+        data = await self._check(resp)
+        return TetExecutionResult(**data)
+
+    async def teleport(self, alias: str, target_node: str) -> None:
+        resp = await self._post(f"/v1/tet/teleport/{alias}", target_node)
+        await self._check(resp)
+
+    async def get_topology(self) -> List[TopologyEdge]:
+        resp = await self._get("/v1/topology")
+        data = await self._check(resp)
+        return [TopologyEdge(**e) for e in data]
+
+    async def get_swarm_metrics(self) -> NorthstarReport:
+        resp = await self._get("/v1/swarm/metrics")
+        data = await self._check(resp)
+        return NorthstarReport(**data)
+
+    async def get_health(self) -> Dict[str, Any]:
+        resp = await self._get("/health")
+        return await self._check(resp)
+
+    # -- Cartridge management -----------------------------------------------
+
+    async def invoke_cartridge(self, invocation: CartridgeInvocation) -> CartridgeResult:
+        resp = await self._post(
+            "/v1/cartridge/invoke", invocation.model_dump()
+        )
+        data = await self._check(resp)
+        return CartridgeResult(**data)
+
+    # -- MCP ----------------------------------------------------------------
+
+    async def _mcp_call(self, method: str, params: Any = None) -> Any:
+        import time
+
+        request = {
+            "jsonrpc": "2.0",
+            "id": int(time.time() * 1000),
+            "method": method,
+            "params": params,
+        }
+        resp = await self._post("/v1/mcp", request)
+        data = await self._check(resp)
+        return data.get("result")
+
+    async def list_tools(self) -> List[McpTool]:
+        result = await self._mcp_call("tools/list")
+        return [McpTool(**t) for t in (result or {}).get("tools", [])]
+
+    async def call_tool(self, name: str, arguments: Dict[str, Any]) -> Any:
+        return await self._mcp_call("tools/call", {"name": name, "arguments": arguments})
+
+    async def list_resources(self) -> List[McpResource]:
+        result = await self._mcp_call("resources/list")
+        return [McpResource(**r) for r in (result or {}).get("resources", [])]
+
+    async def list_prompts(self) -> List[McpPrompt]:
+        result = await self._mcp_call("prompts/list")
+        return [McpPrompt(**p) for p in (result or {}).get("prompts", [])]
+
+    # -- Telemetry ----------------------------------------------------------
+
+    def create_telemetry_stream(self) -> TelemetryStream:
+        ws_url = self._base.replace("http", "ws") + "/v1/swarm/stream"
+        return TelemetryStream(ws_url)

trytet_client/models.py

@@ -0,0 +1,151 @@
+"""Pydantic models for all Trytet API types."""
+
+from typing import Optional, Union, List, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class AgentManifestMetadata(BaseModel):
+    name: str
+    version: str
+    author_pubkey: Optional[str] = None
+
+
+class AgentManifestConstraints(BaseModel):
+    max_memory_pages: int
+    fuel_limit: int
+    max_egress_bytes: int
+
+
+class AgentManifestPermissions(BaseModel):
+    can_egress: List[str] = Field(default_factory=list)
+    can_persist: bool = False
+    can_teleport: bool = False
+    is_genesis_factory: bool = False
+    can_fork: bool = False
+
+
+class AgentManifest(BaseModel):
+    metadata: AgentManifestMetadata
+    constraints: AgentManifestConstraints
+    permissions: AgentManifestPermissions
+
+
+class FuelVoucher(BaseModel):
+    tet_id: str
+    fuel_limit: int
+    nonce: int
+    signature: List[int]
+
+
+class EgressPolicy(BaseModel):
+    allowed_domains: List[str]
+    max_daily_bytes: int
+    require_https: bool = True
+
+
+class TetExecutionRequest(BaseModel):
+    payload: Optional[List[int]] = None
+    alias: Optional[str] = None
+    env: Optional[Dict[str, str]] = None
+    injected_files: Optional[Dict[str, str]] = None
+    allocated_fuel: Optional[int] = None
+    max_memory_mb: Optional[int] = None
+    parent_snapshot_id: Optional[str] = None
+    target_function: Optional[str] = None
+    call_depth: int = 0
+    voucher: Optional[FuelVoucher] = None
+    manifest: Optional[AgentManifest] = None
+    egress_policy: Optional[EgressPolicy] = None
+
+
+class StructuredTelemetry(BaseModel):
+    stdout_lines: List[str] = Field(default_factory=list)
+    stderr_lines: List[str] = Field(default_factory=list)
+    memory_used_kb: int = 0
+
+
+class CrashReport(BaseModel):
+    error_type: str
+    message: str
+    instruction_offset: Optional[int] = None
+
+
+ExecutionStatus = Union[
+    str, Dict[str, Any]
+]  # "Success" | "OutOfFuel" | ... | {"Crash": {...}}
+
+
+class TetExecutionResult(BaseModel):
+    tet_id: str
+    status: Any  # ExecutionStatus
+    telemetry: StructuredTelemetry
+    execution_duration_us: int
+    fuel_consumed: int
+    mutated_files: Dict[str, str] = Field(default_factory=dict)
+    migrated_to: Optional[str] = None
+
+
+class SnapshotResponse(BaseModel):
+    snapshot_id: str
+    size_bytes: int
+
+
+class TopologyEdge(BaseModel):
+    source: str
+    target: str
+    latency_us: int
+    bytes_transferred: int
+
+
+class NorthstarReport(BaseModel):
+    teleport_warp_us: int
+    mitosis_constant_us: int
+    oracle_fidelity_us: int
+    market_evacuation_us: int
+    cartridge_spinup_us: int
+    timestamp: str
+
+
+class CartridgeInvocation(BaseModel):
+    component_id: str
+    payload: str
+    fuel: int
+    max_memory_mb: int = 512
+
+
+class CartridgeResult(BaseModel):
+    output: str
+    fuel_consumed: int
+    duration_us: int
+
+
+class McpTool(BaseModel):
+    name: str
+    description: str
+    inputSchema: Dict[str, Any] = Field(default_factory=dict)
+
+
+class McpResource(BaseModel):
+    uri: str
+    name: str
+    description: Optional[str] = None
+    mimeType: Optional[str] = None
+
+
+class McpPromptArgument(BaseModel):
+    name: str
+    description: Optional[str] = None
+    required: Optional[bool] = None
+
+
+class McpPrompt(BaseModel):
+    name: str
+    description: Optional[str] = None
+    arguments: Optional[List[McpPromptArgument]] = None
+
+
+class TelemetryEvent(BaseModel):
+    event_type: str
+    tet_id: str
+    timestamp_us: int
+    data: Dict[str, Any] = Field(default_factory=dict)

trytet_client/telemetry.py

@@ -0,0 +1,62 @@
+"""WebSocket telemetry stream for real-time Trytet observability."""
+
+import asyncio
+import json
+from typing import Any, Callable, Dict, Set
+
+import websockets
+from websockets.asyncio.client import ClientConnection
+
+from .models import TelemetryEvent
+
+TelemetryCallback = Callable[[TelemetryEvent], None]
+
+
+class TelemetryStream:
+    """Async WebSocket client for the Trytet telemetry stream."""
+
+    def __init__(self, ws_url: str):
+        self._url = ws_url
+        self._ws: ClientConnection | None = None
+        self._listeners: Set[TelemetryCallback] = set()
+        self._closed = False
+        self._reconnect_delay = 1.0
+
+    async def connect(self) -> None:
+        """Connect and begin receiving telemetry events."""
+        while not self._closed:
+            try:
+                async with websockets.connect(self._url) as ws:
+                    self._ws = ws
+                    self._reconnect_delay = 1.0
+                    await self._read_loop(ws)
+            except Exception:
+                if not self._closed:
+                    await asyncio.sleep(self._reconnect_delay)
+                    self._reconnect_delay = min(self._reconnect_delay * 2, 30.0)
+
+    async def _read_loop(self, ws: ClientConnection) -> None:
+        async for message in ws:
+            try:
+                data = json.loads(message)
+                event = TelemetryEvent(**data)
+                await self._emit(event)
+            except Exception:
+                pass
+
+    async def _emit(self, event: TelemetryEvent) -> None:
+        for listener in list(self._listeners):
+            try:
+                listener(event)
+            except Exception:
+                pass
+
+    def on_event(self, callback: TelemetryCallback) -> Callable[[], None]:
+        """Register a callback. Returns an unregister function."""
+        self._listeners.add(callback)
+        return lambda: self._listeners.discard(callback)
+
+    def close(self) -> None:
+        """Close the stream and stop reconnecting."""
+        self._closed = True
+        self._listeners.clear()

trytet_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: trytet-client
+Version: 0.2.0
+Summary: Official Python SDK for the Trytet Engine — sub-millisecond Wasm sandbox for AI agents
+Author: Trytet
+License: MIT
+Keywords: agent,llm,sandbox,trytet,wasm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Trytet Python SDK
+
+Official Python client for the [Trytet Engine](https://trytet.io) — a sub-millisecond, hyper-ephemeral Wasm execution substrate for AI agents.
+
+## Installation
+
+```bash
+pip install trytet-client
+```
+
+## Quick Start
+
+```python
+import asyncio
+from trytet_client import TrytetClient, TetExecutionRequest
+
+async def main():
+    async with TrytetClient(base_url="http://localhost:3000") as client:
+        # Execute a Wasm payload
+        with open("my_agent.wasm", "rb") as f:
+            payload = list(f.read())
+
+        result = await client.execute(TetExecutionRequest(
+            payload=payload,
+            allocated_fuel=1_000_000,
+            alias="my-agent",
+        ))
+        print(f"Status: {result.status}")
+        print(f"Fuel consumed: {result.fuel_consumed}")
+
+        # List available MCP tools
+        tools = await client.list_tools()
+        for tool in tools:
+            print(f"  {tool.name}: {tool.description}")
+
+        # Invoke a cartridge
+        from trytet_client import CartridgeInvocation
+        cart_result = await client.invoke_cartridge(CartridgeInvocation(
+            component_id="js-evaluator",
+            payload="2 + 2",
+            fuel=1_000_000,
+        ))
+        print(cart_result.output)
+
+asyncio.run(main())
+```
+
+## Features
+
+- Full async HTTP client with retry and backoff
+- MCP (Model Context Protocol) support — tools, resources, prompts
+- Cartridge management API
+- WebSocket telemetry streaming
+- Pydantic models for all API types
+- Type-safe request/response handling

trytet_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+trytet_client/__init__.py,sha256=42WjFrZB3puFosTfxD3MznsIu1M8ARqG2OyCz8SI3EU,947
+trytet_client/client.py,sha256=6tjuGTRqpvDslm9Q3xMKGwaUQXDuuRltE3QFHC95Bdc,5907
+trytet_client/models.py,sha256=4j05SQlcKn3VP8kY4Lx5AZjXnv0X3OtExpx19bJJSZw,3468
+trytet_client/telemetry.py,sha256=2uusXvANG_rYc-DA1PpKK-99SMUq8IgWpv4F8RWAG88,2063
+trytet_client-0.2.0.dist-info/METADATA,sha256=poJDadTLPfZs6DMY3kpcGbHKgd_vf9taizIJJLDwD1E,2405
+trytet_client-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+trytet_client-0.2.0.dist-info/RECORD,,

trytet_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any