Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
Context Compaction
Automatically manage context window size by compacting conversation history. Prevent token limit errors while preserving important context.
Quick Start
Agent-Centric Usage
from praisonaiagents import Agent
from praisonaiagents import ManagerConfig
# Agent with context compaction via context= param
agent = Agent(
name="LongChat",
instructions="You are a helpful assistant for extended conversations.",
context=ManagerConfig(
auto_compact=True,
compact_threshold=0.8, # Trigger at 80% usage
strategy="smart", # Options: truncate, sliding_window, summarize, smart
)
)
# Context is automatically compacted during long conversations
response = agent.chat("Let's have a detailed discussion about AI history...")
# Strategies: truncate, sliding_window, prune_tools, summarize, smart
Compaction Strategies
Truncate
Remove oldest messages first:
from praisonaiagents import Agent
from praisonaiagents import ManagerConfig
agent = Agent(
name="Assistant",
instructions="You are helpful.",
context=ManagerConfig(
auto_compact=True,
strategy="truncate",
)
)
Sliding Window
Keep most recent messages within token limit:
agent = Agent(
name="Assistant",
instructions="You are helpful.",
context=ManagerConfig(
auto_compact=True,
strategy="sliding_window",
)
)
Summarize
Replace old messages with a summary:
agent = Agent(
name="Assistant",
instructions="You are helpful.",
context=ManagerConfig(
auto_compact=True,
strategy="summarize",
)
)
Smart
Intelligently select which messages to keep:
agent = Agent(
name="Assistant",
instructions="You are helpful.",
context=ManagerConfig(
auto_compact=True,
strategy="smart",
)
)
Configuration Options
from praisonaiagents.compaction import ContextCompactor, CompactionStrategy
compactor = ContextCompactor(
max_tokens=4000, # Target token limit
strategy=CompactionStrategy.SLIDING,
preserve_system=True, # Keep system messages
preserve_recent=3, # Keep last N messages
preserve_first=1 # Keep first N messages
)
CLI Usage
praisonai compaction status # Show settings
praisonai compaction set sliding # Set strategy
praisonai compaction stats # Show statistics
Low-level API Reference
ContextCompactor Direct Usage
from praisonaiagents.compaction import (
ContextCompactor, CompactionStrategy
)
compactor = ContextCompactor(
max_tokens=4000,
strategy=CompactionStrategy.SLIDING,
preserve_system=True,
preserve_recent=3
)
# Compact messages
messages = [
{"role": "system", "content": "You are helpful."},
{"role": "user", "content": "Hello"},
{"role": "assistant", "content": "Hi there!"},
# ... many more messages
]
compacted, result = compactor.compact(messages)
print(f"Reduced: {result.original_tokens} -> {result.compacted_tokens}")
Checking Stats
# Check if compaction is needed
stats = compactor.get_stats(messages)
print(f"Total tokens: {stats['total_tokens']}")
print(f"Max tokens: {stats['max_tokens']}")
print(f"Needs compaction: {stats['needs_compaction']}")
Compaction Results
compacted, result = compactor.compact(messages)
print(f"Original tokens: {result.original_tokens}")
print(f"Compacted tokens: {result.compacted_tokens}")
print(f"Tokens saved: {result.tokens_saved}")
print(f"Compression ratio: {result.compression_ratio:.1%}")
print(f"Messages kept: {result.messages_kept}")
print(f"Messages removed: {result.messages_removed}")
print(f"Was compacted: {result.was_compacted}")
print(f"Strategy used: {result.strategy_used.value}")
Serialization
# Serialize result
data = result.to_dict()
# Contains all metrics
print(data['compression_ratio'])
# Only loads when accessed
from praisonaiagents.compaction import ContextCompactor
