tactus 0.30.0__py3-none-any.whl → 0.31.1__py3-none-any.whl

tactus/core/dsl_stubs.py

@@ -469,20 +469,21 @@ def create_dsl_stubs(
 
         return accept_config
 
-    def _stages(*stage_names) -> None:
-        """Register stage names."""
-        # Handle both stages("a", "b", "c") and stages({"a", "b", "c"})
-        if len(stage_names) == 1 and hasattr(stage_names[0], "items"):
-            # Single Lua table argument - convert it
-            stages_list = lua_table_to_dict(stage_names[0])
-        else:
-            # Multiple string arguments
-            stages_list = list(stage_names)
-        builder.set_stages(stages_list)
-
-    def _specification(spec_name: str, scenarios) -> None:
-        """Register a BDD specification."""
-        builder.register_specification(spec_name, lua_table_to_dict(scenarios))
+    def _specification(*args) -> None:
+        """Register BDD specs.
+
+        Supported forms:
+          - Specification([[ Gherkin text ]])  (alias for Specifications)
+          - Specification("name", { ... })     (structured form; legacy)
+        """
+        if len(args) == 1:
+            builder.register_specifications(args[0])
+            return
+        if len(args) >= 2:
+            spec_name, scenarios = args[0], args[1]
+            builder.register_specification(spec_name, lua_table_to_dict(scenarios))
+            return
+        raise TypeError("Specification expects either (gherkin_text) or (name, scenarios)")
 
     def _specifications(gherkin_text: str) -> None:
         """Register Gherkin BDD specifications."""
@@ -493,8 +494,17 @@ def create_dsl_stubs(
         builder.register_custom_step(step_text, lua_function)
 
     def _evaluation(config) -> None:
-        """Set evaluation configuration."""
-        builder.set_evaluation_config(lua_table_to_dict(config or {}))
+        """Register evaluation configuration.
+
+        Supported forms:
+          - Evaluation({ runs=..., parallel=... })          (single-run config)
+          - Evaluation({ dataset=..., evaluators=..., ...}) (alias for Evaluations)
+        """
+        config_dict = lua_table_to_dict(config or {})
+        if any(k in config_dict for k in ("dataset", "dataset_file", "evaluators", "thresholds")):
+            builder.register_evaluations(config_dict)
+            return
+        builder.set_evaluation_config(config_dict)
 
     def _evaluations(config) -> None:
         """Register Pydantic Evals evaluation configuration."""
@@ -690,6 +700,28 @@ def create_dsl_stubs(
         "integer": _field_builder("integer"),
     }
 
+    def _evaluator_builder(evaluator_type: str):
+        """Create a simple evaluator config builder for Evaluation(s)({ evaluators = {...} })."""
+
+        def build_evaluator(options=None):
+            if options is None:
+                options = {}
+            if hasattr(options, "items"):
+                options = lua_table_to_dict(options)
+            if not isinstance(options, dict):
+                options = {}
+            cfg = {"type": evaluator_type}
+            cfg.update(options)
+            return cfg
+
+        return build_evaluator
+
+    # Evaluation(s)() helper constructors (Pydantic Evals integration).
+    # These are configuration builders, not runtime behavior.
+    field["equals_expected"] = _evaluator_builder("equals_expected")
+    field["min_length"] = _evaluator_builder("min_length")
+    field["contains"] = _evaluator_builder("contains")
+
     # Create lookup functions for uppercase names (Agent, Model)
     # These allow: Agent("greeter")(), Model("classifier")()  (callable syntax)
     _Agent = AgentLookup(_agent_registry)
@@ -1256,6 +1288,12 @@ def create_dsl_stubs(
             if len(config_dict) == 0:
                 config_dict = {}
 
+        # Normalize empty schemas (lua {} -> python []) so tools treat empty schemas
+        # as empty objects, not arrays.
+        if isinstance(config_dict, dict):
+            config_dict["input"] = _normalize_schema(config_dict.get("input", {}))
+            config_dict["output"] = _normalize_schema(config_dict.get("output", {}))
+
         # Check for legacy handler field
         if handler_fn is None and isinstance(config_dict, dict):
             handler_fn = config_dict.pop("handler", None)
@@ -1429,6 +1467,12 @@ def create_dsl_stubs(
             if len(config_dict) == 0:
                 config_dict = {}
 
+        # Normalize empty schemas (lua {} -> python []) so tools treat empty schemas
+        # as empty objects, not arrays.
+        if isinstance(config_dict, dict):
+            config_dict["input"] = _normalize_schema(config_dict.get("input", {}))
+            config_dict["output"] = _normalize_schema(config_dict.get("output", {}))
+
         # Check for legacy handler field
         if handler_fn is None and isinstance(config_dict, dict):
             handler_fn = config_dict.pop("handler", None)
@@ -1573,19 +1617,44 @@ def create_dsl_stubs(
         """
         config_dict = lua_table_to_dict(config)
 
-        # Handle tools field - convert ToolHandles to their names
+        # No alias support: toolsets -> tools is not supported.
+        if "toolsets" in config_dict:
+            raise ValueError(
+                f"Agent '{agent_name}': 'toolsets' is not supported. Use 'tools' for tool/toolset references."
+            )
+
+        # inline_tools: inline tool definitions only (list of dicts with "handler")
+        if "inline_tools" in config_dict:
+            inline_tools = config_dict["inline_tools"]
+            if isinstance(inline_tools, (list, tuple)):
+                non_dict_items = [t for t in inline_tools if not isinstance(t, dict)]
+                if non_dict_items:
+                    raise ValueError(
+                        f"Agent '{agent_name}': 'inline_tools' must be a list of inline tool definitions."
+                    )
+            elif inline_tools is not None:
+                raise ValueError(
+                    f"Agent '{agent_name}': 'inline_tools' must be a list of inline tool definitions."
+                )
+
+        # tools: tool/toolset references and toolset expressions (filter dicts)
         if "tools" in config_dict:
             tools = config_dict["tools"]
             if isinstance(tools, (list, tuple)):
-                tool_names = []
+                normalized = []
                 for t in tools:
-                    if hasattr(t, "name"):  # ToolHandle
-                        tool_names.append(t.name)
-                    elif isinstance(t, str):
-                        tool_names.append(t)
-                # Store as toolsets for runtime compatibility
-                config_dict["toolsets"] = tool_names
-                del config_dict["tools"]
+                    if isinstance(t, dict):
+                        if "handler" in t:
+                            raise ValueError(
+                                f"Agent '{agent_name}': inline tool definitions must be in 'inline_tools', not 'tools'."
+                            )
+                        normalized.append(t)
+                        continue
+                    if hasattr(t, "name"):  # ToolHandle or ToolsetHandle
+                        normalized.append(t.name)
+                    else:
+                        normalized.append(t)
+                config_dict["tools"] = normalized
 
         # Extract input schema if present
         input_schema = None
@@ -1605,9 +1674,11 @@ def create_dsl_stubs(
                 config_dict["output_schema"] = output_schema
                 del config_dict["output"]
 
-        # Support 'session' as an alias for 'message_history'
-        if "session" in config_dict and "message_history" not in config_dict:
-            config_dict["message_history"] = config_dict["session"]
+        # No compatibility aliases: session -> message_history is not supported.
+        if "session" in config_dict:
+            raise ValueError(
+                f"Agent '{agent_name}': 'session' is not supported. Use 'message_history'."
+            )
 
         # Register agent with provided name
         builder.register_agent(agent_name, config_dict, output_schema)
@@ -1635,6 +1706,12 @@ def create_dsl_stubs(
                 # expects name as a separate parameter. We need to pass config without 'name'.
                 agent_config = {k: v for k, v in config_dict.items() if k != "name"}
 
+                # Agent DSL uses `tools` for tool/toolset references; the DSPy agent config uses
+                # `toolsets` for the resolved toolsets list.
+                if "tools" in agent_config and "toolsets" not in agent_config:
+                    agent_config["toolsets"] = agent_config["tools"]
+                    del agent_config["tools"]
+
                 # Pre-process model format: combine provider and model into "provider:model"
                 # This matches what _setup_agents does
                 if "provider" in agent_config and "model" in agent_config:
@@ -1729,19 +1806,40 @@ def create_dsl_stubs(
 
         config_dict = lua_table_to_dict(config)
 
-        # Handle tools field - convert ToolHandles to their names
+        # No alias support: toolsets -> tools is not supported.
+        if "toolsets" in config_dict:
+            raise ValueError("Agent: 'toolsets' is not supported. Use 'tools'.")
+
+        # inline_tools: inline tool definitions only (list of dicts with "handler")
+        if "inline_tools" in config_dict:
+            inline_tools = config_dict["inline_tools"]
+            if isinstance(inline_tools, (list, tuple)):
+                non_dict_items = [t for t in inline_tools if not isinstance(t, dict)]
+                if non_dict_items:
+                    raise ValueError(
+                        "Agent: 'inline_tools' must be a list of inline tool definitions."
+                    )
+            elif inline_tools is not None:
+                raise ValueError("Agent: 'inline_tools' must be a list of inline tool definitions.")
+
+        # tools: tool/toolset references and toolset expressions (filter dicts)
         if "tools" in config_dict:
             tools = config_dict["tools"]
             if isinstance(tools, (list, tuple)):
-                tool_names = []
+                normalized = []
                 for t in tools:
-                    if hasattr(t, "name"):  # ToolHandle
-                        tool_names.append(t.name)
-                    elif isinstance(t, str):
-                        tool_names.append(t)
-                # Store as toolsets for runtime compatibility
-                config_dict["toolsets"] = tool_names
-                del config_dict["tools"]
+                    if isinstance(t, dict):
+                        if "handler" in t:
+                            raise ValueError(
+                                "Agent: inline tool definitions must be in 'inline_tools', not 'tools'."
+                            )
+                        normalized.append(t)
+                        continue
+                    if hasattr(t, "name"):  # ToolHandle or ToolsetHandle
+                        normalized.append(t.name)
+                    else:
+                        normalized.append(t)
+                config_dict["tools"] = normalized
 
         # Extract input schema if present
         input_schema = None
@@ -1761,9 +1859,9 @@ def create_dsl_stubs(
                 config_dict["output_schema"] = output_schema
                 del config_dict["output"]
 
-        # Support 'session' as an alias for 'message_history'
-        if "session" in config_dict and "message_history" not in config_dict:
-            config_dict["message_history"] = config_dict["session"]
+        # No compatibility aliases: session -> message_history is not supported.
+        if "session" in config_dict:
+            raise ValueError("Agent: 'session' is not supported. Use 'message_history'.")
 
         # Generate a temporary name - will be replaced when assigned
         import uuid
@@ -1863,7 +1961,6 @@ def create_dsl_stubs(
         "Toolset": _toolset,
         "Tool": _new_tool,  # NEW syntax - assignment based
         "Hitl": _hitl,
-        "Stages": _stages,
         "Specification": _specification,
         # BDD Testing
         "Specifications": _specifications,

tactus/core/output_validator.py

@@ -6,7 +6,7 @@ Enables type safety and composability for sub-agent workflows.
 """
 
 import logging
-from typing import Dict, Any, Optional, List
+from typing import Any, Optional, List
 
 logger = logging.getLogger(__name__)
 
@@ -37,7 +37,16 @@ class OutputValidator:
         "array": list,
     }
 
-    def __init__(self, output_schema: Optional[Dict[str, Any]] = None):
+    @classmethod
+    def _is_scalar_schema(cls, schema: Any) -> bool:
+        return (
+            isinstance(schema, dict)
+            and "type" in schema
+            and isinstance(schema.get("type"), str)
+            and schema.get("type") in cls.TYPE_MAP
+        )
+
+    def __init__(self, output_schema: Optional[Any] = None):
         """
         Initialize validator with output schema.
 
@@ -57,9 +66,17 @@ class OutputValidator:
                 }
         """
         self.schema = output_schema or {}
-        logger.debug(f"OutputValidator initialized with {len(self.schema)} output fields")
 
-    def validate(self, output: Any) -> Dict[str, Any]:
+        if self._is_scalar_schema(self.schema):
+            logger.debug("OutputValidator initialized with scalar output schema")
+        else:
+            try:
+                field_count = len(self.schema)
+            except TypeError:
+                field_count = 0
+            logger.debug(f"OutputValidator initialized with {field_count} output fields")
+
+    def validate(self, output: Any) -> Any:
         """
         Validate workflow output against schema.
 
@@ -72,16 +89,56 @@ class OutputValidator:
         Raises:
             OutputValidationError: If validation fails
         """
+        # If a procedure returns a Result wrapper, validate its `.output` payload
+        # while preserving the wrapper (so callers can still access usage/cost/etc.).
+        from tactus.protocols.result import TactusResult
+
+        wrapped_result: TactusResult | None = output if isinstance(output, TactusResult) else None
+        if wrapped_result is not None:
+            output = wrapped_result.output
+
         # If no schema defined, accept any output
         if not self.schema:
             logger.debug("No output schema defined, skipping validation")
             if isinstance(output, dict):
-                return output
+                validated_payload = output
             elif hasattr(output, "items"):
                 # Lua table - convert to dict
-                return dict(output.items())
+                validated_payload = dict(output.items())
             else:
-                return {"result": output}
+                validated_payload = output
+
+            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
+
+            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__}"
+                )
+
+            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
 
         # Convert Lua tables to dicts recursively
         if hasattr(output, "items") or isinstance(output, dict):
@@ -99,16 +156,13 @@ class OutputValidator:
 
         # Check required fields and validate types
         for field_name, field_def in self.schema.items():
-            # Check if it's the new syntax
-            from tactus.core.dsl_stubs import FieldDefinition
-
-            if not isinstance(field_def, FieldDefinition):
+            if not isinstance(field_def, dict) or "type" not in field_def:
                 errors.append(
                     f"Field '{field_name}' uses old type syntax. "
                     f"Use field.{field_def.get('type', 'string')}{{}} instead."
                 )
                 continue
-            is_required = field_def.get("required", False)
+            is_required = bool(field_def.get("required", False))
 
             if is_required and field_name not in output:
                 errors.append(f"Required field '{field_name}' is missing")
@@ -151,6 +205,8 @@ class OutputValidator:
             raise OutputValidationError(error_msg)
 
         logger.info(f"Output validation passed for {len(validated_output)} fields")
+        if wrapped_result is not None:
+            return wrapped_result.model_copy(update={"output": validated_output})
         return validated_output
 
     def _check_type(self, value: Any, expected_type: str) -> bool:
@@ -209,10 +265,8 @@ class OutputValidator:
     def get_field_description(self, field_name: str) -> Optional[str]:
         """Get description for an output field."""
         if field_name in self.schema:
-            from tactus.core.dsl_stubs import FieldDefinition
-
             field_def = self.schema[field_name]
-            if isinstance(field_def, FieldDefinition):
+            if isinstance(field_def, dict):
                 return field_def.get("description")
         return None
 

tactus/core/registry.py

@@ -48,13 +48,8 @@ class AgentDeclaration(BaseModel):
     model: Union[str, dict[str, Any]] = "gpt-4o"
     system_prompt: Union[str, Any]  # String with {markers} or Lua function
     initial_message: Optional[str] = None
-    tools: list[Union[str, dict[str, Any]]] = Field(
-        default_factory=list
-    )  # Supports toolset expressions
-    inline_tool_defs: list[dict[str, Any]] = Field(
-        default_factory=list
-    )  # Inline tool definitions with Lua handlers
-    output: Optional[AgentOutputSchema] = None  # Legacy field
+    tools: list[Any] = Field(default_factory=list)  # Tool/toolset references and expressions
+    inline_tools: list[dict[str, Any]] = Field(default_factory=list)  # Inline tool definitions
     output: Optional[AgentOutputSchema] = None  # Aligned with pydantic-ai
     message_history: Optional[MessageHistoryConfiguration] = None
     max_turns: int = 50
@@ -127,6 +122,10 @@ class AgentMockConfig(BaseModel):
         default_factory=dict,
         description="Optional token usage payload (exposed as result.usage in Lua)",
     )
+    temporal: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Optional temporal mock turns (1-indexed by agent turn).",
+    )
 
 
 class ProcedureRegistry(BaseModel):
@@ -146,7 +145,6 @@ class ProcedureRegistry(BaseModel):
     toolsets: dict[str, dict[str, Any]] = Field(default_factory=dict)
     lua_tools: dict[str, dict[str, Any]] = Field(default_factory=dict)  # Lua function tools
     hitl_points: dict[str, HITLDeclaration] = Field(default_factory=dict)
-    stages: list[str] = Field(default_factory=list)
     specifications: list[SpecificationDeclaration] = Field(default_factory=list)
     dependencies: dict[str, DependencyDeclaration] = Field(default_factory=dict)
     mocks: dict[str, dict[str, Any]] = Field(default_factory=dict)  # Mock configurations
@@ -241,19 +239,6 @@ class RegistryBuilder:
                 fields[field_name] = OutputFieldDeclaration(**field_config_with_name)
             config["output"] = AgentOutputSchema(fields=fields)
 
-        # Handle toolsets -> tools rename (backward compatibility)
-        # The Lua DSL uses "toolsets" for toolset references and "tools" for inline tool definitions
-        # AgentDeclaration expects "tools" for toolset references
-        if "toolsets" in config:
-            if "tools" in config:
-                # Both exist: tools = inline defs, toolsets = references
-                # Keep inline defs in a temp field, use toolsets as tools
-                config["inline_tool_defs"] = config.pop("tools")
-                config["tools"] = config.pop("toolsets")
-            else:
-                # Only toolsets exists: rename to tools
-                config["tools"] = config.pop("toolsets")
-
         # Apply defaults
         if "provider" not in config and self.registry.default_provider:
             config["provider"] = self.registry.default_provider
@@ -340,10 +325,6 @@ class RegistryBuilder:
         except Exception as e:
             self._add_error(f"Invalid agent mock config for '{agent_name}': {e}")
 
-    def set_stages(self, stage_names: list[str]) -> None:
-        """Set stage names."""
-        self.registry.stages = stage_names
-
     def register_specification(self, name: str, scenarios: list) -> None:
         """Register a BDD specification."""
         try:
@@ -379,6 +360,13 @@ class RegistryBuilder:
             "state_schema": state_schema,
         }
 
+        # If this is the main entry point, also populate the top-level schemas so
+        # runtime output validation and tooling use a single canonical `output`.
+        if name == "main":
+            self.registry.input_schema = input_schema
+            self.registry.output_schema = output_schema
+            self.registry.state_schema = state_schema
+
     def register_top_level_input(self, schema: dict) -> None:
         """Register top-level input schema for script mode."""
         self.registry.top_level_input_schema = schema