tactus 0.31.2__py3-none-any.whl

tactus/providers/bedrock.py

@@ -0,0 +1,117 @@
+"""
+AWS Bedrock provider implementation.
+"""
+
+import os
+from typing import Optional, Dict
+from tactus.providers.base import ProviderConfig
+
+
+class BedrockProvider:
+    """AWS Bedrock LLM provider."""
+
+    PROVIDER_NAME = "bedrock"
+
+    # Known Bedrock models (Claude via Bedrock)
+    KNOWN_MODELS = {
+        "anthropic.claude-haiku-4-5-20251001-v1:0",  # Claude 4.5 Haiku
+        "anthropic.claude-3-5-sonnet-20240620-v1:0",
+        "anthropic.claude-3-5-haiku-20241022-v1:0",
+        "anthropic.claude-3-sonnet-20240229-v1:0",
+        "anthropic.claude-3-haiku-20240307-v1:0",
+        "anthropic.claude-v2",
+        "anthropic.claude-v2:1",
+        "anthropic.claude-instant-v1",
+    }
+
+    @staticmethod
+    def validate_model(model_id: str) -> bool:
+        """
+        Validate that a model ID is valid for Bedrock.
+
+        Args:
+            model_id: The model identifier to validate
+
+        Returns:
+            True if valid (starts with 'anthropic.' or in known models)
+        """
+        return (
+            model_id in BedrockProvider.KNOWN_MODELS
+            or model_id.startswith("anthropic.")
+            or model_id.startswith("amazon.")
+            or model_id.startswith("meta.")
+            or model_id.startswith("cohere.")
+        )
+
+    @staticmethod
+    def get_required_credentials() -> list[str]:
+        """
+        Get list of required credential keys for Bedrock.
+
+        Returns:
+            List containing AWS credential keys
+        """
+        return [
+            "AWS_ACCESS_KEY_ID",
+            "AWS_SECRET_ACCESS_KEY",
+            "AWS_DEFAULT_REGION",  # Optional but recommended
+        ]
+
+    @staticmethod
+    def check_credentials() -> bool:
+        """
+        Check if Bedrock credentials are available.
+
+        Returns:
+            True if AWS credentials are set
+        """
+        return bool(os.environ.get("AWS_ACCESS_KEY_ID") and os.environ.get("AWS_SECRET_ACCESS_KEY"))
+
+    @staticmethod
+    def create_config(
+        model_id: str,
+        credentials: Optional[Dict[str, str]] = None,
+        region: Optional[str] = None,
+        **kwargs,
+    ) -> ProviderConfig:
+        """
+        Create a Bedrock provider configuration.
+
+        Args:
+            model_id: Model identifier (e.g., 'anthropic.claude-3-5-sonnet-20240620-v1:0')
+            credentials: Optional credentials dict with AWS keys
+            region: AWS region (defaults to us-east-1)
+            **kwargs: Additional config
+
+        Returns:
+            ProviderConfig instance
+        """
+        # Get credentials from dict or environment
+        creds = {}
+        if credentials:
+            if "access_key_id" in credentials:
+                creds["access_key_id"] = credentials["access_key_id"]
+            if "secret_access_key" in credentials:
+                creds["secret_access_key"] = credentials["secret_access_key"]
+            # Also check uppercase keys
+            if "AWS_ACCESS_KEY_ID" in credentials:
+                creds["access_key_id"] = credentials["AWS_ACCESS_KEY_ID"]
+            if "AWS_SECRET_ACCESS_KEY" in credentials:
+                creds["secret_access_key"] = credentials["AWS_SECRET_ACCESS_KEY"]
+
+        # Get region from parameter, credentials, or environment
+        if not region:
+            if credentials and "region" in credentials:
+                region = credentials["region"]
+            elif credentials and "AWS_DEFAULT_REGION" in credentials:
+                region = credentials["AWS_DEFAULT_REGION"]
+            else:
+                region = os.environ.get("AWS_DEFAULT_REGION", "us-east-1")
+
+        return ProviderConfig(
+            provider_name=BedrockProvider.PROVIDER_NAME,
+            model_id=model_id,
+            credentials=creds if creds else None,
+            region=region,
+            additional_config=kwargs,
+        )

tactus/providers/google.py

@@ -0,0 +1,105 @@
+"""
+Google Gemini provider implementation.
+"""
+
+import os
+from typing import Optional, Dict
+from tactus.providers.base import ProviderConfig
+
+
+class GoogleProvider:
+    """Google Gemini LLM provider."""
+
+    PROVIDER_NAME = "google-gla"  # Google GenAI (not Vertex AI)
+
+    # Known Gemini models
+    # Reference: https://ai.google.dev/gemini-api/docs/models/gemini
+    KNOWN_MODELS = {
+        # Gemini 3 models (preview)
+        "gemini-3-pro-preview",
+        "gemini-3-flash-preview",
+        "gemini-3-pro-image-preview",
+        # Gemini 2.0 models
+        "gemini-2.0-flash-exp",
+        "gemini-2.0-flash-thinking-exp",
+        "gemini-2.0-flash",
+        "gemini-2.0-flash-lite",
+        # Gemini 1.5 models
+        "gemini-1.5-pro",
+        "gemini-1.5-flash",
+        "gemini-1.5-flash-8b",
+        # Experimental models
+        "gemini-exp-1206",
+        "gemini-exp-1121",
+    }
+
+    @staticmethod
+    def validate_model(model_id: str) -> bool:
+        """
+        Validate that a model ID is valid for Google Gemini.
+
+        Args:
+            model_id: The model identifier to validate
+
+        Returns:
+            True if valid (starts with 'gemini' or in known models)
+        """
+        return model_id in GoogleProvider.KNOWN_MODELS or model_id.startswith("gemini")
+
+    @staticmethod
+    def get_required_credentials() -> list[str]:
+        """
+        Get list of required credential keys for Google Gemini.
+
+        Returns:
+            List containing 'GOOGLE_API_KEY'
+        """
+        return ["GOOGLE_API_KEY"]
+
+    @staticmethod
+    def check_credentials() -> bool:
+        """
+        Check if Google credentials are available.
+
+        Returns:
+            True if GOOGLE_API_KEY is set
+        """
+        return bool(os.environ.get("GOOGLE_API_KEY"))
+
+    @staticmethod
+    def create_config(
+        model_id: str,
+        credentials: Optional[Dict[str, str]] = None,
+        region: Optional[str] = None,
+        **kwargs,
+    ) -> ProviderConfig:
+        """
+        Create a Google Gemini provider configuration.
+
+        Args:
+            model_id: Model identifier (e.g., 'gemini-2.0-flash-exp', 'gemini-1.5-pro')
+            credentials: Optional credentials dict with 'api_key'
+            region: Ignored for Google (no regional endpoints)
+            **kwargs: Additional config (ignored)
+
+        Returns:
+            ProviderConfig instance
+        """
+        # Get API key from credentials or environment
+        api_key = None
+        if credentials and "api_key" in credentials:
+            api_key = credentials["api_key"]
+        elif not os.environ.get("GOOGLE_API_KEY"):
+            # Try to get from credentials dict with uppercase key
+            if credentials and "GOOGLE_API_KEY" in credentials:
+                api_key = credentials["GOOGLE_API_KEY"]
+
+        creds = {"api_key": api_key} if api_key else None
+
+        return ProviderConfig(
+            provider_name=GoogleProvider.PROVIDER_NAME,
+            model_id=model_id,
+            credentials=creds,
+            region=None,  # Google doesn't use regions
+            additional_config=kwargs,
+        )

tactus/providers/openai.py

@@ -0,0 +1,98 @@
+"""
+OpenAI provider implementation.
+"""
+
+import os
+from typing import Optional, Dict
+from tactus.providers.base import ProviderConfig
+
+
+class OpenAIProvider:
+    """OpenAI LLM provider."""
+
+    PROVIDER_NAME = "openai"
+
+    # Known OpenAI models
+    KNOWN_MODELS = {
+        "gpt-4o",
+        "gpt-4o-mini",
+        "gpt-4-turbo",
+        "gpt-4-turbo-preview",
+        "gpt-4",
+        "gpt-3.5-turbo",
+        "o1",
+        "o1-mini",
+        "o1-preview",
+    }
+
+    @staticmethod
+    def validate_model(model_id: str) -> bool:
+        """
+        Validate that a model ID is valid for OpenAI.
+
+        Args:
+            model_id: The model identifier to validate
+
+        Returns:
+            True if valid (starts with 'gpt' or 'o1'), False otherwise
+        """
+        # Accept known models or anything starting with gpt/o1
+        return model_id in OpenAIProvider.KNOWN_MODELS or model_id.startswith(("gpt", "o1"))
+
+    @staticmethod
+    def get_required_credentials() -> list[str]:
+        """
+        Get list of required credential keys for OpenAI.
+
+        Returns:
+            List containing 'OPENAI_API_KEY'
+        """
+        return ["OPENAI_API_KEY"]
+
+    @staticmethod
+    def check_credentials() -> bool:
+        """
+        Check if OpenAI credentials are available.
+
+        Returns:
+            True if OPENAI_API_KEY is set
+        """
+        return bool(os.environ.get("OPENAI_API_KEY"))
+
+    @staticmethod
+    def create_config(
+        model_id: str,
+        credentials: Optional[Dict[str, str]] = None,
+        region: Optional[str] = None,
+        **kwargs,
+    ) -> ProviderConfig:
+        """
+        Create an OpenAI provider configuration.
+
+        Args:
+            model_id: Model identifier (e.g., 'gpt-4o')
+            credentials: Optional credentials dict with 'api_key'
+            region: Ignored for OpenAI
+            **kwargs: Additional config (ignored)
+
+        Returns:
+            ProviderConfig instance
+        """
+        # Get API key from credentials or environment
+        api_key = None
+        if credentials and "api_key" in credentials:
+            api_key = credentials["api_key"]
+        elif not os.environ.get("OPENAI_API_KEY"):
+            # Try to get from credentials dict with uppercase key
+            if credentials and "OPENAI_API_KEY" in credentials:
+                api_key = credentials["OPENAI_API_KEY"]
+
+        creds = {"api_key": api_key} if api_key else None
+
+        return ProviderConfig(
+            provider_name=OpenAIProvider.PROVIDER_NAME,
+            model_id=model_id,
+            credentials=creds,
+            region=None,  # OpenAI doesn't use regions
+            additional_config=kwargs,
+        )

tactus/sandbox/__init__.py

@@ -0,0 +1,63 @@
+"""
+Docker sandbox module for Tactus.
+
+Provides container-based isolation for procedure execution, protecting
+the host system from potentially unsafe agent tool operations.
+
+Usage:
+    from tactus.sandbox import (
+        is_docker_available,
+        SandboxConfig,
+        ContainerRunner,
+        SandboxError,
+        SandboxUnavailableError,
+    )
+
+    # Check if Docker is available
+    available, reason = is_docker_available()
+
+    # Configure sandbox
+    config = SandboxConfig(enabled=True)
+
+    # Run procedure in sandbox
+    runner = ContainerRunner(config)
+    result = await runner.run(source, params)
+"""
+
+from .config import SandboxConfig, SandboxLimits, get_default_sandbox_config
+from .docker_manager import (
+    DockerManager,
+    is_docker_available,
+    DEFAULT_IMAGE_NAME,
+    DEFAULT_IMAGE_TAG,
+)
+from .container_runner import (
+    ContainerRunner,
+    SandboxError,
+    SandboxUnavailableError,
+)
+from .protocol import (
+    ExecutionRequest,
+    ExecutionResult,
+    ExecutionStatus,
+)
+
+__all__ = [
+    # Config
+    "SandboxConfig",
+    "SandboxLimits",
+    "get_default_sandbox_config",
+    # Docker management
+    "DockerManager",
+    "is_docker_available",
+    "DEFAULT_IMAGE_NAME",
+    "DEFAULT_IMAGE_TAG",
+    # Container execution
+    "ContainerRunner",
+    "SandboxError",
+    "SandboxUnavailableError",
+    # Protocol
+    "ExecutionRequest",
+    "ExecutionResult",
+    "ExecutionStatus",
+]

tactus/sandbox/config.py

@@ -0,0 +1,171 @@
+"""
+Sandbox configuration model for Docker-based isolation.
+
+Defines the SandboxConfig Pydantic model for controlling container execution.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class SandboxLimits(BaseModel):
+    """Resource limits for the sandbox container."""
+
+    memory: str = Field(default="2g", description="Memory limit (e.g., '2g', '512m')")
+    cpus: str = Field(default="2", description="CPU limit (e.g., '2', '0.5')")
+
+
+class SandboxConfig(BaseModel):
+    """
+    Configuration for Docker sandbox execution.
+
+    Controls whether and how procedures run in isolated Docker containers.
+    """
+
+    # Core settings
+    # Security model:
+    # - enabled=None (default): Sandbox AUTO (use if available; otherwise run without isolation)
+    # - enabled=True: Sandbox REQUIRED, error if Docker unavailable
+    # - enabled=False: Sandbox explicitly disabled (security risk acknowledged)
+    enabled: Optional[bool] = Field(
+        default=None,
+        description="Enable sandbox mode. None=auto, True=required, False=disabled",
+    )
+
+    # Docker image settings
+    image: str = Field(
+        default="tactus-sandbox:local",
+        description="Docker image to use for sandbox execution",
+    )
+
+    # MCP server settings
+    mcp_servers_path: str = Field(
+        default="~/.tactus/mcp-servers",
+        description="Path to directory containing MCP server code and dependencies",
+    )
+
+    # Additional environment variables to pass to container
+    env: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional environment variables to pass to the container",
+    )
+
+    # Volume mount settings
+    mount_current_dir: bool = Field(
+        default=True,
+        description="Mount current directory to /workspace:rw by default. Set false to disable.",
+    )
+
+    # Additional volume mounts
+    volumes: List[str] = Field(
+        default_factory=list,
+        description="Additional volume mounts in 'host:container:mode' format",
+    )
+
+    # Network mode
+    network: str = Field(
+        default="bridge",
+        description="Docker network mode (bridge for broker access, none blocks all network)",
+    )
+
+    # Broker transport (how the secretless runtime reaches the host broker)
+    # - tcp: Standard mode using TCP sockets (works locally and in K8s/cloud)
+    # - tls: TCP with TLS encryption (for production deployments)
+    # - stdio: Legacy mode using stdin/stdout (deprecated due to buffering issues)
+    broker_transport: str = Field(
+        default="tcp",
+        description="Broker transport for the runtime container: tcp, tls, or stdio (deprecated)",
+    )
+    broker_host: str = Field(
+        default="host.docker.internal",
+        description="Broker hostname for tcp/tls (as seen from inside the container)",
+    )
+    broker_bind_host: str = Field(
+        default="0.0.0.0",
+        description="Bind address for the host-side broker server in tcp/tls modes",
+    )
+    broker_port: int = Field(
+        default=0,
+        description="Port for the host-side broker server in tcp/tls modes (0=auto)",
+    )
+    broker_tls_cert_file: Optional[str] = Field(
+        default=None,
+        description="TLS certificate file for broker (PEM). Required when broker_transport='tls'",
+    )
+    broker_tls_key_file: Optional[str] = Field(
+        default=None,
+        description="TLS private key file for broker (PEM). Required when broker_transport='tls'",
+    )
+
+    # Resource limits
+    limits: SandboxLimits = Field(
+        default_factory=SandboxLimits,
+        description="Resource limits for the container",
+    )
+
+    # Timeout for container execution (seconds)
+    timeout: int = Field(
+        default=3600,
+        description="Maximum execution time in seconds before container is killed",
+    )
+
+    # Development mode: mount live Tactus source code
+    dev_mode: bool = Field(
+        default=False,
+        description="Enable development mode: mount live Tactus source code instead of using baked-in version",
+    )
+
+    def get_mcp_servers_path(self) -> Path:
+        """Get the expanded MCP servers path."""
+        return Path(self.mcp_servers_path).expanduser()
+
+    def is_explicitly_disabled(self) -> bool:
+        """
+        Check if sandbox has been explicitly disabled by the user.
+
+        Returns:
+            True if user set enabled=False (acknowledging security risk).
+        """
+        return self.enabled is False
+
+    def should_use_sandbox(self, docker_available: bool) -> bool:
+        """
+        Determine if sandbox should be used for execution.
+
+        Args:
+            docker_available: Whether Docker is available and running.
+
+        Returns:
+            True if sandbox should be used.
+        """
+        if self.is_explicitly_disabled():
+            return False
+        return docker_available
+
+    def should_error_if_unavailable(self) -> bool:
+        """
+        Determine if we should error when Docker is unavailable.
+
+        Returns:
+            True if Docker unavailability should be a fatal error.
+            This is True only when the user explicitly requires the sandbox (enabled=True).
+        """
+        return self.enabled is True
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    @model_validator(mode="after")
+    def add_default_volumes(self):
+        """Add default volume mounts based on config flags."""
+        if self.mount_current_dir:
+            # Insert at beginning so user volumes can override
+            if ".:/workspace:rw" not in self.volumes:
+                self.volumes.insert(0, ".:/workspace:rw")
+        return self
+
+
+def get_default_sandbox_config() -> SandboxConfig:
+    """Get the default sandbox configuration."""
+    return SandboxConfig()