soothe-client-python 0.9.8__tar.gz → 0.9.10__tar.gz

{soothe_client_python-0.9.8 → soothe_client_python-0.9.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soothe-client-python
-Version: 0.9.8
+Version: 0.9.10
 Summary: WebSocket client + appkit for soothe-daemon (Python)
 Project-URL: Homepage, https://github.com/mirasoth/soothe-client-python
 Project-URL: Documentation, https://soothe.readthedocs.io
@@ -69,10 +69,13 @@ More patterns: [`examples/`](examples/) (hello → streaming → multi-turn →
 
 | Need | Use |
 |------|-----|
-| One conversation, stream replies | `DaemonSession` |
+| One conversation, stream replies | `DaemonSession` (`soothe_client.appkit`) |
+| Jobs / cron (async) | `AsyncCommandClient` (alias of `WsCommandClient`) |
+| Jobs / cron (scripts / sync) | `CommandClient` (alias of `SyncWsCommandClient`) |
 | Raw WebSocket / custom RPCs | `WebSocketClient` |
 | Many users / HTTP backend | `ConnectionPool` + `TurnRunner` |
-| Jobs / autopilot / cron | `WsCommandClient` |
+
+Wire request param models live in `soothe_client.protocol_params` (not at package root).
 
 ## Develop
 

{soothe_client_python-0.9.8 → soothe_client_python-0.9.10}/README.md

@@ -36,10 +36,13 @@ More patterns: [`examples/`](examples/) (hello → streaming → multi-turn →
 
 | Need | Use |
 |------|-----|
-| One conversation, stream replies | `DaemonSession` |
+| One conversation, stream replies | `DaemonSession` (`soothe_client.appkit`) |
+| Jobs / cron (async) | `AsyncCommandClient` (alias of `WsCommandClient`) |
+| Jobs / cron (scripts / sync) | `CommandClient` (alias of `SyncWsCommandClient`) |
 | Raw WebSocket / custom RPCs | `WebSocketClient` |
 | Many users / HTTP backend | `ConnectionPool` + `TurnRunner` |
-| Jobs / autopilot / cron | `WsCommandClient` |
+
+Wire request param models live in `soothe_client.protocol_params` (not at package root).
 
 ## Develop
 

soothe_client_python-0.9.10/src/soothe_client/__init__.py

@@ -0,0 +1,189 @@
+"""Soothe WebSocket client for talking to a running soothe-daemon.
+
+Public surface (community apps)::
+
+    from soothe_client import WebSocketClient, is_daemon_live
+    from soothe_client.appkit import DaemonSession
+    from soothe_client import AsyncCommandClient, CommandClient  # preferred aliases
+
+Advanced wire validation lives in ``soothe_client.protocol_params``.
+Higher-level session / multi-user helpers live in ``soothe_client.appkit``.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import warnings
+from typing import Any
+
+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,
+    connected_websocket,
+    fetch_config_section,
+    fetch_loop_cards,
+    fetch_loop_history,
+    fetch_loop_messages,
+    fetch_skills_catalog,
+    is_daemon_live,
+    protocol1_rpc,
+    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.session import (
+    bootstrap_loop_session,
+    connect_websocket_with_retries,
+)
+from soothe_client.websocket import WebSocketClient
+from soothe_client.ws_command_client import (
+    AsyncCommandClient,
+    CommandClient,
+    SyncWsCommandClient,
+    WsCommandClient,
+    async_command_client_from_config,
+    async_ws_command_client_from_config,
+    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"
+
+# Legacy ``*Params`` names formerly re-exported at package root.
+_LEGACY_PARAM_NAMES = frozenset(
+    {
+        "AuthParams",
+        "AuthRefreshParams",
+        "AutopilotCancelAllParams",
+        "AutopilotCancelGoalParams",
+        "AutopilotDreamParams",
+        "AutopilotGetGoalParams",
+        "AutopilotGetJobParams",
+        "AutopilotListGoalsParams",
+        "AutopilotListJobsParams",
+        "AutopilotResumeParams",
+        "AutopilotStatusParams",
+        "AutopilotSubmitParams",
+        "AutopilotSubscribeParams",
+        "AutopilotWakeParams",
+        "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",
+    }
+)
+
+__all__ = [
+    "__version__",
+    # Transport
+    "WebSocketClient",
+    "ProtocolError",
+    # Errors
+    "DaemonError",
+    "DisconnectCause",
+    "ReconnectError",
+    "StaleLoopError",
+    "disconnect_cause_name",
+    # Command clients (canonical + preferred aliases)
+    "WsCommandClient",
+    "SyncWsCommandClient",
+    "AsyncCommandClient",
+    "CommandClient",
+    "ws_command_client_from_config",
+    "async_ws_command_client_from_config",
+    "command_client_from_config",
+    "async_command_client_from_config",
+    # Session bootstrap
+    "bootstrap_loop_session",
+    "connect_websocket_with_retries",
+    # Helpers
+    "websocket_url_from_config",
+    "connected_websocket",
+    "protocol1_rpc",
+    "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",
+    # Intent hints
+    "TEXT_COMPLETION",
+    "IMAGE_TO_TEXT",
+    "OCR",
+    "EMBED",
+    "DEFAULT_DELIVERABLE_PHASES",
+    "validate_loop_input_intent_hint",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load legacy ``*Params`` with a deprecation warning.
+
+    Prefer ``from soothe_client.protocol_params import LoopInputParams``.
+    """
+    if name in _LEGACY_PARAM_NAMES:
+        warnings.warn(
+            f"Importing {name!r} from soothe_client is deprecated; "
+            f"use soothe_client.protocol_params.{name} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from soothe_client import protocol_params as _params
+
+        return getattr(_params, name)
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

{soothe_client_python-0.9.8 → soothe_client_python-0.9.10}/src/soothe_client/appkit/__init__.py

@@ -1,13 +1,16 @@
 """Application helpers built on WebSocketClient.
 
-Product-agnostic building blocks for agent UIs and backends:
+Primary building blocks for agent UIs and backends:
 
 - ``DaemonSession`` — dual-socket loop session + streamed turns
 - ``ConnectionPool`` / ``TurnRunner`` — multi-session turn execution
 - ``QueryGate`` — one-in-flight query per session
-- ``EventClassifier`` / ``extract_thinking_step`` — stream → deliverable mapping
+- ``EventClassifier`` — stream → deliverable mapping
 - ``SSEBroadcaster`` — drop-on-full fan-out to subscribers
 - ``SessionStore`` — persistence seam (Protocol)
+
+Advanced stream/pipeline plumbing lives in submodules
+(``events``, ``chunk_filter``, ``turn``, ``managed_client``).
 """
 
 from __future__ import annotations
@@ -18,7 +21,6 @@ from soothe_client.appkit.attachments import (
     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,
@@ -26,17 +28,7 @@ from soothe_client.appkit.classifier import (
     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.daemon_session import DaemonSession
 from soothe_client.appkit.pool import (
     ConnectionPool,
     ErrPoolExhausted,
@@ -50,15 +42,6 @@ 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,
@@ -77,13 +60,13 @@ from soothe_client.appkit.turn_runner import (
 )
 
 __all__ = [
-    "DEFAULT_POST_IDLE_DRAIN_S",
     "DEFAULT_THINKING_STEP_EVENTS",
     "STREAM_CLOSE_FAIL",
     "STREAM_CLOSE_SOFT_COMPLETE",
     "Attachment",
-    "BootstrapFunc",
-    "ClientFactory",
+    "ChatEventResult",
+    "ChatEventTerminal",
+    "ClassifierConfig",
     "CompactImageOptions",
     "ConnectionPool",
     "DaemonSession",
@@ -92,18 +75,10 @@ __all__ = [
     "ErrPoolExhausted",
     "ErrQueryBusy",
     "ErrQueryTimeout",
-    "ChatEventResult",
-    "ChatEventTerminal",
-    "ClassifierConfig",
     "EventClassifier",
     "InputOpts",
-    "ManagedClient",
     "OnComplete",
     "OnError",
-    "PRIORITY_CRITICAL",
-    "PRIORITY_HIGH",
-    "PRIORITY_LOW",
-    "PRIORITY_NORMAL",
     "PoolConfig",
     "PooledConn",
     "QueryGate",
@@ -114,22 +89,12 @@ __all__ = [
     "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_python-0.9.8 → soothe_client_python-0.9.10}/src/soothe_client/appkit/daemon_session.py

@@ -23,7 +23,7 @@ from soothe_client.stream_terminal import (
     is_turn_end_custom_data,
     is_turn_progress_chunk,
 )
-from soothe_client.turn_boundary import frame_seq, frame_turn_id
+from soothe_client.turn_boundary import frame_seq, frame_turn_id, parse_turn_generation
 from soothe_client.websocket import WebSocketClient
 
 logger = logging.getLogger(__name__)
@@ -37,7 +37,21 @@ StreamDeliveryResolver = Callable[[], str]
 
 
 class DaemonSession:
-    """Daemon-backed loop session with stream + RPC sockets."""
+    """One conversation with a daemon loop: connect, send turns, stream chunks.
+
+    Owns a subscribed stream WebSocket plus an RPC sidecar so metadata calls
+    do not starve loop events. Typical usage::
+
+        session = DaemonSession("ws://127.0.0.1:8765")
+        await session.connect()
+        await session.send_turn("Hello")
+        async for _ns, mode, data in session.iter_turn_chunks():
+            ...
+        await session.close()
+
+    Advanced: ``early_drop_fn`` / ``stats_factory`` customize stream filtering
+    and metrics for product UIs; most apps leave the defaults.
+    """
 
     def __init__(
         self,
@@ -67,7 +81,7 @@ class DaemonSession:
         self.last_turn_end_state: str | None = None
         self.last_turn_cancellation_seen: bool = False
         self.last_turn_error_message: str | None = None
-        # IG-659: last completed turn's seq floor (drop stale prior-turn frames).
+        # Last completed turn's seq floor (drop stale prior-turn frames).
         self._last_turn_end_seq: int = 0
         self._expected_turn_id: str | None = None
 
@@ -108,7 +122,11 @@ class DaemonSession:
         )
 
     async def connect(self, *, resume_loop_id: str | None = None) -> dict[str, Any]:
-        """Connect and bootstrap a daemon loop session."""
+        """Open the stream socket and bootstrap (or resume) a loop session.
+
+        Returns:
+            Status event from the daemon (includes ``loop_id`` on success).
+        """
         await connect_websocket_with_retries(self._client)
         return await self._bootstrap_loop(resume_loop_id=resume_loop_id)
 
@@ -182,7 +200,7 @@ class DaemonSession:
         await self._bootstrap_loop(resume_loop_id=resume_loop_id)
 
     async def close(self, *, handshake_timeout: float = 2.0) -> None:
-        """Close stream and RPC sockets (idempotent)."""
+        """Close stream and RPC sockets. Safe to call more than once."""
         if self._closed:
             return
         self._closed = True
@@ -219,7 +237,11 @@ class DaemonSession:
         clarification_answers: list[str] | None = None,
         intent_hint: str | None = None,
     ) -> None:
-        """Send a new user turn to the daemon."""
+        """Send a user message on the active loop (start of a turn).
+
+        Call ``iter_turn_chunks`` afterward to consume the streamed reply.
+        Requires ``connect()`` (or another bootstrap) first.
+        """
         if not self._loop_id:
             raise RuntimeError("No active loop session")
         await self._client.send_input(
@@ -303,13 +325,15 @@ class DaemonSession:
         *,
         max_wait_s: float | None = None,
     ) -> AsyncIterator[tuple[tuple[Any, ...], str, Any]]:
-        """Yield ``(namespace, mode, data)`` chunks for the active daemon turn.
+        """Yield ``(namespace, mode, data)`` stream chunks until the turn ends.
+
+        Handles idle timeout, post-idle drain, and turn boundary filtering.
+        Call after ``send_turn``.
 
         Args:
             max_wait_s: Optional absolute deadline for the whole turn. When set,
                 raises ``TimeoutError`` if the daemon never emits a turn-end
-                signal in time (idle after payload, stopped, stream.end, or
-                strange_loop.completed).
+                signal in time.
         """
         self.turn_event_stats = self._new_turn_stats()
         self.last_turn_end_state = None
@@ -392,13 +416,19 @@ class DaemonSession:
                     if ev_seq is not None and last_end_seq > 0 and ev_seq <= last_end_seq:
                         continue
 
-                    # IG-659 phases 1–2: drop mismatched turn_id once bound.
+                    # Drop mismatched turn_id once bound — except status=running,
+                    # which may rebind to a newer generation (pre-admit early
+                    # running can briefly carry a stale or empty turn_id).
                     ev_turn_id = frame_turn_id(event)
+                    is_running_status = (
+                        event_type == "status" and str(event.get("state") or "") == "running"
+                    )
                     if (
                         expected_turn_id
                         and ev_turn_id
                         and ev_turn_id != expected_turn_id
                         and event_type in {"event", "status"}
+                        and not is_running_status
                     ):
                         logger.debug(
                             "Ignoring mismatched turn_id frame type=%s got=%s expected=%s",
@@ -426,8 +456,18 @@ class DaemonSession:
                             progress_seen = True
                             status_turn = frame_turn_id(event)
                             if status_turn:
-                                expected_turn_id = status_turn
-                                self._expected_turn_id = status_turn
+                                new_gen = parse_turn_generation(status_turn)
+                                old_gen = parse_turn_generation(expected_turn_id)
+                                if expected_turn_id is None or (
+                                    new_gen is not None and (old_gen is None or new_gen >= old_gen)
+                                ):
+                                    if expected_turn_id and status_turn != expected_turn_id:
+                                        # Successor turn admitted while this reader
+                                        # still held a stale/early binding.
+                                        stream_payload_seen = False
+                                        turn_progress_seen = False
+                                    expected_turn_id = status_turn
+                                    self._expected_turn_id = status_turn
                         elif query_started and state == "stopped":
                             self.last_turn_end_state = state
                             if ev_seq is not None:

{soothe_client_python-0.9.8 → soothe_client_python-0.9.10}/src/soothe_client/helpers.py

@@ -1,4 +1,8 @@
-"""WebSocket helper functions for daemon communication."""
+"""Small WebSocket helpers for CLI and scripts (status, fetch, one-shot RPC).
+
+For interactive turns use ``DaemonSession``. For jobs/cron use
+``WsCommandClient`` / ``CommandClient``.
+"""
 
 from __future__ import annotations
 

{soothe_client_python-0.9.8 → soothe_client_python-0.9.10}/src/soothe_client/protocol_params.py

@@ -32,6 +32,7 @@ __all__ = [
     "AutopilotListGoalsParams",
     "AutopilotGetGoalParams",
     "AutopilotCancelGoalParams",
+    "AutopilotCancelAllParams",
     "AutopilotWakeParams",
     "AutopilotDreamParams",
     "AutopilotResumeParams",
@@ -363,6 +364,10 @@ class AutopilotCancelGoalParams(ParamsBase):
     goal_id: str = Field(..., min_length=1)
 
 
+class AutopilotCancelAllParams(EmptyParams):
+    """Params for ``method=autopilot_cancel_all`` — no required fields."""
+
+
 class AutopilotWakeParams(EmptyParams):
     """Params for ``method=autopilot_wake`` — no required fields."""
 

{soothe_client_python-0.9.8 → soothe_client_python-0.9.10}/src/soothe_client/session.py

@@ -1,4 +1,8 @@
-"""Shared WebSocket session bootstrap for CLI headless and TUI."""
+"""Session bootstrap helpers for CLI, TUI, and appkit.
+
+Prefer ``DaemonSession`` for application code. These helpers are the lower-level
+connect + loop-subscribe steps used when you own the ``WebSocketClient``.
+"""
 
 from __future__ import annotations
 
@@ -22,14 +26,7 @@ _LEGACY_LOOP_AUTOPILOT_MODE = "solo"
 
 
 async def connect_websocket_with_retries(client: Any) -> None:
-    """Connect to the daemon with bounded retries for cold-start races.
-
-    Args:
-        client: WebSocketClient instance.
-
-    Raises:
-        ConnectionError: If connection fails after all retries.
-    """
+    """Connect a ``WebSocketClient`` with retries (daemon cold-start safe)."""
     last_error: OSError | ConnectionError | TimeoutError | None = None
     for attempt in range(_CONNECT_RETRY_COUNT):
         try:

{soothe_client_python-0.9.8 → soothe_client_python-0.9.10}/src/soothe_client/stream_terminal.py

@@ -1,7 +1,7 @@
-"""Shared stream/turn terminal frame helpers for WebSocket and DaemonSession.
+"""Internal stream/turn terminal frame helpers.
 
-Keeps peel-at-turn-start and turn-end detection on one vocabulary so leftover
-prior-goal terminals cannot blank the next TUI query.
+Used by ``WebSocketClient`` and ``DaemonSession`` so leftover prior-turn
+terminals cannot blank the next query. Not part of the community public API.
 """
 
 from __future__ import annotations

{soothe_client_python-0.9.8 → soothe_client_python-0.9.10}/src/soothe_client/turn_boundary.py

@@ -1,7 +1,8 @@
-"""Turn / stream boundary helpers (IG-659).
+"""Internal turn / stream boundary helpers.
 
-``turn_id`` correlates a user turn across status, events, and terminals.
-``seq`` is a daemon-assigned monotonic counter per loop for drop-stale filtering.
+Used by ``DaemonSession`` and ``WebSocketClient`` for ``turn_id`` / ``seq``
+filtering. Not part of the community public API — import only if you are
+extending stream handling.
 """
 
 from __future__ import annotations
@@ -18,6 +19,19 @@ def format_turn_id(loop_id: str, generation: int) -> str:
     return f"{lid}:{gen}"
 
 
+def parse_turn_generation(turn_id: str | None) -> int | None:
+    """Extract generation int from ``turn_id``, or None if malformed."""
+    raw = str(turn_id or "").strip()
+    if not raw or ":" not in raw:
+        return None
+    suffix = raw.rsplit(":", 1)[-1]
+    try:
+        gen = int(suffix)
+    except ValueError:
+        return None
+    return gen if gen > 0 else None
+
+
 def frame_turn_id(frame: dict[str, Any] | None) -> str | None:
     """Return ``turn_id`` from a status/event frame or nested custom data."""
     if not isinstance(frame, dict):
@@ -51,4 +65,5 @@ __all__ = [
     "format_turn_id",
     "frame_seq",
     "frame_turn_id",
+    "parse_turn_generation",
 ]