superdialog 0.2.0a0__py3-none-any.whl

superdialog/__init__.py

@@ -0,0 +1,55 @@
+"""SuperDialog -- standalone dialog state machine framework."""
+
+__version__ = "0.2.0a0"
+
+from .agent import Agent, TurnResult
+from .agents import LLMAgent
+from .chat_context import ChatContext, ChatMessage
+from .dialog_machine import DialogMachine
+from .flow import Flow, FlowSet, create_dialog_flow
+from .flow_state import FlowState
+from .llm.registry import register_llm_provider
+from .session import (
+    AsyncioLockBackend,
+    InMemorySessionStore,
+    LockBackend,
+    NullSessionStore,
+    Session,
+    SessionHandle,
+    SessionRecord,
+    SessionStore,
+    SessionWorker,
+)
+from .stream import StreamChunk, ToolCall, Turn
+from .tools import HttpTool, MCPTool, PythonTool, Tool, ToolResult
+
+__all__ = [
+    "Agent",
+    "AsyncioLockBackend",
+    "ChatContext",
+    "ChatMessage",
+    "DialogMachine",
+    "Flow",
+    "FlowSet",
+    "FlowState",
+    "HttpTool",
+    "InMemorySessionStore",
+    "LLMAgent",
+    "LockBackend",
+    "MCPTool",
+    "NullSessionStore",
+    "PythonTool",
+    "Session",
+    "SessionHandle",
+    "SessionRecord",
+    "SessionStore",
+    "SessionWorker",
+    "StreamChunk",
+    "Tool",
+    "ToolCall",
+    "ToolResult",
+    "Turn",
+    "TurnResult",
+    "create_dialog_flow",
+    "register_llm_provider",
+]

superdialog/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Host adapters for :class:`superdialog.DialogMachine`.
+
+Each adapter is gated behind its own optional extra so the core package
+stays import-light:
+
+* :mod:`superdialog.adapters.livekit`   -- ``pip install superdialog[livekit]``
+* :mod:`superdialog.adapters.pipecat`   -- ``pip install superdialog[pipecat]``
+* :mod:`superdialog.adapters.fastapi`   -- ``pip install superdialog[fastapi]``
+* :mod:`superdialog.adapters.websocket` -- ``pip install superdialog[ws]``
+
+Import the submodule you need; this package intentionally does not eagerly
+import any adapter to keep the dependency surface minimal.
+"""

superdialog/adapters/fastapi.py

@@ -0,0 +1,120 @@
+"""FastAPI adapter for any superdialog :class:`Agent`.
+
+Provides :func:`make_router` (an ``APIRouter`` factory) and a
+:class:`FastAPIRouter` convenience wrapper that knows how to mount the
+router onto an existing :class:`fastapi.FastAPI` app.
+
+Endpoints:
+
+* ``POST /turn``   -- run one synchronous turn and return ``{reply, metadata}``.
+* ``POST /stream`` -- run one streaming turn as Server-Sent Events.
+* ``POST /assist`` -- queue a system-level steering instruction.
+* ``POST /reset``  -- drop conversation memory (Agent.reset when available).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from superdialog.stream import StreamChunk
+
+if TYPE_CHECKING:  # pragma: no cover
+    from superdialog.agent import Agent
+else:
+    Agent = Any
+
+logger = logging.getLogger(__name__)
+
+
+def _require_fastapi() -> tuple[Any, Any, Any]:
+    try:
+        from fastapi import APIRouter, FastAPI  # type: ignore
+        from fastapi.responses import StreamingResponse  # type: ignore
+    except ImportError as e:
+        raise RuntimeError(
+            "FastAPI adapter requires the fastapi extra: "
+            "`pip install superdialog[fastapi]`"
+        ) from e
+    return APIRouter, FastAPI, StreamingResponse
+
+
+def make_router(agent: Agent) -> Any:
+    """Return an ``APIRouter`` exposing the standard agent endpoints.
+
+    Accepts any superdialog :class:`Agent`. ``/turn`` and ``/stream``
+    are available unconditionally; ``/assist`` and ``/reset`` are wired
+    in only when the underlying agent supports them (``DialogMachine``,
+    ``LLMAgent`` do; bare protocol implementations may not).
+    """
+    APIRouter, _FastAPI, StreamingResponse = _require_fastapi()
+    router = APIRouter()
+
+    @router.post("/turn")
+    async def handle_turn(payload: dict[str, Any]) -> dict[str, Any]:
+        text = payload.get("text", "")
+        context = payload.get("context") or None
+        # Forward `context` only to agents that accept it (DialogMachine);
+        # generic Agent.turn signature only takes (text, *, stream).
+        try:
+            turn = await agent.turn(text, context=context)  # type: ignore[call-arg]
+        except TypeError:
+            turn = await agent.turn(text)
+        return {"reply": turn.text, "metadata": turn.metadata}
+
+    @router.post("/stream")
+    async def handle_stream(payload: dict[str, Any]) -> Any:
+        text = payload.get("text", "")
+        context = payload.get("context") or None
+        try:
+            stream = await agent.turn(text, context=context, stream=True)  # type: ignore[call-arg]
+        except TypeError:
+            stream = await agent.turn(text, stream=True)
+
+        async def sse() -> Any:
+            async for chunk in stream:  # type: ignore[union-attr]
+                yield _sse_event(chunk)
+
+        return StreamingResponse(sse(), media_type="text/event-stream")
+
+    @router.post("/assist")
+    async def handle_assist(payload: dict[str, Any]) -> dict[str, str]:
+        text = payload.get("text", "")
+        assist_fn = getattr(agent, "assist", None)
+        if assist_fn is None:
+            return {"status": "unsupported"}
+        assist_fn(text)
+        return {"status": "ok"}
+
+    @router.post("/reset")
+    async def handle_reset() -> dict[str, str]:
+        reset_fn = getattr(agent, "reset", None)
+        if reset_fn is None:
+            return {"status": "unsupported"}
+        reset_fn()
+        return {"status": "ok"}
+
+    return router
+
+
+def _sse_event(chunk: StreamChunk) -> str:
+    payload = {"text": chunk.text, "done": chunk.done}
+    if chunk.done and chunk.turn is not None:
+        payload["metadata"] = chunk.turn.metadata
+    return f"data: {json.dumps(payload)}\n\n"
+
+
+class FastAPIRouter:
+    """Mountable router that exposes a superdialog :class:`Agent` over HTTP."""
+
+    def __init__(self, agent: Agent) -> None:
+        self.agent = agent
+        self.router = make_router(agent)
+
+    def mount(self, app: Any, prefix: str = "") -> None:
+        """Attach the router to ``app`` (a ``FastAPI`` instance)."""
+        app.include_router(self.router, prefix=prefix)
+
+
+__all__ = ["FastAPIRouter", "make_router"]

superdialog/adapters/livekit.py

@@ -0,0 +1,197 @@
+"""LiveKit Agents adapter for any superdialog :class:`Agent`.
+
+Mirrors the ``livekit-plugins-langchain`` pattern: expose a class that
+quacks like ``livekit.agents.llm.LLM`` so a LiveKit ``Agent`` can use any
+superdialog Agent (``DialogMachine``, ``LLMAgent``, ``LangChainAgent``)
+as its turn engine.
+
+PORT NOTE: confidence-driven barge-in interop (VAD end-of-speech signals
+piped into a richer streaming protocol) is a v0.4 follow-up. The adapter
+currently consumes ``Agent.turn(text, stream=True)`` and surfaces tokens
+as LiveKit ``ChatChunk`` frames.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+from superdialog.stream import StreamChunk
+
+if TYPE_CHECKING:  # pragma: no cover - only for static type checkers
+    from superdialog.agent import Agent
+else:
+    Agent = Any  # runtime alias so annotations don't import the protocol
+
+logger = logging.getLogger(__name__)
+
+
+def _require_livekit() -> Any:
+    """Return the ``livekit.agents.llm`` module or raise a friendly error."""
+    try:
+        from livekit.agents import llm as lk_llm  # type: ignore
+    except ImportError as e:
+        raise RuntimeError(
+            "DialogMachineLLM requires the livekit extra: "
+            "`pip install superdialog[livekit]`"
+        ) from e
+    return lk_llm
+
+
+class DialogMachineLLM:
+    """LiveKit ``Agent(llm=...)`` adapter backed by any superdialog :class:`Agent`.
+
+    Usage::
+
+        from livekit.agents import Agent as LKAgent, AgentSession
+        from superdialog import DialogMachine
+        from superdialog.adapters.livekit import DialogMachineLLM
+
+        dm = DialogMachine(flow=flow, llm="openai/gpt-5.1")
+        lk_agent = LKAgent(llm=DialogMachineLLM(dm))
+        await session.start(agent=lk_agent)
+
+    Any superdialog ``Agent`` (``DialogMachine``, ``LLMAgent``,
+    ``LangChainAgent``, or a custom Protocol implementation) works in
+    place of ``dm``. The adapter duck-types LiveKit's LLM protocol; the
+    precise method shape depends on the ``livekit-agents`` version
+    pinned in the ``[livekit]`` extra. Construction is lazy: importing
+    this module without livekit installed is allowed, only instantiation
+    fails.
+    """
+
+    def __init__(self, agent: Agent) -> None:
+        _require_livekit()  # fail-fast with a clear error message
+        self.agent = agent
+
+    def chat(
+        self,
+        *,
+        chat_ctx: Any,
+        fnc_ctx: Any = None,
+        conn_options: Any = None,
+        **kwargs: Any,
+    ) -> "DialogMachineStream":
+        """Return a streaming response object LiveKit can iterate over."""
+        return DialogMachineStream(
+            agent=self.agent,
+            chat_ctx=chat_ctx,
+            fnc_ctx=fnc_ctx,
+        )
+
+
+class DialogMachineStream:
+    """Async iterator that drives a single :class:`Agent` turn.
+
+    Pulls the latest user text out of LiveKit's ``ChatContext``, runs
+    ``agent.turn(text, stream=True)`` and yields LiveKit-shaped
+    ``ChatChunk`` frames. Falls back to plain dict frames when the
+    livekit-agents version does not expose a public ``ChatChunk``
+    constructor we can rely on.
+    """
+
+    def __init__(
+        self,
+        agent: Agent,
+        chat_ctx: Any,
+        fnc_ctx: Any = None,
+    ) -> None:
+        self._agent = agent
+        self._chat_ctx = chat_ctx
+        self._fnc_ctx = fnc_ctx
+        self._iter: AsyncIterator[StreamChunk] | None = None
+
+    async def _ensure_iter(self) -> AsyncIterator[StreamChunk]:
+        if self._iter is not None:
+            return self._iter
+        user_text = _extract_latest_user_text(self._chat_ctx)
+        stream = await self._agent.turn(user_text, stream=True)
+        assert hasattr(
+            stream, "__aiter__"
+        ), "Agent.turn(stream=True) must yield an async iterator"
+        self._iter = stream  # type: ignore[assignment]
+        return self._iter
+
+    def __aiter__(self) -> "DialogMachineStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        iterator = await self._ensure_iter()
+        try:
+            chunk: StreamChunk = await iterator.__anext__()
+        except StopAsyncIteration:
+            raise
+        return _to_chat_chunk(chunk)
+
+    async def aclose(self) -> None:  # pragma: no cover - tested via stop
+        iterator = self._iter
+        self._iter = None
+        if iterator is not None and hasattr(iterator, "aclose"):
+            await iterator.aclose()
+
+
+def _extract_latest_user_text(chat_ctx: Any) -> str:
+    """Pull the most recent user message out of a LiveKit ChatContext.
+
+    Tolerates the small API shifts between livekit-agents minor versions
+    by trying a sequence of attribute paths and falling back to ``str``.
+    """
+    if chat_ctx is None:
+        return ""
+    messages = (
+        getattr(chat_ctx, "messages", None) or getattr(chat_ctx, "items", None) or []
+    )
+    for msg in reversed(list(messages)):
+        role = getattr(msg, "role", None) or (
+            msg.get("role") if isinstance(msg, dict) else None
+        )
+        if role != "user":
+            continue
+        content = (
+            getattr(msg, "content", None)
+            if not isinstance(msg, dict)
+            else msg.get("content")
+        )
+        if isinstance(content, list):
+            parts = [
+                p if isinstance(p, str) else getattr(p, "text", "") for p in content
+            ]
+            return "".join(parts)
+        if isinstance(content, str):
+            return content
+    return ""
+
+
+def _to_chat_chunk(chunk: StreamChunk) -> Any:
+    """Render a :class:`StreamChunk` as a LiveKit ``ChatChunk``.
+
+    Older livekit-agents releases expose ``ChatChunk(request_id, delta)``;
+    newer ones use keyword-only constructors. When the symbol is missing
+    we fall back to a plain dict — LiveKit's runtime accepts dicts in
+    several call sites and tests can assert on shape directly.
+    """
+    lk_llm = _require_livekit()
+    chat_chunk_cls = getattr(lk_llm, "ChatChunk", None)
+    delta_cls = getattr(lk_llm, "ChoiceDelta", None)
+    if chat_chunk_cls is None:
+        return {"text": chunk.text, "done": chunk.done}
+    # Try a sequence of constructor shapes that have shipped across
+    # livekit-agents versions. Fall back to a plain dict if every shape
+    # raises (ValidationError, TypeError, etc.).
+    candidates: list[dict[str, Any]] = []
+    if delta_cls is not None:
+        delta_obj = delta_cls(role="assistant", content=chunk.text)
+        candidates.append({"id": "", "delta": delta_obj})
+        candidates.append({"request_id": "", "delta": delta_obj})
+    candidates.append({"id": "", "delta": {"content": chunk.text}})
+    candidates.append({"request_id": "", "delta": {"content": chunk.text}})
+    candidates.append({"content": chunk.text})
+    for kwargs in candidates:
+        try:
+            return chat_chunk_cls(**kwargs)
+        except Exception:  # noqa: BLE001 - probe across LK versions
+            continue
+    return {"text": chunk.text, "done": chunk.done}
+
+
+__all__ = ["DialogMachineLLM", "DialogMachineStream"]

superdialog/adapters/pipecat.py

@@ -0,0 +1,84 @@
+"""PipeCat adapter: a ``FrameProcessor`` that runs any superdialog :class:`Agent`.
+
+PipeCat plumbs frames between processors; we accept ``TextFrame`` items
+on the inbound side, drive a single ``Agent.turn(text)``, and emit
+``TextFrame`` items on the outbound side. Subclassing ``FrameProcessor``
+is deferred so importing this module without the ``pipecat`` extra is
+safe; only :func:`make_processor` (and class instantiation) requires it.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover
+    from superdialog.agent import Agent
+else:
+    Agent = Any
+
+logger = logging.getLogger(__name__)
+
+
+def _require_pipecat() -> tuple[Any, Any]:
+    """Return ``(FrameProcessor, TextFrame)`` or raise a friendly error."""
+    try:
+        from pipecat.frames.frames import TextFrame  # type: ignore
+        from pipecat.processors.frame_processor import FrameProcessor  # type: ignore
+    except ImportError as e:
+        raise RuntimeError(
+            "DialogMachineProcessor requires the pipecat extra: "
+            "`pip install superdialog[pipecat]`"
+        ) from e
+    return FrameProcessor, TextFrame
+
+
+def make_processor(agent: Agent) -> Any:
+    """Return a PipeCat ``FrameProcessor`` bound to ``agent``.
+
+    Accepts any superdialog :class:`Agent` (``DialogMachine``,
+    ``LLMAgent``, ``LangChainAgent``, or a custom implementation).
+
+    PipeCat's processor API has rotated between releases; rather than
+    bake a specific signature into our import graph we synthesise a
+    subclass at call time from whatever ``FrameProcessor`` is installed.
+    """
+    FrameProcessor, TextFrame = _require_pipecat()
+
+    class DialogMachineProcessor(FrameProcessor):  # type: ignore[misc, valid-type]
+        """Concrete processor driving ``agent.turn`` per text frame."""
+
+        def __init__(self) -> None:
+            super().__init__()
+            self._agent = agent
+
+        async def process_frame(
+            self,
+            frame: Any,
+            direction: Any = None,
+        ) -> None:
+            # Defer to parent for upstream/control frames it knows about.
+            parent_process = getattr(super(), "process_frame", None)
+            if parent_process is not None:
+                try:
+                    await parent_process(frame, direction)
+                except TypeError:
+                    await parent_process(frame)
+            if not isinstance(frame, TextFrame):
+                return
+            user_text = getattr(frame, "text", "") or ""
+            if not user_text:
+                return
+            turn = await self._agent.turn(user_text)
+            push = getattr(self, "push_frame", None)
+            if push is None:
+                return
+            try:
+                await push(TextFrame(turn.text), direction)
+            except TypeError:
+                await push(TextFrame(turn.text))
+
+    return DialogMachineProcessor()
+
+
+__all__ = ["make_processor"]

superdialog/adapters/websocket.py

@@ -0,0 +1,200 @@
+"""WebSocket runner for any superdialog :class:`Agent` or :class:`SessionWorker`.
+
+Two modes:
+
+* **Single-tenant** (``WebSocketRunner(agent=...)``) -- one Agent multiplexed
+  across all connections. State is shared; use only for demos / single-user
+  servers.
+* **Multi-tenant** (``WebSocketRunner(worker=...)``) -- session-keyed. Every
+  inbound frame must carry a ``session_id``; the runner acquires it on the
+  bound :class:`SessionWorker` and routes the message through the matching
+  :class:`SessionHandle`. State is isolated per session_id and persisted via
+  whatever ``SessionStore`` the worker is configured with.
+
+Protocol (JSON messages over a single WS connection):
+
+* Client → server::
+
+    # single-tenant mode
+    {"type": "user_text", "text": "..."}
+    {"type": "assist",    "text": "..."}
+    {"type": "reset"}
+
+    # multi-tenant mode (session_id required on every frame)
+    {"type": "user_text", "session_id": "user-42", "text": "..."}
+    {"type": "assist",    "session_id": "user-42", "text": "..."}
+
+* Server → client::
+
+    {"type": "agent_chunk", "text": "...", "done": false}
+    {"type": "agent_chunk", "text": "...", "done": true, "metadata": {...}}
+    {"type": "assist_ack"}
+    {"type": "reset_ack"}
+    {"type": "error", "message": "..."}
+
+Streaming is preferred; for single-shot replies callers can ignore all
+but the final chunk (it carries the full ``metadata``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover
+    from superdialog.agent import Agent
+    from superdialog.session import SessionWorker
+else:
+    Agent = Any
+    SessionWorker = Any
+
+logger = logging.getLogger(__name__)
+
+
+def _require_websockets() -> Any:
+    try:
+        import websockets  # type: ignore
+    except ImportError as e:
+        raise RuntimeError(
+            "WebSocketRunner requires the ws extra: `pip install superdialog[ws]`"
+        ) from e
+    return websockets
+
+
+class WebSocketRunner:
+    """Serve a superdialog :class:`Agent` or :class:`SessionWorker` over WS.
+
+    Exactly one of ``agent`` / ``worker`` must be supplied. Mixing the two
+    constructor forms raises ``ValueError`` at construction time so callers
+    fail fast.
+    """
+
+    def __init__(
+        self,
+        agent: Agent | None = None,
+        agent_id: str = "default",
+        api_key: str | None = None,
+        *,
+        worker: SessionWorker | None = None,
+    ) -> None:
+        if (agent is None) == (worker is None):
+            raise ValueError(
+                "WebSocketRunner requires exactly one of `agent` or `worker`"
+            )
+        self.agent = agent
+        self.worker = worker
+        self.agent_id = agent_id
+        self.api_key = api_key
+
+    # ------------------------------------------------------------------
+    # Message dispatch
+    # ------------------------------------------------------------------
+
+    async def handle_message(self, ws: Any, raw: str) -> None:
+        """Process one inbound JSON frame and stream the response."""
+        try:
+            msg = json.loads(raw)
+        except json.JSONDecodeError:
+            await ws.send(json.dumps({"type": "error", "message": "invalid_json"}))
+            return
+        if self.worker is not None:
+            await self._handle_with_worker(ws, msg)
+        else:
+            await self._handle_with_agent(ws, msg)
+
+    async def _handle_with_agent(self, ws: Any, msg: dict[str, Any]) -> None:
+        """Single-tenant dispatch -- everything routes through ``self.agent``."""
+        kind = msg.get("type")
+        if kind == "user_text":
+            await self._stream_reply(ws, self.agent, msg.get("text", ""))
+        elif kind == "assist":
+            await self._call_assist(ws, self.agent, msg.get("text", ""))
+        elif kind == "reset":
+            await self._call_reset(ws, self.agent)
+        else:
+            await ws.send(
+                json.dumps({"type": "error", "message": f"unknown_type:{kind}"})
+            )
+
+    async def _handle_with_worker(self, ws: Any, msg: dict[str, Any]) -> None:
+        """Multi-tenant dispatch -- every frame must carry ``session_id``."""
+        session_id = msg.get("session_id")
+        if not session_id:
+            await ws.send(
+                json.dumps({"type": "error", "message": "missing_session_id"})
+            )
+            return
+        kind = msg.get("type")
+        async with self.worker.acquire(session_id) as handle:
+            if kind == "user_text":
+                await self._stream_reply(ws, handle, msg.get("text", ""))
+            elif kind == "assist":
+                handle.assist(msg.get("text", ""))
+                await ws.send(json.dumps({"type": "assist_ack"}))
+            elif kind == "reset":
+                # SessionHandle has no reset(); fall back to the underlying agent.
+                await self._call_reset(ws, handle.agent)
+            else:
+                await ws.send(
+                    json.dumps({"type": "error", "message": f"unknown_type:{kind}"})
+                )
+
+    # ------------------------------------------------------------------
+    # Per-target helpers (work against Agent OR SessionHandle)
+    # ------------------------------------------------------------------
+
+    async def _stream_reply(self, ws: Any, target: Any, text: str) -> None:
+        stream = await target.turn(text, stream=True)
+        async for chunk in stream:  # type: ignore[union-attr]
+            frame: dict[str, Any] = {
+                "type": "agent_chunk",
+                "text": chunk.text,
+                "done": chunk.done,
+            }
+            if chunk.done and chunk.turn is not None:
+                frame["metadata"] = chunk.turn.metadata
+            await ws.send(json.dumps(frame))
+
+    async def _call_assist(self, ws: Any, target: Any, text: str) -> None:
+        assist_fn = getattr(target, "assist", None)
+        if assist_fn is None:
+            await ws.send(
+                json.dumps({"type": "error", "message": "assist_unsupported"})
+            )
+            return
+        assist_fn(text)
+        await ws.send(json.dumps({"type": "assist_ack"}))
+
+    async def _call_reset(self, ws: Any, target: Any) -> None:
+        reset_fn = getattr(target, "reset", None)
+        if reset_fn is None:
+            await ws.send(json.dumps({"type": "error", "message": "reset_unsupported"}))
+            return
+        reset_fn()
+        await ws.send(json.dumps({"type": "reset_ack"}))
+
+    # ------------------------------------------------------------------
+    # Connection lifecycle
+    # ------------------------------------------------------------------
+
+    async def _handler(self, ws: Any, *_: Any) -> None:
+        try:
+            async for raw in ws:
+                await self.handle_message(ws, raw)
+        except Exception as exc:  # noqa: BLE001 - protocol-level safety net
+            logger.exception("websocket handler crashed: %s", exc)
+
+    def serve(self, host: str = "0.0.0.0", port: int = 8080) -> None:  # nosec B104
+        """Block on an asyncio event loop serving the WS endpoint."""
+        websockets = _require_websockets()
+
+        async def _main() -> None:
+            async with websockets.serve(self._handler, host, port):
+                await asyncio.Future()
+
+        asyncio.run(_main())
+
+
+__all__ = ["WebSocketRunner"]