chuk-ai-session-manager 0.5__py3-none-any.whl → 0.7__py3-none-any.whl

chuk_ai_session_manager/__init__.py

@@ -28,12 +28,25 @@ Infinite Context Example:
     await sm.user_says("Tell me about machine learning")
     await sm.ai_responds("Machine learning is...", model="gpt-4")
     # Session will auto-segment when limits are reached
+
+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)
 """
 
 import logging
 
 # Package version
-__version__ = "0.4"
+__version__ = "0.5"
 
 # Set up package-level logger
 logger = logging.getLogger(__name__)
@@ -103,6 +116,11 @@ def configure_storage(sandbox_id: str = "chuk-ai-session-manager",
         
     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
+        - redis: Persistent, requires pip install chuk-ai-session-manager[redis]
     """
     try:
         setup_chuk_sessions_storage(
@@ -128,6 +146,22 @@ def is_available() -> dict:
     Returns:
         Dictionary showing availability of each component
     """
+    # Check if Redis is available
+    redis_available = False
+    try:
+        import redis
+        redis_available = True
+    except ImportError:
+        pass
+    
+    # Check if tiktoken is available for enhanced token counting
+    tiktoken_available = False
+    try:
+        import tiktoken
+        tiktoken_available = True
+    except ImportError:
+        pass
+    
     return {
         "core_enums": True,
         "core_models": True,
@@ -139,9 +173,39 @@ def is_available() -> dict:
         "token_tracking": True,
         "exceptions": True,
         "session_manager": True,
+        "redis_support": redis_available,
+        "enhanced_token_counting": tiktoken_available,
     }
 
 
+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
+        }
+    except Exception as e:
+        return {
+            "provider": os.getenv("SESSION_PROVIDER", "memory"),
+            "error": str(e)
+        }
+
+
 # Main exports - everything should be available
 __all__ = [
     # Version and utilities
@@ -149,6 +213,7 @@ __all__ = [
     "get_version", 
     "is_available",
     "configure_storage",
+    "get_storage_info",
     
     # Core enums
     "EventSource",
@@ -201,5 +266,10 @@ try:
 except Exception as e:
     logger.debug(f"Auto-setup skipped: {e}")
 
-# Log successful import
-logger.debug(f"CHUK AI Session Manager v{__version__} imported successfully")
+# Log successful import with storage info
+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})")
+except Exception:
+    logger.debug(f"CHUK AI Session Manager v{__version__} imported successfully")

chuk_ai_session_manager-0.7.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: chuk-ai-session-manager
+Version: 0.7
+Summary: Session manager for AI applications
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: chuk-sessions>=0.4.1
+Requires-Dist: chuk-tool-processor>=0.4.1
+Requires-Dist: pydantic>=2.11.3
+Provides-Extra: redis
+Requires-Dist: chuk-sessions[redis]>=0.4.1; extra == "redis"
+Requires-Dist: redis>=4.0.0; extra == "redis"
+Provides-Extra: tiktoken
+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: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: chuk-sessions[redis]>=0.4; extra == "all"
+Requires-Dist: redis>=4.0.0; extra == "all"
+Requires-Dist: tiktoken>=0.9.0; extra == "all"
+
+# CHUK AI Session Manager
+
+**A powerful session management system for AI applications**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Automatic conversation tracking, token usage monitoring, tool call logging, infinite context support with automatic summarization, and hierarchical session relationships. Perfect for AI applications that need reliable session management.
+
+## 🚀 Quick Start
+
+### Installation Options
+
+```bash
+# Basic installation (memory storage only)
+pip install chuk-ai-session-manager
+
+# With Redis support for production
+pip install chuk-ai-session-manager[redis]
+
+# With enhanced token counting
+pip install chuk-ai-session-manager[tiktoken]
+
+# Full installation with all optional features
+pip install chuk-ai-session-manager[all]
+
+# Development installation
+pip install chuk-ai-session-manager[dev]
+```
+
+### Quick Example
+
+```python
+from chuk_ai_session_manager import track_conversation
+
+# Track any conversation automatically
+session_id = await track_conversation(
+    user_message="What's the weather like?",
+    ai_response="I don't have access to real-time weather data.",
+    model="gpt-3.5-turbo",
+    provider="openai"
+)
+
+print(f"Conversation tracked in session: {session_id}")
+```
+
+That's it! Zero configuration required.
+
+## ⚡ Major Features
+
+### 🎯 **Zero-Configuration Tracking**
+```python
+from chuk_ai_session_manager import SessionManager
+
+# Just start using it
+sm = SessionManager()
+await sm.user_says("Hello!")
+await sm.ai_responds("Hi there!", model="gpt-4")
+
+# Get stats instantly
+stats = await sm.get_stats()
+print(f"Tokens: {stats['total_tokens']}, Cost: ${stats['estimated_cost']:.4f}")
+```
+
+### 🔄 **Infinite Context**
+```python
+# Automatically handles conversations longer than token limits
+sm = SessionManager(infinite_context=True, token_threshold=4000)
+await sm.user_says("Tell me about the history of computing...")
+await sm.ai_responds("Computing history begins with...", model="gpt-4")
+# Session will auto-segment when limits are reached
+```
+
+### ⚙️ **Storage Backends**
+
+| Installation | Storage | Use Case | Performance |
+|-------------|---------|----------|-------------|
+| `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 |
+
+### 🛠️ **Tool Integration**
+```python
+# Automatic tool call tracking
+await sm.tool_used(
+    tool_name="calculator",
+    arguments={"operation": "add", "a": 5, "b": 3},
+    result={"result": 8}
+)
+```
+
+## 💡 Common Use Cases
+
+### Web App Conversation Tracking
+```python
+from chuk_ai_session_manager import track_conversation
+
+# In your chat endpoint
+session_id = await track_conversation(
+    user_message=request.message,
+    ai_response=ai_response,
+    model="gpt-4",
+    provider="openai",
+    session_id=request.session_id  # Continue existing conversation
+)
+```
+
+### LLM Wrapper with Automatic Tracking
+```python
+from chuk_ai_session_manager import track_llm_call
+import openai
+
+async def my_openai_call(prompt):
+    response = await openai.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response.choices[0].message.content
+
+# Automatically tracked
+response, session_id = await track_llm_call(
+    user_input="Explain machine learning",
+    llm_function=my_openai_call,
+    model="gpt-3.5-turbo",
+    provider="openai"
+)
+```
+
+### Long Conversations with Auto-Segmentation
+```python
+from chuk_ai_session_manager import track_infinite_conversation
+
+# Start a conversation
+session_id = await track_infinite_conversation(
+    user_message="Tell me about the history of computing",
+    ai_response="Computing history begins with ancient calculating devices...",
+    model="gpt-4",
+    token_threshold=4000  # Auto-segment after 4000 tokens
+)
+
+# Continue the conversation - will auto-segment if needed
+session_id = await track_infinite_conversation(
+    user_message="What about quantum computers?",
+    ai_response="Quantum computing represents a fundamental shift...",
+    session_id=session_id,
+    model="gpt-4"
+)
+```
+
+## 🔧 Configuration
+
+### Storage Configuration
+
+```bash
+# Memory provider (default) - fast, no persistence
+export SESSION_PROVIDER=memory
+
+# Redis provider - persistent, production-ready (requires redis extra)
+export SESSION_PROVIDER=redis
+export SESSION_REDIS_URL=redis://localhost:6379/0
+```
+
+### Installation Matrix
+
+| Command | Memory | Redis | Token Counting | Use Case |
+|---------|--------|-------|----------------|----------|
+| `pip install chuk-ai-session-manager` | ✅ | ❌ | Basic | Development |
+| `pip install chuk-ai-session-manager[redis]` | ✅ | ✅ | Basic | Production |
+| `pip install chuk-ai-session-manager[tiktoken]` | ✅ | ❌ | Enhanced | Better accuracy |
+| `pip install chuk-ai-session-manager[all]` | ✅ | ✅ | Enhanced | Full features |
+
+## 📊 Monitoring & Analytics
+
+```python
+# Get comprehensive session analytics
+stats = await sm.get_stats(include_all_segments=True)
+
+print(f"""
+🚀 Session Analytics Dashboard
+============================
+Session ID: {stats['session_id']}
+Total Messages: {stats['total_messages']}
+User Messages: {stats['user_messages']}
+AI Messages: {stats['ai_messages']}
+Tool Calls: {stats['tool_calls']}
+Total Tokens: {stats['total_tokens']}
+Total Cost: ${stats['estimated_cost']:.6f}
+Session Segments: {stats.get('session_segments', 1)}
+""")
+```
+
+## 🏗️ Why CHUK AI Session Manager?
+
+- **Zero Configuration**: Start tracking conversations in 3 lines of code
+- **Infinite Context**: Never worry about token limits again
+- **Universal**: Works with any LLM provider (OpenAI, Anthropic, etc.)
+- **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
+
+## 🛡️ Error Handling
+
+```python
+from chuk_ai_session_manager import (
+    SessionManagerError,
+    SessionNotFound,
+    TokenLimitExceeded
+)
+
+try:
+    session_id = await track_conversation("Hello", "Hi there")
+except SessionNotFound as e:
+    print(f"Session not found: {e}")
+except TokenLimitExceeded as e:
+    print(f"Token limit exceeded: {e}")
+except SessionManagerError as e:
+    print(f"General session error: {e}")
+```
+
+## 🔄 Dependencies
+
+- **Required**: `chuk-sessions` (session storage), `pydantic` (data models), `chuk-tool-processor` (tool integration)
+- **Optional**: `redis` (Redis storage), `tiktoken` (accurate token counting)
+
+## 📄 License
+
+MIT License - build amazing AI applications with confidence!
+
+---
+
+**Ready to build better AI applications?**
+
+```bash
+pip install chuk-ai-session-manager
+```
+
+**Start tracking conversations in 30 seconds!**

{chuk_ai_session_manager-0.5.dist-info → chuk_ai_session_manager-0.7.dist-info}/RECORD

@@ -1,4 +1,4 @@
-chuk_ai_session_manager/__init__.py,sha256=no7tWD_1TG8b9Zuc52ha5fHtke5YQBraxXA_9xaAsqE,5633
+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
@@ -16,7 +16,7 @@ chuk_ai_session_manager/models/session_event.py,sha256=RTghC9_sDHzD8qdgEYCoclJzp
 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.5.dist-info/METADATA,sha256=AQtoeqt0OvMykMTJYsfxrObeOfnoSyj66RRuBrzoEoM,25537
-chuk_ai_session_manager-0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-chuk_ai_session_manager-0.5.dist-info/top_level.txt,sha256=5RinqD0v-niHuLYePUREX4gEWTlrpgtUg0RfexVRBMk,24
-chuk_ai_session_manager-0.5.dist-info/RECORD,,
+chuk_ai_session_manager-0.7.dist-info/METADATA,sha256=dyL99WC_86DIPfkjLr-q4Dw2kKi-J7olpyaOfyFEsgM,7910
+chuk_ai_session_manager-0.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+chuk_ai_session_manager-0.7.dist-info/top_level.txt,sha256=5RinqD0v-niHuLYePUREX4gEWTlrpgtUg0RfexVRBMk,24
+chuk_ai_session_manager-0.7.dist-info/RECORD,,

chuk_ai_session_manager-0.5.dist-info/METADATA

@@ -1,896 +0,0 @@
-Metadata-Version: 2.4
-Name: chuk-ai-session-manager
-Version: 0.5
-Summary: Session manager for AI applications
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: chuk-sessions>=0.3
-Requires-Dist: chuk-tool-processor>=0.4.1
-Requires-Dist: pydantic>=2.11.3
-Provides-Extra: tiktoken
-Requires-Dist: tiktoken>=0.9.0; extra == "tiktoken"
-Provides-Extra: redis
-Requires-Dist: redis>=4.0.0; extra == "redis"
-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: redis>=4.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"
-Provides-Extra: full
-
-# CHUK AI Session Manager Documentation
-
-A powerful session management system for AI applications that provides automatic conversation tracking, token usage monitoring, tool call logging, infinite context support, and hierarchical session relationships.
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Import Issues & Fixes](#import-issues--fixes)
-3. [Core Architecture](#core-architecture)
-4. [Quick Start](#quick-start)
-5. [Simple API](#simple-api)
-6. [Advanced Usage](#advanced-usage)
-7. [Core Models](#core-models)
-8. [Infinite Context](#infinite-context)
-9. [Tool Integration](#tool-integration)
-10. [Session Storage](#session-storage)
-11. [Prompt Building](#prompt-building)
-12. [Configuration](#configuration)
-
-## Overview
-
-The CHUK AI Session Manager is designed to solve common challenges in AI application development:
-
-- **Conversation Tracking**: Automatically track user-AI interactions
-- **Token Management**: Monitor usage and costs across different models
-- **Infinite Context**: Handle conversations that exceed token limits through automatic summarization
-- **Tool Integration**: Log tool calls and results seamlessly
-- **Session Hierarchy**: Create parent-child relationships between conversation segments
-- **Flexible Storage**: Built on CHUK Sessions for reliable persistence
-
-### Key Features
-
-- **Zero-friction API**: Simple functions for common tasks
-- **Async-first**: Built for modern Python async/await patterns
-- **Token-aware**: Automatic token counting and cost estimation
-- **Provider-agnostic**: Works with any LLM provider (OpenAI, Anthropic, etc.)
-- **Hierarchical sessions**: Support for complex conversation structures
-- **Automatic summarization**: Maintains context across session segments
-
-## Import Structure
-
-With the clean `__init__.py`, all components should be available at the top level:
-
-```python
-from chuk_ai_session_manager import (
-    # Simple API - Primary interface for most users
-    SessionManager,
-    track_conversation,
-    track_llm_call,
-    quick_conversation,
-    track_infinite_conversation,
-    track_tool_use,
-    get_session_stats,
-    get_conversation_history,
-    
-    # Core Models
-    Session,
-    SessionEvent,
-    SessionMetadata,
-    SessionRun,
-    RunStatus,
-    
-    # Enums
-    EventSource,
-    EventType,
-    
-    # Token Management
-    TokenUsage,
-    TokenSummary,
-    
-    # Advanced Components
-    InfiniteConversationManager,
-    SummarizationStrategy,
-    SessionAwareToolProcessor,
-    build_prompt_from_session,
-    PromptStrategy,
-    truncate_prompt_to_token_limit,
-    
-    # Storage
-    setup_chuk_sessions_storage,
-    
-    # Exceptions
-    SessionManagerError,
-    SessionNotFound,
-    SessionAlreadyExists,
-    InvalidSessionOperation,
-    TokenLimitExceeded,
-    StorageError,
-    ToolProcessingError,
-    
-    # Utilities
-    configure_storage,
-    get_version,
-    is_available
-)
-```
-
-### Verifying Installation
-
-Check that everything is working:
-
-```python
-import chuk_ai_session_manager as casm
-
-print(f"Version: {casm.get_version()}")
-print("Available components:", casm.is_available())
-
-# This should show all components as True
-# {
-#   "core_enums": True,
-#   "core_models": True, 
-#   "simple_api": True,
-#   "storage": True,
-#   "infinite_context": True,
-#   "tool_processor": True,
-#   "prompt_builder": True,
-#   "token_tracking": True,
-#   "exceptions": True,
-#   "session_manager": True
-# }
-```
-
-## Core Architecture
-
-The system is built around several key components working together to provide seamless conversation management:
-
-```
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│   Simple API    │    │ SessionManager   │    │ Core Models     │
-│                 │    │                  │    │                 │
-│ track_conversation() │    │ High-level API   │    │ Session         │
-│ track_llm_call()     │    │ Infinite context │    │ SessionEvent    │
-│ quick_conversation() │    │ Auto-summarization│   │ TokenUsage      │
-└─────────────────┘    └──────────────────┘    └─────────────────┘
-         │                       │                       │
-         └───────────────────────┼───────────────────────┘
-                                 │
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│ Tool Processor  │    │ Storage Backend  │    │ Prompt Builder  │
-│                 │    │                  │    │                 │
-│ Session-aware   │    │ CHUK Sessions    │    │ Multiple        │
-│ Tool execution  │    │ JSON persistence │    │ strategies      │
-│ Retry & caching │    │ TTL management   │    │ Token limits    │
-└─────────────────┘    └──────────────────┘    └─────────────────┘
-```
-
-**Key Components:**
-- **Simple API**: One-line functions for common operations
-- **SessionManager**: High-level conversation management with infinite context
-- **Core Models**: Session, SessionEvent, TokenUsage for data modeling
-- **Tool Processor**: Automatic tool call tracking with retry and caching
-- **Storage Backend**: CHUK Sessions for reliable persistence
-- **Prompt Builder**: Intelligent context building for LLM calls
-
-## Quick Start
-
-### Installation
-
-```bash
-# Install the package
-uv add chuk-ai-session-manager
-
-# Or with pip
-pip install chuk-ai-session-manager
-```
-
-### Basic Usage
-
-```python
-from chuk_ai_session_manager import track_conversation
-
-# Track a simple conversation
-session_id = await track_conversation(
-    user_message="What's the weather like?",
-    ai_response="I don't have access to real-time weather data.",
-    model="gpt-3.5-turbo",
-    provider="openai"
-)
-
-print(f"Conversation tracked in session: {session_id}")
-```
-
-### With Statistics
-
-```python
-from chuk_ai_session_manager import quick_conversation
-
-stats = await quick_conversation(
-    user_message="Explain quantum computing",
-    ai_response="Quantum computing uses quantum mechanical phenomena...",
-    model="gpt-4",
-    provider="openai"
-)
-
-print(f"Tokens used: {stats['total_tokens']}")
-print(f"Estimated cost: ${stats['estimated_cost']:.4f}")
-```
-
-### Basic Integration with Your LLM
-
-```python
-from chuk_ai_session_manager import track_llm_call
-import openai
-
-async def my_openai_call(prompt):
-    response = await openai.chat.completions.create(
-        model="gpt-3.5-turbo",
-        messages=[{"role": "user", "content": prompt}]
-    )
-    return response.choices[0].message.content
-
-# Track your LLM call automatically
-response, session_id = await track_llm_call(
-    user_input="Explain machine learning",
-    llm_function=my_openai_call,
-    model="gpt-3.5-turbo",
-    provider="openai"
-)
-
-print(f"AI Response: {response}")
-print(f"Tracked in session: {session_id}")
-```
-
-## Simple API
-
-The Simple API provides convenient functions for common tasks:
-
-```python
-from chuk_ai_session_manager import (
-    track_conversation,
-    track_llm_call,
-    quick_conversation,
-    track_infinite_conversation,
-    track_tool_use,
-    get_session_stats,
-    get_conversation_history
-)
-```
-
-### `track_conversation()`
-
-The simplest way to track a conversation turn - perfect for one-off tracking:
-
-```python
-session_id = await track_conversation(
-    user_message="Hello!",
-    ai_response="Hi there! How can I help?",
-    model="gpt-3.5-turbo",
-    provider="openai",
-    session_id=None,  # Optional: continue existing session
-    infinite_context=False,  # Enable infinite context
-    token_threshold=4000  # Token limit for segmentation
-)
-
-# Returns the session ID for continuing the conversation later
-```
-
-### `track_llm_call()`
-
-Wrap your LLM function calls for automatic tracking:
-
-```python
-async def call_openai(prompt):
-    # Your OpenAI API call here
-    response = await openai.chat.completions.create(
-        model="gpt-3.5-turbo",
-        messages=[{"role": "user", "content": prompt}]
-    )
-    return response.choices[0].message.content
-
-response, session_id = await track_llm_call(
-    user_input="Explain machine learning",
-    llm_function=call_openai,
-    model="gpt-3.5-turbo",
-    provider="openai"
-)
-```
-
-### `track_infinite_conversation()`
-
-For long conversations that might exceed token limits:
-
-```python
-# Start a conversation
-session_id = await track_infinite_conversation(
-    user_message="Tell me about the history of computing",
-    ai_response="Computing history begins with ancient calculating devices...",
-    model="gpt-4",
-    token_threshold=4000,  # Auto-segment after 4000 tokens
-    max_turns=20  # Or after 20 conversation turns
-)
-
-# Continue the conversation
-session_id = await track_infinite_conversation(
-    user_message="What about quantum computers?",
-    ai_response="Quantum computing represents a fundamental shift...",
-    session_id=session_id,  # Continue the same conversation
-    model="gpt-4"
-)
-```
-
-### `track_tool_use()`
-
-Track tool/function calls:
-
-```python
-session_id = await track_tool_use(
-    tool_name="calculator",
-    arguments={"operation": "add", "a": 5, "b": 3},
-    result={"result": 8},
-    session_id=session_id,
-    error=None  # Optional error message
-)
-```
-
-## SessionManager Class
-
-For more control and persistent conversations, use the `SessionManager` class directly:
-
-```python
-from chuk_ai_session_manager import SessionManager
-
-# Create a session manager
-sm = SessionManager(
-    system_prompt="You are a helpful assistant specialized in Python programming.",
-    infinite_context=True,
-    token_threshold=4000,
-    max_turns_per_segment=20
-)
-
-# Track conversations
-await sm.user_says("How do I create a list comprehension?")
-await sm.ai_responds(
-    "A list comprehension is a concise way to create lists in Python...",
-    model="gpt-4",
-    provider="openai"
-)
-
-# Track tool usage
-await sm.tool_used(
-    tool_name="code_executor",
-    arguments={"code": "print([x**2 for x in range(5)])"},
-    result={"output": "[0, 1, 4, 9, 16]"}
-)
-
-# Get session statistics
-stats = await sm.get_stats()
-print(f"Session {stats['session_id']}: {stats['total_messages']} messages, ${stats['estimated_cost']:.4f}")
-```
-
-### Working with System Prompts
-
-```python
-# Set initial system prompt
-sm = SessionManager(system_prompt="You are a creative writing assistant.")
-
-# Update system prompt later
-await sm.update_system_prompt("You are now a technical documentation writer.")
-
-# Get messages including system prompt for your LLM calls
-messages = await sm.get_messages_for_llm(include_system=True)
-# [{"role": "system", "content": "You are now a technical documentation writer."}, ...]
-```
-
-### SessionManager Properties
-
-```python
-sm = SessionManager()
-
-# Access session information
-print(f"Session ID: {sm.session_id}")
-print(f"System Prompt: {sm.system_prompt}")
-print(f"Infinite Context: {sm.is_infinite}")
-
-# Check if this is a new session
-print(f"Is new session: {sm._is_new}")  # Useful for initialization logic
-```
-
-### Managing Long Conversations
-
-```python
-# Enable infinite context with custom settings
-sm = SessionManager(
-    infinite_context=True,
-    token_threshold=3000,  # Segment at 3000 tokens
-    max_turns_per_segment=15  # Or 15 conversation turns
-)
-
-# The session will auto-segment when limits are reached
-# You don't need to do anything - it happens automatically!
-
-# Get full conversation across all segments
-full_conversation = await sm.get_conversation(include_all_segments=True)
-
-# Get session chain (list of session IDs in the conversation)
-session_chain = await sm.get_session_chain()
-print(f"Conversation spans {len(session_chain)} sessions: {session_chain}")
-```
-
-## Core Models
-
-### Session
-
-The main container for a conversation:
-
-```python
-from chuk_ai_session_manager import Session
-
-# Create a new session
-session = await Session.create(
-    parent_id=None,  # Optional parent session
-    metadata={"user_id": "user123", "topic": "programming"}
-)
-
-# Session properties
-print(f"Session ID: {session.id}")
-print(f"Created: {session.metadata.created_at}")
-print(f"Total tokens: {session.total_tokens}")
-print(f"Total cost: ${session.total_cost:.4f}")
-
-# Add events
-from chuk_ai_session_manager.models.session_event import SessionEvent
-from chuk_ai_session_manager.models.event_source import EventSource
-from chuk_ai_session_manager.models.event_type import EventType
-
-event = await SessionEvent.create_with_tokens(
-    message="Hello world!",
-    prompt="Hello world!",
-    model="gpt-3.5-turbo",
-    source=EventSource.USER,
-    type=EventType.MESSAGE
-)
-
-await session.add_event_and_save(event)
-```
-
-### SessionEvent
-
-Individual events within a session:
-
-```python
-from chuk_ai_session_manager import SessionEvent, EventSource, EventType
-
-# Create an event with automatic token counting
-event = await SessionEvent.create_with_tokens(
-    message="What is machine learning?",
-    prompt="What is machine learning?",
-    completion=None,  # For user messages
-    model="gpt-3.5-turbo",
-    source=EventSource.USER,
-    type=EventType.MESSAGE
-)
-
-# Event properties
-print(f"Event ID: {event.id}")
-print(f"Tokens used: {event.token_usage.total_tokens}")
-print(f"Source: {event.source.value}")
-print(f"Type: {event.type.value}")
-
-# Update metadata
-await event.set_metadata("user_id", "user123")
-await event.set_metadata("intent", "question")
-
-# Check metadata
-user_id = await event.get_metadata("user_id")
-has_intent = await event.has_metadata("intent")
-```
-
-### TokenUsage
-
-Tracks token consumption and costs:
-
-```python
-from chuk_ai_session_manager import TokenUsage
-
-# Create from text
-usage = await TokenUsage.from_text(
-    prompt="What is the capital of France?",
-    completion="The capital of France is Paris.",
-    model="gpt-3.5-turbo"
-)
-
-print(f"Prompt tokens: {usage.prompt_tokens}")
-print(f"Completion tokens: {usage.completion_tokens}")
-print(f"Total tokens: {usage.total_tokens}")
-print(f"Estimated cost: ${usage.estimated_cost_usd:.6f}")
-
-# Update token usage
-await usage.update(prompt_tokens=10, completion_tokens=5)
-
-# Count tokens for any text
-token_count = await TokenUsage.count_tokens("Hello world!", "gpt-4")
-```
-
-### Event Source and Type Enums
-
-```python
-from chuk_ai_session_manager import EventSource, EventType
-
-# Event sources
-EventSource.USER     # User input
-EventSource.LLM      # AI model response  
-EventSource.SYSTEM   # System/tool events
-
-# Event types
-EventType.MESSAGE       # Conversation messages
-EventType.TOOL_CALL     # Tool/function calls
-EventType.SUMMARY       # Session summaries
-EventType.REFERENCE     # References to other content
-EventType.CONTEXT_BRIDGE # Context bridging events
-```
-
-## Infinite Context
-
-The infinite context system automatically handles conversations that exceed token limits by creating linked sessions with summaries.
-
-### InfiniteConversationManager
-
-```python
-from chuk_ai_session_manager import (
-    InfiniteConversationManager,
-    SummarizationStrategy,
-    EventSource
-)
-
-# Create manager with custom settings
-icm = InfiniteConversationManager(
-    token_threshold=3000,
-    max_turns_per_segment=15,
-    summarization_strategy=SummarizationStrategy.KEY_POINTS
-)
-
-# Process messages (automatically segments when needed)
-async def my_llm_callback(messages):
-    # Your LLM call here
-    return "Summary of the conversation..."
-
-current_session_id = await icm.process_message(
-    session_id="session-123",
-    message="Tell me about quantum computing",
-    source=EventSource.USER,
-    llm_callback=my_llm_callback,
-    model="gpt-4"
-)
-
-# Build context for LLM calls
-context = await icm.build_context_for_llm(
-    session_id=current_session_id,
-    max_messages=10,
-    include_summaries=True
-)
-
-# Get session chain
-chain = await icm.get_session_chain(current_session_id)
-print(f"Conversation chain: {[s.id for s in chain]}")
-```
-
-### Summarization Strategies
-
-```python
-from chuk_ai_session_manager import SummarizationStrategy
-
-# Different summarization approaches
-SummarizationStrategy.BASIC        # General overview
-SummarizationStrategy.KEY_POINTS   # Focus on key information
-SummarizationStrategy.TOPIC_BASED  # Organize by topics
-SummarizationStrategy.QUERY_FOCUSED # Focus on user questions
-```
-
-## Tool Integration
-
-### SessionAwareToolProcessor
-
-Integrates with `chuk_tool_processor` for automatic tool call tracking:
-
-```python
-from chuk_ai_session_manager import SessionAwareToolProcessor
-
-# Create processor for a session
-processor = await SessionAwareToolProcessor.create(
-    session_id="session-123",
-    enable_caching=True,
-    max_retries=2,
-    retry_delay=1.0
-)
-
-# Process LLM message with tool calls
-llm_response = {
-    "tool_calls": [
-        {
-            "function": {
-                "name": "calculator",
-                "arguments": '{"operation": "add", "a": 5, "b": 3}'
-            }
-        }
-    ]
-}
-
-results = await processor.process_llm_message(llm_response, None)
-for result in results:
-    print(f"Tool: {result.tool}, Result: {result.result}")
-```
-
-### Sample Tools
-
-```python
-# The package includes sample tools for demonstration
-from chuk_ai_session_manager.sample_tools import (
-    CalculatorTool,
-    WeatherTool, 
-    SearchTool
-)
-
-# These are registered with chuk_tool_processor
-# You can see how to structure your own tools
-```
-
-## Session Storage
-
-### CHUK Sessions Backend
-
-The storage is built on CHUK Sessions:
-
-```python
-from chuk_ai_session_manager import (
-    setup_chuk_sessions_storage,
-    SessionStorage,
-    ChukSessionsStore
-)
-
-# Setup storage (usually done automatically)
-backend = setup_chuk_sessions_storage(
-    sandbox_id="my-ai-app",
-    default_ttl_hours=48
-)
-
-# Get the store
-store = ChukSessionsStore(backend)
-
-# Manual session operations
-session = await store.get("session-123")
-await store.save(session)
-await store.delete("session-123")
-session_ids = await store.list_sessions(prefix="user-")
-```
-
-### Storage Configuration
-
-```python
-# Configure storage at import time
-from chuk_ai_session_manager import configure_storage
-
-success = configure_storage(
-    sandbox_id="my-application",
-    default_ttl_hours=72  # 3 day TTL
-)
-
-if success:
-    print("Storage configured successfully")
-else:
-    print("Storage configuration failed")
-```
-
-## Prompt Building
-
-### Building Prompts from Sessions
-
-```python
-from chuk_ai_session_manager import (
-    build_prompt_from_session,
-    PromptStrategy,
-    truncate_prompt_to_token_limit
-)
-
-# Build prompts with different strategies
-prompt = await build_prompt_from_session(
-    session,
-    strategy=PromptStrategy.CONVERSATION,  # Include conversation history
-    max_tokens=3000,
-    model="gpt-4",
-    include_parent_context=True,
-    max_history=10
-)
-
-# Prompt strategies
-PromptStrategy.MINIMAL      # Just task and latest context
-PromptStrategy.TASK_FOCUSED # Focus on the task
-PromptStrategy.TOOL_FOCUSED # Emphasize tool usage
-PromptStrategy.CONVERSATION # Include conversation history
-PromptStrategy.HIERARCHICAL # Include parent session context
-```
-
-### Token Limit Management
-
-```python
-from chuk_ai_session_manager import truncate_prompt_to_token_limit
-
-# Ensure prompt fits within token limits
-truncated_prompt = await truncate_prompt_to_token_limit(
-    prompt=messages,
-    max_tokens=3000,
-    model="gpt-3.5-turbo"
-)
-```
-
-## Configuration
-
-### Package Configuration
-
-```python
-import chuk_ai_session_manager as casm
-
-# Check what's available
-print("Package version:", casm.get_version())
-availability = casm.is_available()
-print("Available components:", availability)
-
-# Configure storage
-success = casm.configure_storage(
-    sandbox_id="my-app",
-    default_ttl_hours=24
-)
-```
-
-### Environment Setup
-
-The package depends on several components:
-
-1. **Required**: `chuk_sessions` - for storage backend
-2. **Required**: `pydantic` - for data models  
-3. **Optional**: `tiktoken` - for accurate token counting (falls back to approximation)
-4. **Optional**: `chuk_tool_processor` - for tool integration
-
-### Error Handling
-
-```python
-from chuk_ai_session_manager import (
-    SessionManagerError,
-    SessionNotFound,
-    TokenLimitExceeded,
-    StorageError
-)
-
-try:
-    session_id = await track_conversation("Hello", "Hi there")
-except SessionNotFound as e:
-    print(f"Session not found: {e}")
-except TokenLimitExceeded as e:
-    print(f"Token limit exceeded: {e}")
-except StorageError as e:
-    print(f"Storage error: {e}")
-except SessionManagerError as e:
-    print(f"General session error: {e}")
-```
-
-## 🌟 What Makes CHUK Special?
-
-| Feature | Other Libraries | CHUK AI Session Manager |
-|---------|----------------|------------------------|
-| **Setup Complexity** | Complex configuration | 3 lines of code |
-| **Cost Tracking** | Manual calculation | Automatic across all providers |
-| **Long Conversations** | Token limit errors | Infinite context with auto-segmentation |
-| **Multi-Provider** | Provider-specific code | Works with any LLM |
-| **Production Ready** | Requires additional work | Built for production |
-| **Learning Curve** | Steep | 5 minutes to productivity |
-| **Tool Integration** | Manual tracking | Automatic tool call logging |
-| **Session Management** | Build from scratch | Complete session hierarchy |
-
-## 🎯 Quick Decision Guide
-
-**Choose CHUK AI Session Manager if you want:**
-- ✅ Simple conversation tracking with zero configuration
-- ✅ Automatic cost monitoring across all LLM providers
-- ✅ Infinite conversation length without token limit errors
-- ✅ Production-ready session management out of the box
-- ✅ Complete conversation analytics and observability
-- ✅ Framework-agnostic solution that works with any LLM library
-- ✅ Built-in tool call tracking and retry mechanisms
-- ✅ Hierarchical session relationships for complex workflows
-
-## 📊 Monitoring & Analytics
-
-```python
-# Get comprehensive session analytics
-stats = await sm.get_stats(include_all_segments=True)
-
-print(f"""
-🚀 Session Analytics Dashboard
-============================
-Session ID: {stats['session_id']}
-Total Messages: {stats['total_messages']}
-User Messages: {stats['user_messages']}
-AI Messages: {stats['ai_messages']}
-Tool Calls: {stats['tool_calls']}
-Total Tokens: {stats['total_tokens']}
-Total Cost: ${stats['estimated_cost']:.6f}
-Session Segments: {stats.get('session_segments', 1)}
-Created: {stats['created_at']}
-Last Update: {stats['last_update']}
-Infinite Context: {stats.get('infinite_context', False)}
-""")
-
-# Get conversation history
-conversation = await sm.get_conversation(include_all_segments=True)
-for i, turn in enumerate(conversation):
-    print(f"{i+1}. {turn['role']}: {turn['content'][:50]}...")
-```
-
-## 🛡️ Error Handling
-
-The package provides specific exceptions for different error conditions:
-
-```python
-from chuk_ai_session_manager import (
-    SessionManagerError,
-    SessionNotFound,
-    TokenLimitExceeded,
-    StorageError
-)
-
-try:
-    session_id = await track_conversation("Hello", "Hi there")
-except SessionNotFound as e:
-    print(f"Session not found: {e}")
-except TokenLimitExceeded as e:
-    print(f"Token limit exceeded: {e}")
-except StorageError as e:
-    print(f"Storage error: {e}")
-except SessionManagerError as e:
-    print(f"General session error: {e}")
-```
-
-## 🔧 Environment Setup
-
-The package requires several dependencies that should be automatically installed:
-
-1. **Required**: `chuk_sessions` - for storage backend
-2. **Required**: `pydantic` - for data models  
-3. **Optional**: `tiktoken` - for accurate token counting (falls back to approximation)
-4. **Optional**: `chuk_tool_processor` - for tool integration
-
-### Dependencies Check
-
-```python
-import chuk_ai_session_manager as casm
-
-# Check if all components are available
-availability = casm.is_available()
-for component, available in availability.items():
-    status = "✅" if available else "❌"
-    print(f"{status} {component}")
-```
-
-## 🤝 Community & Support
-
-- 📖 **Full Documentation**: Complete API reference and tutorials
-- 🐛 **Issues**: Report bugs and request features on GitHub  
-- 💡 **Examples**: Check `/examples` directory for working code
-- 📧 **Support**: Enterprise support available
-
-## 📝 License
-
-MIT License - build amazing AI applications with confidence!
-
----
-
-**🎉 Ready to build better AI applications?**
-
-```bash
-uv add chuk-ai-session-manager
-```
-
-**Get started in 30 seconds with one line of code!**