Praison AI

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
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.

Diagram

Context Budget Flow

💬 User Request

💰 Context Budgeter

⚙️ Allocate Segments

🤖 Agent

✅ Response

Quick Start

  1. Configure via Agent
    python
    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
    python
    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.

Diagram

Yes

No, has provider/ prefix

Yes

No

No prefix

Yes

No

🏷 Model name

litellm.model_cost
knows it?

✅ max_input_tokens
from litellm

Strip provider prefix
try base name

litellm knows
base name?

✅ max_input_tokens
from litellm

Static MODEL_LIMITS
exact or partial match?

✅ Static value

⚠️ default: 128000

Offline fallback table

ModelContext LimitDefault Output Reserve
gpt-5, gpt-5-mini, gpt-5-nano1,047,57632,768
gpt-4.1, gpt-4.1-mini, gpt-4.1-nano1,047,57632,768
gpt-4o, gpt-4o-mini128,00016,384
gpt-4-turbo128,0004,096
gpt-48,1924,096
gpt-3.5-turbo16,3854,096
o3, o3-mini, o4-mini200,000100,000
claude-3-5-sonnet, claude-3-5-haiku200,0008,192
claude-3-opus, claude-3-sonnet, claude-3-haiku200,0008,192
gemini-2.0-flash, gemini-1.5-flash1,048,5768,192
gemini-1.5-pro2,097,1528,192
python
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:

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

python
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
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
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
# Set output reserve
praisonai chat --context-output-reserve 10000

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

Environment Variables

bash
PRAISONAI_CONTEXT_OUTPUT_RESERVE=8000
PRAISONAI_CONTEXT_THRESHOLD=0.8

Serialization

python
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

Diagram
BudgeterAgentUserBudgeterAgentUserSend requestAllocate token budgetsSegment budgets (system, tools, history, etc.)Trim context to fit budgetResponse within context window

Best Practices

Reserve output tokens explicitly

Set output_reserve for the model’s reply so retrieval and history do not consume the full window.

Align budget with your model limit

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.

Monitor utilisation above 80%

Trigger compaction or retrieval trimming before hard overflow — do not wait for API errors.

Segment large tool results

Allocate per-segment budgets when tools return bulky JSON or file contents.

Related

Context Ledger

Track actual token usage by segment

 Context Optimizer

Reduce context when over budget