soothe-client-python 0.9.4__tar.gz → 0.9.6__tar.gz

soothe_client_python-0.9.6/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: soothe-client-python
+Version: 0.9.6
+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
+Project-URL: Repository, https://github.com/mirasoth/soothe-client-python
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,client,soothe,websocket
+Classifier: Development Status :: 4 - Beta
+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
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.11
+Requires-Dist: pillow<12.0.0,>=10.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: soothe-sdk<1.0.0,>=0.8.1
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# soothe-client-python
+
+Talk to a running **soothe-daemon** over WebSocket — send prompts, stream agent
+turns, run jobs.
+
+```bash
+pip install soothe-client-python
+```
+
+Requires a local daemon (default `ws://127.0.0.1:8765`).
+
+## Quick start
+
+```python
+import asyncio
+from soothe_client.appkit import DaemonSession
+
+async def main() -> None:
+    session = DaemonSession("ws://127.0.0.1:8765")
+    await session.connect()
+    await session.send_turn("Summarize this in one sentence: agents need tools.")
+    async for _namespace, mode, data in session.iter_turn_chunks():
+        if mode == "custom" and isinstance(data, dict):
+            text = data.get("content") or data.get("text")
+            if text:
+                print(text, end="", flush=True)
+    print()
+    await session.close()
+
+asyncio.run(main())
+```
+
+More patterns: [`examples/`](examples/) (hello → streaming → multi-turn → pool → jobs).
+
+## What you get
+
+| Need | Use |
+|------|-----|
+| One conversation, stream replies | `DaemonSession` |
+| Raw WebSocket / custom RPCs | `WebSocketClient` |
+| Many users / HTTP backend | `ConnectionPool` + `TurnRunner` |
+| Jobs / autopilot / cron | `WsCommandClient` |
+
+## Develop
+
+```bash
+make sync-dev
+make check                 # lint + unit tests
+make test-examples-offline # offline appkit examples
+make test-examples         # live 01–06 (needs soothed)
+make test-integration      # live integration suite (needs soothed)
+```

soothe_client_python-0.9.6/README.md

@@ -0,0 +1,52 @@
+# soothe-client-python
+
+Talk to a running **soothe-daemon** over WebSocket — send prompts, stream agent
+turns, run jobs.
+
+```bash
+pip install soothe-client-python
+```
+
+Requires a local daemon (default `ws://127.0.0.1:8765`).
+
+## Quick start
+
+```python
+import asyncio
+from soothe_client.appkit import DaemonSession
+
+async def main() -> None:
+    session = DaemonSession("ws://127.0.0.1:8765")
+    await session.connect()
+    await session.send_turn("Summarize this in one sentence: agents need tools.")
+    async for _namespace, mode, data in session.iter_turn_chunks():
+        if mode == "custom" and isinstance(data, dict):
+            text = data.get("content") or data.get("text")
+            if text:
+                print(text, end="", flush=True)
+    print()
+    await session.close()
+
+asyncio.run(main())
+```
+
+More patterns: [`examples/`](examples/) (hello → streaming → multi-turn → pool → jobs).
+
+## What you get
+
+| Need | Use |
+|------|-----|
+| One conversation, stream replies | `DaemonSession` |
+| Raw WebSocket / custom RPCs | `WebSocketClient` |
+| Many users / HTTP backend | `ConnectionPool` + `TurnRunner` |
+| Jobs / autopilot / cron | `WsCommandClient` |
+
+## Develop
+
+```bash
+make sync-dev
+make check                 # lint + unit tests
+make test-examples-offline # offline appkit examples
+make test-examples         # live 01–06 (needs soothed)
+make test-integration      # live integration suite (needs soothed)
+```

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/pyproject.toml

@@ -23,15 +23,13 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "soothe-sdk>=0.5.25,<1.0.0",
+    "soothe-sdk>=0.8.1,<1.0.0",
     "pydantic>=2.0.0,<3.0.0",
     "websockets>=12.0",
+    "pillow>=10.0.0,<12.0.0",
 ]
 
 [project.optional-dependencies]
-image = [
-    "pillow>=10.0.0",
-]
 dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=1.3.0",
@@ -79,5 +77,8 @@ disallow_untyped_defs = true
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-testpaths = ["tests", "examples"]
+testpaths = ["tests/unit", "examples/appkit"]
 addopts = "--import-mode=importlib"
+markers = [
+    "integration: live soothe-daemon tests (skipped when unreachable)",
+]

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/__init__.py

@@ -1,8 +1,7 @@
-"""Soothe WebSocket client for soothe-daemon.
+"""Soothe WebSocket client for talking to a running 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`).
+Transport helpers (connect, loops, RPCs) live here. Higher-level session
+and multi-user turn tools live in ``soothe_client.appkit``.
 """
 
 from __future__ import annotations
@@ -21,12 +20,14 @@ from soothe_client.errors import (
 )
 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,
@@ -42,7 +43,17 @@ from soothe_client.intent_hints import (
 from soothe_client.protocol_params import (
     AuthParams,
     AuthRefreshParams,
+    AutopilotCancelGoalParams,
+    AutopilotDreamParams,
+    AutopilotGetGoalParams,
+    AutopilotGetJobParams,
+    AutopilotListGoalsParams,
+    AutopilotListJobsParams,
+    AutopilotResumeParams,
+    AutopilotStatusParams,
+    AutopilotSubmitParams,
     AutopilotSubscribeParams,
+    AutopilotWakeParams,
     ConfigGetParams,
     ConfigReloadParams,
     CronAddParams,
@@ -114,6 +125,8 @@ __all__ = [
     "bootstrap_loop_session",
     "connect_websocket_with_retries",
     "websocket_url_from_config",
+    "connected_websocket",
+    "protocol1_rpc",
     "check_daemon_status",
     "is_daemon_live",
     "request_daemon_config_reload",
@@ -144,6 +157,16 @@ __all__ = [
     "LoopDetachParams",
     "SubscribeParams",
     "AutopilotSubscribeParams",
+    "AutopilotStatusParams",
+    "AutopilotSubmitParams",
+    "AutopilotListGoalsParams",
+    "AutopilotGetGoalParams",
+    "AutopilotCancelGoalParams",
+    "AutopilotWakeParams",
+    "AutopilotDreamParams",
+    "AutopilotResumeParams",
+    "AutopilotListJobsParams",
+    "AutopilotGetJobParams",
     "JobCreateParams",
     "JobStatusParams",
     "JobPauseParams",

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/__init__.py

@@ -1,15 +1,12 @@
-"""Reusable application-architecture layer over Layer 0 (RFC-629).
+"""Application helpers built on WebSocketClient.
 
-appkit is product-agnostic. Deliverable phases, persistence, and UI copy stay
-in the application (e.g. soothe-cli). Building blocks:
+Product-agnostic building blocks for agent UIs and backends:
 
-- ``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
+- ``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
+- ``SSEBroadcaster`` — drop-on-full fan-out to subscribers
 - ``SessionStore`` — persistence seam (Protocol)
 """
 

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/attachments.py

@@ -1,8 +1,7 @@
-"""Image attachment compaction for appkit (RFC-629 Layer 1).
+"""Image attachment compaction for appkit.
 
 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.
+Non-images and decode failures pass through unchanged.
 """
 
 from __future__ import annotations
@@ -12,6 +11,8 @@ import io
 from dataclasses import dataclass
 from typing import Any
 
+from PIL import Image
+
 
 @dataclass(slots=True)
 class CompactImageOptions:
@@ -49,10 +50,6 @@ def compact_image_attachment(
     """
     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)

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/broadcaster.py

@@ -1,4 +1,4 @@
-"""SSE-style pub/sub fan-out for appkit (RFC-629 Layer 1).
+"""SSE-style pub/sub fan-out for appkit.
 
 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

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/classifier.py

@@ -1,4 +1,4 @@
-"""Event classifier for appkit (RFC-629 Layer 1).
+"""Event classifier for appkit.
 
 Maps a stream of decoded daemon events into deliverable/streaming/terminal
 outcomes, keyed on (namespace, mode, phase). Product apps pass their own

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/daemon_session.py

@@ -1,9 +1,8 @@
-"""Dual-socket daemon loop session with turn streaming (CLI-grade mechanics).
+"""Dual-socket daemon loop session with turn streaming.
 
 Owns a subscribed stream WebSocket plus an RPC sidecar so metadata calls do not
-starve ``loop_events``. ``iter_turn_chunks`` implements stale-idle guarding,
-post-idle drain, loop scoping, and connection-loss detection — behavior that
-originated in soothe-cli and is not yet mirrored in Go/TS TurnRunner.
+starve loop events. ``iter_turn_chunks`` handles idle timeout, post-idle drain,
+loop scoping, and connection-loss detection.
 """
 
 from __future__ import annotations
@@ -25,7 +24,12 @@ logger = logging.getLogger(__name__)
 
 DEFAULT_POST_IDLE_DRAIN_S = 0.5
 _RPC_HANDSHAKE_TIMEOUT_S = 20.0
-_TURN_END_CUSTOM_TYPES = frozenset({"soothe.cognition.strange_loop.completed"})
+_TURN_END_CUSTOM_TYPES = frozenset(
+    {
+        "soothe.cognition.strange_loop.completed",
+        "soothe.stream.end",
+    }
+)
 
 EarlyDropFn = Callable[[tuple[Any, ...], str, Any], bool]
 StatsFactory = Callable[[], Any]
@@ -210,6 +214,7 @@ class DaemonSession:
         clarification_mode: str | None = None,
         clarification_answer: bool = False,
         clarification_answers: list[str] | None = None,
+        intent_hint: str | None = None,
     ) -> None:
         """Send a new user turn to the daemon."""
         if not self._loop_id:
@@ -227,6 +232,7 @@ class DaemonSession:
             clarification_mode=clarification_mode,
             clarification_answer=clarification_answer,
             clarification_answers=clarification_answers,
+            intent_hint=intent_hint,
         )
 
     async def cancel_remote_query(self) -> None:
@@ -289,8 +295,19 @@ class DaemonSession:
             await self._ensure_rpc_connected()
             return await self._rpc_client.request("loop_list", {"limit": limit}, timeout=15.0)
 
-    async def iter_turn_chunks(self) -> AsyncIterator[tuple[tuple[Any, ...], str, Any]]:
-        """Yield ``(namespace, mode, data)`` chunks for the active daemon turn."""
+    async def iter_turn_chunks(
+        self,
+        *,
+        max_wait_s: float | None = None,
+    ) -> AsyncIterator[tuple[tuple[Any, ...], str, Any]]:
+        """Yield ``(namespace, mode, data)`` chunks for the active daemon 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).
+        """
         self.turn_event_stats = self._new_turn_stats()
         self.last_turn_end_state = None
         self.last_turn_cancellation_seen = False
@@ -303,6 +320,9 @@ class DaemonSession:
         turn_read_started = time.monotonic()
         first_event_logged = False
         progress_seen = False
+        absolute_deadline = (
+            time.monotonic() + max_wait_s if max_wait_s is not None and max_wait_s > 0 else None
+        )
         peel = getattr(self._client, "peel_stale_pending_control_events", None)
         stale_pending = peel() if callable(peel) else []
         if stale_pending:
@@ -315,6 +335,11 @@ class DaemonSession:
         async with self._read_lock:
             try:
                 while True:
+                    if absolute_deadline is not None and time.monotonic() >= absolute_deadline:
+                        raise TimeoutError(
+                            f"Turn timed out after {max_wait_s:.0f}s "
+                            f"(loop={expected_loop_id or '?'})"
+                        )
                     if not progress_seen and time.monotonic() - turn_read_started > 30.0:
                         logger.warning(
                             "No daemon stream progress after %.0fs (loop=%s, "
@@ -407,7 +432,14 @@ class DaemonSession:
                     if mode == "custom" and isinstance(data, dict):
                         custom_type = str(data.get("type", "")).strip()
                         if custom_type in _TURN_END_CUSTOM_TYPES:
-                            self.last_turn_end_state = "completed"
+                            # stream.end may be scope-tagged; treat blank / turn as end.
+                            if custom_type == "soothe.stream.end":
+                                scope = str(data.get("scope") or "turn").strip().lower()
+                                if scope not in {"", "turn"}:
+                                    continue
+                            self.last_turn_end_state = (
+                                "stream_end" if custom_type == "soothe.stream.end" else "completed"
+                            )
                             async for chunk in self._drain_stream_events_after_idle(
                                 expected_loop_id=expected_loop_id,
                             ):

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/managed_client.py

@@ -1,7 +1,7 @@
-"""ManagedClient seam for appkit ConnectionPool / TurnRunner (RFC-629).
+"""ManagedClient adapter used by ConnectionPool and TurnRunner.
 
-The concrete ``WebSocketClient`` satisfies it via ``WebSocketManagedClient``;
-tests supply fakes.
+Wraps ``WebSocketClient`` and upgrades flat appkit payloads
+(``loop_input``, ``command_request``, …) to protocol-1 envelopes before send.
 """
 
 from __future__ import annotations
@@ -18,10 +18,72 @@ BootstrapFunc = Callable[
     Awaitable[str],
 ]
 
+# Flat appkit payloads still use legacy ``{"type": "<op>", ...}`` maps (parity
+# with Go InputMessageForLoop). The live daemon accepts protocol-1 envelopes
+# only — coerce at the ManagedClient boundary before send.
+_ALREADY_ENVELOPE_TYPES = frozenset(
+    {
+        "request",
+        "response",
+        "notification",
+        "subscribe",
+        "next",
+        "error",
+        "complete",
+        "unsubscribe",
+        "connection_init",
+        "connection_ack",
+        "ping",
+        "pong",
+        "receipt_response",
+    }
+)
+_NOTIFICATION_METHODS = frozenset({"loop_input", "slash_command", "disconnect", "delivery_ack"})
+_REQUEST_METHOD_ALIASES = {
+    # TurnRunner cancel uses flat command_request; wire method is rpc_command.
+    "command_request": "rpc_command",
+}
+
+
+def _coerce_appkit_wire_message(msg: dict[str, Any], client: WebSocketClient) -> dict[str, Any]:
+    """Upgrade flat appkit dicts to protocol-1 envelopes when needed."""
+    from soothe_sdk.wire.codec import MessageType, WireEnvelope
+
+    msg_type = str(msg.get("type") or "")
+    if msg.get("proto") == "1" or msg_type in _ALREADY_ENVELOPE_TYPES:
+        return msg
+
+    params = {
+        key: value
+        for key, value in msg.items()
+        if key not in {"type", "proto", "method", "params", "id", "request_id"}
+    }
+
+    if msg_type in _NOTIFICATION_METHODS:
+        return WireEnvelope(
+            proto="1",
+            type=MessageType.NOTIFICATION.value,
+            method=msg_type,
+            params=params,
+        ).to_wire_dict()
+
+    if msg_type in _REQUEST_METHOD_ALIASES or msg_type:
+        request_method = _REQUEST_METHOD_ALIASES.get(msg_type, msg_type)
+        req_id = str(msg.get("request_id") or msg.get("id") or client._next_request_id())
+        return WireEnvelope(
+            proto="1",
+            type=MessageType.REQUEST.value,
+            method=request_method,
+            params=params,
+            id=req_id,
+        ).to_wire_dict()
+
+    return msg
+
 
 @runtime_checkable
 class ManagedClient(Protocol):
-    """Subset of Layer 0 that ConnectionPool and TurnRunner depend on."""
+    """Subset of WebSocketClient that ConnectionPool and TurnRunner depend on."""
 
     async def connect(self) -> None:
         """Dial and handshake."""
@@ -72,7 +134,7 @@ class WebSocketManagedClient:
 
     @property
     def underlying(self) -> WebSocketClient:
-        """Return the wrapped Layer 0 client."""
+        """Return the wrapped WebSocketClient."""
         return self._client
 
     async def connect(self) -> None:
@@ -89,7 +151,7 @@ class WebSocketManagedClient:
     async def send_message(self, msg: Any) -> None:
         if not isinstance(msg, dict):
             raise TypeError("send_message expects a dict payload")
-        await self._client.send(msg)
+        await self._client.send(_coerce_appkit_wire_message(msg, self._client))
 
     async def receive_messages(
         self,

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/pool.py

@@ -1,4 +1,4 @@
-"""Per-session connection pool for appkit (RFC-629 Layer 1).
+"""Per-session connection pool for appkit.
 
 Manages a pool of daemon connections, one active per session. Reuses an
 active connection when still live, otherwise bootstraps a fresh loop or

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/query_gate.py

@@ -1,4 +1,4 @@
-"""Single-flight query gate (RFC-629 Layer 1)."""
+"""Single-flight query gate."""
 
 from __future__ import annotations
 

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/session_store.py

@@ -1,4 +1,4 @@
-"""Persistence seam for appkit (RFC-629 Layer 1)."""
+"""Persistence seam for appkit."""
 
 from __future__ import annotations
 

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/thinking_step.py

@@ -1,4 +1,4 @@
-"""Thinking-step extraction for appkit (RFC-629 Layer 1).
+"""Thinking-step extraction for appkit.
 
 Maps an allowlisted progress event to one structured UI line. Free-form
 streams (tokens, reports, reasoning) are excluded. Ported from Go/TS appkit.

{soothe_client_python-0.9.4 → soothe_client_python-0.9.6}/src/soothe_client/appkit/turn_runner.py

@@ -1,11 +1,11 @@
-"""Turn runner for appkit (RFC-629 Layer 1).
+"""Turn runner for appkit.
 
 Executes one query turn end-to-end: acquire a pooled connection, enforce
 single-flight, send loop_input, consume the event stream, classify events,
 resolve the deliverable, persist the reply, and broadcast completion.
 
 Supports absolute query timeout, optional idle silence watchdog, soft-complete
-policies (IG-651), and optional attachment compaction before send.
+policies, and optional attachment compaction before send.
 """
 
 from __future__ import annotations