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

tactus/validation/semantic_visitor.py

@@ -29,6 +29,8 @@ class TactusDSLVisitor(LuaParserVisitor):
         "Agent",  # CamelCase
         "Model",  # CamelCase
         "Procedure",  # CamelCase
+        "Task",  # CamelCase
+        "IncludeTasks",  # CamelCase
         "Prompt",  # CamelCase
         "Hitl",  # CamelCase
         "Specification",  # CamelCase
@@ -57,6 +59,9 @@ class TactusDSLVisitor(LuaParserVisitor):
         self.current_line = 0
         self.current_col = 0
         self.in_function_body = False  # Track if we're inside a function body
+        self._processed_task_calls: set[int] = set()
+        self._retriever_aliases: dict[str, str] = {}
+        self._retriever_modules: dict[str, str] = {}
 
     def _record_error(
         self,
@@ -90,6 +95,27 @@ class TactusDSLVisitor(LuaParserVisitor):
             self.in_function_body = previous_in_function_body
         return child_visit_result
 
+    def visitChunk(self, context: LuaParser.ChunkContext):
+        """Enforce IncludeTasks file task-only constraint when used."""
+        result = self.visitChildren(context)
+        if self.builder.registry.include_tasks:
+            # If any non-task declarations exist, error out.
+            if (
+                self.builder.registry.agents
+                or self.builder.registry.toolsets
+                or self.builder.registry.lua_tools
+                or self.builder.registry.contexts
+                or self.builder.registry.corpora
+                or self.builder.registry.retrievers
+                or self.builder.registry.compactors
+                or self.builder.registry.named_procedures
+            ):
+                self._record_error(
+                    "IncludeTasks files must only contain Task declarations.",
+                    declaration="IncludeTasks",
+                )
+        return result
+
     def visitStat(self, context: LuaParser.StatContext):
         """Handle statement nodes including assignments."""
         # Check if this is an assignment statement
@@ -103,6 +129,7 @@ class TactusDSLVisitor(LuaParserVisitor):
                 assignment_target_node = variable_list.var()[0]
                 if assignment_target_node.NAME():
                     assignment_target_name = assignment_target_node.NAME().getText()
+                    self._track_retriever_alias(assignment_target_name, expression_list)
 
                     # Check if this is a DSL setting assignment
                     setting_handlers_by_name = {
@@ -131,6 +158,16 @@ class TactusDSLVisitor(LuaParserVisitor):
                                 assignment_target_name, first_expression
                             )
 
+        attname_list = getattr(context, "attnamelist", None)
+        exp_list = getattr(context, "explist", None)
+        if callable(attname_list) and callable(exp_list):
+            attname_nodes = attname_list()
+            exp_nodes = exp_list()
+            if attname_nodes and exp_nodes:
+                name_nodes = attname_nodes.NAME()
+                if name_nodes:
+                    self._track_retriever_alias(name_nodes[0].getText(), exp_nodes)
+
         # Continue visiting children
         return self.visitChildren(context)
 
@@ -144,12 +181,43 @@ class TactusDSLVisitor(LuaParserVisitor):
             if prefix_expression.functioncall():
                 function_call = prefix_expression.functioncall()
                 function_name = self._extract_function_name(function_call)
+                dotted_name = None
+                if function_name not in {
+                    "Agent",
+                    "Tool",
+                    "Toolset",
+                    "Context",
+                    "Corpus",
+                    "Retriever",
+                    "Compactor",
+                }:
+                    dotted_name = self._extract_dotted_dsl_name(function_call)
+                    if dotted_name:
+                        function_name = dotted_name
+                else:
+                    dotted_name = self._extract_dotted_dsl_name(function_call)
+
+                # Check if this is a chained method call (e.g., Agent('name').turn()).
+                # Dotted module calls like vector.Corpus { ... } are not chained.
+                get_text = getattr(function_call, "getText", None)
+                function_call_text = get_text() if callable(get_text) else ""
+                is_chained_method_call = (
+                    re.search(r"[)}\\]]\\s*\\.", function_call_text) is not None
+                )
 
-                # Check if this is a chained method call (e.g., Agent('name').turn())
-                # Chained calls have structure: func_name args . method_name args
-                # Simple declarations have: func_name args or func_name table
-                # If there are more than 2 children, it's a chained call, not a declaration
-                is_chained_method_call = function_call.getChildCount() > 2
+                if function_name in {"Corpus", "Retriever"}:
+                    has_namespace = dotted_name is not None or re.match(
+                        r"[A-Za-z_][A-Za-z0-9_]*\\.", function_call_text
+                    )
+                    if not has_namespace:
+                        self._record_error(
+                            message=(
+                                f"Direct {function_name} declarations are not supported. "
+                                "Use module.Corpus { ... } instead."
+                            ),
+                            declaration=function_name,
+                        )
+                        return
 
                 if function_name == "Agent" and not is_chained_method_call:
                     # Extract config from Agent {...}
@@ -194,6 +262,37 @@ class TactusDSLVisitor(LuaParserVisitor):
                         assignment_target_name,
                         declaration_config if declaration_config else {},
                     )
+                elif function_name == "Context":
+                    declaration_config = self._extract_single_table_arg(function_call)
+                    self.builder.register_context(
+                        assignment_target_name,
+                        declaration_config if declaration_config else {},
+                    )
+                elif function_name == "Corpus":
+                    declaration_config = self._extract_single_table_arg(function_call)
+                    self.builder.register_corpus(
+                        assignment_target_name,
+                        declaration_config if declaration_config else {},
+                    )
+                elif function_name == "Retriever":
+                    declaration_config = self._extract_single_table_arg(function_call)
+                    retriever_id = self._resolve_retriever_id_from_call(function_call)
+                    if (
+                        isinstance(declaration_config, dict)
+                        and retriever_id
+                        and "retriever_id" not in declaration_config
+                    ):
+                        declaration_config["retriever_id"] = retriever_id
+                    self.builder.register_retriever(
+                        assignment_target_name,
+                        declaration_config if declaration_config else {},
+                    )
+                elif function_name == "Compactor":
+                    declaration_config = self._extract_single_table_arg(function_call)
+                    self.builder.register_compactor(
+                        assignment_target_name,
+                        declaration_config if declaration_config else {},
+                    )
                 elif function_name == "Procedure":
                     # New assignment syntax: main = Procedure { function(input) ... }
                     # Register as a named procedure
@@ -204,10 +303,29 @@ class TactusDSLVisitor(LuaParserVisitor):
                         {},  # Output schema will be extracted from top-level output {}
                         {},  # State schema
                     )
+                elif function_name == "Task":
+                    # Assignment-based task declaration: name = Task { ... }
+                    self._processed_task_calls.add(id(function_call))
+                    self._register_task_declaration(assignment_target_name, function_call)
+                else:
+                    # Heuristic: treat any assignment-based call with a 'corpus' field as a retriever.
+                    declaration_config = self._extract_single_table_arg(function_call)
+                    if isinstance(declaration_config, dict) and "corpus" in declaration_config:
+                        retriever_id = self._resolve_retriever_id_from_call(function_call)
+                        if retriever_id and "retriever_id" not in declaration_config:
+                            declaration_config["retriever_id"] = retriever_id
+                        self.builder.register_retriever(
+                            assignment_target_name,
+                            declaration_config,
+                        )
 
     def _extract_single_table_arg(self, function_call) -> dict:
         """Extract a single table argument from a function call like Agent {...}."""
-        argument_list_nodes = function_call.args()
+        args_method = getattr(function_call, "args", None)
+        if args_method is None:
+            return {}
+
+        argument_list_nodes = args_method()
         if not argument_list_nodes:
             return {}
 
@@ -239,6 +357,14 @@ class TactusDSLVisitor(LuaParserVisitor):
             if function_name in self.DSL_FUNCTIONS and not is_method_access_call:
                 # Process the DSL call (but skip method calls like Tool.called())
                 try:
+                    if function_name == "Task":
+                        if id(context) in self._processed_task_calls:
+                            return None
+                        self._register_task_declaration(None, context)
+                        return None
+                    if function_name == "IncludeTasks":
+                        self._register_include_tasks(context)
+                        return None
                     self._process_dsl_call(function_name, context)
                 except Exception as processing_exception:
                     self.errors.append(
@@ -254,6 +380,122 @@ class TactusDSLVisitor(LuaParserVisitor):
 
         return self.visitChildren(context)
 
+    def _register_task_declaration(
+        self,
+        assignment_name: Optional[str],
+        function_call_context: LuaParser.FunctioncallContext,
+        parent_task: Optional[str] = None,
+    ) -> None:
+        args = self._extract_arguments(function_call_context)
+        task_name = None
+        task_config: dict[str, Any] = {}
+
+        if args:
+            if isinstance(args[0], str):
+                task_name = args[0]
+            elif isinstance(args[0], dict):
+                task_config = args[0]
+
+        if len(args) >= 2 and isinstance(args[1], dict):
+            task_config = args[1]
+
+        if assignment_name and task_name and assignment_name != task_name:
+            self._record_error(
+                message=(
+                    f"Task name mismatch: '{assignment_name} = Task \"{task_name}\" {{ ... }}'. "
+                    f"Remove the string name or set it to '{assignment_name}'."
+                ),
+                declaration="Task",
+            )
+            task_name = assignment_name
+
+        if assignment_name and not task_name:
+            task_name = assignment_name
+
+        if not task_name:
+            self._record_error("Task name is required.", declaration="Task")
+            return
+
+        children = self._extract_nested_tasks(function_call_context)
+        for child in children:
+            child_name = child["name"]
+            self.builder.register_task(child_name, child.get("config", {}), parent=task_name)
+
+        self.builder.register_task(task_name, task_config, parent=parent_task)
+
+    def _extract_nested_tasks(
+        self, function_call_context: LuaParser.FunctioncallContext
+    ) -> list[dict[str, Any]]:
+        """Extract nested Task calls from a Task { ... } table constructor."""
+        nested_tasks: list[dict[str, Any]] = []
+        argument_list_nodes = function_call_context.args()
+        if not argument_list_nodes:
+            return nested_tasks
+
+        for args_ctx in argument_list_nodes:
+            table_ctx = args_ctx.tableconstructor()
+            if not table_ctx or not table_ctx.fieldlist():
+                continue
+            for field in table_ctx.fieldlist().field():
+                if len(field.exp()) != 1:
+                    continue
+                child_exp = field.exp(0)
+                child_call = None
+                if hasattr(child_exp, "functioncall") and child_exp.functioncall():
+                    child_call = child_exp.functioncall()
+                elif child_exp.prefixexp() and child_exp.prefixexp().functioncall():
+                    child_call = child_exp.prefixexp().functioncall()
+                if not child_call:
+                    continue
+                child_name = self._extract_function_name(child_call)
+                if child_name != "Task":
+                    continue
+                child_args = self._extract_arguments(child_call)
+                child_task_name = None
+                if field.NAME():
+                    child_task_name = field.NAME().getText()
+                if not child_task_name and child_args:
+                    child_task_name = child_args[0] if isinstance(child_args[0], str) else None
+                child_task_config = {}
+                if len(child_args) >= 2 and isinstance(child_args[1], dict):
+                    child_task_config = child_args[1]
+                if field.NAME() and child_args and isinstance(child_args[0], str):
+                    if field.NAME().getText() != child_args[0]:
+                        self._record_error(
+                            message=(
+                                f"Task name mismatch: '{field.NAME().getText()} = Task \"{child_args[0]}\" {{ ... }}'. "
+                                f"Remove the string name or set it to '{field.NAME().getText()}'."
+                            ),
+                            declaration="Task",
+                        )
+                if child_task_name:
+                    nested_tasks.append(
+                        {
+                            "name": child_task_name,
+                            "config": child_task_config,
+                        }
+                    )
+        return nested_tasks
+
+    def _register_include_tasks(self, context: LuaParser.FunctioncallContext) -> None:
+        args = self._extract_arguments(context)
+        if not args:
+            self._record_error("IncludeTasks requires a path string.", declaration="IncludeTasks")
+            return
+        if not isinstance(args[0], str):
+            self._record_error(
+                "IncludeTasks path must be a string literal.",
+                declaration="IncludeTasks",
+            )
+            return
+        namespace = None
+        if len(args) >= 2:
+            if isinstance(args[1], str):
+                namespace = args[1]
+            elif isinstance(args[1], dict):
+                namespace = args[1].get("namespace")
+        self.builder.register_include_tasks(args[0], namespace)
+
     def _check_deprecated_method_calls(self, ctx: LuaParser.FunctioncallContext):
         """Check for deprecated method calls like .turn() or .run()."""
         # Method calls have the form: varOrExp nameAndArgs+
@@ -373,6 +615,112 @@ class TactusDSLVisitor(LuaParserVisitor):
 
         return None
 
+    def _extract_dotted_dsl_name(
+        self, function_call_context: LuaParser.FunctioncallContext
+    ) -> Optional[str]:
+        """Extract DSL names from dotted calls like module.Corpus {...}."""
+        get_text = getattr(function_call_context, "getText", None)
+        if not callable(get_text):
+            return None
+        function_call_text = get_text()
+        match = re.match(
+            r"(?:[A-Za-z_][A-Za-z0-9_]*\.)+(Agent|Tool|Toolset|Context|Corpus|Retriever|Compactor)\b",
+            function_call_text,
+        )
+        if match:
+            return match.group(1)
+        return None
+
+    def _track_retriever_alias(self, assignment_name: str, expression_list) -> None:
+        """Track retriever constructor aliases from require(...) assignments."""
+        try:
+            expressions = expression_list.exp()
+        except Exception:
+            return
+        if not expressions:
+            return
+        expression_node = expressions[0]
+        get_text = getattr(expression_node, "getText", None)
+        if not callable(get_text):
+            return
+        expression_text = get_text()
+        match = re.match(
+            r'require\("tactus\.retrievers\.([A-Za-z0-9_]+)"\)(?:\.Retriever)?$',
+            expression_text,
+        )
+        if not match:
+            return
+        module_name = match.group(1)
+        retriever_id = module_name.replace("_", "-")
+        if expression_text.endswith(".Retriever"):
+            self._retriever_aliases[assignment_name] = retriever_id
+        else:
+            self._retriever_modules[assignment_name] = retriever_id
+
+    def _resolve_retriever_id_from_call(
+        self, function_call_context: LuaParser.FunctioncallContext
+    ) -> Optional[str]:
+        function_name = self._extract_function_name(function_call_context)
+        if function_name and function_name in self._retriever_aliases:
+            return self._retriever_aliases[function_name]
+        call_text = function_call_context.getText()
+        dotted_match = re.match(r"([A-Za-z_][A-Za-z0-9_]*)\.Retriever\b", call_text)
+        if dotted_match:
+            module_name = dotted_match.group(1)
+            return self._retriever_modules.get(module_name)
+        return None
+
+    def _parse_functioncall_expression(
+        self, function_call_context: LuaParser.FunctioncallContext
+    ) -> Any:
+        """Parse function calls used inside DSL expressions (e.g., context messages)."""
+        function_name = self._extract_function_name(function_call_context)
+        if not function_name:
+            return None
+
+        args = self._extract_arguments(function_call_context)
+
+        if function_name == "template":
+            template_text = args[0] if args else ""
+            vars_dict = args[1] if len(args) > 1 else {}
+            if not isinstance(template_text, str):
+                return None
+            if not isinstance(vars_dict, dict):
+                vars_dict = {}
+            return {"template": template_text, "vars": vars_dict}
+
+        if function_name in {"system", "user", "assistant"}:
+            if not args:
+                return None
+            arg = args[0]
+            if isinstance(arg, dict) and "template" in arg:
+                return {
+                    "type": function_name,
+                    "template": arg.get("template"),
+                    "vars": arg.get("vars", {}),
+                }
+            if isinstance(arg, str):
+                return {"type": function_name, "content": arg}
+            return {"type": function_name, "content": str(arg)}
+
+        if function_name == "context":
+            if not args:
+                return None
+            pack_name = args[0]
+            budget = args[1] if len(args) > 1 else None
+            directive: dict[str, Any] = {
+                "type": "context",
+                "name": pack_name if isinstance(pack_name, str) else str(pack_name),
+            }
+            if isinstance(budget, dict):
+                directive["budget"] = budget
+            return directive
+
+        if function_name == "history":
+            return {"type": "history"}
+
+        return None
+
     def _process_dsl_call(self, function_name: str, ctx: LuaParser.FunctioncallContext):
         """Extract arguments and register declaration."""
         argument_values = self._extract_arguments(ctx)
@@ -742,6 +1090,9 @@ class TactusDSLVisitor(LuaParserVisitor):
             return True
         elif ctx.tableconstructor():
             return self._parse_table_constructor(ctx.tableconstructor())
+        function_call = getattr(ctx, "functioncall", None)
+        if callable(function_call):
+            return self._parse_functioncall_expression(function_call())
 
         # For other expressions, return None (can't evaluate without execution)
         return None

tactus/validation/validator.py

@@ -9,6 +9,7 @@ Validates .tac files using ANTLR parser:
 
 import logging
 from enum import Enum
+from pathlib import Path
 from typing import Optional
 
 from antlr4 import InputStream, CommonTokenStream
@@ -16,7 +17,7 @@ from .generated.LuaLexer import LuaLexer
 from .generated.LuaParser import LuaParser
 from .semantic_visitor import TactusDSLVisitor
 from .error_listener import TactusErrorListener
-from tactus.core.registry import ValidationResult, ValidationMessage
+from tactus.core.registry import ValidationResult, ValidationMessage, TaskDeclaration
 
 logger = logging.getLogger(__name__)
 
@@ -175,7 +176,101 @@ class TactusValidator:
         try:
             with open(file_path, "r") as source_file_handle:
                 source_text = source_file_handle.read()
-            return self.validate(source_text, mode)
+            primary_result = self.validate(source_text, mode)
+            if not primary_result.valid or mode == ValidationMode.QUICK:
+                return primary_result
+            registry = primary_result.registry
+            if not registry or not registry.include_tasks:
+                return primary_result
+
+            base_path = Path(file_path).parent
+            merged_registry = registry
+            include_queue = [
+                {
+                    "path": include.get("path"),
+                    "namespace": include.get("namespace"),
+                    "base": base_path,
+                }
+                for include in registry.include_tasks
+            ]
+            seen_includes: set[Path] = set()
+
+            while include_queue:
+                include = include_queue.pop(0)
+                include_path = include.get("path")
+                if not include_path:
+                    continue
+                include_base = include.get("base") or base_path
+                include_file = (include_base / include_path).resolve()
+                if include_file in seen_includes:
+                    return self._result_with_errors(
+                        errors=[
+                            ValidationMessage(
+                                level="error",
+                                message=f"IncludeTasks cycle detected: {include_file}",
+                            )
+                        ]
+                    )
+                seen_includes.add(include_file)
+                if not include_file.exists():
+                    return self._result_with_errors(
+                        errors=[
+                            ValidationMessage(
+                                level="error",
+                                message=f"Included tasks file not found: {include_file}",
+                            )
+                        ]
+                    )
+                with open(include_file, "r") as include_handle:
+                    include_source = include_handle.read()
+                include_result = self.validate(include_source, mode)
+                if not include_result.valid or not include_result.registry:
+                    return include_result
+                if self._include_has_non_task_declarations(include_result.registry):
+                    return self._result_with_errors(
+                        errors=[
+                            ValidationMessage(
+                                level="error",
+                                message=(
+                                    "IncludeTasks files must only contain Task declarations: "
+                                    f"{include_file}"
+                                ),
+                            )
+                        ]
+                    )
+                try:
+                    self._merge_tasks(
+                        merged_registry,
+                        include_result.registry,
+                        namespace=include.get("namespace"),
+                    )
+                except ValueError as merge_error:
+                    return self._result_with_errors(
+                        errors=[
+                            ValidationMessage(
+                                level="error",
+                                message=str(merge_error),
+                            )
+                        ]
+                    )
+
+                if include_result.registry.include_tasks:
+                    include_queue.extend(
+                        [
+                            {
+                                "path": nested.get("path"),
+                                "namespace": nested.get("namespace"),
+                                "base": include_file.parent,
+                            }
+                            for nested in include_result.registry.include_tasks
+                        ]
+                    )
+
+            return self._result_success(
+                errors=primary_result.errors,
+                warnings=primary_result.warnings,
+                registry=merged_registry,
+            )
         except FileNotFoundError:
             return self._result_with_errors(
                 errors=[
@@ -194,3 +289,48 @@ class TactusValidator:
                     )
                 ]
             )
+
+    def _include_has_non_task_declarations(self, registry) -> bool:
+        if registry is None:
+            return False
+        return any(
+            [
+                registry.agents,
+                registry.toolsets,
+                registry.lua_tools,
+                registry.contexts,
+                registry.corpora,
+                registry.retrievers,
+                registry.compactors,
+                registry.named_procedures,
+                registry.specifications,
+                registry.dependencies,
+                registry.models,
+                registry.hitl_points,
+                registry.mocks,
+                registry.agent_mocks,
+                registry.prompts,
+            ]
+        )
+
+    def _merge_tasks(
+        self,
+        target_registry,
+        include_registry,
+        namespace: Optional[str] = None,
+    ) -> None:
+        if not include_registry.tasks:
+            return
+        if namespace:
+            if namespace in target_registry.tasks:
+                raise ValueError(f"Duplicate task namespace '{namespace}'")
+            target_registry.tasks[namespace] = TaskDeclaration(
+                name=namespace,
+                children=include_registry.tasks,
+            )
+            return
+
+        for task_name, task in include_registry.tasks.items():
+            if task_name in target_registry.tasks:
+                raise ValueError(f"Duplicate task '{task_name}'")
+            target_registry.tasks[task_name] = task

{tactus-0.36.0.dist-info → tactus-0.38.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tactus
-Version: 0.36.0
+Version: 0.38.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
@@ -14,15 +14,18 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: >=3.9
 Requires-Dist: antlr4-python3-runtime==4.13.1
 Requires-Dist: behave>=1.2.6
+Requires-Dist: biblicus>=1.0.0
 Requires-Dist: boto3>=1.28.0
-Requires-Dist: dotyaml>=0.1.0
+Requires-Dist: dotyaml>=0.1.4
 Requires-Dist: dspy>=2.5
 Requires-Dist: flask-cors>=4.0.0
 Requires-Dist: flask>=3.0.0
@@ -39,7 +42,7 @@ Requires-Dist: openpyxl>=3.1
 Requires-Dist: opentelemetry-api>=1.39.1
 Requires-Dist: opentelemetry-sdk>=1.39.1
 Requires-Dist: pyarrow>=14.0
-Requires-Dist: pydantic-ai-slim[bedrock,evals]
+Requires-Dist: pydantic-ai
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml
 Requires-Dist: rapidfuzz>=3.0.0
@@ -48,9 +51,9 @@ Requires-Dist: typer
 Provides-Extra: dev
 Requires-Dist: antlr4-tools>=0.2.1; extra == 'dev'
 Requires-Dist: behave>=1.2.6; extra == 'dev'
-Requires-Dist: black==25.12.0; extra == 'dev'
+Requires-Dist: black==24.10.0; extra == 'dev'
 Requires-Dist: coverage>=7.4; extra == 'dev'
-Requires-Dist: fastmcp>=2.3.5; extra == 'dev'
+Requires-Dist: fastmcp>=2.3.5; (python_version >= '3.10') and extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'