samtale 0.1.0__py3-none-any.whl

samtale/__init__.py

@@ -0,0 +1,24 @@
+from .agent import Agent
+from .exceptions import (
+    AgentClosedError,
+    ChatterError,
+    MessageValidationError,
+    RemoteError,
+    RemoteRejection,
+    SendTimeout,
+    TransportError,
+)
+from .message import Message, Status
+
+__all__ = [
+    "Agent",
+    "AgentClosedError",
+    "ChatterError",
+    "Message",
+    "MessageValidationError",
+    "RemoteError",
+    "RemoteRejection",
+    "SendTimeout",
+    "Status",
+    "TransportError",
+]

samtale/agent.py

@@ -0,0 +1,370 @@
+from __future__ import annotations
+
+"""HTTP agent runtime.
+
+The `Agent` class exposes a small peer-to-peer HTTP message endpoint, a handler
+registry, an internal queue, and outbound helpers for sending messages to other
+agents. Handler execution is intentionally serialized through the queue.
+"""
+
+import asyncio
+import logging
+import math
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+from pydantic import BaseModel
+import uvicorn
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.routing import Route
+
+from .exceptions import (
+    AgentClosedError,
+    MessageValidationError,
+    RemoteError,
+    RemoteRejection,
+    SendTimeout,
+    TransportError,
+)
+from .helpers import (
+    Handler,
+    HandlerDefinition,
+    complete_future,
+    dispatch_handler,
+    error_response,
+    fail_future,
+    json_message,
+    remote_error_payload,
+    request_message,
+    response_message,
+    status_for,
+    validate_response,
+)
+from .message import Message, Status
+
+logger = logging.getLogger(__name__)
+
+
+class Agent:
+    """An asynchronous HTTP endpoint that receives and sends `Message` objects.
+
+    Each agent owns a Starlette app at `app`, an inbox queue, a bounded worker
+    pool, and a reusable HTTP client for outbound messages.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        timeout: float = 5.0,
+        handler_timeout: float | None = None,
+        max_concurrency: int = 1,
+    ):
+        """Create an agent.
+
+        Args:
+            name: Stable sender name used in outbound and response messages.
+            timeout: HTTP client timeout for outbound sends.
+            handler_timeout: Optional timeout for each handler invocation.
+            max_concurrency: Maximum number of handlers that may run at once.
+        """
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("name must be a non-empty string")
+        if not _valid_timeout(timeout):
+            raise ValueError("timeout must be greater than zero")
+        if handler_timeout is not None and not _valid_timeout(handler_timeout):
+            raise ValueError("handler_timeout must be greater than zero")
+        if (
+            not isinstance(max_concurrency, int)
+            or isinstance(max_concurrency, bool)
+            or max_concurrency <= 0
+        ):
+            raise ValueError("max_concurrency must be a positive integer")
+
+        # Keep construction cheap: the HTTP app is ready, but the worker pool
+        # starts with the app lifespan or an explicit start() call.
+        self.name = name.strip()
+        self.timeout = timeout
+        self.handler_timeout = handler_timeout
+        self.max_concurrency = max_concurrency
+        self.handlers: dict[str, HandlerDefinition] = {}
+        self.inbox: asyncio.Queue[tuple[Message, asyncio.Future[Message]]] = (
+            asyncio.Queue()
+        )
+        self._workers: list[asyncio.Task[None]] = []
+        self._client: httpx.AsyncClient | None = None
+        self._active_futures: set[asyncio.Future[Message]] = set()
+        self._accepting = False
+
+        @asynccontextmanager
+        async def lifespan(app: Starlette):
+            # Starlette owns the server lifecycle; the agent owns the inbox worker.
+            await self.start()
+            try:
+                yield
+            finally:
+                await self.close()
+
+        async def receive(request: Request):
+            # HTTP requests stop at the queue boundary. The agent loop does the
+            # actual handler lookup and execution.
+            try:
+                message = await request_message(request)
+            except MessageValidationError as exc:
+                return error_response(self.name, None, "malformed_message", str(exc))
+            except Exception:
+                logger.exception("Failed to read inbound message")
+                return error_response(
+                    self.name,
+                    None,
+                    "internal_error",
+                    "The message could not be processed",
+                )
+
+            if not self._accepting:
+                return error_response(
+                    self.name, message, "agent_closed", "The agent is closed"
+                )
+
+            future: asyncio.Future[Message] = asyncio.get_running_loop().create_future()
+            await self.inbox.put((message, future))
+            try:
+                response = await future
+            except asyncio.CancelledError:
+                future.cancel()
+                raise
+            except AgentClosedError:
+                response = Message.error(
+                    self.name,
+                    message,
+                    "agent_closed",
+                    {"message": "The agent is closed"},
+                )
+
+            return json_message(response, status_for(response))
+
+        self.app = Starlette(
+            lifespan=lifespan, routes=[Route("/messages", receive, methods=["POST"])]
+        )
+
+    def on(
+        self,
+        message_type: str,
+        *,
+        model: type[BaseModel] | None = None,
+    ):
+        """Register an async handler for a message type.
+
+        Args:
+            message_type: Domain message type, for example `temperature.read`.
+            model: Optional Pydantic model used to validate and parse the payload.
+
+        Returns:
+            A decorator that stores the handler and returns it unchanged.
+        """
+        if not isinstance(message_type, str) or not message_type:
+            raise ValueError("message_type must be a non-empty string")
+        if model is not None and (
+            not isinstance(model, type) or not issubclass(model, BaseModel)
+        ):
+            raise TypeError("model must be a Pydantic BaseModel subclass")
+
+        # Decorator API: @agent.on("read") registers the async handler.
+        def decorator(fn: Handler):
+            if message_type in self.handlers:
+                raise ValueError(f"handler already registered for {message_type!r}")
+            self.handlers[message_type] = HandlerDefinition(
+                handler=fn,
+                model=model,
+                schema=model.model_json_schema() if model is not None else {},
+            )
+            return fn
+
+        return decorator
+
+    def reject(
+        self, request: Message, reason: str, payload: dict[str, Any] | None = None
+    ) -> Message:
+        """Build a correlated domain rejection from inside a handler."""
+        return Message.reject(self.name, request, reason, payload)
+
+    def ok(self, request: Message, payload: dict[str, Any] | None = None) -> Message:
+        """Build a correlated successful response from inside a handler."""
+        return Message.ok(self.name, request, payload)
+
+    async def start(self) -> None:
+        """Start the outbound HTTP client and handler workers."""
+        # Idempotent so tests or embedding code can call it directly.
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+        self._workers = [worker for worker in self._workers if not worker.done()]
+        self._workers.extend(
+            asyncio.create_task(self._loop())
+            for _ in range(self.max_concurrency - len(self._workers))
+        )
+        self._accepting = True
+
+    async def close(self) -> None:
+        """Stop the worker pool, fail pending requests, and close the client."""
+        # Cancel the background worker cleanly during app shutdown.
+        self._accepting = False
+        error = AgentClosedError(f"agent {self.name!r} is closed")
+        for future in tuple(self._active_futures):
+            fail_future(future, error)
+
+        for worker in self._workers:
+            worker.cancel()
+        if self._workers:
+            await asyncio.gather(*self._workers, return_exceptions=True)
+        self._workers.clear()
+        self._active_futures.clear()
+
+        while not self.inbox.empty():
+            _message, future = self.inbox.get_nowait()
+            fail_future(future, error)
+            self.inbox.task_done()
+
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def _loop(self) -> None:
+        """Dispatch queued messages until cancelled."""
+        while True:
+            message, future = await self.inbox.get()
+            self._active_futures.add(future)
+            try:
+                if not future.done():
+                    complete_future(future, await self._dispatch(message))
+            except Exception:
+                logger.exception("Handler %r failed unexpectedly", message.type)
+                complete_future(
+                    future,
+                    Message.error(
+                        self.name,
+                        message,
+                        "handler_failure",
+                        {"message": "The message handler failed"},
+                    ),
+                )
+            finally:
+                self._active_futures.discard(future)
+                self.inbox.task_done()
+
+    async def _dispatch(self, message: Message) -> Message:
+        """Run the registered handler and normalize its result to a response."""
+        definition = self.handlers.get(message.type)
+        if definition is None:
+            return Message.reject(
+                self.name,
+                message,
+                "unsupported_message",
+                {
+                    "accepted_messages": [
+                        {
+                            "type": message_type,
+                            "schema": self.handlers[message_type].schema,
+                        }
+                        for message_type in sorted(self.handlers)
+                    ],
+                },
+            )
+
+        return await dispatch_handler(
+            self.name, definition, message, self.handler_timeout
+        )
+
+    async def send(self, address: str, message_type: str, **payload: Any) -> Message:
+        """Send a request to another agent and return the full response message.
+
+        Raises:
+            SendTimeout: The HTTP request timed out.
+            TransportError: The transport failed or the response envelope was invalid.
+            RemoteError: The peer returned an HTTP error with a valid agent error.
+        """
+        # Create the wire message, POST it to the peer, and return the complete
+        # validated response envelope.
+        message = Message(sender=self.name, type=message_type, payload=payload)
+        await self.start()
+        assert self._client is not None
+
+        try:
+            response = await self._client.post(
+                f"{address.rstrip('/')}/messages", json=message.to_dict()
+            )
+            response.raise_for_status()
+        except httpx.TimeoutException as exc:
+            raise SendTimeout(address, message.id, self.timeout) from exc
+        except httpx.HTTPStatusError as exc:
+            envelope = response_message(exc.response, address)
+            validate_response(address, message, envelope)
+            if envelope.status is Status.ERROR:
+                raise RemoteError(
+                    address, message.id, remote_error_payload(envelope)
+                ) from exc
+            raise TransportError(
+                f"{address} returned HTTP {exc.response.status_code}"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+
+        envelope = response_message(response, address)
+        validate_response(address, message, envelope)
+        return envelope
+
+    async def ask(
+        self, address: str, message_type: str, **payload: Any
+    ) -> dict[str, Any]:
+        """Send a request that is expected to succeed and return only payload."""
+        response = await self.send(address, message_type, **payload)
+        self._require_ok(address, response)
+        return response.payload
+
+    async def emit(
+        self,
+        address: str,
+        message_type: str,
+        **payload: Any,
+    ) -> None:
+        """Send a message and discard the successful response payload.
+
+        This is an acknowledgement-based convenience method, not guaranteed
+        delivery and not true fire-and-forget.
+        """
+        response = await self.send(
+            address,
+            message_type,
+            **payload,
+        )
+
+        self._require_ok(address, response)
+
+    @staticmethod
+    def _require_ok(address: str, response: Message) -> None:
+        if response.status is Status.REJECTED:
+            raise RemoteRejection(
+                address,
+                response.reply_to or "",
+                response.reason or "rejected",
+                response.payload,
+            )
+        if response.status is Status.ERROR:
+            raise RemoteError(
+                address, response.reply_to or "", remote_error_payload(response)
+            )
+
+    def run(self, *, host: str = "0.0.0.0", port: int = 8000) -> None:
+        """Run the agent's Starlette app with uvicorn."""
+        # Convenience runner for examples and small local processes.
+        uvicorn.run(self.app, host=host, port=port)
+
+
+def _valid_timeout(value: object) -> bool:
+    return (
+        isinstance(value, int | float)
+        and not isinstance(value, bool)
+        and math.isfinite(value)
+        and value > 0
+    )

samtale/exceptions.py

@@ -0,0 +1,50 @@
+from typing import Any
+
+
+class ChatterError(Exception):
+    """Base exception for samtale."""
+
+
+class AgentClosedError(ChatterError):
+    """Raised when work cannot complete because the agent is closing."""
+
+
+class MessageValidationError(ChatterError):
+    """Raised when a wire message is malformed."""
+
+
+class RemoteError(ChatterError):
+    def __init__(self, target: str, message_id: str, error: dict):
+        self.target = target
+        self.message_id = message_id
+        self.error = error
+        super().__init__(f"{target} returned error for {message_id}: {error}")
+
+
+class RemoteRejection(ChatterError):
+    """Raised when a remote agent rejects an otherwise valid request."""
+
+    def __init__(
+        self,
+        target: str,
+        message_id: str,
+        reason: str,
+        payload: dict[str, Any],
+    ):
+        self.target = target
+        self.message_id = message_id
+        self.reason = reason
+        self.payload = payload
+        super().__init__(f"{target} rejected message {message_id}: {reason}")
+
+
+class SendTimeout(ChatterError):
+    def __init__(self, target: str, message_id: str, timeout: float):
+        self.target = target
+        self.message_id = message_id
+        self.timeout = timeout
+        super().__init__(f"message {message_id} to {target} timed out after {timeout:g}s")
+
+
+class TransportError(ChatterError):
+    """Raised when the HTTP transport fails or returns a malformed response."""

samtale/helpers.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ValidationError
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from .exceptions import MessageValidationError, TransportError
+from .message import Message, Status
+
+Handler = Callable[..., Awaitable[Any]]
+PayloadModel = type[BaseModel]
+logger = logging.getLogger(__name__)
+HANDLER_FAILURE_MESSAGE = "The message handler failed"
+
+
+@dataclass(slots=True)
+class HandlerDefinition:
+    handler: Handler
+    model: PayloadModel | None = None
+    schema: dict[str, Any] = field(default_factory=dict)
+
+
+def json_message(message: Message, status: int) -> JSONResponse:
+    return JSONResponse(message.to_dict(), status_code=status)
+
+
+def error_response(
+    sender: str,
+    request: Message | None,
+    reason: str,
+    detail: str,
+) -> JSONResponse:
+    message = Message.error(sender, request, reason, {"message": detail})
+    return json_message(message, status_for(message))
+
+
+async def request_message(request: Request) -> Message:
+    try:
+        data = await request.json()
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise MessageValidationError(f"invalid JSON: {exc}") from exc
+
+    message = Message.from_dict(data)
+    if not message.is_request:
+        raise MessageValidationError("the messages endpoint only accepts requests")
+    return message
+
+
+def status_for(message: Message) -> int:
+    if message.status is not Status.ERROR:
+        return 200
+    return {
+        "malformed_message": 400,
+        "handler_timeout": 504,
+        "agent_closed": 503,
+    }.get(message.reason, 500)
+
+
+def parse_payload(
+    agent_name: str,
+    definition: HandlerDefinition,
+    message: Message,
+) -> tuple[Message | None, BaseModel | None]:
+    if definition.model is not None:
+        try:
+            return None, definition.model.model_validate(message.payload)
+        except ValidationError as exc:
+            return (
+                Message.reject(
+                    agent_name,
+                    message,
+                    "invalid_payload",
+                    {
+                        "expected_message": {"type": message.type, "schema": definition.schema},
+                        "issues": pydantic_issues(exc),
+                    },
+                ),
+                None,
+            )
+
+    return None, None
+
+
+async def dispatch_handler(
+    sender: str,
+    definition: HandlerDefinition,
+    message: Message,
+    timeout: float | None,
+) -> Message:
+    invalid, parsed_payload = parse_payload(sender, definition, message)
+    if invalid is not None:
+        return invalid
+
+    try:
+        invocation = (
+            definition.handler(message, parsed_payload)
+            if definition.model is not None
+            else definition.handler(message)
+        )
+        result = await invocation if timeout is None else await asyncio.wait_for(invocation, timeout)
+    except asyncio.TimeoutError:
+        return Message.error(
+            sender,
+            message,
+            "handler_timeout",
+            {"message": f"Handler timed out after {timeout:g}s"},
+        )
+    except Exception:
+        logger.exception("Handler %r failed", message.type)
+        return Message.error(sender, message, "handler_failure", {"message": HANDLER_FAILURE_MESSAGE})
+
+    return normalize_handler_result(sender, message, result)
+
+
+def normalize_handler_result(sender: str, request: Message, result: Any) -> Message:
+    try:
+        if isinstance(result, Message):
+            response = normalize_handler_message(sender, request, result)
+        elif result is None:
+            response = Message.ok(sender, request)
+        elif isinstance(result, dict):
+            response = Message.ok(sender, request, result)
+        else:
+            raise MessageValidationError("Handler must return a dict, Message, or None")
+    except MessageValidationError as exc:
+        return Message.error(sender, request, "invalid_handler_result", {"message": str(exc)})
+
+    return response
+
+
+def pydantic_issues(exc: ValidationError) -> list[dict[str, Any]]:
+    return [
+        {
+            "field": ".".join(str(part) for part in error["loc"]),
+            "reason": error["type"],
+            "message": error["msg"],
+        }
+        for error in exc.errors()
+    ]
+
+
+def normalize_handler_message(sender: str, request: Message, result: Message) -> Message:
+    if result.reply_to != request.id or result.type != request.type:
+        raise MessageValidationError("handler response must match the request")
+    if result.sender != sender:
+        return Message(
+            sender=sender,
+            type=result.type,
+            payload=result.payload,
+            id=result.id,
+            reply_to=result.reply_to,
+            status=result.status,
+            reason=result.reason,
+        )
+    return result
+
+
+def validate_response(address: str, request: Message, response: Message) -> None:
+    if response.reply_to != request.id:
+        raise TransportError(f"{address} response did not match message {request.id}")
+    if response.type != request.type:
+        raise TransportError(f"{address} response type {response.type!r} did not match {request.type!r}")
+    if response.status is None:
+        raise TransportError(f"{address} response did not include status")
+
+
+def remote_error_payload(response: Message) -> dict[str, Any]:
+    return {
+        "status": response.status.value if response.status else None,
+        "reason": response.reason,
+        "payload": response.payload,
+    }
+
+
+def complete_future(future: asyncio.Future[Message] | None, result: Message) -> None:
+    if future is not None and not future.done():
+        future.set_result(result)
+
+
+def fail_future(future: asyncio.Future[Message] | None, exc: Exception) -> None:
+    if future is not None and not future.done():
+        future.set_exception(exc)
+
+
+def response_message(response: httpx.Response, target: str) -> Message:
+    try:
+        return Message.from_dict(response.json())
+    except Exception as exc:
+        raise TransportError(f"{target} returned a malformed response") from exc

samtale/message.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+from uuid import uuid4
+
+from .exceptions import MessageValidationError
+
+
+class Status(StrEnum):
+    OK = "ok"
+    REJECTED = "rejected"
+    ERROR = "error"
+
+
+@dataclass(slots=True)
+class Message:
+    sender: str
+    type: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=lambda: str(uuid4()))
+    reply_to: str | None = None
+    status: Status | None = None
+    reason: str | None = None
+
+    def __post_init__(self) -> None:
+        _require_text(self.id, "id")
+        _require_text(self.sender, "sender")
+        _require_text(self.type, "type")
+        if not isinstance(self.payload, dict):
+            raise MessageValidationError("payload must be an object")
+        try:
+            json.dumps(self.payload, allow_nan=False)
+        except (TypeError, ValueError) as exc:
+            raise MessageValidationError("payload must be JSON-compatible") from exc
+        if self.status is not None and not isinstance(self.status, Status):
+            try:
+                self.status = Status(self.status)
+            except (TypeError, ValueError) as exc:
+                raise MessageValidationError(f"invalid status: {self.status!r}") from exc
+
+        if self.reply_to is None:
+            self._validate_uncorrelated()
+            return
+
+        _require_text(self.reply_to, "reply_to")
+        if self.status is None:
+            raise MessageValidationError("responses require status")
+        if self.status is Status.OK:
+            if self.reason is not None:
+                raise MessageValidationError("ok responses cannot have reason")
+            return
+        _require_text(self.reason, "reason")
+
+    def _validate_uncorrelated(self) -> None:
+        if self.type == "_agent.error":
+            if self.status is not Status.ERROR:
+                raise MessageValidationError("uncorrelated framework errors require error status")
+            _require_text(self.reason, "reason")
+            return
+        if self.status is not None:
+            raise MessageValidationError("requests cannot have status")
+        if self.reason is not None:
+            raise MessageValidationError("requests cannot have reason")
+
+    @classmethod
+    def from_dict(cls, data: object) -> "Message":
+        if not isinstance(data, dict):
+            raise MessageValidationError("message must be a JSON object")
+
+        allowed = {"id", "sender", "type", "payload", "reply_to", "status", "reason"}
+        extra = set(data) - allowed
+        if extra:
+            raise MessageValidationError(f"unknown message field: {sorted(extra)[0]}")
+        for field_name in ("id", "sender", "type"):
+            if field_name not in data:
+                raise MessageValidationError(f"missing required field: {field_name}")
+        if "reply_to" in data and data["reply_to"] is None:
+            raise MessageValidationError("reply_to must be a non-empty string")
+        if "status" in data and data["status"] is None:
+            raise MessageValidationError("status must be one of: ok, rejected, error")
+        if "reason" in data and data["reason"] is None:
+            raise MessageValidationError("reason must be a non-empty string")
+
+        try:
+            status = Status(data["status"]) if "status" in data else None
+        except (TypeError, ValueError) as exc:
+            raise MessageValidationError(f"invalid status: {data.get('status')!r}") from exc
+
+        return cls(
+            id=data["id"],
+            sender=data["sender"],
+            type=data["type"],
+            payload=data.get("payload", {}),
+            reply_to=data.get("reply_to"),
+            status=status,
+            reason=data.get("reason"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "id": self.id,
+            "sender": self.sender,
+            "type": self.type,
+            "payload": self.payload,
+        }
+        if self.reply_to is not None:
+            data["reply_to"] = self.reply_to
+        if self.status is not None:
+            data["status"] = self.status.value
+        if self.reason is not None:
+            data["reason"] = self.reason
+        return data
+
+    @classmethod
+    def ok(cls, sender: str, request: "Message", payload: dict[str, Any] | None = None) -> "Message":
+        return cls(sender=sender, type=request.type, payload=payload or {}, reply_to=request.id, status=Status.OK)
+
+    @classmethod
+    def reject(
+        cls,
+        sender: str,
+        request: "Message",
+        reason: str,
+        payload: dict[str, Any] | None = None,
+    ) -> "Message":
+        return cls(
+            sender=sender,
+            type=request.type,
+            payload=payload or {},
+            reply_to=request.id,
+            status=Status.REJECTED,
+            reason=reason,
+        )
+
+    @classmethod
+    def error(
+        cls,
+        sender: str,
+        request: "Message" | None,
+        reason: str,
+        payload: dict[str, Any] | None = None,
+    ) -> "Message":
+        return cls(
+            sender=sender,
+            type=request.type if request else "_agent.error",
+            payload=payload or {},
+            reply_to=request.id if request else None,
+            status=Status.ERROR,
+            reason=reason,
+        )
+
+    @property
+    def is_request(self) -> bool:
+        return self.reply_to is None and self.status is None
+
+    @property
+    def is_response(self) -> bool:
+        return self.reply_to is not None
+
+
+def _require_text(value: object, field: str) -> None:
+    if not isinstance(value, str) or not value:
+        raise MessageValidationError(f"{field} must be a non-empty string")

samtale-0.1.0.dist-info/METADATA

@@ -0,0 +1,282 @@
+Metadata-Version: 2.5
+Name: samtale
+Version: 0.1.0
+Summary: A modern, minimal messaging framework for agents.
+Project-URL: Homepage, https://github.com/devjc/samtale
+Project-URL: Repository, https://github.com/devjc/samtale
+Project-URL: Issues, https://github.com/devjc/samtale/issues
+Author: Joshua Croft
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,asyncio,http,messaging,multi-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: httpx
+Requires-Dist: pydantic>=2
+Requires-Dist: starlette
+Requires-Dist: uvicorn
+Description-Content-Type: text/markdown
+
+# Samtale
+
+A modern, minimal messaging framework for agents.
+
+Samtale lets independent Python components exchange typed requests and
+structured outcomes over HTTP. An agent can be a sensor, controller, service,
+state machine, or LLM-backed application.
+
+Samtale provides a uniform message envelope, Pydantic payload validation,
+bounded handler concurrency, and three outcomes: `ok`, `rejected`, or `error`.
+When an agent does not understand a request, it responds with the message types
+and JSON schemas it accepts.
+
+Samtale provides no broker, orchestration, memory, conversation history,
+workflow engine, or LLM dependency.
+
+```text
+request → envelope validation → handler lookup → payload validation
+        → handler execution → ok / rejected / error
+```
+
+Python 3.11 or later is required.
+
+## Installation
+
+```bash
+pip install samtale
+```
+
+## A small agent
+
+```python
+from typing import Literal
+
+from pydantic import BaseModel
+
+from samtale import Agent, Message
+
+
+class WeatherRequest(BaseModel):
+    location: str
+    unit: Literal["c", "f"] = "c"
+
+
+weather = Agent("weather")
+
+
+@weather.on("weather_request", model=WeatherRequest)
+async def get_weather(message: Message, request: WeatherRequest):
+    return {
+        "location": request.location,
+        "temperature": 18.4,
+        "unit": request.unit,
+    }
+
+
+if __name__ == "__main__":
+    weather.run(port=8003)
+```
+
+Call it from another agent:
+
+```python
+import asyncio
+
+from samtale import Agent
+
+
+async def main() -> None:
+    consumer = Agent("consumer")
+
+    try:
+        result = await consumer.ask(
+            "http://localhost:8003",
+            "weather_request",
+            location="London",
+            unit="c",
+        )
+        print(result)
+    finally:
+        await consumer.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Rejection is an outcome
+
+An agent can understand a request and still decline it for a domain reason:
+
+```python
+from pydantic import BaseModel
+
+from samtale import Message, Agent
+
+
+class SetTemperature(BaseModel):
+    value: float
+
+weather = Agent("weather")
+
+@weather.on("temperature.set", model=SetTemperature)
+async def set_temperature(message: Message, request: SetTemperature):
+    if request.value > 21:
+        return weather.reject(
+            message,
+            "outside_supported_range",
+            {
+                "requested": request.value,
+                "maximum": 21,
+            },
+        )
+
+    return {"value": request.value}
+```
+
+`send()` returns that rejection normally, leaving the next decision to the
+caller:
+
+```python
+from samtale import Status, Agent
+
+consumer = Agent("consumer")
+
+async def set_temperature_with_fallback() -> None:
+    response = await consumer.send(
+        "http://localhost:8003",
+        "temperature.set",
+        value=24,
+    )
+
+    if (
+        response.status is Status.REJECTED
+        and response.reason == "outside_supported_range"
+    ):
+        response = await consumer.send(
+            "http://localhost:8003",
+            "temperature.set",
+            value=response.payload["maximum"],
+        )
+```
+
+The framework standardizes the exchange; the agents decide what happens next.
+
+## Self-describing rejections
+
+If the consumer sends an unsupported message type, the weather agent returns a
+normal rejection with its accepted messages. The relevant response fields look
+like this:
+
+```json
+{
+  "status": "rejected",
+  "reason": "unsupported_message",
+  "payload": {
+    "accepted_messages": [
+      {
+        "type": "weather_request",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "location": {"type": "string"},
+            "unit": {"enum": ["c", "f"], "default": "c"}
+          },
+          "required": ["location"]
+        }
+      }
+    ]
+  }
+}
+```
+
+Invalid payloads are also rejected and include the expected message schema
+alongside structured validation issues.
+
+## Sending messages
+
+The three outbound methods share the same acknowledged HTTP exchange:
+
+- `send()` returns the complete response `Message`, including rejections.
+- `ask()` expects success and returns only the response payload.
+- `emit()` expects success and discards the response payload.
+
+`ask()` and `emit()` raise `RemoteRejection` for ordinary domain rejections and
+`RemoteError` for unexpected remote failures. `emit()` is a convenience method,
+not guaranteed delivery or true fire-and-forget.
+
+## Concurrency
+
+Agents execute one handler at a time by default. Set `max_concurrency` when an
+agent should continue processing while another handler awaits I/O:
+
+```python
+agent = Agent("weather", max_concurrency=8)
+```
+
+At most eight handlers execute simultaneously; additional messages remain in
+the inbox. Concurrent handlers can access the same local state across `await`
+points, so applications should protect shared mutable state when necessary.
+
+## Wire format
+
+A request is a JSON object:
+
+```json
+{
+  "id": "request-id",
+  "sender": "consumer",
+  "type": "weather_request",
+  "payload": {"location": "London", "unit": "c"}
+}
+```
+
+The response retains the domain type and correlates itself with `reply_to`:
+
+```json
+{
+  "id": "response-id",
+  "sender": "weather",
+  "type": "weather_request",
+  "payload": {"location": "London", "temperature": 18.4, "unit": "c"},
+  "reply_to": "request-id",
+  "status": "ok"
+}
+```
+
+HTTP status describes the HTTP-level outcome. Message status describes the
+domain outcome. Rejections use HTTP 200; malformed input and runtime failures
+use the corresponding HTTP error status.
+
+## Run the included example
+
+From a checkout:
+
+```bash
+uv sync --locked
+uv run python examples/weather.py
+```
+
+In another terminal:
+
+```bash
+uv run python examples/weather_consumer.py
+```
+
+The consumer first demonstrates schema discovery with an unsupported request,
+then sends a valid typed request.
+
+## Tests
+
+```bash
+uv run python -m unittest discover -s tests -v
+```
+
+The GitHub Actions workflow runs the suite on Python 3.11, 3.12, and 3.13.

samtale-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+samtale/__init__.py,sha256=GtX07b-NyPimRydKv6_YTfaKAfVfhqdNlHmvNzG3umw,447
+samtale/agent.py,sha256=HucC8U6OEk95WyuJ8yJGgCsbdnfurePf9zPKqSnv9KU,13424
+samtale/exceptions.py,sha256=Y5DAY84cfkuJj1ItHWIEE5EaiJb4KdSFHWLlsUOFg_k,1445
+samtale/helpers.py,sha256=ojablal9BTmxQ2Xvo1fagwpAa7EZG-AgtyyLv0flOHg,6280
+samtale/message.py,sha256=fM__KvwXBJdxF_8ma15Tr6TLwEQPM44Z-TPo0uUnl0o,5786
+samtale-0.1.0.dist-info/METADATA,sha256=DDxLlbmdmHI0VdeOyeamdpDCoLZyjqKn_aE6ypNOdFo,6930
+samtale-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+samtale-0.1.0.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+samtale-0.1.0.dist-info/RECORD,,

samtale-0.1.0.dist-info/WHEEL

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

samtale-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.