tactus 0.31.0__py3-none-any.whl

tactus/primitives/state.py

@@ -0,0 +1,182 @@
+"""
+State Primitive - Mutable state management for procedures.
+
+Provides:
+- State.get(key, default) - Get state value
+- State.set(key, value) - Set state value
+- State.increment(key, amount) - Increment numeric value
+- State.append(key, value) - Append to list
+- State.all() - Get all state as table
+"""
+
+import logging
+from typing import Any, Dict
+
+logger = logging.getLogger(__name__)
+
+
+class StatePrimitive:
+    """
+    Manages mutable state for procedure execution.
+
+    State is preserved across agent turns and can be used to track
+    progress, accumulate results, and coordinate between agents.
+    """
+
+    def __init__(self, state_schema: Dict[str, Any] = None):
+        """
+        Initialize state storage.
+
+        Args:
+            state_schema: Optional state schema with field definitions and defaults
+        """
+        self._state: Dict[str, Any] = {}
+        self._schema: Dict[str, Any] = state_schema or {}
+
+        # Initialize state with defaults from schema
+        for key, field_def in self._schema.items():
+            if isinstance(field_def, dict) and "default" in field_def:
+                self._state[key] = field_def["default"]
+
+        logger.debug(f"StatePrimitive initialized with {len(self._schema)} schema fields")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get a value from state.
+
+        Args:
+            key: State key to retrieve
+            default: Default value if key not found
+
+        Returns:
+            Stored value or default
+
+        Example (Lua):
+            local count = State.get("hypothesis_count", 0)
+        """
+        value = self._state.get(key, default)
+        logger.debug(f"State.get('{key}') = {value}")
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        """
+        Set a value in state.
+
+        Args:
+            key: State key to set
+            value: Value to store
+
+        Example (Lua):
+            State.set("current_phase", "exploration")
+        """
+        # Validate against schema if present
+        if key in self._schema:
+            field_def = self._schema[key]
+            if isinstance(field_def, dict) and "type" in field_def:
+                expected_type = field_def["type"]
+                if not self._validate_type(value, expected_type):
+                    logger.warning(
+                        f"State.set('{key}'): value type {type(value).__name__} "
+                        f"does not match schema type {expected_type}"
+                    )
+
+        self._state[key] = value
+        logger.debug(f"State.set('{key}', {value})")
+
+    def increment(self, key: str, amount: float = 1) -> float:
+        """
+        Increment a numeric value in state.
+
+        Args:
+            key: State key to increment
+            amount: Amount to increment by (default 1)
+
+        Returns:
+            New value after increment
+
+        Example (Lua):
+            State.increment("hypotheses_filed")
+            State.increment("score", 10)
+        """
+        current = self._state.get(key, 0)
+
+        # Ensure numeric
+        if not isinstance(current, (int, float)):
+            logger.warning(f"State.increment: '{key}' is not numeric, resetting to 0")
+            current = 0
+
+        new_value = current + amount
+        self._state[key] = new_value
+
+        logger.debug(f"State.increment('{key}', {amount}) = {new_value}")
+        return new_value
+
+    def append(self, key: str, value: Any) -> None:
+        """
+        Append a value to a list in state.
+
+        Args:
+            key: State key (will be created as list if doesn't exist)
+            value: Value to append
+
+        Example (Lua):
+            State.append("nodes_created", node_id)
+        """
+        if key not in self._state:
+            self._state[key] = []
+        elif not isinstance(self._state[key], list):
+            logger.warning(f"State.append: '{key}' is not a list, converting")
+            self._state[key] = [self._state[key]]
+
+        self._state[key].append(value)
+        logger.debug(f"State.append('{key}', {value}) -> list length: {len(self._state[key])}")
+
+    def all(self) -> Dict[str, Any]:
+        """
+        Get all state as a dictionary.
+
+        Returns:
+            Complete state dictionary
+
+        Example (Lua):
+            local state = State.all()
+            for k, v in pairs(state) do
+                print(k, v)
+            end
+        """
+        logger.debug(f"State.all() returning {len(self._state)} keys")
+        return self._state.copy()
+
+    def clear(self) -> None:
+        """Clear all state (mainly for testing)."""
+        self._state.clear()
+        logger.debug("State.clear() - all state cleared")
+
+    def _validate_type(self, value: Any, expected_type: str) -> bool:
+        """
+        Validate value against expected type from schema.
+
+        Args:
+            value: Value to validate
+            expected_type: Expected type string (string, number, boolean, array, object)
+
+        Returns:
+            True if value matches expected type, False otherwise
+        """
+        type_mapping = {
+            "string": str,
+            "number": (int, float),
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+        }
+
+        expected_python_type = type_mapping.get(expected_type)
+        if expected_python_type is None:
+            logger.warning(f"Unknown type in schema: {expected_type}")
+            return True  # Allow unknown types
+
+        return isinstance(value, expected_python_type)
+
+    def __repr__(self) -> str:
+        return f"StatePrimitive({len(self._state)} keys)"

tactus/primitives/step.py

@@ -0,0 +1,209 @@
+"""
+Step primitive for checkpointed operations.
+
+Provides checkpoint() for creating explicit checkpoints in procedures.
+"""
+
+from typing import Any, Callable
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class StepPrimitive:
+    """
+    Step primitive for checkpointing operations.
+
+    Example usage:
+        local metrics = checkpoint(function()
+            return some_evaluation_function({
+                model_id = input.model_id,
+                version = "champion"
+            })
+        end)
+
+    On first execution: runs the function and caches result at current position
+    On replay: returns cached result from execution log
+    """
+
+    def __init__(self, execution_context):
+        """
+        Initialize Step primitive.
+
+        Args:
+            execution_context: ExecutionContext instance for checkpoint operations
+        """
+        self.execution_context = execution_context
+
+    def checkpoint(self, fn: Callable[[], Any], lua_source_info=None) -> Any:
+        """
+        Execute function with position-based checkpointing.
+
+        Args:
+            fn: Function to execute (must be deterministic)
+            lua_source_info: Optional dict with Lua source location {file, line, function}
+
+        Returns:
+            Result of fn() on first execution, cached result on replay
+        """
+        logger.debug(f"checkpoint() at position {self.execution_context.next_position()}")
+
+        # Prioritize Lua source info over Python stack inspection
+        if lua_source_info:
+            # Convert Lua table to dict if needed (lupa might pass a LuaTable object)
+            try:
+                if hasattr(lua_source_info, "items"):
+                    # It's already dict-like
+                    lua_dict = (
+                        dict(lua_source_info.items())
+                        if hasattr(lua_source_info, "items")
+                        else lua_source_info
+                    )
+                else:
+                    # Try to convert if it's a LuaTable
+                    lua_dict = dict(lua_source_info)
+            except Exception:
+                # Fallback - treat as dict
+                lua_dict = lua_source_info if isinstance(lua_source_info, dict) else {}
+
+            # Use source info from Lua debug.getinfo
+            source_info = {
+                "file": self.execution_context.current_tac_file or lua_dict.get("file", "unknown"),
+                "line": lua_dict.get("line", 0),
+                "function": lua_dict.get("function", "unknown"),
+            }
+            logger.debug(f"Using Lua source info: {source_info}")
+        else:
+            # Fallback to Python stack inspection (for backward compatibility)
+            import inspect
+
+            frame = inspect.currentframe()
+            if frame and frame.f_back:
+                caller_frame = frame.f_back
+                source_info = {
+                    "file": caller_frame.f_code.co_filename,
+                    "line": caller_frame.f_lineno,
+                    "function": caller_frame.f_code.co_name,
+                }
+            else:
+                source_info = None
+
+        try:
+            result = self.execution_context.checkpoint(
+                fn, "explicit_checkpoint", source_info=source_info
+            )
+            logger.debug("checkpoint() completed successfully")
+            return result
+        except Exception as e:
+            logger.error(f"checkpoint() failed: {e}")
+            raise
+
+
+class CheckpointPrimitive:
+    """
+    Checkpoint management primitive.
+
+    Provides checkpoint clearing operations for testing.
+    """
+
+    def __init__(self, execution_context):
+        """
+        Initialize Checkpoint primitive.
+
+        Args:
+            execution_context: ExecutionContext instance
+        """
+        self.execution_context = execution_context
+
+    def _coerce_position(self, position: Any) -> int:
+        """
+        Coerce a Lua/Python value into a checkpoint position (int).
+
+        Lua commonly passes numbers as int/float and may pass strings; accept both.
+        """
+        if isinstance(position, bool):
+            raise TypeError("Checkpoint position must be a number (bool is not allowed)")
+
+        if isinstance(position, int):
+            return position
+
+        if isinstance(position, float) and position.is_integer():
+            return int(position)
+
+        if isinstance(position, str):
+            stripped = position.strip()
+            if stripped.isdigit() or (stripped.startswith("-") and stripped[1:].isdigit()):
+                return int(stripped)
+            raise TypeError(f"Checkpoint position must be an integer (got string {position!r})")
+
+        raise TypeError(f"Checkpoint position must be an integer (got {type(position).__name__})")
+
+    def clear_all(self) -> None:
+        """
+        Clear all checkpoints. Restarts procedure from beginning.
+
+        Example:
+            Checkpoint.clear_all()
+        """
+        logger.info("Clearing all checkpoints")
+        self.execution_context.checkpoint_clear_all()
+
+    def clear_after(self, position: int) -> None:
+        """
+        Clear checkpoint at position and all subsequent ones.
+
+        Args:
+            position: Checkpoint position to clear from
+
+        Example:
+            Checkpoint.clear_after(3)  -- Clear checkpoint 3 and beyond
+        """
+        logger.info(f"Clearing checkpoints after position {position}")
+        self.execution_context.checkpoint_clear_after(position)
+
+    def next_position(self) -> int:
+        """
+        Get the next checkpoint position.
+
+        Returns:
+            Next position in execution log
+
+        Example:
+            local pos = Checkpoint.next_position()
+            print("Next checkpoint will be at position: " .. pos)
+        """
+        return self.execution_context.next_position()
+
+    def exists(self, position: Any) -> bool:
+        """
+        Check if a checkpoint exists at the given position.
+
+        Args:
+            position: Checkpoint position (0-indexed)
+
+        Returns:
+            True if an entry exists at that position, else False
+        """
+        coerced = self._coerce_position(position)
+        metadata = getattr(self.execution_context, "metadata", None)
+        if metadata is None or not hasattr(metadata, "execution_log"):
+            raise RuntimeError("ExecutionContext does not expose checkpoint metadata")
+        return 0 <= coerced < len(metadata.execution_log)
+
+    def get(self, position: Any) -> Any:
+        """
+        Get the cached value from a checkpoint without advancing replay.
+
+        Args:
+            position: Checkpoint position (0-indexed)
+
+        Returns:
+            Cached result at that position, or None (Lua nil) if not present
+        """
+        coerced = self._coerce_position(position)
+        metadata = getattr(self.execution_context, "metadata", None)
+        if metadata is None or not hasattr(metadata, "execution_log"):
+            raise RuntimeError("ExecutionContext does not expose checkpoint metadata")
+        if coerced < 0 or coerced >= len(metadata.execution_log):
+            return None
+        return metadata.execution_log[coerced].result

tactus/primitives/system.py

@@ -0,0 +1,93 @@
+"""
+System Primitive - non-blocking operational alerts.
+
+Provides:
+- System.alert(opts) - Emit structured alert event (non-blocking)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+
+logger = logging.getLogger(__name__)
+
+
+class SystemPrimitive:
+    """System-level primitives that are safe to call from anywhere."""
+
+    _ALLOWED_LEVELS = {"info", "warning", "error", "critical"}
+
+    def __init__(self, procedure_id: Optional[str] = None, log_handler: Any = None):
+        self.procedure_id = procedure_id
+        self.log_handler = log_handler
+
+    def _lua_to_python(self, obj: Any) -> Any:
+        """Convert Lua objects to Python equivalents recursively."""
+        if obj 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 alert(self, options: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Emit a system alert (NON-BLOCKING).
+
+        Args:
+            options: Dict with:
+                - message: str - Alert message (required)
+                - level: str - info, warning, error, critical (default: info)
+                - source: str - Where the alert originated (optional)
+                - context: Dict - Additional structured context (optional)
+        """
+        opts = self._lua_to_python(options) or {}
+
+        message = str(opts.get("message", "Alert"))
+        level = str(opts.get("level", "info")).lower()
+        source = opts.get("source")
+        context = opts.get("context") or {}
+
+        if level not in self._ALLOWED_LEVELS:
+            raise ValueError(
+                f"Invalid alert level '{level}'. Allowed levels: {sorted(self._ALLOWED_LEVELS)}"
+            )
+
+        # Emit structured event if possible (preferred for CLI/IDE)
+        if self.log_handler:
+            try:
+                from tactus.protocols.models import SystemAlertEvent
+
+                event = SystemAlertEvent(
+                    level=level,
+                    message=message,
+                    source=str(source) if source is not None else None,
+                    context=context if isinstance(context, dict) else {"context": context},
+                    procedure_id=self.procedure_id,
+                )
+                self.log_handler.log(event)
+                return
+            except Exception as e:  # pragma: no cover
+                logger.warning(f"Failed to emit SystemAlertEvent: {e}")
+
+        # Fallback to standard logging
+        python_level = {
+            "info": logging.INFO,
+            "warning": logging.WARNING,
+            "error": logging.ERROR,
+            "critical": logging.CRITICAL,
+        }[level]
+
+        origin = f" source={source}" if source is not None else ""
+        if context:
+            logger.log(python_level, f"System.alert [{level}]{origin}: {message} | {context}")
+        else:
+            logger.log(python_level, f"System.alert [{level}]{origin}: {message}")
+
+    def __repr__(self) -> str:
+        return f"SystemPrimitive(procedure_id={self.procedure_id})"