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

# Token Budgeting

> Dynamic token budget management for large context handling

Token budgeting keeps retrieved context within each model's window so agents never overflow the context limit.

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

agent = Agent(
    name="Researcher",
    instructions="Answer from the knowledge base.",
    knowledge=KnowledgeConfig(sources=["./docs"], retrieval_k=5),
)
agent.start("What are the key features?")
```

The user asks a knowledge-heavy question; token budgeting trims retrieved chunks so the prompt stays within the model window.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Token Budget Flow"
        Agent[🤖 Agent] --> Budget[📊 TokenBudget]
        Budget --> Context[📄 Context Chunks]
        Context --> LLM[💬 LLM Response]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef budget fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef context fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef response fill:#10B981,stroke:#7C90A0,color:#fff

    class Agent agent
    class Budget budget
    class Context context
    class LLM response
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Token Budgeting

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

> [!NOTE]
>
> **Async enforcement (1.6.88+):** `ExecutionConfig(max_budget=...)` is now enforced on async agent runs (`astart()`) as well as sync runs. `BudgetExceededError` is raised on both paths when the cap is exceeded. Gateway bots also honour the budget.

## Quick Start

**1. Agent with Knowledge**

Knowledge retrieval applies token budgets automatically when indexing and retrieving.

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

agent = Agent(
    name="BudgetAwareAgent",
    instructions="Answer questions using the knowledge base.",
    knowledge=KnowledgeConfig(sources=["./docs"], retrieval_k=5),
)
agent.start("What are the key features?")
```

**2. Long-Context Model (gpt-5)**

Pass a model name and the window resolves automatically — gpt-5 unlocks the full 1M context.

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

# Simplest agent-centric usage — model resolves to the 1M window
agent = Agent(
    name="LongContextAgent",
    instructions="Answer using the full document.",
    llm="gpt-5",
)

# Under the hood
budget = TokenBudget(model="gpt-5")
print(budget.model_context_window)  # 1047576
```

**3. Direct Budget Control**

Use `TokenBudget` when building custom RAG pipelines.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.rag import TokenBudget, DefaultBudgetEnforcer

budget = TokenBudget(model="gpt-4o-mini")
available = budget.dynamic_budget(system_tokens=500, history_tokens=1000)

enforcer = DefaultBudgetEnforcer()
chunks = ["chunk one...", "chunk two...", "chunk three..."]
enforced = enforcer.enforce(budget, chunks)
print(f"Kept {len(enforced)} of {len(chunks)} chunks ({available} tokens available)")
```

## Configuration

### TokenBudget Options

| Option | Type | Default | Description |
| - | - | - | - |
| `model` | `str` | `"gpt-4o-mini"` | Model name for context window lookup |
| `reserved_response` | `int` | `4096` | Tokens reserved for the LLM response |
| `reserved_system` | `int` | `500` | Tokens reserved for system prompt |
| `reserved_history` | `int` | `1000` | Tokens reserved for chat history |

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

budget = TokenBudget(
    model="gpt-4o",
    reserved_response=4096,
    reserved_system=1000,
    reserved_history=2000,
)
print(budget.model_context_window)  # 128000
print(budget.max_context_tokens)
```

### Model Context Windows

| Model | Context Window |
| - | - |
| gpt-5, gpt-5-mini, gpt-5-nano | 1,047,576 |
| gpt-4.1, gpt-4.1-mini, gpt-4.1-nano | 1,047,576 |
| gpt-4o, gpt-4o-mini | 128,000 |
| gpt-4-turbo | 128,000 |
| gpt-4 | 8,192 |
| gpt-4-32k | 32,768 |
| gpt-3.5-turbo | 16,385 |
| o3, o3-mini, o4-mini | 200,000 |
| o1 | 200,000 |
| o1-mini, o1-preview | 128,000 |
| claude-3-5-sonnet, claude-3-5-haiku | 200,000 |
| claude-3-opus, claude-3-sonnet, claude-3-haiku | 200,000 |
| gemini-1.5-pro | 2,097,152 |
| gemini-1.5-flash, gemini-2.0-flash | 1,048,576 |

> [!NOTE]
>
> RAG context-window values are sourced from a single canonical `MODEL_LIMITS` table shared with the rest of the SDK; RAG-only extras (Mistral, Llama, DeepSeek, Cohere, o1 variants, gpt-4-32k) are layered on top. Values here match `get_model_context_window()` exactly — pass any model name and get the same window everywhere.

> [!NOTE]
>
> As of PraisonAI PR #3796, the shared context-window lookup consults litellm's `model_cost` registry first, so any litellm-known model (Mistral, DeepSeek, xAI, Qwen, Bedrock, Azure, OpenRouter, versioned OpenAI/Anthropic/Google ids) resolves to its true window even when it is not in the table below. The static table is the offline fallback. See [How the context window is resolved](https://praison.ai/docs/features/context-budgeter.md#how-the-context-window-is-resolved) for the full order.

> [!NOTE]
>
> Unknown or versioned model names resolve via partial match (e.g. `gpt-4o-2024-05-13` → `gpt-4o`). The default 128,000 tokens only applies when **both** litellm and the static partial-match miss.

## Budget Enforcement

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.rag import TokenBudget, DefaultBudgetEnforcer

budget = TokenBudget(model="gpt-4o-mini")
enforcer = DefaultBudgetEnforcer()

chunks = ["chunk1 content...", "chunk2 content...", "chunk3 content..."]
enforced_chunks = enforcer.enforce(budget, chunks)
```

Implement `BudgetEnforcerProtocol` for priority-based or custom selection strategies.

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai knowledge stats --json
praisonai knowledge index ./docs --verbose
```

***

## Best Practices

> [accordion] Reserve adequate response tokens
>
> Leave enough headroom for complete answers — undersized `reserved_response` truncates outputs mid-sentence.

> [accordion] Account for chat history
>
> Multi-turn conversations consume tokens quickly; increase `reserved_history` or enable context compaction on long sessions.

> [accordion] Match budget to model
>
> Different models have different context windows — always pass the actual model name so `dynamic_budget()` calculates correctly.

> [accordion] Monitor with verbose indexing
>
> Run `praisonai knowledge index ./docs --verbose` to see chunk counts and token estimates before production retrieval.

***

## Related

> [card] [Thinking Budgets](https://praison.ai/docs/features/thinking-budgets.md)
>
> Extended reasoning token limits

> [card] [Token Usage Protocol](https://praison.ai/docs/features/token-usage-protocol.md)
>
> Track token consumption across runs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.