Skip to main content
The Context Budgeter allocates token budgets across context segments based on model limits and configurable priorities. 
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.

​
Quick Start

1

Configure via Agent

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")
2

Use the budgeter directly

from praisonaiagents.context import ContextBudgeter

budgeter = ContextBudgeter(model="gpt-4o-mini")
budget = budgeter.allocate()
print(f"Usable context: {budget.usable:,} tokens")

​
Model Limits

ModelContext LimitDefault Output Reserve
gpt-4o128,00016,384
gpt-4o-mini128,00016,384
gpt-4-turbo128,0004,096
claude-3-opus200,0008,192
claude-3-sonnet200,0008,192
gemini-1.5-pro2,097,1528,192
gemini-1.5-flash1,048,5768,192
from praisonaiagents.context 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:
SegmentDefault BudgetPurpose
System Prompt2,000Agent instructions
Rules500Workspace rules
Skills500Skill definitions
Memory1,000Persistent memory
Tools Schema2,000Tool definitions
Tool Outputs20,000Tool call results
Buffer1,000Safety margin
HistoryRemainderConversation history

​
Custom Budgets

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

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

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

# Set output reserve
praisonai chat --context-output-reserve 10000

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

​
Environment Variables

PRAISONAI_CONTEXT_OUTPUT_RESERVE=8000
PRAISONAI_CONTEXT_THRESHOLD=0.8

​
Serialization

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

​
Best Practices

Set output_reserve for the model’s reply so retrieval and history do not consume the full window.
Pass the correct model name so limits match the provider’s context window.
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.

Context Ledger

Track actual token usage by segment

Context Optimizer

Reduce context when over budget