htmlgraph 0.20.1__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/orchestration/spawners/base.py

@@ -0,0 +1,194 @@
+"""Base spawner class with common functionality for all AI spawners."""
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.orchestration.live_events import LiveEventPublisher
+    from htmlgraph.sdk import SDK
+
+
+@dataclass
+class AIResult:
+    """Result from AI CLI execution."""
+
+    success: bool
+    response: str
+    tokens_used: int | None
+    error: str | None
+    raw_output: dict | list | str | None
+    tracked_events: list[dict] | None = None  # Events tracked in HtmlGraph
+
+
+class BaseSpawner:
+    """
+    Base class for AI spawners with common functionality.
+
+    Provides:
+    - Live event publishing for WebSocket streaming
+    - SDK initialization with parent session support
+    - Common error handling patterns
+    """
+
+    def __init__(self) -> None:
+        """Initialize spawner."""
+        self._live_publisher: LiveEventPublisher | None = None
+
+    def _get_live_publisher(self) -> "LiveEventPublisher | None":
+        """
+        Get LiveEventPublisher instance for real-time WebSocket streaming.
+
+        Returns None if publisher unavailable (optional dependency).
+        """
+        if self._live_publisher is None:
+            try:
+                from htmlgraph.orchestration.live_events import LiveEventPublisher
+
+                self._live_publisher = LiveEventPublisher()
+            except Exception:
+                # Live events are optional
+                pass
+        return self._live_publisher
+
+    def _publish_live_event(
+        self,
+        event_type: str,
+        spawner_type: str,
+        **kwargs: str | int | float | bool | None,
+    ) -> None:
+        """
+        Publish a live event for WebSocket streaming.
+
+        Silently fails if publisher unavailable (optional feature).
+        """
+        publisher = self._get_live_publisher()
+        if publisher is None:
+            return
+
+        parent_event_id = os.getenv("HTMLGRAPH_PARENT_EVENT")
+
+        try:
+            if event_type == "spawner_start":
+                publisher.spawner_start(
+                    spawner_type=spawner_type,
+                    prompt=str(kwargs.get("prompt", "")),
+                    parent_event_id=parent_event_id,
+                    model=str(kwargs.get("model", "")) if kwargs.get("model") else None,
+                )
+            elif event_type == "spawner_phase":
+                progress_val = kwargs.get("progress")
+                publisher.spawner_phase(
+                    spawner_type=spawner_type,
+                    phase=str(kwargs.get("phase", "executing")),
+                    progress=int(progress_val) if progress_val is not None else None,
+                    details=str(kwargs.get("details", ""))
+                    if kwargs.get("details")
+                    else None,
+                    parent_event_id=parent_event_id,
+                )
+            elif event_type == "spawner_complete":
+                duration_val = kwargs.get("duration")
+                tokens_val = kwargs.get("tokens")
+                publisher.spawner_complete(
+                    spawner_type=spawner_type,
+                    success=bool(kwargs.get("success", False)),
+                    duration_seconds=float(duration_val)
+                    if duration_val is not None
+                    else None,
+                    response_preview=str(kwargs.get("response", ""))[:200]
+                    if kwargs.get("response")
+                    else None,
+                    tokens_used=int(tokens_val) if tokens_val is not None else None,
+                    error=str(kwargs.get("error", "")) if kwargs.get("error") else None,
+                    parent_event_id=parent_event_id,
+                )
+            elif event_type == "spawner_tool_use":
+                publisher.spawner_tool_use(
+                    spawner_type=spawner_type,
+                    tool_name=str(kwargs.get("tool_name", "unknown")),
+                    parent_event_id=parent_event_id,
+                )
+            elif event_type == "spawner_message":
+                publisher.spawner_message(
+                    spawner_type=spawner_type,
+                    message=str(kwargs.get("message", "")),
+                    role=str(kwargs.get("role", "assistant")),
+                    parent_event_id=parent_event_id,
+                )
+        except Exception:
+            # Live events should never break spawner execution
+            pass
+
+    def _get_sdk(self) -> "SDK | None":
+        """
+        Get SDK instance for HtmlGraph tracking with parent session support.
+
+        Returns None if SDK unavailable.
+        """
+        try:
+            from htmlgraph.sdk import SDK
+
+            # Read parent session context from environment
+            parent_session = os.getenv("HTMLGRAPH_PARENT_SESSION")
+            parent_agent = os.getenv("HTMLGRAPH_PARENT_AGENT")
+
+            # Create SDK with parent session context
+            sdk = SDK(
+                agent=f"spawner-{parent_agent}" if parent_agent else "spawner",
+                parent_session=parent_session,  # Pass parent session
+            )
+
+            return sdk
+
+        except Exception:
+            # SDK unavailable or not properly initialized (optional dependency)
+            # This happens in test contexts without active sessions
+            # Don't log error to avoid noise in tests
+            return None
+
+    def _get_parent_context(self) -> tuple[str | None, int]:
+        """
+        Get parent activity context for event tracking.
+
+        Returns:
+            Tuple of (parent_activity_id, nesting_depth)
+        """
+        parent_activity = os.getenv("HTMLGRAPH_PARENT_ACTIVITY")
+        nesting_depth_str = os.getenv("HTMLGRAPH_NESTING_DEPTH", "0")
+        nesting_depth = int(nesting_depth_str) if nesting_depth_str.isdigit() else 0
+        return parent_activity, nesting_depth
+
+    def _track_activity(
+        self,
+        sdk: "SDK",
+        tool: str,
+        summary: str,
+        payload: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Track activity in HtmlGraph with parent context.
+
+        Args:
+            sdk: SDK instance
+            tool: Tool name
+            summary: Activity summary
+            payload: Activity payload (will be enriched with parent context)
+            **kwargs: Additional arguments for track_activity
+        """
+        if payload is None:
+            payload = {}
+
+        # Enrich with parent context
+        parent_activity, nesting_depth = self._get_parent_context()
+        if parent_activity:
+            payload["parent_activity"] = parent_activity
+        if nesting_depth > 0:
+            payload["nesting_depth"] = nesting_depth
+
+        try:
+            sdk.track_activity(tool=tool, summary=summary, payload=payload, **kwargs)
+        except Exception:
+            # Tracking failure should not break execution
+            pass

htmlgraph/orchestration/spawners/claude.py

@@ -0,0 +1,173 @@
+"""Claude spawner implementation."""
+
+import json
+import logging
+import subprocess
+from typing import TYPE_CHECKING
+
+from .base import AIResult, BaseSpawner
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    pass
+
+
+class ClaudeSpawner(BaseSpawner):
+    """
+    Spawner for Claude Code CLI.
+
+    NOTE: Uses same Claude Code authentication as Task() tool, but provides
+    isolated execution context. Each call creates a new session without shared
+    context. Best for independent tasks or external scripts.
+
+    For orchestration workflows with shared context, prefer Task() tool which
+    leverages prompt caching (5x cheaper for related work).
+    """
+
+    def spawn(
+        self,
+        prompt: str,
+        output_format: str = "json",
+        permission_mode: str = "bypassPermissions",
+        resume: str | None = None,
+        verbose: bool = False,
+        timeout: int = 300,
+        extra_args: list[str] | None = None,
+    ) -> AIResult:
+        """
+        Spawn Claude in headless mode.
+
+        NOTE: Uses same Claude Code authentication as Task() tool, but provides
+        isolated execution context. Each call creates a new session without shared
+        context. Best for independent tasks or external scripts.
+
+        For orchestration workflows with shared context, prefer Task() tool which
+        leverages prompt caching (5x cheaper for related work).
+
+        Args:
+            prompt: Task description for Claude
+            output_format: "text" or "json" (stream-json requires --verbose)
+            permission_mode: Permission handling mode:
+                - "bypassPermissions": Auto-approve all (default)
+                - "acceptEdits": Auto-approve edits only
+                - "dontAsk": Fail on permission prompts
+                - "default": Normal interactive prompts
+                - "plan": Plan mode (no execution)
+                - "delegate": Delegation mode
+            resume: Resume from previous session (--resume). Default: None
+            verbose: Enable verbose output (--verbose). Default: False
+            timeout: Max seconds (default: 300, Claude can be slow with initialization)
+            extra_args: Additional arguments to pass to Claude CLI
+
+        Returns:
+            AIResult with response or error
+
+        Example:
+            >>> spawner = ClaudeSpawner()
+            >>> result = spawner.spawn("What is 2+2?")
+            >>> if result.success:
+            ...     logger.info("%s", result.response)  # "4"
+            ...     logger.info(f"Cost: ${result.raw_output['total_cost_usd']}")
+        """
+        cmd = ["claude", "-p"]
+
+        if output_format != "text":
+            cmd.extend(["--output-format", output_format])
+
+        if permission_mode:
+            cmd.extend(["--permission-mode", permission_mode])
+
+        # Add resume flag if specified
+        if resume:
+            cmd.extend(["--resume", resume])
+
+        # Add verbose flag
+        if verbose:
+            cmd.append("--verbose")
+
+        # Add extra args
+        if extra_args:
+            cmd.extend(extra_args)
+
+        # Use -- separator to ensure prompt isn't consumed by variadic args
+        cmd.append("--")
+        cmd.append(prompt)
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+
+            if output_format == "json":
+                # Parse JSON output
+                try:
+                    output = json.loads(result.stdout)
+                except json.JSONDecodeError as e:
+                    return AIResult(
+                        success=False,
+                        response="",
+                        tokens_used=None,
+                        error=f"Failed to parse JSON output: {e}",
+                        raw_output=result.stdout,
+                    )
+
+                # Extract result and metadata
+                usage = output.get("usage", {})
+                tokens = (
+                    usage.get("input_tokens", 0)
+                    + usage.get("cache_creation_input_tokens", 0)
+                    + usage.get("cache_read_input_tokens", 0)
+                    + usage.get("output_tokens", 0)
+                )
+
+                return AIResult(
+                    success=output.get("type") == "result"
+                    and not output.get("is_error"),
+                    response=output.get("result", ""),
+                    tokens_used=tokens,
+                    error=output.get("error") if output.get("is_error") else None,
+                    raw_output=output,
+                )
+            else:
+                # Plain text output
+                return AIResult(
+                    success=result.returncode == 0,
+                    response=result.stdout.strip(),
+                    tokens_used=None,
+                    error=None if result.returncode == 0 else result.stderr,
+                    raw_output=result.stdout,
+                )
+
+        except FileNotFoundError:
+            return AIResult(
+                success=False,
+                response="",
+                tokens_used=None,
+                error="Claude CLI not found. Install Claude Code from: https://claude.com/claude-code",
+                raw_output=None,
+            )
+        except subprocess.TimeoutExpired as e:
+            return AIResult(
+                success=False,
+                response="",
+                tokens_used=None,
+                error=f"Timed out after {timeout} seconds",
+                raw_output={
+                    "partial_stdout": e.stdout.decode() if e.stdout else None,
+                    "partial_stderr": e.stderr.decode() if e.stderr else None,
+                }
+                if e.stdout or e.stderr
+                else None,
+            )
+        except Exception as e:
+            return AIResult(
+                success=False,
+                response="",
+                tokens_used=None,
+                error=f"Unexpected error: {type(e).__name__}: {e}",
+                raw_output=None,
+            )