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

> Model-aware token budget allocation for context management

# Context Budgeter

The Context Budgeter allocates token budgets across context segments based on model limits and configurable priorities.

## Agent-Centric Quick Start

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

# Configure output reserve via context param
agent = Agent(
    instructions="You are helpful.",
    context=ManagerConfig(
        output_reserve=16000,  # Reserve 16k tokens for output
    ),
)

# Access budget info
budget = agent.context_manager.get_budget()
print(f"Usable context: {budget.usable:,} tokens")
```

## Low-Level API

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

# Create budgeter for your model
budgeter = ContextBudgeter(model="gpt-4o-mini")
budget = budgeter.allocate()

print(f"Model limit: {budget.model_limit:,} tokens")
print(f"Output reserve: {budget.output_reserve:,} tokens")
print(f"Usable context: {budget.usable:,} tokens")
```

## Model Limits

| Model            | Context Limit | Default Output Reserve |
| ---------------- | ------------- | ---------------------- |
| gpt-4o           | 128,000       | 16,384                 |
| gpt-4o-mini      | 128,000       | 16,384                 |
| gpt-4-turbo      | 128,000       | 4,096                  |
| claude-3-opus    | 200,000       | 8,192                  |
| claude-3-sonnet  | 200,000       | 8,192                  |
| gemini-1.5-pro   | 2,097,152     | 8,192                  |
| gemini-1.5-flash | 1,048,576     | 8,192                  |

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

limit = get_model_limit("gpt-4o-mini")  # 128000
reserve = get_output_reserve("gpt-4o-mini")  # 16384
```

## Budget Allocation

Default segment budgets:

| Segment       | Default Budget | Purpose              |
| ------------- | -------------- | -------------------- |
| System Prompt | 2,000          | Agent instructions   |
| Rules         | 500            | Workspace rules      |
| Skills        | 500            | Skill definitions    |
| Memory        | 1,000          | Persistent memory    |
| Tools Schema  | 2,000          | Tool definitions     |
| Tool Outputs  | 20,000         | Tool call results    |
| Buffer        | 1,000          | Safety margin        |
| History       | Remainder      | Conversation history |

## Custom Budgets

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
budgeter = ContextBudgeter(
    model="gpt-4o",
    system_prompt_budget=3000,
    rules_budget=1000,
    skills_budget=500,
    memory_budget=5000,
    tools_schema_budget=3000,
    tool_outputs_budget=30000,
    buffer_budget=2000,
)
budget = budgeter.allocate()
```

## Overflow Detection

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
budgeter = ContextBudgeter(model="gpt-4o-mini")

# Check if current usage exceeds budget
current_tokens = 100000
is_overflow = budgeter.check_overflow(current_tokens)

# Get utilization percentage
utilization = budgeter.get_utilization(current_tokens)
print(f"Utilization: {utilization:.1%}")

# Get remaining capacity
remaining = budgeter.get_remaining(current_tokens)
print(f"Remaining: {remaining:,} tokens")
```

## Threshold-Based Triggers

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
budgeter = ContextBudgeter(model="gpt-4o-mini")
budget = budgeter.allocate()

# Trigger optimization at 80% utilization
threshold = 0.8
trigger_at = int(budget.usable * threshold)

current_tokens = 95000
if current_tokens > trigger_at:
    print("Time to optimize!")
```

## CLI Configuration

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Set output reserve
praisonai chat --context-output-reserve 10000

# Set optimization threshold
praisonai chat --context-threshold 0.8
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
PRAISONAI_CONTEXT_OUTPUT_RESERVE=8000
PRAISONAI_CONTEXT_THRESHOLD=0.8
```

## Serialization

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
budgeter = ContextBudgeter(model="gpt-4o-mini")
budget_dict = budgeter.to_dict()

# Returns:
# {
#     'model': 'gpt-4o-mini',
#     'model_limit': 128000,
#     'output_reserve': 16384,
#     'usable': 111616,
#     'allocation': {...}
# }
```

## Next Steps

* [Context Ledger](/docs/features/context-ledger) - Track actual token usage
* [Context Optimizer](/docs/features/context-optimizer) - Reduce when over budget