ringforge 0.1.0__py3-none-any.whl

ringforge/__init__.py

@@ -0,0 +1,47 @@
+"""Ringforge SDK — Python client for the Ringforge agent mesh platform."""
+
+from ringforge.client import RingforgeClient
+from ringforge.types import (
+    RingforgeConfig,
+    AgentConfig,
+    AgentState,
+    PresenceAgent,
+    ActivityKind,
+    ActivityEvent,
+    BroadcastActivityParams,
+    MemoryEntry,
+    SetMemoryParams,
+    QueryMemoryParams,
+    DirectMessage,
+    SendMessageParams,
+    Group,
+    CreateGroupParams,
+    TaskSubmitParams,
+    TaskResult,
+    TaskStatus,
+    TaskEvent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RingforgeClient",
+    "RingforgeConfig",
+    "AgentConfig",
+    "AgentState",
+    "PresenceAgent",
+    "ActivityKind",
+    "ActivityEvent",
+    "BroadcastActivityParams",
+    "MemoryEntry",
+    "SetMemoryParams",
+    "QueryMemoryParams",
+    "DirectMessage",
+    "SendMessageParams",
+    "Group",
+    "CreateGroupParams",
+    "TaskSubmitParams",
+    "TaskResult",
+    "TaskStatus",
+    "TaskEvent",
+]

ringforge/activity.py

@@ -0,0 +1,61 @@
+"""Activity sub-API for broadcasting and subscribing to fleet events."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING, Any
+
+from ringforge.types import ActivityEvent, BroadcastActivityParams
+
+if TYPE_CHECKING:
+    from ringforge.client import RingforgeClient
+
+
+class ActivityAPI:
+    """Broadcast and subscribe to fleet-wide activity events."""
+
+    def __init__(self, client: RingforgeClient) -> None:
+        self._client = client
+
+    async def broadcast(
+        self,
+        params: BroadcastActivityParams,
+        idempotency_key: str | None = None,
+    ) -> dict[str, str]:
+        """Broadcast an activity event to the fleet."""
+        payload = {k: v for k, v in asdict(params).items() if v is not None and v != []}
+        return await self._client.push(
+            "activity:broadcast",
+            {"payload": payload},
+            idempotency_key=idempotency_key,
+        )
+
+    async def history(
+        self,
+        *,
+        limit: int | None = None,
+        kinds: list[str] | None = None,
+    ) -> list[ActivityEvent]:
+        """Get recent activity history."""
+        opts: dict[str, Any] = {}
+        if limit is not None:
+            opts["limit"] = limit
+        if kinds is not None:
+            opts["kinds"] = kinds
+        resp = await self._client.push("activity:history", {"payload": opts})
+        events_data = resp.get("payload", {}).get("events", [])
+        return [ActivityEvent(**e) for e in events_data]
+
+    async def subscribe(self, tags: list[str]) -> list[str]:
+        """Subscribe to tagged activity events."""
+        resp = await self._client.push(
+            "activity:subscribe", {"payload": {"tags": tags}}
+        )
+        return resp.get("subscribed_tags", [])
+
+    async def unsubscribe(self, tags: list[str]) -> list[str]:
+        """Unsubscribe from tagged activity events."""
+        resp = await self._client.push(
+            "activity:unsubscribe", {"payload": {"tags": tags}}
+        )
+        return resp.get("subscribed_tags", [])

ringforge/client.py

@@ -0,0 +1,405 @@
+"""Ringforge async WebSocket client using the Phoenix Channel v2 wire protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from typing import Any, Callable, Coroutine
+
+import websockets
+import websockets.exceptions
+
+from ringforge.types import RingforgeConfig
+from ringforge.presence import PresenceAPI
+from ringforge.activity import ActivityAPI
+from ringforge.memory import MemoryAPI
+from ringforge.messaging import DirectMessageAPI
+from ringforge.groups import GroupAPI
+from ringforge.tasks import TasksAPI
+
+logger = logging.getLogger("ringforge")
+
+# Type alias for event handlers
+EventHandler = Callable[..., Any] | Callable[..., Coroutine[Any, Any, Any]]
+
+
+class RingforgeClient:
+    """Async client for the Ringforge agent mesh platform.
+
+    Implements the Phoenix Channel v2 JSON wire protocol over WebSocket.
+    Messages are JSON arrays: ``[join_ref, ref, topic, event, payload]``
+
+    Example::
+
+        from ringforge import RingforgeClient, RingforgeConfig, AgentConfig
+
+        config = RingforgeConfig(
+            server="wss://ringforge.example.com/ws/websocket",
+            api_key="rf_live_...",
+            agent=AgentConfig(name="my-agent", capabilities=["search"]),
+        )
+        client = RingforgeClient(config)
+        await client.connect()
+    """
+
+    def __init__(self, config: RingforgeConfig) -> None:
+        self._config = config
+        self._ws: websockets.WebSocketClientProtocol | None = None
+        self._ref: int = 0
+        self._agent_id: str | None = None
+        self._fleet_id: str | None = None
+        self._connected = False
+        self._running = False
+        self._reconnect_attempts = 0
+
+        # Pending replies: ref → Future
+        self._pending: dict[str, asyncio.Future[dict[str, Any]]] = {}
+
+        # Event listeners: event_name → set of handlers
+        self._listeners: dict[str, set[EventHandler]] = {}
+
+        # Idempotency cache: key → (result, expires_at)
+        self._idempotency_cache: dict[str, tuple[Any, float]] = {}
+
+        # Background tasks
+        self._heartbeat_task: asyncio.Task[None] | None = None
+        self._receive_task: asyncio.Task[None] | None = None
+
+        # Sub-APIs
+        self.presence = PresenceAPI(self)
+        self.activity = ActivityAPI(self)
+        self.memory = MemoryAPI(self)
+        self.dm = DirectMessageAPI(self)
+        self.groups = GroupAPI(self)
+        self.tasks = TasksAPI(self)
+
+    # ── Properties ────────────────────────────────────────
+
+    @property
+    def agent_id(self) -> str | None:
+        """Agent ID assigned after connection."""
+        return self._agent_id
+
+    @property
+    def fleet_id(self) -> str | None:
+        """Fleet ID resolved after connection."""
+        return self._fleet_id
+
+    @property
+    def connected(self) -> bool:
+        """Whether the client is connected to the fleet."""
+        return self._connected
+
+    # ── Connection ────────────────────────────────────────
+
+    async def connect(self) -> str:
+        """Connect to the Ringforge fleet.
+
+        Returns the assigned agent ID.
+        """
+        self._running = True
+        await self._do_connect()
+        assert self._agent_id is not None
+        return self._agent_id
+
+    async def _do_connect(self) -> None:
+        """Establish WebSocket connection and join the fleet channel."""
+        url = self._config.server
+        try:
+            self._ws = await websockets.connect(url)
+        except Exception as exc:
+            self._emit_sync("error", exc)
+            raise
+
+        # Start receive loop
+        self._receive_task = asyncio.create_task(self._receive_loop())
+
+        # Join the fleet channel
+        topic = (
+            f"fleet:{self._config.fleet_id}"
+            if self._config.fleet_id
+            else "fleet:lobby"
+        )
+        self._topic = topic
+
+        join_payload = {
+            "api_key": self._config.api_key,
+            "agent": {
+                "name": self._config.agent.name,
+                "framework": self._config.agent.framework,
+                "capabilities": self._config.agent.capabilities,
+            },
+            "payload": {
+                "state": self._config.agent.state,
+                "task": self._config.agent.task,
+                "metadata": self._config.agent.metadata,
+                "name": self._config.agent.name,
+                "framework": self._config.agent.framework,
+                "capabilities": self._config.agent.capabilities,
+            },
+        }
+
+        resp = await self._push_raw(topic, "phx_join", join_payload, join_ref="join")
+        status = resp.get("status", "")
+        response = resp.get("response", {})
+
+        if status != "ok":
+            raise ConnectionError(f"Fleet join failed: {resp}")
+
+        self._agent_id = response.get("agent_id")
+        self._fleet_id = response.get("fleet_id") or self._config.fleet_id
+        self._connected = True
+        self._reconnect_attempts = 0
+
+        # Start heartbeat
+        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+
+        self._emit_sync("connected", self._agent_id)
+
+    async def disconnect(self) -> None:
+        """Disconnect from the fleet."""
+        self._running = False
+        self._connected = False
+
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            self._heartbeat_task = None
+
+        if self._receive_task:
+            self._receive_task.cancel()
+            self._receive_task = None
+
+        if self._ws:
+            try:
+                # Send leave
+                ref = self._next_ref()
+                msg = json.dumps([None, ref, self._topic, "phx_leave", {}])
+                await self._ws.send(msg)
+            except Exception:
+                pass
+            await self._ws.close()
+            self._ws = None
+
+        self._agent_id = None
+        self._fleet_id = None
+        self._emit_sync("disconnected", "client_disconnect")
+
+    # ── Event System ──────────────────────────────────────
+
+    def on(self, event: str, handler: EventHandler) -> "RingforgeClient":
+        """Register an event handler."""
+        if event not in self._listeners:
+            self._listeners[event] = set()
+        self._listeners[event].add(handler)
+        return self
+
+    def off(self, event: str, handler: EventHandler) -> "RingforgeClient":
+        """Remove an event handler."""
+        if event in self._listeners:
+            self._listeners[event].discard(handler)
+        return self
+
+    def _emit_sync(self, event: str, *args: Any) -> None:
+        """Emit an event to all registered handlers."""
+        handlers = self._listeners.get(event, set())
+        for handler in handlers:
+            try:
+                result = handler(*args)
+                # If handler is a coroutine, schedule it
+                if asyncio.iscoroutine(result):
+                    asyncio.ensure_future(result)
+            except Exception as exc:
+                logger.error("Error in %s handler: %s", event, exc)
+
+    # ── Push (public) ─────────────────────────────────────
+
+    async def push(
+        self,
+        event: str,
+        payload: dict[str, Any],
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Push a message to the fleet channel.
+
+        Args:
+            event: Channel event name (e.g. ``"presence:update"``).
+            payload: Event payload dict.
+            idempotency_key: Optional key for deduplication (cached 5 min).
+
+        Returns:
+            Server response payload.
+        """
+        if not self._connected or not self._ws:
+            raise RuntimeError("Not connected")
+
+        # Check idempotency cache
+        if idempotency_key:
+            cached = self._idempotency_cache.get(idempotency_key)
+            if cached and cached[1] > time.monotonic():
+                return cached[0]
+            payload = {**payload, "_idempotency_key": idempotency_key}
+
+        resp = await self._push_raw(self._topic, event, payload)
+        status = resp.get("status", "")
+        response = resp.get("response", resp)
+
+        if status == "error":
+            raise RuntimeError(f"Push '{event}' failed: {json.dumps(response)}")
+
+        # Cache idempotent result
+        if idempotency_key:
+            self._idempotency_cache[idempotency_key] = (
+                response,
+                time.monotonic() + 300,
+            )
+
+        return response
+
+    # ── Wire Protocol ─────────────────────────────────────
+
+    def _next_ref(self) -> str:
+        """Generate the next message reference."""
+        self._ref += 1
+        return str(self._ref)
+
+    async def _push_raw(
+        self,
+        topic: str,
+        event: str,
+        payload: dict[str, Any],
+        join_ref: str | None = None,
+    ) -> dict[str, Any]:
+        """Send a raw Phoenix Channel message and wait for the reply.
+
+        Wire format: ``[join_ref, ref, topic, event, payload]``
+        """
+        if not self._ws:
+            raise RuntimeError("WebSocket not connected")
+
+        ref = self._next_ref()
+        msg = json.dumps([join_ref, ref, topic, event, payload])
+
+        # Create future for reply
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[dict[str, Any]] = loop.create_future()
+        self._pending[ref] = future
+
+        await self._ws.send(msg)
+
+        try:
+            return await asyncio.wait_for(future, timeout=self._config.timeout)
+        except asyncio.TimeoutError:
+            self._pending.pop(ref, None)
+            raise TimeoutError(f"Push '{event}' timed out after {self._config.timeout}s")
+
+    async def _receive_loop(self) -> None:
+        """Background loop reading messages from the WebSocket."""
+        try:
+            async for raw in self._ws:  # type: ignore[union-attr]
+                try:
+                    msg = json.loads(raw)
+                except json.JSONDecodeError:
+                    logger.warning("Received non-JSON message: %s", raw[:200])
+                    continue
+
+                if not isinstance(msg, list) or len(msg) < 5:
+                    logger.warning("Unexpected message format: %s", raw[:200])
+                    continue
+
+                _join_ref, ref, topic, event, payload = msg
+
+                # Handle replies to our pushes
+                if event == "phx_reply" and ref and ref in self._pending:
+                    future = self._pending.pop(ref)
+                    if not future.done():
+                        future.set_result(payload)
+                    continue
+
+                # Handle server-pushed events (broadcasts)
+                if event == "phx_error":
+                    self._emit_sync("error", RuntimeError(f"Channel error: {payload}"))
+                    continue
+
+                if event == "phx_close":
+                    self._connected = False
+                    self._emit_sync("disconnected", "server_close")
+                    break
+
+                # Forward all other events to handlers
+                event_payload = payload.get("payload", payload) if isinstance(payload, dict) else payload
+                self._emit_sync(event, event_payload)
+
+        except websockets.exceptions.ConnectionClosed as exc:
+            self._connected = False
+            self._emit_sync("disconnected", f"connection_closed: {exc}")
+        except asyncio.CancelledError:
+            return
+        except Exception as exc:
+            self._connected = False
+            self._emit_sync("error", exc)
+            self._emit_sync("disconnected", f"error: {exc}")
+
+        # Auto-reconnect
+        if self._running and self._config.auto_reconnect:
+            asyncio.ensure_future(self._reconnect())
+
+    async def _heartbeat_loop(self) -> None:
+        """Send Phoenix heartbeat every 30 seconds."""
+        try:
+            while self._connected and self._ws:
+                await asyncio.sleep(30)
+                if self._ws and self._connected:
+                    ref = self._next_ref()
+                    msg = json.dumps([None, ref, "phoenix", "heartbeat", {}])
+                    try:
+                        await self._ws.send(msg)
+                    except Exception:
+                        break
+        except asyncio.CancelledError:
+            return
+
+    async def _reconnect(self) -> None:
+        """Attempt to reconnect with exponential backoff."""
+        while (
+            self._running
+            and self._reconnect_attempts < self._config.max_reconnect_attempts
+        ):
+            self._reconnect_attempts += 1
+            delay = min(
+                self._config.reconnect_interval * (1.5 ** self._reconnect_attempts),
+                30.0,
+            )
+            self._emit_sync("reconnecting", self._reconnect_attempts)
+            logger.info(
+                "Reconnecting (attempt %d/%d) in %.1fs...",
+                self._reconnect_attempts,
+                self._config.max_reconnect_attempts,
+                delay,
+            )
+            await asyncio.sleep(delay)
+
+            try:
+                await self._do_connect()
+                logger.info("Reconnected successfully")
+                return
+            except Exception as exc:
+                logger.warning("Reconnect attempt %d failed: %s", self._reconnect_attempts, exc)
+
+        if self._running:
+            self._emit_sync(
+                "error",
+                RuntimeError(
+                    f"Failed to reconnect after {self._config.max_reconnect_attempts} attempts"
+                ),
+            )
+
+    # ── Cleanup ───────────────────────────────────────────
+
+    async def __aenter__(self) -> "RingforgeClient":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.disconnect()

ringforge/groups.py

@@ -0,0 +1,61 @@
+"""Groups sub-API for agent collaboration."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING, Any
+
+from ringforge.types import CreateGroupParams, Group
+
+if TYPE_CHECKING:
+    from ringforge.client import RingforgeClient
+
+
+class GroupAPI:
+    """Create and manage agent groups for collaboration."""
+
+    def __init__(self, client: RingforgeClient) -> None:
+        self._client = client
+
+    async def create(self, params: CreateGroupParams) -> Group:
+        """Create a new group."""
+        payload = {k: v for k, v in asdict(params).items() if v is not None and v != []}
+        resp = await self._client.push("group:create", {"payload": payload})
+        return Group(**resp)
+
+    async def join(self, group_id: str) -> None:
+        """Join an existing group."""
+        await self._client.push("group:join", {"payload": {"group_id": group_id}})
+
+    async def leave(self, group_id: str) -> None:
+        """Leave a group."""
+        await self._client.push("group:leave", {"payload": {"group_id": group_id}})
+
+    async def message(self, group_id: str, message: Any) -> None:
+        """Send a message to a group."""
+        await self._client.push(
+            "group:message", {"payload": {"group_id": group_id, "message": message}}
+        )
+
+    async def list(
+        self, *, status: str | None = None, type: str | None = None
+    ) -> list[Group]:
+        """List groups in the fleet."""
+        opts: dict[str, Any] = {}
+        if status is not None:
+            opts["status"] = status
+        if type is not None:
+            opts["type"] = type
+        resp = await self._client.push("group:list", {"payload": opts})
+        return [Group(**g) for g in resp.get("groups", [])]
+
+    async def my_groups(self) -> list[Group]:
+        """Get groups the current agent belongs to."""
+        resp = await self._client.push("group:my_groups", {})
+        return [Group(**g) for g in resp.get("groups", [])]
+
+    async def dissolve(self, group_id: str, result: Any = None) -> None:
+        """Dissolve a group (owner only)."""
+        await self._client.push(
+            "group:dissolve", {"payload": {"group_id": group_id, "result": result}}
+        )

ringforge/memory.py

@@ -0,0 +1,77 @@
+"""Memory sub-API for shared key-value storage."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING, Any
+
+from ringforge.types import MemoryEntry, QueryMemoryParams, SetMemoryParams
+
+if TYPE_CHECKING:
+    from ringforge.client import RingforgeClient
+
+
+class MemoryAPI:
+    """Shared key-value store accessible by all agents in the fleet."""
+
+    def __init__(self, client: RingforgeClient) -> None:
+        self._client = client
+
+    async def set(
+        self,
+        key: str,
+        params: SetMemoryParams,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Set a memory entry."""
+        payload = {k: v for k, v in asdict(params).items() if v is not None and v != []}
+        payload["key"] = key
+        return await self._client.push(
+            "memory:set", {"payload": payload}, idempotency_key=idempotency_key
+        )
+
+    async def get(self, key: str) -> MemoryEntry:
+        """Get a memory entry by key."""
+        resp = await self._client.push("memory:get", {"payload": {"key": key}})
+        return MemoryEntry(**resp.get("payload", {}))
+
+    async def delete(self, key: str) -> None:
+        """Delete a memory entry."""
+        await self._client.push("memory:delete", {"payload": {"key": key}})
+
+    async def list(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        tags: list[str] | None = None,
+        author: str | None = None,
+    ) -> list[MemoryEntry]:
+        """List memory entries."""
+        opts: dict[str, Any] = {}
+        if limit is not None:
+            opts["limit"] = limit
+        if offset is not None:
+            opts["offset"] = offset
+        if tags is not None:
+            opts["tags"] = tags
+        if author is not None:
+            opts["author"] = author
+        resp = await self._client.push("memory:list", {"payload": opts})
+        entries_data = resp.get("payload", {}).get("entries", [])
+        return [MemoryEntry(**e) for e in entries_data]
+
+    async def query(self, params: QueryMemoryParams) -> list[MemoryEntry]:
+        """Search/query memory entries."""
+        payload = {k: v for k, v in asdict(params).items() if v is not None and v != []}
+        resp = await self._client.push("memory:query", {"payload": payload})
+        entries_data = resp.get("payload", {}).get("entries", [])
+        return [MemoryEntry(**e) for e in entries_data]
+
+    async def subscribe(
+        self, pattern: str, events: list[str] | None = None
+    ) -> dict[str, str]:
+        """Subscribe to memory changes by pattern."""
+        return await self._client.push(
+            "memory:subscribe", {"payload": {"pattern": pattern, "events": events}}
+        )

ringforge/messaging.py

@@ -0,0 +1,38 @@
+"""Messaging sub-API for direct messages between agents."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING, Any
+
+from ringforge.types import DirectMessage, SendMessageParams
+
+if TYPE_CHECKING:
+    from ringforge.client import RingforgeClient
+
+
+class DirectMessageAPI:
+    """Send and receive direct messages between agents."""
+
+    def __init__(self, client: RingforgeClient) -> None:
+        self._client = client
+
+    async def send(
+        self,
+        params: SendMessageParams,
+        idempotency_key: str | None = None,
+    ) -> dict[str, str]:
+        """Send a direct message to another agent."""
+        payload = {k: v for k, v in asdict(params).items() if v is not None}
+        resp = await self._client.push(
+            "direct:send", {"payload": payload}, idempotency_key=idempotency_key
+        )
+        return resp.get("payload", resp)
+
+    async def history(self, with_agent: str, limit: int = 50) -> list[DirectMessage]:
+        """Get conversation history with another agent."""
+        resp = await self._client.push(
+            "direct:history", {"payload": {"with": with_agent, "limit": limit}}
+        )
+        messages_data = resp.get("payload", {}).get("messages", [])
+        return [DirectMessage(**m) for m in messages_data]

ringforge/presence.py

@@ -0,0 +1,43 @@
+"""Presence sub-API for tracking agent state across the fleet."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ringforge.types import AgentState, PresenceAgent
+
+if TYPE_CHECKING:
+    from ringforge.client import RingforgeClient
+
+
+class PresenceAPI:
+    """Manage agent presence within the fleet."""
+
+    def __init__(self, client: RingforgeClient) -> None:
+        self._client = client
+
+    async def update(
+        self,
+        *,
+        state: AgentState | None = None,
+        task: str | None = None,
+        load: float | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Update this agent's presence."""
+        params: dict[str, Any] = {}
+        if state is not None:
+            params["state"] = state
+        if task is not None:
+            params["task"] = task
+        if load is not None:
+            params["load"] = load
+        if metadata is not None:
+            params["metadata"] = metadata
+        await self._client.push("presence:update", {"payload": params})
+
+    async def roster(self) -> list[PresenceAgent]:
+        """Request the current fleet roster."""
+        resp = await self._client.push("presence:roster", {})
+        agents_data = resp.get("payload", {}).get("agents", [])
+        return [PresenceAgent(**a) for a in agents_data]

ringforge/tasks.py

@@ -0,0 +1,63 @@
+"""Tasks sub-API for orchestrating work across agents."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING, Any
+
+from ringforge.types import TaskEvent, TaskResult, TaskSubmitParams
+
+if TYPE_CHECKING:
+    from ringforge.client import RingforgeClient
+
+
+class TasksAPI:
+    """Orchestrate work across agents with the task system."""
+
+    def __init__(self, client: RingforgeClient) -> None:
+        self._client = client
+
+    async def submit(
+        self,
+        params: TaskSubmitParams,
+        idempotency_key: str | None = None,
+    ) -> dict[str, str]:
+        """Submit a new task for assignment.
+
+        Returns dict with ``task_id`` and ``status``.
+        """
+        payload = {k: v for k, v in asdict(params).items() if v is not None and v != []}
+        return await self._client.push(
+            "task:submit", {"payload": payload}, idempotency_key=idempotency_key
+        )
+
+    async def status(self, task_id: str) -> TaskEvent:
+        """Get the status of a task."""
+        resp = await self._client.push(
+            "task:status", {"payload": {"task_id": task_id}}
+        )
+        return _parse_task_event(resp.get("payload", resp))
+
+    async def claim(self, task_id: str) -> TaskEvent:
+        """Claim an assigned task (worker agents)."""
+        resp = await self._client.push(
+            "task:claim", {"payload": {"task_id": task_id}}
+        )
+        return _parse_task_event(resp.get("payload", resp))
+
+    async def result(self, task_id: str, result: TaskResult) -> TaskEvent:
+        """Submit a task result (worker agents)."""
+        resp = await self._client.push(
+            "task:result",
+            {"payload": {"task_id": task_id, "result": asdict(result)}},
+        )
+        return _parse_task_event(resp.get("payload", resp))
+
+
+def _parse_task_event(data: dict[str, Any]) -> TaskEvent:
+    """Parse a raw dict into a TaskEvent, handling nested TaskResult."""
+    result_data = data.pop("result", None)
+    task = TaskEvent(**{k: v for k, v in data.items() if k in TaskEvent.__dataclass_fields__})
+    if result_data and isinstance(result_data, dict):
+        task.result = TaskResult(**{k: v for k, v in result_data.items() if k in TaskResult.__dataclass_fields__})
+    return task

ringforge/types.py

@@ -0,0 +1,243 @@
+"""Type definitions for the Ringforge SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Literal
+
+
+# ── Agent State ────────────────────────────────────────────
+
+AgentState = Literal["online", "busy", "away", "offline"]
+
+
+# ── Config ─────────────────────────────────────────────────
+
+
+@dataclass
+class AgentConfig:
+    """Agent identity configuration."""
+
+    name: str
+    framework: str = "ringforge-sdk-py"
+    capabilities: list[str] = field(default_factory=list)
+    state: AgentState = "online"
+    task: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RingforgeConfig:
+    """Client connection configuration."""
+
+    server: str
+    api_key: str
+    agent: AgentConfig
+    fleet_id: str | None = None
+    auto_reconnect: bool = True
+    reconnect_interval: float = 3.0
+    max_reconnect_attempts: int = 10
+    timeout: float = 10.0
+    private_key: str | None = None
+
+
+# ── Presence ───────────────────────────────────────────────
+
+
+@dataclass
+class PresenceAgent:
+    """An agent visible in the fleet roster."""
+
+    agent_id: str
+    name: str | None = None
+    framework: str | None = None
+    capabilities: list[str] = field(default_factory=list)
+    state: AgentState = "online"
+    task: str | None = None
+    load: float = 0.0
+    connected_at: str = ""
+
+
+# ── Activity ───────────────────────────────────────────────
+
+ActivityKind = Literal[
+    "task_started",
+    "task_progress",
+    "task_completed",
+    "task_failed",
+    "discovery",
+    "question",
+    "alert",
+    "custom",
+]
+
+
+@dataclass
+class ActivityEvent:
+    """A fleet activity event."""
+
+    event_id: str
+    from_agent: dict[str, str] = field(default_factory=dict)  # {agent_id, name}
+    kind: str = "custom"
+    description: str = ""
+    tags: list[str] = field(default_factory=list)
+    data: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = ""
+
+
+@dataclass
+class BroadcastActivityParams:
+    """Parameters for broadcasting an activity event."""
+
+    kind: str  # ActivityKind
+    description: str
+    tags: list[str] = field(default_factory=list)
+    data: dict[str, Any] = field(default_factory=dict)
+    scope: Literal["fleet", "tagged", "direct"] = "fleet"
+    to: str | None = None
+
+
+# ── Memory ─────────────────────────────────────────────────
+
+
+@dataclass
+class MemoryEntry:
+    """A shared memory entry."""
+
+    id: str = ""
+    key: str = ""
+    fleet_id: str = ""
+    value: str = ""
+    type: str = "string"
+    tags: list[str] = field(default_factory=list)
+    author: str | None = None
+    created_at: str = ""
+    updated_at: str = ""
+    ttl: str | None = None
+    access_count: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SetMemoryParams:
+    """Parameters for setting a memory entry."""
+
+    value: str
+    tags: list[str] = field(default_factory=list)
+    type: str = "string"
+    ttl: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class QueryMemoryParams:
+    """Parameters for querying memory entries."""
+
+    tags: list[str] = field(default_factory=list)
+    text_search: str | None = None
+    author: str | None = None
+    since: str | None = None
+    limit: int | None = None
+    sort: Literal["relevance", "created_at", "updated_at", "access_count"] | None = None
+
+
+# ── Direct Messages ────────────────────────────────────────
+
+
+@dataclass
+class DirectMessage:
+    """A direct message between agents."""
+
+    message_id: str = ""
+    from_agent: dict[str, str] = field(default_factory=dict)
+    to: str = ""
+    correlation_id: str | None = None
+    message: Any = None
+    timestamp: str = ""
+
+
+@dataclass
+class SendMessageParams:
+    """Parameters for sending a direct message."""
+
+    to: str
+    message: Any
+    correlation_id: str | None = None
+
+
+# ── Groups ─────────────────────────────────────────────────
+
+
+@dataclass
+class Group:
+    """An agent group."""
+
+    group_id: str = ""
+    name: str = ""
+    type: str = "squad"
+    capabilities: list[str] = field(default_factory=list)
+    status: str = ""
+    created_by: str = ""
+    member_count: int = 0
+    settings: dict[str, Any] = field(default_factory=dict)
+    inserted_at: str = ""
+
+
+@dataclass
+class CreateGroupParams:
+    """Parameters for creating a group."""
+
+    name: str
+    type: Literal["squad", "pod", "channel"] = "squad"
+    capabilities: list[str] = field(default_factory=list)
+    settings: dict[str, Any] = field(default_factory=dict)
+    invite: list[str] = field(default_factory=list)
+
+
+# ── Tasks ──────────────────────────────────────────────────
+
+TaskStatus = Literal["pending", "assigned", "claimed", "running", "completed", "failed", "timeout"]
+
+
+@dataclass
+class TaskSubmitParams:
+    """Parameters for submitting a task."""
+
+    name: str
+    description: str
+    capabilities: list[str] = field(default_factory=list)
+    assign_to: str | None = None
+    priority: int = 0
+    timeout: int = 300
+    params: dict[str, Any] = field(default_factory=dict)
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TaskResult:
+    """Result of a completed task."""
+
+    success: bool
+    data: Any = None
+    error: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TaskEvent:
+    """A task lifecycle event."""
+
+    task_id: str = ""
+    name: str = ""
+    status: str = "pending"  # TaskStatus
+    submitted_by: str = ""
+    assigned_to: str | None = None
+    claimed_by: str | None = None
+    priority: int = 0
+    params: dict[str, Any] = field(default_factory=dict)
+    result: TaskResult | None = None
+    tags: list[str] = field(default_factory=list)
+    timeout: int = 300
+    created_at: str = ""
+    updated_at: str = ""

ringforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: ringforge
+Version: 0.1.0
+Summary: Python SDK for the Ringforge agent mesh platform
+License-Expression: MIT
+Keywords: agent,ai,mesh,ringforge,sdk
+Requires-Python: >=3.10
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ringforge
+
+Python SDK for the **Ringforge** agent mesh platform. Connect AI agents into a real-time fleet with presence tracking, shared memory, task orchestration, direct messaging, and group collaboration — all async over WebSocket.
+
+## Install
+
+```bash
+pip install ringforge
+```
+
+## Quick Start
+
+```python
+import asyncio
+from ringforge import RingforgeClient, RingforgeConfig, AgentConfig
+
+async def main():
+    config = RingforgeConfig(
+        server="wss://ringforge.example.com/ws/websocket",
+        api_key="rf_live_...",
+        agent=AgentConfig(name="my-agent", capabilities=["search", "summarize"]),
+    )
+
+    async with RingforgeClient(config) as client:
+        print(f"Connected as {client.agent_id}")
+
+        client.on("direct:message", lambda msg: print(f"Got: {msg}"))
+
+        # Keep running
+        await asyncio.Event().wait()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+from ringforge import RingforgeConfig, AgentConfig
+
+config = RingforgeConfig(
+    server="wss://ringforge.example.com/ws/websocket",
+    api_key="rf_live_...",
+    agent=AgentConfig(
+        name="my-agent",
+        framework="langchain",          # optional
+        capabilities=["search"],         # optional
+        state="online",                  # initial state
+        task="Waiting for work",         # initial task description
+        metadata={"version": "1.0"},     # arbitrary metadata
+    ),
+    fleet_id="fleet_abc123",             # optional — omit to auto-resolve
+    auto_reconnect=True,                 # default: True
+    reconnect_interval=3.0,              # default: 3.0s
+    max_reconnect_attempts=10,           # default: 10
+    timeout=10.0,                        # push timeout, default: 10s
+)
+```
+
+## Sub-APIs
+
+### Presence
+
+Track agent state across the fleet.
+
+```python
+# Update your presence
+await client.presence.update(state="busy", task="Processing request #42")
+
+# Get the full fleet roster
+agents = await client.presence.roster()
+for agent in agents:
+    print(f"{agent.name} [{agent.state}]")
+```
+
+### Activity
+
+Broadcast and subscribe to fleet-wide activity events.
+
+```python
+from ringforge import BroadcastActivityParams
+
+# Broadcast an activity event
+await client.activity.broadcast(BroadcastActivityParams(
+    kind="task_completed",
+    description="Finished data analysis",
+    tags=["analytics"],
+    data={"rows_processed": 50_000},
+))
+
+# Get recent history
+events = await client.activity.history(limit=20)
+
+# Subscribe to tags
+await client.activity.subscribe(["alerts", "deployments"])
+```
+
+### Memory
+
+Shared key-value store accessible by all agents.
+
+```python
+from ringforge import SetMemoryParams, QueryMemoryParams
+
+# Set a value
+await client.memory.set("config:model", SetMemoryParams(
+    value="gpt-4o",
+    tags=["config"],
+    ttl=3600,
+))
+
+# Get a value
+entry = await client.memory.get("config:model")
+print(entry.value)  # "gpt-4o"
+
+# Search memory
+results = await client.memory.query(QueryMemoryParams(
+    tags=["config"],
+    text_search="model",
+    sort="relevance",
+))
+
+# Subscribe to changes
+await client.memory.subscribe("config:*")
+client.on("memory:changed", lambda e: print(f"{e['key']} changed"))
+```
+
+### Direct Messages
+
+Send messages to specific agents.
+
+```python
+from ringforge import SendMessageParams
+
+# Send a message
+await client.dm.send(SendMessageParams(
+    to="agent_abc123",
+    message={"type": "question", "text": "What is the current status?"},
+    correlation_id="req-001",
+))
+
+# Listen for incoming messages
+client.on("direct:message", lambda msg: print(f"From {msg['from']['name']}: {msg['message']}"))
+
+# Get conversation history
+history = await client.dm.history("agent_abc123", limit=25)
+```
+
+### Groups
+
+Create and manage agent groups.
+
+```python
+from ringforge import CreateGroupParams
+
+# Create a group
+group = await client.groups.create(CreateGroupParams(
+    name="research-squad",
+    type="squad",
+    capabilities=["search", "summarize"],
+    invite=["agent_abc123"],
+))
+
+# Send a group message
+await client.groups.message(group.group_id, {"status": "in_progress"})
+
+# Listen for group messages
+client.on("group:message", lambda msg: print(f"[{msg['group_id']}] {msg}"))
+
+# List groups
+groups = await client.groups.list()
+my_groups = await client.groups.my_groups()
+```
+
+### Tasks
+
+Orchestrate work across agents.
+
+```python
+from ringforge import TaskSubmitParams, TaskResult
+
+# ── Submitter: create a task ──
+result = await client.tasks.submit(TaskSubmitParams(
+    name="analyze-dataset",
+    description="Run sentiment analysis on Q4 reviews",
+    capabilities=["nlp", "sentiment"],
+    priority=5,
+    timeout=300,
+    params={"dataset": "s3://bucket/reviews-q4.csv"},
+    tags=["analytics", "nlp"],
+))
+task_id = result["task_id"]
+
+# Check task status
+task = await client.tasks.status(task_id)
+print(f"Task {task.name}: {task.status}")
+
+# Listen for results
+client.on("task:result", lambda e: print(f"Result: {e}"))
+
+# ── Worker: claim and complete tasks ──
+async def handle_task(event):
+    await client.tasks.claim(event["task_id"])
+    # ... do work ...
+    await client.tasks.result(event["task_id"], TaskResult(
+        success=True,
+        data={"sentiment": "positive", "confidence": 0.92},
+        metadata={"duration_ms": 4200},
+    ))
+
+client.on("task:assigned", handle_task)
+```
+
+## Events
+
+Subscribe to real-time events with `client.on(event, handler)`:
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `connected` | `agent_id: str` | Successfully joined the fleet |
+| `disconnected` | `reason: str` | Disconnected from fleet |
+| `reconnecting` | `attempt: int` | Attempting to reconnect |
+| `error` | `exception` | Connection or protocol error |
+| `presence:joined` | `PresenceAgent` | Agent joined the fleet |
+| `presence:left` | `{agent_id}` | Agent left the fleet |
+| `presence:state_changed` | `PresenceAgent` | Agent updated their state |
+| `presence:roster` | `[PresenceAgent]` | Full roster response |
+| `activity:broadcast` | `ActivityEvent` | Activity event received |
+| `direct:message` | `DirectMessage` | Direct message received |
+| `memory:changed` | `{key, action, author, timestamp}` | Memory entry changed |
+| `group:created` | `Group` | Group created |
+| `group:member_joined` | `{group_id, agent_id}` | Agent joined a group |
+| `group:member_left` | `{group_id, agent_id}` | Agent left a group |
+| `group:dissolved` | `{group_id, result, dissolved_by}` | Group dissolved |
+| `group:message` | `{group_id, from, message, timestamp}` | Group message received |
+| `group:invite` | `{group_id, name, type, invited_by}` | Invited to a group |
+| `task:assigned` | `TaskEvent` | Task assigned to you |
+| `task:claimed` | `TaskEvent` | Task was claimed |
+| `task:result` | `TaskEvent` | Task result submitted |
+| `task:timeout` | `TaskEvent` | Task timed out |
+| `system:quota_warning` | `{resource, used, limit}` | Approaching resource limit |
+
+Handlers can be sync functions or async coroutines — both work.
+
+## Idempotency
+
+All mutating operations accept an optional `idempotency_key`. Duplicate pushes with the same key within 5 minutes return the cached result.
+
+```python
+import uuid
+
+key = str(uuid.uuid4())
+await client.activity.broadcast(params, idempotency_key=key)
+# Safe to retry
+await client.activity.broadcast(params, idempotency_key=key)
+```
+
+## Features
+
+- **Async/await** — built on `asyncio` and `websockets`
+- **Auto-reconnect** — exponential backoff, configurable attempts
+- **Type hints everywhere** — dataclasses, not dicts
+- **Phoenix Channel v2** — native wire protocol implementation
+- **Event-driven** — sync and async handlers
+- **Idempotency** — built-in client-side dedup cache
+- **Context manager** — `async with RingforgeClient(config) as client:`
+
+## License
+
+See [LICENSE](../../LICENSE) in the repository root.

ringforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ringforge/__init__.py,sha256=IoktcvqZcEY_oznRqB_yDbd1zmsy9p0s8ZaM-R6VRzA,942
+ringforge/activity.py,sha256=PzQdHevl2fERmH0XOVCxrFAywq7tIj-DoWr8nYEl30Q,2056
+ringforge/client.py,sha256=bv74NDGRCus7kXZf_f-5zQeLXXwDtgHlPnb1KtzuDB4,14289
+ringforge/groups.py,sha256=FSm4zhVOWZYUpJnV_b-JPlZbIzdMSocWYPqTMqU4NCI,2220
+ringforge/memory.py,sha256=VpEf_CVRCRvZb_ETcaSZXpeKVWJTxd7lNDitFpgUjkE,2749
+ringforge/messaging.py,sha256=1u5JaSOwuJd3L2RM_uAopDv3Idv8fb9uToSnOd9hGRA,1314
+ringforge/presence.py,sha256=FJbArqGg0kY5xsD7Ias39kEDxma7MwgEVVqSdjnSqPg,1345
+ringforge/tasks.py,sha256=-GfFFZxnPp6WyOxmx5Kgy0iD0A2Kn5mA1CtMT3EBqJA,2282
+ringforge/types.py,sha256=5ra2urVNLfYb1tmHljfexKOp0DgA-j6bpnq1IHDdRk0,6593
+ringforge-0.1.0.dist-info/METADATA,sha256=5uNkrX6bKucLAg-gIXPFrFvDf8btCl7ZyS6hvD0nvJc,8254
+ringforge-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ringforge-0.1.0.dist-info/RECORD,,

ringforge-0.1.0.dist-info/WHEEL

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