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

tactus/primitives/file.py

@@ -39,29 +39,31 @@ class FilePrimitive:
         """
         self.base_path = Path(base_path) if base_path else Path.cwd()
         self.execution_context = execution_context
-        logger.debug(f"FilePrimitive initialized with base_path: {self.base_path}")
+        logger.debug("FilePrimitive initialized with base_path: %s", self.base_path)
 
-    def _check_determinism(self, operation: str):
+    def _check_determinism(self, operation: str) -> None:
         """Warn if file operation called outside checkpoint."""
         if self.execution_context and not getattr(
             self.execution_context, "_inside_checkpoint", False
         ):
             import warnings
 
+            warning_banner = "=" * 70
             warnings.warn(
-                f"\n{'=' * 70}\n"
+                "\n"
+                f"{warning_banner}\n"
                 f"DETERMINISM WARNING: File.{operation}() called outside checkpoint\n"
-                f"{'=' * 70}\n\n"
-                f"File operations are non-deterministic - "
-                f"file contents can change between executions.\n\n"
-                f"To fix, wrap in Step.checkpoint():\n\n"
-                f"  state.data = Step.checkpoint(function()\n"
+                f"{warning_banner}\n\n"
+                "File operations are non-deterministic - "
+                "file contents can change between executions.\n\n"
+                "To fix, wrap in Step.checkpoint():\n\n"
+                "  state.data = Step.checkpoint(function()\n"
                 f"    return File.{operation}(...)\n"
-                f"  end)\n\n"
-                f"Why: Files can be modified, deleted, or created "
-                f"between procedure executions,\n"
-                f"causing different behavior on replay.\n"
-                f"\n{'=' * 70}\n",
+                "  end)\n\n"
+                "Why: Files can be modified, deleted, or created "
+                "between procedure executions,\n"
+                "causing different behavior on replay.\n"
+                f"\n{warning_banner}\n",
                 UserWarning,
                 stacklevel=3,
             )
@@ -88,21 +90,21 @@ class FilePrimitive:
         file_path = self._resolve_path(path)
 
         try:
-            logger.debug(f"Reading file: {file_path}")
-            with open(file_path, "r", encoding="utf-8") as f:
-                content = f.read()
-            logger.info(f"Read {len(content)} bytes from {file_path}")
+            logger.debug("Reading file: %s", file_path)
+            with open(file_path, "r", encoding="utf-8") as file_handle:
+                content = file_handle.read()
+            logger.info("Read %s bytes from %s", len(content), file_path)
             return content
 
         except FileNotFoundError:
-            error_msg = f"File not found: {file_path}"
-            logger.error(error_msg)
-            raise FileNotFoundError(error_msg)
+            error_message = f"File not found: {file_path}"
+            logger.error(error_message)
+            raise FileNotFoundError(error_message)
 
-        except Exception as e:
-            error_msg = f"Failed to read file {file_path}: {e}"
-            logger.error(error_msg)
-            raise IOError(error_msg)
+        except Exception as error:
+            error_message = f"Failed to read file {file_path}: {error}"
+            logger.error(error_message)
+            raise IOError(error_message)
 
     def write(self, path: str, content: str) -> bool:
         """
@@ -130,17 +132,17 @@ class FilePrimitive:
             # Create parent directories if needed
             file_path.parent.mkdir(parents=True, exist_ok=True)
 
-            logger.debug(f"Writing to file: {file_path}")
-            with open(file_path, "w", encoding="utf-8") as f:
-                f.write(content)
+            logger.debug("Writing to file: %s", file_path)
+            with open(file_path, "w", encoding="utf-8") as file_handle:
+                file_handle.write(content)
 
-            logger.info(f"Wrote {len(content)} bytes to {file_path}")
+            logger.info("Wrote %s bytes to %s", len(content), file_path)
             return True
 
-        except Exception as e:
-            error_msg = f"Failed to write file {file_path}: {e}"
-            logger.error(error_msg)
-            raise IOError(error_msg)
+        except Exception as error:
+            error_message = f"Failed to write file {file_path}: {error}"
+            logger.error(error_message)
+            raise IOError(error_message)
 
     def exists(self, path: str) -> bool:
         """
@@ -162,9 +164,9 @@ class FilePrimitive:
         """
         self._check_determinism("exists")
         file_path = self._resolve_path(path)
-        exists = file_path.exists() and file_path.is_file()
-        logger.debug(f"File exists check for {file_path}: {exists}")
-        return exists
+        file_exists = file_path.exists() and file_path.is_file()
+        logger.debug("File exists check for %s: %s", file_path, file_exists)
+        return file_exists
 
     def size(self, path: str) -> int:
         """
@@ -187,13 +189,13 @@ class FilePrimitive:
         file_path = self._resolve_path(path)
 
         if not file_path.exists():
-            error_msg = f"File not found: {file_path}"
-            logger.error(error_msg)
-            raise FileNotFoundError(error_msg)
+            error_message = f"File not found: {file_path}"
+            logger.error(error_message)
+            raise FileNotFoundError(error_message)
 
-        size = file_path.stat().st_size
-        logger.debug(f"File size for {file_path}: {size} bytes")
-        return size
+        file_size_bytes = file_path.stat().st_size
+        logger.debug("File size for %s: %s bytes", file_path, file_size_bytes)
+        return file_size_bytes
 
     def _resolve_path(self, path: str) -> Path:
         """
@@ -208,22 +210,22 @@ class FilePrimitive:
         Raises:
             ValueError: If absolute path or path traversal detected
         """
-        path_obj = Path(path)
+        relative_path = Path(path)
 
         # Security: Never allow absolute paths
-        if path_obj.is_absolute():
+        if relative_path.is_absolute():
             raise ValueError(f"Absolute paths not allowed: {path}")
 
         # Resolve relative to base_path
-        resolved = (self.base_path / path_obj).resolve()
+        resolved_path = (self.base_path / relative_path).resolve()
 
         # Security: Verify resolved path is under base_path
         try:
-            resolved.relative_to(self.base_path)
+            resolved_path.relative_to(self.base_path)
         except ValueError:
             raise ValueError(f"Path traversal detected: {path} resolves outside base directory")
 
-        return resolved
+        return resolved_path
 
     def __repr__(self) -> str:
         return f"FilePrimitive(base_path={self.base_path})"

tactus/primitives/handles.py

@@ -17,7 +17,7 @@ Usage:
 """
 
 import logging
-from typing import Any, Optional, Dict, TYPE_CHECKING
+from typing import Any, Optional, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from tactus.dspy.agent import DSPyAgentHandle
@@ -26,7 +26,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-def _convert_lua_table(lua_table):
+def _convert_lua_table(lua_table: Any) -> Any:
     """
     Convert a lupa Lua table to a Python dict or list.
 
@@ -87,7 +87,7 @@ class AgentHandle:
         self._execution_context: Optional[Any] = None
         logger.debug(f"AgentHandle created for '{name}'")
 
-    def __call__(self, inputs=None):
+    def __call__(self, inputs: Any = None) -> Any:
         """
         Execute an agent turn using the callable interface.
 
@@ -108,27 +108,33 @@ class AgentHandle:
             result = worker({message = "Process this task"})
             print(result.response)
         """
-        logger.debug(
-            f"[CHECKPOINT] AgentHandle '{self.name}'.__call__ invoked, _primitive={self._primitive is not None}, _execution_context={self._execution_context is not None}"
-        )
+        logger.debug(
+            "[CHECKPOINT] AgentHandle '%s'.__call__ invoked, _primitive=%s, "
+            "_execution_context=%s",
+            self.name,
+            self._primitive is not None,
+            self._execution_context is not None,
+        )
         if self._primitive is None:
             raise RuntimeError(
                 f"Agent '{self.name}' initialization failed.\n"
                 f"This should not happen with immediate agent creation.\n"
                 f"Please report this as a bug with a minimal reproduction example."
             )
-        # Convert Lua table to Python dict if needed
-        converted_inputs = _convert_lua_table(inputs) if inputs is not None else None
-
-        # Convenience: allow shorthand string calls in Lua:
-        #   World("Hello") == World({message = "Hello"})
-        if isinstance(converted_inputs, str):
-            converted_inputs = {"message": converted_inputs}
+        # Convert Lua table to Python dict if needed
+        converted_inputs = _convert_lua_table(inputs) if inputs is not None else None
+
+        # Convenience: allow shorthand string calls in Lua:
+        #   World("Hello") == World({message = "Hello"})
+        if isinstance(converted_inputs, str):
+            converted_inputs = {"message": converted_inputs}
 
         # If we have an execution context, checkpoint the agent call
-        logger.debug(
-            f"[CHECKPOINT] AgentHandle '{self.name}' called, has_execution_context={self._execution_context is not None}"
-        )
+        logger.debug(
+            "[CHECKPOINT] AgentHandle '%s' called, has_execution_context=%s",
+            self.name,
+            self._execution_context is not None,
+        )
         if self._execution_context is not None:
 
             def agent_call():
@@ -148,18 +154,20 @@ class AgentHandle:
                             "file": info.get("source", "unknown"),
                             "line": info.get("currentline", 0),
                         }
-                except Exception as e:
-                    logger.debug(f"Could not capture source location: {e}")
-
-            logger.debug(
-                f"[CHECKPOINT] Creating checkpoint for agent '{self.name}', type=agent_turn, source_info={source_info}"
-            )
-            result = self._execution_context.checkpoint(
-                agent_call, checkpoint_type="agent_turn", source_info=source_info
-            )
-        else:
-            # No execution context - call directly without checkpointing
-            result = self._primitive(converted_inputs)
+                except Exception as error:
+                    logger.debug("Could not capture source location: %s", error)
+
+            logger.debug(
+                "[CHECKPOINT] Creating checkpoint for agent '%s', type=agent_turn, source_info=%s",
+                self.name,
+                source_info,
+            )
+            result = self._execution_context.checkpoint(
+                agent_call, checkpoint_type="agent_turn", source_info=source_info
+            )
+        else:
+            # No execution context - call directly without checkpointing
+            result = self._primitive(converted_inputs)
 
         # Convenience: expose the last agent output on the handle as `.output`
         # for Lua patterns like `agent(); return agent.output`.
@@ -201,9 +209,13 @@ class AgentHandle:
         """
         self._primitive = primitive
         self._execution_context = execution_context
-        logger.debug(
-            f"[CHECKPOINT] AgentHandle '{self.name}' connected to primitive (checkpointing={'enabled' if execution_context else 'disabled'}, execution_context={execution_context})"
-        )
+        logger.debug(
+            "[CHECKPOINT] AgentHandle '%s' connected to primitive (checkpointing=%s, "
+            "execution_context=%s)",
+            self.name,
+            "enabled" if execution_context else "disabled",
+            execution_context,
+        )
 
     def __repr__(self) -> str:
         connected = "connected" if self._primitive else "disconnected"
@@ -227,7 +239,7 @@ class ModelHandle:
         """
         self.name = name
         self._primitive: Optional["ModelPrimitive"] = None
-        logger.debug(f"ModelHandle created for '{name}'")
+        logger.debug("ModelHandle created for '%s'", name)
 
     def predict(self, data: Any) -> Any:
         """
@@ -289,7 +301,7 @@ class ModelHandle:
             primitive: The ModelPrimitive to delegate to
         """
         self._primitive = primitive
-        logger.debug(f"ModelHandle '{self.name}' connected to primitive")
+        logger.debug("ModelHandle '%s' connected to primitive", self.name)
 
     def __repr__(self) -> str:
         connected = "connected" if self._primitive else "disconnected"
@@ -303,7 +315,7 @@ class AgentLookup:
     Injected into Lua as 'Agent'. Callable to look up agents by name.
     """
 
-    def __init__(self, registry: Dict[str, AgentHandle]):
+    def __init__(self, registry: dict[str, AgentHandle]):
         """
         Initialize with reference to the agent registry.
 
@@ -344,7 +356,7 @@ class ModelLookup:
     Injected into Lua as 'Model'. Callable to look up models by name.
     """
 
-    def __init__(self, registry: Dict[str, ModelHandle]):
+    def __init__(self, registry: dict[str, ModelHandle]):
         """
         Initialize with reference to the model registry.
 

tactus/primitives/host.py

@@ -9,9 +9,10 @@ It delegates allowlisted operations to the trusted host-side broker via the
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Dict, Optional
+from typing import Any, Optional
 
 from tactus.broker.client import BrokerClient
+from tactus.utils.asyncio_helpers import clear_closed_event_loop
 
 
 class HostPrimitive:
@@ -27,7 +28,7 @@ class HostPrimitive:
 
             self._registry = HostToolRegistry.default()
 
-    def _run_coro(self, coro):
+    def _run_coro(self, coroutine: Any) -> Any:
         """
         Run an async coroutine from Lua's synchronous context.
 
@@ -38,37 +39,38 @@ class HostPrimitive:
 
             import threading
 
-            result_container = {"value": None, "exception": None}
+            thread_result = {"value": None, "exception": None}
 
             def run_in_thread():
                 try:
-                    result_container["value"] = asyncio.run(coro)
-                except Exception as e:
-                    result_container["exception"] = e
+                    thread_result["value"] = asyncio.run(coroutine)
+                except Exception as error:
+                    thread_result["exception"] = error
 
             thread = threading.Thread(target=run_in_thread)
             thread.start()
             thread.join()
 
-            if result_container["exception"]:
-                raise result_container["exception"]
-            return result_container["value"]
+            if thread_result["exception"]:
+                raise thread_result["exception"]
+            return thread_result["value"]
 
         except RuntimeError:
-            return asyncio.run(coro)
+            clear_closed_event_loop()
+            return asyncio.run(coroutine)
 
-    def _lua_to_python(self, obj: Any) -> Any:
-        if obj is None:
+    def _lua_to_python(self, value: Any) -> Any:
+        if value is None:
             return None
-        if hasattr(obj, "items") and not isinstance(obj, dict):
-            return {k: self._lua_to_python(v) for k, v in obj.items()}
-        if isinstance(obj, dict):
-            return {k: self._lua_to_python(v) for k, v in obj.items()}
-        if isinstance(obj, (list, tuple)):
-            return [self._lua_to_python(v) for v in obj]
-        return obj
-
-    def call(self, name: str, args: Optional[Dict[str, Any]] = None) -> Any:
+        if hasattr(value, "items") and not isinstance(value, dict):
+            return {k: self._lua_to_python(v) for k, v in value.items()}
+        if isinstance(value, dict):
+            return {k: self._lua_to_python(v) for k, v in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [self._lua_to_python(v) for v in value]
+        return value
+
+    def call(self, name: str, args: Optional[dict[str, Any]] = None) -> Any:
         """
         Call an allowlisted host tool via the broker.
 
@@ -78,17 +80,17 @@ class HostPrimitive:
         if not isinstance(name, str) or not name:
             raise ValueError("Host.call requires a non-empty tool name string")
 
-        args_dict = self._lua_to_python(args) or {}
-        if not isinstance(args_dict, dict):
+        args_payload = self._lua_to_python(args) or {}
+        if not isinstance(args_payload, dict):
             raise ValueError("Host.call args must be an object/table")
 
         if self._client is not None:
-            return self._run_coro(self._client.call_tool(name=name, args=args_dict))
+            return self._run_coro(self._client.call_tool(name=name, args=args_payload))
 
         if self._registry is not None:
             try:
-                return self._registry.call(name, args_dict)
-            except KeyError as e:
-                raise RuntimeError(f"Tool not allowlisted: {name}") from e
+                return self._registry.call(name, args_payload)
+            except KeyError as error:
+                raise RuntimeError(f"Tool not allowlisted: {name}") from error
 
         raise RuntimeError("Host.call requires TACTUS_BROKER_SOCKET to be set")