tactus 0.31.0__py3-none-any.whl

tactus/sandbox/docker_manager.py

@@ -0,0 +1,433 @@
+"""
+Docker management utilities for sandbox execution.
+
+Handles Docker availability detection, image building, and version management.
+"""
+
+import hashlib
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Tuple, Optional
+
+logger = logging.getLogger(__name__)
+
+# Default image name for local sandbox
+DEFAULT_IMAGE_NAME = "tactus-sandbox"
+DEFAULT_IMAGE_TAG = "local"
+
+
+def calculate_source_hash(tactus_root: Path) -> str:
+    """
+    Calculate hash of Tactus source files for change detection.
+
+    This enables fast, automatic rebuilds when code changes without
+    requiring manual version bumps or rebuild commands.
+
+    Args:
+        tactus_root: Root directory of the Tactus package
+
+    Returns:
+        Short hash (16 chars) representing the current state of source code
+    """
+    # Key paths that affect sandbox behavior
+    paths_to_hash = [
+        tactus_root / "tactus" / "dspy",
+        tactus_root / "tactus" / "adapters",
+        tactus_root / "tactus" / "core",
+        tactus_root / "tactus" / "primitives",
+        tactus_root / "tactus" / "sandbox",
+        tactus_root / "tactus" / "stdlib",
+        tactus_root / "tactus" / "docker",
+        tactus_root / "pyproject.toml",  # Dependencies affect sandbox
+    ]
+
+    hasher = hashlib.sha256()
+
+    for path in sorted(paths_to_hash):
+        if not path.exists():
+            continue
+
+        if path.is_file():
+            # Hash file contents
+            hasher.update(path.read_bytes())
+        elif path.is_dir():
+            # Hash directory files (recursively), skipping caches.
+            for file in sorted(path.rglob("*")):
+                if not file.is_file():
+                    continue
+                if "__pycache__" in file.parts:
+                    continue
+                if file.suffix == ".pyc":
+                    continue
+                if file.name == ".DS_Store":
+                    continue
+
+                # Hash relative path + contents for reproducibility
+                rel_path = str(file.relative_to(tactus_root))
+                hasher.update(rel_path.encode())
+                hasher.update(file.read_bytes())
+
+    # Return short hash (16 chars is plenty for collision avoidance)
+    return hasher.hexdigest()[:16]
+
+
+def is_docker_available() -> Tuple[bool, str]:
+    """
+    Check if Docker is available and running.
+
+    Returns:
+        Tuple of (available, reason) where:
+        - available: True if Docker is ready to use
+        - reason: Empty string if available, otherwise explanation of why not
+    """
+    # Check if docker CLI exists
+    docker_path = shutil.which("docker")
+    if not docker_path:
+        return False, "Docker CLI not found in PATH"
+
+    try:
+        # Check if Docker daemon is running
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            # Parse common error messages
+            stderr = result.stderr.lower()
+            if "cannot connect" in stderr or "connection refused" in stderr:
+                return False, "Docker daemon not running"
+            if "permission denied" in stderr:
+                return (
+                    False,
+                    "Permission denied accessing Docker (try: sudo usermod -aG docker $USER)",
+                )
+            return False, f"Docker error: {result.stderr.strip()}"
+
+        return True, ""
+
+    except subprocess.TimeoutExpired:
+        return False, "Docker daemon not responding (timeout after 10s)"
+    except FileNotFoundError:
+        return False, "Docker CLI not found"
+    except Exception as e:
+        return False, f"Docker check failed: {e}"
+
+
+class DockerManager:
+    """
+    Manages Docker images for sandbox execution.
+
+    Handles image building, version checking, and cleanup.
+    """
+
+    def __init__(
+        self,
+        image_name: str = DEFAULT_IMAGE_NAME,
+        image_tag: str = DEFAULT_IMAGE_TAG,
+    ):
+        """
+        Initialize Docker manager.
+
+        Args:
+            image_name: Base name for Docker images
+            image_tag: Tag for the image (e.g., 'local', 'v1.0.0')
+        """
+        self.image_name = image_name
+        self.image_tag = image_tag
+        self.full_image_name = f"{image_name}:{image_tag}"
+
+    def image_exists(self) -> bool:
+        """Check if the sandbox image exists locally."""
+        try:
+            result = subprocess.run(
+                ["docker", "image", "inspect", self.full_image_name],
+                capture_output=True,
+                timeout=10,
+            )
+            return result.returncode == 0
+        except (subprocess.TimeoutExpired, Exception):
+            return False
+
+    def get_image_version(self) -> Optional[str]:
+        """
+        Get the Tactus version label from the existing image.
+
+        Returns:
+            Version string if found, None otherwise.
+        """
+        try:
+            result = subprocess.run(
+                [
+                    "docker",
+                    "image",
+                    "inspect",
+                    "--format",
+                    '{{index .Config.Labels "tactus.version"}}',
+                    self.full_image_name,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+            return None
+        except Exception:
+            return None
+
+    def get_image_source_hash(self) -> Optional[str]:
+        """
+        Get the source hash label from the existing image.
+
+        Returns:
+            Source hash string if found, None otherwise.
+        """
+        try:
+            result = subprocess.run(
+                [
+                    "docker",
+                    "image",
+                    "inspect",
+                    "--format",
+                    '{{index .Config.Labels "tactus.source_hash"}}',
+                    self.full_image_name,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+            return None
+        except Exception:
+            return None
+
+    def needs_rebuild(self, current_version: str, current_hash: Optional[str] = None) -> bool:
+        """
+        Check if the image needs to be rebuilt.
+
+        Checks both version and source hash (if provided) to determine
+        if a rebuild is necessary. This enables automatic rebuilds when
+        code changes without requiring manual version bumps.
+
+        Args:
+            current_version: Current Tactus version.
+            current_hash: Optional source hash of current code. If provided,
+                         will trigger rebuild when hash doesn't match.
+
+        Returns:
+            True if image should be rebuilt.
+        """
+        if not self.image_exists():
+            return True
+
+        # Check version mismatch
+        image_version = self.get_image_version()
+        if image_version is None:
+            return True
+
+        if image_version != current_version:
+            return True
+
+        # Check source hash mismatch (if hash checking is enabled)
+        if current_hash is not None:
+            image_hash = self.get_image_source_hash()
+            if image_hash is None:
+                # Old image without hash label - rebuild to add it
+                logger.debug("Image missing source hash label, rebuild needed")
+                return True
+
+            if image_hash != current_hash:
+                logger.debug(f"Source hash mismatch: {image_hash} != {current_hash}")
+                return True
+
+        return False
+
+    def build_image(
+        self,
+        dockerfile_path: Path,
+        context_path: Path,
+        version: str,
+        source_hash: Optional[str] = None,
+        verbose: bool = False,
+    ) -> Tuple[bool, str]:
+        """
+        Build the sandbox Docker image.
+
+        Args:
+            dockerfile_path: Path to the Dockerfile
+            context_path: Build context path (usually the Tactus package root)
+            version: Tactus version to label the image with
+            source_hash: Optional source hash to label the image with for change detection
+            verbose: If True, stream build output
+
+        Returns:
+            Tuple of (success, message)
+        """
+        if not dockerfile_path.exists():
+            return False, f"Dockerfile not found: {dockerfile_path}"
+
+        if not context_path.exists():
+            return False, f"Build context not found: {context_path}"
+
+        logger.info(f"Building sandbox image: {self.full_image_name}")
+
+        cmd = [
+            "docker",
+            "build",
+            "-t",
+            self.full_image_name,
+            "-f",
+            str(dockerfile_path),
+            "--label",
+            f"tactus.version={version}",
+        ]
+
+        # Add source hash label if provided
+        if source_hash:
+            cmd.extend(["--label", f"tactus.source_hash={source_hash}"])
+
+        cmd.append(str(context_path))
+
+        try:
+            if verbose:
+                # Stream output in real-time
+                process = subprocess.Popen(
+                    cmd,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.STDOUT,
+                    text=True,
+                )
+                output_lines = []
+                for line in iter(process.stdout.readline, ""):
+                    if line:
+                        output_lines.append(line.rstrip())
+                        logger.info(line.rstrip())
+                process.wait()
+                returncode = process.returncode
+                output = "\n".join(output_lines)
+            else:
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=600,  # 10 minute timeout for builds
+                )
+                returncode = result.returncode
+                output = result.stderr if result.returncode != 0 else result.stdout
+
+            if returncode == 0:
+                logger.info(f"Successfully built: {self.full_image_name}")
+                return True, f"Successfully built {self.full_image_name}"
+            else:
+                return False, f"Build failed: {output}"
+
+        except subprocess.TimeoutExpired:
+            return False, "Build timed out after 10 minutes"
+        except Exception as e:
+            return False, f"Build failed: {e}"
+
+    def ensure_image_exists(
+        self,
+        dockerfile_path: Path,
+        context_path: Path,
+        version: str,
+        force_rebuild: bool = False,
+    ) -> Tuple[bool, str]:
+        """
+        Ensure the sandbox image exists, building if necessary.
+
+        Args:
+            dockerfile_path: Path to the Dockerfile
+            context_path: Build context path
+            version: Current Tactus version
+            force_rebuild: If True, rebuild even if image exists
+
+        Returns:
+            Tuple of (success, message)
+        """
+        if force_rebuild or self.needs_rebuild(version):
+            return self.build_image(dockerfile_path, context_path, version)
+
+        return True, f"Image {self.full_image_name} is up to date"
+
+    def remove_image(self) -> Tuple[bool, str]:
+        """
+        Remove the sandbox image.
+
+        Returns:
+            Tuple of (success, message)
+        """
+        if not self.image_exists():
+            return True, f"Image {self.full_image_name} does not exist"
+
+        try:
+            result = subprocess.run(
+                ["docker", "rmi", self.full_image_name],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            if result.returncode == 0:
+                return True, f"Removed {self.full_image_name}"
+            else:
+                return False, f"Failed to remove image: {result.stderr}"
+        except Exception as e:
+            return False, f"Failed to remove image: {e}"
+
+    def cleanup_old_images(self, keep_tags: Optional[list] = None) -> int:
+        """
+        Remove old sandbox images, keeping specified tags.
+
+        Args:
+            keep_tags: List of tags to keep. Defaults to ['local'].
+
+        Returns:
+            Number of images removed.
+        """
+        if keep_tags is None:
+            keep_tags = [DEFAULT_IMAGE_TAG]
+
+        try:
+            # List all images with our base name
+            result = subprocess.run(
+                [
+                    "docker",
+                    "images",
+                    "--format",
+                    "{{.Repository}}:{{.Tag}}",
+                    self.image_name,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode != 0:
+                return 0
+
+            removed = 0
+            for line in result.stdout.strip().split("\n"):
+                if not line:
+                    continue
+                # Parse image:tag
+                if ":" in line:
+                    _, tag = line.rsplit(":", 1)
+                    if tag not in keep_tags:
+                        rm_result = subprocess.run(
+                            ["docker", "rmi", line],
+                            capture_output=True,
+                            timeout=30,
+                        )
+                        if rm_result.returncode == 0:
+                            removed += 1
+                            logger.info(f"Removed old image: {line}")
+
+            return removed
+
+        except Exception as e:
+            logger.warning(f"Failed to cleanup old images: {e}")
+            return 0

tactus/sandbox/entrypoint.py

@@ -0,0 +1,227 @@
+"""
+Container entrypoint for sandboxed procedure execution.
+
+This module is run inside the Docker container. It:
+1. Reads an ExecutionRequest from stdin (JSON)
+2. Executes the procedure using TactusRuntime
+3. Writes an ExecutionResult to stdout (JSON with markers)
+
+Usage:
+    python -m tactus.sandbox.entrypoint
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+import time
+import traceback
+from typing import Any, Dict, Optional
+
+from tactus.sandbox.protocol import ExecutionResult
+
+# Configure logging to stderr (stdout is reserved for result)
+_LOG_LEVELS = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warning": logging.WARNING,
+    "warn": logging.WARNING,
+    "error": logging.ERROR,
+    "critical": logging.CRITICAL,
+}
+
+_log_level_str = os.environ.get("TACTUS_LOG_LEVEL", "info").strip().lower()
+_log_level = _LOG_LEVELS.get(_log_level_str, logging.INFO)
+
+# CloudWatch-friendly, one line per record.
+_log_fmt = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+
+logging.basicConfig(
+    level=_log_level,
+    format=_log_fmt,
+    stream=sys.stderr,
+)
+logger = logging.getLogger(__name__)
+
+# Keep container stderr focused on procedure logs by default.
+# Use `TACTUS_LOG_LEVEL=debug` to include internal runtime logs.
+if _log_level > logging.DEBUG:
+    logging.getLogger("tactus.core").setLevel(logging.WARNING)
+    logging.getLogger("tactus.primitives").setLevel(logging.WARNING)
+    logging.getLogger("tactus.stdlib").setLevel(logging.WARNING)
+
+
+def read_request_from_stdin() -> Optional[Dict[str, Any]]:
+    """Read the execution request from stdin as JSON."""
+    import json
+
+    try:
+        # Read exactly one JSON message (the initial ExecutionRequest).
+        # Keep stdin open for broker responses during execution.
+        input_data = sys.stdin.readline()
+        if not input_data.strip():
+            logger.error("No input received on stdin")
+            return None
+
+        return json.loads(input_data)
+    except json.JSONDecodeError as e:
+        logger.error(f"Failed to parse JSON from stdin: {e}")
+        return None
+
+
+def write_result_to_stdout(result: ExecutionResult) -> None:
+    """Write the execution result to stdout with markers."""
+    from tactus.sandbox.protocol import wrap_result_for_stdout
+
+    output = wrap_result_for_stdout(result)
+    sys.stdout.write(output)
+    sys.stdout.flush()
+
+
+async def execute_procedure(
+    source: str,
+    params: Dict[str, Any],
+    source_file_path: Optional[str] = None,
+    format: str = "lua",
+) -> Any:
+    """
+    Execute a procedure using TactusRuntime.
+
+    Args:
+        source: Procedure source code
+        params: Input parameters
+        config: Runtime configuration
+        mcp_servers: MCP server configurations
+        source_file_path: Original source file path
+        format: Source format ("lua" or "yaml")
+
+    Returns:
+        Procedure execution result
+    """
+    from tactus.core import TactusRuntime
+    from tactus.adapters.memory import MemoryStorage
+    from tactus.adapters.broker_log import BrokerLogHandler
+    from tactus.adapters.http_callback_log import HTTPCallbackLogHandler
+    from tactus.adapters.cost_collector_log import CostCollectorLogHandler
+
+    # Create a unique procedure ID
+    import uuid
+
+    procedure_id = str(uuid.uuid4())
+
+    # Prefer HTTP callbacks when configured (IDE streaming with container networking).
+    log_handler = HTTPCallbackLogHandler.from_environment()
+    if log_handler:
+        logger.info(
+            f"[SANDBOX] Using HTTP callback log handler: {os.environ.get('TACTUS_CALLBACK_URL')}"
+        )
+    else:
+        # Otherwise, try broker socket streaming (works without container networking, e.g. stdio/UDS).
+        log_handler = BrokerLogHandler.from_environment()
+        if log_handler:
+            logger.info(
+                f"[SANDBOX] Using broker log handler: {os.environ.get('TACTUS_BROKER_SOCKET')}"
+            )
+        else:
+            # Provide cost collection + checkpoint event handling even without IDE callbacks.
+            log_handler = CostCollectorLogHandler()
+            logger.info("[SANDBOX] No callback configured; using CostCollectorLogHandler")
+
+    # Create runtime with log handler for event streaming
+    runtime = TactusRuntime(
+        procedure_id=procedure_id,
+        storage_backend=MemoryStorage(),
+        mcp_servers=None,
+        external_config={},
+        source_file_path=source_file_path,
+        log_handler=log_handler,  # Enable event streaming to IDE
+    )
+
+    # Execute procedure
+    result = await runtime.execute(
+        source=source,
+        context=params,
+        format=format,
+    )
+
+    return result
+
+
+async def main_async() -> int:
+    """Main async entrypoint."""
+    from tactus.sandbox.protocol import (
+        ExecutionRequest,
+        ExecutionResult,
+    )
+
+    start_time = time.time()
+
+    # Read request from stdin
+    request_data = read_request_from_stdin()
+    if request_data is None:
+        result = ExecutionResult.failure(
+            error="Failed to read execution request from stdin",
+            error_type="InputError",
+        )
+        write_result_to_stdout(result)
+        return 1
+
+    try:
+        # Parse request
+        request = ExecutionRequest(**request_data)
+        logger.info(f"Executing procedure (id={request.execution_id})")
+
+        # Execute procedure
+        proc_result = await execute_procedure(
+            source=request.source,
+            params=request.params,
+            source_file_path=request.source_file_path,
+            format=request.format,
+        )
+
+        # Create success result
+        duration = time.time() - start_time
+        result = ExecutionResult.success(
+            result=proc_result,
+            duration_seconds=duration,
+        )
+
+        write_result_to_stdout(result)
+        return 0
+
+    except Exception as e:
+        logger.exception(f"Procedure execution failed: {e}")
+
+        duration = time.time() - start_time
+        result = ExecutionResult.failure(
+            error=str(e),
+            error_type=type(e).__name__,
+            traceback=traceback.format_exc(),
+            duration_seconds=duration,
+        )
+
+        write_result_to_stdout(result)
+        return 1
+    finally:
+        # Ensure stdio broker transport is closed cleanly to avoid pending-task warnings.
+        try:
+            from tactus.broker.client import close_stdio_transport
+
+            await close_stdio_transport()
+        except Exception:
+            pass
+
+
+def main() -> int:
+    """Synchronous main entrypoint."""
+    try:
+        return asyncio.run(main_async())
+    except KeyboardInterrupt:
+        logger.info("Execution interrupted")
+        return 130  # Standard interrupt exit code
+
+
+if __name__ == "__main__":
+    sys.exit(main())