hostel-protocol-python 0.1.0__tar.gz → 0.2.0__tar.gz

{hostel_protocol_python-0.1.0 → hostel_protocol_python-0.2.0}/Makefile

@@ -1,7 +1,7 @@
-.PHONY: install format lint typecheck test
+.PHONY: install format lint typecheck test build
 
 install:
-	uv sync --all-extras
+	uv sync --all-groups
 
 format:
 	uv run black src/ tests/
@@ -12,7 +12,10 @@ lint:
 	uv run black --check src/ tests/
 
 typecheck:
-	uv run mypy src/
+	uv run mypy --package hostel.protocol --package hostel.transport --package hostel.client
 
 test:
 	uv run pytest
+
+build:
+	uv build

hostel_protocol_python-0.2.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: hostel-protocol-python
+Version: 0.2.0
+Summary: Pydantic models, transport and client for the Hostel protocol
+Requires-Python: >=3.12
+Requires-Dist: hostel-protocol>=0.1.0
+Requires-Dist: protobuf>=7.0
+Requires-Dist: pydantic>=2.5.0
+Provides-Extra: client
+Requires-Dist: pyzmq>=26.0; extra == 'client'
+Provides-Extra: transport
+Requires-Dist: pyzmq>=26.0; extra == 'transport'

{hostel_protocol_python-0.1.0 → hostel_protocol_python-0.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostel-protocol-python"
-version = "0.1.0"
-description = "Pydantic convenience layer for the Hostel protocol"
+version = "0.2.0"
+description = "Pydantic models, transport and client for the Hostel protocol"
 requires-python = ">=3.12"
 dependencies = [
     "hostel-protocol>=0.1.0",
@@ -14,10 +14,15 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+transport = ["pyzmq>=26.0"]
+client = ["pyzmq>=26.0"]
+
+[dependency-groups]
 dev = [
     "pytest",
     "pytest-cov",
     "pytest-asyncio",
+    "pyzmq>=26.0",
     "black",
     "ruff",
     "mypy",
@@ -25,7 +30,7 @@ dev = [
 ]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/hostel_protocol"]
+packages = ["src/hostel"]
 
 [tool.black]
 line-length = 120
@@ -45,9 +50,13 @@ plugins = ["pydantic.mypy"]
 module = "hostel.protocol.v1.*"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = "zmq.*"
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "--cov=hostel_protocol --cov-report=term-missing"
+addopts = "--cov=hostel --cov-report=term-missing"
 
 [tool.uv]
 constraint-dependencies = ["protobuf>=7.0"]

hostel_protocol_python-0.2.0/src/hostel/client/__init__.py

@@ -0,0 +1,5 @@
+"""hostel.client — High-level async client for the Hostel protocol."""
+
+from hostel.client.client import HostelClient
+
+__all__ = ["HostelClient"]

hostel_protocol_python-0.2.0/src/hostel/client/client.py

@@ -0,0 +1,302 @@
+"""Async client for the Hostel protocol."""
+
+import asyncio
+import logging
+import uuid
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from hostel.protocol.models import (
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    CreateComponentRequest,
+    CreateTaskRequest,
+    DeleteComponentRequest,
+    DeleteTaskRequest,
+    GetComponentRequest,
+    GetTaskRequest,
+    HostelMessage,
+    ListAgentsRequest,
+    ListComponentsRequest,
+    ListTasksRequest,
+    TaskData,
+    UpdateComponentRequest,
+    UpdateTaskRequest,
+)
+from hostel.transport import DEFAULT_IPC_ENDPOINT
+from hostel.transport.transport import Transport
+from hostel.transport.zeromq import ZmqTransport
+
+logger = logging.getLogger(__name__)
+
+
+class HostelClient:
+
+    def __init__(self, transport: Transport | None = None, endpoint: str | None = None):
+        if transport is not None:
+            self.transport = transport
+        else:
+            self.transport = ZmqTransport(endpoint or DEFAULT_IPC_ENDPOINT)
+        self._pending: dict[str, asyncio.Queue[HostelMessage]] = {}
+
+    async def start(self) -> None:
+        logger.debug("Starting Hostel Client...")
+        await self.transport.connect()
+        logger.debug("IPC connected, sending hello...")
+
+        request_id = uuid.uuid4().hex
+        await self.transport.send(HostelMessage(id=request_id, type="system", action="hello", system_payload={}))
+
+        msg = await self.transport.receive()
+        assert msg.action == "ready"
+
+        logger.debug("Received ready from server, starting receiver...")
+        asyncio.create_task(self._receiver())
+        logger.info("Hostel Client started.")
+
+    async def _receiver(self) -> None:
+        while True:
+            msg = await self.transport.receive()
+            request_id = msg.id
+            if request_id and request_id in self._pending:
+                await self._pending[request_id].put(msg)
+
+    # ── Agent operations ─────────────────────────────────────────────────
+
+    async def list_agents(self) -> list[dict[str, Any]]:
+        request_id = uuid.uuid4().hex
+        queue: asyncio.Queue[HostelMessage] = asyncio.Queue()
+        self._pending[request_id] = queue
+
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="list_agents",
+                agent_list_request=ListAgentsRequest(),
+            )
+        )
+        msg = await queue.get()
+        del self._pending[request_id]
+
+        assert msg.agent_list_response is not None
+        return msg.agent_list_response.agents
+
+    # ── Chat operations ──────────────────────────────────────────────────
+
+    async def chat(self, agent_name: str, messages: list[ChatMessage]) -> AsyncGenerator[ChatResponse, None]:
+        request_id = uuid.uuid4().hex
+        queue: asyncio.Queue[HostelMessage] = asyncio.Queue()
+        self._pending[request_id] = queue
+
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="chat",
+                chat_request=ChatRequest(agent_name=agent_name, messages=messages),
+            )
+        )
+
+        while True:
+            msg = await queue.get()
+            assert msg.chat_response_chunk is not None
+            chunk = msg.chat_response_chunk
+
+            logger.debug(f"Received chat chunk: {chunk}")
+            yield chunk
+
+            if chunk.role == "agent" and chunk.scope in ("complete", "error"):
+                break
+
+        del self._pending[request_id]
+
+    # ── Task operations ──────────────────────────────────────────────────
+
+    async def create_task(
+        self,
+        agent_name: str,
+        prompt: str,
+        start_datetime: str,
+        webhook_url: str | None = None,
+    ) -> str:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="create_task",
+                task_create=CreateTaskRequest(
+                    agent_name=agent_name,
+                    prompt=prompt,
+                    start_datetime=start_datetime,
+                    webhook_url=webhook_url,
+                ),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.task_create_response is not None
+        assert msg.task_create_response.task is not None
+        task_id = msg.task_create_response.task.id
+        logger.debug(f"Created task with ID: {task_id}")
+        return task_id
+
+    async def list_tasks(self) -> list[TaskData]:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="list_tasks",
+                task_list=ListTasksRequest(),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.task_list_response is not None
+        tasks = msg.task_list_response.tasks
+        logger.debug(f"Retrieved {len(tasks)} tasks")
+        return tasks
+
+    async def get_task(self, task_id: str) -> TaskData | None:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="get_task",
+                task_get=GetTaskRequest(task_id=task_id),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.task_get_response is not None
+        return msg.task_get_response.task
+
+    async def update_task(
+        self,
+        task_id: str,
+        agent_name: str | None = None,
+        prompt: str | None = None,
+        start_datetime: str | None = None,
+        webhook_url: str | None = None,
+        status: str | None = None,
+    ) -> bool:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="update_task",
+                task_update=UpdateTaskRequest(
+                    task_id=task_id,
+                    agent_name=agent_name,
+                    prompt=prompt,
+                    start_datetime=start_datetime,
+                    webhook_url=webhook_url,
+                    status=status,
+                ),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.task_update_response is not None
+        success = msg.task_update_response.task is not None
+        logger.debug(f"Task {task_id} update {'succeeded' if success else 'failed'}")
+        return success
+
+    async def delete_task(self, task_id: str) -> bool:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="delete_task",
+                task_delete=DeleteTaskRequest(task_id=task_id),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.task_delete_response is not None
+        success = msg.task_delete_response.success
+        logger.debug(f"Task {task_id} delete {'succeeded' if success else 'failed'}")
+        return success
+
+    # ── Component operations ─────────────────────────────────────────────
+
+    async def create_component(self, component_type: str, data: dict[str, Any]) -> bool:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="create_component",
+                component_create=CreateComponentRequest(component_type=component_type, data=data),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.component_create_response is not None
+        return msg.component_create_response.success
+
+    async def get_component(self, component_type: str, name: str) -> dict[str, Any] | None:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="get_component",
+                component_get=GetComponentRequest(component_type=component_type, name=name),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.component_get_response is not None
+        return msg.component_get_response.data
+
+    async def list_components(self, component_type: str) -> list[dict[str, Any]]:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="list_components",
+                component_list=ListComponentsRequest(component_type=component_type),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.component_list_response is not None
+        return msg.component_list_response.components
+
+    async def update_component(self, component_type: str, name: str, data: dict[str, Any]) -> bool:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="update_component",
+                component_update=UpdateComponentRequest(component_type=component_type, name=name, data=data),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.component_update_response is not None
+        return msg.component_update_response.success
+
+    async def delete_component(self, component_type: str, name: str) -> bool:
+        request_id = uuid.uuid4().hex
+        await self.transport.send(
+            HostelMessage(
+                id=request_id,
+                type="request",
+                action="delete_component",
+                component_delete=DeleteComponentRequest(component_type=component_type, name=name),
+            )
+        )
+
+        msg = await self.transport.receive()
+        assert msg.component_delete_response is not None
+        return msg.component_delete_response.success

{hostel_protocol_python-0.1.0/src/hostel_protocol → hostel_protocol_python-0.2.0/src/hostel/protocol}/__init__.py

@@ -1,7 +1,11 @@
-"""hostel_protocol — Pydantic convenience layer for the Hostel protocol."""
+"""hostel.protocol — Pydantic convenience layer for the Hostel protocol."""
 
-from hostel_protocol.converter import proto_to_pydantic, pydantic_to_proto
-from hostel_protocol.models import (
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
+
+from hostel.protocol.converter import proto_to_pydantic, pydantic_to_proto
+from hostel.protocol.models import (
     AIChatMessage,
     ChatMessage,
     ChatRequest,

{hostel_protocol_python-0.1.0/src/hostel_protocol → hostel_protocol_python-0.2.0/src/hostel/protocol}/converter.py

@@ -16,7 +16,7 @@ from hostel.protocol.v1 import (
 )
 from pydantic import BaseModel
 
-from hostel_protocol import models
+from hostel.protocol import models
 
 # ---------------------------------------------------------------------------
 # Registry: Pydantic model class  <->  Protobuf message class

hostel_protocol_python-0.2.0/src/hostel/transport/__init__.py

@@ -0,0 +1,11 @@
+"""hostel.transport — Transport abstractions and implementations."""
+
+from hostel.transport.transport import ClientId, ServerTransport, Transport
+
+__all__ = [
+    "ClientId",
+    "Transport",
+    "ServerTransport",
+]
+
+DEFAULT_IPC_ENDPOINT = "ipc:///tmp/hostel.ipc"

hostel_protocol_python-0.2.0/src/hostel/transport/transport.py

@@ -0,0 +1,45 @@
+"""Abstract base classes for Hostel transports."""
+
+from abc import ABC, abstractmethod
+
+from hostel.protocol.models import HostelMessage
+
+ClientId = bytes
+
+
+class Transport(ABC):
+
+    @abstractmethod
+    async def connect(self) -> None:
+        pass
+
+    @abstractmethod
+    async def send(self, message: HostelMessage) -> None:
+        pass
+
+    @abstractmethod
+    async def receive(self) -> HostelMessage:
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        pass
+
+
+class ServerTransport(ABC):
+
+    @abstractmethod
+    async def connect(self) -> None:
+        pass
+
+    @abstractmethod
+    async def send(self, client_id: ClientId, message: HostelMessage) -> None:
+        pass
+
+    @abstractmethod
+    async def receive(self) -> tuple[ClientId, HostelMessage]:
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        pass

hostel_protocol_python-0.2.0/src/hostel/transport/zeromq.py

@@ -0,0 +1,119 @@
+"""ZeroMQ transport implementations for Hostel."""
+
+import logging
+import uuid
+
+import zmq
+import zmq.asyncio
+from hostel.protocol.v1 import message_pb2
+
+from hostel.protocol.converter import proto_to_pydantic, pydantic_to_proto
+from hostel.protocol.models import HostelMessage
+from hostel.transport.transport import ClientId, ServerTransport, Transport
+
+logger = logging.getLogger(__name__)
+
+
+class ZmqTransport(Transport):
+    """ZeroMQ DEALER transport for client-side IPC."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        *,
+        identity: str | None = None,
+        linger_ms: int = 0,
+    ):
+        self.endpoint = endpoint
+        self.identity = identity or uuid.uuid4().hex
+        self.linger_ms = linger_ms
+
+        self._ctx: zmq.asyncio.Context | None = None
+        self._socket: zmq.asyncio.Socket | None = None
+
+    async def connect(self) -> None:
+        if self._socket is not None:
+            return
+
+        self._ctx = zmq.asyncio.Context.instance()
+        self._socket = self._ctx.socket(zmq.DEALER)
+        self._socket.setsockopt(zmq.IDENTITY, self.identity.encode())
+        self._socket.setsockopt(zmq.LINGER, self.linger_ms)
+        self._socket.connect(self.endpoint)
+
+    async def send(self, message: HostelMessage) -> None:
+        if self._socket is None:
+            raise RuntimeError("Transport not connected")
+
+        proto = pydantic_to_proto(message)
+        raw = proto.SerializeToString()
+        await self._socket.send_multipart([b"", raw])
+
+    async def receive(self) -> HostelMessage:
+        if self._socket is None:
+            raise RuntimeError("Transport not connected")
+
+        frames = await self._socket.recv_multipart()
+        if len(frames) != 2 or frames[0] != b"":
+            raise ValueError(f"Invalid DEALER frame: {frames}")
+
+        _, raw = frames
+        proto = message_pb2.HostelMessage()
+        proto.ParseFromString(raw)
+        return proto_to_pydantic(proto)  # type: ignore[return-value]
+
+    async def close(self) -> None:
+        if self._socket is not None:
+            self._socket.close()
+            self._socket = None
+
+
+class ZmqRouterTransport(ServerTransport):
+    """ZeroMQ ROUTER transport for the service side."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        *,
+        linger_ms: int = 0,
+    ):
+        self.endpoint = endpoint
+        self.linger_ms = linger_ms
+
+        self._ctx: zmq.asyncio.Context | None = None
+        self._socket: zmq.asyncio.Socket | None = None
+
+    async def connect(self) -> None:
+        if self._socket is not None:
+            return
+
+        self._ctx = zmq.asyncio.Context.instance()
+        self._socket = self._ctx.socket(zmq.ROUTER)
+        self._socket.setsockopt(zmq.LINGER, self.linger_ms)
+        self._socket.bind(self.endpoint)
+
+    async def receive(self) -> tuple[ClientId, HostelMessage]:
+        if self._socket is None:
+            raise RuntimeError("Transport not bound")
+
+        frames = await self._socket.recv_multipart()
+        if len(frames) != 3 or frames[1] != b"":
+            raise ValueError(f"Invalid ROUTER frame: {frames}")
+
+        client_id, _, raw = frames
+        proto = message_pb2.HostelMessage()
+        proto.ParseFromString(raw)
+        return client_id, proto_to_pydantic(proto)  # type: ignore[return-value]
+
+    async def send(self, client_id: ClientId, message: HostelMessage) -> None:
+        if self._socket is None:
+            raise RuntimeError("Transport not bound")
+
+        proto = pydantic_to_proto(message)
+        raw = proto.SerializeToString()
+        await self._socket.send_multipart([client_id, b"", raw])
+
+    async def close(self) -> None:
+        if self._socket is not None:
+            self._socket.close()
+            self._socket = None