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

chuk_ai_session_manager/session_storage.py

@@ -20,7 +20,7 @@ except ImportError as e:
         f"Cannot import SessionManager from chuk_sessions: {e}\n"
         "Please ensure chuk_sessions is properly installed with: uv add chuk-sessions\n"
         "Or check the available classes in chuk_sessions by running:\n"
-        "python -c \"import chuk_sessions; print(dir(chuk_sessions))\""
+        'python -c "import chuk_sessions; print(dir(chuk_sessions))"'
     ) from e
 
 from chuk_ai_session_manager.models.session import Session
@@ -31,81 +31,76 @@ logger = logging.getLogger(__name__)
 class SessionStorage:
     """
     CHUK Sessions backend for AI Session Manager.
-    
+
     Stores AI sessions as JSON in CHUK Sessions custom metadata.
     All provider logic is handled by CHUK Sessions.
     """
-    
+
     def __init__(
-        self, 
-        sandbox_id: str = "ai-session-manager",
-        default_ttl_hours: int = 24
+        self, sandbox_id: str = "ai-session-manager", default_ttl_hours: int = 24
     ):
         self.chuk = ChukSessionManager(
-            sandbox_id=sandbox_id,
-            default_ttl_hours=default_ttl_hours
+            sandbox_id=sandbox_id, default_ttl_hours=default_ttl_hours
         )
         self.sandbox_id = sandbox_id
         self._cache: Dict[str, Session] = {}
-        
+
         logger.info(f"AI Session Manager using CHUK Sessions (sandbox: {sandbox_id})")
-    
+
     async def get(self, session_id: str) -> Optional[Session]:
         """Get AI session by ID."""
         if session_id in self._cache:
             return self._cache[session_id]
-        
+
         try:
             # Get session info from CHUK Sessions
             info = await self.chuk.get_session_info(session_id)
             if not info:
                 return None
-            
+
             # Check if it's an AI session manager session
-            custom_metadata = info.get('custom_metadata', {})
-            if custom_metadata.get('session_type') != 'ai_session_manager':
+            custom_metadata = info.get("custom_metadata", {})
+            if custom_metadata.get("session_type") != "ai_session_manager":
                 return None
-            
-            ai_session_json = custom_metadata.get('ai_session_data')
+
+            ai_session_json = custom_metadata.get("ai_session_data")
             if not ai_session_json:
                 return None
-            
+
             # Parse the JSON data
             session_data = json.loads(ai_session_json)
             ai_session = Session.model_validate(session_data)
-            
+
             self._cache[session_id] = ai_session
             return ai_session
-            
+
         except Exception as e:
             logger.error(f"Failed to get AI session {session_id}: {e}")
             return None
-    
+
     async def save(self, session: Session) -> None:
         """Save AI session to CHUK Sessions."""
         try:
             # Use Pydantic's model_dump_json which handles datetime serialization properly
             session_json = session.model_dump_json()
             user_id = self._extract_user_id(session)
-            
+
             custom_metadata = {
-                'ai_session_data': session_json,
-                'event_count': len(session.events),
-                'session_type': 'ai_session_manager'
+                "ai_session_data": session_json,
+                "event_count": len(session.events),
+                "session_type": "ai_session_manager",
             }
-            
+
             await self.chuk.allocate_session(
-                session_id=session.id,
-                user_id=user_id,
-                custom_metadata=custom_metadata
+                session_id=session.id, user_id=user_id, custom_metadata=custom_metadata
             )
-            
+
             self._cache[session.id] = session
-            
+
         except Exception as e:
             logger.error(f"Failed to save AI session {session.id}: {e}")
             raise
-    
+
     async def delete(self, session_id: str) -> None:
         """Delete AI session."""
         try:
@@ -114,34 +109,34 @@ class SessionStorage:
         except Exception as e:
             logger.error(f"Failed to delete AI session {session_id}: {e}")
             raise
-    
+
     async def list_sessions(self, prefix: str = "") -> List[str]:
         """List AI session IDs."""
         session_ids = list(self._cache.keys())
         if prefix:
             session_ids = [sid for sid in session_ids if sid.startswith(prefix)]
         return session_ids
-    
+
     def _extract_user_id(self, session: Session) -> Optional[str]:
         """Extract user ID from AI session metadata."""
         try:
-            if hasattr(session.metadata, 'properties'):
-                return session.metadata.properties.get('user_id')
-        except:
+            if hasattr(session.metadata, "properties"):
+                return session.metadata.properties.get("user_id")
+        except (AttributeError, TypeError):
             pass
         return None
-    
+
     async def extend_session_ttl(self, session_id: str, additional_hours: int) -> bool:
         """Extend session TTL."""
         return await self.chuk.extend_session_ttl(session_id, additional_hours)
-    
+
     def get_stats(self) -> Dict[str, Any]:
         """Get storage statistics."""
         return {
-            'backend': 'chuk_sessions',
-            'sandbox_id': self.sandbox_id,
-            'cached_ai_sessions': len(self._cache),
-            'chuk_sessions_stats': self.chuk.get_cache_stats()
+            "backend": "chuk_sessions",
+            "sandbox_id": self.sandbox_id,
+            "cached_ai_sessions": len(self._cache),
+            "chuk_sessions_stats": self.chuk.get_cache_stats(),
         }
 
 
@@ -158,32 +153,30 @@ def get_backend() -> SessionStorage:
 
 
 def setup_chuk_sessions_storage(
-    sandbox_id: str = "ai-session-manager",
-    default_ttl_hours: int = 24
+    sandbox_id: str = "ai-session-manager", default_ttl_hours: int = 24
 ) -> SessionStorage:
     """Set up CHUK Sessions as the storage backend."""
     global _backend
     _backend = SessionStorage(
-        sandbox_id=sandbox_id,
-        default_ttl_hours=default_ttl_hours
+        sandbox_id=sandbox_id, default_ttl_hours=default_ttl_hours
     )
     return _backend
 
 
 class ChukSessionsStore:
     """Storage interface adapter for CHUK Sessions."""
-    
+
     def __init__(self, backend: Optional[SessionStorage] = None):
         self.backend = backend or get_backend()
-    
+
     async def get(self, session_id: str) -> Optional[Session]:
         return await self.backend.get(session_id)
-    
+
     async def save(self, session: Session) -> None:
         await self.backend.save(session)
-    
+
     async def delete(self, session_id: str) -> None:
         await self.backend.delete(session_id)
-    
+
     async def list_sessions(self, prefix: str = "") -> List[str]:
-        return await self.backend.list_sessions(prefix)
+        return await self.backend.list_sessions(prefix)

{chuk_ai_session_manager-0.7.1.dist-info → chuk_ai_session_manager-0.8.1.dist-info}/METADATA

@@ -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.8.1.dist-info/RECORD

@@ -0,0 +1,45 @@
+chuk_ai_session_manager/__init__.py,sha256=bOe9gnKjblWKudA6EyUKlPDOypa6D2H8agImFIXxUK4,8794
+chuk_ai_session_manager/exceptions.py,sha256=xkjLB3tc0ObyAAUNIaklN2rY8LD-qTia3BwxdgAaY4k,4412
+chuk_ai_session_manager/infinite_conversation.py,sha256=SSCxCMfvgX30hfoB8IKqAnI_sQfqK7u0juUFyzUxZjk,11792
+chuk_ai_session_manager/sample_tools.py,sha256=1W81aE8qsUde5UZOup_k3r_9BrlVx3J77awj9eLhCgw,8287
+chuk_ai_session_manager/session_aware_tool_processor.py,sha256=vaCcWPh4i77Ur9lrYjUaHI_UucITc2nTaQ8BDlF2alQ,7473
+chuk_ai_session_manager/session_manager.py,sha256=lMaOSLuC48mLPmTFVRr4OGpJiJLUDEJ2UocSVHzhlOg,28032
+chuk_ai_session_manager/session_prompt_builder.py,sha256=T99BPgfoJxujQYM5TlU72IbpoPQ90YLQTvKEa-sQL-o,18097
+chuk_ai_session_manager/session_storage.py,sha256=9kINMmujlqYiTaiTKhnIJO1hfC76LEqrP2zc4wZiLnc,6203
+chuk_ai_session_manager/api/__init__.py,sha256=APDZLJTWC9cZbIuigiIzmI2uN1_CG-5Nk4rmdgMU08Q,42
+chuk_ai_session_manager/api/simple_api.py,sha256=LjkYec8_lqbARszdJHQfqaTYlWJ1xMqslHMxQZf1kiA,10253
+chuk_ai_session_manager/guards/__init__.py,sha256=UVpSqMqbjhMny4JK0D5ZNpzO2YxXq23of0ZkauuXPyQ,2731
+chuk_ai_session_manager/guards/bindings.py,sha256=afyiyP-HBn5dQPPYJOLBUP8bRWFvbH-NAE1t0QGnHXM,6898
+chuk_ai_session_manager/guards/cache.py,sha256=QztAjsFZmh6H_V0GBKUkRwQA_pd1SbdpO_LQruLRfqQ,5254
+chuk_ai_session_manager/guards/manager.py,sha256=OKjqZxl4-DaGfoQfKiMy7z3vS2EauNDDmDJZRpbpU74,30605
+chuk_ai_session_manager/guards/models.py,sha256=TQ6m8b4DURrum7-NNid03tMDOZ6bGjMDpVYxCPNud-o,16425
+chuk_ai_session_manager/guards/ungrounded.py,sha256=c60RfBXXfsWONtHQ7KG69LBxVgl2fHGlD6hMJH0Pzt8,5376
+chuk_ai_session_manager/memory/__init__.py,sha256=UDrugFtN5ury4WcvCwH669qRib_H-VyiULjSaigv8jA,5521
+chuk_ai_session_manager/memory/artifacts_bridge.py,sha256=fCmS1JLzsTmmZkEobKHulPHtcS0hXjmIU2W3x269ZCM,13149
+chuk_ai_session_manager/memory/context_packer.py,sha256=QjOqWLmLe2jfYQ_lncc49pZYwB7J_tPNKXoOYO-rhm8,11784
+chuk_ai_session_manager/memory/fault_handler.py,sha256=cUc5QwrUNl2J7Zd7Nm4kGSCZo35IdjooWcmxNp_yGuM,15798
+chuk_ai_session_manager/memory/manifest.py,sha256=vjCNEHjDrEMvL3OjPFVNul9Q32y4NqmSHL2vaXtZT5k,10125
+chuk_ai_session_manager/memory/models.py,sha256=zm1dtAK6SYtJzOxYyBqOouv9puwR5iHoezPx_ekddEI,33782
+chuk_ai_session_manager/memory/mutation_log.py,sha256=dSGHQnjHIDCMtT9YzuK4PwJXCsDG0yypNgDt2U1n0VM,6138
+chuk_ai_session_manager/memory/pack_cache.py,sha256=7KewvuX0kvbFfgIjPAZVSzt9ICfh1-V75JzIHWmbteg,6088
+chuk_ai_session_manager/memory/page_table.py,sha256=-k-Kd2zLZwK9VNPXZNmH_s22dFxqMmzN9BtL6MJ13hM,8762
+chuk_ai_session_manager/memory/prefetcher.py,sha256=0VX5Uw3NMTV_OpBdYOcAaawp3A7h6wQ-kxcdKwv6uOc,6340
+chuk_ai_session_manager/memory/tlb.py,sha256=iJ1AwCNAhPxR5L3o68idF57W22M5EZNRxusuPBWrUGg,7702
+chuk_ai_session_manager/memory/vm_prompts.py,sha256=xsa__nIV4L2GeiIPmNbJrm5-Jm0CEqmKipOkLExUN6k,8106
+chuk_ai_session_manager/memory/working_set.py,sha256=7P1SazsT15YyLxY5jEgq5EX_nYNFjY6tUnoFUxQXyoI,19441
+chuk_ai_session_manager/models/__init__.py,sha256=Lor8zOLGRjJQzGRM5S5pyOHyhjf-U8nJsvQM6KZDJPw,1345
+chuk_ai_session_manager/models/event_source.py,sha256=xbcGHwCBVWJeIQGDkoecH2iKyt9XoFfnchFS_8bMwRc,199
+chuk_ai_session_manager/models/event_type.py,sha256=OOdLQGBqG1QlBJvvMEVOvyVoX4RrUpyXSltE4SN9GFw,516
+chuk_ai_session_manager/models/session.py,sha256=PErniz2nntzRmlYNTubb1eSKG0LyUTiJ9qRkTUHx320,12114
+chuk_ai_session_manager/models/session_event.py,sha256=Hzx0tUF-v6693lojnw_j2FWTe-LNR5LfqesFMvCbjgY,8657
+chuk_ai_session_manager/models/session_metadata.py,sha256=o3siHorFPOfk16fpoopA8Wg5qxmEJLIl0d3uiJNJeTE,1456
+chuk_ai_session_manager/models/session_run.py,sha256=Q3scCXXsS3ZegN-iIjUzs49wxVR0G7UOgfgYZXpSVFY,4233
+chuk_ai_session_manager/models/token_usage.py,sha256=sMQzCYrPxzC25-0BTeAAQIR0VLDfNqOC9ykeADrNFlA,11004
+chuk_ai_session_manager/procedural_memory/__init__.py,sha256=ZytWkGBMCnZIqYxKXoIpksdi6ERKiqsc6qkPBNRNe3w,2023
+chuk_ai_session_manager/procedural_memory/formatter.py,sha256=Mq1shYs-ToZw6U5OxAX62MscWd8kUVvE48X8k7MT8n8,12891
+chuk_ai_session_manager/procedural_memory/manager.py,sha256=_wgpxD3dChZRT7mveqfxB0aSueu4XZlZxGPZqWjZaTA,16904
+chuk_ai_session_manager/procedural_memory/models.py,sha256=EdDsMeQA5bGiNr6VU9RbzEG5JGODfTmt2IHqneVAGOo,12137
+chuk_ai_session_manager-0.8.1.dist-info/METADATA,sha256=I7OmmmrRP8Jg8HzSVkUDBKU9fJUQIcFA1J2u7-ZwgT0,10542
+chuk_ai_session_manager-0.8.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+chuk_ai_session_manager-0.8.1.dist-info/top_level.txt,sha256=5RinqD0v-niHuLYePUREX4gEWTlrpgtUg0RfexVRBMk,24
+chuk_ai_session_manager-0.8.1.dist-info/RECORD,,

{chuk_ai_session_manager-0.7.1.dist-info → chuk_ai_session_manager-0.8.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

chuk_ai_session_manager-0.7.1.dist-info/RECORD

@@ -1,22 +0,0 @@
-chuk_ai_session_manager/__init__.py,sha256=r24MtKySdzvUgK8psNHYHiTRzOUAEXPOBmaNg2cjyFw,7882
-chuk_ai_session_manager/exceptions.py,sha256=WqrrUZuOAiUmz7tKnSnk0y222U_nV9a8LyaXLayn2fg,4420
-chuk_ai_session_manager/infinite_conversation.py,sha256=7j3caMnsX27M5rjj4oOkqiy_2AfcupWwsAWRflnKiSo,12092
-chuk_ai_session_manager/sample_tools.py,sha256=U-jTGveTJ95uSnA4jB30fJQJG3K-TGxN9jcOY6qVHZQ,8179
-chuk_ai_session_manager/session_aware_tool_processor.py,sha256=iVe3d-qfp5QGkdNrgfZeRYoOjd8nLZ0g6K7HW1thFE8,7274
-chuk_ai_session_manager/session_manager.py,sha256=AauyE2XTqAM53fGxpJD73nVwxB3cWH0jMlBXakYTAD0,29195
-chuk_ai_session_manager/session_prompt_builder.py,sha256=Jeg_MWses_hFtHtDL7ZQl6EdSNVmVIIrLDrWEoPumfM,17613
-chuk_ai_session_manager/session_storage.py,sha256=wb6SPwOKVoov2cGmK6DuorpPM7xbjnCRHrA6VTvG7GE,6427
-chuk_ai_session_manager/api/__init__.py,sha256=Lo_BoDW2rSn0Zw-CbjahOxc6ykjjTpucxHZo5FA2Gnc,41
-chuk_ai_session_manager/api/simple_api.py,sha256=aUDH2KzkI_M2eUiW9DAQo2KmUYaVa5u25-gSIF3PzGM,10504
-chuk_ai_session_manager/models/__init__.py,sha256=H1rRuDQDRf821JPUWUn5Zgwvc5BAqcEGekkHEmX-IgE,1167
-chuk_ai_session_manager/models/event_source.py,sha256=mn_D16sXMa6nAX-5BzssygJPz6VF24GRe-3IaH7bTnI,196
-chuk_ai_session_manager/models/event_type.py,sha256=TPPvAz-PlXVtrwXDNVFVnhdt1yEfgDGmKDGt8ArYcTk,275
-chuk_ai_session_manager/models/session.py,sha256=yUPuu6yt8HbBebkIejpgSDGTLhZjtLOxFRkWG2C6XKM,12193
-chuk_ai_session_manager/models/session_event.py,sha256=RTghC9_sDHzD8qdgEYCoclJzpVo8cE6B2f7jlsDOVr0,9006
-chuk_ai_session_manager/models/session_metadata.py,sha256=KFG7lc_E0BQTP2OD9Y529elVGJXppDUMqz8vVONW0rw,1510
-chuk_ai_session_manager/models/session_run.py,sha256=uhMM4-WSrqOUsiWQPnyakInd-foZhxI-YnSHSWiZZwE,4369
-chuk_ai_session_manager/models/token_usage.py,sha256=M9Qwmeb2woILaSRwA2SIAiG-sIwC3cL_1H-y3NjW5Ik,11436
-chuk_ai_session_manager-0.7.1.dist-info/METADATA,sha256=UFiDpEPfzRXVPX23KPy14pUobcg1Xil-BqKcrEeTNRM,7912
-chuk_ai_session_manager-0.7.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-chuk_ai_session_manager-0.7.1.dist-info/top_level.txt,sha256=5RinqD0v-niHuLYePUREX4gEWTlrpgtUg0RfexVRBMk,24
-chuk_ai_session_manager-0.7.1.dist-info/RECORD,,