> ## 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 Optimizer

> Strategies for reducing context size when approaching model limits

# Context Optimizer

The Context Optimizer provides multiple strategies for reducing context size when approaching model limits, preventing overflow errors and reducing costs.

## Agent-Centric Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import ManagerConfig

# Configure optimization strategy via context param
agent = Agent(
    instructions="You are helpful.",
    context=ManagerConfig(
        auto_compact=True,
        compact_threshold=0.8,  # Trigger at 80% usage
        strategy="smart",  # truncate, sliding_window, prune_tools, summarize, smart
    ),
)

# Optimization happens automatically when threshold is reached
response = agent.chat("Hello!")
```

## Optimization Strategies

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    A[Messages] --> B{Strategy}
    B -->|truncate| C[Remove Oldest]
    B -->|sliding_window| D[Keep Recent N]
    B -->|prune_tools| E[Truncate Tool Outputs]
    B -->|summarize| F[LLM Summary]
    B -->|non_destructive| G[Tag & Exclude]
    B -->|smart| H[Smart 4-Step]
    C --> I[Optimized]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I
```

### Smart Strategy Flow (Default)

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart TD
    A[Over Budget?] -->|Yes| B[Step 1: Summarize Tool Outputs]
    B --> C{Under Budget?}
    C -->|Yes| D[Done]
    C -->|No| E[Step 2: Truncate Tool Outputs]
    E --> F{Under Budget?}
    F -->|Yes| D
    F -->|No| G[Step 3: Sliding Window]
    G --> H{Under Budget?}
    H -->|Yes| D
    H -->|No| I[Step 4: Summarize Conversation]
    I --> D
```

## Low-Level API

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import get_optimizer, OptimizerStrategy

# Get an optimizer
optimizer = get_optimizer(OptimizerStrategy.SMART)

# Optimize messages to target token count
messages = [...]  # Your conversation history
optimized, stats = optimizer.optimize(messages, target_tokens=50000)

print(f"Reduced from {len(messages)} to {len(optimized)} messages")
print(f"Saved {stats.tokens_saved} tokens")
```

## Strategy Reference

### Truncate

Removes oldest messages first, preserving system prompt and recent context.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import TruncateOptimizer

optimizer = TruncateOptimizer()
result, stats = optimizer.optimize(messages, target_tokens=10000)
```

**Best for**: Simple cases where old context is not important.

### Sliding Window

Keeps the N most recent messages within a token window.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import SlidingWindowOptimizer

optimizer = SlidingWindowOptimizer()
result, stats = optimizer.optimize(messages, target_tokens=10000)
```

**Best for**: Conversations where recent context matters most.

### Prune Tools

Truncates old tool outputs while preserving recent ones.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import PruneToolsOptimizer

optimizer = PruneToolsOptimizer(
    protect_recent=5,  # Keep last 5 tool outputs intact
    max_output_tokens=500,  # Truncate older outputs to 500 tokens
)
result, stats = optimizer.optimize(messages, target_tokens=10000)
```

**Best for**: Tool-heavy conversations with large outputs.

### Summarize

Uses LLM to create a summary of older conversation.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import SummarizeOptimizer

optimizer = SummarizeOptimizer(
    keep_recent=4,  # Keep last 4 turns intact
    model="gpt-4o-mini",
)
result, stats = optimizer.optimize(messages, target_tokens=10000)
```

**Best for**: Long conversations where context continuity matters.

### Non-Destructive

Tags messages for exclusion without deleting them (enables undo).

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import NonDestructiveOptimizer

optimizer = NonDestructiveOptimizer()
result, stats = optimizer.optimize(messages, target_tokens=10000)

# Messages are tagged with 'excluded': True
# Use get_effective_history() to filter
```

**Best for**: When you need to preserve full history for audit/undo.

### Smart (Recommended)

Combines all strategies intelligently based on content analysis.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import SmartOptimizer

optimizer = SmartOptimizer()
result, stats = optimizer.optimize(messages, target_tokens=10000)
```

**Order of operations** (Smart Strategy):

1. **Summarize tool outputs** - Uses LLM to intelligently summarize large tool outputs (preserves key info)
2. **Truncate tool outputs** - Fallback truncation for remaining large outputs
3. **Sliding window** - Remove oldest messages
4. **Summarize conversation** - LLM summary of older conversation if still over limit

<Note>
  Tool output summarization uses LLM to preserve key information instead of blindly truncating. This is enabled by default when `llm_summarize=True`.
</Note>

## Factory Function

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import get_optimizer, OptimizerStrategy

# Available strategies
strategies = [
    OptimizerStrategy.TRUNCATE,
    OptimizerStrategy.SLIDING_WINDOW,
    OptimizerStrategy.PRUNE_TOOLS,
    OptimizerStrategy.SUMMARIZE,
    OptimizerStrategy.NON_DESTRUCTIVE,
    OptimizerStrategy.SMART,
]

for strategy in strategies:
    optimizer = get_optimizer(strategy)
    result, stats = optimizer.optimize(messages, target_tokens=10000)
    print(f"{strategy.value}: {len(result)} messages")
```

## Optimization Result

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import OptimizationResult

# stats returned from optimize()
stats: OptimizationResult
print(f"Original tokens: {stats.original_tokens}")
print(f"Optimized tokens: {stats.optimized_tokens}")
print(f"Tokens saved: {stats.tokens_saved}")
print(f"Strategy used: {stats.strategy_used}")
print(f"Messages removed: {stats.messages_removed}")
print(f"Tool outputs pruned: {stats.tool_outputs_pruned}")
print(f"Tool outputs summarized: {stats.tool_outputs_summarized}")
print(f"Tokens saved by summarization: {stats.tokens_saved_by_summarization}")
print(f"Tokens saved by truncation: {stats.tokens_saved_by_truncation}")
```

## Tool Call Preservation

The optimizer preserves tool\_call/tool\_result pairs to maintain API validity:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# These pairs are kept together or removed together
{"role": "assistant", "tool_calls": [{"id": "call_123", ...}]}
{"role": "tool", "tool_call_id": "call_123", "content": "..."}
```

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Set optimization strategy
praisonai chat --context-strategy smart

# Set trigger threshold
praisonai chat --context-threshold 0.8

# Manual optimization in session
/context compact
```

## Configuration

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# config.yaml
context:
  auto_compact: true
  compact_threshold: 0.8
  strategy: smart
```

## Next Steps

* [Context Monitor](/docs/features/context-monitor) - Watch optimization in action
* [Context Budgeter](/docs/features/context-budgeter) - Set up budgets