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

tactus/core/lua_sandbox.py

@@ -12,7 +12,7 @@ Provides a sandboxed Lua runtime with:
 
 import logging
 import os
-from typing import Dict, Any, Optional
+from typing import Any, Optional
 
 try:
     import lupa
@@ -59,10 +59,13 @@ class LuaSandbox:
         # Fix base_path at initialization time to prevent security boundary expansion
         # This ensures file I/O libraries and require() always use the same base path,
         # even if the working directory changes later
-        self.base_path = base_path if base_path else os.getcwd()
+        self.base_path = base_path or os.getcwd()
 
         # Create Lua runtime with safety restrictions
-        self.lua = LuaRuntime(unpack_returned_tuples=True, attribute_filter=self._attribute_filter)
+        self.lua = LuaRuntime(
+            unpack_returned_tuples=True,
+            attribute_filter=self._attribute_filter,
+        )
 
         # Remove dangerous modules
         self._remove_dangerous_modules()
@@ -75,7 +78,7 @@ class LuaSandbox:
 
         logger.debug("Lua sandbox initialized successfully")
 
-    def _attribute_filter(self, obj, attr_name, is_setting):
+    def _attribute_filter(self, obj: Any, attr_name: str, is_setting: bool) -> str:
         """
         Filter attribute access to prevent dangerous operations.
 
@@ -86,7 +89,7 @@ class LuaSandbox:
             raise AttributeError(f"Access to private attribute '{attr_name}' is not allowed")
 
         # Block access to certain dangerous methods
-        blocked_methods = {
+        blocked_attributes = {
             "__import__",
             "__loader__",
             "__spec__",
@@ -98,12 +101,12 @@ class LuaSandbox:
             "__subclasses__",
         }
 
-        if attr_name in blocked_methods:
+        if attr_name in blocked_attributes:
             raise AttributeError(f"Access to '{attr_name}' is not allowed in sandbox")
 
         return attr_name
 
-    def _remove_dangerous_modules(self):
+    def _remove_dangerous_modules(self) -> None:
         """Remove dangerous Lua standard library modules."""
         # Remove modules that provide file system or system access
         # Note: 'package' and 'require' are kept but restricted in _setup_safe_require()
@@ -125,17 +128,19 @@ class LuaSandbox:
         # Whitelist only safe debug functions for source location tracking
         # Keep debug.getinfo but remove dangerous debug functions
         if "debug" in lua_globals:
-            self.lua.execute("""
+            self.lua.execute(
+                """
                 if debug then
                     local safe_debug = {
                         getinfo = debug.getinfo
                     }
                     debug = safe_debug
                 end
-            """)
+                """
+            )
             logger.debug("Replaced debug module with safe_debug (only getinfo allowed)")
 
-    def _setup_safe_require(self):
+    def _setup_safe_require(self) -> None:
         """Configure require/package to search user's project and stdlib.
 
         This allows using Lua's require() mechanism while restricting module
@@ -157,17 +162,22 @@ class LuaSandbox:
         # 1. User's project directory (existing behavior)
         # 2. Tactus stdlib .tac files
         # Both single-file modules (?.tac) and directory modules (?/init.tac) are supported
-        user_path = os.path.join(self.base_path, "?.tac")
+        user_module_path = os.path.join(self.base_path, "?.tac")
         user_init_path = os.path.join(self.base_path, "?", "init.tac")
-        stdlib_path = os.path.join(stdlib_tac_path, "?.tac")
+        stdlib_module_path = os.path.join(stdlib_tac_path, "?.tac")
         stdlib_init_path = os.path.join(stdlib_tac_path, "?", "init.tac")
 
         # Normalize backslashes for cross-platform compatibility
-        paths = [user_path, user_init_path, stdlib_path, stdlib_init_path]
-        paths = [p.replace("\\", "/") for p in paths]
+        raw_paths = [
+            user_module_path,
+            user_init_path,
+            stdlib_module_path,
+            stdlib_init_path,
+        ]
+        normalized_paths = [path.replace("\\", "/") for path in raw_paths]
 
         # Join with Lua's path separator (semicolon)
-        safe_path = ";".join(paths)
+        safe_path = ";".join(normalized_paths)
 
         lua_globals = self.lua.globals()
         package = lua_globals["package"]
@@ -186,11 +196,11 @@ class LuaSandbox:
             # Add Python stdlib loader
             self._setup_python_stdlib_loader()
 
-            logger.debug(f"Configured safe require with paths: {safe_path}")
+            logger.debug("Configured safe require with paths: %s", safe_path)
         else:
             logger.warning("package module not available - require will not work")
 
-    def _setup_python_stdlib_loader(self):
+    def _setup_python_stdlib_loader(self) -> None:
         """Add custom loader for Python stdlib modules."""
         from tactus.stdlib.loader import StdlibModuleLoader
 
@@ -203,7 +213,8 @@ class LuaSandbox:
 
         # Add to package.loaders (Lua 5.1) or package.searchers (Lua 5.2+)
         # Lupa uses LuaJIT which follows Lua 5.1 conventions
-        self.lua.execute("""
+        self.lua.execute(
+            """
             -- Add Python stdlib loader to package.loaders
             -- Insert after the preload loader but before path loader
             local loaders = package.loaders or package.searchers
@@ -221,11 +232,12 @@ class LuaSandbox:
                 -- Insert at position 2 (after preload, before path)
                 table.insert(loaders, 2, python_searcher)
             end
-        """)
+            """
+        )
 
         logger.debug("Python stdlib loader installed")
 
-    def _setup_safe_globals(self):
+    def _setup_safe_globals(self) -> None:
         """Setup safe global functions and utilities."""
         # Keep safe standard library functions
         # (These are already available by default, just documenting them)
@@ -252,7 +264,7 @@ class LuaSandbox:
         }
 
         # Just log what's available - no need to explicitly set
-        logger.debug(f"Safe Lua functions available: {', '.join(safe_functions)}")
+        logger.debug("Safe Lua functions available: %s", ", ".join(safe_functions))
 
         # Replace math and os libraries with safe versions if context available
         if self.execution_context is not None:
@@ -301,7 +313,7 @@ class LuaSandbox:
         self.lua.globals()["os"] = safe_os
         logger.debug("Added safe os.date() function")
 
-    def setup_assignment_interception(self, callback: Any):
+    def setup_assignment_interception(self, callback: Any) -> None:
         """
         Setup assignment interception on global scope to capture variable definitions.
 
@@ -337,11 +349,15 @@ class LuaSandbox:
         try:
             self.lua.execute(lua_code)
             logger.debug("Assignment interception enabled with metatable on _G")
-        except Exception as e:
-            logger.error(f"Failed to setup assignment interception: {e}", exc_info=True)
-            raise LuaSandboxError(f"Could not setup assignment interception: {e}")
+        except Exception as exception:
+            logger.error(
+                "Failed to setup assignment interception: %s",
+                exception,
+                exc_info=True,
+            )
+            raise LuaSandboxError(f"Could not setup assignment interception: {exception}")
 
-    def set_execution_context(self, context: Any):
+    def set_execution_context(self, context: Any) -> None:
         """
         Set or update execution context and refresh safe libraries.
 
@@ -353,7 +369,7 @@ class LuaSandbox:
         self._setup_safe_globals()
         logger.debug("ExecutionContext attached to LuaSandbox")
 
-    def inject_primitive(self, name: str, primitive_obj: Any):
+    def inject_primitive(self, name: str, primitive_obj: Any) -> None:
         """
         Inject a Python primitive object into Lua globals.
 
@@ -362,9 +378,9 @@ class LuaSandbox:
             primitive_obj: Python object to expose to Lua
         """
         self.lua.globals()[name] = primitive_obj
-        logger.debug(f"Injected primitive '{name}' into Lua sandbox")
+        logger.debug("Injected primitive '%s' into Lua sandbox", name)
 
-    def set_global(self, name: str, value: Any):
+    def set_global(self, name: str, value: Any) -> None:
         """
         Set a global variable in Lua.
 
@@ -372,28 +388,20 @@ class LuaSandbox:
             name: Name of the global variable
             value: Value to set (can be Python object, dict, etc.)
         """
-        # Convert Python dicts to Lua tables if needed
+        self.lua.globals()[name] = self._convert_python_value_to_lua(value)
+        logger.debug("Set global '%s' in Lua sandbox", name)
+
+    def _convert_python_value_to_lua(self, value: Any) -> Any:
+        """Convert Python values to Lua-friendly values."""
         if isinstance(value, dict):
-            lua_table = self.lua.table()
-            for k, v in value.items():
-                if isinstance(v, dict):
-                    # Recursively convert nested dicts
-                    lua_table[k] = self._dict_to_lua_table(v)
-                else:
-                    lua_table[k] = v
-            self.lua.globals()[name] = lua_table
-        else:
-            self.lua.globals()[name] = value
-        logger.debug(f"Set global '{name}' in Lua sandbox")
+            return self._dict_to_lua_table(value)
+        return value
 
-    def _dict_to_lua_table(self, d: dict):
+    def _dict_to_lua_table(self, python_dict: dict) -> Any:
         """Convert Python dict to Lua table recursively."""
         lua_table = self.lua.table()
-        for k, v in d.items():
-            if isinstance(v, dict):
-                lua_table[k] = self._dict_to_lua_table(v)
-            else:
-                lua_table[k] = v
+        for key, value in python_dict.items():
+            lua_table[key] = self._convert_python_value_to_lua(value)
         return lua_table
 
     def execute(self, lua_code: str) -> Any:
@@ -410,21 +418,21 @@ class LuaSandbox:
             LuaSandboxError: If execution fails
         """
         try:
-            logger.debug(f"Executing Lua code ({len(lua_code)} bytes)")
+            logger.debug("Executing Lua code (%s bytes)", len(lua_code))
             result = self.lua.execute(lua_code)
             logger.debug("Lua execution completed successfully")
             return result
 
-        except lupa.LuaError as e:
+        except lupa.LuaError as exception:
             # Lua runtime error
-            error_msg = str(e)
-            logger.error(f"Lua execution error: {error_msg}")
-            raise LuaSandboxError(f"Lua runtime error: {error_msg}")
+            error_message = str(exception)
+            logger.error("Lua execution error: %s", error_message)
+            raise LuaSandboxError(f"Lua runtime error: {error_message}")
 
-        except Exception as e:
+        except Exception as exception:
             # Other Python exceptions
-            logger.error(f"Sandbox execution error: {e}")
-            raise LuaSandboxError(f"Sandbox error: {e}")
+            logger.error("Sandbox execution error: %s", exception)
+            raise LuaSandboxError(f"Sandbox error: {exception}")
 
     def eval(self, lua_expression: str) -> Any:
         """
@@ -443,16 +451,16 @@ class LuaSandbox:
             result = self.lua.eval(lua_expression)
             return result
 
-        except lupa.LuaError as e:
-            error_msg = str(e)
-            logger.error(f"Lua eval error: {error_msg}")
-            raise LuaSandboxError(f"Lua eval error: {error_msg}")
+        except lupa.LuaError as exception:
+            error_message = str(exception)
+            logger.error("Lua eval error: %s", error_message)
+            raise LuaSandboxError(f"Lua eval error: {error_message}")
 
     def get_global(self, name: str) -> Any:
         """Get a value from Lua global scope."""
         return self.lua.globals()[name]
 
-    def create_lua_table(self, python_dict: Optional[Dict[str, Any]] = None) -> Any:
+    def create_lua_table(self, python_dict: Optional[dict[str, Any]] = None) -> Any:
         """
         Create a Lua table from a Python dictionary.
 
@@ -469,11 +477,11 @@ class LuaSandbox:
         # Create and populate Lua table
         lua_table = self.lua.table()
         for key, value in python_dict.items():
-            lua_table[key] = value
+            lua_table[key] = self._convert_python_value_to_lua(value)
 
         return lua_table
 
-    def lua_table_to_dict(self, lua_table: Any) -> Dict[str, Any]:
+    def lua_table_to_dict(self, lua_table: Any) -> dict[str, Any]:
         """
         Convert a Lua table to a Python dictionary.
 
@@ -495,8 +503,8 @@ class LuaSandbox:
                 else:
                     result[key] = value
 
-        except Exception as e:
-            logger.warning(f"Error converting Lua table to dict: {e}")
+        except Exception as exception:
+            logger.warning("Error converting Lua table to dict: %s", exception)
             # Fallback: try direct iteration
             try:
                 for key in lua_table:

tactus/core/message_history_manager.py

@@ -7,6 +7,7 @@ token budgets, message limits, and custom filters.
 Aligned with pydantic-ai's message_history concept.
 """
 
+from datetime import datetime, timezone
 from typing import Any, Optional
 
 try:
@@ -29,6 +30,8 @@ class MessageHistoryManager:
         """Initialize message history manager."""
         self.histories: dict[str, list[ModelMessage]] = {}
         self.shared_history: list[ModelMessage] = []
+        self._next_message_id = 1
+        self._checkpoints: dict[str, int] = {}
 
     def get_history_for_agent(
         self,
@@ -56,22 +59,24 @@ class MessageHistoryManager:
 
         # Determine source
         if message_history_config.source == "own":
-            messages = self.histories.get(agent_name, [])
+            selected_messages = self.histories.get(agent_name, [])
         elif message_history_config.source == "shared":
-            messages = self.shared_history
+            selected_messages = self.shared_history
         else:
             # Another agent's history
-            messages = self.histories.get(message_history_config.source, [])
+            selected_messages = self.histories.get(message_history_config.source, [])
 
         # Apply filter if specified
         if message_history_config.filter:
-            messages = self._apply_filter(messages, message_history_config.filter, context)
+            selected_messages = self._apply_filter(
+                selected_messages, message_history_config.filter, context
+            )
 
-        return messages
+        return selected_messages
 
     def add_message(
         self,
-        agent_name: str,
+        agent_name: Optional[str],
         message: ModelMessage,
         also_shared: bool = False,
     ) -> None:
@@ -83,6 +88,12 @@ class MessageHistoryManager:
             message: Message to add
             also_shared: Also add to shared history
         """
+        message = self._ensure_message_metadata(message)
+
+        if agent_name is None:
+            self.shared_history.append(message)
+            return
+
         if agent_name not in self.histories:
             self.histories[agent_name] = []
 
@@ -102,7 +113,7 @@ class MessageHistoryManager:
     def _apply_filter(
         self,
         messages: list[ModelMessage],
-        filter_spec: Any,
+        filter_specification: Any,
         context: Optional[Any],
     ) -> list[ModelMessage]:
         """
@@ -117,33 +128,41 @@ class MessageHistoryManager:
             Filtered messages
         """
         # If it's a callable (Lua function), call it
-        if callable(filter_spec):
+        if callable(filter_specification):
             try:
-                return filter_spec(messages, context)
-            except Exception as e:
+                return filter_specification(messages, context)
+            except Exception as exception:
                 # If filter fails, return unfiltered
-                print(f"Warning: Filter function failed: {e}")
+                print(f"Warning: Filter function failed: {exception}")
                 return messages
 
         # Otherwise it's a tuple (filter_type, filter_arg)
-        if not isinstance(filter_spec, tuple) or len(filter_spec) < 2:
+        if not isinstance(filter_specification, tuple) or len(filter_specification) < 2:
             return messages
 
-        filter_type = filter_spec[0]
-        filter_arg = filter_spec[1]
-
-        if filter_type == "last_n":
-            return self._filter_last_n(messages, filter_arg)
-        elif filter_type == "token_budget":
-            return self._filter_by_token_budget(messages, filter_arg)
-        elif filter_type == "by_role":
-            return self._filter_by_role(messages, filter_arg)
-        elif filter_type == "compose":
+        filter_name = filter_specification[0]
+        filter_value = filter_specification[1]
+
+        if filter_name == "last_n":
+            return self._filter_last_n(messages, filter_value)
+        elif filter_name == "first_n":
+            return self._filter_first_n(messages, filter_value)
+        elif filter_name == "token_budget":
+            return self._filter_by_token_budget(messages, filter_value)
+        elif filter_name == "head_tokens":
+            return self._filter_head_tokens(messages, filter_value)
+        elif filter_name == "tail_tokens":
+            return self._filter_tail_tokens(messages, filter_value)
+        elif filter_name == "by_role":
+            return self._filter_by_role(messages, filter_value)
+        elif filter_name == "system_prefix":
+            return self._filter_system_prefix(messages)
+        elif filter_name == "compose":
             # Apply multiple filters in sequence
-            result = messages
-            for f in filter_arg:
-                result = self._apply_filter(result, f, context)
-            return result
+            filtered_messages = messages
+            for filter_step in filter_value:
+                filtered_messages = self._apply_filter(filtered_messages, filter_step, context)
+            return filtered_messages
         else:
             # Unknown filter type, return unfiltered
             return messages
@@ -156,6 +175,14 @@ class MessageHistoryManager:
         """Keep only the last N messages."""
         return messages[-n:] if n > 0 else []
 
+    def _filter_first_n(
+        self,
+        messages: list[ModelMessage],
+        n: int,
+    ) -> list[ModelMessage]:
+        """Keep only the first N messages."""
+        return messages[:n] if n > 0 else []
+
     def _filter_by_token_budget(
         self,
         messages: list[ModelMessage],
@@ -173,22 +200,52 @@ class MessageHistoryManager:
         # Rough estimate: 4 chars per token
         max_chars = max_tokens * 4
 
-        result = []
-        current_chars = 0
+        filtered_messages = []
+        current_character_count = 0
 
         # Work backwards from most recent
         for message in reversed(messages):
             # Estimate message size
-            message_chars = self._estimate_message_chars(message)
+            message_character_count = self._estimate_message_chars(message)
 
-            if current_chars + message_chars > max_chars:
+            if current_character_count + message_character_count > max_chars:
                 # Would exceed budget, stop here
                 break
 
-            result.insert(0, message)
-            current_chars += message_chars
+            filtered_messages.insert(0, message)
+            current_character_count += message_character_count
 
-        return result
+        return filtered_messages
+
+    def _filter_head_tokens(
+        self,
+        messages: list[ModelMessage],
+        max_tokens: int,
+    ) -> list[ModelMessage]:
+        """Keep earliest messages that fit within the token budget."""
+        if max_tokens <= 0:
+            return []
+
+        max_chars = max_tokens * 4
+        filtered_messages = []
+        current_character_count = 0
+
+        for message in messages:
+            message_character_count = self._estimate_message_chars(message)
+            if current_character_count + message_character_count > max_chars:
+                break
+            filtered_messages.append(message)
+            current_character_count += message_character_count
+
+        return filtered_messages
+
+    def _filter_tail_tokens(
+        self,
+        messages: list[ModelMessage],
+        max_tokens: int,
+    ) -> list[ModelMessage]:
+        """Keep latest messages that fit within the token budget."""
+        return self._filter_by_token_budget(messages, max_tokens)
 
     def _filter_by_role(
         self,
@@ -198,23 +255,61 @@ class MessageHistoryManager:
         """Keep only messages with specified role."""
         return [m for m in messages if self._get_message_role(m) == role]
 
+    def _filter_system_prefix(
+        self,
+        messages: list[ModelMessage],
+    ) -> list[ModelMessage]:
+        """Keep only the leading contiguous system messages."""
+        system_prefix_messages: list[ModelMessage] = []
+        for message in messages:
+            if self._get_message_role(message) != "system":
+                break
+            system_prefix_messages.append(message)
+        return system_prefix_messages
+
+    def _ensure_message_metadata(self, message: ModelMessage) -> ModelMessage:
+        """Ensure message has id and created_at metadata when dict-based."""
+        if not isinstance(message, dict):
+            return message
+
+        if "id" not in message:
+            message["id"] = self._next_message_id
+            self._next_message_id += 1
+
+        if "created_at" not in message:
+            message["created_at"] = datetime.now(timezone.utc).isoformat()
+
+        return message
+
+    def record_checkpoint(self, name: str, message_id: int) -> None:
+        """Record a named checkpoint pointing at a message id."""
+        self._checkpoints[name] = message_id
+
+    def get_checkpoint(self, name: str) -> Optional[int]:
+        """Retrieve a checkpoint id by name."""
+        return self._checkpoints.get(name)
+
+    def next_message_id(self) -> int:
+        """Return the next message id that will be assigned."""
+        return self._next_message_id
+
     def _estimate_message_chars(self, message: ModelMessage) -> int:
         """Estimate character count of a message."""
         if isinstance(message, dict):
             # Dict-based message
-            content = message.get("content", "")
-            if isinstance(content, str):
-                return len(content)
-            elif isinstance(content, list):
+            message_content = message.get("content", "")
+            if isinstance(message_content, str):
+                return len(message_content)
+            elif isinstance(message_content, list):
                 # Multiple content parts
-                total = 0
-                for part in content:
+                total_character_count = 0
+                for part in message_content:
                     if isinstance(part, dict):
-                        total += len(str(part.get("text", "")))
+                        total_character_count += len(str(part.get("text", "")))
                     else:
-                        total += len(str(part))
-                return total
-            return len(str(content))
+                        total_character_count += len(str(part))
+                return total_character_count
+            return len(str(message_content))
         else:
             # Pydantic AI ModelMessage object
             try: