tactus 0.33.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

tactus/testing/behave_integration.py

@@ -8,16 +8,145 @@ from parsed Gherkin and registered steps.
 import logging
 import tempfile
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Any, Dict, List, Optional
 
 from .models import ParsedFeature, ParsedScenario
 from .steps.registry import StepRegistry
 from .steps.custom import CustomStepManager
 
-
 logger = logging.getLogger(__name__)
 
 
+def load_custom_steps_from_lua(procedure_file: Path) -> Dict[str, Any]:
+    """
+    Load custom step definitions from a procedure file using the Lua runtime.
+
+    This function executes the Lua code to capture actual Lua function references,
+    unlike the validator which does static analysis and returns None for functions.
+
+    Args:
+        procedure_file: Path to the .tac procedure file
+
+    Returns:
+        Dict mapping step patterns to Lua function references
+    """
+    from tactus.core.lua_sandbox import LuaSandbox
+    from tactus.core.registry import RegistryBuilder
+    from tactus.core.dsl_stubs import create_dsl_stubs
+
+    # Create a minimal sandbox and builder
+    sandbox = LuaSandbox()
+    builder = RegistryBuilder()
+
+    # Create DSL stubs that capture the Lua functions
+    stubs = create_dsl_stubs(builder, tool_primitive=None, mock_manager=None)
+
+    # Remove internal items
+    stubs.pop("_registries", None)
+    stubs.pop("_tactus_register_binding", None)
+
+    # Inject stubs into sandbox
+    for name, stub in stubs.items():
+        sandbox.set_global(name, stub)
+
+    # Execute the procedure file
+    source = procedure_file.read_text()
+    try:
+        sandbox.execute(source)
+    except Exception as e:
+        logger.warning(f"Error executing procedure for custom steps: {e}")
+        return {}
+
+    # Return the custom steps with actual Lua function references
+    result = builder.validate()
+    if result.registry and result.registry.custom_steps:
+        return result.registry.custom_steps
+    return {}
+
+
+def load_custom_steps_in_context(test_context: Any) -> Dict[str, Any]:
+    """
+    Load custom step definitions using the test context's runtime.
+
+    This ensures the Lua functions have access to a proper runtime for
+    executing agents, Classify primitives, etc.
+
+    Args:
+        test_context: TactusTestContext with an initialized runtime
+
+    Returns:
+        Dict mapping step patterns to Lua function references
+    """
+    from tactus.core.registry import RegistryBuilder
+    from tactus.core.dsl_stubs import create_dsl_stubs
+
+    # Ensure runtime is set up
+    if not test_context.runtime:
+        test_context.setup_runtime()
+
+    # Get the runtime's sandbox
+    runtime = test_context.runtime
+
+    # Create a new builder to capture custom steps
+    builder = RegistryBuilder()
+
+    # Ensure a mock manager exists so Mocks {} in spec files can be applied
+    # during custom step execution, even when tests are not in mocked mode.
+    mock_manager = runtime.mock_manager if hasattr(runtime, "mock_manager") else None
+    if mock_manager is None:
+        from tactus.core.mocking import MockManager
+
+        mock_manager = MockManager()
+
+    # Create DSL stubs connected to the runtime
+    # We pass the runtime's existing components including execution_context
+    stubs = create_dsl_stubs(
+        builder,
+        tool_primitive=runtime.tool_primitive if hasattr(runtime, "tool_primitive") else None,
+        mock_manager=mock_manager,
+        runtime_context={
+            "runtime": runtime,
+            "execution_context": (
+                runtime.execution_context if hasattr(runtime, "execution_context") else None
+            ),
+            "registry": runtime.registry if hasattr(runtime, "registry") else None,
+            "log_handler": runtime.log_handler if hasattr(runtime, "log_handler") else None,
+            "mock_manager": mock_manager,
+            "tool_primitive": (
+                runtime.tool_primitive if hasattr(runtime, "tool_primitive") else None
+            ),
+            "_created_agents": {},
+        },
+    )
+
+    # Remove internal items
+    stubs.pop("_registries", None)
+    stubs.pop("_tactus_register_binding", None)
+
+    # Create a fresh sandbox for loading custom steps
+    from tactus.core.lua_sandbox import LuaSandbox
+
+    sandbox = LuaSandbox()
+
+    # Inject stubs into sandbox
+    for name, stub in stubs.items():
+        sandbox.set_global(name, stub)
+
+    # Execute the procedure file to capture step definitions
+    source = test_context.procedure_file.read_text()
+    try:
+        sandbox.execute(source)
+    except Exception as e:
+        logger.warning(f"Error loading custom steps in context: {e}")
+        return {}
+
+    # Return the custom steps
+    result = builder.validate()
+    if result.registry and result.registry.custom_steps:
+        return result.registry.custom_steps
+    return {}
+
+
 class BehaveFeatureGenerator:
     """
     Generates Behave-compatible .feature files from parsed Gherkin.
@@ -173,6 +302,32 @@ class BehaveStepsGenerator:
                 f.write("    # Call the actual step function from builtin module\n")
                 f.write(f"    builtin.{func_name}(context.tac, **kwargs)\n\n")
 
+            # Generate custom step patterns using regex matcher
+            custom_patterns = custom_steps.get_all_patterns() if custom_steps else []
+            if custom_patterns:
+                f.write("# Custom step definitions from procedure file\n")
+                f.write("use_step_matcher('re')\n\n")
+
+                for i, pattern in enumerate(custom_patterns):
+                    wrapper_name = f"custom_step_{i}"
+                    # Escape the pattern for Python string (use raw string)
+                    escaped_pattern = pattern.replace("\\", "\\\\").replace("'", "\\'")
+                    # For the pattern argument, just escape single quotes since we use single-quoted raw string
+                    pattern_arg = pattern.replace("'", "\\'")
+                    # Escape docstring (remove quotes for safety)
+                    docstring_pattern = pattern[:50].replace('"', "'").replace("\\", "")
+
+                    f.write(f"@step(r'{escaped_pattern}')\n")
+                    f.write(f"def {wrapper_name}(context, *args):\n")
+                    f.write(f'    """Custom step: {docstring_pattern}"""\n')
+                    f.write("    # Execute via custom step manager with captured groups\n")
+                    f.write(
+                        f"    context.custom_steps.execute_by_pattern(r'{pattern_arg}', context.tac, *args)\n\n"
+                    )
+
+                # Switch back to parse matcher for any remaining steps
+                f.write("use_step_matcher('parse')\n\n")
+
         logger.info(f"Generated steps file: {steps_file}")
         return steps_file
 
@@ -267,7 +422,10 @@ class BehaveEnvironmentGenerator:
             f.write("from tactus.testing.context import TactusTestContext\n")
             f.write("from tactus.testing.steps.registry import StepRegistry\n")
             f.write("from tactus.testing.steps.builtin import register_builtin_steps\n")
-            f.write("from tactus.testing.steps.custom import CustomStepManager\n\n")
+            f.write("from tactus.testing.steps.custom import CustomStepManager\n")
+            f.write(
+                "from tactus.testing.behave_integration import load_custom_steps_in_context\n\n"
+            )
 
             f.write("def before_all(context):\n")
             f.write('    """Setup before all tests."""\n')
@@ -275,9 +433,6 @@ class BehaveEnvironmentGenerator:
             f.write("    context.step_registry = StepRegistry()\n")
             f.write("    register_builtin_steps(context.step_registry)\n")
             f.write("    \n")
-            f.write("    # Initialize custom step manager\n")
-            f.write("    context.custom_steps = CustomStepManager()\n")
-            f.write("    \n")
             f.write("    # Store test configuration (using absolute path)\n")
             f.write(f"    context.procedure_file = Path(r'{absolute_procedure_file}')\n")
             f.write(f"    context.mock_tools = json.loads('{mock_tools_json}')\n")
@@ -308,7 +463,16 @@ class BehaveEnvironmentGenerator:
                 "        context.mock_registry = UnifiedMockRegistry(hitl_handler=MockHITLHandler())\n"
             )
             f.write("        # Share mock registry with TactusTestContext\n")
-            f.write("        context.tac.mock_registry = context.mock_registry\n\n")
+            f.write("        context.tac.mock_registry = context.mock_registry\n")
+            f.write("    \n")
+            f.write("    # Load custom steps with runtime context for this scenario\n")
+            f.write(
+                "    # (This ensures Lua functions have access to the runtime for agents, etc.)\n"
+            )
+            f.write("    context.custom_steps = CustomStepManager()\n")
+            f.write("    custom_steps_dict = load_custom_steps_in_context(context.tac)\n")
+            f.write("    for pattern, lua_func in custom_steps_dict.items():\n")
+            f.write("        context.custom_steps.register_from_lua(pattern, lua_func)\n\n")
 
             f.write("def after_scenario(context, scenario):\n")
             f.write('    """Cleanup after each scenario."""\n')

tactus/testing/context.py

@@ -10,7 +10,6 @@ import logging
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-
 logger = logging.getLogger(__name__)
 
 

tactus/testing/evaluation_runner.py

@@ -14,7 +14,6 @@ from typing import List
 from .models import ScenarioResult, EvaluationResult
 from .test_runner import TactusTestRunner
 
-
 logger = logging.getLogger(__name__)
 
 

tactus/testing/gherkin_parser.py

@@ -15,7 +15,6 @@ except ImportError:
 
 from .models import ParsedStep, ParsedScenario, ParsedFeature
 
-
 logger = logging.getLogger(__name__)
 
 

tactus/testing/mock_hitl.py

@@ -11,7 +11,6 @@ from typing import Any, Dict, Optional
 
 from tactus.protocols.models import HITLRequest, HITLResponse
 
-
 logger = logging.getLogger(__name__)
 
 

tactus/testing/mock_tools.py

@@ -10,7 +10,6 @@ from typing import Any, Dict
 
 from tactus.primitives.tool import ToolPrimitive, ToolCall
 
-
 logger = logging.getLogger(__name__)
 
 

tactus/testing/models.py

@@ -6,7 +6,6 @@ from datetime import datetime
 from typing import List, Optional
 from pydantic import BaseModel, Field
 
-
 # Parsed Gherkin Models (from gherkin-official)
 
 

tactus/testing/steps/builtin.py

@@ -18,7 +18,6 @@ from typing import Any
 
 from .registry import StepRegistry
 
-
 logger = logging.getLogger(__name__)
 
 

tactus/testing/steps/custom.py

@@ -1,40 +1,71 @@
 """
 Custom step manager for user-defined Lua step functions.
+
+Supports regex pattern matching for step definitions, allowing
+expressive BDD specifications with captured arguments.
 """
 
 import logging
-from typing import Any, Dict
-
+import re
+from typing import Any, Dict, Optional, Tuple
 
 logger = logging.getLogger(__name__)
 
 
 class CustomStepManager:
     """
-    Manages custom Lua step definitions.
+    Manages custom Lua step definitions with regex pattern matching.
 
     Allows users to define custom steps in their procedure files
-    using the step() function with Lua implementations.
+    using the Step() function with regex patterns and Lua implementations.
+
+    Example:
+        Step("a classifier with classes (.+)", function(ctx, classes)
+            -- classes contains the captured group
+        end)
     """
 
     def __init__(self, lua_sandbox=None):
         self.lua_sandbox = lua_sandbox
-        self.custom_steps: Dict[str, Any] = {}
+        self._steps: Dict[re.Pattern, Any] = {}  # compiled_pattern -> lua_function
+        self._patterns: Dict[str, re.Pattern] = {}  # pattern_str -> compiled_pattern
 
-    def register_from_lua(self, step_text: str, lua_function: Any) -> None:
+    def register_from_lua(self, pattern: str, lua_function: Any) -> None:
         """
-        Register a custom step from Lua code.
+        Register a custom step from Lua code with regex pattern.
 
         Args:
-            step_text: The step text pattern (exact match)
+            pattern: The step text pattern (regex with capture groups)
             lua_function: Lua function reference to execute
         """
-        self.custom_steps[step_text] = lua_function
-        logger.debug(f"Registered custom step: {step_text}")
+        try:
+            compiled = re.compile(pattern, re.IGNORECASE)
+            self._steps[compiled] = lua_function
+            self._patterns[pattern] = compiled
+            logger.debug(f"Registered custom step pattern: {pattern}")
+        except re.error as e:
+            logger.error(f"Invalid regex pattern '{pattern}': {e}")
+            raise ValueError(f"Invalid step pattern: {e}")
+
+    def _match(self, step_text: str) -> Optional[Tuple[Any, tuple]]:
+        """
+        Find a matching pattern and return the Lua function with captured groups.
+
+        Args:
+            step_text: The step text to match
+
+        Returns:
+            Tuple of (lua_function, captured_groups) if match found, None otherwise
+        """
+        for pattern, lua_func in self._steps.items():
+            match = pattern.match(step_text)
+            if match:
+                return lua_func, match.groups()
+        return None
 
     def execute(self, step_text: str, context: Any) -> bool:
         """
-        Execute custom Lua step if it exists.
+        Execute custom Lua step if pattern matches.
 
         Args:
             step_text: The step text to match
@@ -43,12 +74,12 @@ class CustomStepManager:
         Returns:
             True if step was found and executed, False otherwise
         """
-        if step_text in self.custom_steps:
-            lua_func = self.custom_steps[step_text]
+        result = self._match(step_text)
+        if result:
+            lua_func, groups = result
             try:
-                # Call Lua function with context
-                # The Lua function should perform assertions
-                lua_func(context)
+                # Call Lua function with context + captured groups
+                lua_func(context, *groups)
                 return True
             except Exception as e:
                 logger.error(f"Custom step '{step_text}' failed: {e}")
@@ -57,13 +88,41 @@ class CustomStepManager:
         return False
 
     def has_step(self, step_text: str) -> bool:
-        """Check if custom step exists."""
-        return step_text in self.custom_steps
+        """Check if any pattern matches the step text."""
+        return self._match(step_text) is not None
+
+    def get_all_patterns(self) -> list[str]:
+        """Get all registered pattern strings."""
+        return list(self._patterns.keys())
 
-    def get_all_steps(self) -> list[str]:
-        """Get all registered custom step texts."""
-        return list(self.custom_steps.keys())
+    def execute_by_pattern(self, pattern: str, context: Any, *args) -> bool:
+        """
+        Execute custom Lua step by pattern string with pre-captured args.
+
+        This is used when the regex matching has already been done (e.g., by Behave)
+        and we just need to call the Lua function with the captured groups.
+
+        Args:
+            pattern: The pattern string to look up
+            context: Test context object
+            *args: Captured groups from regex match
+
+        Returns:
+            True if step was found and executed, False otherwise
+        """
+        if pattern in self._patterns:
+            compiled = self._patterns[pattern]
+            lua_func = self._steps.get(compiled)
+            if lua_func:
+                try:
+                    lua_func(context, *args)
+                    return True
+                except Exception as e:
+                    logger.error(f"Custom step '{pattern}' failed: {e}")
+                    raise AssertionError(f"Custom step failed: {e}")
+        return False
 
     def clear(self) -> None:
         """Clear all custom steps."""
-        self.custom_steps.clear()
+        self._steps.clear()
+        self._patterns.clear()

tactus/testing/steps/registry.py

@@ -6,7 +6,6 @@ import re
 import logging
 from typing import Callable, Dict, Optional, Pattern, Tuple
 
-
 logger = logging.getLogger(__name__)
 
 

tactus/testing/test_runner.py

@@ -68,13 +68,19 @@ class TactusTestRunner:
         # Register built-in steps
         register_builtin_steps(self.step_registry)
 
-    def setup(self, gherkin_text: str) -> None:
+    def setup(self, gherkin_text: str, custom_steps_dict: Optional[dict] = None) -> None:
         """
         Setup test environment from Gherkin text.
 
         Args:
             gherkin_text: Raw Gherkin feature text
+            custom_steps_dict: Optional dict of step patterns to Lua functions from registry
         """
+        # Register custom steps from registry if provided
+        if custom_steps_dict:
+            for pattern, lua_func in custom_steps_dict.items():
+                self.custom_steps.register_from_lua(pattern, lua_func)
+
         # Parse Gherkin
         parser = GherkinParser()
         self.parsed_feature = parser.parse(gherkin_text)

tactus/validation/semantic_visitor.py

@@ -12,7 +12,6 @@ from .generated.LuaParser import LuaParser
 from .generated.LuaParserVisitor import LuaParserVisitor
 from tactus.core.registry import RegistryBuilder, ValidationMessage
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -467,11 +466,18 @@ class TactusDSLVisitor(LuaParserVisitor):
             if args and len(args) >= 2:
                 self.builder.register_hitl(args[0], args[1] if isinstance(args[1], dict) else {})
         elif func_name == "Specification":  # CamelCase
-            # Either:
-            # - Specification([[ Gherkin text ]]) (alias for Specifications)
-            # - Specification("name", { ... })   (structured form)
+            # Three supported forms:
+            # - Specification([[ Gherkin text ]]) (inline Gherkin)
+            # - Specification("name", { ... })   (structured form; legacy)
+            # - Specification { from = "path" }  (external file reference)
             if args and len(args) == 1:
-                self.builder.register_specifications(args[0])
+                arg = args[0]
+                if isinstance(arg, dict) and "from" in arg:
+                    # External file reference
+                    self.builder.register_specs_from(arg["from"])
+                else:
+                    # Inline Gherkin text
+                    self.builder.register_specifications(arg)
             elif args and len(args) >= 2:
                 self.builder.register_specification(
                     args[0], args[1] if isinstance(args[1], list) else []

tactus/validation/validator.py

@@ -18,7 +18,6 @@ from .semantic_visitor import TactusDSLVisitor
 from .error_listener import TactusErrorListener
 from tactus.core.registry import ValidationResult, ValidationMessage
 
-
 logger = logging.getLogger(__name__)
 
 

{tactus-0.33.0.dist-info → tactus-0.34.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tactus
-Version: 0.33.0
+Version: 0.34.0
 Summary: Tactus: Lua-based DSL for agentic workflows
 Project-URL: Homepage, https://github.com/AnthusAI/Tactus
 Project-URL: Documentation, https://github.com/AnthusAI/Tactus/tree/main/docs
@@ -30,7 +30,7 @@ Requires-Dist: gherkin-official>=28.0.0
 Requires-Dist: h5py>=3.10
 Requires-Dist: lupa>=2.6
 Requires-Dist: nanoid>=2.0.0
-Requires-Dist: openai>=1.35.10
+Requires-Dist: nest-asyncio>=1.5.0
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: pyarrow>=14.0
 Requires-Dist: pydantic-ai[bedrock]
@@ -49,6 +49,16 @@ Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: python-semantic-release>=9.0.0; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: discord-py>=2.0; extra == 'discord'
+Provides-Extra: email
+Requires-Dist: aiosmtplib>=3.0; extra == 'email'
+Provides-Extra: notifications
+Requires-Dist: aiosmtplib>=3.0; extra == 'notifications'
+Requires-Dist: discord-py>=2.0; extra == 'notifications'
+Requires-Dist: slack-sdk>=3.0; extra == 'notifications'
+Provides-Extra: slack
+Requires-Dist: slack-sdk>=3.0; extra == 'slack'
 Description-Content-Type: text/markdown
 
 # Tactus
@@ -502,6 +512,8 @@ See [docs/TOOLS.md](docs/TOOLS.md) for the complete tools reference.
 pip install tactus
 ```
 
+**Docker required by default:** `tactus run` uses a Docker sandbox for isolation and will error if Docker is not available. Use `--no-sandbox` (or set `sandbox.enabled: false` in config) to opt out when your architecture does not require container isolation.
+
 ### Your First Procedure
 
 Create `hello.tac`: