soothe-cli 0.1.0__py3-none-any.whl

soothe_cli/shared/tool_formatters/structured.py

@@ -0,0 +1,202 @@
+"""Formatter for ToolOutput structured results."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from soothe_sdk.protocol import preview_first
+
+from soothe_cli.shared.tool_formatters.base import BaseFormatter
+from soothe_cli.shared.tool_output_formatter import ToolBrief
+
+
+class StructuredFormatter(BaseFormatter):
+    """Formatter for ToolOutput structured results.
+
+    Handles results from the agentic loop (RFC-0008) that use ToolOutput schema
+    with success/error classification and error types.
+    """
+
+    def format(self, tool_name: str, result: Any) -> ToolBrief:
+        """Format ToolOutput structured result.
+
+        Args:
+            tool_name: Name of the tool.
+            result: ToolOutput object with success, data, error, error_type fields.
+
+        Returns:
+            ToolBrief with structured summary.
+
+        Example:
+            >>> from soothe_sdk import ToolOutput
+            >>> formatter = StructuredFormatter()
+            >>> output = ToolOutput.ok(data="file content")
+            >>> brief = formatter.format("read_file", output)
+            >>> brief.icon
+            '✓'
+        """
+        # Import ToolOutput (may not be available in all contexts)
+        try:
+            from soothe_sdk import ToolOutput
+
+            if not isinstance(result, ToolOutput):
+                # Not a ToolOutput - should not happen if classifier works correctly
+                # Fallback to simple formatting
+                return self._format_unknown(result)
+
+            # Handle silent failure (success=True but no data)
+            if result.is_silent_failure():
+                return ToolBrief(
+                    icon="⚠",
+                    summary="No result",
+                    detail="Tool succeeded but returned no data",
+                    metrics={"silent_failure": True},
+                )
+
+            # Handle failure
+            if not result.success:
+                error_msg = preview_first(result.error, 80) if result.error else "Unknown error"
+                error_type = result.error_type or "unknown"
+
+                return ToolBrief(
+                    icon="✗",
+                    summary="Failed",
+                    detail=error_msg,
+                    metrics={"error": True, "error_type": error_type},
+                )
+
+            # Success - try to extract meaningful summary from data
+            return self._format_success(tool_name, result.data)
+
+        except ImportError:
+            # ToolOutput not available - fallback
+            return self._format_unknown(result)
+
+    def _format_success(self, tool_name: str, data: Any) -> ToolBrief:  # noqa: ARG002
+        """Format successful ToolOutput result.
+
+        Attempts to extract meaningful summary from data.
+
+        Args:
+            tool_name: Name of the tool (unused, for future tool-specific formatting).
+            data: Result data (can be any type).
+
+        Returns:
+            ToolBrief with success summary.
+        """
+        # Handle None
+        if data is None:
+            return ToolBrief(
+                icon="✓",
+                summary="Completed",
+                detail="no data",
+                metrics={"has_data": False},
+            )
+
+        # Handle string data
+        if isinstance(data, str):
+            size_bytes = len(data.encode("utf-8"))
+            size_str = self._format_size(size_bytes)
+            lines = self._count_lines(data)
+
+            summary = f"Read {size_str}"
+            detail = f"{lines} lines" if lines > 0 else "empty"
+
+            return ToolBrief(
+                icon="✓",
+                summary=summary,
+                detail=detail,
+                metrics={"size_bytes": size_bytes, "lines": lines},
+            )
+
+        # Handle dict data
+        if isinstance(data, dict):
+            field_count = len(data)
+
+            # Try to extract common fields
+            if "id" in data:
+                obj_id = data["id"]
+                return ToolBrief(
+                    icon="✓",
+                    summary="Completed",
+                    detail=f"id: {obj_id}",
+                    metrics={"has_id": True},
+                )
+
+            return ToolBrief(
+                icon="✓",
+                summary="Completed",
+                detail=f"{field_count} fields",
+                metrics={"field_count": field_count},
+            )
+
+        # Handle list data
+        if isinstance(data, list):
+            count = len(data)
+            return ToolBrief(
+                icon="✓",
+                summary="Completed",
+                detail=f"{count} items",
+                metrics={"count": count},
+            )
+
+        # Handle other types
+        data_type = type(data).__name__
+        return ToolBrief(
+            icon="✓",
+            summary="Completed",
+            detail=f"data: {data_type}",
+            metrics={"data_type": data_type},
+        )
+
+    def _format_unknown(self, result: Any) -> ToolBrief:
+        """Format unknown result type.
+
+        Fallback for non-ToolOutput results.
+
+        Args:
+            result: Unknown result type.
+
+        Returns:
+            ToolBrief with generic summary.
+        """
+        if isinstance(result, str):
+            if "error" in result.lower() or "failed" in result.lower():
+                return ToolBrief(
+                    icon="✗",
+                    summary="Failed",
+                    detail=self._truncate_text(result, 80),
+                    metrics={"error": True},
+                )
+
+            return ToolBrief(
+                icon="✓",
+                summary="Completed",
+                detail=f"{len(result)} chars",
+                metrics={},
+            )
+
+        if isinstance(result, dict):
+            if "error" in result:
+                error_msg = preview_first(str(result["error"]), 80)
+                return ToolBrief(
+                    icon="✗",
+                    summary="Failed",
+                    detail=error_msg,
+                    metrics={"error": True},
+                )
+
+            return ToolBrief(
+                icon="✓",
+                summary="Completed",
+                detail=f"{len(result)} fields",
+                metrics={},
+            )
+
+        # Generic fallback
+        return ToolBrief(
+            icon="✓",
+            summary="Completed",
+            detail=None,
+            metrics={},
+        )

soothe_cli/shared/tool_formatters/web.py

@@ -0,0 +1,143 @@
+"""Formatter for web search and crawl tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from soothe_cli.shared.tool_formatters.base import BaseFormatter
+from soothe_cli.shared.tool_output_formatter import ToolBrief
+
+
+class WebFormatter(BaseFormatter):
+    """Formatter for web operation tools.
+
+    Handles: search_web, crawl_web
+
+    Provides semantic summaries with result counts, URLs, and content metrics.
+    """
+
+    def format(self, tool_name: str, result: Any) -> ToolBrief:
+        r"""Format web tool result.
+
+        Args:
+            tool_name: Name of the web tool.
+            result: Tool result (typically string with search results or crawled content).
+
+        Returns:
+            ToolBrief with web operation summary.
+
+        Raises:
+            ValueError: If tool_name is not a recognized web tool.
+
+        Example:
+            >>> formatter = WebFormatter()
+            >>> brief = formatter.format("search_web", "1. Result\n2. Result")
+            >>> brief.summary
+            'Found 2 results'
+        """
+        # Normalize tool name
+        normalized = tool_name.lower().replace("-", "_").replace(" ", "_")
+
+        # Route to specific formatter
+        if normalized == "search_web":
+            return self._format_search_web(result)
+        if normalized == "crawl_web":
+            return self._format_crawl_web(result)
+
+        msg = f"Unknown web tool: {tool_name}"
+        raise ValueError(msg)
+
+    def _format_search_web(self, result: str) -> ToolBrief:
+        r"""Format search_web result.
+
+        Shows count of search results found.
+
+        Args:
+            result: Search results string with titles, URLs, snippets.
+
+        Returns:
+            ToolBrief with result count.
+
+        Example:
+            >>> brief = formatter._format_search_web("1. Example\n2. Another")
+            >>> brief.summary
+            'Found 2 results'
+        """
+        # Check for error
+        if "error" in result.lower() or "failed" in result.lower():
+            return ToolBrief(
+                icon="✗",
+                summary="Search failed",
+                detail=self._truncate_text(result, 80),
+                metrics={"error": True},
+            )
+
+        # Count results (non-empty lines or result sections)
+        lines = [line for line in result.split("\n") if line.strip()]
+
+        # Try to detect result count patterns
+        # Pattern: numbered results "1. Title" "2. Title"
+        numbered_results = [
+            line for line in lines if len(line) > 0 and line[0].isdigit() and "." in line[:3]
+        ]
+        count = len(numbered_results) if numbered_results else max(1, len(lines) // 3)
+
+        summary = f"Found {count} result{'s' if count != 1 else ''}"
+
+        # Show first URL or title as detail if available
+        first_line = lines[0] if lines else ""
+        detail = self._truncate_text(first_line, 80) if first_line else None
+
+        return ToolBrief(
+            icon="✓",
+            summary=summary,
+            detail=detail,
+            metrics={"count": count},
+        )
+
+    def _format_crawl_web(self, result: str) -> ToolBrief:
+        """Format crawl_web result.
+
+        Shows content size and word/line count.
+
+        Args:
+            result: Crawled content string.
+
+        Returns:
+            ToolBrief with content metrics.
+
+        Example:
+            >>> brief = formatter._format_crawl_web("Article content...")
+            >>> brief.summary
+            'Crawled 2.3 KB'
+            >>> brief.detail
+            '450 words'
+        """
+        # Check for error
+        if "error" in result.lower() or "failed" in result.lower():
+            return ToolBrief(
+                icon="✗",
+                summary="Crawl failed",
+                detail=self._truncate_text(result, 80),
+                metrics={"error": True},
+            )
+
+        # Calculate metrics
+        size_bytes = len(result.encode("utf-8"))
+        size_str = self._format_size(size_bytes)
+
+        # Count words and lines
+        words = len(result.split())
+        lines = self._count_lines(result)
+
+        summary = f"Crawled {size_str}"
+
+        # Show word count as detail
+        detail = f"{words} words"
+
+        return ToolBrief(
+            icon="✓",
+            summary=summary,
+            detail=detail,
+            metrics={"size_bytes": size_bytes, "words": words, "lines": lines},
+        )

soothe_cli/shared/tool_output_formatter.py

@@ -0,0 +1,227 @@
+"""Tool output formatter for semantic result summarization (RFC-0020).
+
+This module provides a formatter-based pipeline that transforms raw tool outputs
+into concise, semantic summaries following RFC-0020 event display architecture.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ToolBrief:
+    """Structured summary of tool execution result.
+
+    Follows RFC-0020 two-level tree display pattern with maximum lengths
+    enforced for terminal display.
+
+    Attributes:
+        icon: Status indicator (✓, ✗, ⚠).
+        summary: One-line summary (max 50 characters).
+        detail: Optional detail line (max 80 characters).
+        metrics: Optional metadata (size, duration, count, etc.).
+    """
+
+    icon: str
+    summary: str
+    detail: str | None = None
+    metrics: dict[str, Any] = field(default_factory=dict)
+
+    def to_display(self) -> str:
+        """Format as RFC-0020 display string.
+
+        Returns:
+            Formatted string: "icon summary (detail)" or "icon summary".
+
+        Example:
+            >>> brief = ToolBrief(icon="✓", summary="Read 2.3 KB", detail="42 lines")
+            >>> brief.to_display()
+            '✓ Read 2.3 KB (42 lines)'
+        """
+        result = f"{self.icon} {self.summary}"
+        if self.detail:
+            result += f" ({self.detail})"
+        return result
+
+    def __post_init__(self) -> None:
+        """Enforce RFC-0020 length constraints."""
+        # Maximum summary length: 50 characters
+        max_summary_len = 50
+        if len(self.summary) > max_summary_len:
+            self.summary = self.summary[: max_summary_len - 3] + "..."
+
+        # Maximum detail length: 80 characters
+        max_detail_len = 80
+        if self.detail and len(self.detail) > max_detail_len:
+            self.detail = self.detail[: max_detail_len - 3] + "..."
+
+
+# Tool category mapping for classifier
+TOOL_CATEGORIES: dict[str, str] = {
+    # File operations
+    "read_file": "file_ops",
+    "write_file": "file_ops",
+    "delete_file": "file_ops",
+    "list_files": "file_ops",
+    "search_files": "file_ops",
+    "glob": "file_ops",
+    "ls": "file_ops",
+    # Execution
+    "run_command": "execution",
+    "run_python": "execution",
+    "run_background": "execution",
+    "kill_process": "execution",
+    # Media
+    "transcribe_audio": "media",
+    "get_video_info": "media",
+    "analyze_image": "media",
+    # Goals
+    "create_goal": "goals",
+    "list_goals": "goals",
+    "complete_goal": "goals",
+    "fail_goal": "goals",
+    # Web
+    "search_web": "web",
+    "crawl_web": "web",
+}
+
+
+def classify_tool(tool_name: str) -> str:
+    """Classify tool into category based on name.
+
+    Args:
+        tool_name: Name of the tool (e.g., "read_file", "run_command").
+
+    Returns:
+        Tool category (e.g., "file_ops", "execution", "media", "goals", "web", "unknown").
+
+    Example:
+        >>> classify_tool("read_file")
+        'file_ops'
+        >>> classify_tool("unknown_tool")
+        'unknown'
+    """
+    # Normalize tool name to snake_case (handle variations)
+    normalized = tool_name.lower().replace("-", "_").replace(" ", "_")
+
+    # Look up in category mapping
+    return TOOL_CATEGORIES.get(normalized, "unknown")
+
+
+def detect_result_type(result: Any) -> str:
+    """Detect result type for routing to appropriate formatter.
+
+    Args:
+        result: Tool result (can be str, dict, ToolOutput, or other).
+
+    Returns:
+        Result type string: "tool_output", "dict", "str", or "unknown".
+
+    Example:
+        >>> detect_result_type("some string")
+        'str'
+        >>> detect_result_type({"success": True})
+        'dict'
+    """
+    # Check for ToolOutput (from agentic loop)
+    # Import here to avoid circular imports
+    try:
+        from soothe_sdk import ToolOutput
+
+        if isinstance(result, ToolOutput):
+            return "tool_output"
+    except ImportError:
+        pass  # ToolOutput not available, skip check
+
+    # Check standard types
+    if isinstance(result, dict):
+        return "dict"
+    if isinstance(result, str):
+        return "str"
+    return "unknown"
+
+
+class ToolOutputFormatter:
+    """Main formatter for tool output summarization.
+
+    Coordinates classification and routing to tool-specific formatters
+    with fallback handling for unknown tools.
+    """
+
+    def format(self, tool_name: str, result: Any) -> ToolBrief:
+        r"""Format tool result into semantic summary.
+
+        Args:
+            tool_name: Name of the tool (e.g., "read_file", "run_command").
+            result: Tool result (can be str, dict, ToolOutput, or other).
+
+        Returns:
+            ToolBrief with semantic summary.
+
+        Example:
+            >>> formatter = ToolOutputFormatter()
+            >>> brief = formatter.format("read_file", "Hello\nWorld\n")
+            >>> brief.to_display()
+            '✓ Read 12 B (2 lines)'
+        """
+        # Classify tool
+        category = classify_tool(tool_name)
+
+        # Detect result type
+        result_type = detect_result_type(result)
+
+        # Route to appropriate formatter
+        try:
+            # Import formatters (lazy import to avoid circular dependencies)
+            from soothe_cli.shared.tool_formatters import (
+                ExecutionFormatter,
+                FallbackFormatter,
+                FileOpsFormatter,
+                GoalFormatter,
+                MediaFormatter,
+                StructuredFormatter,
+                WebFormatter,
+            )
+
+            # Handle ToolOutput first (highest priority)
+            if result_type == "tool_output":
+                formatter = StructuredFormatter()
+                return formatter.format(tool_name, result)
+
+            # Route by category
+            if category == "file_ops":
+                formatter = FileOpsFormatter()
+                return formatter.format(tool_name, result)
+            if category == "execution":
+                formatter = ExecutionFormatter()
+                return formatter.format(tool_name, result)
+            if category == "media":
+                formatter = MediaFormatter()
+                return formatter.format(tool_name, result)
+            if category == "goals":
+                formatter = GoalFormatter()
+                return formatter.format(tool_name, result)
+            if category == "web":
+                formatter = WebFormatter()
+                return formatter.format(tool_name, result)
+            # Unknown category - use fallback
+            formatter = FallbackFormatter()
+            return formatter.format(tool_name, result)
+
+        except Exception as e:
+            # Log error and fallback to simple formatting
+            logger.warning(
+                "Formatter error for tool %s: %s. Using fallback.",
+                tool_name,
+                e,
+                exc_info=True,
+            )
+            from soothe_cli.shared.tool_formatters import FallbackFormatter
+
+            formatter = FallbackFormatter()
+            return formatter.format(tool_name, result)

soothe_cli/shared/tui_trace_log.py

@@ -0,0 +1,40 @@
+"""Structured INFO logs for TUI debugging when ``SootheConfig.tui_debug`` is true.
+
+Enable via ``SOOTHE_TUI_DEBUG=true`` or ``tui_debug: true`` in config. Logs use logger
+``soothe.ux.tui.trace`` so you can filter with ``SOOTHE_LOG_LEVEL=INFO`` and grep for
+``tui_trace``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from soothe_sdk import log_preview
+
+_logger = logging.getLogger("soothe.ux.tui.trace")
+
+_PREVIEW_CHARS = 180
+
+
+def _fmt_field(key: str, value: Any) -> str:
+    if isinstance(value, str) and len(value) > _PREVIEW_CHARS:
+        value = log_preview(value, _PREVIEW_CHARS)
+    return f"{key}={value!r}"
+
+
+def log_tui_trace(*, tui_debug: bool, event: str, **fields: Any) -> None:
+    """Emit a single INFO log line when TUI debug mode is enabled.
+
+    Args:
+        tui_debug: Whether tracing is enabled (from config).
+        event: Short event name (e.g. ``renderer.assistant_text``).
+        fields: Key/value pairs appended as ``key='value'`` (strings truncated).
+    """
+    if not tui_debug:
+        return
+    if fields:
+        tail = " ".join(_fmt_field(k, v) for k, v in fields.items())
+        _logger.info("tui_trace | %s | %s", event, tail)
+    else:
+        _logger.info("tui_trace | %s", event)

soothe_cli/tui/__init__.py

@@ -0,0 +1,5 @@
+"""TUI interface for Soothe."""
+
+from soothe_cli.tui.app import SootheApp, run_textual_tui
+
+__all__ = ["SootheApp", "run_textual_tui"]

soothe_cli/tui/_ask_user_types.py

@@ -0,0 +1,50 @@
+"""Types for ask_user widget interactions (stub from deepagents-cli migration).
+
+This module provides type definitions for interactive user prompts.
+"""
+
+from typing_extensions import TypedDict
+
+
+class Choice(TypedDict):
+    """A choice option for user selection.
+
+    Args:
+        label: Display label for the choice.
+        value: Value to return if this choice is selected.
+    """
+
+    label: str
+    value: str
+
+
+class Question(TypedDict):
+    """A question to ask the user.
+
+    Args:
+        question: The question text to display.
+        choices: Optional list of choices for selection.
+        other: Whether to allow "Other" as a choice option.
+    """
+
+    question: str
+    choices: list[Choice] | None
+    other: bool
+
+
+# Result type from ask_user widget
+AskUserWidgetResult = dict[str, str]
+
+
+class AskUserRequest(TypedDict):
+    """Request to ask user interactive questions.
+
+    Args:
+        questions: List of questions to ask.
+        timeout_seconds: Optional timeout for the prompt.
+        prompt_id: Unique identifier for this prompt.
+    """
+
+    questions: list[Question]
+    timeout_seconds: int | None
+    prompt_id: str

soothe_cli/tui/_cli_context.py

@@ -0,0 +1,27 @@
+"""Lightweight runtime context type for CLI model overrides.
+
+Extracted from `configurable_model` so hot-path modules (`app`,
+`textual_adapter`) can import `CLIContext` without pulling in the langchain
+middleware stack.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from typing_extensions import TypedDict
+
+
+class CLIContext(TypedDict, total=False):
+    """Runtime context passed via `context=` to the LangGraph graph.
+
+    Carries per-invocation overrides that `ConfigurableModelMiddleware`
+    reads from `request.runtime.context`.
+    """
+
+    model: str | None
+    """Model spec to swap at runtime (e.g. `'openai:gpt-4o'`)."""
+
+    model_params: dict[str, Any]
+    """Invocation params (e.g. `temperature`, `max_tokens`) to merge
+    into `model_settings`."""