Session Management¶
Oblix provides built-in session management capabilities to handle conversational interactions with AI models. This page explains how sessions work and how to use them effectively.
What are Sessions?¶
Sessions in Oblix are persistent containers for conversation history that:
- Store messages between users and AI models
- Maintain context across multiple interactions
- Persist across application restarts
- Enable stateful conversations
Sessions are particularly useful for building chat applications, virtual assistants, or any interactive AI experience where context matters.
Session Lifecycle¶
A typical session lifecycle includes:
- Creation - A new session is created with a unique ID
- Message Exchange - User and AI messages are added to the session
- Context Maintenance - Context is preserved between interactions
- Persistence - Session data is saved to disk
- Retrieval - Sessions can be loaded by ID for continued interaction
- Deletion - Sessions can be deleted when no longer needed
Working with Sessions¶
Creating a Session¶
from oblix import OblixClient
client = OblixClient(oblix_api_key="your_api_key")
# Create a new session
session_id = await client.create_session(
title="Customer Support Chat",
initial_context={"customer_id": "cust_123", "subscription_tier": "premium"}
)
print(f"Created session: {session_id}")
Executing Prompts in a Session¶
# Set the current session
client.current_session_id = session_id
# Execute prompts in the session context
response = await client.execute("Hello, I'm having trouble with my account")
# The context is automatically maintained
follow_up_response = await client.execute("Can you help me reset my password?")
Using Chat Methods¶
For chat applications, Oblix provides simplified methods:
# Send a single message in a session
response = await client.chat_once("Hello, how can I help you today?")
session_id = response["session_id"]
# Continue the conversation in the same session
response = await client.chat_once("I need help with my subscription", session_id)
Interactive Chat Sessions¶
For command-line or interactive applications:
# Start an interactive chat session
await client.start_chat()
# Or resume an existing session
await client.start_chat(session_id="existing_session_id")
Managing Sessions¶
Oblix provides methods to list, load, and delete sessions:
# List recent sessions
sessions = client.list_sessions(limit=10)
for session in sessions:
print(f"ID: {session['id']} | Title: {session['title']} | Messages: {session['message_count']}")
# Load a specific session
session_data = client.load_session("session_id_here")
# Delete a session
success = client.delete_session("session_id_here")
Session Storage¶
By default, Oblix stores sessions as JSON files in a local directory:
- Default location:
~/.oblix/sessions/
- Format: Each session is stored as a separate JSON file
- Naming: Files are named using the session ID
You can customize the storage location:
from oblix.sessions import SessionManager
# Custom session directory
session_manager = SessionManager(base_dir="/path/to/custom/directory")
# Use with client
client = OblixClient(oblix_api_key="your_api_key")
client.session_manager = session_manager
Session Structure¶
Each session contains:
- ID: Unique identifier for the session
- Title: Human-readable title for the session
- Created/Updated: Timestamps for creation and last update
- Messages: Array of message objects with:
- Role: 'user' or 'assistant'
- Content: Message text
- Timestamp: When the message was added
- Context: Optional dictionary for additional context
Example session structure:
{
"id": "5f3e9a7b-6c1d-4d8e-9e7a-9b8c7d6e5f4a",
"title": "Technical Support Chat",
"created_at": "2023-07-15T14:30:22.123Z",
"updated_at": "2023-07-15T14:35:46.789Z",
"messages": [
{
"id": "msg_1",
"role": "user",
"content": "I'm having trouble installing the software.",
"timestamp": "2023-07-15T14:30:22.123Z"
},
{
"id": "msg_2",
"role": "assistant",
"content": "I'm sorry to hear that. What operating system are you using?",
"timestamp": "2023-07-15T14:30:25.456Z"
},
{
"id": "msg_3",
"role": "user",
"content": "I'm using Windows 11.",
"timestamp": "2023-07-15T14:35:46.789Z"
}
],
"context": {
"user_id": "user_789",
"product": "Oblix SDK"
}
}
Context Management¶
Sessions maintain conversation history, which is used as context for future interactions. By default, Oblix includes recent messages when generating responses, allowing models to understand the conversation flow.
You can also provide additional context when creating a session:
# Create session with initial context
session_id = await client.create_session(
initial_context={
"user_name": "Alex",
"preferences": {
"language": "English",
"format": "concise"
}
}
)
Model Consistency in Sessions¶
When using sessions with multiple available models, Oblix attempts to maintain consistency by:
- Using the same model for all messages in a session when possible
- Falling back to alternative models only when necessary
- Including sufficient context to maintain conversation flow even when switching models
Advanced Session Features¶
Session Metadata¶
You can access and update session metadata:
# Get session data
session_data = client.load_session(session_id)
# Access metadata
title = session_data["title"]
created_at = session_data["created_at"]
message_count = len(session_data["messages"])
Message Filtering¶
When working with long conversations, you can filter messages:
# Get only the most recent messages
recent_messages = session_data["messages"][-5:]
# Filter by role
user_messages = [msg for msg in session_data["messages"] if msg["role"] == "user"]
Context Window Management¶
For long conversations that might exceed model context windows, Oblix automatically:
- Selects the most relevant messages as context
- Prioritizes recent messages
- Includes critical context from earlier in the conversation
Best Practices¶
When working with sessions:
- Create dedicated sessions for different conversation types
- Include relevant initial context to guide the conversation
- Clean up old sessions to manage storage
- Monitor session length for very long conversations
- Consider model consistency when choosing models for sessions
By effectively using Oblix's session management capabilities, you can build conversational AI applications that maintain context and provide a natural, coherent user experience.