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

chuk_ai_session_manager-0.7.1/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: chuk-ai-session-manager
+Version: 0.7.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: 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.7.1/README.md

@@ -0,0 +1,236 @@
+# 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 → chuk_ai_session_manager-0.7.1}/pyproject.toml

@@ -4,30 +4,45 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-ai-session-manager"
-version = "0.5"
+version = "0.7.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.3",
-    "chuk-tool-processor>=0.4.1",
+    "chuk-sessions>=0.4.2",
+    "chuk-tool-processor>=0.4.1", 
     "pydantic>=2.11.3",
 ]
 
 # Optional dependencies
 [project.optional-dependencies]
+# Redis support (passes through to chuk-sessions)
+redis = [
+    "chuk-sessions[redis]>=0.4.1",
+    "redis>=4.0.0"
+]
+
+# Token counting for better accuracy
 tiktoken = ["tiktoken>=0.9.0"]
-redis = ["redis>=4.0.0"]
+
+# Development dependencies
 dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
-    "pytest-asyncio>=0.21.0",  # Essential for async tests
-    "redis>=4.0.0",
+    "pytest-asyncio>=0.21.0",
     "black>=23.0.0",
     "isort>=5.12.0",
     "mypy>=1.0.0",
 ]
-full = []
+
+# All optional features
+all = [
+    "chuk-sessions[redis]>=0.4",
+    "redis>=4.0.0",
+    "tiktoken>=0.9.0",
+]
 
 # Configure setuptools for src/ layout
 [tool.setuptools.packages.find]

{chuk_ai_session_manager-0.5 → chuk_ai_session_manager-0.7.1}/src/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")