tactus 0.31.0__py3-none-any.whl

tactus/core/message_history_manager.py

@@ -0,0 +1,236 @@
+"""
+Message history management for per-agent conversation histories.
+
+Manages conversation histories with filtering capabilities for
+token budgets, message limits, and custom filters.
+
+Aligned with pydantic-ai's message_history concept.
+"""
+
+from typing import Any, Optional
+
+try:
+    from pydantic_ai.messages import ModelMessage
+except ImportError:
+    # Fallback if pydantic_ai not available
+    ModelMessage = dict
+
+from .registry import MessageHistoryConfiguration
+
+
+class MessageHistoryManager:
+    """Manages per-agent message histories with filtering.
+
+    Aligned with pydantic-ai's message_history concept - this manager
+    maintains the message_history lists that get passed to agent.run_sync().
+    """
+
+    def __init__(self):
+        """Initialize message history manager."""
+        self.histories: dict[str, list[ModelMessage]] = {}
+        self.shared_history: list[ModelMessage] = []
+
+    def get_history_for_agent(
+        self,
+        agent_name: str,
+        message_history_config: Optional[MessageHistoryConfiguration] = None,
+        context: Optional[Any] = None,
+    ) -> list[ModelMessage]:
+        """
+        Get filtered message history for an agent.
+
+        This returns the message_history list that will be passed to
+        pydantic-ai's agent.run_sync(message_history=...).
+
+        Args:
+            agent_name: Name of the agent
+            message_history_config: Message history configuration (source, filter)
+            context: Runtime context for filter functions
+
+        Returns:
+            List of messages for the agent (message_history for pydantic-ai)
+        """
+        if message_history_config is None:
+            # Default: own history, no filter
+            return self.histories.get(agent_name, [])
+
+        # Determine source
+        if message_history_config.source == "own":
+            messages = self.histories.get(agent_name, [])
+        elif message_history_config.source == "shared":
+            messages = self.shared_history
+        else:
+            # Another agent's history
+            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)
+
+        return messages
+
+    def add_message(
+        self,
+        agent_name: str,
+        message: ModelMessage,
+        also_shared: bool = False,
+    ) -> None:
+        """
+        Add a message to an agent's history.
+
+        Args:
+            agent_name: Name of the agent
+            message: Message to add
+            also_shared: Also add to shared history
+        """
+        if agent_name not in self.histories:
+            self.histories[agent_name] = []
+
+        self.histories[agent_name].append(message)
+
+        if also_shared:
+            self.shared_history.append(message)
+
+    def clear_agent_history(self, agent_name: str) -> None:
+        """Clear an agent's history."""
+        self.histories[agent_name] = []
+
+    def clear_shared_history(self) -> None:
+        """Clear shared history."""
+        self.shared_history = []
+
+    def _apply_filter(
+        self,
+        messages: list[ModelMessage],
+        filter_spec: Any,
+        context: Optional[Any],
+    ) -> list[ModelMessage]:
+        """
+        Apply declarative or function filter.
+
+        Args:
+            messages: Messages to filter
+            filter_spec: Filter specification (tuple or callable)
+            context: Runtime context
+
+        Returns:
+            Filtered messages
+        """
+        # If it's a callable (Lua function), call it
+        if callable(filter_spec):
+            try:
+                return filter_spec(messages, context)
+            except Exception as e:
+                # If filter fails, return unfiltered
+                print(f"Warning: Filter function failed: {e}")
+                return messages
+
+        # Otherwise it's a tuple (filter_type, filter_arg)
+        if not isinstance(filter_spec, tuple) or len(filter_spec) < 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":
+            # Apply multiple filters in sequence
+            result = messages
+            for f in filter_arg:
+                result = self._apply_filter(result, f, context)
+            return result
+        else:
+            # Unknown filter type, return unfiltered
+            return messages
+
+    def _filter_last_n(
+        self,
+        messages: list[ModelMessage],
+        n: int,
+    ) -> list[ModelMessage]:
+        """Keep only the last N messages."""
+        return messages[-n:] if n > 0 else []
+
+    def _filter_by_token_budget(
+        self,
+        messages: list[ModelMessage],
+        max_tokens: int,
+    ) -> list[ModelMessage]:
+        """
+        Filter messages to stay within token budget.
+
+        Uses a simple heuristic: ~4 characters per token.
+        Keeps most recent messages that fit within budget.
+        """
+        if max_tokens <= 0:
+            return []
+
+        # Rough estimate: 4 chars per token
+        max_chars = max_tokens * 4
+
+        result = []
+        current_chars = 0
+
+        # Work backwards from most recent
+        for message in reversed(messages):
+            # Estimate message size
+            message_chars = self._estimate_message_chars(message)
+
+            if current_chars + message_chars > max_chars:
+                # Would exceed budget, stop here
+                break
+
+            result.insert(0, message)
+            current_chars += message_chars
+
+        return result
+
+    def _filter_by_role(
+        self,
+        messages: list[ModelMessage],
+        role: str,
+    ) -> list[ModelMessage]:
+        """Keep only messages with specified role."""
+        return [m for m in messages if self._get_message_role(m) == role]
+
+    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):
+                # Multiple content parts
+                total = 0
+                for part in content:
+                    if isinstance(part, dict):
+                        total += len(str(part.get("text", "")))
+                    else:
+                        total += len(str(part))
+                return total
+            return len(str(content))
+        else:
+            # Pydantic AI ModelMessage object
+            try:
+                # Try to access content attribute
+                content = getattr(message, "content", "")
+                return len(str(content))
+            except Exception:
+                # Fallback: convert to string
+                return len(str(message))
+
+    def _get_message_role(self, message: ModelMessage) -> str:
+        """Get role from a message."""
+        if isinstance(message, dict):
+            return message.get("role", "")
+        else:
+            try:
+                return getattr(message, "role", "")
+            except Exception:
+                return ""

tactus/core/mocking.py

@@ -0,0 +1,286 @@
+"""
+Mocking infrastructure for Tactus.
+
+Provides comprehensive mocking capabilities including:
+- Static mocks (always return same value)
+- Temporal mocks (different returns per call)
+- Conditional mocks (based on input parameters)
+- Mock state tracking and assertions
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Union
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MockCall:
+    """Record of a mock tool call."""
+
+    tool_name: str
+    args: Dict[str, Any]
+    result: Any
+    call_number: int
+    timestamp: float
+
+
+@dataclass
+class MockConfig:
+    """Configuration for a mocked tool."""
+
+    tool_name: str
+
+    # Static mock - always returns this
+    static_result: Optional[Any] = None
+
+    # Temporal mocks - return different values per call
+    temporal_results: List[Any] = field(default_factory=list)
+
+    # Conditional mocks - return based on args
+    conditional_mocks: List[Dict[str, Any]] = field(default_factory=list)
+
+    # Error simulation
+    error: Optional[str] = None
+
+    # Whether this mock is enabled
+    enabled: bool = True
+
+
+class MockManager:
+    """
+    Manages mock state and temporal mocking for testing.
+
+    This is injected into the runtime to intercept tool calls
+    and return mock responses when configured.
+    """
+
+    def __init__(self):
+        """Initialize mock manager."""
+        self.mocks: Dict[str, MockConfig] = {}
+        self.call_history: Dict[str, List[MockCall]] = {}
+        self.call_counts: Dict[str, int] = {}
+        self.enabled = True  # Global mock enable/disable
+
+    def register_mock(self, tool_name: str, config: Union[MockConfig, Dict[str, Any]]) -> None:
+        """
+        Register a mock configuration for a tool.
+
+        Args:
+            tool_name: Name of the tool to mock
+            config: MockConfig or dict with mock settings
+        """
+        if isinstance(config, dict):
+            # Convert dict to MockConfig
+            if "output" in config:
+                # Simple static mock
+                mock_config = MockConfig(tool_name=tool_name, static_result=config["output"])
+            elif "error" in config:
+                # Error simulation
+                mock_config = MockConfig(tool_name=tool_name, error=config["error"])
+            elif "temporal" in config:
+                # Temporal mocking
+                mock_config = MockConfig(tool_name=tool_name, temporal_results=config["temporal"])
+            else:
+                # Full config
+                mock_config = MockConfig(tool_name=tool_name, **config)
+        else:
+            mock_config = config
+
+        self.mocks[tool_name] = mock_config
+        logger.info(f"Registered mock for tool '{tool_name}'")
+
+    def get_mock_response(self, tool_name: str, args: Dict[str, Any]) -> Optional[Any]:
+        """
+        Get mock response for a tool call.
+
+        Args:
+            tool_name: Name of the tool being called
+            args: Arguments passed to the tool
+
+        Returns:
+            Mock response if configured, None if tool should run normally
+        """
+        if not self.enabled:
+            return None
+
+        if tool_name not in self.mocks:
+            return None
+
+        mock_config = self.mocks[tool_name]
+        if not mock_config.enabled:
+            return None
+
+        # Get call number for this tool
+        call_number = self.call_counts.get(tool_name, 0) + 1
+
+        # Check for error simulation
+        if mock_config.error:
+            raise RuntimeError(mock_config.error)
+
+        # Check temporal mocks first
+        if mock_config.temporal_results:
+            # Return based on call number (1-indexed)
+            if call_number <= len(mock_config.temporal_results):
+                result = mock_config.temporal_results[call_number - 1]
+                logger.debug(
+                    f"Mock '{tool_name}' returning temporal result for call {call_number}: {result}"
+                )
+                return result
+            else:
+                # Fallback to last result if we've exceeded temporal results
+                result = mock_config.temporal_results[-1]
+                logger.debug(
+                    f"Mock '{tool_name}' returning last temporal result (call {call_number}): {result}"
+                )
+                return result
+
+        # Check conditional mocks
+        for conditional in mock_config.conditional_mocks:
+            condition = conditional.get("when", {})
+            if self._matches_condition(args, condition):
+                result = conditional.get("return")
+                logger.debug(f"Mock '{tool_name}' matched condition, returning: {result}")
+                return result
+
+        # Return static result if configured
+        if mock_config.static_result is not None:
+            logger.debug(f"Mock '{tool_name}' returning static result: {mock_config.static_result}")
+            return mock_config.static_result
+
+        # No mock response configured
+        return None
+
+    def record_call(self, tool_name: str, args: Dict[str, Any], result: Any) -> None:
+        """
+        Record a tool call for assertions.
+
+        Args:
+            tool_name: Name of the tool that was called
+            args: Arguments passed to the tool
+            result: Result returned by the tool (or mock)
+        """
+        import time
+
+        # Update call count
+        self.call_counts[tool_name] = self.call_counts.get(tool_name, 0) + 1
+
+        # Create call record
+        call = MockCall(
+            tool_name=tool_name,
+            args=args,
+            result=result,
+            call_number=self.call_counts[tool_name],
+            timestamp=time.time(),
+        )
+
+        # Add to history
+        if tool_name not in self.call_history:
+            self.call_history[tool_name] = []
+        self.call_history[tool_name].append(call)
+
+        logger.debug(f"Recorded call to '{tool_name}' (call #{call.call_number})")
+
+    def get_call_count(self, tool_name: str) -> int:
+        """
+        Get the number of times a tool was called.
+
+        Args:
+            tool_name: Name of the tool
+
+        Returns:
+            Number of calls to the tool
+        """
+        return self.call_counts.get(tool_name, 0)
+
+    def get_call_history(self, tool_name: str) -> List[MockCall]:
+        """
+        Get the call history for a tool.
+
+        Args:
+            tool_name: Name of the tool
+
+        Returns:
+            List of MockCall records
+        """
+        return self.call_history.get(tool_name, [])
+
+    def reset(self) -> None:
+        """Reset all mock state."""
+        self.call_history.clear()
+        self.call_counts.clear()
+        logger.debug("Mock manager state reset")
+
+    def _matches_condition(self, args: Dict[str, Any], condition: Dict[str, Any]) -> bool:
+        """
+        Check if args match a condition.
+
+        Args:
+            args: Tool arguments to check
+            condition: Condition dict with patterns to match
+
+        Returns:
+            True if condition matches
+        """
+        for key, pattern in condition.items():
+            if key not in args:
+                return False
+
+            arg_value = args[key]
+
+            # Handle different pattern types
+            if isinstance(pattern, str):
+                # Check for operators
+                if pattern.startswith("contains:"):
+                    substring = pattern[9:].strip()
+                    if substring not in str(arg_value):
+                        return False
+                elif pattern.startswith("startswith:"):
+                    prefix = pattern[11:].strip()
+                    if not str(arg_value).startswith(prefix):
+                        return False
+                elif pattern.startswith("endswith:"):
+                    suffix = pattern[9:].strip()
+                    if not str(arg_value).endswith(suffix):
+                        return False
+                else:
+                    # Exact match
+                    if arg_value != pattern:
+                        return False
+            else:
+                # Direct comparison
+                if arg_value != pattern:
+                    return False
+
+        return True
+
+    def enable_mock(self, tool_name: Optional[str] = None) -> None:
+        """
+        Enable mocking for a specific tool or all tools.
+
+        Args:
+            tool_name: Specific tool to enable, or None for all
+        """
+        if tool_name:
+            if tool_name in self.mocks:
+                self.mocks[tool_name].enabled = True
+                logger.info(f"Enabled mock for tool '{tool_name}'")
+        else:
+            self.enabled = True
+            logger.info("Enabled all mocks")
+
+    def disable_mock(self, tool_name: Optional[str] = None) -> None:
+        """
+        Disable mocking for a specific tool or all tools.
+
+        Args:
+            tool_name: Specific tool to disable, or None for all
+        """
+        if tool_name:
+            if tool_name in self.mocks:
+                self.mocks[tool_name].enabled = False
+                logger.info(f"Disabled mock for tool '{tool_name}'")
+        else:
+            self.enabled = False
+            logger.info("Disabled all mocks")