> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Context Budgeter
> Model-aware token budget allocation for context management
The Context Budgeter allocates token budgets across context segments based on model limits and configurable priorities.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, ManagerConfig
agent = Agent(
name="budget-agent",
instructions="Stay within token budgets.",
context=ManagerConfig(output_reserve=16000),
)
agent.start("Summarise this thread without using the full window.")
```
The user configures segment priorities; the budgeter allocates tokens before each model call.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Context Budget Flow"
In[💬 User Request] --> Budgeter[💰 Context Budgeter]
Budgeter --> Alloc[⚙️ Allocate Segments]
Alloc --> Agent[🤖 Agent]
Agent --> Out[✅ Response]
end
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class In agent
class Budgeter,Alloc process
class Agent config
class Out output
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import ManagerConfig
agent = Agent(
instructions="You are helpful.",
context=ManagerConfig(output_reserve=16000),
)
budget = agent.context_manager.get_budget()
print(f"Usable context: {budget.usable:,} tokens")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.context import ContextBudgeter
budgeter = ContextBudgeter(model="gpt-4o-mini")
budget = budgeter.allocate()
print(f"Usable context: {budget.usable:,} tokens")
```
## How the context window is resolved
The model's context window and output reserve resolve in three steps — litellm first, then the static table, then a safe default.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
Model[🏷 Model name] --> L{litellm.model_cost
knows it?}
L -->|Yes| Resolved1[✅ max_input_tokens
from litellm]
L -->|No, has provider/ prefix| Strip[Strip provider prefix
try base name]
Strip --> L2{litellm knows
base name?}
L2 -->|Yes| Resolved2[✅ max_input_tokens
from litellm]
L2 -->|No| Static{Static MODEL_LIMITS
exact or partial match?}
L -->|No prefix| Static
Static -->|Yes| Resolved3[✅ Static value]
Static -->|No| Default[⚠️ default: 128000]
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
classDef warn fill:#8B0000,stroke:#7C90A0,color:#fff
class Model input
class L,L2,Static decision
class Strip process
class Resolved1,Resolved2,Resolved3 ok
class Default warn
```
Any model in litellm's `model_cost` registry — 100+ providers including Mistral, DeepSeek, xAI, Qwen, Bedrock, Azure OpenAI, OpenRouter, and versioned OpenAI/Anthropic/Google ids — resolves to its real window automatically. No config needed.
Provider-prefixed ids (e.g. `openai/gpt-4o`, `anthropic/claude-3-5-sonnet`, `azure/gpt-4o`) fall back to the base model name after the prefix. Lookup is case-insensitive.
When litellm is not installed, the static `MODEL_LIMITS` / `OUTPUT_RESERVES` tables below supply the answer — everything still works offline. `pip install litellm` unlocks the full registry.
### Offline fallback table
| Model | Context Limit | Default Output Reserve |
| ---------------------------------------------- | ------------- | ---------------------- |
| gpt-5, gpt-5-mini, gpt-5-nano | 1,047,576 | 32,768 |
| gpt-4.1, gpt-4.1-mini, gpt-4.1-nano | 1,047,576 | 32,768 |
| gpt-4o, gpt-4o-mini | 128,000 | 16,384 |
| gpt-4-turbo | 128,000 | 4,096 |
| gpt-4 | 8,192 | 4,096 |
| gpt-3.5-turbo | 16,385 | 4,096 |
| o3, o3-mini, o4-mini | 200,000 | 100,000 |
| claude-3-5-sonnet, claude-3-5-haiku | 200,000 | 8,192 |
| claude-3-opus, claude-3-sonnet, claude-3-haiku | 200,000 | 8,192 |
| gemini-2.0-flash, gemini-1.5-flash | 1,048,576 | 8,192 |
| gemini-1.5-pro | 2,097,152 | 8,192 |
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.context import get_model_limit, get_output_reserve
# Consults litellm.model_cost first, then falls back to the static table.
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"}}
from praisonaiagents.context import ContextBudgeter
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"}}
from praisonaiagents.context import ContextBudgeter
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"}}
from praisonaiagents.context import ContextBudgeter
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"}}
from praisonaiagents.context import ContextBudgeter
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': {...}
# }
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Budgeter
User->>Agent: Send request
Agent->>Budgeter: Allocate token budgets
Budgeter-->>Agent: Segment budgets (system, tools, history, etc.)
Agent->>Agent: Trim context to fit budget
Agent-->>User: Response within context window
```
***
## Best Practices
Set `output_reserve` for the model's reply so retrieval and history do not consume the full window.
Pass the actual model id (including any provider prefix like `openai/` or `azure/`) — litellm auto-resolution handles the rest, so limits match the provider's real context window without a manual override.
Trigger compaction or retrieval trimming before hard overflow — do not wait for API errors.
Allocate per-segment budgets when tools return bulky JSON or file contents.
## Related
Track actual token usage by segment
Reduce context when over budget