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

tactus/__init__.py

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

tactus/adapters/channels/base.py

@@ -9,7 +9,7 @@ requiring separate processes (e.g., Discord WebSocket gateway).
 import asyncio
 import logging
 from abc import ABC, abstractmethod
-from typing import AsyncIterator
+from typing import AsyncIterator, Optional
 
 from tactus.protocols.control import (
     ControlRequest,
@@ -54,7 +54,20 @@ class InProcessChannel(ABC):
 
     def __init__(self):
         """Initialize the channel with an internal response queue."""
-        self._response_queue: asyncio.Queue[ControlResponse] = asyncio.Queue()
+        self._response_queue: Optional[asyncio.Queue[ControlResponse]] = None
+        self._shutdown_event: Optional[asyncio.Event] = None
+
+    def _ensure_asyncio_primitives(self) -> None:
+        if self._response_queue is not None and self._shutdown_event is not None:
+            return
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError as error:
+            raise RuntimeError(
+                "InProcessChannel requires a running event loop before use. "
+                "Initialize it from within an async context."
+            ) from error
+        self._response_queue = asyncio.Queue()
         self._shutdown_event = asyncio.Event()
 
     @property
@@ -105,6 +118,7 @@ class InProcessChannel(ABC):
         Yields:
             ControlResponse as they are received
         """
+        self._ensure_asyncio_primitives()
         while not self._shutdown_event.is_set():
             try:
                 # Use wait_for with timeout to check shutdown periodically
@@ -149,6 +163,7 @@ class InProcessChannel(ABC):
         Override for additional cleanup (close connections, etc.).
         """
         logger.info("%s: shutting down", self.channel_id)
+        self._ensure_asyncio_primitives()
         self._shutdown_event.set()
 
     def push_response(self, response: ControlResponse) -> None:
@@ -164,6 +179,7 @@ class InProcessChannel(ABC):
             response: ControlResponse to add to queue
         """
         try:
+            self._ensure_asyncio_primitives()
             self._response_queue.put_nowait(response)
         except Exception as error:
             logger.error("%s: failed to queue response: %s", self.channel_id, error)
@@ -180,4 +196,6 @@ class InProcessChannel(ABC):
             response: ControlResponse to add to queue
             loop: The event loop to use for thread-safe call
         """
+        if self._response_queue is None:
+            loop.call_soon_threadsafe(self._ensure_asyncio_primitives)
         loop.call_soon_threadsafe(self._response_queue.put_nowait, response)

tactus/adapters/channels/broker.py

@@ -91,6 +91,7 @@ class BrokerControlChannel(InProcessChannel):
         )
 
         try:
+            self._ensure_asyncio_primitives()
             # Serialize request to JSON-compatible dict
             request_data = request.model_dump(mode="json")
 

tactus/adapters/channels/host.py

@@ -90,12 +90,14 @@ class HostControlChannel(InProcessChannel):
             request.request_id,
         )
 
+        self._ensure_asyncio_primitives()
+
         # Store for background thread access
         self._current_request = request
         self._cancel_event.clear()
 
         # Capture event loop for thread-safe response pushing
-        self._event_loop = asyncio.get_event_loop()
+        self._event_loop = asyncio.get_running_loop()
 
         # Display the request (synchronous, before starting thread)
         self._display_request(request)

tactus/adapters/channels/ipc.py

@@ -46,10 +46,22 @@ class IPCControlChannel:
 
         self._server: Optional[asyncio.Server] = None
         self._clients: dict[str, asyncio.StreamWriter] = {}  # client_id -> writer
-        self._response_queue: asyncio.Queue[ControlResponse] = asyncio.Queue()
+        self._response_queue: Optional[asyncio.Queue[ControlResponse]] = None
         self._pending_requests: dict[str, ControlRequest] = {}  # request_id -> request
         self._initialized = False
 
+    def _ensure_response_queue(self) -> asyncio.Queue[ControlResponse]:
+        if self._response_queue is None:
+            try:
+                asyncio.get_running_loop()
+            except RuntimeError as error:
+                raise RuntimeError(
+                    "IPCControlChannel requires a running event loop before use. "
+                    "Initialize it from within an async context."
+                ) from error
+            self._response_queue = asyncio.Queue()
+        return self._response_queue
+
     @property
     def capabilities(self) -> ChannelCapabilities:
         """IPC supports all request types and can respond synchronously."""
@@ -68,6 +80,7 @@ class IPCControlChannel:
             return
 
         logger.info("%s: initializing...", self.channel_id)
+        self._ensure_response_queue()
 
         # Remove old socket file if it exists
         if os.path.exists(self.socket_path):
@@ -168,8 +181,9 @@ class IPCControlChannel:
         Yields:
             ControlResponse objects
         """
+        response_queue = self._ensure_response_queue()
         while True:
-            response = await self._response_queue.get()
+            response = await response_queue.get()
             logger.info(
                 "%s: received response for %s",
                 self.channel_id,
@@ -264,6 +278,7 @@ class IPCControlChannel:
         self._clients[client_id] = writer
 
         try:
+            response_queue = self._ensure_response_queue()
             # Send any pending requests to the new client
             for request_id, request_data in self._pending_requests.items():
                 try:
@@ -302,7 +317,7 @@ class IPCControlChannel:
                         timed_out=message.get("timed_out", False),
                         channel_id=self.channel_id,
                     )
-                    await self._response_queue.put(response)
+                    await response_queue.put(response)
                     logger.info(
                         "%s: received response for %s",
                         self.channel_id,

tactus/adapters/channels/sse.py

@@ -267,6 +267,7 @@ class SSEControlChannel(InProcessChannel):
         self, request_id: str, response: ControlResponse
     ) -> None:
         try:
+            self._ensure_asyncio_primitives()
             event_loop = asyncio.get_event_loop()
             if event_loop.is_running():
                 asyncio.run_coroutine_threadsafe(self._response_queue.put(response), event_loop)
@@ -326,4 +327,5 @@ class SSEControlChannel(InProcessChannel):
     async def shutdown(self) -> None:
         """Shutdown SSE channel."""
         logger.info("%s: shutting down", self.channel_id)
+        self._ensure_asyncio_primitives()
         self._shutdown_event.set()

tactus/adapters/mcp_manager.py

@@ -5,18 +5,32 @@ Manages multiple MCP server connections using Pydantic AI's native MCPServerStdi
 Handles lifecycle, tool prefixing, and tool call tracking.
 """
 
+from __future__ import annotations
+
 import logging
 import os
 import re
 import asyncio
 from contextlib import AsyncExitStack
-from typing import Any
-
-from pydantic_ai.mcp import MCPServerStdio
+from typing import Any, Optional
 
 logger = logging.getLogger(__name__)
 
 
+MCPServerStdio: Optional[Any] = None
+
+
+def _require_mcp_server_stdio():
+    try:
+        from pydantic_ai.mcp import MCPServerStdio
+    except ImportError as import_error:
+        raise RuntimeError(
+            "MCP support requires optional dependencies. "
+            'Install with `pip install "pydantic-ai-slim[mcp]"`.'
+        ) from import_error
+    return MCPServerStdio
+
+
 def substitute_env_vars(value: Any) -> Any:
     """
     Replace ${VAR} with environment variable values.
@@ -55,8 +69,8 @@ class MCPServerManager:
         """
         self.configs = server_configs
         self.tool_primitive = tool_primitive
-        self.servers: list[MCPServerStdio] = []
-        self.server_toolsets: dict[str, MCPServerStdio] = {}  # Map server names to toolsets
+        self.servers: list[Any] = []
+        self.server_toolsets: dict[str, Any] = {}  # Map server names to toolsets
         self._exit_stack = AsyncExitStack()
         logger.info("MCPServerManager initialized with %s server(s)", len(server_configs))
 
@@ -64,7 +78,7 @@ class MCPServerManager:
         """Connect to all configured MCP servers."""
         for name, config in self.configs.items():
             # Retry a few times for transient stdio startup issues.
-            last_error: Exception | None = None
+            last_error: Optional[Exception] = None
             for attempt in range(1, 4):
                 try:
                     logger.info(
@@ -77,6 +91,9 @@ class MCPServerManager:
                     resolved_config = substitute_env_vars(config)
 
                     # Create base server
+                    MCPServerStdio = globals().get("MCPServerStdio")
+                    if MCPServerStdio is None:
+                        MCPServerStdio = _require_mcp_server_stdio()
                     server = MCPServerStdio(
                         command=resolved_config["command"],
                         args=resolved_config.get("args", []),
@@ -190,7 +207,7 @@ class MCPServerManager:
 
         return trace_tool_call
 
-    def get_toolsets(self) -> list[MCPServerStdio]:
+    def get_toolsets(self) -> list[Any]:
         """
         Return list of connected servers as toolsets.
 

tactus/backends/http_backend.py

@@ -3,7 +3,7 @@ HTTP model backend for REST endpoint inference.
 """
 
 import logging
-from typing import Any
+from typing import Any, Dict, Optional
 
 import httpx
 
@@ -13,7 +13,7 @@ logger = logging.getLogger(__name__)
 class HTTPModelBackend:
     """Model backend that calls HTTP REST endpoints."""
 
-    def __init__(self, endpoint: str, timeout: float = 30.0, headers: dict | None = None):
+    def __init__(self, endpoint: str, timeout: float = 30.0, headers: Optional[Dict] = None):
         """
         Initialize HTTP model backend.
 

tactus/backends/pytorch_backend.py

@@ -4,7 +4,7 @@ PyTorch model backend for .pt file inference.
 
 import logging
 from pathlib import Path
-from typing import Any
+from typing import Any, List, Optional
 
 logger = logging.getLogger(__name__)
 
@@ -12,7 +12,7 @@ logger = logging.getLogger(__name__)
 class PyTorchModelBackend:
     """Model backend that loads and runs PyTorch models."""
 
-    def __init__(self, path: str, device: str = "cpu", labels: list[str] | None = None):
+    def __init__(self, path: str, device: str = "cpu", labels: Optional[List[str]] = None):
         """
         Initialize PyTorch model backend.
 

tactus/broker/client.py

@@ -16,7 +16,7 @@ import sys
 import threading
 import uuid
 from pathlib import Path
-from typing import Any, AsyncIterator, Optional
+from typing import Any, AsyncIterator, Optional, Union
 
 from tactus.broker.protocol import read_message, write_message
 from tactus.broker.stdio import STDIO_REQUEST_PREFIX, STDIO_TRANSPORT_VALUE
@@ -122,7 +122,7 @@ async def close_stdio_transport() -> None:
 
 
 class BrokerClient:
-    def __init__(self, socket_path: str | Path):
+    def __init__(self, socket_path: Union[str, Path]):
         self.socket_path = str(socket_path)
 
     @classmethod
@@ -158,7 +158,7 @@ class BrokerClient:
             except ValueError as error:
                 raise ValueError(f"Invalid broker port in endpoint: {self.socket_path}") from error
 
-            ssl_context: ssl.SSLContext | None = None
+            ssl_context: Optional[ssl.SSLContext] = None
             if use_tls:
                 ssl_context = ssl.create_default_context()
                 cafile = os.environ.get("TACTUS_BROKER_TLS_CA_FILE")

tactus/broker/server.py

@@ -29,6 +29,18 @@ from tactus.broker.protocol import (
 logger = logging.getLogger(__name__)
 
 
+try:
+    from builtins import BaseExceptionGroup as BaseExceptionGroup
+except ImportError:  # pragma: no cover - Python < 3.11 fallback
+
+    class BaseExceptionGroup(Exception):
+        """Minimal BaseExceptionGroup fallback for Python < 3.11."""
+
+        def __init__(self, message: str, exceptions: list[BaseException]):
+            super().__init__(message)
+            self.exceptions = exceptions
+
+
 def _json_dumps(obj: Any) -> str:
     return json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
 
@@ -170,7 +182,7 @@ class _BaseBrokerServer:
         control_handler: Optional[Callable[[dict], Awaitable[dict]]] = None,
     ):
         self._listener = None
-        self._serve_task: asyncio.Task[None] | None = None
+        self._serve_task: Optional[asyncio.Task[None]] = None
         self._openai = openai_backend or OpenAIChatBackend()
         self._tools = tool_registry or HostToolRegistry.default()
         self._event_handler = event_handler
@@ -1012,7 +1024,7 @@ class BrokerServer(_BaseBrokerServer):
             openai_backend=openai_backend, tool_registry=tool_registry, event_handler=event_handler
         )
         self.socket_path = Path(socket_path)
-        self._server: asyncio.AbstractServer | None = None
+        self._server: Optional[asyncio.AbstractServer] = None
 
     async def start(self) -> None:
         # Most platforms enforce a short maximum length for AF_UNIX socket paths.
@@ -1445,7 +1457,7 @@ class TcpBrokerServer(_BaseBrokerServer):
         *,
         host: str = "127.0.0.1",
         port: int = 0,
-        ssl_context: ssl.SSLContext | None = None,
+        ssl_context: Optional[ssl.SSLContext] = None,
         openai_backend: Optional[OpenAIChatBackend] = None,
         tool_registry: Optional[HostToolRegistry] = None,
         event_handler: Optional[Callable[[dict[str, Any]], None]] = None,
@@ -1460,8 +1472,8 @@ class TcpBrokerServer(_BaseBrokerServer):
         self.host = host
         self.port = port
         self.ssl_context = ssl_context
-        self.bound_port: int | None = None
-        self._serve_task: asyncio.Task[None] | None = None
+        self.bound_port: Optional[int] = None
+        self._serve_task: Optional[asyncio.Task[None]] = None
 
     async def start(self) -> None:
         # Create AnyIO TCP listener (doesn't block, just binds to port)

tactus/core/dsl_stubs.py

@@ -31,7 +31,7 @@ Agent/Tool calls use direct variable access:
     done.last_result()              -- Get last tool result
 """
 
-from typing import Any, Callable
+from typing import Any, Callable, Dict, Optional
 
 from .registry import RegistryBuilder
 from tactus.primitives.handles import AgentHandle, ModelHandle, AgentLookup, ModelLookup
@@ -112,7 +112,7 @@ def create_dsl_stubs(
     builder: RegistryBuilder,
     tool_primitive: Any = None,
     mock_manager: Any = None,
-    runtime_context: dict[str, Any] | None = None,
+    runtime_context: Optional[Dict[str, Any]] = None,
 ) -> dict[str, Callable]:
     """
     Create DSL stub functions that populate the registry.
@@ -144,7 +144,7 @@ def create_dsl_stubs(
     _procedure_registry = {}
 
     def _process_procedure_config(
-        name: str | None, config: Any, procedure_registry: dict[str, Any]
+        name: Optional[str], config: Any, procedure_registry: Dict[str, Any]
     ):
         """
         Process procedure config and register the procedure.

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.
@@ -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/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):