tactus 0.31.0__py3-none-any.whl

tactus/core/template_resolver.py

@@ -0,0 +1,142 @@
+"""
+Template variable resolution for DSL strings.
+
+Resolves template markers like {params.topic}, {state.count}, etc.
+in system prompts, HITL messages, and other template strings.
+"""
+
+import re
+from typing import Any, Optional
+
+
+class TemplateResolver:
+    """Resolves template variables in strings."""
+
+    # Pattern matches {namespace.key} or {namespace.key.nested}
+    TEMPLATE_PATTERN = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)\}")
+
+    def __init__(
+        self,
+        params: Optional[dict[str, Any]] = None,
+        state: Optional[dict[str, Any]] = None,
+        outputs: Optional[dict[str, Any]] = None,
+        context: Optional[dict[str, Any]] = None,
+        prepared: Optional[dict[str, Any]] = None,
+        env: Optional[dict[str, str]] = None,
+    ):
+        """
+        Initialize template resolver with available namespaces.
+
+        Args:
+            params: Input parameters
+            state: Procedure state
+            outputs: Output values (for return_prompt)
+            context: Runtime context
+            prepared: Agent prepare hook output
+            env: Environment variables
+        """
+        self.namespaces = {
+            "params": params or {},
+            "state": state or {},
+            "output": outputs or {},
+            "context": context or {},
+            "prepared": prepared or {},
+            "env": env or {},
+        }
+
+    def resolve(self, template: str) -> str:
+        """
+        Resolve all template variables in a string.
+
+        Args:
+            template: String with {namespace.key} markers
+
+        Returns:
+            String with markers replaced by values
+
+        Example:
+            >>> resolver = TemplateResolver(params={"topic": "AI"})
+            >>> resolver.resolve("Research: {params.topic}")
+            "Research: AI"
+        """
+        if not template:
+            return template
+
+        def replace_match(match):
+            path = match.group(1)
+            value = self._get_value(path)
+            if value is None:
+                # Keep the marker if value not found
+                return match.group(0)
+            return str(value)
+
+        return self.TEMPLATE_PATTERN.sub(replace_match, template)
+
+    def _get_value(self, path: str) -> Any:
+        """
+        Get value from namespaces using dot notation.
+
+        Args:
+            path: Dot-separated path like "params.topic" or "state.count"
+
+        Returns:
+            Value at path, or None if not found
+        """
+        parts = path.split(".")
+        if not parts:
+            return None
+
+        # First part is the namespace
+        namespace_name = parts[0]
+        namespace = self.namespaces.get(namespace_name)
+        if namespace is None:
+            return None
+
+        # Navigate nested keys
+        current = namespace
+        for part in parts[1:]:
+            if isinstance(current, dict):
+                current = current.get(part)
+            else:
+                # Can't navigate further
+                return None
+
+            if current is None:
+                return None
+
+        return current
+
+
+def resolve_template(
+    template: str,
+    params: Optional[dict[str, Any]] = None,
+    state: Optional[dict[str, Any]] = None,
+    outputs: Optional[dict[str, Any]] = None,
+    context: Optional[dict[str, Any]] = None,
+    prepared: Optional[dict[str, Any]] = None,
+    env: Optional[dict[str, str]] = None,
+) -> str:
+    """
+    Convenience function to resolve a template string.
+
+    Args:
+        template: String with {namespace.key} markers
+        params: Input parameters
+        state: Procedure state
+        outputs: Output values
+        context: Runtime context
+        prepared: Agent prepare hook output
+        env: Environment variables
+
+    Returns:
+        Resolved string
+    """
+    resolver = TemplateResolver(
+        params=params,
+        state=state,
+        outputs=outputs,
+        context=context,
+        prepared=prepared,
+        env=env,
+    )
+    return resolver.resolve(template)

tactus/core/yaml_parser.py

@@ -0,0 +1,301 @@
+"""
+YAML Parser and Validator for Lua DSL Procedures.
+
+Parses procedure YAML configurations and validates required structure.
+"""
+
+import yaml
+import logging
+from typing import Dict, Any, Optional, List
+
+logger = logging.getLogger(__name__)
+
+
+class ProcedureConfigError(Exception):
+    """Raised when procedure configuration is invalid."""
+
+    pass
+
+
+class ProcedureYAMLParser:
+    """Parses and validates Lua DSL procedure YAML configurations."""
+
+    @staticmethod
+    def parse(yaml_content: str) -> Dict[str, Any]:
+        """
+        Parse YAML content into a validated procedure configuration.
+
+        Args:
+            yaml_content: YAML string to parse
+
+        Returns:
+            Validated configuration dictionary
+
+        Raises:
+            ProcedureConfigError: If YAML is invalid or missing required fields
+        """
+        try:
+            config = yaml.safe_load(yaml_content)
+        except yaml.YAMLError as e:
+            raise ProcedureConfigError(f"Invalid YAML syntax: {e}")
+
+        if not isinstance(config, dict):
+            raise ProcedureConfigError("YAML root must be a dictionary")
+
+        # Validate required top-level fields
+        ProcedureYAMLParser._validate_required_fields(config)
+
+        # Validate specific sections
+        ProcedureYAMLParser._validate_params(config.get("params", {}))
+        ProcedureYAMLParser._validate_outputs(config.get("output", {}))
+        ProcedureYAMLParser._validate_default_model(config.get("default_model"))
+        ProcedureYAMLParser._validate_default_provider(config.get("default_provider"))
+        ProcedureYAMLParser._validate_agents(config.get("agents", {}), config)
+        ProcedureYAMLParser._validate_procedure(config.get("procedure"))
+
+        logger.info(f"Successfully parsed procedure: {config.get('name')}")
+        return config
+
+    @staticmethod
+    def _validate_required_fields(config: Dict[str, Any]) -> None:
+        """Validate that required top-level fields are present."""
+        required = ["name", "version", "procedure"]
+        missing = [field for field in required if field not in config]
+
+        if missing:
+            raise ProcedureConfigError(f"Missing required fields: {', '.join(missing)}")
+
+        # Validate class field if present (for routing)
+        if "class" in config:
+            if config["class"] != "LuaDSL":
+                logger.warning(
+                    f"Procedure class '{config['class']}' may not be compatible "
+                    "with Lua DSL runtime"
+                )
+
+    @staticmethod
+    def _validate_params(params: Dict[str, Any]) -> None:
+        """Validate parameter definitions."""
+        if not isinstance(params, dict):
+            raise ProcedureConfigError("'params' must be a dictionary")
+
+        for param_name, param_def in params.items():
+            if not isinstance(param_def, dict):
+                raise ProcedureConfigError(
+                    f"Parameter '{param_name}' definition must be a dictionary"
+                )
+
+            # Validate type field if present
+            if "type" in param_def:
+                valid_types = ["string", "number", "boolean", "array", "object"]
+                if param_def["type"] not in valid_types:
+                    raise ProcedureConfigError(
+                        f"Parameter '{param_name}' has invalid type: {param_def['type']}. "
+                        f"Must be one of: {', '.join(valid_types)}"
+                    )
+
+    @staticmethod
+    def _validate_outputs(outputs: Dict[str, Any]) -> None:
+        """Validate output definitions."""
+        if not isinstance(outputs, dict):
+            raise ProcedureConfigError("'output' must be a dictionary")
+
+        for output_name, output_def in outputs.items():
+            if not isinstance(output_def, dict):
+                raise ProcedureConfigError(
+                    f"Output '{output_name}' definition must be a dictionary"
+                )
+
+            # Validate type field if present
+            if "type" in output_def:
+                valid_types = ["string", "number", "boolean", "array", "object"]
+                if output_def["type"] not in valid_types:
+                    raise ProcedureConfigError(
+                        f"Output '{output_name}' has invalid type: {output_def['type']}. "
+                        f"Must be one of: {', '.join(valid_types)}"
+                    )
+
+    @staticmethod
+    def _validate_default_model(default_model: Optional[str]) -> None:
+        """Validate default_model field if present."""
+        if default_model is not None:
+            if not isinstance(default_model, str):
+                raise ProcedureConfigError("'default_model' must be a string")
+            if not default_model.strip():
+                raise ProcedureConfigError("'default_model' cannot be empty")
+
+    @staticmethod
+    def _validate_default_provider(default_provider: Optional[str]) -> None:
+        """Validate default_provider field if present."""
+        if default_provider is not None:
+            if not isinstance(default_provider, str):
+                raise ProcedureConfigError("'default_provider' must be a string")
+            if not default_provider.strip():
+                raise ProcedureConfigError("'default_provider' cannot be empty")
+            # Validate it's a known provider
+            valid_providers = ["openai", "bedrock"]
+            if default_provider not in valid_providers:
+                raise ProcedureConfigError(
+                    f"'default_provider' must be one of: {', '.join(valid_providers)}. "
+                    f"Got: {default_provider}"
+                )
+
+    @staticmethod
+    def _validate_agents(agents: Dict[str, Any], config: Dict[str, Any]) -> None:
+        """Validate agent definitions."""
+        if not isinstance(agents, dict):
+            raise ProcedureConfigError("'agents' must be a dictionary")
+
+        if not agents:
+            raise ProcedureConfigError("At least one agent must be defined")
+
+        for agent_name, agent_def in agents.items():
+            if not isinstance(agent_def, dict):
+                raise ProcedureConfigError(f"Agent '{agent_name}' definition must be a dictionary")
+
+            # Validate required agent fields
+            required_agent_fields = ["system_prompt", "initial_message"]
+            missing = [field for field in required_agent_fields if field not in agent_def]
+
+            if missing:
+                raise ProcedureConfigError(
+                    f"Agent '{agent_name}' missing required fields: {', '.join(missing)}"
+                )
+
+            # Validate model field if present
+            if "model" in agent_def:
+                model_value = agent_def["model"]
+
+                # Model can be either a string or a dict with settings
+                if isinstance(model_value, str):
+                    if not model_value.strip():
+                        raise ProcedureConfigError(f"Agent '{agent_name}' model cannot be empty")
+                elif isinstance(model_value, dict):
+                    # Model is a dict - must have 'name' key
+                    if "name" not in model_value:
+                        raise ProcedureConfigError(
+                            f"Agent '{agent_name}' model dict must have a 'name' key"
+                        )
+                    if not isinstance(model_value["name"], str):
+                        raise ProcedureConfigError(
+                            f"Agent '{agent_name}' model name must be a string"
+                        )
+                    if not model_value["name"].strip():
+                        raise ProcedureConfigError(
+                            f"Agent '{agent_name}' model name cannot be empty"
+                        )
+
+                    # Validate model settings in the dict
+                    valid_settings = {
+                        "name",  # The model name itself
+                        # Standard parameters (GPT-4 models)
+                        "temperature",
+                        "top_p",
+                        "max_tokens",
+                        "presence_penalty",
+                        "frequency_penalty",
+                        "logit_bias",
+                        "stop_sequences",
+                        "seed",
+                        "parallel_tool_calls",
+                        "timeout",
+                        # OpenAI reasoning models (o1, GPT-5)
+                        "openai_reasoning_effort",
+                        # Extra fields
+                        "extra_headers",
+                        "extra_body",
+                    }
+
+                    for setting_key in model_value.keys():
+                        if setting_key not in valid_settings:
+                            raise ProcedureConfigError(
+                                f"Agent '{agent_name}' has unknown model setting: '{setting_key}'. "
+                                f"Valid keys: {', '.join(sorted(valid_settings))}"
+                            )
+
+                    # Validate specific field types
+                    if "temperature" in model_value:
+                        temp = model_value["temperature"]
+                        if not isinstance(temp, (int, float)) or temp < 0 or temp > 2:
+                            raise ProcedureConfigError(
+                                f"Agent '{agent_name}' temperature must be a number between 0 and 2"
+                            )
+
+                    if "top_p" in model_value:
+                        top_p = model_value["top_p"]
+                        if not isinstance(top_p, (int, float)) or top_p < 0 or top_p > 1:
+                            raise ProcedureConfigError(
+                                f"Agent '{agent_name}' top_p must be a number between 0 and 1"
+                            )
+
+                    if "max_tokens" in model_value:
+                        max_tok = model_value["max_tokens"]
+                        if not isinstance(max_tok, int) or max_tok < 1:
+                            raise ProcedureConfigError(
+                                f"Agent '{agent_name}' max_tokens must be a positive integer"
+                            )
+
+                    if "openai_reasoning_effort" in model_value:
+                        effort = model_value["openai_reasoning_effort"]
+                        valid_efforts = ["low", "medium", "high"]
+                        if effort not in valid_efforts:
+                            raise ProcedureConfigError(
+                                f"Agent '{agent_name}' openai_reasoning_effort must be one of: {', '.join(valid_efforts)}. "
+                                f"Got: {effort}"
+                            )
+                else:
+                    raise ProcedureConfigError(
+                        f"Agent '{agent_name}' model must be a string or dict with 'name' key"
+                    )
+
+            # Validate provider field - required unless default_provider is set
+            has_default_provider = "default_provider" in config
+            if "provider" not in agent_def and not has_default_provider:
+                raise ProcedureConfigError(
+                    f"Agent '{agent_name}' must specify 'provider' (or set 'default_provider' at procedure level)"
+                )
+
+            if "provider" in agent_def:
+                if not isinstance(agent_def["provider"], str):
+                    raise ProcedureConfigError(f"Agent '{agent_name}' provider must be a string")
+                if not agent_def["provider"].strip():
+                    raise ProcedureConfigError(f"Agent '{agent_name}' provider cannot be empty")
+                # Validate it's a known provider
+                valid_providers = ["openai", "bedrock"]
+                if agent_def["provider"] not in valid_providers:
+                    raise ProcedureConfigError(
+                        f"Agent '{agent_name}' provider must be one of: {', '.join(valid_providers)}. "
+                        f"Got: {agent_def['provider']}"
+                    )
+
+            # Validate tools field if present
+            if "tools" in agent_def:
+                if not isinstance(agent_def["tools"], list):
+                    raise ProcedureConfigError(f"Agent '{agent_name}' tools must be a list")
+
+    @staticmethod
+    def _validate_procedure(procedure: Optional[str]) -> None:
+        """Validate procedure Lua code."""
+        if not procedure:
+            raise ProcedureConfigError("'procedure' field is required")
+
+        if not isinstance(procedure, str):
+            raise ProcedureConfigError("'procedure' must be a string")
+
+        if not procedure.strip():
+            raise ProcedureConfigError("'procedure' cannot be empty")
+
+        # Basic Lua syntax check (just verify it's not obviously broken)
+        # The actual Lua runtime will do full validation
+        if procedure.count("(") != procedure.count(")"):
+            logger.warning("Procedure has unmatched parentheses - may have syntax errors")
+
+    @staticmethod
+    def extract_agent_names(config: Dict[str, Any]) -> List[str]:
+        """Extract list of agent names from configuration."""
+        return list(config.get("agents", {}).keys())
+
+    @staticmethod
+    def get_agent_config(config: Dict[str, Any], agent_name: str) -> Optional[Dict[str, Any]]:
+        """Get configuration for a specific agent."""
+        return config.get("agents", {}).get(agent_name)

tactus/docker/Dockerfile

@@ -0,0 +1,61 @@
+# Tactus Sandbox Container
+#
+# This Dockerfile creates an isolated environment for running Tactus procedures
+# securely. The container includes all necessary runtimes for Tactus and MCP servers.
+#
+# Build: docker build -t tactus-sandbox:local -f tactus/docker/Dockerfile .
+# Run: docker run -i --rm tactus-sandbox:local
+
+FROM python:3.11-slim
+
+# Labels for image management
+ARG TACTUS_VERSION=dev
+LABEL tactus.version="${TACTUS_VERSION}"
+LABEL maintainer="Anthus <info@anthus.ai>"
+LABEL description="Tactus sandbox container for secure procedure execution"
+
+# Install system dependencies
+# - Node.js for JavaScript/TypeScript MCP servers
+# - git for any git operations
+# - build-essential for native Python packages
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    build-essential \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user for security
+RUN useradd -m -s /bin/bash tactus
+WORKDIR /app
+
+# Copy package files first (for better caching)
+COPY pyproject.toml ./
+COPY README.md ./
+COPY tactus/ ./tactus/
+
+# Ensure the non-root runtime user can read the codebase even if the host
+# working tree has restrictive permissions (e.g., umask 077).
+RUN chmod -R a+rX /app/tactus
+
+# Install Tactus and its dependencies
+RUN pip install --no-cache-dir -e .
+
+# Create workspace and mcp-servers directories
+RUN mkdir -p /workspace /mcp-servers && \
+    chown -R tactus:tactus /workspace /mcp-servers
+
+# Copy entrypoint script
+COPY tactus/docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Switch to non-root user
+USER tactus
+
+# Set working directory for procedure execution
+WORKDIR /workspace
+
+# Default entrypoint runs the sandbox entrypoint module
+ENTRYPOINT ["/entrypoint.sh"]

tactus/docker/entrypoint.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+#
+# Entrypoint script for Tactus sandbox container.
+#
+# This script:
+# 1. Starts any configured MCP servers from /mcp-servers
+# 2. Runs the Tactus sandbox entrypoint to execute the procedure
+# 3. Cleans up MCP server processes on exit
+#
+
+set -e
+
+# Cleanup function to kill MCP servers on exit
+cleanup() {
+    if [ -n "$MCP_PIDS" ]; then
+        echo "[sandbox] Stopping MCP servers..." >&2
+        for pid in $MCP_PIDS; do
+            kill "$pid" 2>/dev/null || true
+        done
+    fi
+}
+trap cleanup EXIT
+
+MCP_PIDS=""
+
+# Start MCP servers if directory is mounted and contains servers
+if [ -d "/mcp-servers" ] && [ "$(ls -A /mcp-servers 2>/dev/null)" ]; then
+    echo "[sandbox] Found MCP servers directory" >&2
+
+    for server_dir in /mcp-servers/*/; do
+        if [ ! -d "$server_dir" ]; then
+            continue
+        fi
+
+        server_name=$(basename "$server_dir")
+        echo "[sandbox] Starting MCP server: $server_name" >&2
+
+        # Check for Python server
+        if [ -f "${server_dir}server.py" ]; then
+            # Check for virtualenv
+            if [ -d "${server_dir}.venv" ]; then
+                source "${server_dir}.venv/bin/activate"
+                python "${server_dir}server.py" &
+                deactivate
+            else
+                python "${server_dir}server.py" &
+            fi
+            MCP_PIDS="$MCP_PIDS $!"
+
+        # Check for Node.js server
+        elif [ -f "${server_dir}server.js" ]; then
+            node "${server_dir}server.js" &
+            MCP_PIDS="$MCP_PIDS $!"
+
+        elif [ -f "${server_dir}index.js" ]; then
+            node "${server_dir}index.js" &
+            MCP_PIDS="$MCP_PIDS $!"
+        fi
+    done
+
+    # Give MCP servers a moment to start
+    if [ -n "$MCP_PIDS" ]; then
+        sleep 1
+    fi
+fi
+
+# Run the Tactus sandbox entrypoint with unbuffered I/O (-u flag)
+# This ensures stdin/stdout/stderr are not buffered, enabling real-time streaming
+exec python -u -m tactus.sandbox.entrypoint "$@"

tactus/dspy/__init__.py

@@ -0,0 +1,39 @@
+"""
+Tactus DSPy Integration
+
+This module provides the integration layer between Tactus and DSPy,
+exposing DSPy primitives as first-class Tactus language constructs.
+
+The integration follows a layered approach:
+- Low-level primitives (Module, Signature, etc.) are thin wrappers over DSPy
+- High-level constructs (Agent) are built in Tactus using these primitives
+"""
+
+from tactus.dspy.agent import DSPyAgentHandle, create_dspy_agent
+from tactus.dspy.config import configure_lm, get_current_lm, reset_lm_configuration
+from tactus.dspy.history import TactusHistory, create_history
+from tactus.dspy.module import TactusModule, create_module
+from tactus.dspy.prediction import TactusPrediction, create_prediction, wrap_prediction
+from tactus.dspy.signature import (
+    create_signature,
+    create_structured_signature,
+    parse_signature_string,
+)
+
+__all__ = [
+    "configure_lm",
+    "get_current_lm",
+    "reset_lm_configuration",
+    "create_signature",
+    "create_structured_signature",
+    "parse_signature_string",
+    "TactusModule",
+    "create_module",
+    "TactusHistory",
+    "create_history",
+    "TactusPrediction",
+    "create_prediction",
+    "wrap_prediction",
+    "DSPyAgentHandle",
+    "create_dspy_agent",
+]