soothe-client-python 1.0.0__tar.gz → 1.0.2__tar.gz

{soothe_client_python-1.0.0 → soothe_client_python-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soothe-client-python
-Version: 1.0.0
+Version: 1.0.2
 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

{soothe_client_python-1.0.0 → soothe_client_python-1.0.2}/src/soothe_client/appkit/__init__.py

@@ -42,6 +42,14 @@ from soothe_client.appkit.thinking_step import (
     DEFAULT_THINKING_STEP_EVENTS,
     extract_thinking_step,
 )
+from soothe_client.appkit.turn_boundary import (
+    TURN_END_IDLE,
+    TURN_END_STOPPED,
+    TURN_END_STREAM_END,
+    TurnBoundary,
+    TurnLifecycleGate,
+    is_daemon_turn_end_event,
+)
 from soothe_client.appkit.turn_runner import (
     STREAM_CLOSE_FAIL,
     STREAM_CLOSE_SOFT_COMPLETE,
@@ -88,10 +96,16 @@ __all__ = [
     "SessionMessage",
     "SessionStore",
     "StreamClosePolicy",
+    "TURN_END_IDLE",
+    "TURN_END_STOPPED",
+    "TURN_END_STREAM_END",
     "TimeoutPolicy",
+    "TurnBoundary",
     "TurnConfig",
+    "TurnLifecycleGate",
     "TurnRunner",
     "compact_attachments",
+    "is_daemon_turn_end_event",
     "compact_image_attachment",
     "default_pool_config",
     "extract_thinking_step",

{soothe_client_python-1.0.0 → soothe_client_python-1.0.2}/src/soothe_client/appkit/classifier.py

@@ -49,9 +49,9 @@ class ClassifierConfig:
             persisted as final (avoids finishing on stub ACKs). Defaults to 8.
         thinking_step_events: Optional override of the default thinking-step
             event allowlist.
-        treat_status_idle_as_complete: When true, a status frame with
-            ``state==idle`` and non-empty accumulated assistant text completes
-            the turn (typical for direct-model turns). Default false.
+        treat_status_idle_as_complete: Standalone ``classify`` only. Prefer
+            ``TurnRunner`` + ``TurnBoundary`` for turn end (DaemonSession
+            contract). Default false.
     """
 
     deliverable_phases: frozenset[str] | set[str]
@@ -85,6 +85,8 @@ class EventClassifier:
             return False
         if event_type in (
             "status.idle",
+            "status.stopped",
+            "soothe.stream.end",
             "idle_timeout",
             "query_timeout",
             "stream_closed",
@@ -314,12 +316,10 @@ class EventClassifier:
                     )
                 return self._continue_result(content)
 
-        direct_content, direct_ok = self._messages_mode_assistant_content(data)
-        if direct_ok and self.is_substantive_assistant_reply(direct_content):
-            return self._deliverable_result(
-                direct_content,
-                "soothe.protocol.message.direct_model",
-            )
+        # Unphased terminal AI text is streamable narration only.
+        unphased_content, unphased_ok = self._messages_mode_assistant_content(data)
+        if unphased_ok:
+            return self._continue_result(unphased_content)
 
         if has_payload and raw_content:
             if _is_terminal_message_type(msg_type) or msg_type == "":

soothe_client_python-1.0.2/src/soothe_client/appkit/turn_boundary.py

@@ -0,0 +1,127 @@
+"""DaemonSession turn-end contract for the pool TurnRunner path.
+
+TurnRunner owns one ``TurnBoundary`` per Execute. EventClassifier may
+early-complete on deliverable phases for UX; it is not the sole terminator.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from soothe_client.stream_terminal import (
+    STREAM_END,
+    is_turn_end_custom_data,
+    is_turn_progress_chunk,
+)
+
+TURN_END_STREAM_END = STREAM_END
+TURN_END_IDLE = "status.idle"
+TURN_END_STOPPED = "status.stopped"
+
+
+@dataclass
+class TurnLifecycleGate:
+    """Per-turn progress flags (DaemonSession parity; not shared across chats)."""
+
+    saw_running: bool = False
+    saw_stream_payload: bool = False
+    saw_turn_progress: bool = False
+
+    def observe(self, msg: Any) -> None:
+        frame = _normalize_frame(msg)
+        if frame is None:
+            return
+        typ = str(frame.get("type") or "")
+        if typ == "status":
+            if str(frame.get("state") or "").strip().lower() == "running":
+                self.saw_running = True
+            return
+        if typ == "event":
+            self.saw_stream_payload = True
+            mode = str(frame.get("mode") or "")
+            if is_turn_progress_chunk(mode, frame.get("data")):
+                self.saw_turn_progress = True
+
+    def allow_stream_end(self) -> bool:
+        return self.saw_running and self.saw_turn_progress
+
+    def allow_idle_complete(self) -> bool:
+        return self.saw_running and self.saw_stream_payload
+
+
+@dataclass
+class TurnBoundary:
+    """Applies DaemonSession end rules to pool decoded frames."""
+
+    gate: TurnLifecycleGate = field(default_factory=TurnLifecycleGate)
+    ended: bool = False
+    reason: str = ""
+
+    def feed(self, msg: Any) -> tuple[bool, str]:
+        if self.ended:
+            return True, self.reason
+        self.gate.observe(msg)
+        frame = _normalize_frame(msg)
+        if frame is None:
+            return False, ""
+
+        typ = str(frame.get("type") or "")
+        if typ == "status":
+            state = str(frame.get("state") or "").strip().lower()
+            if state == "stopped" and self.gate.saw_running:
+                return self._mark(TURN_END_STOPPED)
+            if state == "idle" and self.gate.allow_idle_complete():
+                return self._mark(TURN_END_IDLE)
+            return False, ""
+
+        if typ == "event":
+            mode = str(frame.get("mode") or "")
+            data = frame.get("data")
+            if mode == "custom" and is_turn_end_custom_data(data) and self.gate.allow_stream_end():
+                return self._mark(TURN_END_STREAM_END)
+        return False, ""
+
+    def _mark(self, reason: str) -> tuple[bool, str]:
+        self.ended = True
+        self.reason = reason
+        return True, reason
+
+
+def is_daemon_turn_end_event(completion_event: str) -> bool:
+    """True for TurnBoundary completion_event values (not phase deliverables)."""
+    return (completion_event or "").strip() in {
+        TURN_END_STREAM_END,
+        TURN_END_IDLE,
+        TURN_END_STOPPED,
+    }
+
+
+def _normalize_frame(msg: Any) -> dict[str, Any] | None:
+    if not isinstance(msg, dict):
+        return None
+    typ = msg.get("type")
+    if typ == "next":
+        payload = msg.get("payload")
+        if not isinstance(payload, dict):
+            return None
+        inner = payload.get("data")
+        if isinstance(inner, dict) and inner.get("type") == "status":
+            return inner
+        if isinstance(inner, dict) and inner.get("mode"):
+            return {
+                "type": "event",
+                "mode": inner.get("mode"),
+                "data": inner.get("data"),
+                "namespace": inner.get("namespace") or payload.get("namespace"),
+            }
+        mode = payload.get("mode")
+        if mode:
+            return {
+                "type": "event",
+                "mode": mode,
+                "data": payload.get("data"),
+                "namespace": payload.get("namespace"),
+            }
+        return None
+    return msg

{soothe_client_python-1.0.0 → soothe_client_python-1.0.2}/src/soothe_client/appkit/turn_runner.py

@@ -1,11 +1,11 @@
 """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.
+single-flight, send loop_input, consume the event stream, persist/broadcast.
 
-Supports absolute query timeout, optional idle silence watchdog, soft-complete
-policies, and optional attachment compaction before send.
+Turn end is owned by ``TurnBoundary`` (DaemonSession.iter_turn_chunks contract:
+gated ``stream.end`` / idle / stopped). ``EventClassifier`` selects user-visible
+text and may early-complete on deliverable phases for UX.
 """
 
 from __future__ import annotations
@@ -24,6 +24,7 @@ from soothe_client.appkit.classifier import ChatEventTerminal, EventClassifier
 from soothe_client.appkit.pool import ConnectionPool, PooledConn
 from soothe_client.appkit.query_gate import QueryGate
 from soothe_client.appkit.session_store import SessionMessage, SessionStore
+from soothe_client.appkit.turn_boundary import TurnBoundary, is_daemon_turn_end_event
 from soothe_client.intent_hints import validate_loop_input_intent_hint
 
 Attachment = dict[str, Any]
@@ -261,6 +262,7 @@ class TurnRunner:
 
             assistant_content = ""
             started_at = time.time()
+            boundary = TurnBoundary()
             agen = event_stream.__aiter__()
             arm_idle()
 
@@ -378,6 +380,7 @@ class TurnRunner:
 
                 arm_idle()
 
+                ended, end_reason = boundary.feed(msg)
                 event_result = self._classifier.classify(msg, assistant_content)
                 if (
                     event_result.err is not None
@@ -404,7 +407,9 @@ class TurnRunner:
                     event_result,
                     assistant_content,
                 )
-                if deliverable:
+                if deliverable and not is_daemon_turn_end_event(
+                    event_result.completion_event or ""
+                ):
                     await self._complete_turn(
                         session_id,
                         loop_id,
@@ -413,6 +418,20 @@ class TurnRunner:
                         event_result.completion_event or "",
                     )
                     return
+
+                if ended:
+                    if self._classifier.is_substantive_assistant_reply(assistant_content):
+                        await self._complete_turn(
+                            session_id,
+                            loop_id,
+                            assistant_content.strip(),
+                            started_at,
+                            end_reason,
+                        )
+                        return
+                    empty = RuntimeError(f"turn ended ({end_reason}) with no assistant content")
+                    await self._fail_turn(session_id, loop_id, empty)
+                    raise empty
         finally:
             query_timer.cancel()
             with contextlib.suppress(asyncio.CancelledError):

{soothe_client_python-1.0.0 → soothe_client_python-1.0.2}/src/soothe_client/intent_hints.py

@@ -9,14 +9,14 @@ IMAGE_TO_TEXT: Final = "image_to_text"
 OCR: Final = "ocr"
 EMBED: Final = "embed"
 
-REMOVED_INTENT_HINTS: frozenset[str] = frozenset({"direct_llm", "quiz"})
+REMOVED_INTENT_HINTS: frozenset[str] = frozenset({"direct_llm", "quiz", "direct_model"})
 
 # Default deliverable phases for turn-ending replies (excludes plan_direct narration).
 DEFAULT_DELIVERABLE_PHASES: frozenset[str] = frozenset(
     {
         "quiz",
         "goal_completion",
-        "direct_model",
+        "chitchat",
         "text_completion",
         "image_to_text",
         "ocr",
@@ -30,13 +30,16 @@ _REMOVED_INTENT_HINT_MESSAGES: dict[str, str] = {
         "use text_completion (text-only) or image_to_text (with attachments)"
     ),
     "quiz": "intent_hint quiz is removed; omit intent_hint and let intake classify the turn",
+    "direct_model": (
+        "intent_hint direct_model is removed; use text_completion, image_to_text, ocr, or embed"
+    ),
 }
 
 
 def validate_loop_input_intent_hint(hint: str) -> str | None:
     """Return an error message when ``hint`` is a removed legacy value.
 
-    Direct model hints and agent-path pass-through values (e.g.
+    Intent-hint values and agent-path pass-through values (e.g.
     ``resume_clarification``, ``skill:foo``) are allowed.
     """
     key = hint.strip().lower()

{soothe_client_python-1.0.0 → soothe_client_python-1.0.2}/src/soothe_client/protocol_params.py

@@ -200,7 +200,7 @@ class LoopInputParams(ParamsBase):
         model_params: Additional model parameters.
         router_profile: Named ``router_profiles`` overlay for chat roles this turn.
         attachments: Image attachments.
-        intent_hint: Daemon direct-model hint (text_completion, image_to_text, ocr, embed).
+        intent_hint: Daemon intent_hint (text_completion, image_to_text, ocr, embed).
         response_schema: Structured output schema.
         response_schema_name: Schema name for logging.
         response_schema_strict: Enable strict schema validation.
@@ -415,7 +415,7 @@ class JobCreateParams(ParamsBase):
         autonomous: Enable autonomous mode.
         max_iterations: Max iterations.
         guidance: Initial guidance.
-        intent_hint: Daemon direct-model hint (text_completion, image_to_text, ocr, embed).
+        intent_hint: Daemon intent_hint (text_completion, image_to_text, ocr, embed).
     """
 
     goal: str = Field(..., min_length=1, description="Root goal text")

{soothe_client_python-1.0.0 → soothe_client_python-1.0.2}/src/soothe_client/websocket.py

@@ -966,7 +966,7 @@ class WebSocketClient:
             model_params: Additional model parameters.
             router_profile: Named router profile for chat-role overlay this turn.
             attachments: Image attachments (mime_type + base64 data).
-            intent_hint: Daemon-only direct model hint. Supported values:
+            intent_hint: Daemon-only intent_hint. Supported values:
                 ``text_completion`` (``default`` role, text-only),
                 ``image_to_text`` (``image`` role, attachments required),
                 ``ocr`` (``ocr`` role, attachments required),
@@ -974,7 +974,8 @@ class WebSocketClient:
                 ``response_schema`` is supported for ``text_completion`` and
                 ``image_to_text``. Agent-path pass-through hints (e.g.
                 ``resume_clarification``, ``skill:foo``) are forwarded unchanged.
-                Legacy ``direct_llm`` and ``quiz`` are rejected before send.
+                Legacy ``direct_llm``, ``quiz``, and ``direct_model`` are rejected
+                before send.
 
         Raises:
             ValueError: When ``intent_hint`` is a removed legacy value.