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

tactus/core/exceptions.py

@@ -11,6 +11,14 @@ class TactusRuntimeError(Exception):
     pass
 
 
+class TaskSelectionRequired(TactusRuntimeError):
+    """Raised when multiple tasks are available and no default can be chosen."""
+
+    def __init__(self, tasks: list[str]):
+        self.tasks = tasks
+        super().__init__("Multiple tasks available; select one explicitly.")
+
+
 class ProcedureWaitingForHuman(Exception):
     """
     Raised to exit workflow when waiting for human response.

tactus/core/execution_context.py

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

tactus/core/message_history_manager.py

@@ -8,7 +8,7 @@ Aligned with pydantic-ai's message_history concept.
 """
 
 from datetime import datetime, timezone
-from typing import Any, Optional
+from typing import Any, Optional, Tuple
 
 try:
     from pydantic_ai.messages import ModelMessage
@@ -146,7 +146,7 @@ class MessageHistoryManager:
         return self._apply_named_filter(messages, filter_name, filter_value)
 
     @staticmethod
-    def _parse_filter_spec(filter_specification: Any) -> tuple[str | None, Any]:
+    def _parse_filter_spec(filter_specification: Any) -> Tuple[Optional[str], Any]:
         if not isinstance(filter_specification, tuple) or len(filter_specification) < 2:
             return None, None
 

tactus/core/mocking.py

@@ -13,6 +13,18 @@ import logging
 from typing import Any, Optional, Union
 
 logger = logging.getLogger(__name__)
+_CURRENT_MOCK_MANAGER: Optional["MockManager"] = None
+
+
+def set_current_mock_manager(manager: Optional["MockManager"]) -> None:
+    """Set the globally accessible mock manager for stdlib helpers."""
+    global _CURRENT_MOCK_MANAGER
+    _CURRENT_MOCK_MANAGER = manager
+
+
+def get_current_mock_manager() -> Optional["MockManager"]:
+    """Get the globally accessible mock manager for stdlib helpers."""
+    return _CURRENT_MOCK_MANAGER
 
 
 @dataclass

tactus/core/output_validator.py

@@ -6,7 +6,7 @@ Enables type safety and composability for sub-agent workflows.
 """
 
 import logging
-from typing import Any, Optional
+from typing import Any, Optional, Tuple
 
 logger = logging.getLogger(__name__)
 
@@ -78,7 +78,7 @@ class OutputValidator:
             logger.debug("OutputValidator initialized with %s output fields", field_count)
 
     @staticmethod
-    def _unwrap_result(output: Any) -> tuple[Any, Any | None]:
+    def _unwrap_result(output: Any) -> Tuple[Any, Optional[Any]]:
         from tactus.protocols.result import TactusResult
 
         wrapped_result = output if isinstance(output, TactusResult) else None
@@ -94,7 +94,7 @@ class OutputValidator:
 
     @staticmethod
     def _wrap_validated_output(
-        wrapped_result: Any | None,
+        wrapped_result: Optional[Any],
         validated_payload: Any,
     ) -> Any:
         if wrapped_result is not None:
@@ -129,7 +129,7 @@ class OutputValidator:
     def _validate_without_schema(
         self,
         output: Any,
-        wrapped_result: Any | None,
+        wrapped_result: Optional[Any],
     ) -> Any:
         """Accept any output when no schema is defined."""
         logger.debug("No output schema defined, skipping validation")
@@ -139,7 +139,7 @@ class OutputValidator:
     def _validate_scalar_schema(
         self,
         output: Any,
-        wrapped_result: Any | None,
+        wrapped_result: Optional[Any],
     ) -> Any:
         """Validate scalar outputs (`field.string{}` etc.)."""
         # Lua tables are not valid scalar outputs.
@@ -168,7 +168,7 @@ class OutputValidator:
     def _validate_structured_schema(
         self,
         output: Any,
-        wrapped_result: Any | None,
+        wrapped_result: Optional[Any],
     ) -> Any:
         """Validate dict/table outputs against a schema."""
         if hasattr(output, "items") or isinstance(output, dict):

tactus/core/registry.py

@@ -6,10 +6,17 @@ procedure declarations from .tac files.
 """
 
 import logging
-from typing import Any
+from typing import Any, Dict, Optional, Union
 
 from pydantic import BaseModel, Field, ValidationError, ConfigDict
 
+from tactus.core.context_models import (
+    CompactorDeclaration,
+    ContextDeclaration,
+    CorpusDeclaration,
+    RetrieverDeclaration,
+)
+
 logger = logging.getLogger(__name__)
 
 
@@ -19,7 +26,7 @@ class OutputFieldDeclaration(BaseModel):
     name: str
     field_type: str = Field(alias="type")  # string, number, boolean, array, object
     required: bool = False
-    description: str | None = None
+    description: Optional[str] = None
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -31,7 +38,7 @@ class MessageHistoryConfiguration(BaseModel):
     """
 
     source: str = "own"  # "own", "shared", or another agent's name
-    filter: Any | None = None  # Lua function reference or filter name
+    filter: Optional[Any] = None  # Lua function reference or filter name
 
 
 class AgentOutputSchema(BaseModel):
@@ -44,21 +51,21 @@ class AgentDeclaration(BaseModel):
     """Agent declaration from DSL."""
 
     name: str
-    provider: str | None = None
-    model: str | dict[str, Any] = "gpt-4o"
-    system_prompt: str | Any  # String with {markers} or Lua function
-    initial_message: str | None = None
+    provider: Optional[str] = None
+    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[Any] = Field(default_factory=list)  # Tool/toolset references and expressions
     inline_tools: list[dict[str, Any]] = Field(default_factory=list)  # Inline tool definitions
-    output: AgentOutputSchema | None = None  # Aligned with pydantic-ai
-    message_history: MessageHistoryConfiguration | None = None
+    output: Optional[AgentOutputSchema] = None  # Aligned with pydantic-ai
+    message_history: Optional[MessageHistoryConfiguration] = None
     max_turns: int = 50
     disable_streaming: bool = (
         False  # Disable streaming for models that don't support tools in streaming mode
     )
-    temperature: float | None = None
-    max_tokens: int | None = None
-    model_type: str | None = None  # e.g., "chat", "responses" for reasoning models
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None
+    model_type: Optional[str] = None  # e.g., "chat", "responses" for reasoning models
 
     model_config = ConfigDict(extra="allow")
 
@@ -69,9 +76,9 @@ class HITLDeclaration(BaseModel):
     name: str
     hitl_type: str = Field(alias="type")  # approval, input, review
     message: str
-    timeout: int | None = None
+    timeout: Optional[int] = None
     default: Any = None
-    options: list[dict[str, Any]] | None = None
+    options: Optional[list[dict[str, Any]]] = None
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -81,9 +88,9 @@ class ScenarioDeclaration(BaseModel):
 
     name: str
     given: dict[str, Any] = Field(default_factory=dict)
-    when: str | None = None  # defaults to "procedure_completes"
-    then_output: dict[str, Any] | None = None
-    then_state: dict[str, Any] | None = None
+    when: Optional[str] = None  # defaults to "procedure_completes"
+    then_output: Optional[Dict[str, Any]] = None
+    then_state: Optional[Dict[str, Any]] = None
     mocks: dict[str, Any] = Field(default_factory=dict)  # tool_name -> response
 
 
@@ -128,13 +135,25 @@ class AgentMockConfig(BaseModel):
     )
 
 
+class TaskDeclaration(BaseModel):
+    """Task declaration from DSL."""
+
+    name: str
+    children: dict[str, "TaskDeclaration"] = Field(default_factory=dict)
+
+    model_config = ConfigDict(extra="allow")
+
+
+TaskDeclaration.model_rebuild()
+
+
 class ProcedureRegistry(BaseModel):
     """Collects all declarations from a .tac file."""
 
     model_config = {"arbitrary_types_allowed": True}
 
     # Metadata
-    description: str | None = None
+    description: Optional[str] = None
 
     # Declarations
     input_schema: dict[str, Any] = Field(default_factory=dict)
@@ -149,31 +168,37 @@ class ProcedureRegistry(BaseModel):
     dependencies: dict[str, DependencyDeclaration] = Field(default_factory=dict)
     mocks: dict[str, dict[str, Any]] = Field(default_factory=dict)  # Mock configurations
     agent_mocks: dict[str, AgentMockConfig] = Field(default_factory=dict)  # Agent mock configs
+    contexts: dict[str, ContextDeclaration] = Field(default_factory=dict)
+    corpora: dict[str, CorpusDeclaration] = Field(default_factory=dict)
+    retrievers: dict[str, RetrieverDeclaration] = Field(default_factory=dict)
+    compactors: dict[str, CompactorDeclaration] = Field(default_factory=dict)
+    tasks: dict[str, TaskDeclaration] = Field(default_factory=dict)
+    include_tasks: list[dict[str, Any]] = Field(default_factory=list)
 
     # Message history configuration (aligned with pydantic-ai)
     message_history_config: dict[str, Any] = Field(default_factory=dict)
 
     # Gherkin BDD Testing
-    gherkin_specifications: str | None = None  # Raw Gherkin text
+    gherkin_specifications: Optional[str] = None  # Raw Gherkin text
     specs_from_references: list[str] = Field(default_factory=list)  # External spec file paths
     custom_steps: dict[str, Any] = Field(default_factory=dict)  # step_text -> lua_function
     evaluation_config: dict[str, Any] = Field(default_factory=dict)  # runs, parallel, etc.
 
     # Pydantic Evals Integration
-    pydantic_evaluations: dict[str, Any] | None = None  # Pydantic Evals configuration
+    pydantic_evaluations: Optional[Dict[str, Any]] = None  # Pydantic Evals configuration
 
     # Prompts
     prompts: dict[str, str] = Field(default_factory=dict)
-    return_prompt: str | None = None
-    error_prompt: str | None = None
-    status_prompt: str | None = None
+    return_prompt: Optional[str] = None
+    error_prompt: Optional[str] = None
+    status_prompt: Optional[str] = None
 
     # Execution settings
     async_enabled: bool = False
     max_depth: int = 5
     max_turns: int = 50
-    default_provider: str | None = None
-    default_model: str | None = None
+    default_provider: Optional[str] = None
+    default_model: Optional[str] = None
 
     # Named procedures (for in-file sub-procedures)
     named_procedures: dict[str, dict[str, Any]] = Field(default_factory=dict)
@@ -193,8 +218,8 @@ class ValidationMessage(BaseModel):
 
     level: str  # "error" or "warning"
     message: str
-    location: tuple[int, int] | None = None
-    declaration: str | None = None
+    location: Optional[tuple[int, int]] = None
+    declaration: Optional[str] = None
 
 
 class ValidationResult(BaseModel):
@@ -203,7 +228,7 @@ class ValidationResult(BaseModel):
     valid: bool
     errors: list[ValidationMessage] = Field(default_factory=list)
     warnings: list[ValidationMessage] = Field(default_factory=list)
-    registry: ProcedureRegistry | None = None
+    registry: Optional["ProcedureRegistry"] = None
 
 
 class RegistryBuilder:
@@ -229,7 +254,7 @@ class RegistryBuilder:
         self,
         name: str,
         config: dict,
-        output_schema: dict | None = None,
+        output_schema: Optional[dict] = None,
     ) -> None:
         """Register an agent declaration."""
         agent_config = dict(config)
@@ -334,6 +359,123 @@ class RegistryBuilder:
         except Exception as exception:
             self._add_error(f"Invalid agent mock config for '{agent_name}': {exception}")
 
+    def register_context(self, name: str, config: dict) -> None:
+        """Register a context declaration."""
+        context_config = dict(config)
+        context_config["name"] = name
+        try:
+            self.registry.contexts[name] = ContextDeclaration(**context_config)
+        except ValidationError as exception:
+            self._add_error(f"Invalid context '{name}': {exception}")
+
+    def register_corpus(self, name: str, config: dict) -> None:
+        """Register a corpus declaration."""
+        corpus_config = dict(config)
+        if "root" in corpus_config and "corpus_root" not in corpus_config:
+            corpus_config["corpus_root"] = corpus_config.pop("root")
+        try:
+            self.registry.corpora[name] = CorpusDeclaration(name=name, config=corpus_config)
+        except ValidationError as exception:
+            self._add_error(f"Invalid corpus '{name}': {exception}")
+
+    def register_retriever(self, name: str, config: dict) -> None:
+        """Register a retriever declaration."""
+        retriever_config = dict(config)
+        if "retriever_id" not in retriever_config:
+            candidate = retriever_config.get("retriever_type")
+            if candidate is not None:
+                retriever_config["retriever_id"] = candidate
+        if isinstance(retriever_config.get("configuration"), dict):
+            pipeline = retriever_config["configuration"].get("pipeline", {}) or {}
+            if isinstance(pipeline, dict) and isinstance(pipeline.get("query"), dict):
+                query_config = pipeline.get("query") or {}
+                for key in (
+                    "limit",
+                    "offset",
+                    "maximum_total_characters",
+                    "maximum_items_per_source",
+                    "max_items_per_source",
+                    "include_metadata",
+                    "metadata_fields",
+                    "join_with",
+                ):
+                    if key in query_config and key not in retriever_config:
+                        retriever_config[key] = query_config.get(key)
+        corpus_name = retriever_config.pop("corpus", None)
+        try:
+            self.registry.retrievers[name] = RetrieverDeclaration(
+                name=name,
+                corpus=corpus_name,
+                config=retriever_config,
+            )
+        except ValidationError as exception:
+            self._add_error(f"Invalid retriever '{name}': {exception}")
+
+    def register_task(
+        self,
+        name: str,
+        task_config: Optional[dict] = None,
+        parent: Optional[str] = None,
+    ) -> None:
+        """Register a task declaration (optionally nested under a parent task)."""
+        if not name:
+            self._add_error("Task name is required.")
+            return
+
+        if ":" in name:
+            self._add_error(f"Task name '{name}' may not contain ':'")
+            return
+
+        task_payload = dict(task_config or {})
+        task_payload["name"] = name
+
+        try:
+            task = TaskDeclaration(**task_payload)
+        except ValidationError as exception:
+            self._add_error(f"Invalid task '{name}': {exception}")
+            return
+
+        if parent is None:
+            if name in self.registry.tasks:
+                self._add_error(f"Duplicate task '{name}'")
+                return
+            self.registry.tasks[name] = task
+            return
+
+        parent_task = self._find_task(parent)
+        if parent_task is None:
+            self._add_error(f"Parent task '{parent}' not found for '{name}'")
+            return
+
+        if name in parent_task.children:
+            self._add_error(f"Duplicate task '{parent}:{name}'")
+            return
+
+        parent_task.children[name] = task
+
+    def register_include_tasks(self, path: str, namespace: Optional[str] = None) -> None:
+        """Register an IncludeTasks directive for static task discovery."""
+        payload = {"path": path}
+        if namespace:
+            payload["namespace"] = namespace
+        self.registry.include_tasks.append(payload)
+
+    def _find_task(self, name: str) -> Optional[TaskDeclaration]:
+        if name in self.registry.tasks:
+            return self.registry.tasks[name]
+        return None
+
+    def register_compactor(self, name: str, config: dict) -> None:
+        """Register a compactor declaration."""
+        compactor_config = dict(config)
+        try:
+            self.registry.compactors[name] = CompactorDeclaration(
+                name=name,
+                config=compactor_config,
+            )
+        except ValidationError as exception:
+            self._add_error(f"Invalid compactor '{name}': {exception}")
+
     def register_specification(self, name: str, scenarios: list) -> None:
         """Register a BDD specification."""
         try: