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

tactus/primitives/retry.py

@@ -7,7 +7,7 @@ Provides:
 
 import logging
 import time
-from typing import Callable, Any, Optional, Dict
+from typing import Any, Callable, Optional
 
 logger = logging.getLogger(__name__)
 
@@ -27,12 +27,14 @@ class RetryPrimitive:
         """Initialize Retry primitive."""
         logger.debug("RetryPrimitive initialized")
 
-    def with_backoff(self, fn: Callable, options: Optional[Dict[str, Any]] = None) -> Any:
+    def with_backoff(
+        self, function_to_retry: Callable, options: Optional[dict[str, Any]] = None
+    ) -> Any:
         """
         Retry a function with exponential backoff.
 
         Args:
-            fn: Function to retry (Lua function)
+            function_to_retry: Function to retry (Lua function)
             options: Dict with:
                 - max_attempts: Maximum retry attempts (default: 3)
                 - initial_delay: Initial delay in seconds (default: 1)
@@ -61,58 +63,58 @@ class RetryPrimitive:
             })
         """
         # Convert Lua tables to Python dicts if needed
-        opts = self._convert_lua_to_python(options) or {}
+        options_dict = self._convert_lua_to_python(options) or {}
 
-        max_attempts = opts.get("max_attempts", 3)
-        initial_delay = opts.get("initial_delay", 1.0)
-        max_delay = opts.get("max_delay", 60.0)
-        backoff_factor = opts.get("backoff_factor", 2.0)
-        on_error = opts.get("on_error")
+        max_attempts = options_dict.get("max_attempts", 3)
+        initial_delay = options_dict.get("initial_delay", 1.0)
+        max_delay = options_dict.get("max_delay", 60.0)
+        backoff_factor = options_dict.get("backoff_factor", 2.0)
+        on_error = options_dict.get("on_error")
 
-        attempt = 0
-        delay = initial_delay
+        attempt_number = 0
+        current_delay = initial_delay
         last_error = None
 
-        logger.info(f"Starting retry with_backoff (max_attempts={max_attempts})")
+        logger.info("Starting retry with_backoff (max_attempts=%s)", max_attempts)
 
-        while attempt < max_attempts:
-            attempt += 1
+        while attempt_number < max_attempts:
+            attempt_number += 1
 
             try:
-                logger.debug(f"Retry attempt {attempt}/{max_attempts}")
-                result = fn()
-                logger.info(f"Success on attempt {attempt}/{max_attempts}")
+                logger.debug("Retry attempt %s/%s", attempt_number, max_attempts)
+                result = function_to_retry()
+                logger.info("Success on attempt %s/%s", attempt_number, max_attempts)
                 return result
 
-            except Exception as e:
-                last_error = e
-                logger.warning(f"Attempt {attempt}/{max_attempts} failed: {e}")
+            except Exception as error:
+                last_error = error
+                logger.warning("Attempt %s/%s failed: %s", attempt_number, max_attempts, error)
 
                 # Call error callback if provided
                 if on_error and callable(on_error):
                     try:
                         on_error(
                             {
-                                "attempt": attempt,
+                                "attempt": attempt_number,
                                 "max_attempts": max_attempts,
-                                "error": str(e),
-                                "delay": delay,
+                                "error": str(error),
+                                "delay": current_delay,
                             }
                         )
                     except Exception as callback_error:
-                        logger.error(f"Error callback failed: {callback_error}")
+                        logger.error("Error callback failed: %s", callback_error)
 
                 # Check if we should retry
-                if attempt >= max_attempts:
-                    logger.error(f"All {max_attempts} attempts failed")
+                if attempt_number >= max_attempts:
+                    logger.error("All %s attempts failed", max_attempts)
                     raise Exception(f"Retry failed after {max_attempts} attempts: {last_error}")
 
                 # Wait with exponential backoff
-                logger.info(f"Waiting {delay:.2f}s before retry...")
-                time.sleep(delay)
+                logger.info("Waiting %.2fs before retry...", current_delay)
+                time.sleep(current_delay)
 
                 # Increase delay for next attempt (exponential backoff)
-                delay = min(delay * backoff_factor, max_delay)
+                current_delay = min(current_delay * backoff_factor, max_delay)
 
         # Should not reach here, but handle it
         raise Exception(f"Retry logic error: {last_error}")

tactus/primitives/session.py

@@ -9,7 +9,7 @@ from typing import Any, Optional
 try:
     from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse, TextPart
 except ImportError:
-    # Fallback types if pydantic_ai not available
+    # Fallback types when pydantic_ai is not available at runtime.
     ModelMessage = dict
     ModelRequest = dict
     ModelResponse = dict
@@ -39,28 +39,54 @@ class SessionPrimitive:
         self.session_manager = session_manager
         self.agent_name = agent_name
 
-    def append(self, message_data: dict) -> None:
+    def _has_session_context(self) -> bool:
+        """
+        Return True when this primitive is bound to a session manager and agent.
+        """
+        return bool(self.session_manager and self.agent_name)
+
+    def _serialize_message(self, message: Any) -> dict[str, str]:
+        """
+        Convert a stored message into a Lua-friendly dict shape.
+        """
+        if isinstance(message, dict):
+            return {
+                "role": message.get("role", ""),
+                "content": str(message.get("content", "")),
+            }
+
+        # Handle pydantic_ai ModelMessage objects.
+        try:
+            return {
+                "role": getattr(message, "role", ""),
+                "content": str(getattr(message, "content", "")),
+            }
+        except Exception:
+            # Fallback: preserve content as a string with an unknown role.
+            return {"role": "unknown", "content": str(message)}
+
+    def append(self, message_payload: dict[str, Any]) -> None:
         """
         Append a message to the session history.
 
         Args:
-            message_data: Dict with 'role' and 'content' keys
+            message_payload: dict with 'role' and 'content' keys
                          role: 'user', 'assistant', 'system'
                          content: message text
 
         Example:
             Session.append({role = "user", content = "Hello"})
         """
-        if not self.session_manager or not self.agent_name:
+        if not self._has_session_context():
             return
 
-        role = message_data.get("role", "user")
-        content = message_data.get("content", "")
+        message_role = message_payload.get("role", "user")
+        message_content = message_payload.get("content", "")
 
         # Create a simple message dict
-        message = {"role": role, "content": content}
+        message_entry = {"role": message_role, "content": message_content}
 
-        self.session_manager.add_message(self.agent_name, message)
+        self.session_manager.add_message(self.agent_name, message_entry)
 
     def inject_system(self, text: str) -> None:
         """
@@ -84,12 +110,12 @@ class SessionPrimitive:
         Example:
             Session.clear()
         """
-        if not self.session_manager or not self.agent_name:
+        if not self._has_session_context():
             return
 
         self.session_manager.clear_agent_history(self.agent_name)
 
-    def history(self) -> list:
+    def history(self) -> list[dict[str, str]]:
         """
         Get the full conversation history for this agent.
 
@@ -102,30 +128,17 @@ class SessionPrimitive:
                 Log.info(msg.role .. ": " .. msg.content)
             end
         """
-        if not self.session_manager or not self.agent_name:
+        if not self._has_session_context():
             return []
 
         messages = self.session_manager.histories.get(self.agent_name, [])
 
         # Convert to Lua-friendly format
-        result = []
-        for msg in messages:
-            if isinstance(msg, dict):
-                result.append({"role": msg.get("role", ""), "content": str(msg.get("content", ""))})
-            else:
-                # Handle pydantic_ai ModelMessage objects
-                try:
-                    result.append(
-                        {
-                            "role": getattr(msg, "role", ""),
-                            "content": str(getattr(msg, "content", "")),
-                        }
-                    )
-                except Exception:
-                    # Fallback: convert to string
-                    result.append({"role": "unknown", "content": str(msg)})
-
-        return result
+        serialized_messages: list[dict[str, str]] = [
+            self._serialize_message(message) for message in messages
+        ]
+
+        return serialized_messages
 
     def load_from_node(self, node: Any) -> None:
         """

tactus/primitives/state.py

@@ -10,7 +10,7 @@ Provides:
 """
 
 import logging
-from typing import Any, Dict
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -23,22 +23,26 @@ class StatePrimitive:
     progress, accumulate results, and coordinate between agents.
     """
 
-    def __init__(self, state_schema: Dict[str, Any] = None):
+    def __init__(self, state_schema: dict[str, Any] | None = 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 {}
+        self._state_values: dict[str, Any] = {}
+        self._state = self._state_values
+        self._schema_definitions: 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"]
+        for state_key, schema_field_definition in self._schema_definitions.items():
+            if isinstance(schema_field_definition, dict) and "default" in schema_field_definition:
+                self._state_values[state_key] = schema_field_definition["default"]
 
-        logger.debug(f"StatePrimitive initialized with {len(self._schema)} schema fields")
+        logger.debug(
+            "StatePrimitive initialized with %s schema fields",
+            len(self._schema_definitions),
+        )
 
     def get(self, key: str, default: Any = None) -> Any:
         """
@@ -54,9 +58,9 @@ class StatePrimitive:
         Example (Lua):
             local count = State.get("hypothesis_count", 0)
         """
-        value = self._state.get(key, default)
-        logger.debug(f"State.get('{key}') = {value}")
-        return value
+        stored_value = self._state_values.get(key, default)
+        logger.debug("State.get('%s') = %s", key, stored_value)
+        return stored_value
 
     def set(self, key: str, value: Any) -> None:
         """
@@ -70,18 +74,20 @@ class StatePrimitive:
             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):
+        if key in self._schema_definitions:
+            schema_field_definition = self._schema_definitions[key]
+            if isinstance(schema_field_definition, dict) and "type" in schema_field_definition:
+                expected_type = schema_field_definition["type"]
+                if not self._is_value_matching_schema_type(value, expected_type):
                     logger.warning(
-                        f"State.set('{key}'): value type {type(value).__name__} "
-                        f"does not match schema type {expected_type}"
+                        "State.set('%s'): value type %s does not match schema type %s",
+                        key,
+                        type(value).__name__,
+                        expected_type,
                     )
 
-        self._state[key] = value
-        logger.debug(f"State.set('{key}', {value})")
+        self._state_values[key] = value
+        logger.debug("State.set('%s', %s)", key, value)
 
     def increment(self, key: str, amount: float = 1) -> float:
         """
@@ -98,17 +104,17 @@ class StatePrimitive:
             State.increment("hypotheses_filed")
             State.increment("score", 10)
         """
-        current = self._state.get(key, 0)
+        current_value = self._state_values.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
+        if not isinstance(current_value, (int, float)):
+            logger.warning("State.increment: '%s' is not numeric, resetting to 0", key)
+            current_value = 0
 
-        new_value = current + amount
-        self._state[key] = new_value
+        new_value = current_value + amount
+        self._state_values[key] = new_value
 
-        logger.debug(f"State.increment('{key}', {amount}) = {new_value}")
+        logger.debug("State.increment('%s', %s) = %s", key, amount, new_value)
         return new_value
 
     def append(self, key: str, value: Any) -> None:
@@ -122,16 +128,21 @@ class StatePrimitive:
         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]:
+        if key not in self._state_values:
+            self._state_values[key] = []
+        elif not isinstance(self._state_values[key], list):
+            logger.warning("State.append: '%s' is not a list, converting", key)
+            self._state_values[key] = [self._state_values[key]]
+
+        self._state_values[key].append(value)
+        logger.debug(
+            "State.append('%s', %s) -> list length: %s",
+            key,
+            value,
+            len(self._state_values[key]),
+        )
+
+    def all(self) -> dict[str, Any]:
         """
         Get all state as a dictionary.
 
@@ -144,15 +155,15 @@ class StatePrimitive:
                 print(k, v)
             end
         """
-        logger.debug(f"State.all() returning {len(self._state)} keys")
-        return self._state.copy()
+        logger.debug("State.all() returning %s keys", len(self._state_values))
+        return self._state_values.copy()
 
     def clear(self) -> None:
         """Clear all state (mainly for testing)."""
-        self._state.clear()
+        self._state_values.clear()
         logger.debug("State.clear() - all state cleared")
 
-    def _validate_type(self, value: Any, expected_type: str) -> bool:
+    def _is_value_matching_schema_type(self, value: Any, expected_type: str) -> bool:
         """
         Validate value against expected type from schema.
 
@@ -173,10 +184,10 @@ class StatePrimitive:
 
         expected_python_type = type_mapping.get(expected_type)
         if expected_python_type is None:
-            logger.warning(f"Unknown type in schema: {expected_type}")
+            logger.warning("Unknown type in schema: %s", expected_type)
             return True  # Allow unknown types
 
         return isinstance(value, expected_python_type)
 
     def __repr__(self) -> str:
-        return f"StatePrimitive({len(self._state)} keys)"
+        return f"StatePrimitive({len(self._state_values)} keys)"

tactus/primitives/step.py

@@ -46,7 +46,7 @@ class StepPrimitive:
         Returns:
             Result of fn() on first execution, cached result on replay
         """
-        logger.debug(f"checkpoint() at position {self.execution_context.next_position()}")
+        logger.debug("checkpoint() at position %s", self.execution_context.next_position())
 
         # Prioritize Lua source info over Python stack inspection
         if lua_source_info:
@@ -54,11 +54,7 @@ class StepPrimitive:
             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
-                    )
+                    lua_dict = dict(lua_source_info.items())
                 else:
                     # Try to convert if it's a LuaTable
                     lua_dict = dict(lua_source_info)
@@ -72,14 +68,14 @@ class StepPrimitive:
                 "line": lua_dict.get("line", 0),
                 "function": lua_dict.get("function", "unknown"),
             }
-            logger.debug(f"Using Lua source info: {source_info}")
+            logger.debug("Using Lua source info: %s", 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
+            current_frame = inspect.currentframe()
+            if current_frame and current_frame.f_back:
+                caller_frame = current_frame.f_back
                 source_info = {
                     "file": caller_frame.f_code.co_filename,
                     "line": caller_frame.f_lineno,
@@ -94,8 +90,8 @@ class StepPrimitive:
             )
             logger.debug("checkpoint() completed successfully")
             return result
-        except Exception as e:
-            logger.error(f"checkpoint() failed: {e}")
+        except Exception as error:
+            logger.error("checkpoint() failed: %s", error)
             raise
 
 
@@ -158,7 +154,7 @@ class CheckpointPrimitive:
         Example:
             Checkpoint.clear_after(3)  -- Clear checkpoint 3 and beyond
         """
-        logger.info(f"Clearing checkpoints after position {position}")
+        logger.info("Clearing checkpoints after position %s", position)
         self.execution_context.checkpoint_clear_after(position)
 
     def next_position(self) -> int:

tactus/primitives/system.py

@@ -8,7 +8,7 @@ Provides:
 from __future__ import annotations
 
 import logging
-from typing import Any, Dict, Optional
+from typing import Any, Optional
 
 logger = logging.getLogger(__name__)
 
@@ -22,19 +22,19 @@ class SystemPrimitive:
         self.procedure_id = procedure_id
         self.log_handler = log_handler
 
-    def _lua_to_python(self, obj: Any) -> Any:
+    def _lua_to_python(self, value: Any) -> Any:
         """Convert Lua objects to Python equivalents recursively."""
-        if obj is None:
+        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 alert(self, options: Optional[Dict[str, Any]] = None) -> None:
+        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 alert(self, options: Optional[dict[str, Any]] = None) -> None:
         """
         Emit a system alert (NON-BLOCKING).
 
@@ -45,12 +45,12 @@ class SystemPrimitive:
                 - source: str - Where the alert originated (optional)
                 - context: Dict - Additional structured context (optional)
         """
-        opts = self._lua_to_python(options) or {}
+        options_dict = 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 {}
+        message = str(options_dict.get("message", "Alert"))
+        level = str(options_dict.get("level", "info")).lower()
+        source = options_dict.get("source")
+        context = options_dict.get("context") or {}
 
         if level not in self._ALLOWED_LEVELS:
             raise ValueError(
@@ -71,8 +71,8 @@ class SystemPrimitive:
                 )
                 self.log_handler.log(event)
                 return
-            except Exception as e:  # pragma: no cover
-                logger.warning(f"Failed to emit SystemAlertEvent: {e}")
+            except Exception as error:  # pragma: no cover
+                logger.warning("Failed to emit SystemAlertEvent: %s", error)
 
         # Fallback to standard logging
         python_level = {
@@ -84,9 +84,22 @@ class SystemPrimitive:
 
         origin = f" source={source}" if source is not None else ""
         if context:
-            logger.log(python_level, f"System.alert [{level}]{origin}: {message} | {context}")
+            logger.log(
+                python_level,
+                "System.alert [%s]%s: %s | %s",
+                level,
+                origin,
+                message,
+                context,
+            )
         else:
-            logger.log(python_level, f"System.alert [{level}]{origin}: {message}")
+            logger.log(
+                python_level,
+                "System.alert [%s]%s: %s",
+                level,
+                origin,
+                message,
+            )
 
     def __repr__(self) -> str:
         return f"SystemPrimitive(procedure_id={self.procedure_id})"