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

tactus/__init__.py

@@ -5,7 +5,7 @@ Tactus provides a declarative workflow engine for AI agents with pluggable
 backends for storage, HITL, and chat recording.
 """
 
-__version__ = "0.35.1"
+__version__ = "0.36.0"
 
 # Core exports
 from tactus.core.runtime import TactusRuntime

tactus/adapters/channels/sse.py

@@ -248,7 +248,14 @@ class SSEControlChannel(InProcessChannel):
         """
         logger.info("%s: received response for %s", self.channel_id, request_id)
 
-        response = ControlResponse(
+        response = self._build_response(request_id, value)
+
+        # Push to queue from sync context (Flask thread)
+        # Get the running event loop and schedule the put operation
+        self._enqueue_response_from_sync_context(request_id, response)
+
+    def _build_response(self, request_id: str, value: Any) -> ControlResponse:
+        return ControlResponse(
             request_id=request_id,
             value=value,
             responded_at=datetime.now(timezone.utc),
@@ -256,15 +263,14 @@ class SSEControlChannel(InProcessChannel):
             channel_id=self.channel_id,
         )
 
-        # Push to queue from sync context (Flask thread)
-        # Get the running event loop and schedule the put operation
+    def _enqueue_response_from_sync_context(
+        self, request_id: str, response: ControlResponse
+    ) -> None:
         try:
             event_loop = asyncio.get_event_loop()
             if event_loop.is_running():
-                # Schedule the coroutine in the running loop
                 asyncio.run_coroutine_threadsafe(self._response_queue.put(response), event_loop)
             else:
-                # If no loop is running, use put_nowait (shouldn't happen)
                 self._response_queue.put_nowait(response)
         except Exception as error:
             logger.error(

tactus/adapters/control_loop.py

@@ -201,37 +201,12 @@ class ControlLoopHandler:
             message[:50],
         )
 
-        # Run the async request flow
-        # Check if we're already in an async context
-        try:
-            event_loop = asyncio.get_running_loop()
-            if event_loop.is_closed():
-                raise RuntimeError("Running event loop is closed")
+        # Run the async request flow.
+        running_event_loop = self._get_running_event_loop()
+        if running_event_loop is not None:
+            return self._run_request_in_running_loop(running_event_loop, request)
 
-            # Already in async context - create task and run it
-            # This shouldn't normally happen since request_interaction is sync
-            import nest_asyncio
-
-            nest_asyncio.apply()
-            return event_loop.run_until_complete(self._request_interaction_async(request))
-        except RuntimeError:
-            # Not in async context - create a temporary event loop.
-            previous_event_loop: asyncio.AbstractEventLoop | None = None
-            try:
-                previous_event_loop = asyncio.get_event_loop()
-            except RuntimeError:
-                previous_event_loop = None
-            else:
-                if getattr(previous_event_loop, "is_closed", lambda: False)():
-                    previous_event_loop = None
-
-            event_loop = asyncio.new_event_loop()
-            try:
-                asyncio.set_event_loop(event_loop)
-                return event_loop.run_until_complete(self._request_interaction_async(request))
-            finally:
-                event_loop.close()
-                asyncio.set_event_loop(previous_event_loop)
+        return self._run_request_in_new_loop(request)
 
     async def _request_interaction_async(self, request: ControlRequest) -> ControlResponse:
         """
@@ -312,6 +287,45 @@ class ControlLoopHandler:
 
         raise ProcedureWaitingForHuman(request.procedure_id, request.request_id)
 
+    def _get_running_event_loop(self) -> Optional[asyncio.AbstractEventLoop]:
+        try:
+            event_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return None
+
+        if event_loop.is_closed():
+            return None
+        return event_loop
+
+    def _run_request_in_running_loop(
+        self, event_loop: asyncio.AbstractEventLoop, request: ControlRequest
+    ) -> ControlResponse:
+        # Already in async context - create task and run it.
+        # This shouldn't normally happen since request_interaction is sync.
+        import nest_asyncio
+
+        nest_asyncio.apply()
+        return event_loop.run_until_complete(self._request_interaction_async(request))
+
+    def _run_request_in_new_loop(self, request: ControlRequest) -> ControlResponse:
+        # Not in async context - create a temporary event loop.
+        previous_event_loop: Optional[asyncio.AbstractEventLoop] = None
+        try:
+            previous_event_loop = asyncio.get_event_loop()
+        except RuntimeError:
+            previous_event_loop = None
+        else:
+            if getattr(previous_event_loop, "is_closed", lambda: False)():
+                previous_event_loop = None
+
+        event_loop = asyncio.new_event_loop()
+        try:
+            asyncio.set_event_loop(event_loop)
+            return event_loop.run_until_complete(self._request_interaction_async(request))
+        finally:
+            event_loop.close()
+            asyncio.set_event_loop(previous_event_loop)
+
     async def _fanout(
         self,
         request: ControlRequest,

tactus/core/execution_context.py

@@ -155,11 +155,16 @@ class BaseExecutionContext(ExecutionContext):
         self.lua_sandbox: Any | None = 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)
 

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

@@ -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[str | None, 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

@@ -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:
@@ -91,6 +92,15 @@ class OutputValidator:
             return dict(output.items())
         return output
 
+    @staticmethod
+    def _wrap_validated_output(
+        wrapped_result: Any | None,
+        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: Any | None,
+    ) -> 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: Any | None,
+    ) -> 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: Any | None,
+    ) -> 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:
         """

tactus/core/runtime.py

@@ -221,17 +221,7 @@ class TactusRuntime:
             logger.info("Step 0: Setting up Lua sandbox")
             strict_determinism = self.external_config.get("strict_determinism", False)
 
-            # Compute base_path for sandbox from source file path if available
-            # This ensures require() works correctly even when running from different directories
-            sandbox_base_path = None
-            if self.source_file_path:
-                from pathlib import Path
-
-                sandbox_base_path = str(Path(self.source_file_path).parent.resolve())
-                logger.debug(
-                    "Using source file directory as sandbox base_path: %s",
-                    sandbox_base_path,
-                )
+            sandbox_base_path = self._resolve_sandbox_base_path()
 
             self.lua_sandbox = LuaSandbox(
                 execution_context=None,
@@ -242,13 +232,7 @@ class TactusRuntime:
             # 0.5. Create execution context EARLY so it's available during DSL parsing
             # This is critical for immediate agent creation during parsing
             logger.info("Step 0.5: Creating execution context (early)")
-            self.execution_context = BaseExecutionContext(
-                procedure_id=self.procedure_id,
-                storage_backend=self.storage_backend,
-                hitl_handler=self.hitl_handler,
-                strict_determinism=strict_determinism,
-                log_handler=self.log_handler,
-            )
+            self.execution_context = self._create_execution_context(strict_determinism)
 
             # Set run_id if provided
             if self.run_id:
@@ -788,6 +772,30 @@ class TactusRuntime:
                 except Exception as e:
                     logger.warning("Error cleaning up dependencies: %s", e)
 
+    def _resolve_sandbox_base_path(self) -> str | None:
+        # Compute base_path for sandbox from source file path if available.
+        # This ensures require() works correctly even when running from different directories.
+        if not self.source_file_path:
+            return None
+
+        from pathlib import Path
+
+        sandbox_base_path = str(Path(self.source_file_path).parent.resolve())
+        logger.debug(
+            "Using source file directory as sandbox base_path: %s",
+            sandbox_base_path,
+        )
+        return sandbox_base_path
+
+    def _create_execution_context(self, strict_determinism: bool) -> BaseExecutionContext:
+        return BaseExecutionContext(
+            procedure_id=self.procedure_id,
+            storage_backend=self.storage_backend,
+            hitl_handler=self.hitl_handler,
+            strict_determinism=strict_determinism,
+            log_handler=self.log_handler,
+        )
+
     async def _initialize_primitives(
         self,
         placeholder_tool: ToolPrimitive | None = None,