soothe-client-python 0.9.4__py3-none-any.whl

soothe_client/__init__.py

@@ -0,0 +1,171 @@
+"""Soothe WebSocket client for soothe-daemon.
+
+Layer 0 transport and session helpers. Layer 1 application mechanics live in
+``soothe_client.appkit``. Shared wire codec and path constants live in
+soothe-sdk (`soothe_sdk.wire`, `soothe_sdk.paths`).
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from soothe_sdk.core.types import VerbosityLevel
+from soothe_sdk.wire.codec import ProtocolError
+
+from soothe_client.errors import (
+    DaemonError,
+    DisconnectCause,
+    ReconnectError,
+    StaleLoopError,
+    disconnect_cause_name,
+)
+from soothe_client.helpers import (
+    check_daemon_status,
+    fetch_config_section,
+    fetch_loop_cards,
+    fetch_loop_history,
+    fetch_loop_messages,
+    fetch_skills_catalog,
+    is_daemon_live,
+    request_daemon_config_reload,
+    request_daemon_shutdown,
+    websocket_url_from_config,
+)
+from soothe_client.intent_hints import (
+    DEFAULT_DELIVERABLE_PHASES,
+    EMBED,
+    IMAGE_TO_TEXT,
+    OCR,
+    TEXT_COMPLETION,
+    validate_loop_input_intent_hint,
+)
+from soothe_client.protocol_params import (
+    AuthParams,
+    AuthRefreshParams,
+    AutopilotSubscribeParams,
+    ConfigGetParams,
+    ConfigReloadParams,
+    CronAddParams,
+    CronCancelParams,
+    CronListParams,
+    CronShowParams,
+    DaemonShutdownParams,
+    DaemonStatusParams,
+    DisconnectParams,
+    InvokeSkillParams,
+    JobCancelParams,
+    JobCreateParams,
+    JobDagParams,
+    JobGuidanceParams,
+    JobPauseParams,
+    JobResumeParams,
+    JobStatusParams,
+    LoopCardsFetchParams,
+    LoopDeleteParams,
+    LoopDetachParams,
+    LoopGetParams,
+    LoopInputParams,
+    LoopListParams,
+    LoopMessagesParams,
+    LoopNewParams,
+    LoopPruneParams,
+    LoopReattachParams,
+    LoopStateGetParams,
+    LoopStateUpdateParams,
+    LoopTreeParams,
+    McpStatusParams,
+    ModelsListParams,
+    RpcCommandParams,
+    SkillsListParams,
+    SlashCommandParams,
+    SubscribeParams,
+)
+from soothe_client.session import (
+    bootstrap_loop_session,
+    connect_websocket_with_retries,
+)
+from soothe_client.websocket import WebSocketClient
+from soothe_client.ws_command_client import (
+    SyncWsCommandClient,
+    WsCommandClient,
+    async_ws_command_client_from_config,
+    ws_command_client_from_config,
+)
+
+try:
+    __version__ = importlib.metadata.version("soothe-client-python")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    "WebSocketClient",
+    "VerbosityLevel",
+    "ProtocolError",
+    "DaemonError",
+    "DisconnectCause",
+    "ReconnectError",
+    "StaleLoopError",
+    "disconnect_cause_name",
+    "WsCommandClient",
+    "SyncWsCommandClient",
+    "ws_command_client_from_config",
+    "async_ws_command_client_from_config",
+    "bootstrap_loop_session",
+    "connect_websocket_with_retries",
+    "websocket_url_from_config",
+    "check_daemon_status",
+    "is_daemon_live",
+    "request_daemon_config_reload",
+    "request_daemon_shutdown",
+    "fetch_skills_catalog",
+    "fetch_config_section",
+    "fetch_loop_history",
+    "fetch_loop_cards",
+    "fetch_loop_messages",
+    "TEXT_COMPLETION",
+    "IMAGE_TO_TEXT",
+    "OCR",
+    "EMBED",
+    "DEFAULT_DELIVERABLE_PHASES",
+    "validate_loop_input_intent_hint",
+    "LoopGetParams",
+    "LoopListParams",
+    "LoopTreeParams",
+    "LoopPruneParams",
+    "LoopDeleteParams",
+    "LoopNewParams",
+    "LoopReattachParams",
+    "LoopInputParams",
+    "LoopMessagesParams",
+    "LoopStateGetParams",
+    "LoopStateUpdateParams",
+    "LoopCardsFetchParams",
+    "LoopDetachParams",
+    "SubscribeParams",
+    "AutopilotSubscribeParams",
+    "JobCreateParams",
+    "JobStatusParams",
+    "JobPauseParams",
+    "JobResumeParams",
+    "JobCancelParams",
+    "JobDagParams",
+    "JobGuidanceParams",
+    "CronAddParams",
+    "CronListParams",
+    "CronShowParams",
+    "CronCancelParams",
+    "DaemonStatusParams",
+    "DaemonShutdownParams",
+    "ConfigGetParams",
+    "ConfigReloadParams",
+    "SkillsListParams",
+    "ModelsListParams",
+    "InvokeSkillParams",
+    "McpStatusParams",
+    "AuthParams",
+    "AuthRefreshParams",
+    "SlashCommandParams",
+    "RpcCommandParams",
+    "DisconnectParams",
+]

soothe_client/appkit/__init__.py

@@ -0,0 +1,138 @@
+"""Reusable application-architecture layer over Layer 0 (RFC-629).
+
+appkit is product-agnostic. Deliverable phases, persistence, and UI copy stay
+in the application (e.g. soothe-cli). Building blocks:
+
+- ``unwrap_next`` / ``is_loop_scoped_event`` — protocol-1 stream helpers
+- ``QueryGate`` — single-flight cancel-before-context gating
+- ``TurnEventPipeline`` — reader / processor / applier concurrency
+- ``DaemonSession`` — dual-socket loop session + ``iter_turn_chunks``
+- ``EventClassifier`` / ``extract_thinking_step`` — deliverable terminal mapping
+- ``SSEBroadcaster`` — drop-on-full SSE-style fan-out
+- ``ConnectionPool`` / ``TurnRunner`` — pooled multi-session turn execution
+- ``SessionStore`` — persistence seam (Protocol)
+"""
+
+from __future__ import annotations
+
+from soothe_client.appkit.attachments import (
+    CompactImageOptions,
+    compact_attachments,
+    compact_image_attachment,
+)
+from soothe_client.appkit.broadcaster import SSEBroadcaster, SSEEvent
+from soothe_client.appkit.chunk_filter import should_drop_stream_chunk_early
+from soothe_client.appkit.classifier import (
+    EVENT_FINAL_REPORT,
+    ChatEventResult,
+    ChatEventTerminal,
+    ClassifierConfig,
+    EventClassifier,
+)
+from soothe_client.appkit.daemon_session import DEFAULT_POST_IDLE_DRAIN_S, DaemonSession
+from soothe_client.appkit.events import is_loop_scoped_event, unwrap_next
+from soothe_client.appkit.managed_client import (
+    BootstrapFunc,
+    ClientFactory,
+    ManagedClient,
+    WebSocketManagedClient,
+    default_bootstrap_func,
+    default_client_factory,
+)
+from soothe_client.appkit.observability import TurnEventStats
+from soothe_client.appkit.pool import (
+    ConnectionPool,
+    ErrPoolExhausted,
+    PoolConfig,
+    PooledConn,
+    default_pool_config,
+)
+from soothe_client.appkit.query_gate import ErrQueryBusy, QueryGate
+from soothe_client.appkit.session_store import SessionEntry, SessionMessage, SessionStore
+from soothe_client.appkit.thinking_step import (
+    DEFAULT_THINKING_STEP_EVENTS,
+    extract_thinking_step,
+)
+from soothe_client.appkit.turn import (
+    PRIORITY_CRITICAL,
+    PRIORITY_HIGH,
+    PRIORITY_LOW,
+    PRIORITY_NORMAL,
+    TurnApplyBatcher,
+    TurnEventPipeline,
+    run_turn_pipeline,
+)
+from soothe_client.appkit.turn_runner import (
+    STREAM_CLOSE_FAIL,
+    STREAM_CLOSE_SOFT_COMPLETE,
+    Attachment,
+    ErrIdleTimeout,
+    ErrQueryTimeout,
+    InputOpts,
+    OnComplete,
+    OnError,
+    StreamClosePolicy,
+    TimeoutPolicy,
+    TurnConfig,
+    TurnRunner,
+    idle_timeout_for_turn,
+    input_message_for_loop,
+)
+
+__all__ = [
+    "DEFAULT_POST_IDLE_DRAIN_S",
+    "DEFAULT_THINKING_STEP_EVENTS",
+    "STREAM_CLOSE_FAIL",
+    "STREAM_CLOSE_SOFT_COMPLETE",
+    "Attachment",
+    "BootstrapFunc",
+    "ClientFactory",
+    "CompactImageOptions",
+    "ConnectionPool",
+    "DaemonSession",
+    "EVENT_FINAL_REPORT",
+    "ErrIdleTimeout",
+    "ErrPoolExhausted",
+    "ErrQueryBusy",
+    "ErrQueryTimeout",
+    "ChatEventResult",
+    "ChatEventTerminal",
+    "ClassifierConfig",
+    "EventClassifier",
+    "InputOpts",
+    "ManagedClient",
+    "OnComplete",
+    "OnError",
+    "PRIORITY_CRITICAL",
+    "PRIORITY_HIGH",
+    "PRIORITY_LOW",
+    "PRIORITY_NORMAL",
+    "PoolConfig",
+    "PooledConn",
+    "QueryGate",
+    "SSEBroadcaster",
+    "SSEEvent",
+    "SessionEntry",
+    "SessionMessage",
+    "SessionStore",
+    "StreamClosePolicy",
+    "TimeoutPolicy",
+    "TurnApplyBatcher",
+    "TurnConfig",
+    "TurnEventPipeline",
+    "TurnEventStats",
+    "TurnRunner",
+    "WebSocketManagedClient",
+    "compact_attachments",
+    "compact_image_attachment",
+    "default_bootstrap_func",
+    "default_client_factory",
+    "default_pool_config",
+    "extract_thinking_step",
+    "idle_timeout_for_turn",
+    "input_message_for_loop",
+    "is_loop_scoped_event",
+    "run_turn_pipeline",
+    "should_drop_stream_chunk_early",
+    "unwrap_next",
+]

soothe_client/appkit/attachments.py

@@ -0,0 +1,118 @@
+"""Image attachment compaction for appkit (RFC-629 Layer 1).
+
+Downscales ``image/*`` payloads when either dimension exceeds a max size.
+Non-images and decode failures pass through unchanged. Requires Pillow when
+compaction is requested; without Pillow, inputs are returned unchanged.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class CompactImageOptions:
+    """Controls ``compact_image_attachment``. Zero / unset fields use defaults."""
+
+    max_dim: int = 768
+    jpeg_quality: int = 85
+
+
+def _compact_defaults(opts: CompactImageOptions | None) -> tuple[int, int]:
+    max_dim, quality = 768, 85
+    if opts is None:
+        return max_dim, quality
+    if opts.max_dim > 0:
+        max_dim = opts.max_dim
+    if opts.jpeg_quality > 0:
+        quality = opts.jpeg_quality
+    return max_dim, quality
+
+
+def compact_image_attachment(
+    mime_type: str,
+    data_b64: str,
+    opts: CompactImageOptions | None = None,
+) -> tuple[str, str]:
+    """Downscale an image attachment when either dimension exceeds ``max_dim``.
+
+    Args:
+        mime_type: Attachment MIME type (e.g. ``image/png``).
+        data_b64: Base64-encoded image bytes.
+        opts: Optional size / JPEG quality overrides.
+
+    Returns:
+        ``(out_mime, out_b64)``. Non-images and failures return inputs unchanged.
+    """
+    if not data_b64 or not mime_type.startswith("image/"):
+        return mime_type, data_b64
+    try:
+        from PIL import Image
+    except ImportError:
+        return mime_type, data_b64
+
+    try:
+        raw = base64.b64decode(data_b64, validate=False)
+    except Exception:
+        return mime_type, data_b64
+    if not raw:
+        return mime_type, data_b64
+
+    try:
+        with Image.open(io.BytesIO(raw)) as img:
+            img.load()
+            w, h = img.size
+            max_dim, quality = _compact_defaults(opts)
+            if w <= max_dim and h <= max_dim:
+                return mime_type, data_b64
+            if w >= h:
+                nw = max_dim if w > max_dim else w
+                nh = max(1, h * nw // w) if w > max_dim else h
+            else:
+                nh = max_dim if h > max_dim else h
+                nw = max(1, w * nh // h) if h > max_dim else w
+            resized = img.resize((nw, nh), Image.Resampling.LANCZOS)
+            buf = io.BytesIO()
+            out_mime = mime_type
+            if mime_type == "image/png":
+                if resized.mode not in ("RGB", "RGBA", "L", "P"):
+                    resized = resized.convert("RGBA")
+                resized.save(buf, format="PNG")
+            else:
+                if resized.mode != "RGB":
+                    resized = resized.convert("RGB")
+                resized.save(buf, format="JPEG", quality=quality)
+                out_mime = "image/jpeg"
+            return out_mime, base64.b64encode(buf.getvalue()).decode("ascii")
+    except Exception:
+        return mime_type, data_b64
+
+
+def compact_attachments(
+    atts: list[dict[str, Any]] | None,
+    opts: CompactImageOptions | None = None,
+) -> list[dict[str, Any]]:
+    """Apply ``compact_image_attachment`` to each ``mime_type`` + ``data`` map."""
+    if not atts:
+        return atts or []
+    out: list[dict[str, Any]] = []
+    for att in atts:
+        cp = dict(att)
+        mime = cp.get("mime_type")
+        data = cp.get("data")
+        if isinstance(mime, str) and isinstance(data, str) and mime and data:
+            out_mime, out_data = compact_image_attachment(mime, data, opts)
+            cp["mime_type"] = out_mime
+            cp["data"] = out_data
+        out.append(cp)
+    return out
+
+
+__all__ = [
+    "CompactImageOptions",
+    "compact_attachments",
+    "compact_image_attachment",
+]

soothe_client/appkit/broadcaster.py

@@ -0,0 +1,116 @@
+"""SSE-style pub/sub fan-out for appkit (RFC-629 Layer 1).
+
+Generic, string-keyed pub/sub for SSE-style event delivery. Slow consumers do
+not stall the broadcaster: each subscriber has a bounded queue and overflowing
+events are dropped (drop-on-full).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+SUBSCRIBER_QUEUE_CAP = 100
+
+
+@dataclass(frozen=True, slots=True)
+class SSEEvent:
+    """One Server-Sent Event payload. The ``type`` vocabulary is app-defined."""
+
+    type: str
+    data: Any = None
+
+
+@dataclass
+class _Subscriber:
+    queue: asyncio.Queue[SSEEvent | None] = field(
+        default_factory=lambda: asyncio.Queue(maxsize=SUBSCRIBER_QUEUE_CAP)
+    )
+    closed: bool = False
+
+
+class SSEBroadcaster:
+    """Fan events out to all subscribers for a session id (non-blocking)."""
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, dict[str, _Subscriber]] = {}
+
+    def subscribe(self, session_id: str) -> tuple[AsyncIterator[SSEEvent], str]:
+        """Register a subscriber and return ``(async iterator, subscription id)``.
+
+        Unsubscribe via ``unsubscribe`` or ``close``.
+        """
+        sub_id = str(uuid4())
+        sub = _Subscriber()
+        subs = self._subscribers.get(session_id)
+        if subs is None:
+            subs = {}
+            self._subscribers[session_id] = subs
+        subs[sub_id] = sub
+        return _iterate(sub), sub_id
+
+    def unsubscribe(self, session_id: str, sub_id: str) -> None:
+        """Remove a subscriber by id and close its iterator. Safe if unknown."""
+        subs = self._subscribers.get(session_id)
+        if not subs:
+            return
+        sub = subs.pop(sub_id, None)
+        if sub is None:
+            return
+        self._close_sub(sub)
+        if not subs:
+            del self._subscribers[session_id]
+
+    def broadcast(self, session_id: str, event: SSEEvent) -> None:
+        """Send an event to all subscribers (drop-on-full, non-blocking)."""
+        subs = self._subscribers.get(session_id)
+        if not subs:
+            return
+        for sub in subs.values():
+            if sub.closed:
+                continue
+            try:
+                sub.queue.put_nowait(event)
+            except asyncio.QueueFull:
+                pass  # drop-on-full
+
+    def close(self, session_id: str) -> None:
+        """Close all subscribers for a session id and remove the entry."""
+        subs = self._subscribers.pop(session_id, None)
+        if not subs:
+            return
+        for sub in subs.values():
+            self._close_sub(sub)
+
+    def close_all(self) -> None:
+        """Close every subscriber channel across all sessions."""
+        for session_id in list(self._subscribers):
+            self.close(session_id)
+
+    @staticmethod
+    def _close_sub(sub: _Subscriber) -> None:
+        if sub.closed:
+            return
+        sub.closed = True
+        try:
+            sub.queue.put_nowait(None)
+        except asyncio.QueueFull:
+            with contextlib.suppress(asyncio.QueueEmpty):
+                sub.queue.get_nowait()
+            with contextlib.suppress(asyncio.QueueFull):
+                sub.queue.put_nowait(None)
+
+
+async def _iterate(sub: _Subscriber) -> AsyncIterator[SSEEvent]:
+    while True:
+        item = await sub.queue.get()
+        if item is None:
+            return
+        yield item
+
+
+__all__ = ["SSEEvent", "SSEBroadcaster", "SUBSCRIBER_QUEUE_CAP"]

soothe_client/appkit/chunk_filter.py

@@ -0,0 +1,99 @@
+"""Early filters for daemon stream chunks (wire / dict-shaped payloads).
+
+CLI callers that also see LangChain message objects should pass a richer filter
+callback (e.g. ``soothe_cli.runtime.wire.chunk_filter.should_drop_stream_chunk_early``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_MSG_PAIR_LEN = 2
+
+
+def updates_chunk_is_noop(data: Any) -> bool:
+    """True when an ``updates`` chunk carries no LangGraph interrupt."""
+    if not isinstance(data, dict):
+        return True
+    return "__interrupt__" not in data
+
+
+def _wire_body(msg: dict[str, Any]) -> dict[str, Any]:
+    for key in ("kwargs", "data"):
+        nested = msg.get(key)
+        if isinstance(nested, dict):
+            return nested
+    return msg
+
+
+def _dict_has_tool_invocation(msg: dict[str, Any]) -> bool:
+    body = _wire_body(msg)
+    if body.get("tool_calls") or body.get("tool_call_chunks"):
+        return True
+    for key in ("content", "content_blocks"):
+        raw = body.get(key)
+        if isinstance(raw, list):
+            for item in raw:
+                if isinstance(item, dict) and item.get("type") in {
+                    "tool_call",
+                    "tool_call_chunk",
+                    "tool_use",
+                }:
+                    return True
+    return False
+
+
+def _plain_text(msg: dict[str, Any]) -> str:
+    body = _wire_body(msg)
+    content = body.get("content", msg.get("content"))
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict):
+                text = block.get("text")
+                if isinstance(text, str):
+                    parts.append(text)
+        return "".join(parts)
+    return ""
+
+
+def message_chunk_is_non_actionable(data: Any) -> bool:
+    """True when a wire ``messages`` pair has no tool, text, or loop phase payload."""
+    if not isinstance(data, (list, tuple)) or len(data) != _MSG_PAIR_LEN:
+        return False
+    msg = data[0]
+    if msg is None:
+        return True
+    if not isinstance(msg, dict):
+        # Non-dict messages (e.g. LangChain objects) are not filtered here.
+        return False
+    body = _wire_body(msg)
+    raw = str(body.get("type") or msg.get("type") or "")
+    if raw in ("tool", "ToolMessage") or raw.endswith("ToolMessage"):
+        return False
+    if _dict_has_tool_invocation(msg):
+        return False
+    if body.get("phase") or msg.get("phase"):
+        return False
+    return not _plain_text(msg).strip()
+
+
+def should_drop_stream_chunk_early(namespace: tuple[Any, ...], mode: str, data: Any) -> bool:
+    """Return True when the chunk can be skipped before the turn pipeline."""
+    del namespace  # reserved for product filters
+    if mode == "updates":
+        return updates_chunk_is_noop(data)
+    if mode == "messages":
+        return message_chunk_is_non_actionable(data)
+    return False
+
+
+__all__ = [
+    "message_chunk_is_non_actionable",
+    "should_drop_stream_chunk_early",
+    "updates_chunk_is_noop",
+]