Context API¶

API reference for conversation context management and strategies.

ContextManager¶

Manages conversation history and context for LLM interactions.

Constructor¶

ContextManager(
    max_tokens: int = 4096,
    system_prompt: Optional[str] = None
)

Parameters:

max_tokens - Maximum context size in tokens
system_prompt - System instructions for LLM

Methods¶

add_message()¶

def add_message(self, message: Message, conversation_id: str) -> None

Add SPADE message to conversation context.

Example:

context = ContextManager(system_prompt="You are helpful")
context.add_message(spade_message, "user1_session")

add_message_dict()¶

def add_message_dict(self, message_dict: ContextMessage, conversation_id: str) -> None

Add message from dictionary format.

Example:

user_msg = {"role": "user", "content": "Hello!"}
context.add_message_dict(user_msg, "user1_session")

add_assistant_message()¶

def add_assistant_message(self, content: str, conversation_id: Optional[str] = None) -> None

Add assistant response to context.

Example:

context.add_assistant_message("Hello! How can I help?", "user1_session")

add_tool_result()¶

def add_tool_result(
    self, 
    tool_name: str, 
    result: Any, 
    tool_call_id: str, 
    conversation_id: Optional[str] = None
) -> None

Add tool execution result to context.

Example:

context.add_tool_result(
    tool_name="get_weather",
    result="22°C, sunny",
    tool_call_id="call_123",
    conversation_id="user1_session"
)

get_prompt()¶

def get_prompt(self, conversation_id: Optional[str] = None) -> List[ContextMessage]

Get formatted prompt for LLM provider.

Example:

prompt = context.get_prompt("user1_session")
# Returns list of messages formatted for LLM

get_conversation_history()¶

def get_conversation_history(self, conversation_id: Optional[str] = None) -> List[ContextMessage]

Get raw conversation history.

Example:

history = context.get_conversation_history("user1_session")
print(f"Conversation has {len(history)} messages")

clear()¶

def clear(self, conversation_id: Optional[str] = None) -> None

Clear conversation messages.

Example:

# Clear specific conversation
context.clear("user1_session")

# Clear all conversations
context.clear("all")

get_active_conversations()¶

def get_active_conversations(self) -> List[str]

Get list of active conversation IDs.

Example:

conversations = context.get_active_conversations()
print(f"Active conversations: {conversations}")

set_current_conversation()¶

def set_current_conversation(self, conversation_id: str) -> bool

Set current conversation context.

Example:

success = context.set_current_conversation("user1_session")

Example Usage¶

from spade_llm.context import ContextManager

# Create context manager
context = ContextManager(
    system_prompt="You are a helpful coding assistant",
    max_tokens=2000
)

# Add conversation messages
context.add_message_dict(
    {"role": "user", "content": "Help me with Python"}, 
    "coding_session"
)

context.add_assistant_message(
    "I'd be happy to help with Python!", 
    "coding_session"
)

# Get formatted prompt
prompt = context.get_prompt("coding_session")
# Use with LLM provider

Context Management Strategies¶

ContextManagement (Abstract Base)¶

Base class for all context management strategies.

from spade_llm.context.management import ContextManagement

apply_context_strategy()¶

def apply_context_strategy(
    self, 
    messages: List[ContextMessage], 
    system_prompt: Optional[str] = None
) -> List[ContextMessage]

Apply the context management strategy to messages.

get_stats()¶

def get_stats(self, total_messages: int) -> Dict[str, Any]

Get statistics about context management.

NoContextManagement¶

Preserves all messages without any filtering.

from spade_llm.context import NoContextManagement

context = NoContextManagement()

WindowSizeContext¶

Basic sliding window context management.

from spade_llm.context import WindowSizeContext

context = WindowSizeContext(max_messages=20)

Parameters: - max_messages (int): Maximum number of messages to keep

SmartWindowSizeContext¶

Context management with message selection.

from spade_llm.context import SmartWindowSizeContext

context = SmartWindowSizeContext(
    max_messages=20,
    preserve_initial=3,
    prioritize_tools=True
)

Parameters: - max_messages (int): Maximum number of messages to keep - preserve_initial (int, optional): Number of initial messages to always preserve - prioritize_tools (bool, optional): Whether to prioritize tool result messages

Example:

# Smart context with tool prioritization
smart_context = SmartWindowSizeContext(
    max_messages=25,
    preserve_initial=3,
    prioritize_tools=True
)

# Get statistics
stats = smart_context.get_stats(total_messages=50)
# Returns: {"strategy": "smart_window_size", "max_messages": 25, ...}

Message Types¶

ContextMessage Types¶

from spade_llm.context._types import (
    SystemMessage,
    UserMessage, 
    AssistantMessage,
    ToolResultMessage
)

SystemMessage¶

{
    "role": "system",
    "content": "You are a helpful assistant"
}

UserMessage¶

{
    "role": "user",
    "content": "Hello, how are you?",
    "name": "user@example.com"  # Optional
}

AssistantMessage¶

# Text response
{
    "role": "assistant",
    "content": "I'm doing well, thank you!"
}

# With tool calls
{
    "role": "assistant", 
    "content": None,
    "tool_calls": [
        {
            "id": "call_123",
            "type": "function",
            "function": {
                "name": "get_weather",
                "arguments": "{\"city\": \"Madrid\"}"
            }
        }
    ]
}

ToolResultMessage¶

{
    "role": "tool",
    "content": "Weather in Madrid: 22°C, sunny",
    "tool_call_id": "call_123"
}