tactus 0.34.1__py3-none-any.whl → 0.35.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.34.1"
+__version__ = "0.35.0"
 
 # Core exports
 from tactus.core.runtime import TactusRuntime

tactus/adapters/broker_log.py

@@ -12,7 +12,7 @@ import logging
 import os
 import queue
 import threading
-from typing import Optional
+from typing import Any, Optional
 
 from tactus.protocols.models import LogEvent, CostEvent
 
@@ -35,7 +35,7 @@ class BrokerLogHandler:
         self.cost_events: list[CostEvent] = []
 
         # Thread-safe queue for events to send
-        self._queue: queue.Queue = queue.Queue()
+        self._queue: queue.Queue[dict[str, Any]] = queue.Queue()
 
         # Background worker thread
         self._worker_thread: Optional[threading.Thread] = None
@@ -79,31 +79,31 @@ class BrokerLogHandler:
         from tactus.broker.client import BrokerClient
 
         # Create fresh client in this thread's event loop
-        loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(loop)
+        event_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(event_loop)
         client = BrokerClient(self._socket_path)
 
         try:
             while not self._shutdown.is_set():
                 try:
                     # Wait for event with timeout to check shutdown flag
-                    event_dict = self._queue.get(timeout=0.05)
+                    event_payload = self._queue.get(timeout=0.05)
 
                     # Send event to broker
-                    loop.run_until_complete(client.emit_event(event_dict))
+                    event_loop.run_until_complete(client.emit_event(event_payload))
                     self._queue.task_done()
 
                 except queue.Empty:
                     continue
-                except Exception as e:
+                except Exception as error:
                     # Best effort - don't crash worker on individual failures
-                    logger.debug(f"[BROKER_LOG] Failed to emit event: {e}")
+                    logger.debug("[BROKER_LOG] Failed to emit event: %s", error)
                     try:
                         self._queue.task_done()
                     except ValueError:
                         pass
         finally:
-            loop.close()
+            event_loop.close()
             logger.debug("[BROKER_LOG] Background worker stopped")
 
     def log(self, event: LogEvent) -> None:
@@ -118,20 +118,23 @@ class BrokerLogHandler:
             self.cost_events.append(event)
 
         # Serialize to JSON-friendly dict
-        event_dict = event.model_dump(mode="json")
+        event_payload = event.model_dump(mode="json")
 
         # Normalize timestamp formatting for downstream consumers.
         iso_string = event.timestamp.isoformat()
-        if not (iso_string.endswith("Z") or "+" in iso_string or iso_string.count("-") > 2):
+        has_timezone_marker = (
+            iso_string.endswith("Z") or "+" in iso_string or iso_string.count("-") > 2
+        )
+        if not has_timezone_marker:
             iso_string += "Z"
-        event_dict["timestamp"] = iso_string
+        event_payload["timestamp"] = iso_string
 
         # Ensure worker is running
         self._ensure_worker_started()
 
         # Queue event for background sending (non-blocking)
         try:
-            self._queue.put_nowait(event_dict)
+            self._queue.put_nowait(event_payload)
         except queue.Full:
             # Drop event if queue is full (shouldn't happen with unlimited queue)
             logger.debug("[BROKER_LOG] Queue full, dropping event")
@@ -157,7 +160,7 @@ class BrokerLogHandler:
 
         if not self._queue.empty():
             remaining = self._queue.qsize()
-            logger.warning(f"[BROKER_LOG] Flush timeout with {remaining} events remaining")
+            logger.warning("[BROKER_LOG] Flush timeout with %s events remaining", remaining)
 
         # Signal worker to shutdown
         self._shutdown.set()

tactus/adapters/channels/__init__.py

@@ -13,7 +13,7 @@ The control loop uses a publish-subscribe pattern with namespace-based routing:
 - Subscribers can be observers (read-only) or responders (can provide input)
 """
 
-from typing import List, Dict, Any, Optional
+from typing import Any, Optional
 import logging
 import sys
 
@@ -31,7 +31,7 @@ _CHANNEL_LOADERS = {
 }
 
 
-def load_channel(channel_id: str, config: Dict[str, Any]) -> Optional[ControlChannel]:
+def load_channel(channel_id: str, config: dict[str, Any]) -> Optional[ControlChannel]:
     """
     Load a control channel by ID.
 
@@ -43,7 +43,7 @@ def load_channel(channel_id: str, config: Dict[str, Any]) -> Optional[ControlCha
         ControlChannel instance or None if loading fails
     """
     if channel_id not in _CHANNEL_LOADERS:
-        logger.warning(f"Unknown or not yet implemented channel: {channel_id}")
+        logger.warning("Unknown or not yet implemented channel: %s", channel_id)
         return None
 
     module_path = _CHANNEL_LOADERS[channel_id]
@@ -55,19 +55,21 @@ def load_channel(channel_id: str, config: Dict[str, Any]) -> Optional[ControlCha
         module = importlib.import_module(module_name)
         channel_class = getattr(module, class_name)
         return channel_class(**config)
-    except ImportError as e:
+    except ImportError as error:
         logger.warning(
-            f"Failed to load {channel_id} channel. "
-            f"Ensure dependencies are installed. "
-            f"Error: {e}"
+            "Failed to load %s channel. Ensure dependencies are installed. Error: %s",
+            channel_id,
+            error,
         )
         return None
-    except Exception as e:
-        logger.exception(f"Failed to initialize {channel_id} channel: {e}")
+    except Exception as error:
+        logger.exception("Failed to initialize %s channel: %s", channel_id, error)
         return None
 
 
-def load_channels_from_config(config: Optional[ControlLoopConfig] = None) -> List[ControlChannel]:
+def load_channels_from_config(
+    config: Optional[ControlLoopConfig] = None,
+) -> list[ControlChannel]:
     """
     Load control channels based on configuration and context.
 
@@ -81,7 +83,7 @@ def load_channels_from_config(config: Optional[ControlLoopConfig] = None) -> Lis
     Returns:
         List of enabled ControlChannel instances
     """
-    channels: List[ControlChannel] = []
+    channels: list[ControlChannel] = []
 
     if config is None:
         config = ControlLoopConfig()
@@ -101,11 +103,11 @@ def load_channels_from_config(config: Optional[ControlLoopConfig] = None) -> Lis
             continue
 
         # Remove 'enabled' from config before passing to constructor
-        init_config = {k: v for k, v in channel_config.items() if k != "enabled"}
+        init_config = {key: value for key, value in channel_config.items() if key != "enabled"}
         channel = load_channel(channel_id, init_config)
         if channel:
             channels.append(channel)
-            logger.info(f"Loaded control channel: {channel_id}")
+            logger.info("Loaded control channel: %s", channel_id)
 
     # If no channels configured, use defaults
     if not config.channels:
@@ -114,7 +116,7 @@ def load_channels_from_config(config: Optional[ControlLoopConfig] = None) -> Lis
     return channels
 
 
-def load_default_channels(procedure_id: Optional[str] = None) -> List[ControlChannel]:
+def load_default_channels(procedure_id: Optional[str] = None) -> list[ControlChannel]:
     """
     Load default control channels based on context.
 
@@ -128,7 +130,7 @@ def load_default_channels(procedure_id: Optional[str] = None) -> List[ControlCha
     Returns:
         List of enabled ControlChannel instances
     """
-    channels: List[ControlChannel] = []
+    channels: list[ControlChannel] = []
 
     # CLI channel - auto-detect based on tty
     if sys.stdin.isatty():

tactus/adapters/channels/base.py

@@ -75,8 +75,8 @@ class InProcessChannel(ABC):
 
         Default: no-op. Override for auth handshakes, connections, etc.
         """
-        logger.info(f"{self.channel_id}: initializing...")
-        logger.info(f"{self.channel_id}: ready")
+        logger.info("%s: initializing...", self.channel_id)
+        logger.info("%s: ready", self.channel_id)
 
     @abstractmethod
     async def send(self, request: ControlRequest) -> DeliveryResult:
@@ -112,7 +112,11 @@ class InProcessChannel(ABC):
                     self._response_queue.get(),
                     timeout=0.5,
                 )
-                logger.info(f"{self.channel_id}: received response for {response.request_id}")
+                logger.info(
+                    "%s: received response for %s",
+                    self.channel_id,
+                    response.request_id,
+                )
                 yield response
             except asyncio.TimeoutError:
                 continue
@@ -130,7 +134,12 @@ class InProcessChannel(ABC):
             external_message_id: Channel-specific message ID
             reason: Reason for cancellation
         """
-        logger.debug(f"{self.channel_id}: cancelling {external_message_id}: {reason}")
+        logger.debug(
+            "%s: cancelling %s: %s",
+            self.channel_id,
+            external_message_id,
+            reason,
+        )
 
     async def shutdown(self) -> None:
         """
@@ -139,7 +148,7 @@ class InProcessChannel(ABC):
         Default: sets shutdown event to stop receive loop.
         Override for additional cleanup (close connections, etc.).
         """
-        logger.info(f"{self.channel_id}: shutting down")
+        logger.info("%s: shutting down", self.channel_id)
         self._shutdown_event.set()
 
     def push_response(self, response: ControlResponse) -> None:
@@ -156,8 +165,8 @@ class InProcessChannel(ABC):
         """
         try:
             self._response_queue.put_nowait(response)
-        except Exception as e:
-            logger.error(f"{self.channel_id}: failed to queue response: {e}")
+        except Exception as error:
+            logger.error("%s: failed to queue response: %s", self.channel_id, error)
 
     def push_response_threadsafe(
         self, response: ControlResponse, loop: asyncio.AbstractEventLoop

tactus/adapters/channels/broker.py

@@ -73,9 +73,9 @@ class BrokerControlChannel(InProcessChannel):
 
     async def initialize(self) -> None:
         """Initialize broker control channel (broker already connected)."""
-        logger.info(f"{self.channel_id}: initializing...")
+        logger.info("%s: initializing...", self.channel_id)
         # Broker client already initialized by BrokerLogHandler setup
-        logger.info(f"{self.channel_id}: ready (via broker)")
+        logger.info("%s: ready (via broker)", self.channel_id)
 
     async def send(self, request: ControlRequest) -> DeliveryResult:
         """
@@ -84,7 +84,11 @@ class BrokerControlChannel(InProcessChannel):
         The request is serialized and sent via broker's control.request method.
         The host will relay to its SSE channel and return the response.
         """
-        logger.info(f"{self.channel_id}: sending control request {request.request_id} via broker")
+        logger.info(
+            "%s: sending control request %s via broker",
+            self.channel_id,
+            request.request_id,
+        )
 
         try:
             # Serialize request to JSON-compatible dict
@@ -96,7 +100,11 @@ class BrokerControlChannel(InProcessChannel):
 
                 if event_type == "delivered":
                     # Request successfully delivered to host channels
-                    logger.debug(f"{self.channel_id}: request {request.request_id} delivered")
+                    logger.debug(
+                        "%s: request %s delivered",
+                        self.channel_id,
+                        request.request_id,
+                    )
                     continue
 
                 elif event_type == "response":
@@ -110,13 +118,21 @@ class BrokerControlChannel(InProcessChannel):
                         channel_id=response_data.get("channel_id", "sse"),
                         responder_id=response_data.get("responder_id"),
                     )
-                    logger.info(f"{self.channel_id}: received response for {request.request_id}")
+                    logger.info(
+                        "%s: received response for %s",
+                        self.channel_id,
+                        request.request_id,
+                    )
                     self._response_queue.put_nowait(response)
                     break
 
                 elif event_type == "timeout":
                     # Host-side timeout
-                    logger.warning(f"{self.channel_id}: timeout for {request.request_id}")
+                    logger.warning(
+                        "%s: timeout for %s",
+                        self.channel_id,
+                        request.request_id,
+                    )
                     response = ControlResponse(
                         request_id=request.request_id,
                         value=request.default_value,
@@ -131,7 +147,12 @@ class BrokerControlChannel(InProcessChannel):
                     # Delivery or processing error
                     error = event.get("error", {})
                     error_msg = error.get("message", "Unknown broker error")
-                    logger.error(f"{self.channel_id}: error for {request.request_id}: {error_msg}")
+                    logger.error(
+                        "%s: error for %s: %s",
+                        self.channel_id,
+                        request.request_id,
+                        error_msg,
+                    )
                     raise RuntimeError(f"Broker control request failed: {error_msg}")
 
             return DeliveryResult(
@@ -141,14 +162,19 @@ class BrokerControlChannel(InProcessChannel):
                 success=True,
             )
 
-        except Exception as e:
-            logger.error(f"{self.channel_id}: failed to send {request.request_id}: {e}")
+        except Exception as error:
+            logger.error(
+                "%s: failed to send %s: %s",
+                self.channel_id,
+                request.request_id,
+                error,
+            )
             return DeliveryResult(
                 channel_id=self.channel_id,
                 external_message_id=request.request_id,
                 delivered_at=datetime.now(timezone.utc),
                 success=False,
-                error_message=str(e),
+                error_message=str(error),
             )
 
     @classmethod
@@ -171,9 +197,13 @@ class BrokerControlChannel(InProcessChannel):
 
             client = BrokerClient(socket_path)
             logger.info(
-                f"BrokerControlChannel: initialized from environment (socket={socket_path})"
+                "BrokerControlChannel: initialized from environment (socket=%s)",
+                socket_path,
             )
             return cls(client)
-        except Exception as e:
-            logger.warning(f"BrokerControlChannel: failed to initialize from environment: {e}")
+        except Exception as error:
+            logger.warning(
+                "BrokerControlChannel: failed to initialize from environment: %s",
+                error,
+            )
             return None

tactus/adapters/channels/cli.py

@@ -26,10 +26,14 @@ from tactus.adapters.channels.host import HostControlChannel
 logger = logging.getLogger(__name__)
 
 
-def format_time_ago(dt: datetime) -> str:
+def format_time_ago(timestamp: datetime) -> str:
     """Format datetime as human-readable time ago string."""
     now = datetime.now(timezone.utc)
-    delta = now - dt.replace(tzinfo=timezone.utc) if dt.tzinfo is None else now - dt
+    delta = (
+        now - timestamp.replace(tzinfo=timezone.utc)
+        if timestamp.tzinfo is None
+        else now - timestamp
+    )
 
     seconds = int(delta.total_seconds())
     if seconds < 60:
@@ -90,11 +94,11 @@ class CLIControlChannel(HostControlChannel):
 
     async def initialize(self) -> None:
         """Initialize the CLI channel."""
-        logger.info(f"{self.channel_id}: initializing...")
+        logger.info("%s: initializing...", self.channel_id)
         # Check if stdin is a tty
         if not sys.stdin.isatty():
-            logger.warning(f"{self.channel_id}: stdin is not a tty, prompts may not work")
-        logger.info(f"{self.channel_id}: ready")
+            logger.warning("%s: stdin is not a tty, prompts may not work", self.channel_id)
+        logger.info("%s: ready", self.channel_id)
 
     def _display_request(self, request: ControlRequest) -> None:
         """
@@ -163,13 +167,13 @@ class CLIControlChannel(HostControlChannel):
         request_type = request.request_type
         if request_type == ControlRequestType.APPROVAL:
             return self._handle_approval(request)
-        elif request_type == ControlRequestType.INPUT:
+        if request_type == ControlRequestType.INPUT:
             return self._handle_input(request)
-        elif request_type == ControlRequestType.REVIEW:
+        if request_type == ControlRequestType.REVIEW:
             return self._handle_review(request)
-        elif request_type == ControlRequestType.ESCALATION:
+        if request_type == ControlRequestType.ESCALATION:
             return self._handle_escalation(request)
-        elif request_type == ControlRequestType.INPUTS:
+        if request_type == ControlRequestType.INPUTS:
             return self._handle_inputs(request)
         else:
             # Default: treat as input
@@ -212,8 +216,8 @@ class CLIControlChannel(HostControlChannel):
         """Handle options selection."""
         # Display options
         self.console.print("\n[bold]Options:[/bold]")
-        for i, option in enumerate(options, 1):
-            self.console.print(f"  {i}. [cyan]{option.label}[/cyan]")
+        for index, option in enumerate(options, 1):
+            self.console.print(f"  {index}. [cyan]{option.label}[/cyan]")
             if option.description:
                 self.console.print(f"     [dim]{option.description}[/dim]")
 
@@ -309,15 +313,15 @@ class CLIControlChannel(HostControlChannel):
 
         # Display summary
         self.console.print(f"\n[bold cyan]Collecting {len(items)} inputs:[/bold cyan]")
-        for idx, item in enumerate(items, 1):
+        for index, item in enumerate(items, 1):
             req_marker = "*" if item.required else ""
-            self.console.print(f"  {idx}. [cyan]{item.label}[/cyan]{req_marker}")
+            self.console.print(f"  {index}. [cyan]{item.label}[/cyan]{req_marker}")
         self.console.print()
 
         # Collect responses for each item
         responses = {}
 
-        for idx, item in enumerate(items, 1):
+        for index, item in enumerate(items, 1):
             if self.is_cancelled():
                 return None
 
@@ -325,7 +329,7 @@ class CLIControlChannel(HostControlChannel):
             self.console.print(
                 Panel(
                     item.message,
-                    title=f"[bold]{idx}/{len(items)}: {item.label}[/bold]",
+                    title=f"[bold]{index}/{len(items)}: {item.label}[/bold]",
                     style="cyan" if item.required else "blue",
                 )
             )

tactus/adapters/channels/host.py

@@ -15,7 +15,7 @@ import asyncio
 import logging
 import threading
 from abc import abstractmethod
-from typing import Optional
+from typing import Any, Optional
 from datetime import datetime, timezone
 
 from tactus.protocols.control import (
@@ -84,7 +84,11 @@ class HostControlChannel(InProcessChannel):
         Returns:
             DeliveryResult indicating successful delivery
         """
-        logger.info(f"{self.channel_id}: sending notification for {request.request_id}")
+        logger.info(
+            "%s: sending notification for %s",
+            self.channel_id,
+            request.request_id,
+        )
 
         # Store for background thread access
         self._current_request = request
@@ -122,7 +126,12 @@ class HostControlChannel(InProcessChannel):
             external_message_id: Request ID (same as sent)
             reason: Reason for cancellation (e.g., "Responded via tactus_cloud")
         """
-        logger.debug(f"{self.channel_id}: cancelling {external_message_id}: {reason}")
+        logger.debug(
+            "%s: cancelling %s: %s",
+            self.channel_id,
+            external_message_id,
+            reason,
+        )
         self._cancel_event.set()
         self._show_cancelled(reason)
 
@@ -167,9 +176,9 @@ class HostControlChannel(InProcessChannel):
                 else:
                     self.push_response(response)
 
-        except Exception as e:
+        except Exception as error:
             if not self._cancel_event.is_set():
-                logger.error(f"{self.channel_id}: input error: {e}")
+                logger.error("%s: input error: %s", self.channel_id, error)
 
     @abstractmethod
     def _display_request(self, request: ControlRequest) -> None:
@@ -185,7 +194,7 @@ class HostControlChannel(InProcessChannel):
         ...
 
     @abstractmethod
-    def _prompt_for_input(self, request: ControlRequest) -> Optional[any]:
+    def _prompt_for_input(self, request: ControlRequest) -> Optional[Any]:
         """
         Collect input from the user.