tactus 0.34.1__py3-none-any.whl → 0.35.0__py3-none-any.whl

tactus/primitives/tool.py

@@ -9,7 +9,7 @@ Provides:
 """
 
 import logging
-from typing import Any, Optional, Dict, List, TYPE_CHECKING
+from typing import Any, Optional, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from tactus.primitives.tool_handle import ToolHandle
@@ -20,13 +20,13 @@ logger = logging.getLogger(__name__)
 class ToolCall:
     """Represents a single tool call with arguments and result."""
 
-    def __init__(self, name: str, args: Dict[str, Any], result: Any):
+    def __init__(self, name: str, args: dict[str, Any], result: Any):
         self.name = name
         self.args = args
         self.result = result
         self.timestamp = None  # Could add timestamp tracking
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for Lua access."""
         return {"name": self.name, "args": self.args, "result": self.result}
 
@@ -47,19 +47,22 @@ class ToolPrimitive:
     """
 
     def __init__(
-        self, log_handler=None, agent_name: Optional[str] = None, procedure_id: Optional[str] = None
+        self,
+        log_handler=None,
+        agent_name: Optional[str] = None,
+        procedure_id: Optional[str] = None,
     ):
         """Initialize tool tracking."""
-        self._tool_calls: List[ToolCall] = []
-        self._last_calls: Dict[str, ToolCall] = {}  # name -> last call
+        self._tool_calls: list[ToolCall] = []
+        self._last_calls: dict[str, ToolCall] = {}  # name -> last call
         self.log_handler = log_handler
         self.agent_name = agent_name
         self.procedure_id = procedure_id
         self._runtime = None  # Will be set by runtime for Tool.get() support
-        self._tool_registry: Dict[str, "ToolHandle"] = {}  # For Tool("name") lookup
+        self._tool_registry: dict[str, "ToolHandle"] = {}  # For Tool("name") lookup
         logger.debug("ToolPrimitive initialized")
 
-    def set_tool_registry(self, registry: Dict[str, "ToolHandle"]) -> None:
+    def set_tool_registry(self, registry: dict[str, "ToolHandle"]) -> None:
         """
         Set the tool registry for Tool("name") lookup.
 
@@ -69,7 +72,7 @@ class ToolPrimitive:
             registry: Dict mapping tool names to ToolHandle instances
         """
         self._tool_registry = registry
-        logger.debug(f"ToolPrimitive tool registry set with {len(registry)} tools")
+        logger.debug("ToolPrimitive tool registry set with %s tools", len(registry))
 
     def __call__(self, tool_name: str) -> "ToolHandle":
         """
@@ -132,7 +135,7 @@ class ToolPrimitive:
         """
         from tactus.primitives.tool_handle import ToolHandle
 
-        logger.debug(f"Tool.get('{tool_name}') called")
+        logger.debug("Tool.get('%s') called", tool_name)
 
         # Look up toolset from runtime registry
         toolset = self._get_toolset(tool_name)
@@ -143,10 +146,10 @@ class ToolPrimitive:
             )
 
         # Extract the callable function from the toolset
-        tool_fn = self._extract_tool_function(toolset, tool_name)
+        tool_function = self._extract_tool_function(toolset, tool_name)
 
-        logger.debug(f"Tool.get('{tool_name}') returning ToolHandle")
-        return ToolHandle(tool_name, tool_fn, self)
+        logger.debug("Tool.get('%s') returning ToolHandle", tool_name)
+        return ToolHandle(tool_name, tool_function, self)
 
     def _get_toolset(self, name: str) -> Optional[Any]:
         """
@@ -226,7 +229,9 @@ class ToolPrimitive:
 
         # Fallback: assume the toolset itself contains tool functions
         logger.warning(
-            f"Could not extract tool function for '{tool_name}' from toolset type {type(toolset)}"
+            "Could not extract tool function for '%s' from toolset type %s",
+            tool_name,
+            type(toolset),
         )
 
         # Return a wrapper that attempts to call through the toolset
@@ -252,9 +257,9 @@ class ToolPrimitive:
                 Log.info("Done tool was called")
             end
         """
-        called = tool_name in self._last_calls
-        logger.debug(f"Tool.called('{tool_name}') = {called}")
-        return called
+        was_called = tool_name in self._last_calls
+        logger.debug("Tool.called('%s') = %s", tool_name, was_called)
+        return was_called
 
     def last_result(self, tool_name: str) -> Any:
         """
@@ -273,14 +278,14 @@ class ToolPrimitive:
             end
         """
         if tool_name not in self._last_calls:
-            logger.debug(f"Tool.last_result('{tool_name}') = None (never called)")
+            logger.debug("Tool.last_result('%s') = None (never called)", tool_name)
             return None
 
         result = self._last_calls[tool_name].result
-        logger.debug(f"Tool.last_result('{tool_name}') = {result}")
+        logger.debug("Tool.last_result('%s') = %s", tool_name, result)
         return result
 
-    def last_call(self, tool_name: str) -> Optional[Dict[str, Any]]:
+    def last_call(self, tool_name: str) -> Optional[dict[str, Any]]:
         """
         Get full information about the last call to a tool.
 
@@ -298,15 +303,19 @@ class ToolPrimitive:
             end
         """
         if tool_name not in self._last_calls:
-            logger.debug(f"Tool.last_call('{tool_name}') = None (never called)")
+            logger.debug("Tool.last_call('%s') = None (never called)", tool_name)
             return None
 
         call_dict = self._last_calls[tool_name].to_dict()
-        logger.debug(f"Tool.last_call('{tool_name}') = {call_dict}")
+        logger.debug("Tool.last_call('%s') = %s", tool_name, call_dict)
         return call_dict
 
     def record_call(
-        self, tool_name: str, args: Dict[str, Any], result: Any, agent_name: Optional[str] = None
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        result: Any,
+        agent_name: Optional[str] = None,
     ) -> None:
         """
         Record a tool call (called by runtime after tool execution).
@@ -319,11 +328,15 @@ class ToolPrimitive:
 
         Note: This is called internally by the runtime, not from Lua
         """
-        call = ToolCall(tool_name, args, result)
-        self._tool_calls.append(call)
-        self._last_calls[tool_name] = call
-
-        logger.debug(f"Tool call recorded: {tool_name} -> {len(self._tool_calls)} total calls")
+        tool_call = ToolCall(tool_name, args, result)
+        self._tool_calls.append(tool_call)
+        self._last_calls[tool_name] = tool_call
+
+        logger.debug(
+            "Tool call recorded: %s -> %s total calls",
+            tool_name,
+            len(self._tool_calls),
+        )
 
         # Emit ToolCallEvent if we have a log handler
         if self.log_handler:
@@ -338,10 +351,10 @@ class ToolPrimitive:
                     procedure_id=self.procedure_id,
                 )
                 self.log_handler.log(event)
-            except Exception as e:
-                logger.warning(f"Failed to log tool call event: {e}")
+            except Exception as error:
+                logger.warning("Failed to log tool call event: %s", error)
 
-    def get_all_calls(self) -> List[ToolCall]:
+    def get_all_calls(self) -> list[ToolCall]:
         """
         Get all tool calls (for debugging/logging).
 

tactus/primitives/tool_handle.py

@@ -7,7 +7,9 @@ that can be invoked directly without going through an agent.
 
 import asyncio
 import logging
-from typing import Any, Callable, Dict, Optional, TYPE_CHECKING
+from typing import Any, Callable, Optional, TYPE_CHECKING
+
+from tactus.utils.asyncio_helpers import clear_closed_event_loop
 
 if TYPE_CHECKING:
     from tactus.primitives.tool import ToolPrimitive
@@ -30,7 +32,7 @@ class ToolHandle:
     def __init__(
         self,
         name: str,
-        impl_fn: Callable,
+        implementation_function: Callable,
         tool_primitive: Optional["ToolPrimitive"] = None,
         is_async: bool = False,
         record_calls: bool = True,
@@ -40,19 +42,34 @@ class ToolHandle:
 
         Args:
             name: Tool name for tracking/logging
-            impl_fn: The actual function to execute
+            implementation_function: The actual function to execute
             tool_primitive: Optional ToolPrimitive for call recording
-            is_async: Whether impl_fn is async (for MCP tools)
+            is_async: Whether the implementation function is async (for MCP tools)
         """
         self.name = name
-        self.impl_fn = impl_fn
+        self.implementation_function = implementation_function
         self.tool_primitive = tool_primitive
         self.is_async = is_async
         self.record_calls = record_calls
 
-        logger.debug(f"ToolHandle created for '{name}' (async={is_async})")
+        logger.debug("ToolHandle created for '%s' (async=%s)", name, is_async)
+
+    def _has_tool_primitive(self) -> bool:
+        return self.tool_primitive is not None
+
+    def _normalize_tool_arguments(self, tool_arguments: Any) -> Any:
+        """
+        Convert a Lua table or mapping-like input to a plain Python dict when possible.
+        """
+        if tool_arguments is None:
+            return {}
+
+        if hasattr(tool_arguments, "items"):
+            return self._lua_table_to_dict(tool_arguments)
+
+        return tool_arguments
 
-    def call(self, args: Dict[str, Any]) -> Any:
+    def call(self, args: dict[str, Any]) -> Any:
         """
         Execute the tool with given arguments.
 
@@ -65,31 +82,35 @@ class ToolHandle:
         Example (Lua):
             local result = my_tool:call({arg1 = "value"})
         """
-        logger.debug(f"ToolHandle.call('{self.name}') with args: {args}")
+        logger.debug("ToolHandle.call('%s') with args: %s", self.name, args)
 
         try:
             # Convert Lua table to Python dict if needed
-            if hasattr(args, "items"):
-                args = self._lua_table_to_dict(args)
+            normalized_arguments = self._normalize_tool_arguments(args)
 
             # Execute the implementation
-            if self.is_async or asyncio.iscoroutinefunction(self.impl_fn):
-                result = self._run_async(args)
+            if self.is_async or asyncio.iscoroutinefunction(self.implementation_function):
+                result = self._run_async(normalized_arguments)
             else:
-                result = self.impl_fn(args)
+                result = self.implementation_function(normalized_arguments)
 
             # Record the call for tracking
             if self.tool_primitive and self.record_calls:
-                self.tool_primitive.record_call(self.name, args, result)
+                self.tool_primitive.record_call(self.name, normalized_arguments, result)
 
-            logger.debug(f"ToolHandle.call('{self.name}') returned: {result}")
+            logger.debug("ToolHandle.call('%s') returned: %s", self.name, result)
             return result
 
-        except Exception as e:
-            logger.error(f"ToolHandle.call('{self.name}') failed: {e}", exc_info=True)
+        except Exception as error:
+            logger.error(
+                "ToolHandle.call('%s') failed: %s",
+                self.name,
+                error,
+                exc_info=True,
+            )
             raise
 
-    def __call__(self, args: Dict[str, Any]) -> Any:
+    def __call__(self, args: dict[str, Any]) -> Any:
         """
         Make handle callable for shorthand syntax.
 
@@ -110,15 +131,15 @@ class ToolHandle:
                 Log.info("Task completed!")
             end
         """
-        if not self.tool_primitive:
-            logger.warning(f"ToolHandle.called('{self.name}'): No tool_primitive attached")
+        if not self._has_tool_primitive():
+            logger.warning("ToolHandle.called('%s'): No tool_primitive attached", self.name)
             return False
 
         result = self.tool_primitive.called(self.name)
-        logger.debug(f"ToolHandle.called('{self.name}') = {result}")
+        logger.debug("ToolHandle.called('%s') = %s", self.name, result)
         return result
 
-    def last_call(self) -> Optional[Dict[str, Any]]:
+    def last_call(self) -> Optional[dict[str, Any]]:
         """
         Get the last call record for this tool.
 
@@ -131,12 +152,12 @@ class ToolHandle:
                 Log.info("Last multiply: " .. call.args.a .. " * " .. call.args.b)
             end
         """
-        if not self.tool_primitive:
-            logger.warning(f"ToolHandle.last_call('{self.name}'): No tool_primitive attached")
+        if not self._has_tool_primitive():
+            logger.warning("ToolHandle.last_call('%s'): No tool_primitive attached", self.name)
             return None
 
         result = self.tool_primitive.last_call(self.name)
-        logger.debug(f"ToolHandle.last_call('{self.name}') = {result}")
+        logger.debug("ToolHandle.last_call('%s') = %s", self.name, result)
         return result
 
     def last_result(self) -> Any:
@@ -150,12 +171,12 @@ class ToolHandle:
             local answer = done.last_result()
             return { result = answer }
         """
-        if not self.tool_primitive:
-            logger.warning(f"ToolHandle.last_result('{self.name}'): No tool_primitive attached")
+        if not self._has_tool_primitive():
+            logger.warning("ToolHandle.last_result('%s'): No tool_primitive attached", self.name)
             return None
 
         result = self.tool_primitive.last_result(self.name)
-        logger.debug(f"ToolHandle.last_result('{self.name}') = {result}")
+        logger.debug("ToolHandle.last_result('%s') = %s", self.name, result)
         return result
 
     def call_count(self) -> int:
@@ -169,13 +190,13 @@ class ToolHandle:
             local count = multiply.call_count()
             Log.info("Multiply was called " .. count .. " times")
         """
-        if not self.tool_primitive:
-            logger.warning(f"ToolHandle.call_count('{self.name}'): No tool_primitive attached")
+        if not self._has_tool_primitive():
+            logger.warning("ToolHandle.call_count('%s'): No tool_primitive attached", self.name)
             return 0
 
         # Count all calls with this tool name
         count = sum(1 for call in self.tool_primitive._tool_calls if call.name == self.name)
-        logger.debug(f"ToolHandle.call_count('{self.name}') = {count}")
+        logger.debug("ToolHandle.call_count('%s') = %s", self.name, count)
         return count
 
     def reset(self) -> None:
@@ -202,17 +223,17 @@ class ToolHandle:
                 Log.info("Agent 2 completed")
             end
         """
-        if not self.tool_primitive:
-            logger.warning(f"ToolHandle.reset('{self.name}'): No tool_primitive attached")
+        if not self._has_tool_primitive():
+            logger.warning("ToolHandle.reset('%s'): No tool_primitive attached", self.name)
             return
 
         # Remove all calls for this tool
         self.tool_primitive._tool_calls = [
             call for call in self.tool_primitive._tool_calls if call.name != self.name
         ]
-        logger.debug(f"ToolHandle.reset('{self.name}'): Cleared all call records")
+        logger.debug("ToolHandle.reset('%s'): Cleared all call records", self.name)
 
-    def _run_async(self, args: Dict[str, Any]) -> Any:
+    def _run_async(self, args: dict[str, Any]) -> Any:
         """
         Run async function from sync context.
 
@@ -220,46 +241,47 @@ class ToolHandle:
         """
         try:
             # Try to get a running event loop
-            loop = asyncio.get_running_loop()
+            running_loop = asyncio.get_running_loop()
 
             # We're in an async context - use nest_asyncio if available
             try:
                 import nest_asyncio
 
-                nest_asyncio.apply(loop)
-                return asyncio.run(self.impl_fn(args))
+                nest_asyncio.apply(running_loop)
+                return asyncio.run(self.implementation_function(args))
             except ImportError:
                 # nest_asyncio not available, fall back to threading
                 import threading
 
-                result_container = {"value": None, "exception": None}
+                async_result = {"value": None, "exception": None}
 
                 def run_in_thread():
                     try:
-                        new_loop = asyncio.new_event_loop()
-                        asyncio.set_event_loop(new_loop)
+                        thread_event_loop = asyncio.new_event_loop()
+                        asyncio.set_event_loop(thread_event_loop)
                         try:
-                            result_container["value"] = new_loop.run_until_complete(
-                                self.impl_fn(args)
+                            async_result["value"] = thread_event_loop.run_until_complete(
+                                self.implementation_function(args)
                             )
                         finally:
-                            new_loop.close()
-                    except Exception as e:
-                        result_container["exception"] = e
+                            thread_event_loop.close()
+                    except Exception as error:
+                        async_result["exception"] = error
 
-                thread = threading.Thread(target=run_in_thread)
-                thread.start()
-                thread.join()
+                worker_thread = threading.Thread(target=run_in_thread)
+                worker_thread.start()
+                worker_thread.join()
 
-                if result_container["exception"]:
-                    raise result_container["exception"]
-                return result_container["value"]
+                if async_result["exception"]:
+                    raise async_result["exception"]
+                return async_result["value"]
 
         except RuntimeError:
             # No event loop running - safe to use asyncio.run()
-            return asyncio.run(self.impl_fn(args))
+            clear_closed_event_loop()
+            return asyncio.run(self.implementation_function(args))
 
-    def _lua_table_to_dict(self, lua_table) -> Dict[str, Any]:
+    def _lua_table_to_dict(self, lua_table: Any) -> Any:
         """Convert a Lua table to Python dict recursively."""
         if lua_table is None:
             return {}

tactus/primitives/toolset.py

@@ -5,7 +5,7 @@ Provides first-class support for Pydantic AI's composable toolset architecture.
 """
 
 import logging
-from typing import Any, Dict, Callable
+from typing import Any, Callable
 from pydantic_ai.toolsets import AbstractToolset, CombinedToolset, FilteredToolset
 
 logger = logging.getLogger(__name__)
@@ -36,7 +36,7 @@ class ToolsetPrimitive:
         self.definitions = {}  # name -> toolset config (from DSL)
         logger.debug("ToolsetPrimitive initialized")
 
-    def define(self, name: str, config: Dict[str, Any]) -> None:
+    def define(self, name: str, config: dict[str, Any]) -> None:
         """
         Register a toolset definition from the DSL.
 
@@ -61,7 +61,11 @@ class ToolsetPrimitive:
             }
         """
         self.definitions[name] = config
-        logger.info(f"Defined toolset '{name}' of type '{config.get('type')}'")
+        logger.info(
+            "Defined toolset '%s' of type '%s'",
+            name,
+            config.get("type"),
+        )
 
     def get(self, name: str) -> AbstractToolset:
         """
@@ -80,9 +84,9 @@ class ToolsetPrimitive:
             ValueError: If toolset not found
         """
         # Try to resolve from runtime first (config-defined toolsets)
-        toolset = self.runtime.resolve_toolset(name)
-        if toolset:
-            return toolset
+        toolset_from_runtime = self.runtime.resolve_toolset(name)
+        if toolset_from_runtime:
+            return toolset_from_runtime
 
         # Try DSL definitions
         if name in self.definitions:
@@ -101,7 +105,7 @@ class ToolsetPrimitive:
             CombinedToolset containing all input toolsets
         """
         toolset_list = list(toolsets)
-        logger.debug(f"Combining {len(toolset_list)} toolsets")
+        logger.debug("Combining %s toolsets", len(toolset_list))
         return CombinedToolset(toolset_list)
 
     def filter(self, toolset: AbstractToolset, predicate: Callable[[str], bool]) -> FilteredToolset:
@@ -123,14 +127,14 @@ class ToolsetPrimitive:
 
         # Wrap Lua function for Pydantic AI's filter API
         # Pydantic AI's filtered() expects: lambda ctx, tool: bool
-        def pydantic_filter(ctx, tool):
+        def pydantic_filter(_context, tool):
             # Call Lua predicate with just the tool name
             return predicate(tool.name)
 
         logger.debug("Creating filtered toolset")
         return toolset.filtered(pydantic_filter)
 
-    def _create_toolset_from_definition(self, name: str, config: Dict[str, Any]) -> AbstractToolset:
+    def _create_toolset_from_definition(self, name: str, config: dict[str, Any]) -> AbstractToolset:
         """
         Create a toolset from a DSL definition.
 
@@ -148,16 +152,15 @@ class ToolsetPrimitive:
 
         if toolset_type == "plugin":
             return self._create_plugin_toolset(name, config)
-        elif toolset_type == "mcp":
+        if toolset_type == "mcp":
             return self._create_mcp_toolset_reference(name, config)
-        elif toolset_type == "combined":
+        if toolset_type == "combined":
             return self._create_combined_toolset(name, config)
-        elif toolset_type == "filtered":
+        if toolset_type == "filtered":
             return self._create_filtered_toolset(name, config)
-        else:
-            raise ValueError(f"Unknown toolset type: {toolset_type}")
+        raise ValueError(f"Unknown toolset type: {toolset_type}")
 
-    def _create_plugin_toolset(self, name: str, config: Dict[str, Any]) -> AbstractToolset:
+    def _create_plugin_toolset(self, name: str, config: dict[str, Any]) -> AbstractToolset:
         """Create a plugin toolset from paths."""
         from tactus.adapters.plugins import PluginLoader
 
@@ -169,7 +172,7 @@ class ToolsetPrimitive:
         toolset = loader.create_toolset(paths, name=name)
         return toolset
 
-    def _create_mcp_toolset_reference(self, name: str, config: Dict[str, Any]) -> AbstractToolset:
+    def _create_mcp_toolset_reference(self, name: str, config: dict[str, Any]) -> AbstractToolset:
         """Get reference to an MCP toolset."""
         server_name = config.get("server")
         if not server_name:
@@ -183,12 +186,12 @@ class ToolsetPrimitive:
         # Get the toolset by server name
         toolset = self.runtime.mcp_manager.get_toolset_by_name(server_name)
         if toolset:
-            logger.info(f"Found MCP toolset for server '{server_name}'")
+            logger.info("Found MCP toolset for server '%s'", server_name)
             return toolset
 
         raise ValueError(f"MCP server toolset '{server_name}' not found")
 
-    def _create_combined_toolset(self, name: str, config: Dict[str, Any]) -> CombinedToolset:
+    def _create_combined_toolset(self, name: str, config: dict[str, Any]) -> CombinedToolset:
         """Create a combined toolset from sources."""
         sources = config.get("sources", [])
         if not sources:
@@ -197,12 +200,12 @@ class ToolsetPrimitive:
         # Resolve each source toolset
         resolved_toolsets = []
         for source_name in sources:
-            toolset = self.get(source_name)
-            resolved_toolsets.append(toolset)
+            resolved_toolset = self.get(source_name)
+            resolved_toolsets.append(resolved_toolset)
 
         return CombinedToolset(resolved_toolsets)
 
-    def _create_filtered_toolset(self, name: str, config: Dict[str, Any]) -> FilteredToolset:
+    def _create_filtered_toolset(self, name: str, config: dict[str, Any]) -> FilteredToolset:
         """Create a filtered toolset."""
         source = config.get("source")
         filter_pattern = config.get("filter")
@@ -220,7 +223,7 @@ class ToolsetPrimitive:
 
         pattern = re.compile(filter_pattern)
 
-        def filter_func(ctx, tool):
+        def filter_func(_context, tool):
             return pattern.match(tool.name) is not None
 
         return source_toolset.filtered(filter_func)

tactus/sandbox/config.py

@@ -5,7 +5,7 @@ Defines the SandboxConfig Pydantic model for controlling container execution.
 """
 
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Optional
 
 from pydantic import BaseModel, Field, model_validator
 
@@ -47,7 +47,7 @@ class SandboxConfig(BaseModel):
     )
 
     # Additional environment variables to pass to container
-    env: Dict[str, str] = Field(
+    env: dict[str, str] = Field(
         default_factory=dict,
         description="Additional environment variables to pass to the container",
     )
@@ -59,7 +59,7 @@ class SandboxConfig(BaseModel):
     )
 
     # Additional volume mounts
-    volumes: List[str] = Field(
+    volumes: list[str] = Field(
         default_factory=list,
         description="Additional volume mounts in 'host:container:mode' format",
     )
@@ -157,7 +157,7 @@ class SandboxConfig(BaseModel):
     model_config = {"arbitrary_types_allowed": True}
 
     @model_validator(mode="after")
-    def add_default_volumes(self):
+    def add_default_volumes(self) -> "SandboxConfig":
         """Add default volume mounts based on config flags."""
         if self.mount_current_dir:
             # Insert at beginning so user volumes can override