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

tactus/primitives/json.py

@@ -60,16 +60,16 @@ class JsonPrimitive:
             # Convert Lua tables to Python dicts recursively if needed
             python_data = self._lua_to_python(data)
 
-            json_str = json.dumps(python_data, ensure_ascii=False, indent=None)
-            logger.debug(f"Encoded data to JSON ({len(json_str)} bytes)")
-            return json_str
+            json_payload = json.dumps(python_data, ensure_ascii=False, indent=None)
+            logger.debug("Encoded data to JSON (%s bytes)", len(json_payload))
+            return json_payload
 
-        except (TypeError, ValueError) as e:
-            error_msg = f"Failed to encode to JSON: {e}"
-            logger.error(error_msg)
-            raise ValueError(error_msg)
+        except (TypeError, ValueError) as error:
+            error_message = f"Failed to encode to JSON: {error}"
+            logger.error(error_message)
+            raise ValueError(error_message)
 
-    def decode(self, json_str: str):
+    def decode(self, json_str: str) -> Any:
         """
         Decode JSON string to Lua table.
 
@@ -93,7 +93,7 @@ class JsonPrimitive:
         try:
             # Parse JSON to Python dict
             python_data = json.loads(json_str)
-            logger.debug(f"Decoded JSON string ({len(json_str)} bytes)")
+            logger.debug("Decoded JSON string (%s bytes)", len(json_str))
 
             # Convert to Lua table if lua_sandbox available
             if self.lua_sandbox:
@@ -102,10 +102,10 @@ class JsonPrimitive:
                 # Fallback: return Python dict (will work but not ideal)
                 return python_data
 
-        except json.JSONDecodeError as e:
-            error_msg = f"Failed to decode JSON: {e}"
-            logger.error(error_msg)
-            raise ValueError(error_msg)
+        except json.JSONDecodeError as error:
+            error_message = f"Failed to decode JSON: {error}"
+            logger.error(error_message)
+            raise ValueError(error_message)
 
     def _lua_to_python(self, value: Any) -> Any:
         """
@@ -125,27 +125,27 @@ class JsonPrimitive:
             if lua_type(value) == "table":
                 # Try to determine if it's an array or dict
                 # Lua arrays have consecutive integer keys starting at 1
-                result = {}
+                converted = {}
                 is_array = True
                 keys = []
 
                 for k, v in value.items():
                     keys.append(k)
-                    result[k] = self._lua_to_python(v)
+                    converted[k] = self._lua_to_python(v)
                     if not isinstance(k, int) or k < 1:
                         is_array = False
 
                 # Check if keys are consecutive integers starting at 1
                 if is_array and keys:
-                    keys_sorted = sorted(keys)
-                    if keys_sorted != list(range(1, len(keys) + 1)):
+                    sorted_keys = sorted(keys)
+                    if sorted_keys != list(range(1, len(keys) + 1)):
                         is_array = False
 
                 # Convert to list if it's an array
                 if is_array and keys:
-                    return [result[i] for i in range(1, len(keys) + 1)]
+                    return [converted[i] for i in range(1, len(keys) + 1)]
                 else:
-                    return result
+                    return converted
             else:
                 # Primitive value
                 return value
@@ -174,16 +174,15 @@ class JsonPrimitive:
                 lua_table[k] = self._python_to_lua(v)
             return lua_table
 
-        elif isinstance(value, (list, tuple)):
+        if isinstance(value, (list, tuple)):
             # Convert list to Lua array (1-indexed)
             lua_table = self.lua_sandbox.lua.table()
             for i, item in enumerate(value, start=1):
                 lua_table[i] = self._python_to_lua(item)
             return lua_table
 
-        else:
-            # Primitive value (str, int, float, bool, None)
-            return value
+        # Primitive value (str, int, float, bool, None)
+        return value
 
     def __repr__(self) -> str:
         return "JsonPrimitive()"

tactus/primitives/log.py

@@ -9,9 +9,9 @@ Provides:
 """
 
 import logging
-from typing import Any, Dict, Optional, TYPE_CHECKING
+from typing import Any, Optional, TYPE_CHECKING
 
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover
     from tactus.protocols.log_handler import LogHandler
 
 logger = logging.getLogger(__name__)
@@ -38,32 +38,32 @@ class LogPrimitive:
         self.logger = logging.getLogger(f"procedure.{procedure_id}")
         self.log_handler = log_handler
 
-    def _format_message(self, message: str, context: Optional[Dict[str, Any]] = None) -> str:
+    def _format_message(self, message: str, context: Optional[dict[str, Any]] = None) -> str:
         """Format log message with context."""
         if context:
             import json
 
             # Convert Lua tables to Python dicts
-            context_dict = self._lua_to_python(context)
-            context_str = json.dumps(context_dict, indent=2)
-            return f"{message}\nContext: {context_str}"
+            context_payload = self._lua_to_python(context)
+            context_json = json.dumps(context_payload, indent=2)
+            return f"{message}\nContext: {context_json}"
         return message
 
-    def _lua_to_python(self, obj: Any) -> Any:
+    def _lua_to_python(self, value: Any) -> Any:
         """Convert Lua objects to Python equivalents recursively."""
         # Check if it's a Lua table
-        if hasattr(obj, "items"):  # Lua table with dict-like interface
-            return {self._lua_to_python(k): self._lua_to_python(v) for k, v in obj.items()}
-        elif hasattr(obj, "__iter__") and not isinstance(obj, (str, bytes)):  # Lua array
+        if hasattr(value, "items"):  # Lua table with dict-like interface
+            return {self._lua_to_python(k): self._lua_to_python(v) for k, v in value.items()}
+        elif hasattr(value, "__iter__") and not isinstance(value, (str, bytes)):  # Lua array
             try:
-                return [self._lua_to_python(v) for v in obj]
+                return [self._lua_to_python(v) for v in value]
             except Exception:  # noqa: E722
                 # If iteration fails, return as-is
-                return obj
+                return value
         else:
-            return obj
+            return value
 
-    def debug(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+    def debug(self, message: str, context: Optional[dict[str, Any]] = None) -> None:
         """
         Log debug message.
 
@@ -78,11 +78,11 @@ class LogPrimitive:
         if self.log_handler:
             from tactus.protocols.models import LogEvent
 
-            context_dict = self._lua_to_python(context) if context else None
+            context_payload = self._lua_to_python(context) if context else None
             event = LogEvent(
                 level="DEBUG",
                 message=message,
-                context=context_dict,
+                context=context_payload,
                 logger_name=self.logger.name,
                 procedure_id=self.procedure_id,
             )
@@ -92,7 +92,7 @@ class LogPrimitive:
             formatted = self._format_message(message, context)
             self.logger.debug(formatted)
 
-    def info(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+    def info(self, message: str, context: Optional[dict[str, Any]] = None) -> None:
         """
         Log info message.
 
@@ -107,11 +107,11 @@ class LogPrimitive:
         if self.log_handler:
             from tactus.protocols.models import LogEvent
 
-            context_dict = self._lua_to_python(context) if context else None
+            context_payload = self._lua_to_python(context) if context else None
             event = LogEvent(
                 level="INFO",
                 message=message,
-                context=context_dict,
+                context=context_payload,
                 logger_name=self.logger.name,
                 procedure_id=self.procedure_id,
             )
@@ -121,7 +121,7 @@ class LogPrimitive:
             formatted = self._format_message(message, context)
             self.logger.info(formatted)
 
-    def warn(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+    def warn(self, message: str, context: Optional[dict[str, Any]] = None) -> None:
         """
         Log warning message.
 
@@ -136,11 +136,11 @@ class LogPrimitive:
         if self.log_handler:
             from tactus.protocols.models import LogEvent
 
-            context_dict = self._lua_to_python(context) if context else None
+            context_payload = self._lua_to_python(context) if context else None
             event = LogEvent(
                 level="WARNING",
                 message=message,
-                context=context_dict,
+                context=context_payload,
                 logger_name=self.logger.name,
                 procedure_id=self.procedure_id,
             )
@@ -150,11 +150,11 @@ class LogPrimitive:
             formatted = self._format_message(message, context)
             self.logger.warning(formatted)
 
-    def warning(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+    def warning(self, message: str, context: Optional[dict[str, Any]] = None) -> None:
         """Alias for warn(), matching common logging APIs."""
         self.warn(message, context)
 
-    def error(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+    def error(self, message: str, context: Optional[dict[str, Any]] = None) -> None:
         """
         Log error message.
 
@@ -169,11 +169,11 @@ class LogPrimitive:
         if self.log_handler:
             from tactus.protocols.models import LogEvent
 
-            context_dict = self._lua_to_python(context) if context else None
+            context_payload = self._lua_to_python(context) if context else None
             event = LogEvent(
                 level="ERROR",
                 message=message,
-                context=context_dict,
+                context=context_payload,
                 logger_name=self.logger.name,
                 procedure_id=self.procedure_id,
             )

tactus/primitives/message_history.py

@@ -42,28 +42,31 @@ class MessageHistoryPrimitive:
         self.message_history_manager = message_history_manager
         self.agent_name = agent_name
 
-    def append(self, message_data: dict) -> None:
+    def append(self, message_payload: dict[str, Any]) -> None:
         """
         Append a message to the message 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:
             MessageHistory.append({role = "user", content = "Hello"})
         """
-        if not self.message_history_manager or not self.agent_name:
+        if not self.message_history_manager:
             return
 
-        role = message_data.get("role", "user")
-        content = message_data.get("content", "")
+        message_payload = self._normalize_message_payload(message_payload)
+        role = message_payload.get("role", "user")
+        content = message_payload.get("content", "")
 
-        # Create a simple message dict
-        message = {"role": role, "content": content}
+        # Create a message dict and preserve extra fields
+        message_entry = dict(message_payload)
+        message_entry["role"] = role
+        message_entry["content"] = content
 
-        self.message_history_manager.add_message(self.agent_name, message)
+        self.message_history_manager.add_message(self.agent_name, message_entry)
 
     def inject_system(self, text: str) -> None:
         """
@@ -87,12 +90,14 @@ class MessageHistoryPrimitive:
         Example:
             MessageHistory.clear()
         """
-        if not self.message_history_manager or not self.agent_name:
+        if not self.message_history_manager:
             return
+        if self.agent_name:
+            self.message_history_manager.clear_agent_history(self.agent_name)
+        else:
+            self.message_history_manager.clear_shared_history()
 
-        self.message_history_manager.clear_agent_history(self.agent_name)
-
-    def get(self) -> list:
+    def get(self) -> list[dict[str, Any]]:
         """
         Get the full message history for this agent.
 
@@ -107,31 +112,280 @@ class MessageHistoryPrimitive:
                 Log.info(msg.role .. ": " .. msg.content)
             end
         """
-        if not self.message_history_manager or not self.agent_name:
+        if not self.message_history_manager:
             return []
-
-        messages = self.message_history_manager.histories.get(self.agent_name, [])
+        messages = self._get_history_ref()
 
         # 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)})
+        result: list[dict[str, Any]] = []
+        for message in messages:
+            serialized_message = self._serialize_message(message)
+            result.append(serialized_message)
 
         return result
 
+    def replace(self, messages: list[Any]) -> None:
+        """
+        Replace the current message history with a new list.
+
+        Args:
+            messages: List of message dicts to set as the new history
+        """
+        if not self.message_history_manager:
+            return
+
+        normalized_messages = self._normalize_messages(messages)
+        normalized_messages = [
+            self.message_history_manager._ensure_message_metadata(message)
+            for message in normalized_messages
+        ]
+
+        if self.agent_name:
+            self.message_history_manager.histories[self.agent_name] = normalized_messages
+        else:
+            self.message_history_manager.shared_history = normalized_messages
+
+    def reset(self, options: Optional[dict[str, Any]] = None) -> None:
+        """
+        Reset history while optionally keeping leading system messages.
+
+        Args:
+            options: Optional dict with keep mode:
+                - "system_prefix" (default): keep leading system messages only
+                - "system_all": keep all system messages
+                - "none": clear all messages
+        """
+        if not self.message_history_manager:
+            return
+
+        keep_mode = "system_prefix"
+        normalized_options = self._normalize_options(options)
+        if normalized_options:
+            keep_mode = normalized_options.get("keep", keep_mode)
+        elif isinstance(options, str):
+            keep_mode = options
+
+        messages = self._get_history_ref()
+
+        if keep_mode == "none":
+            self.replace([])
+            return
+        if keep_mode == "system_all":
+            system_messages = self.message_history_manager._filter_by_role(messages, "system")
+            self.replace(system_messages)
+            return
+
+        system_prefix_messages = self.message_history_manager._filter_system_prefix(messages)
+        self.replace(system_prefix_messages)
+
+    def head(self, n: int) -> list[dict[str, Any]]:
+        """Return the first N messages without mutating history."""
+        if not self.message_history_manager:
+            return []
+        messages = self._get_history_ref()
+        limit = max(int(n or 0), 0)
+        return self._serialize_messages(messages[:limit])
+
+    def tail(self, n: int) -> list[dict[str, Any]]:
+        """Return the last N messages without mutating history."""
+        if not self.message_history_manager:
+            return []
+        messages = self._get_history_ref()
+        limit = max(int(n or 0), 0)
+        return self._serialize_messages(messages[-limit:] if limit > 0 else [])
+
+    def slice(self, options: dict[str, Any]) -> list[dict[str, Any]]:
+        """Return a slice of messages using 1-based start/stop indices."""
+        if not self.message_history_manager:
+            return []
+        normalized_options = self._normalize_options(options)
+        if not normalized_options:
+            return []
+        messages = self._get_history_ref()
+        start = normalized_options.get("start")
+        stop = normalized_options.get("stop")
+        start_index = max(int(start or 1) - 1, 0)
+        stop_index = int(stop) if stop is not None else None
+        sliced = messages[start_index:stop_index]
+        return self._serialize_messages(sliced)
+
+    def tail_tokens(
+        self, max_tokens: int, options: Optional[dict[str, Any]] = None
+    ) -> list[dict[str, Any]]:
+        """Return the last messages that fit within the token budget."""
+        if not self.message_history_manager:
+            return []
+        messages = self._get_history_ref()
+        token_filtered_messages = self.message_history_manager._filter_tail_tokens(
+            messages, max_tokens
+        )
+        return self._serialize_messages(token_filtered_messages)
+
+    def keep_head(self, n: int) -> None:
+        """Keep only the first N messages."""
+        if not self.message_history_manager:
+            return
+        messages = self._get_history_ref()
+        limit = max(int(n or 0), 0)
+        self.replace(messages[:limit])
+
+    def keep_tail(self, n: int) -> None:
+        """Keep only the last N messages."""
+        if not self.message_history_manager:
+            return
+        messages = self._get_history_ref()
+        limit = max(int(n or 0), 0)
+        self.replace(messages[-limit:] if limit > 0 else [])
+
+    def keep_tail_tokens(self, max_tokens: int, options: Optional[dict[str, Any]] = None) -> None:
+        """Keep only the last messages that fit within the token budget."""
+        if not self.message_history_manager:
+            return
+        messages = self._get_history_ref()
+        token_filtered_messages = self.message_history_manager._filter_tail_tokens(
+            messages, max_tokens
+        )
+        self.replace(token_filtered_messages)
+
+    def rewind(self, n: int) -> None:
+        """Remove the last N messages from history."""
+        if not self.message_history_manager:
+            return
+        messages = self._get_history_ref()
+        count = max(int(n or 0), 0)
+        if count <= 0:
+            return
+        self.replace(messages[:-count])
+
+    def rewind_to(self, message_id: Any) -> None:
+        """Rewind history back to a message id or checkpoint name."""
+        if not self.message_history_manager:
+            return
+
+        target_message_id = message_id
+        if isinstance(message_id, str):
+            checkpoint_id = self.message_history_manager.get_checkpoint(message_id)
+            target_message_id = checkpoint_id if checkpoint_id is not None else message_id
+
+        try:
+            target_message_id = int(target_message_id)
+        except (TypeError, ValueError):
+            return
+
+        messages = self._get_history_ref()
+        for index, message in enumerate(messages):
+            message_id_value = (
+                message.get("id") if isinstance(message, dict) else getattr(message, "id", None)
+            )
+            if message_id_value == target_message_id:
+                self.replace(messages[: index + 1])
+                return
+
+    def checkpoint(self, name: Optional[str] = None) -> Optional[int]:
+        """Return the id of the last message and optionally store a named checkpoint."""
+        if not self.message_history_manager:
+            return None
+
+        messages = self._get_history_ref()
+        if not messages:
+            return None
+
+        last_message = messages[-1]
+        if isinstance(last_message, dict):
+            last_message = self.message_history_manager._ensure_message_metadata(last_message)
+            message_id = last_message.get("id")
+        else:
+            message_id = getattr(last_message, "id", None)
+
+        if isinstance(name, str) and message_id is not None:
+            self.message_history_manager.record_checkpoint(name, message_id)
+
+        return message_id
+
+    def _get_history_ref(self) -> list[Any]:
+        """Get a direct reference to the underlying history list."""
+        if not self.message_history_manager:
+            return []
+        if self.agent_name:
+            return self.message_history_manager.histories.setdefault(self.agent_name, [])
+        return self.message_history_manager.shared_history
+
+    def _serialize_messages(self, messages: list[Any]) -> list[dict[str, Any]]:
+        """Serialize message objects to Lua-friendly dicts."""
+        result: list[dict[str, Any]] = []
+        for message in messages:
+            result.append(self._serialize_message(message))
+        return result
+
+    def _normalize_messages(self, messages: Any) -> list[Any]:
+        """Normalize Python lists or Lua tables into a list of message dicts."""
+        if messages is None:
+            return []
+        if isinstance(messages, list):
+            return messages
+        if isinstance(messages, tuple):
+            return list(messages)
+        if hasattr(messages, "items"):
+            items = list(messages.items())
+            if items and all(isinstance(key, int) for key, _ in items):
+                items.sort(key=lambda pair: pair[0])
+            return [value for _, value in items]
+        return list(messages)
+
+    def _normalize_message_payload(self, message_payload: Any) -> dict[str, Any]:
+        """Normalize a single message payload into a dict."""
+        if message_payload is None:
+            return {}
+        if isinstance(message_payload, dict):
+            return message_payload
+        if hasattr(message_payload, "items"):
+            try:
+                return dict(message_payload.items())
+            except Exception:
+                pass
+        return {"role": "user", "content": str(message_payload)}
+
+    def _normalize_message_data(self, message_data: Any) -> dict[str, Any]:
+        """Compatibility alias for existing tests and external callers."""
+        return self._normalize_message_payload(message_data)
+
+    def _normalize_options(self, options: Any) -> dict[str, Any]:
+        """Normalize options from Lua tables or dicts."""
+        if options is None:
+            return {}
+        if isinstance(options, dict):
+            return options
+        if hasattr(options, "items"):
+            try:
+                return dict(options.items())
+            except Exception:
+                return {}
+        return {}
+
+    def _serialize_message(self, message: Any) -> dict[str, Any]:
+        """Serialize a single message into a Lua-friendly dict."""
+        if isinstance(message, dict):
+            message = self.message_history_manager._ensure_message_metadata(message)
+            serialized = dict(message)
+            serialized["role"] = str(serialized.get("role", ""))
+            serialized["content"] = str(serialized.get("content", ""))
+            return serialized
+
+        # Handle pydantic_ai ModelMessage objects
+        try:
+            serialized = {"role": getattr(message, "role", "")}
+            serialized["content"] = str(getattr(message, "content", ""))
+            message_id = getattr(message, "id", None)
+            if message_id is not None:
+                serialized["id"] = message_id
+            created_at = getattr(message, "created_at", None)
+            if created_at is not None:
+                serialized["created_at"] = created_at
+            return serialized
+        except Exception:
+            # Fallback: convert to string
+            return {"role": "unknown", "content": str(message)}
+
     def load_from_node(self, node: Any) -> None:
         """
         Load message history from a graph node.

tactus/primitives/model.py

@@ -74,7 +74,7 @@ class ModelPrimitive:
                 headers=config.get("headers"),
             )
 
-        elif model_type == "pytorch":
+        if model_type == "pytorch":
             from tactus.backends.pytorch_backend import PyTorchModelBackend
 
             return PyTorchModelBackend(
@@ -83,8 +83,7 @@ class ModelPrimitive:
                 labels=config.get("labels"),
             )
 
-        else:
-            raise ValueError(f"Unknown model type: {model_type}. Supported types: http, pytorch")
+        raise ValueError(f"Unknown model type: {model_type}. Supported types: http, pytorch")
 
     def predict(self, input_data: Any) -> Any:
         """
@@ -104,9 +103,9 @@ class ModelPrimitive:
         # Capture source location
         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,
@@ -132,12 +131,19 @@ class ModelPrimitive:
             Model prediction result
         """
         if self.mock_manager is not None:
-            args = input_data if isinstance(input_data, dict) else {"input": input_data}
-            mock_result = self.mock_manager.get_mock_response(self.model_name, args)
+            args_payload = input_data if isinstance(input_data, dict) else {"input": input_data}
+            mock_result = self.mock_manager.get_mock_response(
+                self.model_name,
+                args_payload,
+            )
             if mock_result is not None:
                 # Ensure temporal mocks advance and calls are available for assertions.
                 try:
-                    self.mock_manager.record_call(self.model_name, args, mock_result)
+                    self.mock_manager.record_call(
+                        self.model_name,
+                        args_payload,
+                        mock_result,
+                    )
                 except Exception:
                     pass
                 return mock_result