tactus 0.35.1__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.35.1"
+__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

@@ -248,7 +248,14 @@ class SSEControlChannel(InProcessChannel):
         """
         logger.info("%s: received response for %s", self.channel_id, request_id)
 
-        response = ControlResponse(
+        response = self._build_response(request_id, value)
+
+        # Push to queue from sync context (Flask thread)
+        # Get the running event loop and schedule the put operation
+        self._enqueue_response_from_sync_context(request_id, response)
+
+    def _build_response(self, request_id: str, value: Any) -> ControlResponse:
+        return ControlResponse(
             request_id=request_id,
             value=value,
             responded_at=datetime.now(timezone.utc),
@@ -256,15 +263,15 @@ class SSEControlChannel(InProcessChannel):
             channel_id=self.channel_id,
         )
 
-        # Push to queue from sync context (Flask thread)
-        # Get the running event loop and schedule the put operation
+    def _enqueue_response_from_sync_context(
+        self, request_id: str, response: ControlResponse
+    ) -> None:
         try:
+            self._ensure_asyncio_primitives()
             event_loop = asyncio.get_event_loop()
             if event_loop.is_running():
-                # Schedule the coroutine in the running loop
                 asyncio.run_coroutine_threadsafe(self._response_queue.put(response), event_loop)
             else:
-                # If no loop is running, use put_nowait (shouldn't happen)
                 self._response_queue.put_nowait(response)
         except Exception as error:
             logger.error(
@@ -320,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/control_loop.py

@@ -201,37 +201,12 @@ class ControlLoopHandler:
             message[:50],
         )
 
-        # Run the async request flow
-        # Check if we're already in an async context
-        try:
-            event_loop = asyncio.get_running_loop()
-            if event_loop.is_closed():
-                raise RuntimeError("Running event loop is closed")
+        # Run the async request flow.
+        running_event_loop = self._get_running_event_loop()
+        if running_event_loop is not None:
+            return self._run_request_in_running_loop(running_event_loop, request)
 
-            # Already in async context - create task and run it
-            # This shouldn't normally happen since request_interaction is sync
-            import nest_asyncio
-
-            nest_asyncio.apply()
-            return event_loop.run_until_complete(self._request_interaction_async(request))
-        except RuntimeError:
-            # Not in async context - create a temporary event loop.
-            previous_event_loop: asyncio.AbstractEventLoop | None = None
-            try:
-                previous_event_loop = asyncio.get_event_loop()
-            except RuntimeError:
-                previous_event_loop = None
-            else:
-                if getattr(previous_event_loop, "is_closed", lambda: False)():
-                    previous_event_loop = None
-
-            event_loop = asyncio.new_event_loop()
-            try:
-                asyncio.set_event_loop(event_loop)
-                return event_loop.run_until_complete(self._request_interaction_async(request))
-            finally:
-                event_loop.close()
-                asyncio.set_event_loop(previous_event_loop)
+        return self._run_request_in_new_loop(request)
 
     async def _request_interaction_async(self, request: ControlRequest) -> ControlResponse:
         """
@@ -312,6 +287,45 @@ class ControlLoopHandler:
 
         raise ProcedureWaitingForHuman(request.procedure_id, request.request_id)
 
+    def _get_running_event_loop(self) -> Optional[asyncio.AbstractEventLoop]:
+        try:
+            event_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return None
+
+        if event_loop.is_closed():
+            return None
+        return event_loop
+
+    def _run_request_in_running_loop(
+        self, event_loop: asyncio.AbstractEventLoop, request: ControlRequest
+    ) -> ControlResponse:
+        # Already in async context - create task and run it.
+        # This shouldn't normally happen since request_interaction is sync.
+        import nest_asyncio
+
+        nest_asyncio.apply()
+        return event_loop.run_until_complete(self._request_interaction_async(request))
+
+    def _run_request_in_new_loop(self, request: ControlRequest) -> ControlResponse:
+        # Not in async context - create a temporary event loop.
+        previous_event_loop: Optional[asyncio.AbstractEventLoop] = None
+        try:
+            previous_event_loop = asyncio.get_event_loop()
+        except RuntimeError:
+            previous_event_loop = None
+        else:
+            if getattr(previous_event_loop, "is_closed", lambda: False)():
+                previous_event_loop = None
+
+        event_loop = asyncio.new_event_loop()
+        try:
+            asyncio.set_event_loop(event_loop)
+            return event_loop.run_until_complete(self._request_interaction_async(request))
+        finally:
+            event_loop.close()
+            asyncio.set_event_loop(previous_event_loop)
+
     async def _fanout(
         self,
         request: ControlRequest,

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.