Context Manager Module

Unified facade for budgeting, compaction, and monitoring agent context

from praisonaiagents import Agent

agent = Agent(
    name="managed-agent",
    instructions="Use the context manager module for precise control.",
    context_window=16000,
)
agent.start("Process this document while managing context carefully.")

The ContextManager orchestrates budgeting, composition, optimisation, and monitoring through one interface.

The user sends a large thread; the context manager budgets tokens and returns an optimised message list for the next LLM call.

How It Works

Quick Start

1. Create a manager

   from praisonaiagents import ContextManager
   
   manager = ContextManager(model="gpt-4o-mini")
   
2. Process messages

   result = manager.process(
       messages=conversation_history,
       system_prompt="You are a helpful assistant.",
       tools=tool_schemas,
   )
   optimized = result["messages"]
   print(f"Tokens saved: {result['tokens_saved']}")
   
3. Inspect utilisation

   stats = manager.get_stats()
   print(f"Utilisation: {stats['utilization']*100:.1f}%")
   

Architecture

Configuration

ManagerConfig

from praisonaiagents import ManagerConfig, EstimationMode

config = ManagerConfig(
    # Auto-compaction
    auto_compact=True,
    compact_threshold=0.8,
    strategy="smart",
    
    # Compression benefit check
    compression_min_gain_pct=5.0,
    compression_max_attempts=3,
    
    # Budget
    output_reserve=8000,
    default_tool_output_max=10000,
    
    # Estimation
    estimation_mode=EstimationMode.HEURISTIC,
    log_estimation_mismatch=False,
    
    # Monitoring
    monitor_enabled=False,
    monitor_path="./context.txt",
    monitor_format="human",
    monitor_write_mode="sync",
    redact_sensitive=True,
)

manager = ContextManager(model="gpt-4o-mini", config=config)

Environment Variables

Variable	Default	Description
PRAISONAI_CONTEXT_AUTO_COMPACT	true	Enable auto-compaction
PRAISONAI_CONTEXT_THRESHOLD	0.8	Compact threshold (0-1)
PRAISONAI_CONTEXT_STRATEGY	smart	Optimization strategy
PRAISONAI_CONTEXT_MONITOR	false	Enable monitoring
PRAISONAI_CONTEXT_ESTIMATION_MODE	heuristic	Token estimation mode

Config Precedence

CLI flags > Environment variables > config.yaml > defaults

Core Methods

process()

Process messages through the full context pipeline:

result = manager.process(
    messages=messages,
    system_prompt="System prompt",
    tools=tools,
    trigger="turn",  # turn, tool_call, manual, overflow
)

# Result contains:
# - messages: Optimized message list
# - optimized: bool - whether optimization occurred
# - tokens_before: int
# - tokens_after: int
# - tokens_saved: int
# - utilization: float (0-1)
# - warnings: List[str]
# - optimization_result: OptimizationResult or None

capture_llm_boundary()

Capture exact state at LLM call boundary for debugging:

hook_data = manager.capture_llm_boundary(messages, tools)

print(f"Message hash: {hook_data.message_hash}")
print(f"Tools hash: {hook_data.tools_hash}")

get_stats()

Get current context statistics:

stats = manager.get_stats()
print(f"Utilization: {stats['utilization']*100:.1f}%")
print(f"Warnings: {stats['warnings']}")

get_resolved_config()

Get fully resolved configuration with source info:

resolved = manager.get_resolved_config()
print(f"Source: {resolved['config']['source']}")
print(f"Precedence: {resolved['precedence']}")

get_history()

Get optimization event history:

history = manager.get_history()
for event in history:
    print(f"{event['timestamp']}: {event['event_type']}")

Per-Tool Budgets

Set custom token budgets per tool:

# Set budget for specific tool
manager.set_tool_budget("file_read", max_tokens=5000, protected=True)

# Get budget for tool
budget = manager.get_tool_budget("file_read")  # 5000

# Truncate output according to budget
truncated = manager.truncate_tool_output("file_read", large_output)

Token Estimation

# Basic estimation
tokens, metrics = manager.estimate_tokens(text)

# With validation (compares heuristic vs accurate)
tokens, metrics = manager.estimate_tokens(text, validate=True)

if metrics:
    print(f"Error: {metrics.error_pct:.1f}%")

Snapshot Callbacks

Register callbacks for LLM boundary snapshots:

def on_snapshot(hook_data):
    print(f"Snapshot at {hook_data.timestamp}")
    print(f"Messages: {len(hook_data.messages)}")

manager.register_snapshot_callback(on_snapshot)

CLI Integration

# Show context stats
praisonai chat
> /context

# Show optimization history
> /context history

# Show resolved config
> /context config

# Trigger manual compaction
> /context compact

Factory Function

Use create_context_manager for proper config precedence:

from praisonaiagents import create_context_manager

manager = create_context_manager(
    model="gpt-4o-mini",
    config_file="config.yaml",
    cli_overrides={"auto_compact": False},
)

---

Best Practices

Enable auto-compact for long sessions

Set auto_compact=True and compact_threshold=0.8 so context stays within model limits without manual /context compact. The praisonai chat / praisonai code interactive CLI honours the same defaults inside its worker loop — no extra wiring required.

Set per-tool output budgets

Use set_tool_budget() on noisy tools like file reads before they flood the context window.

Turn on monitoring for debugging

Enable monitor_enabled and write snapshots to disk when tracing compaction decisions.

Use create_context_manager for precedence

Prefer the factory when mixing CLI flags, env vars, and config.yaml overrides.

---

Related

Context Files

Inject project files into agent context alongside the manager pipeline.

Per-Tool Budgets

Cap individual tool outputs before they reach the manager.

Optimiser

Compression strategies used inside ContextManager.process().

Multi-Agent Policies

Per-agent isolation and handoff sharing rules.