tactus 0.31.2__py3-none-any.whl

tactus/primitives/procedure_callable.py

@@ -0,0 +1,318 @@
+"""
+Lua-callable wrapper for named sub-procedures.
+
+This module provides the ProcedureCallable class that enables direct function
+call syntax for named procedures with automatic checkpointing and replay support.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class ProcedureCallable:
+    """
+    Lua-callable wrapper for named sub-procedures.
+
+    Enables direct function call syntax: result = my_proc({input})
+    Integrates with checkpoint system for auto-replay.
+
+    Example:
+        helper = procedure("helper", {
+            input = {x = {type = "number"}},
+            output = {y = {type = "number"}}
+        }, function()
+            return {y = input.x * 2}
+        end)
+
+        -- Call it directly:
+        result = helper({x = 10})  -- Returns {y = 20}
+    """
+
+    def __init__(
+        self,
+        name: str,
+        procedure_function: Any,  # Lua function reference
+        input_schema: Dict[str, Any],
+        output_schema: Dict[str, Any],
+        state_schema: Dict[str, Any],
+        execution_context,  # ExecutionContext instance
+        lua_sandbox,  # LuaSandbox instance
+        is_main: bool = False,  # Whether this is the main entry procedure
+    ):
+        """
+        Initialize a callable procedure wrapper.
+
+        Args:
+            name: Procedure name
+            procedure_function: Lua function reference to execute
+            input_schema: Input validation schema
+            output_schema: Output validation schema
+            state_schema: State initialization schema
+            execution_context: ExecutionContext for checkpointing
+            lua_sandbox: LuaSandbox for Lua global management
+            is_main: If True, don't checkpoint (main is entry point)
+        """
+        self.name = name
+        self.procedure_function = procedure_function
+        self.input_schema = input_schema
+        self.output_schema = output_schema
+        self.state_schema = state_schema
+        self.execution_context = execution_context
+        self.lua_sandbox = lua_sandbox
+        self.is_main = is_main
+
+    def __call__(self, params: Optional[Dict[str, Any]] = None) -> Any:
+        """
+        Execute the sub-procedure when called from Lua.
+
+        This method is invoked when Lua code calls: result = my_proc({...})
+
+        Args:
+            params: Input parameters as a dictionary (converted from Lua table)
+
+        Returns:
+            The procedure's result (will be converted to Lua table)
+
+        Raises:
+            ValueError: If input validation fails or output is missing required fields
+        """
+        params = params or {}
+
+        # Convert Lua table to dict if needed
+        if hasattr(params, "items"):
+            from tactus.core.dsl_stubs import lua_table_to_dict
+
+            params = lua_table_to_dict(params)
+
+        # Handle empty list case (lua_table_to_dict converts empty {} to [])
+        if isinstance(params, list) and len(params) == 0:
+            params = {}
+
+        # Validate input against schema
+        self._validate_input(params)
+
+        # Wrap execution in checkpoint for automatic replay
+        def execute_procedure():
+            # Convert Python lists/dicts to Lua tables before setting as input
+            def convert_to_lua(value):
+                """Recursively convert Python lists and dicts to Lua tables."""
+                if isinstance(value, list):
+                    # Convert Python list to Lua table (1-indexed)
+                    lua_table = self.lua_sandbox.lua.table()
+                    for i, item in enumerate(value, 1):
+                        lua_table[i] = convert_to_lua(item)
+                    return lua_table
+                elif isinstance(value, dict):
+                    # Convert Python dict to Lua table
+                    lua_table = self.lua_sandbox.lua.table()
+                    for k, v in value.items():
+                        lua_table[k] = convert_to_lua(v)
+                    return lua_table
+                else:
+                    return value
+
+            # Convert params to Lua-compatible format
+            lua_params = self.lua_sandbox.lua.table()
+            for key, value in params.items():
+                lua_params[key] = convert_to_lua(value)
+
+            # Initialize state defaults WITHOUT replacing the state table
+            # (preserving the metatable setup)
+            state_defaults = self._initialize_state()
+            if state_defaults:
+                # Access state via globals and assign - this will trigger the metatable
+                state_table = self.lua_sandbox.lua.globals()["state"]
+                for key, value in state_defaults.items():
+                    state_table[key] = convert_to_lua(value)
+
+            # Execute the procedure function with input as explicit parameter
+            result = self.procedure_function(lua_params)
+
+            # Convert Lua table result to Python dict
+            # Check for lupa table (not Python dict/list)
+            if result and hasattr(result, "items") and not isinstance(result, (dict, list)):
+                from tactus.core.dsl_stubs import lua_table_to_dict
+
+                result = lua_table_to_dict(result)
+
+            # Validate output
+            self._validate_output(result)
+
+            return result
+
+        # Use existing checkpoint infrastructure for sub-procedures
+        # Main procedure is NOT checkpointed (it's the entry point)
+        if self.is_main:
+            # Main procedure: execute directly without checkpointing
+            return execute_procedure()
+        else:
+            # Sub-procedure: checkpoint for automatic replay
+            # Try to capture Lua source location if available
+            source_info = None
+
+            # First try to get Lua debug info
+            # When called from Lua, we need to find the Lua caller's location
+            try:
+                # Get debug.getinfo function from Lua globals
+                lua_globals = self.lua_sandbox.lua.globals()
+                if hasattr(lua_globals, "debug") and hasattr(lua_globals.debug, "getinfo"):
+                    # Try different stack levels to find the Lua caller
+                    debug_info = None
+                    with open("/tmp/tactus-debug.log", "a") as f:
+                        f.write(f"DEBUG: Trying debug.getinfo for {self.name}\n")
+                    for level in [1, 2, 3, 4, 5, 6, 7, 8]:
+                        try:
+                            info = lua_globals.debug.getinfo(level, "Sl")
+                            if info:
+                                lua_dict = dict(info.items()) if hasattr(info, "items") else {}
+                                source = lua_dict.get("source", "")
+                                line = lua_dict.get("currentline", -1)
+                                with open("/tmp/tactus-debug.log", "a") as f:
+                                    f.write(f"DEBUG: Level {level}: source={source}, line={line}\n")
+                                # Look for a valid source location (not -1, not C function)
+                                # Accept [string "<python>"] sources since that's our Lua code
+                                if line > 0 and source:
+                                    if source.startswith("=[C]"):
+                                        continue  # Skip C functions
+                                    debug_info = lua_dict
+                                    with open("/tmp/tactus-debug.log", "a") as f:
+                                        f.write(f"DEBUG: Found valid source at level {level}\n")
+                                    break
+                        except Exception as inner_e:
+                            with open("/tmp/tactus-debug.log", "a") as f:
+                                f.write(f"DEBUG: Level {level} error: {inner_e}\n")
+                            continue
+
+                    if debug_info:
+                        source_info = {
+                            "file": self.execution_context.current_tac_file
+                            or debug_info.get("source", "unknown"),
+                            "line": debug_info.get("currentline", 0),
+                            "function": debug_info.get("name", self.name),
+                        }
+                        with open("/tmp/tactus-debug.log", "a") as f:
+                            f.write(f"DEBUG: Final source_info: {source_info}\n")
+            except Exception as e:
+                with open("/tmp/tactus-debug.log", "a") as f:
+                    f.write(f"DEBUG: Exception getting Lua debug info: {e}\n")
+
+            # If we still don't have source_info, use fallback
+            if not source_info:
+                import inspect
+
+                frame = inspect.currentframe()
+                if frame and frame.f_back:
+                    caller_frame = frame.f_back
+                    # Use .tac file if available, otherwise use Python file
+                    tac_file = self.execution_context.current_tac_file
+                    python_file = caller_frame.f_code.co_filename
+                    with open("/tmp/tactus-debug.log", "a") as f:
+                        f.write(
+                            f"DEBUG: Fallback - current_tac_file={tac_file}, python_file={python_file}\n"
+                        )
+                    source_info = {
+                        "file": tac_file or python_file,
+                        "line": 0,  # Line number unknown without Lua debug
+                        "function": self.name,
+                    }
+
+            return self.execution_context.checkpoint(
+                execute_procedure, checkpoint_type="procedure_call", source_info=source_info
+            )
+
+    def _validate_input(self, params: Dict[str, Any]) -> None:
+        """
+        Validate input parameters against input schema.
+
+        Args:
+            params: Input parameters to validate
+
+        Raises:
+            ValueError: If required fields are missing
+        """
+        missing_inputs = []
+        for field_name, field_def in self.input_schema.items():
+            if isinstance(field_def, dict) and field_def.get("required", False):
+                if field_name not in params:
+                    field_type = field_def.get("type", "any")
+                    field_desc = field_def.get("description", "")
+                    missing_inputs.append(
+                        f"  - {field_name} ({field_type}): {field_desc}"
+                        if field_desc
+                        else f"  - {field_name} ({field_type})"
+                    )
+
+        if missing_inputs:
+            inputs_list = "\n".join(missing_inputs)
+            raise ValueError(
+                f"Procedure '{self.name}' requires input parameters that were not provided:\n{inputs_list}\n\n"
+                f"To run this procedure, provide the required inputs via the API or use a test specification."
+            )
+
+    def _validate_output(self, result: Any) -> None:
+        """
+        Validate output against output schema.
+
+        Args:
+            result: Output to validate
+
+        Raises:
+            ValueError: If output is not a dict or missing required fields
+        """
+        # If no output schema is declared, accept any return value.
+        if not self.output_schema:
+            return
+
+        # Scalar output schema support:
+        #   output = field.string{...}
+        if (
+            isinstance(self.output_schema, dict)
+            and "type" in self.output_schema
+            and isinstance(self.output_schema.get("type"), str)
+        ):
+            expected_type = self.output_schema.get("type")
+            if expected_type not in {"string", "number", "boolean", "object", "array"}:
+                # Not a scalar schema; treat as normal object schema.
+                expected_type = None
+
+        else:
+            expected_type = None
+
+        if expected_type is not None:
+            is_required = bool(self.output_schema.get("required", False))
+            if result is None and not is_required:
+                return
+
+            if expected_type == "string" and not isinstance(result, str):
+                raise ValueError(f"Procedure '{self.name}' must return string, got {type(result)}")
+            if expected_type == "number" and not isinstance(result, (int, float)):
+                raise ValueError(f"Procedure '{self.name}' must return number, got {type(result)}")
+            if expected_type == "boolean" and not isinstance(result, bool):
+                raise ValueError(f"Procedure '{self.name}' must return boolean, got {type(result)}")
+            if expected_type == "object" and not isinstance(result, dict):
+                raise ValueError(f"Procedure '{self.name}' must return object, got {type(result)}")
+            if expected_type == "array" and not isinstance(result, list):
+                raise ValueError(f"Procedure '{self.name}' must return array, got {type(result)}")
+            return
+
+        if not isinstance(result, dict):
+            raise ValueError(f"Procedure '{self.name}' must return dict, got {type(result)}")
+
+        for field_name, field_def in self.output_schema.items():
+            if isinstance(field_def, dict) and field_def.get("required", False):
+                if field_name not in result:
+                    raise ValueError(
+                        f"Procedure '{self.name}' missing required output: {field_name}"
+                    )
+
+    def _initialize_state(self) -> Dict[str, Any]:
+        """
+        Initialize state with default values from state schema.
+
+        Returns:
+            Dictionary with state defaults
+        """
+        state = {}
+        for field_name, field_def in self.state_schema.items():
+            if isinstance(field_def, dict) and "default" in field_def:
+                state[field_name] = field_def["default"]
+        return state

tactus/primitives/retry.py

@@ -0,0 +1,155 @@
+"""
+Retry Primitive - Error handling with exponential backoff.
+
+Provides:
+- Retry.with_backoff(fn, options) - Retry function with exponential backoff
+"""
+
+import logging
+import time
+from typing import Callable, Any, Optional, Dict
+
+logger = logging.getLogger(__name__)
+
+
+class RetryPrimitive:
+    """
+    Handles retry logic with exponential backoff for procedures.
+
+    Enables workflows to:
+    - Retry failed operations automatically
+    - Use exponential backoff between attempts
+    - Handle transient errors gracefully
+    - Configure max attempts and delays
+    """
+
+    def __init__(self):
+        """Initialize Retry primitive."""
+        logger.debug("RetryPrimitive initialized")
+
+    def with_backoff(self, fn: Callable, options: Optional[Dict[str, Any]] = None) -> Any:
+        """
+        Retry a function with exponential backoff.
+
+        Args:
+            fn: Function to retry (Lua function)
+            options: Dict with:
+                - max_attempts: Maximum retry attempts (default: 3)
+                - initial_delay: Initial delay in seconds (default: 1)
+                - max_delay: Maximum delay in seconds (default: 60)
+                - backoff_factor: Multiplier for delay (default: 2)
+                - on_error: Optional callback when error occurs
+
+        Returns:
+            Result from successful function call
+
+        Raises:
+            Exception: If all retry attempts fail
+
+        Example (Lua):
+            local result = Retry.with_backoff(function()
+                -- Try to fetch data from API
+                local data = fetch_api_data()
+                if not data then
+                    error("API returned no data")
+                end
+                return data
+            end, {
+                max_attempts = 5,
+                initial_delay = 2,
+                backoff_factor = 2
+            })
+        """
+        # Convert Lua tables to Python dicts if needed
+        opts = self._convert_lua_to_python(options) or {}
+
+        max_attempts = opts.get("max_attempts", 3)
+        initial_delay = opts.get("initial_delay", 1.0)
+        max_delay = opts.get("max_delay", 60.0)
+        backoff_factor = opts.get("backoff_factor", 2.0)
+        on_error = opts.get("on_error")
+
+        attempt = 0
+        delay = initial_delay
+        last_error = None
+
+        logger.info(f"Starting retry with_backoff (max_attempts={max_attempts})")
+
+        while attempt < max_attempts:
+            attempt += 1
+
+            try:
+                logger.debug(f"Retry attempt {attempt}/{max_attempts}")
+                result = fn()
+                logger.info(f"Success on attempt {attempt}/{max_attempts}")
+                return result
+
+            except Exception as e:
+                last_error = e
+                logger.warning(f"Attempt {attempt}/{max_attempts} failed: {e}")
+
+                # Call error callback if provided
+                if on_error and callable(on_error):
+                    try:
+                        on_error(
+                            {
+                                "attempt": attempt,
+                                "max_attempts": max_attempts,
+                                "error": str(e),
+                                "delay": delay,
+                            }
+                        )
+                    except Exception as callback_error:
+                        logger.error(f"Error callback failed: {callback_error}")
+
+                # Check if we should retry
+                if attempt >= max_attempts:
+                    logger.error(f"All {max_attempts} attempts failed")
+                    raise Exception(f"Retry failed after {max_attempts} attempts: {last_error}")
+
+                # Wait with exponential backoff
+                logger.info(f"Waiting {delay:.2f}s before retry...")
+                time.sleep(delay)
+
+                # Increase delay for next attempt (exponential backoff)
+                delay = min(delay * backoff_factor, max_delay)
+
+        # Should not reach here, but handle it
+        raise Exception(f"Retry logic error: {last_error}")
+
+    def _convert_lua_to_python(self, value: Any) -> Any:
+        """
+        Recursively convert Lua tables to Python dicts.
+
+        Args:
+            value: Lua value to convert
+
+        Returns:
+            Python equivalent (dict or primitive)
+        """
+        if value is None:
+            return None
+
+        # Import lupa for table checking
+        try:
+            from lupa import lua_type
+
+            # Check if it's a Lua table
+            if lua_type(value) == "table":
+                result = {}
+                for k, v in value.items():
+                    # Convert key and value recursively
+                    py_key = self._convert_lua_to_python(k) if lua_type(k) == "table" else k
+                    py_value = self._convert_lua_to_python(v)
+                    result[py_key] = py_value
+                return result
+            else:
+                # Primitive value or function
+                return value
+
+        except ImportError:
+            # If lupa not available, just return as-is
+            return value
+
+    def __repr__(self) -> str:
+        return "RetryPrimitive()"

tactus/primitives/session.py

@@ -0,0 +1,152 @@
+"""
+Session primitive for managing conversation history.
+
+Provides Lua-accessible methods for manipulating chat session state.
+"""
+
+from typing import Any, Optional
+
+try:
+    from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse, TextPart
+except ImportError:
+    # Fallback types if pydantic_ai not available
+    ModelMessage = dict
+    ModelRequest = dict
+    ModelResponse = dict
+    TextPart = dict
+
+
+class SessionPrimitive:
+    """
+    Primitive for managing conversation session state.
+
+    Provides methods to:
+    - Append messages to history
+    - Inject system messages
+    - Clear history
+    - Access full history
+    - Save/load session state
+    """
+
+    def __init__(self, session_manager=None, agent_name: Optional[str] = None):
+        """
+        Initialize Session primitive.
+
+        Args:
+            session_manager: SessionManager instance
+            agent_name: Name of the agent this session belongs to
+        """
+        self.session_manager = session_manager
+        self.agent_name = agent_name
+
+    def append(self, message_data: dict) -> None:
+        """
+        Append a message to the session history.
+
+        Args:
+            message_data: Dict with 'role' and 'content' keys
+                         role: 'user', 'assistant', 'system'
+                         content: message text
+
+        Example:
+            Session.append({role = "user", content = "Hello"})
+        """
+        if not self.session_manager or not self.agent_name:
+            return
+
+        role = message_data.get("role", "user")
+        content = message_data.get("content", "")
+
+        # Create a simple message dict
+        message = {"role": role, "content": content}
+
+        self.session_manager.add_message(self.agent_name, message)
+
+    def inject_system(self, text: str) -> None:
+        """
+        Inject a system message into the session.
+
+        This is useful for providing context or instructions
+        for the next agent turn.
+
+        Args:
+            text: System message content
+
+        Example:
+            Session.inject_system("Focus on security implications")
+        """
+        self.append({"role": "system", "content": text})
+
+    def clear(self) -> None:
+        """
+        Clear the session history for this agent.
+
+        Example:
+            Session.clear()
+        """
+        if not self.session_manager or not self.agent_name:
+            return
+
+        self.session_manager.clear_agent_history(self.agent_name)
+
+    def history(self) -> list:
+        """
+        Get the full conversation history for this agent.
+
+        Returns:
+            List of message dicts with 'role' and 'content' keys
+
+        Example:
+            local messages = Session.history()
+            for i, msg in ipairs(messages) do
+                Log.info(msg.role .. ": " .. msg.content)
+            end
+        """
+        if not self.session_manager or not self.agent_name:
+            return []
+
+        messages = self.session_manager.histories.get(self.agent_name, [])
+
+        # Convert to Lua-friendly format
+        result = []
+        for msg in messages:
+            if isinstance(msg, dict):
+                result.append({"role": msg.get("role", ""), "content": str(msg.get("content", ""))})
+            else:
+                # Handle pydantic_ai ModelMessage objects
+                try:
+                    result.append(
+                        {
+                            "role": getattr(msg, "role", ""),
+                            "content": str(getattr(msg, "content", "")),
+                        }
+                    )
+                except Exception:
+                    # Fallback: convert to string
+                    result.append({"role": "unknown", "content": str(msg)})
+
+        return result
+
+    def load_from_node(self, node: Any) -> None:
+        """
+        Load session state from a graph node.
+
+        Not yet implemented - placeholder for future graph support.
+
+        Args:
+            node: Graph node containing saved session state
+        """
+        # TODO: Implement when graph primitives are added
+        pass
+
+    def save_to_node(self, node: Any) -> None:
+        """
+        Save session state to a graph node.
+
+        Not yet implemented - placeholder for future graph support.
+
+        Args:
+            node: Graph node to save session state to
+        """
+        # TODO: Implement when graph primitives are added
+        pass