tactus 0.35.1__py3-none-any.whl → 0.37.0__py3-none-any.whl

tactus/core/execution_context.py

@@ -6,7 +6,7 @@ Uses pluggable storage and HITL handlers via protocols.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, Callable
+from typing import Any, Callable, Dict, List, Optional
 from datetime import datetime, timezone
 import logging
 import time
@@ -39,7 +39,7 @@ class ExecutionContext(ABC):
         self,
         fn: Callable[[], Any],
         checkpoint_type: str,
-        source_info: dict[str, Any] | None = None,
+        source_info: Optional[Dict[str, Any]] = None,
     ) -> Any:
         """
         Execute fn with position-based checkpointing. On replay, return stored result.
@@ -59,9 +59,9 @@ class ExecutionContext(ABC):
         self,
         request_type: str,
         message: str,
-        timeout_seconds: int | None,
+        timeout_seconds: Optional[int],
         default_value: Any,
-        options: list[dict] | None,
+        options: Optional[List[dict]],
         metadata: dict,
     ) -> HITLResponse:
         """
@@ -121,7 +121,7 @@ class BaseExecutionContext(ExecutionContext):
         self,
         procedure_id: str,
         storage_backend: StorageBackend,
-        hitl_handler: HITLHandler | None = None,
+        hitl_handler: Optional[HITLHandler] = None,
         strict_determinism: bool = False,
         log_handler=None,
     ):
@@ -145,21 +145,26 @@ class BaseExecutionContext(ExecutionContext):
         self._inside_checkpoint = False
 
         # Run ID tracking for distinguishing between different executions
-        self.current_run_id: str | None = None
+        self.current_run_id: Optional[str] = None
 
         # .tac file tracking for accurate source locations
-        self.current_tac_file: str | None = None
-        self.current_tac_content: str | None = None
+        self.current_tac_file: Optional[str] = None
+        self.current_tac_content: Optional[str] = None
 
         # Lua sandbox reference for debug.getinfo access
-        self.lua_sandbox: Any | None = None
+        self.lua_sandbox: Optional[Any] = None
 
         # Rich metadata for HITL notifications
-        self.procedure_name: str = procedure_id  # Use procedure_id as default name
-        self.invocation_id: str = str(uuid.uuid4())
-        self._started_at: datetime = datetime.now(timezone.utc)
-        self._input_data: Any = None
+        self._initialize_run_metadata(procedure_id)
+        self._load_and_reset_metadata(procedure_id)
 
+    def _initialize_run_metadata(self, procedure_id: str) -> None:
+        self.procedure_name = procedure_id
+        self.invocation_id = str(uuid.uuid4())
+        self._started_at = datetime.now(timezone.utc)
+        self._input_data = None
+
+    def _load_and_reset_metadata(self, procedure_id: str) -> None:
         # Load procedure metadata (contains execution_log and replay_index)
         self.metadata = self.storage.load_procedure_metadata(procedure_id)
 
@@ -172,7 +177,7 @@ class BaseExecutionContext(ExecutionContext):
         """Set the run_id for subsequent checkpoints in this execution."""
         self.current_run_id = run_id
 
-    def set_tac_file(self, file_path: str, content: str | None = None) -> None:
+    def set_tac_file(self, file_path: str, content: Optional[str] = None) -> None:
         """
         Store the currently executing .tac file for accurate source location capture.
 
@@ -188,7 +193,7 @@ class BaseExecutionContext(ExecutionContext):
         self.lua_sandbox = lua_sandbox
 
     def set_procedure_metadata(
-        self, procedure_name: str | None = None, input_data: Any = None
+        self, procedure_name: Optional[str] = None, input_data: Any = None
     ) -> None:
         """
         Set rich metadata for HITL notifications.
@@ -206,7 +211,7 @@ class BaseExecutionContext(ExecutionContext):
         self,
         fn: Callable[[], Any],
         checkpoint_type: str,
-        source_info: dict[str, Any] | None = None,
+        source_info: Optional[Dict[str, Any]] = None,
     ) -> Any:
         """
         Execute fn with position-based checkpointing and source tracking.
@@ -401,7 +406,7 @@ class BaseExecutionContext(ExecutionContext):
 
     def _get_code_context(
         self, file_path: str, line_number: int, context_lines: int = 3
-    ) -> str | None:
+    ) -> Optional[str]:
         """Read source file and extract surrounding lines for debugging."""
         try:
             with open(file_path, "r") as source_file:
@@ -416,9 +421,9 @@ class BaseExecutionContext(ExecutionContext):
         self,
         request_type: str,
         message: str,
-        timeout_seconds: int | None,
+        timeout_seconds: Optional[int],
         default_value: Any,
-        options: list[dict] | None,
+        options: Optional[List[dict]],
         metadata: dict,
     ) -> HITLResponse:
         """
@@ -500,7 +505,7 @@ class BaseExecutionContext(ExecutionContext):
         async_procedure_handles[handle.procedure_id] = handle.to_dict()
         self.storage.save_procedure_metadata(self.procedure_id, self.metadata)
 
-    def get_procedure_handle(self, procedure_id: str) -> dict[str, Any] | None:
+    def get_procedure_handle(self, procedure_id: str) -> Optional[Dict[str, Any]]:
         """
         Retrieve procedure handle.
 
@@ -604,7 +609,7 @@ class BaseExecutionContext(ExecutionContext):
 
         return run_id
 
-    def get_subject(self) -> str | None:
+    def get_subject(self) -> Optional[str]:
         """
         Return a human-readable subject line for this execution.
 
@@ -616,7 +621,7 @@ class BaseExecutionContext(ExecutionContext):
             return f"{self.procedure_name} (checkpoint {checkpoint_position})"
         return f"Procedure {self.procedure_id} (checkpoint {checkpoint_position})"
 
-    def get_started_at(self) -> datetime | None:
+    def get_started_at(self) -> Optional[datetime]:
         """
         Return when this execution started.
 
@@ -625,7 +630,7 @@ class BaseExecutionContext(ExecutionContext):
         """
         return self._started_at
 
-    def get_input_summary(self) -> dict[str, Any] | None:
+    def get_input_summary(self) -> Optional[Dict[str, Any]]:
         """
         Return a summary of the initial input to this procedure.
 
@@ -642,7 +647,7 @@ class BaseExecutionContext(ExecutionContext):
         # Otherwise wrap it in a dict
         return {"value": self._input_data}
 
-    def get_conversation_history(self) -> list[dict] | None:
+    def get_conversation_history(self) -> Optional[List[dict]]:
         """
         Return conversation history if available.
 
@@ -653,7 +658,7 @@ class BaseExecutionContext(ExecutionContext):
         # in future implementations
         return None
 
-    def get_prior_control_interactions(self) -> list[dict] | None:
+    def get_prior_control_interactions(self) -> Optional[List[dict]]:
         """
         Return list of prior HITL interactions in this execution.
 
@@ -677,7 +682,7 @@ class BaseExecutionContext(ExecutionContext):
 
         return hitl_checkpoints if hitl_checkpoints else None
 
-    def get_lua_source_line(self) -> int | None:
+    def get_lua_source_line(self) -> Optional[int]:
         """
         Get the current source line from Lua debug.getinfo.
 
@@ -763,7 +768,7 @@ class InMemoryExecutionContext(BaseExecutionContext):
     and simple CLI workflows that don't need to survive restarts.
     """
 
-    def __init__(self, procedure_id: str, hitl_handler: HITLHandler | None = None):
+    def __init__(self, procedure_id: str, hitl_handler: Optional[HITLHandler] = None):
         """
         Initialize with in-memory storage.
 

tactus/core/lua_sandbox.py

@@ -241,7 +241,7 @@ class LuaSandbox:
         """Setup safe global functions and utilities."""
         # Keep safe standard library functions
         # (These are already available by default, just documenting them)
-        safe_functions = {
+        safe_global_symbols = {
             # Math
             "math",  # Math library (will be replaced with safe version if context available)
             "tonumber",  # Convert to number
@@ -264,54 +264,62 @@ class LuaSandbox:
         }
 
         # Just log what's available - no need to explicitly set
-        logger.debug("Safe Lua functions available: %s", ", ".join(safe_functions))
+        logger.debug("Safe Lua functions available: %s", ", ".join(safe_global_symbols))
 
         # Replace math and os libraries with safe versions if context available
         if self.execution_context is not None:
-            from tactus.utils.safe_libraries import (
-                create_safe_math_library,
-                create_safe_os_library,
-            )
+            self._install_context_safe_libraries()
+            return  # Skip default os.date setup below
 
-            def get_context():
-                return self.execution_context
+        self._install_fallback_os_date()
 
-            safe_math_dict = create_safe_math_library(get_context, self.strict_determinism)
-            safe_os_dict = create_safe_os_library(get_context, self.strict_determinism)
+    def _install_context_safe_libraries(self) -> None:
+        """Install safe math and os libraries based on execution context."""
+        from tactus.utils.safe_libraries import (
+            create_safe_math_library,
+            create_safe_os_library,
+        )
 
-            safe_math_table = self._dict_to_lua_table(safe_math_dict)
-            safe_os_table = self._dict_to_lua_table(safe_os_dict)
+        def get_execution_context() -> Any:
+            return self.execution_context
 
-            self.lua.globals()["math"] = safe_math_table
-            self.lua.globals()["os"] = safe_os_table
+        safe_math_dict = create_safe_math_library(get_execution_context, self.strict_determinism)
+        safe_os_dict = create_safe_os_library(get_execution_context, self.strict_determinism)
 
-            logger.debug("Installed safe math and os libraries with determinism checking")
-            return  # Skip default os.date setup below
+        safe_math_table = self._dict_to_lua_table(safe_math_dict)
+        safe_os_table = self._dict_to_lua_table(safe_os_dict)
 
-        # Add safe subset of os module (only date function for timestamps)
-        # This is a fallback when no execution context is available (testing/REPL)
-        from datetime import datetime
+        self.lua.globals()["math"] = safe_math_table
+        self.lua.globals()["os"] = safe_os_table
+
+        logger.debug("Installed safe math and os libraries with determinism checking")
+
+    def _install_fallback_os_date(self) -> None:
+        """Install a safe os.date() fallback when no execution context is available."""
+        safe_os_table = self._build_fallback_os_table()
+        self.lua.globals()["os"] = safe_os_table
+        logger.debug("Added safe os.date() function")
 
-        def safe_date(format_str=None):
+    def _build_fallback_os_table(self) -> Any:
+        """Build a Lua os table with a safe date() implementation."""
+        from datetime import datetime, timezone
+
+        def safe_date(format_string: Optional[str] = None) -> str:
             """Safe implementation of os.date() for timestamp generation."""
-            now = datetime.utcnow()
-            if format_str is None:
+            now = datetime.now(timezone.utc)
+            if format_string is None:
                 # Return default format like Lua's os.date()
                 return now.strftime("%a %b %d %H:%M:%S %Y")
-            elif format_str == "%Y-%m-%dT%H:%M:%SZ":
+            if format_string == "%Y-%m-%dT%H:%M:%SZ":
                 # ISO 8601 format
                 return now.strftime("%Y-%m-%dT%H:%M:%SZ")
-            else:
-                # Support Python strftime formats
-                try:
-                    return now.strftime(format_str)
-                except Exception:  # noqa: E722
-                    return now.strftime("%a %b %d %H:%M:%S %Y")
-
-        # Create safe os table with only date function
-        safe_os = self.lua.table(date=safe_date)
-        self.lua.globals()["os"] = safe_os
-        logger.debug("Added safe os.date() function")
+            # Support Python strftime formats
+            try:
+                return now.strftime(format_string)
+            except Exception:  # noqa: E722
+                return now.strftime("%a %b %d %H:%M:%S %Y")
+
+        return self.lua.table(date=safe_date)
 
     def setup_assignment_interception(self, callback: Any) -> None:
         """

tactus/core/message_history_manager.py

@@ -8,7 +8,7 @@ Aligned with pydantic-ai's message_history concept.
 """
 
 from datetime import datetime, timezone
-from typing import Any, Optional
+from typing import Any, Optional, Tuple
 
 try:
     from pydantic_ai.messages import ModelMessage
@@ -136,37 +136,60 @@ class MessageHistoryManager:
                 print(f"Warning: Filter function failed: {exception}")
                 return messages
 
-        # Otherwise it's a tuple (filter_type, filter_arg)
-        if not isinstance(filter_specification, tuple) or len(filter_specification) < 2:
+        filter_name, filter_value = self._parse_filter_spec(filter_specification)
+        if filter_name is None:
             return messages
 
-        filter_name = filter_specification[0]
-        filter_value = filter_specification[1]
-
-        if filter_name == "last_n":
-            return self._filter_last_n(messages, filter_value)
-        elif filter_name == "first_n":
-            return self._filter_first_n(messages, filter_value)
-        elif filter_name == "token_budget":
-            return self._filter_by_token_budget(messages, filter_value)
-        elif filter_name == "head_tokens":
-            return self._filter_head_tokens(messages, filter_value)
-        elif filter_name == "tail_tokens":
-            return self._filter_tail_tokens(messages, filter_value)
-        elif filter_name == "by_role":
-            return self._filter_by_role(messages, filter_value)
-        elif filter_name == "system_prefix":
-            return self._filter_system_prefix(messages)
-        elif filter_name == "compose":
-            # Apply multiple filters in sequence
-            filtered_messages = messages
-            for filter_step in filter_value:
-                filtered_messages = self._apply_filter(filtered_messages, filter_step, context)
-            return filtered_messages
-        else:
-            # Unknown filter type, return unfiltered
+        if filter_name == "compose":
+            return self._apply_composed_filters(messages, filter_value, context)
+
+        return self._apply_named_filter(messages, filter_name, filter_value)
+
+    @staticmethod
+    def _parse_filter_spec(filter_specification: Any) -> Tuple[Optional[str], Any]:
+        if not isinstance(filter_specification, tuple) or len(filter_specification) < 2:
+            return None, None
+
+        return filter_specification[0], filter_specification[1]
+
+    def _apply_composed_filters(
+        self,
+        messages: list[ModelMessage],
+        filter_steps: Any,
+        context: Optional[Any],
+    ) -> list[ModelMessage]:
+        filtered_messages = messages
+        for filter_step in filter_steps:
+            filtered_messages = self._apply_filter(filtered_messages, filter_step, context)
+        return filtered_messages
+
+    def _apply_named_filter(
+        self,
+        messages: list[ModelMessage],
+        filter_name: str,
+        filter_value: Any,
+    ) -> list[ModelMessage]:
+        filter_function = self._filter_dispatch.get(filter_name)
+        if filter_function is None:
             return messages
 
+        if filter_name == "system_prefix":
+            return filter_function(messages)
+
+        return filter_function(messages, filter_value)
+
+    @property
+    def _filter_dispatch(self) -> dict[str, Any]:
+        return {
+            "last_n": self._filter_last_n,
+            "first_n": self._filter_first_n,
+            "token_budget": self._filter_by_token_budget,
+            "head_tokens": self._filter_head_tokens,
+            "tail_tokens": self._filter_tail_tokens,
+            "by_role": self._filter_by_role,
+            "system_prefix": self._filter_system_prefix,
+        }
+
     def _filter_last_n(
         self,
         messages: list[ModelMessage],

tactus/core/output_validator.py

@@ -6,7 +6,7 @@ Enables type safety and composability for sub-agent workflows.
 """
 
 import logging
-from typing import Any, Optional
+from typing import Any, Optional, Tuple
 
 logger = logging.getLogger(__name__)
 
@@ -29,13 +29,14 @@ class OutputValidator:
     """
 
     # Type mapping from YAML to Python
-    TYPE_MAP = {
+    SCHEMA_TYPE_TO_PYTHON_TYPE = {
         "string": str,
         "number": (int, float),
         "boolean": bool,
         "object": dict,
         "array": list,
     }
+    TYPE_MAP = SCHEMA_TYPE_TO_PYTHON_TYPE
 
     @classmethod
     def _is_scalar_schema(cls, schema: Any) -> bool:
@@ -77,7 +78,7 @@ class OutputValidator:
             logger.debug("OutputValidator initialized with %s output fields", field_count)
 
     @staticmethod
-    def _unwrap_result(output: Any) -> tuple[Any, Any | None]:
+    def _unwrap_result(output: Any) -> Tuple[Any, Optional[Any]]:
         from tactus.protocols.result import TactusResult
 
         wrapped_result = output if isinstance(output, TactusResult) else None
@@ -91,6 +92,15 @@ class OutputValidator:
             return dict(output.items())
         return output
 
+    @staticmethod
+    def _wrap_validated_output(
+        wrapped_result: Optional[Any],
+        validated_payload: Any,
+    ) -> Any:
+        if wrapped_result is not None:
+            return wrapped_result.model_copy(update={"output": validated_payload})
+        return validated_payload
+
     def validate(self, output: Any) -> Any:
         """
         Validate workflow output against schema.
@@ -108,49 +118,63 @@ class OutputValidator:
         # while preserving the wrapper (so callers can still access usage/cost/etc.).
         output, wrapped_result = self._unwrap_result(output)
 
-        # If no schema defined, accept any output
         if not self.schema:
-            logger.debug("No output schema defined, skipping validation")
-            validated_payload = self._normalize_unstructured_output(output)
+            return self._validate_without_schema(output, wrapped_result)
 
-            if wrapped_result is not None:
-                return wrapped_result.model_copy(update={"output": validated_payload})
-            return validated_payload
-
-        # Scalar output schema: `output = field.string{...}` etc.
         if self._is_scalar_schema(self.schema):
-            # Lua tables are not valid scalar outputs.
-            if hasattr(output, "items") and not isinstance(output, dict):
-                output = dict(output.items())
-
-            is_required = self.schema.get("required", False)
-            if output is None and not is_required:
-                return None
+            return self._validate_scalar_schema(output, wrapped_result)
+
+        return self._validate_structured_schema(output, wrapped_result)
+
+    def _validate_without_schema(
+        self,
+        output: Any,
+        wrapped_result: Optional[Any],
+    ) -> Any:
+        """Accept any output when no schema is defined."""
+        logger.debug("No output schema defined, skipping validation")
+        validated_payload = self._normalize_unstructured_output(output)
+        return self._wrap_validated_output(wrapped_result, validated_payload)
+
+    def _validate_scalar_schema(
+        self,
+        output: Any,
+        wrapped_result: Optional[Any],
+    ) -> Any:
+        """Validate scalar outputs (`field.string{}` etc.)."""
+        # Lua tables are not valid scalar outputs.
+        if hasattr(output, "items") and not isinstance(output, dict):
+            output = dict(output.items())
+
+        is_required = self.schema.get("required", False)
+        if output is None and not is_required:
+            return None
+
+        expected_type = self.schema.get("type")
+        if expected_type and not self._check_type(output, expected_type):
+            raise OutputValidationError(
+                f"Output should be {expected_type}, got {type(output).__name__}"
+            )
 
-            expected_type = self.schema.get("type")
-            if expected_type and not self._check_type(output, expected_type):
+        if "enum" in self.schema and self.schema["enum"]:
+            allowed_values = self.schema["enum"]
+            if output not in allowed_values:
                 raise OutputValidationError(
-                    f"Output should be {expected_type}, got {type(output).__name__}"
+                    f"Output has invalid value '{output}'. Allowed values: {allowed_values}"
                 )
 
-            if "enum" in self.schema and self.schema["enum"]:
-                allowed_values = self.schema["enum"]
-                if output not in allowed_values:
-                    raise OutputValidationError(
-                        f"Output has invalid value '{output}'. Allowed values: {allowed_values}"
-                    )
-
-            validated_payload = output
-            if wrapped_result is not None:
-                return wrapped_result.model_copy(update={"output": validated_payload})
-            return validated_payload
+        return self._wrap_validated_output(wrapped_result, output)
 
-        # Convert Lua tables to dicts recursively
+    def _validate_structured_schema(
+        self,
+        output: Any,
+        wrapped_result: Optional[Any],
+    ) -> Any:
+        """Validate dict/table outputs against a schema."""
         if hasattr(output, "items") or isinstance(output, dict):
             logger.debug("Converting Lua tables to Python dicts recursively")
             output = self._convert_lua_tables(output)
 
-        # Output must be a dict/table
         if not isinstance(output, dict):
             raise OutputValidationError(
                 f"Output must be an object/table, got {type(output).__name__}"
@@ -159,7 +183,6 @@ class OutputValidator:
         validation_errors: list[str] = []
         validated_output: dict[str, Any] = {}
 
-        # Check required fields and validate types
         for field_name, field_def in self.schema.items():
             if not isinstance(field_def, dict) or "type" not in field_def:
                 validation_errors.append(
@@ -167,28 +190,23 @@ class OutputValidator:
                     f"Use field.{field_def.get('type', 'string')}{{}} instead."
                 )
                 continue
-            is_required = bool(field_def.get("required", False))
 
+            is_required = bool(field_def.get("required", False))
             if is_required and field_name not in output:
                 validation_errors.append(f"Required field '{field_name}' is missing")
                 continue
 
-            # Skip validation if field not present and not required
             if field_name not in output:
                 continue
 
             value = output[field_name]
-
-            # Type checking
             expected_type = field_def.get("type")
-            if expected_type:
-                if not self._check_type(value, expected_type):
-                    actual_type = type(value).__name__
-                    validation_errors.append(
-                        f"Field '{field_name}' should be {expected_type}, got {actual_type}"
-                    )
+            if expected_type and not self._check_type(value, expected_type):
+                actual_type = type(value).__name__
+                validation_errors.append(
+                    f"Field '{field_name}' should be {expected_type}, got {actual_type}"
+                )
 
-            # Enum validation
             if "enum" in field_def and field_def["enum"]:
                 allowed_values = field_def["enum"]
                 if value not in allowed_values:
@@ -197,10 +215,8 @@ class OutputValidator:
                         f"Allowed values: {allowed_values}"
                     )
 
-            # Add to validated output (only declared fields)
             validated_output[field_name] = value
 
-        # Filter undeclared fields (only return declared fields)
         for field_name in output:
             if field_name not in self.schema:
                 logger.debug("Filtering undeclared field '%s' from output", field_name)
@@ -210,9 +226,7 @@ class OutputValidator:
             raise OutputValidationError(error_message)
 
         logger.info("Output validation passed for %s fields", len(validated_output))
-        if wrapped_result is not None:
-            return wrapped_result.model_copy(update={"output": validated_output})
-        return validated_output
+        return self._wrap_validated_output(wrapped_result, validated_output)
 
     def _check_type(self, value: Any, expected_type: str) -> bool:
         """