chuk-ai-session-manager 0.7.1__tar.gz → 0.8.1__tar.gz

{chuk_ai_session_manager-0.7.1 → chuk_ai_session_manager-0.8.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: chuk-ai-session-manager
-Version: 0.7.1
+Version: 0.8.1
 Summary: Session manager for AI applications
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: chuk-sessions>=0.4.2
-Requires-Dist: chuk-tool-processor>=0.4.1
+Requires-Dist: chuk-sessions>=0.4.1
+Requires-Dist: chuk-tool-processor>=0.18
 Requires-Dist: pydantic>=2.11.3
 Provides-Extra: redis
 Requires-Dist: chuk-sessions[redis]>=0.4.1; extra == "redis"
@@ -15,7 +15,7 @@ Requires-Dist: tiktoken>=0.9.0; extra == "tiktoken"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: isort>=5.12.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
@@ -74,6 +74,35 @@ That's it! Zero configuration required.
 
 ## ⚡ Major Features
 
+### 🧠 **AI Virtual Memory**
+OS-style memory management for AI context windows. Pages, working sets, faults, and eviction - giving conversations the illusion of infinite memory.
+
+```python
+from chuk_ai_session_manager.memory import (
+    MemoryPage, PageTable, WorkingSetManager,
+    ContextPacker, ManifestBuilder, PageType,
+)
+
+# Create pages with type classification
+claim = MemoryPage(
+    page_id="claim_auth",
+    page_type=PageType.CLAIM,  # High-value, low eviction priority
+    content="Decision: Use JWT for authentication",
+    provenance=["msg_042", "msg_043"],
+)
+
+# Track in page table and working set
+table = PageTable()
+table.register(claim)
+
+# Pack context for model with manifest
+packer = ContextPacker()
+packed = packer.pack([claim])
+# Model sees VM:CONTEXT with page citations
+```
+
+See [AI Virtual Memory docs](docs/memory/README.md) for full documentation.
+
 ### 🎯 **Zero-Configuration Tracking**
 ```python
 from chuk_ai_session_manager import SessionManager
@@ -104,6 +133,51 @@ await sm.ai_responds("Computing history begins with...", model="gpt-4")
 | `pip install chuk-ai-session-manager` | Memory | Development, testing | 1.8M ops/sec |
 | `pip install chuk-ai-session-manager[redis]` | Redis | Production, persistence | 20K ops/sec |
 
+### 🛡️ **Conversation Guards and Tool State**
+Runtime guardrails that prevent runaway tool loops, track value bindings, and enforce grounded tool calls.
+
+```python
+from chuk_ai_session_manager.guards import get_tool_state, ToolStateManager
+
+# Get the singleton tool state manager
+tool_state = get_tool_state()
+
+# Track tool calls and bind results as $v0, $v1, ...
+binding = tool_state.bind_value("sqrt", {"x": 16}, 4.0)
+# LLM can now reference $v0 in subsequent calls
+
+# Check for runaway tool loops
+status = tool_state.check_runaway()
+
+# Detect ungrounded calls (missing $vN references)
+check = tool_state.check_ungrounded_call("normal_cdf", {"mean": 0, "std": 1, "x": 1.5})
+
+# Reset state for a new prompt
+tool_state.reset_for_new_prompt()
+```
+
+**Guard components:**
+- `ToolStateManager` - Coordinator for all guards, bindings, and cache
+- `BindingManager` - `$vN` reference system for tracking tool results
+- `ResultCache` - Tool result caching for deduplication
+- `UngroundedGuard` - Detects calls with missing computed-value references
+- Runtime guards (budget, runaway, per-tool limits) from `chuk-tool-processor`
+
+### 🧩 **Procedural Memory**
+Learn from tool call history to improve future tool use.
+
+```python
+from chuk_ai_session_manager import ToolMemoryManager, ProceduralContextFormatter
+
+# Record tool outcomes
+memory = ToolMemoryManager()
+await memory.record("calculator", {"op": "add", "a": 5, "b": 3}, result=8, success=True)
+
+# Format learned patterns for the model's context
+formatter = ProceduralContextFormatter()
+context = formatter.format(memory.get_patterns())
+```
+
 ### 🛠️ **Tool Integration**
 ```python
 # Automatic tool call tracking
@@ -222,6 +296,8 @@ Session Segments: {stats.get('session_segments', 1)}
 - **Production Ready**: Built-in persistence, monitoring, and error handling
 - **Token Aware**: Automatic cost tracking across all providers
 - **Tool Friendly**: Seamless tool call logging and retry mechanisms
+- **Guardrails**: Runtime guards prevent runaway tool loops and ungrounded calls
+- **Procedural Memory**: Learn from tool call history to improve future use
 
 ## 🛡️ Error Handling
 

{chuk_ai_session_manager-0.7.1 → chuk_ai_session_manager-0.8.1}/README.md

@@ -48,6 +48,35 @@ That's it! Zero configuration required.
 
 ## ⚡ Major Features
 
+### 🧠 **AI Virtual Memory**
+OS-style memory management for AI context windows. Pages, working sets, faults, and eviction - giving conversations the illusion of infinite memory.
+
+```python
+from chuk_ai_session_manager.memory import (
+    MemoryPage, PageTable, WorkingSetManager,
+    ContextPacker, ManifestBuilder, PageType,
+)
+
+# Create pages with type classification
+claim = MemoryPage(
+    page_id="claim_auth",
+    page_type=PageType.CLAIM,  # High-value, low eviction priority
+    content="Decision: Use JWT for authentication",
+    provenance=["msg_042", "msg_043"],
+)
+
+# Track in page table and working set
+table = PageTable()
+table.register(claim)
+
+# Pack context for model with manifest
+packer = ContextPacker()
+packed = packer.pack([claim])
+# Model sees VM:CONTEXT with page citations
+```
+
+See [AI Virtual Memory docs](docs/memory/README.md) for full documentation.
+
 ### 🎯 **Zero-Configuration Tracking**
 ```python
 from chuk_ai_session_manager import SessionManager
@@ -78,6 +107,51 @@ await sm.ai_responds("Computing history begins with...", model="gpt-4")
 | `pip install chuk-ai-session-manager` | Memory | Development, testing | 1.8M ops/sec |
 | `pip install chuk-ai-session-manager[redis]` | Redis | Production, persistence | 20K ops/sec |
 
+### 🛡️ **Conversation Guards and Tool State**
+Runtime guardrails that prevent runaway tool loops, track value bindings, and enforce grounded tool calls.
+
+```python
+from chuk_ai_session_manager.guards import get_tool_state, ToolStateManager
+
+# Get the singleton tool state manager
+tool_state = get_tool_state()
+
+# Track tool calls and bind results as $v0, $v1, ...
+binding = tool_state.bind_value("sqrt", {"x": 16}, 4.0)
+# LLM can now reference $v0 in subsequent calls
+
+# Check for runaway tool loops
+status = tool_state.check_runaway()
+
+# Detect ungrounded calls (missing $vN references)
+check = tool_state.check_ungrounded_call("normal_cdf", {"mean": 0, "std": 1, "x": 1.5})
+
+# Reset state for a new prompt
+tool_state.reset_for_new_prompt()
+```
+
+**Guard components:**
+- `ToolStateManager` - Coordinator for all guards, bindings, and cache
+- `BindingManager` - `$vN` reference system for tracking tool results
+- `ResultCache` - Tool result caching for deduplication
+- `UngroundedGuard` - Detects calls with missing computed-value references
+- Runtime guards (budget, runaway, per-tool limits) from `chuk-tool-processor`
+
+### 🧩 **Procedural Memory**
+Learn from tool call history to improve future tool use.
+
+```python
+from chuk_ai_session_manager import ToolMemoryManager, ProceduralContextFormatter
+
+# Record tool outcomes
+memory = ToolMemoryManager()
+await memory.record("calculator", {"op": "add", "a": 5, "b": 3}, result=8, success=True)
+
+# Format learned patterns for the model's context
+formatter = ProceduralContextFormatter()
+context = formatter.format(memory.get_patterns())
+```
+
 ### 🛠️ **Tool Integration**
 ```python
 # Automatic tool call tracking
@@ -196,6 +270,8 @@ Session Segments: {stats.get('session_segments', 1)}
 - **Production Ready**: Built-in persistence, monitoring, and error handling
 - **Token Aware**: Automatic cost tracking across all providers
 - **Tool Friendly**: Seamless tool call logging and retry mechanisms
+- **Guardrails**: Runtime guards prevent runaway tool loops and ungrounded calls
+- **Procedural Memory**: Learn from tool call history to improve future use
 
 ## 🛡️ Error Handling
 

{chuk_ai_session_manager-0.7.1 → chuk_ai_session_manager-0.8.1}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-ai-session-manager"
-version = "0.7.1"
+version = "0.8.1"
 description = "Session manager for AI applications"
 readme = "README.md"
 requires-python = ">=3.11"
 
 # Core dependencies - only what's absolutely required
 dependencies = [
-    "chuk-sessions>=0.4.2",
-    "chuk-tool-processor>=0.4.1", 
+    "chuk-sessions>=0.4.1",
+    "chuk-tool-processor>=0.18",
     "pydantic>=2.11.3",
 ]
 
@@ -31,7 +31,7 @@ tiktoken = ["tiktoken>=0.9.0"]
 dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
-    "pytest-asyncio>=0.21.0",
+    "pytest-asyncio>=1.0.0",
     "black>=23.0.0",
     "isort>=5.12.0",
     "mypy>=1.0.0",
@@ -90,14 +90,63 @@ include = '\.pyi?$'
 profile = "black"
 multi_line_output = 3
 
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]
+ignore = ["E501"]  # Line too long - handled by formatter
+
+[tool.ruff.lint.per-file-ignores]
+# Allow imports after module-level code in __init__.py files
+"__init__.py" = ["E402", "F401"]
+# Allow sys.path modification before imports in examples
+"examples/**/*.py" = ["E402"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = false
+warn_unused_configs = true
+ignore_missing_imports = true
+check_untyped_defs = false
+disallow_untyped_defs = false
+exclude = [
+    "examples/",
+    "tests/",
+    ".*/site-packages/.*",
+]
+
+# Per-module overrides for files with pre-existing type errors.
+# Fix these incrementally and remove the override when clean.
+[[tool.mypy.overrides]]
+module = [
+    "chuk_ai_session_manager.session_manager",
+    "chuk_ai_session_manager.session_prompt_builder",
+    "chuk_ai_session_manager.session_storage",
+    "chuk_ai_session_manager.session_aware_tool_processor",
+    "chuk_ai_session_manager.infinite_conversation",
+    "chuk_ai_session_manager.models.session",
+    "chuk_ai_session_manager.models.session_run",
+    "chuk_ai_session_manager.memory.fault_handler",
+    "chuk_ai_session_manager.memory.artifacts_bridge",
+    "chuk_ai_session_manager.guards.manager",
+]
+ignore_errors = true
+
 [dependency-groups]
 dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=1.0.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "mypy>=1.0.0",
     "bs4>=0.0.2",
     "chuk-llm>=0.3",
     "fastapi>=0.115.12",
     "geopy>=2.4.1",
     "openai>=1.88.0",
-    "pytest-asyncio>=1.0.0",
     "tiktoken>=0.9.0",
     "uvicorn>=0.34.2",
-]
+]

{chuk_ai_session_manager-0.7.1 → chuk_ai_session_manager-0.8.1}/src/chuk_ai_session_manager/__init__.py

@@ -4,7 +4,7 @@ CHUK AI Session Manager - Simple Developer API
 
 A powerful session management system for AI applications that provides:
 - Automatic conversation tracking
-- Token usage monitoring  
+- Token usage monitoring
 - Tool call logging
 - Infinite context support with automatic summarization
 - Hierarchical session relationships
@@ -32,12 +32,12 @@ Infinite Context Example:
 Storage Configuration:
     # Default: Memory storage (no Redis required)
     pip install chuk-ai-session-manager
-    
+
     # Redis: For production persistence
     pip install chuk-ai-session-manager[redis]
     export SESSION_PROVIDER=redis
     export SESSION_REDIS_URL=redis://localhost:6379/0
-    
+
     # Environment variables:
     SESSION_PROVIDER=memory (default - fast, no persistence)
     SESSION_PROVIDER=redis  (persistent - requires [redis] extra)
@@ -46,7 +46,7 @@ Storage Configuration:
 import logging
 
 # Package version
-__version__ = "0.5"
+__version__ = "0.8"
 
 # Set up package-level logger
 logger = logging.getLogger(__name__)
@@ -63,7 +63,7 @@ from chuk_ai_session_manager.exceptions import (
     InvalidSessionOperation,
     TokenLimitExceeded,
     StorageError,
-    ToolProcessingError
+    ToolProcessingError,
 )
 
 # Core models
@@ -87,36 +87,66 @@ from chuk_ai_session_manager.api.simple_api import (
     track_infinite_conversation,
     track_tool_use,
     get_session_stats,
-    get_conversation_history
+    get_conversation_history,
 )
 
 # Advanced components
 from chuk_ai_session_manager.infinite_conversation import (
     InfiniteConversationManager,
-    SummarizationStrategy
+    SummarizationStrategy,
 )
 
-from chuk_ai_session_manager.session_aware_tool_processor import SessionAwareToolProcessor
+from chuk_ai_session_manager.session_aware_tool_processor import (
+    SessionAwareToolProcessor,
+)
 
 from chuk_ai_session_manager.session_prompt_builder import (
     build_prompt_from_session,
     PromptStrategy,
-    truncate_prompt_to_token_limit
+    truncate_prompt_to_token_limit,
 )
 
+# Procedural memory
+from chuk_ai_session_manager.procedural_memory import (
+    ToolMemoryManager,
+    ToolOutcome,
+    ToolLogEntry,
+    ToolPattern,
+    ProceduralMemory,
+    ProceduralContextFormatter,
+    FormatterConfig,
+)
+
+# Guards and state management
+from chuk_ai_session_manager.guards import (
+    ToolStateManager,
+    get_tool_state,
+    reset_tool_state,
+    BindingManager,
+    ResultCache,
+    UngroundedGuard,
+    UngroundedGuardConfig,
+    RuntimeLimits,
+    RuntimeMode,
+    ValueBinding,
+    ToolClassification,
+)
+
+
 # Configuration functions
-def configure_storage(sandbox_id: str = "chuk-ai-session-manager", 
-                     default_ttl_hours: int = 24) -> bool:
+def configure_storage(
+    sandbox_id: str = "chuk-ai-session-manager", default_ttl_hours: int = 24
+) -> bool:
     """
     Configure the storage backend.
-    
+
     Args:
         sandbox_id: CHUK Sessions sandbox ID to use
         default_ttl_hours: Default TTL for sessions
-        
+
     Returns:
         True if configuration was successful, False otherwise
-        
+
     Note:
         Storage provider is controlled by SESSION_PROVIDER environment variable:
         - memory (default): Fast, no persistence, no extra dependencies
@@ -124,8 +154,7 @@ def configure_storage(sandbox_id: str = "chuk-ai-session-manager",
     """
     try:
         setup_chuk_sessions_storage(
-            sandbox_id=sandbox_id,
-            default_ttl_hours=default_ttl_hours
+            sandbox_id=sandbox_id, default_ttl_hours=default_ttl_hours
         )
         logger.info(f"Storage configured with sandbox_id='{sandbox_id}'")
         return True
@@ -142,26 +171,28 @@ def get_version() -> str:
 def is_available() -> dict:
     """
     Check which components are available.
-    
+
     Returns:
         Dictionary showing availability of each component
     """
     # Check if Redis is available
     redis_available = False
     try:
-        import redis
+        import redis  # noqa: F401
+
         redis_available = True
     except ImportError:
         pass
-    
+
     # Check if tiktoken is available for enhanced token counting
     tiktoken_available = False
     try:
-        import tiktoken
+        import tiktoken  # noqa: F401
+
         tiktoken_available = True
     except ImportError:
         pass
-    
+
     return {
         "core_enums": True,
         "core_models": True,
@@ -181,53 +212,47 @@ def is_available() -> dict:
 def get_storage_info() -> dict:
     """
     Get information about the current storage configuration.
-    
+
     Returns:
         Dictionary with storage configuration details
     """
     import os
     from chuk_ai_session_manager.session_storage import get_backend
-    
+
     try:
         backend = get_backend()
         stats = backend.get_stats()
-        
+
         return {
             "provider": os.getenv("SESSION_PROVIDER", "memory"),
             "backend": stats.get("backend", "unknown"),
             "sandbox_id": stats.get("sandbox_id", "unknown"),
             "redis_url": os.getenv("SESSION_REDIS_URL", "not_set"),
-            "stats": stats
+            "stats": stats,
         }
     except Exception as e:
-        return {
-            "provider": os.getenv("SESSION_PROVIDER", "memory"),
-            "error": str(e)
-        }
+        return {"provider": os.getenv("SESSION_PROVIDER", "memory"), "error": str(e)}
 
 
 # Main exports - everything should be available
 __all__ = [
     # Version and utilities
     "__version__",
-    "get_version", 
+    "get_version",
     "is_available",
     "configure_storage",
     "get_storage_info",
-    
     # Core enums
     "EventSource",
     "EventType",
-    
     # Exception classes
     "SessionManagerError",
-    "SessionNotFound", 
+    "SessionNotFound",
     "SessionAlreadyExists",
     "InvalidSessionOperation",
     "TokenLimitExceeded",
     "StorageError",
     "ToolProcessingError",
-    
     # Core models
     "Session",
     "SessionEvent",
@@ -236,20 +261,17 @@ __all__ = [
     "RunStatus",
     "TokenUsage",
     "TokenSummary",
-    
     # Storage
     "setup_chuk_sessions_storage",
-    
     # Primary interfaces - what most users will use
     "SessionManager",
-    "track_conversation", 
+    "track_conversation",
     "track_llm_call",
     "quick_conversation",
     "track_infinite_conversation",
     "track_tool_use",
     "get_session_stats",
     "get_conversation_history",
-    
     # Advanced components
     "InfiniteConversationManager",
     "SummarizationStrategy",
@@ -257,6 +279,26 @@ __all__ = [
     "build_prompt_from_session",
     "PromptStrategy",
     "truncate_prompt_to_token_limit",
+    # Procedural memory
+    "ToolMemoryManager",
+    "ToolOutcome",
+    "ToolLogEntry",
+    "ToolPattern",
+    "ProceduralMemory",
+    "ProceduralContextFormatter",
+    "FormatterConfig",
+    # Guards and state management
+    "ToolStateManager",
+    "get_tool_state",
+    "reset_tool_state",
+    "BindingManager",
+    "ResultCache",
+    "UngroundedGuard",
+    "UngroundedGuardConfig",
+    "RuntimeLimits",
+    "RuntimeMode",
+    "ValueBinding",
+    "ToolClassification",
 ]
 
 # Auto-setup storage on import
@@ -270,6 +312,8 @@ except Exception as e:
 try:
     storage_info = get_storage_info()
     provider = storage_info.get("provider", "unknown")
-    logger.debug(f"CHUK AI Session Manager v{__version__} imported successfully (storage: {provider})")
+    logger.debug(
+        f"CHUK AI Session Manager v{__version__} imported successfully (storage: {provider})"
+    )
 except Exception:
-    logger.debug(f"CHUK AI Session Manager v{__version__} imported successfully")
+    logger.debug(f"CHUK AI Session Manager v{__version__} imported successfully")

chuk_ai_session_manager-0.8.1/src/chuk_ai_session_manager/api/__init__.py

@@ -0,0 +1 @@
+# chuk_ai_session_manager/api/__init__.py