chuk-ai-session-manager 0.7.1__py3-none-any.whl → 0.8.1__py3-none-any.whl

chuk_ai_session_manager/exceptions.py

@@ -2,64 +2,75 @@
 """
 Exception classes for the chuk session manager.
 
-This module defines the exception hierarchy used throughout the 
+This module defines the exception hierarchy used throughout the
 session manager to provide specific, informative error conditions
 for various failure modes.
 """
 
+
 class SessionManagerError(Exception):
     """
     Base exception for all session manager errors.
-    
+
     All other session manager exceptions inherit from this class,
     making it easy to catch all session-related errors with a single
     except clause if needed.
     """
+
     pass
 
 
 class SessionNotFound(SessionManagerError):
     """
     Raised when the requested session ID is not found in storage.
-    
+
     This exception is typically raised when:
     - Attempting to retrieve a session with an invalid ID
     - Accessing a session that has been deleted
     - Using an ID that does not conform to expected format
     """
+
     def __init__(self, session_id=None, message=None):
         self.session_id = session_id
-        default_message = f"Session not found: {session_id}" if session_id else "Session not found"
+        default_message = (
+            f"Session not found: {session_id}" if session_id else "Session not found"
+        )
         super().__init__(message or default_message)
 
 
 class SessionAlreadyExists(SessionManagerError):
     """
     Raised when attempting to create a session with an ID that already exists.
-    
+
     This exception is typically raised during session creation when:
     - Explicitly setting an ID that conflicts with an existing session
     - A UUID collision occurs (extremely rare)
     """
+
     def __init__(self, session_id=None, message=None):
         self.session_id = session_id
-        default_message = f"Session already exists: {session_id}" if session_id else "Session already exists"
+        default_message = (
+            f"Session already exists: {session_id}"
+            if session_id
+            else "Session already exists"
+        )
         super().__init__(message or default_message)
 
 
 class InvalidSessionOperation(SessionManagerError):
     """
     Raised when attempting an invalid operation on a session.
-    
+
     This exception is typically raised when:
     - Performing operations on a closed or archived session
     - Adding events with incorrect sequencing or relationships
     - Attempting unsupported operations in the current session state
     """
+
     def __init__(self, operation=None, reason=None, message=None):
         self.operation = operation
         self.reason = reason
-        
+
         if message:
             default_message = message
         elif operation and reason:
@@ -68,55 +79,58 @@ class InvalidSessionOperation(SessionManagerError):
             default_message = f"Invalid operation: {operation}"
         else:
             default_message = "Invalid session operation"
-            
+
         super().__init__(default_message)
 
 
 class TokenLimitExceeded(SessionManagerError):
     """
     Raised when a token limit is exceeded in a session operation.
-    
+
     This exception is typically raised when:
     - Adding content that would exceed configured token limits
     - Attempting to generate a prompt that exceeds model token limits
     """
+
     def __init__(self, limit=None, actual=None, message=None):
         self.limit = limit
         self.actual = actual
-        
+
         if message:
             default_message = message
         elif limit and actual:
             default_message = f"Token limit exceeded: {actual} > {limit}"
         else:
             default_message = "Token limit exceeded"
-            
+
         super().__init__(default_message)
 
 
 class StorageError(SessionManagerError):
     """
     Raised when a session storage operation fails.
-    
+
     This is a base class for more specific storage errors.
     It can be raised directly for general storage failures.
     """
+
     pass
 
 
 class ToolProcessingError(SessionManagerError):
     """
     Raised when tool processing fails in a session.
-    
+
     This exception is typically raised when:
     - A tool execution fails after all retries
     - Invalid tool parameters are provided
     - Tool results cannot be properly processed
     """
+
     def __init__(self, tool_name=None, reason=None, message=None):
         self.tool_name = tool_name
         self.reason = reason
-        
+
         if message:
             default_message = message
         elif tool_name and reason:
@@ -125,5 +139,5 @@ class ToolProcessingError(SessionManagerError):
             default_message = f"Tool '{tool_name}' processing error"
         else:
             default_message = "Tool processing error"
-            
-        super().__init__(default_message)
+
+        super().__init__(default_message)

chuk_ai_session_manager/guards/__init__.py

@@ -0,0 +1,118 @@
+# chuk_ai_session_manager/guards/__init__.py
+"""Conversation guards and state management.
+
+Components:
+- ToolStateManager: Coordinator for guards, bindings, and cache
+- BindingManager: $vN reference system for tool result tracking
+- ResultCache: Tool result caching for deduplication
+- UngroundedGuard: Detects missing $vN references
+- Models: All Pydantic models for state management
+
+Runtime guards (BudgetGuard, RunawayGuard, etc.) are imported from chuk-tool-processor.
+"""
+
+# Models
+from chuk_ai_session_manager.guards.models import (
+    CachedToolResult,
+    CacheScope,
+    EnforcementLevel,
+    NamedVariable,
+    PerToolCallStatus,
+    ReferenceCheckResult,
+    RepairAction,
+    RunawayStatus,
+    RuntimeLimits,
+    RuntimeMode,
+    SoftBlock,
+    SoftBlockReason,
+    ToolClassification,
+    UngroundedCallResult,
+    UnusedResultAction,
+    ValueBinding,
+    ValueType,
+    classify_value_type,
+    compute_args_hash,
+)
+
+# Sub-managers
+from chuk_ai_session_manager.guards.bindings import BindingManager
+from chuk_ai_session_manager.guards.cache import ResultCache
+
+# Chat-specific guard
+from chuk_ai_session_manager.guards.ungrounded import (
+    UngroundedGuard,
+    UngroundedGuardConfig,
+)
+
+# Coordinator
+from chuk_ai_session_manager.guards.manager import (
+    ToolStateManager,
+    get_tool_state,
+    reset_tool_state,
+)
+
+# Re-export runtime guards from chuk-tool-processor
+from chuk_tool_processor.guards import (
+    BaseGuard,
+    BudgetGuard,
+    BudgetGuardConfig,
+    BudgetState,
+    Guard,
+    GuardResult,
+    GuardVerdict,
+    PerToolGuard,
+    PerToolGuardConfig,
+    PreconditionGuard,
+    PreconditionGuardConfig,
+    RunawayGuard,
+    RunawayGuardConfig,
+)
+
+__all__ = [
+    # Manager
+    "ToolStateManager",
+    "get_tool_state",
+    "reset_tool_state",
+    # Sub-managers
+    "BindingManager",
+    "ResultCache",
+    # Guards (from chuk-tool-processor)
+    "BaseGuard",
+    "Guard",
+    "GuardResult",
+    "GuardVerdict",
+    "BudgetGuard",
+    "BudgetGuardConfig",
+    "BudgetState",
+    "PerToolGuard",
+    "PerToolGuardConfig",
+    "PreconditionGuard",
+    "PreconditionGuardConfig",
+    "RunawayGuard",
+    "RunawayGuardConfig",
+    # Chat-specific guard
+    "UngroundedGuard",
+    "UngroundedGuardConfig",
+    # Enums and Constants
+    "CacheScope",
+    "EnforcementLevel",
+    "RuntimeMode",
+    "UnusedResultAction",
+    "ValueType",
+    "ToolClassification",
+    # Models
+    "CachedToolResult",
+    "NamedVariable",
+    "PerToolCallStatus",
+    "ReferenceCheckResult",
+    "RepairAction",
+    "RunawayStatus",
+    "RuntimeLimits",
+    "SoftBlock",
+    "SoftBlockReason",
+    "UngroundedCallResult",
+    "ValueBinding",
+    # Helpers
+    "classify_value_type",
+    "compute_args_hash",
+]

chuk_ai_session_manager/guards/bindings.py

@@ -0,0 +1,217 @@
+# chuk_ai_session_manager/guards/bindings.py
+"""Value binding system for $vN references.
+
+Every tool result gets assigned a stable ID (v1, v2, v3...) that can
+be referenced in subsequent tool calls using $vN syntax.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from chuk_ai_session_manager.guards.models import (
+    ValueBinding,
+    classify_value_type,
+    compute_args_hash,
+)
+
+# Reference pattern: $v1, $v2, ${v1}, ${myalias}
+REFERENCE_PATTERN = re.compile(r"\$\{?([a-zA-Z_][a-zA-Z0-9_]*|v\d+)\}?")
+
+
+class BindingManager(BaseModel):
+    """Manages value bindings for $vN references.
+
+    Pydantic-native implementation with all state in the model.
+    """
+
+    bindings: dict[str, ValueBinding] = Field(default_factory=dict)
+    alias_to_id: dict[str, str] = Field(default_factory=dict)
+    next_id: int = Field(default=1)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def bind(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        value: Any,
+        aliases: list[str] | None = None,
+    ) -> ValueBinding:
+        """Bind a tool result to a value ID.
+
+        Args:
+            tool_name: Name of the tool that produced this value
+            arguments: Arguments passed to the tool
+            value: The result value
+            aliases: Optional model-provided names
+
+        Returns:
+            The created ValueBinding
+        """
+        value_id = f"v{self.next_id}"
+        self.next_id += 1
+
+        binding = ValueBinding(
+            id=value_id,
+            tool_name=tool_name,
+            args_hash=compute_args_hash(arguments),
+            raw_value=value,
+            value_type=classify_value_type(value),
+            aliases=aliases or [],
+        )
+
+        self.bindings[value_id] = binding
+
+        # Register aliases
+        for alias in binding.aliases:
+            self.alias_to_id[alias] = value_id
+
+        return binding
+
+    def get(self, ref: str) -> ValueBinding | None:
+        """Get a binding by ID or alias."""
+        if ref in self.bindings:
+            return self.bindings[ref]
+        if ref in self.alias_to_id:
+            value_id = self.alias_to_id[ref]
+            return self.bindings.get(value_id)
+        return None
+
+    def add_alias(self, value_id: str, alias: str) -> bool:
+        """Add an alias to an existing binding."""
+        if value_id not in self.bindings:
+            return False
+        binding = self.bindings[value_id]
+        if alias not in binding.aliases:
+            binding.aliases.append(alias)
+        self.alias_to_id[alias] = value_id
+        return True
+
+    def mark_used(self, ref: str, used_in: str) -> None:
+        """Mark a value as having been used."""
+        binding = self.get(ref)
+        if binding:
+            binding.used = True
+            binding.used_in.append(used_in)
+
+    def get_numeric_values(self) -> set[float]:
+        """Get all numeric values from bindings.
+
+        Returns:
+            Set of float values from all bindings that have numeric raw_value
+        """
+        values: set[float] = set()
+        for binding in self.bindings.values():
+            if isinstance(binding.raw_value, (int, float)):
+                values.add(float(binding.raw_value))
+        return values
+
+    def resolve_references(self, arguments: dict[str, Any]) -> dict[str, Any]:
+        """Resolve $vN references in arguments to actual values."""
+        args_str = json.dumps(arguments, default=str)
+
+        def replace_ref(match: re.Match[str]) -> str:
+            ref = match.group(1)
+            binding = self.get(ref)
+            if binding:
+                self.mark_used(ref, "arg_resolution")
+                value = binding.typed_value
+                if isinstance(value, (int, float)):
+                    return str(value)
+                return json.dumps(value)
+            return str(match.group(0))
+
+        resolved_str = REFERENCE_PATTERN.sub(replace_ref, args_str)
+
+        try:
+            result: dict[str, Any] = json.loads(resolved_str)
+            return result
+        except json.JSONDecodeError:
+            return arguments
+
+    def check_references(
+        self, arguments: dict[str, Any]
+    ) -> tuple[bool, list[str], dict[str, Any]]:
+        """Check if all $vN references in arguments exist.
+
+        Returns:
+            Tuple of (all_valid, missing_refs, resolved_values)
+        """
+        args_str = json.dumps(arguments, default=str)
+        matches = REFERENCE_PATTERN.findall(args_str)
+
+        missing: list[str] = []
+        resolved: dict[str, Any] = {}
+
+        for ref in matches:
+            binding = self.get(ref)
+            if binding is None:
+                missing.append(ref)
+            else:
+                resolved[ref] = binding.typed_value
+
+        return len(missing) == 0, missing, resolved
+
+    def find_by_value(
+        self, value: float, tolerance: float = 0.0001
+    ) -> ValueBinding | None:
+        """Find a binding with a matching value."""
+        for binding in self.bindings.values():
+            try:
+                binding_val = float(binding.typed_value)
+                if value == binding_val:
+                    return binding
+                if abs(value) > 1e-10 and abs(binding_val) > 1e-10:
+                    if (
+                        abs(value - binding_val) / max(abs(value), abs(binding_val))
+                        < tolerance
+                    ):
+                        return binding
+            except (ValueError, TypeError):
+                continue
+        return None
+
+    def get_unused(self) -> list[ValueBinding]:
+        """Get all bindings that haven't been used."""
+        return [b for b in self.bindings.values() if not b.used]
+
+    def format_for_model(self) -> str:
+        """Format all bindings for display to the model."""
+        if not self.bindings:
+            return ""
+
+        lines = ["**Available Values (reference with $vN):**"]
+        for binding in self.bindings.values():
+            status = "✓" if binding.used else "○"
+            lines.append(f"  {status} {binding.format_for_model()}")
+
+        return "\n".join(lines)
+
+    def format_unused_warning(self) -> str:
+        """Generate warning about unused tool results."""
+        unused = self.get_unused()
+        if not unused:
+            return ""
+
+        ids = ", ".join(f"${b.id}" for b in unused)
+        return (
+            f"**Note:** You called tools producing {ids} but haven't referenced them. "
+            "Either use these values or explain why they're not needed."
+        )
+
+    def reset(self) -> None:
+        """Reset all bindings."""
+        self.bindings.clear()
+        self.alias_to_id.clear()
+        self.next_id = 1
+
+    def __len__(self) -> int:
+        return len(self.bindings)
+
+    def __bool__(self) -> bool:
+        return bool(self.bindings)

chuk_ai_session_manager/guards/cache.py

@@ -0,0 +1,163 @@
+# chuk_ai_session_manager/guards/cache.py
+"""Tool result caching.
+
+Caches tool call results so duplicates return cached values.
+Prevents the model from re-calling tools unnecessarily.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from chuk_ai_session_manager.guards.models import CachedToolResult, NamedVariable
+
+log = logging.getLogger(__name__)
+
+
+class ResultCache(BaseModel):
+    """Caches tool results for deduplication.
+
+    Pydantic-native implementation.
+    """
+
+    cache: dict[str, CachedToolResult] = Field(default_factory=dict)
+    variables: dict[str, NamedVariable] = Field(default_factory=dict)
+    call_order: list[str] = Field(default_factory=list)
+    max_size: int = Field(default=100)
+    duplicate_count: int = Field(default=0)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def get(self, tool_name: str, arguments: dict[str, Any]) -> CachedToolResult | None:
+        """Check if we have a cached result for this exact tool call."""
+        signature = self._make_signature(tool_name, arguments)
+        cached = self.cache.get(signature)
+        if cached:
+            cached.call_count += 1
+            self.duplicate_count += 1
+            log.info(f"Cache hit for {tool_name} (call #{cached.call_count})")
+        return cached
+
+    def put(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        result: Any,
+    ) -> CachedToolResult:
+        """Cache a tool result."""
+        # Evict if full
+        if len(self.cache) >= self.max_size:
+            self._evict_oldest()
+
+        signature = self._make_signature(tool_name, arguments)
+        cached = CachedToolResult(
+            tool_name=tool_name,
+            arguments=arguments,
+            result=result,
+        )
+        self.cache[signature] = cached
+        self.call_order.append(signature)
+
+        log.debug(f"Cached result for {tool_name}: {cached.format_compact()}")
+        return cached
+
+    def store_variable(
+        self,
+        name: str,
+        value: float,
+        units: str | None = None,
+        source_tool: str | None = None,
+        source_args: dict[str, Any] | None = None,
+    ) -> NamedVariable:
+        """Store a named variable from a computation."""
+        var = NamedVariable(
+            name=name,
+            value=value,
+            units=units,
+            source_tool=source_tool,
+            source_args=source_args,
+        )
+        self.variables[name] = var
+        log.debug(f"Stored variable: {var.format_compact()}")
+        return var
+
+    def get_variable(self, name: str) -> NamedVariable | None:
+        """Get a stored variable by name."""
+        return self.variables.get(name)
+
+    def format_state(self, max_items: int = 10) -> str:
+        """Generate compact state summary for model context."""
+        lines = []
+
+        # Named variables first
+        if self.variables:
+            lines.append("**Stored Variables:**")
+            for var in list(self.variables.values())[:max_items]:
+                lines.append(f"  {var.format_compact()}")
+
+        # Recent tool results
+        recent_sigs = self.call_order[-max_items:]
+        recent_results = [self.cache[sig] for sig in recent_sigs if sig in self.cache]
+
+        if recent_results:
+            if lines:
+                lines.append("")
+            lines.append("**Computed Values:**")
+            for cached in recent_results:
+                lines.append(f"  {cached.format_compact()}")
+
+        return "\n".join(lines) if lines else ""
+
+    def format_duplicate_message(
+        self, tool_name: str, arguments: dict[str, Any]
+    ) -> str:
+        """Generate message when duplicate call is detected."""
+        cached = self.get(tool_name, arguments)
+        if not cached:
+            return f"Tool {tool_name} was called but no cached result available."
+
+        lines = [
+            f"**Cached result for {tool_name}:** {cached.result}",
+            "",
+            "This value was already computed. Use it directly.",
+            "",
+        ]
+
+        state = self.format_state()
+        if state:
+            lines.append(state)
+
+        return "\n".join(lines)
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get cache statistics."""
+        return {
+            "total_cached": len(self.cache),
+            "total_variables": len(self.variables),
+            "duplicate_calls": self.duplicate_count,
+            "call_order_length": len(self.call_order),
+        }
+
+    def reset(self) -> None:
+        """Clear all cached state."""
+        self.cache.clear()
+        self.variables.clear()
+        self.call_order.clear()
+        self.duplicate_count = 0
+
+    def _make_signature(self, tool_name: str, arguments: dict[str, Any]) -> str:
+        """Create unique signature for a tool call."""
+        args_str = json.dumps(arguments, sort_keys=True, default=str)
+        return f"{tool_name}:{args_str}"
+
+    def _evict_oldest(self) -> None:
+        """Evict oldest cached result."""
+        if self.call_order:
+            oldest_sig = self.call_order.pop(0)
+            if oldest_sig in self.cache:
+                del self.cache[oldest_sig]
+                log.debug("Evicted oldest cache entry")