nolag-agents 0.1.0__tar.gz

nolag_agents-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: nolag-agents
+Version: 0.1.0
+Summary: Multi-agent coordination SDK for NoLag - handoff, blackboard, inbox, tools, approval, observe patterns
+Requires-Python: >=3.10
+Requires-Dist: nolag>=2.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"

nolag_agents-0.1.0/nolag_agents/__init__.py

@@ -0,0 +1,69 @@
+"""nolag-agents: Multi-agent coordination SDK for NoLag."""
+
+from .client import NoLagAgents
+from .agent_room import AgentRoom
+from .event_emitter import EventEmitter
+from .correlation import CorrelationManager
+from .patterns.handoff import Handoff
+from .patterns.blackboard import Blackboard
+from .patterns.inbox import Inbox
+from .patterns.tools import Tools
+from .patterns.approve import Approve
+from .patterns.observe import Observe
+from .envelope import (
+    create_task_envelope,
+    create_result_envelope,
+    create_state_envelope,
+    create_event_envelope,
+    create_approval_request,
+    create_approval_response,
+    create_tool_request,
+    create_tool_response,
+)
+from .types import (
+    NoLagAgentsOptions,
+    AgentPresenceData,
+    TaskEnvelope,
+    ResultEnvelope,
+    StateEnvelope,
+    EventEnvelope,
+    ApprovalRequestEnvelope,
+    ApprovalResponseEnvelope,
+    ToolRequestEnvelope,
+    ToolResponseEnvelope,
+    ConnectedAgent,
+    InboxMessage,
+)
+
+__all__ = [
+    "NoLagAgents",
+    "AgentRoom",
+    "EventEmitter",
+    "CorrelationManager",
+    "Handoff",
+    "Blackboard",
+    "Inbox",
+    "Tools",
+    "Approve",
+    "Observe",
+    "create_task_envelope",
+    "create_result_envelope",
+    "create_state_envelope",
+    "create_event_envelope",
+    "create_approval_request",
+    "create_approval_response",
+    "create_tool_request",
+    "create_tool_response",
+    "NoLagAgentsOptions",
+    "AgentPresenceData",
+    "TaskEnvelope",
+    "ResultEnvelope",
+    "StateEnvelope",
+    "EventEnvelope",
+    "ApprovalRequestEnvelope",
+    "ApprovalResponseEnvelope",
+    "ToolRequestEnvelope",
+    "ToolResponseEnvelope",
+    "ConnectedAgent",
+    "InboxMessage",
+]

nolag_agents-0.1.0/nolag_agents/agent_room.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable
+
+from .event_emitter import EventEmitter
+from .types import AgentPresenceData, ConnectedAgent
+from .constants import (
+    TOPIC_TASKS,
+    TOPIC_RESULTS,
+    TOPIC_STATE,
+    TOPIC_EVENTS,
+    TOPIC_INBOX,
+    TOPIC_TOOLS,
+    TOPIC_APPROVAL,
+)
+
+
+class AgentRoom(EventEmitter):
+    """Wraps a nolag Room for agent coordination topics.
+
+    Provides typed pub/sub, presence-based service discovery,
+    and capability routing.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        room_context: Any,
+        client: Any,
+        log: Callable[..., None],
+        agent_id: str,
+        presence: AgentPresenceData | None = None,
+        load_balance: bool = False,
+        load_balance_group: str | None = None,
+        load_balance_topics: list[str] | None = None,
+    ) -> None:
+        super().__init__()
+        self.name = name
+        self.agent_id = agent_id
+        self._room_context = room_context
+        self._client = client
+        self._log = log
+        self._presence = presence
+        self._agents: dict[str, ConnectedAgent] = {}
+        self._load_balance = load_balance
+        self._load_balance_group = load_balance_group
+        self._load_balance_topics = set(load_balance_topics or [TOPIC_TASKS, TOPIC_TOOLS])
+
+        self._wire_topic_listeners()
+        self._wire_presence_listeners()
+
+    async def initialize(self) -> None:
+        """Async initialization — subscribe to topics and set presence."""
+        from nolag import SubscribeOptions
+
+        all_topics = [
+            TOPIC_TASKS, TOPIC_RESULTS, TOPIC_STATE,
+            TOPIC_EVENTS, TOPIC_INBOX, TOPIC_TOOLS, TOPIC_APPROVAL,
+        ]
+        for topic in all_topics:
+            if self._load_balance and topic in self._load_balance_topics:
+                opts = SubscribeOptions(
+                    load_balance=True,
+                    load_balance_group=self._load_balance_group or self.agent_id,
+                )
+                self._log(f"subscribing to {topic} with load balance (group={opts.load_balance_group})")
+                await self._room_context.subscribe(topic, opts)
+            else:
+                await self._room_context.subscribe(topic)
+
+        if self._presence:
+            self._log(f"setting presence in room {self.name}:", self._presence)
+            await self._room_context.set_presence(self._presence.to_dict())
+
+        await self._fetch_initial_presence()
+
+    # ── Service Discovery ──
+
+    def get_connected_agents(self) -> list[ConnectedAgent]:
+        return list(self._agents.values())
+
+    def find_agents(self, capability: str) -> list[ConnectedAgent]:
+        return [a for a in self._agents.values() if capability in a.capabilities]
+
+    def has_capability(self, capability: str) -> bool:
+        return len(self.find_agents(capability)) > 0
+
+    def get_available_capabilities(self) -> list[str]:
+        caps: set[str] = set()
+        for agent in self._agents.values():
+            caps.update(agent.capabilities)
+        return list(caps)
+
+    # ── Presence ──
+
+    async def set_presence(self, data: AgentPresenceData) -> None:
+        self._presence = data
+        self._log(f"updating presence in room {self.name}")
+        await self._room_context.set_presence(data.to_dict())
+
+    async def fetch_presence(self) -> list[ConnectedAgent]:
+        try:
+            actors = await self._room_context.fetch_presence()
+            return [self._to_connected_agent(a) for a in (actors or [])]
+        except Exception:
+            return []
+
+    def emit_presence(
+        self,
+        event: str,
+        actor_id: str,
+        data: AgentPresenceData | None = None,
+    ) -> None:
+        if event == "presence_leave":
+            self._emit("presence_leave", actor_id)
+        else:
+            self._emit(event, actor_id, data or AgentPresenceData(name="", role="agent"))
+
+    # ── Publish ──
+
+    @property
+    def context(self) -> Any:
+        return self._room_context
+
+    async def publish_task(self, envelope: Any) -> None:
+        d = envelope.to_dict() if hasattr(envelope, "to_dict") else envelope
+        if not d.get("createdBy"):
+            d["createdBy"] = self.agent_id
+        await self._publish(TOPIC_TASKS, d)
+
+    async def publish_result(self, envelope: Any) -> None:
+        d = envelope.to_dict() if hasattr(envelope, "to_dict") else envelope
+        if not d.get("completedBy"):
+            d["completedBy"] = self.agent_id
+        await self._publish(TOPIC_RESULTS, d)
+
+    async def publish_state(self, data: dict[str, Any]) -> None:
+        if not data.get("updatedBy"):
+            data["updatedBy"] = self.agent_id
+        await self._publish(TOPIC_STATE, data, retain=True)
+
+    async def publish_event(self, data: dict[str, Any]) -> None:
+        if not data.get("emittedBy"):
+            data["emittedBy"] = self.agent_id
+        await self._publish(TOPIC_EVENTS, data)
+
+    async def publish_inbox(self, data: dict[str, Any]) -> None:
+        await self._publish(TOPIC_INBOX, data)
+
+    async def publish_tools(self, data: dict[str, Any]) -> None:
+        await self._publish(TOPIC_TOOLS, data)
+
+    async def publish_approval(self, data: dict[str, Any]) -> None:
+        await self._publish(TOPIC_APPROVAL, data, retain=True)
+
+    # ── Internals ──
+
+    async def _publish(self, topic: str, data: Any, retain: bool = False) -> None:
+        self._log(f"publish to {topic} in room {self.name}")
+        from .types import _to_camel_dict
+        from nolag import EmitOptions
+        if retain:
+            await self._room_context.emit(topic, data, EmitOptions(retain=True))
+        else:
+            await self._room_context.emit(topic, data)
+
+    def _to_connected_agent(self, actor: Any) -> ConnectedAgent:
+        if isinstance(actor, dict):
+            presence = actor.get("presence") or actor.get("data") or {}
+            return ConnectedAgent(
+                actor_id=actor.get("actor_token_id") or actor.get("actor_id") or "",
+                name=presence.get("name") or actor.get("actor_token_id") or "",
+                role=presence.get("role", "agent"),
+                capabilities=presence.get("capabilities", []),
+                metadata=presence.get("metadata"),
+                connected_at=actor.get("joined_at") or 0,
+            )
+        # ActorPresence object from SDK
+        if hasattr(actor, "actor_token_id"):
+            p = getattr(actor, "presence", {}) or {}
+            return ConnectedAgent(
+                actor_id=actor.actor_token_id,
+                name=p.get("name", actor.actor_token_id),
+                role=p.get("role", "agent"),
+                capabilities=p.get("capabilities", []),
+                metadata=p.get("metadata"),
+                connected_at=getattr(actor, "joined_at", 0) or 0,
+            )
+        return ConnectedAgent()
+
+    async def _fetch_initial_presence(self) -> None:
+        try:
+            actors = await self._room_context.fetch_presence()
+            if isinstance(actors, list):
+                for actor in actors:
+                    connected = self._to_connected_agent(actor)
+                    if connected.actor_id:
+                        self._agents[connected.actor_id] = connected
+                self._log(f"discovered {len(self._agents)} agents in room {self.name}")
+        except Exception:
+            pass
+
+    def _wire_presence_listeners(self) -> None:
+        if not self._client:
+            return
+
+        def _on_join(actor: Any) -> None:
+            # SDK sends ActorPresence objects for presence:join
+            actor_id = getattr(actor, "actor_token_id", None)
+            if not actor_id:
+                return
+            p = getattr(actor, "presence", {}) or {}
+            agent = ConnectedAgent(
+                actor_id=actor_id,
+                name=p.get("name", actor_id),
+                role=p.get("role", "agent"),
+                capabilities=p.get("capabilities", []),
+                metadata=p.get("metadata"),
+                connected_at=0,
+            )
+            self._agents[actor_id] = agent
+            self._log(f"agent joined room {self.name}:", agent.name)
+            pdata = AgentPresenceData(
+                name=agent.name,
+                role=agent.role,
+                capabilities=agent.capabilities,
+                metadata=agent.metadata,
+            )
+            self._emit("presence_join", actor_id, pdata)
+
+        def _on_leave(actor: Any) -> None:
+            actor_id = getattr(actor, "actor_token_id", None)
+            if not actor_id:
+                return
+            self._agents.pop(actor_id, None)
+            self._log(f"agent left room {self.name}:", actor_id)
+            self._emit("presence_leave", actor_id)
+
+        def _on_update(actor: Any) -> None:
+            actor_id = getattr(actor, "actor_token_id", None)
+            if not actor_id:
+                return
+            p = getattr(actor, "presence", {}) or {}
+            existing = self._agents.get(actor_id)
+            agent = ConnectedAgent(
+                actor_id=actor_id,
+                name=p.get("name") or (existing.name if existing else actor_id),
+                role=p.get("role") or (existing.role if existing else "agent"),
+                capabilities=p.get("capabilities") or (existing.capabilities if existing else []),
+                metadata=p.get("metadata") or (existing.metadata if existing else None),
+                connected_at=existing.connected_at if existing else 0,
+            )
+            self._agents[actor_id] = agent
+            pdata = AgentPresenceData(
+                name=agent.name,
+                role=agent.role,
+                capabilities=agent.capabilities,
+                metadata=agent.metadata,
+            )
+            self._emit("presence_update", actor_id, pdata)
+
+        self._client.on("presence:join", _on_join)
+        self._client.on("presence:leave", _on_leave)
+        self._client.on("presence:update", _on_update)
+
+    def _wire_topic_listeners(self) -> None:
+        # Topic subscriptions are done in initialize() (async)
+        # Here we just wire the message handlers (sync .on() calls)
+        simple_map = [
+            (TOPIC_TASKS, "task"),
+            (TOPIC_RESULTS, "result"),
+            (TOPIC_STATE, "state_change"),
+            (TOPIC_EVENTS, "event"),
+            (TOPIC_INBOX, "inbox"),
+        ]
+        for topic, event_name in simple_map:
+            self._room_context.on(topic, self._make_handler(topic, event_name))
+
+        def _on_approval(data: Any, *_args: Any) -> None:
+            self._log(f"received {TOPIC_APPROVAL} in room {self.name}")
+            d = data if isinstance(data, dict) else {}
+            if d.get("type") == "approval_response":
+                self._emit("approval_response", data)
+            else:
+                self._emit("approval_request", data)
+
+        def _on_tools(data: Any, *_args: Any) -> None:
+            self._log(f"received {TOPIC_TOOLS} in room {self.name}")
+            d = data if isinstance(data, dict) else {}
+            if d.get("type") == "tool_response":
+                self._emit("tool_response", data)
+            else:
+                self._emit("tool_request", data)
+
+        self._room_context.on(TOPIC_APPROVAL, _on_approval)
+        self._room_context.on(TOPIC_TOOLS, _on_tools)
+
+    def _make_handler(self, topic: str, event_name: str) -> Callable[..., None]:
+        def handler(data: Any, *_args: Any) -> None:
+            self._log(f"received {topic} in room {self.name}")
+            self._emit(event_name, data)
+        return handler

nolag_agents-0.1.0/nolag_agents/client.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from nolag import NoLag as NoLagClient
+
+from .event_emitter import EventEmitter
+from .agent_room import AgentRoom
+from .utils import generate_id, create_logger
+from .constants import DEFAULT_APP_NAME, DEFAULT_ROOM
+from .types import NoLagAgentsOptions, AgentPresenceData
+
+
+class NoLagAgents(EventEmitter):
+    """High-level agent coordination SDK built on the nolag Python SDK.
+
+    Provides typed rooms for multi-agent patterns: Handoff, Blackboard,
+    Inbox, Tools, Approval, and Observe.
+    """
+
+    def __init__(self, token: str, options: NoLagAgentsOptions | None = None) -> None:
+        super().__init__()
+        opts = options or NoLagAgentsOptions()
+        self._token = token
+        self._app_name = opts.app_name or DEFAULT_APP_NAME
+        self._agent_id = opts.agent_id or generate_id()
+        self._debug = opts.debug
+        self._room_names = opts.rooms or [DEFAULT_ROOM]
+        self._lobby = opts.lobby
+        self._presence = opts.presence
+        self._client_options = opts.client_options or {}
+        self._load_balance = opts.load_balance
+        self._load_balance_group = opts.load_balance_group
+        self._load_balance_topics = opts.load_balance_topics
+
+        self._client: Any = None
+        self._app_context: Any = None
+        self._rooms: dict[str, AgentRoom] = {}
+        self._connected = False
+        self._log = create_logger("NoLagAgents", self._debug)
+
+    @property
+    def agent_id(self) -> str:
+        return self._agent_id
+
+    @property
+    def connected(self) -> bool:
+        return self._connected
+
+    @property
+    def rooms(self) -> dict[str, AgentRoom]:
+        return dict(self._rooms)
+
+    async def connect(self) -> None:
+        self._log("connecting...")
+
+        self._client = NoLagClient(self._token, **self._client_options)
+
+        self._app_context = self._client.set_app(self._app_name)
+
+        self._client.on("connect", self._on_connected)
+        self._client.on("disconnect", self._on_disconnected)
+        self._client.on("reconnect", self._on_reconnected)
+        self._client.on("error", self._on_error)
+
+        await self._client.connect()
+
+        for room_name in self._room_names:
+            await self.room(room_name)
+
+        if self._lobby:
+            await self.subscribe_lobby(self._lobby)
+
+    async def subscribe_lobby(self, lobby_slug: str) -> dict[str, Any]:
+        if not self._app_context:
+            raise RuntimeError("Not connected. Call connect() before subscribing to lobbies.")
+
+        self._log(f"subscribing to lobby: {lobby_slug}")
+        lobby = self._app_context.set_lobby(lobby_slug)
+
+        def _on_lobby_join(evt: Any) -> None:
+            d = evt if isinstance(evt, dict) else {}
+            actor_id = d.get("actor_id")
+            data = d.get("data", {})
+            if actor_id:
+                self._log(f"lobby presence:join - {data.get('name', actor_id)}")
+                for rm in self._rooms.values():
+                    if actor_id not in rm._agents:
+                        from .types import ConnectedAgent
+                        rm._agents[actor_id] = ConnectedAgent(
+                            actor_id=actor_id,
+                            name=data.get("name", actor_id),
+                            role=data.get("role", "agent"),
+                            capabilities=data.get("capabilities", []),
+                            metadata=data.get("metadata"),
+                            connected_at=int(time.time() * 1000),
+                        )
+                    pdata = AgentPresenceData(
+                        name=data.get("name", actor_id),
+                        role=data.get("role", "agent"),
+                        capabilities=data.get("capabilities", []),
+                        metadata=data.get("metadata"),
+                    )
+                    rm.emit_presence("presence_join", actor_id, pdata)
+
+        def _on_lobby_leave(evt: Any) -> None:
+            d = evt if isinstance(evt, dict) else {}
+            actor_id = d.get("actor_id")
+            if actor_id:
+                self._log(f"lobby presence:leave - {actor_id}")
+                for rm in self._rooms.values():
+                    rm._agents.pop(actor_id, None)
+                    rm.emit_presence("presence_leave", actor_id)
+
+        def _on_lobby_update(evt: Any) -> None:
+            d = evt if isinstance(evt, dict) else {}
+            actor_id = d.get("actor_id")
+            data = d.get("data", {})
+            if actor_id:
+                for rm in self._rooms.values():
+                    existing = rm._agents.get(actor_id)
+                    if existing:
+                        if data.get("name"):
+                            existing.name = data["name"]
+                        if data.get("role"):
+                            existing.role = data["role"]
+                        if data.get("capabilities"):
+                            existing.capabilities = data["capabilities"]
+                        if data.get("metadata"):
+                            existing.metadata = data["metadata"]
+                    pdata = AgentPresenceData(
+                        name=data.get("name", ""),
+                        role=data.get("role", "agent"),
+                        capabilities=data.get("capabilities", []),
+                        metadata=data.get("metadata"),
+                    )
+                    rm.emit_presence("presence_update", actor_id, pdata)
+
+        self._client.on("lobbyPresence:join", _on_lobby_join)
+        self._client.on("lobbyPresence:leave", _on_lobby_leave)
+        self._client.on("lobbyPresence:update", _on_lobby_update)
+
+        try:
+            initial_state = await lobby.subscribe()
+            self._log(f"lobby subscribed, initial state: {list((initial_state or {}).keys())}")
+            return initial_state or {}
+        except Exception as err:
+            self._log(f"lobby subscription failed: {err}")
+            return {}
+
+    def disconnect(self) -> None:
+        self._log("disconnecting...")
+        if self._client:
+            self._client.disconnect()
+        self._rooms.clear()
+        self._client = None
+        self._app_context = None
+        self._connected = False
+
+    async def room(self, name: str) -> AgentRoom:
+        agent_room = self._rooms.get(name)
+        if agent_room:
+            return agent_room
+
+        if not self._app_context:
+            raise RuntimeError("Not connected. Call connect() before accessing rooms.")
+
+        self._log(f"joining room: {name}")
+        room_context = self._app_context.set_room(name)
+        agent_room = AgentRoom(
+            name=name,
+            room_context=room_context,
+            client=self._client,
+            log=self._log,
+            agent_id=self._agent_id,
+            presence=self._presence,
+            load_balance=self._load_balance,
+            load_balance_group=self._load_balance_group,
+            load_balance_topics=self._load_balance_topics,
+        )
+        await agent_room.initialize()
+        self._rooms[name] = agent_room
+        return agent_room
+
+    # ── Internal event handlers ──
+
+    def _on_connected(self, *_args: Any) -> None:
+        self._connected = True
+        self._log("connected")
+        self._emit("connected")
+
+    def _on_disconnected(self, *args: Any) -> None:
+        self._connected = False
+        reason = args[0] if args else "unknown"
+        self._log("disconnected:", reason)
+        self._emit("disconnected", reason)
+
+    def _on_reconnected(self, *_args: Any) -> None:
+        self._connected = True
+        self._log("reconnected")
+        self._emit("reconnected")
+
+    def _on_error(self, *args: Any) -> None:
+        err = args[0] if args else Exception("unknown error")
+        self._log("error:", err)
+        self._emit("error", err)

nolag_agents-0.1.0/nolag_agents/constants.py

@@ -0,0 +1,12 @@
+DEFAULT_APP_NAME = "agents"
+
+TOPIC_TASKS = "tasks"
+TOPIC_RESULTS = "results"
+TOPIC_STATE = "state"
+TOPIC_EVENTS = "events"
+TOPIC_INBOX = "inbox"
+TOPIC_TOOLS = "tools"
+TOPIC_APPROVAL = "approval"
+
+DEFAULT_ROOM = "default-workflow"
+LOBBY_AGENT_ACTIVITY = "agent-activity"

nolag_agents-0.1.0/nolag_agents/correlation.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class CorrelationManager(Generic[T]):
+    """Maps correlation IDs to pending asyncio.Future with optional timeout."""
+
+    def __init__(self) -> None:
+        self._pending: dict[str, _Entry] = {}
+
+    def register(self, correlation_id: str, timeout_ms: int | None = None) -> asyncio.Future[T]:
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[T] = loop.create_future()
+        handle: asyncio.TimerHandle | None = None
+
+        if timeout_ms and timeout_ms > 0:
+            def _on_timeout():
+                self._pending.pop(correlation_id, None)
+                if not future.done():
+                    future.set_exception(
+                        TimeoutError(
+                            f"Correlation {correlation_id} timed out after {timeout_ms}ms"
+                        )
+                    )
+            handle = loop.call_later(timeout_ms / 1000.0, _on_timeout)
+
+        self._pending[correlation_id] = _Entry(future=future, handle=handle)
+        return future
+
+    def resolve(self, correlation_id: str, value: T) -> bool:
+        entry = self._pending.pop(correlation_id, None)
+        if entry is None:
+            return False
+        if entry.handle:
+            entry.handle.cancel()
+        if not entry.future.done():
+            entry.future.set_result(value)
+        return True
+
+    def reject(self, correlation_id: str, error: Exception) -> bool:
+        entry = self._pending.pop(correlation_id, None)
+        if entry is None:
+            return False
+        if entry.handle:
+            entry.handle.cancel()
+        if not entry.future.done():
+            entry.future.set_exception(error)
+        return True
+
+    def has(self, correlation_id: str) -> bool:
+        return correlation_id in self._pending
+
+    def clear(self) -> None:
+        for cid, entry in list(self._pending.items()):
+            if entry.handle:
+                entry.handle.cancel()
+            if not entry.future.done():
+                entry.future.set_exception(Exception(f"Correlation {cid} cancelled"))
+        self._pending.clear()
+
+    @property
+    def size(self) -> int:
+        return len(self._pending)
+
+
+class _Entry:
+    __slots__ = ("future", "handle")
+
+    def __init__(self, future: asyncio.Future, handle: asyncio.TimerHandle | None) -> None:
+        self.future = future
+        self.handle = handle