tactus 0.31.2__py3-none-any.whl

tactus/primitives/__init__.py

@@ -0,0 +1,49 @@
+"""
+Tactus primitives - Lua-callable Python objects.
+
+These primitives are injected into the Lua sandbox and provide
+the core functionality for workflow execution.
+"""
+
+from tactus.primitives.state import StatePrimitive
+from tactus.primitives.control import IterationsPrimitive, StopPrimitive
+from tactus.primitives.tool import ToolPrimitive
+from tactus.primitives.log import LogPrimitive
+from tactus.primitives.step import StepPrimitive, CheckpointPrimitive
+from tactus.primitives.json import JsonPrimitive
+from tactus.primitives.retry import RetryPrimitive
+from tactus.primitives.file import FilePrimitive
+
+from tactus.primitives.human import HumanPrimitive
+from tactus.primitives.system import SystemPrimitive
+from tactus.primitives.host import HostPrimitive
+
+# MessageHistory primitive is now available
+from tactus.primitives.message_history import MessageHistoryPrimitive
+
+# NOTE: AgentPrimitive and ResultPrimitive have been replaced by DSPy implementation
+# Agent functionality is now provided by tactus.dspy.agent
+
+# These will be imported when their dependencies are ready
+# from tactus.primitives.system import SystemPrimitive
+# from tactus.primitives.procedure import ProcedurePrimitive
+# from tactus.primitives.graph import GraphNodePrimitive
+
+__all__ = [
+    "StatePrimitive",
+    "IterationsPrimitive",
+    "StopPrimitive",
+    "ToolPrimitive",
+    "HumanPrimitive",
+    "LogPrimitive",
+    "StepPrimitive",
+    "CheckpointPrimitive",
+    "MessageHistoryPrimitive",
+    "JsonPrimitive",
+    "RetryPrimitive",
+    "FilePrimitive",
+    "SystemPrimitive",
+    "HostPrimitive",
+    # "AgentPrimitive",  # Replaced by DSPy implementation
+    # "ResultPrimitive",  # Replaced by DSPy implementation
+]

tactus/primitives/control.py

@@ -0,0 +1,168 @@
+"""
+Control Primitives - Flow control and termination.
+
+Provides:
+- Iterations.current() - Get current iteration number
+- Iterations.exceeded(max) - Check if exceeded max iterations
+- Stop.requested() - Check if stop was requested
+- Stop.reason() - Get stop reason
+- Stop.success() - Check if stop was successful
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class IterationsPrimitive:
+    """
+    Tracks iteration count for procedure execution.
+
+    Provides safety limits and iteration-based control flow.
+    """
+
+    def __init__(self):
+        """Initialize iteration counter."""
+        self._current_iteration = 0
+        logger.debug("IterationsPrimitive initialized")
+
+    def current(self) -> int:
+        """
+        Get the current iteration number.
+
+        Returns:
+            Current iteration count (0-indexed)
+
+        Example (Lua):
+            local iter = Iterations.current()
+            Log.info("Iteration: " .. iter)
+        """
+        return self._current_iteration
+
+    def exceeded(self, max_iterations: int) -> bool:
+        """
+        Check if current iteration has exceeded the maximum.
+
+        Args:
+            max_iterations: Maximum allowed iterations
+
+        Returns:
+            True if current iteration >= max_iterations
+
+        Example (Lua):
+            if Iterations.exceeded(100) then
+                return {success = false, reason = "Max iterations exceeded"}
+            end
+        """
+        exceeded = self._current_iteration >= max_iterations
+        if exceeded:
+            logger.warning(f"Iterations exceeded: {self._current_iteration} >= {max_iterations}")
+        return exceeded
+
+    def increment(self) -> int:
+        """
+        Increment the iteration counter.
+
+        Returns:
+            New iteration count
+
+        Note: This is called internally by the runtime, not from Lua
+        """
+        self._current_iteration += 1
+        logger.debug(f"Iteration incremented to {self._current_iteration}")
+        return self._current_iteration
+
+    def reset(self) -> None:
+        """Reset iteration counter (mainly for testing)."""
+        self._current_iteration = 0
+        logger.debug("Iterations reset to 0")
+
+    def __repr__(self) -> str:
+        return f"IterationsPrimitive(current={self._current_iteration})"
+
+
+class StopPrimitive:
+    """
+    Manages procedure termination state.
+
+    Tracks when a stop was requested and the reason/success status.
+    """
+
+    def __init__(self):
+        """Initialize stop state."""
+        self._requested = False
+        self._reason: Optional[str] = None
+        self._success = True
+        logger.debug("StopPrimitive initialized")
+
+    def requested(self) -> bool:
+        """
+        Check if a stop was requested.
+
+        Returns:
+            True if stop was requested
+
+        Example (Lua):
+            if Stop.requested() then
+                return {success = true, message = "Procedure stopped"}
+            end
+        """
+        return self._requested
+
+    def reason(self) -> Optional[str]:
+        """
+        Get the reason for stopping.
+
+        Returns:
+            Stop reason string or None if not stopped
+
+        Example (Lua):
+            if Stop.requested() then
+                Log.info("Stopped because: " .. Stop.reason())
+            end
+        """
+        return self._reason
+
+    def success(self) -> bool:
+        """
+        Check if the stop was due to successful completion.
+
+        Returns:
+            True if stopped successfully, False if stopped due to error
+
+        Example (Lua):
+            if Stop.requested() and Stop.success() then
+                return {success = true}
+            else
+                return {success = false}
+            end
+        """
+        return self._success
+
+    def request(self, reason: str, success: bool = True) -> None:
+        """
+        Request a stop (called by tools or runtime).
+
+        Args:
+            reason: Reason for stopping
+            success: Whether this is a successful completion
+
+        Note: This is called internally, not from Lua
+        """
+        self._requested = True
+        self._reason = reason
+        self._success = success
+
+        log_level = logging.INFO if success else logging.WARNING
+        logger.log(log_level, f"Stop requested: {reason} (success={success})")
+
+    def reset(self) -> None:
+        """Reset stop state (mainly for testing)."""
+        self._requested = False
+        self._reason = None
+        self._success = True
+        logger.debug("Stop state reset")
+
+    def __repr__(self) -> str:
+        return f"StopPrimitive(requested={self._requested}, success={self._success})"

tactus/primitives/file.py

@@ -0,0 +1,229 @@
+"""
+File Primitive - File I/O operations for workflows.
+
+Provides:
+- File.read(path) - Read file contents
+- File.write(path, content) - Write content to file
+- File.exists(path) - Check if file exists
+- File.size(path) - Get file size in bytes
+"""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class FilePrimitive:
+    """
+    Handles file operations for procedures.
+
+    Enables workflows to:
+    - Read file contents
+    - Write data to files
+    - Check file existence
+    - Get file metadata
+
+    Note: File operations are non-deterministic (files can change between executions).
+    Wrap in Step.checkpoint() for durability.
+    """
+
+    def __init__(self, base_path: Optional[str] = None, execution_context=None):
+        """
+        Initialize File primitive.
+
+        Args:
+            base_path: Optional base directory for relative paths (defaults to cwd)
+            execution_context: Optional ExecutionContext for determinism checking
+        """
+        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}")
+
+    def _check_determinism(self, operation: str):
+        """Warn if file operation called outside checkpoint."""
+        if self.execution_context and not getattr(
+            self.execution_context, "_inside_checkpoint", False
+        ):
+            import warnings
+
+            warnings.warn(
+                f"\n{'=' * 70}\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"    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",
+                UserWarning,
+                stacklevel=3,
+            )
+
+    def read(self, path: str) -> str:
+        """
+        Read file contents as string.
+
+        Args:
+            path: File path to read (absolute or relative to base_path)
+
+        Returns:
+            File contents as string
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            IOError: If file cannot be read
+
+        Example (Lua):
+            local config = File.read("config.json")
+            Log.info("Config loaded", {length = #config})
+        """
+        self._check_determinism("read")
+        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}")
+            return content
+
+        except FileNotFoundError:
+            error_msg = f"File not found: {file_path}"
+            logger.error(error_msg)
+            raise FileNotFoundError(error_msg)
+
+        except Exception as e:
+            error_msg = f"Failed to read file {file_path}: {e}"
+            logger.error(error_msg)
+            raise IOError(error_msg)
+
+    def write(self, path: str, content: str) -> bool:
+        """
+        Write content to file.
+
+        Args:
+            path: File path to write (absolute or relative to base_path)
+            content: Content to write
+
+        Returns:
+            True if successful
+
+        Raises:
+            IOError: If file cannot be written
+
+        Example (Lua):
+            local data = Json.encode({status = "complete"})
+            File.write("output.json", data)
+            Log.info("Data written")
+        """
+        self._check_determinism("write")
+        file_path = self._resolve_path(path)
+
+        try:
+            # 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.info(f"Wrote {len(content)} bytes to {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)
+
+    def exists(self, path: str) -> bool:
+        """
+        Check if file exists.
+
+        Args:
+            path: File path to check (absolute or relative to base_path)
+
+        Returns:
+            True if file exists, False otherwise
+
+        Example (Lua):
+            if File.exists("cache.json") then
+                local data = File.read("cache.json")
+                Log.info("Using cached data")
+            else
+                Log.info("No cache found")
+            end
+        """
+        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
+
+    def size(self, path: str) -> int:
+        """
+        Get file size in bytes.
+
+        Args:
+            path: File path to check (absolute or relative to base_path)
+
+        Returns:
+            File size in bytes
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+
+        Example (Lua):
+            local size = File.size("data.csv")
+            Log.info("File size", {bytes = size, kb = size / 1024})
+        """
+        self._check_determinism("size")
+        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)
+
+        size = file_path.stat().st_size
+        logger.debug(f"File size for {file_path}: {size} bytes")
+        return size
+
+    def _resolve_path(self, path: str) -> Path:
+        """
+        Resolve file path relative to base_path with security validation.
+
+        Args:
+            path: File path to resolve (must be relative)
+
+        Returns:
+            Resolved Path object
+
+        Raises:
+            ValueError: If absolute path or path traversal detected
+        """
+        path_obj = Path(path)
+
+        # Security: Never allow absolute paths
+        if path_obj.is_absolute():
+            raise ValueError(f"Absolute paths not allowed: {path}")
+
+        # Resolve relative to base_path
+        resolved = (self.base_path / path_obj).resolve()
+
+        # Security: Verify resolved path is under base_path
+        try:
+            resolved.relative_to(self.base_path)
+        except ValueError:
+            raise ValueError(f"Path traversal detected: {path} resolves outside base directory")
+
+        return resolved
+
+    def __repr__(self) -> str:
+        return f"FilePrimitive(base_path={self.base_path})"