Skip to main content

Context budget

The Context budget screen (page title Context budget planner) lets you plan how the context window of a model is shared between the input segments, the output, the reasoning and a safety margin, and compute the plan with the Context Manager of the Control Plane. Portal path: /llm/context. It is used by developers and AI platform engineers who size prompts, history and retrieval. The screen is built in portal/src/screens/llm-tools.tsx (ContextPlanner) with the local computation of portal/src/lib/context-budget.ts.

What the screen shows​

The section Budget formula ("W is the model context window. The remaining budget is what you can spend on prompts, history and retrieval."):

  • the formula B_context = W - B_out - B_reasoning - B_safety with the current values and the result (red when the reserved budgets exceed the window);
  • four number fields: Window W (default 200000), Output B_out (8192), Reasoning B_reasoning (8192), Safety B_safety (2048);
  • a bar with the legend Used by segments, Output B_out, Reasoning B_reasoning, Safety B_safety;
  • three cards: Available B_context, Used by segments, Overflow (red when above zero);
  • the messages "Reserved budgets exceed the window: reduce output, reasoning or safety." or "Segments exceed the budget: the Context Manager will compress or drop segments."

The section Segments: one line per segment with its name and its Tokens (default system 1500, history 42000, retrieval 60000, tools 6000), a remove button per line, Add segment, then Compute the plan with the API and the JSON answer.

Everything in Budget formula is computed in the browser, without any call.

Actions​

Button or actionWhat it doesAPI callRoles
Number fields Window W, Output B_out, Reasoning B_reasoning, Safety B_safetyRecompute the budget at once in the browser.noneeveryone
Add segmentAdds a line segment_<n> with 0 tokens.noneeveryone
Remove button (per segment)Removes the segment.noneeveryone
Compute the plan with the APISends the window, the reserved budgets and the segments (name, tokens) and shows the plan: budget (with context_budget and used), segments, compression_actions, classification_max, context_id.POST /v1/context/planLLM readers

Roles​

  • POST /v1/context/plan requires one of the READ roles of services/control-plane/src/eai/domains/llm/__init__.py (ROLES.llmReaders in portal/src/lib/kit.ts): tenant_admin, platform_admin, security_officer, finops, developer, auditor, viewer, agent, ai_platform_engineer, ai_governance_officer, support_engineer.
  • The local computation needs no role.

Typical tasks​

Size the retrieval budget of an agent​

  1. Set the window. Type the Context window of the model (read it in the Models registry) in Window W. Expected result: the formula updates. If it fails: a value of 0 makes the budget infeasible.
  2. Reserve output and reasoning. Set Output B_out to the planned max tokens and Reasoning B_reasoning to the reasoning budget, so that the answer always has room. Expected result: Available B_context shows what is left. If it fails: "Reserved budgets exceed the window" means the reservations are too large.
  3. Describe the segments. Adjust the Tokens of system, history, retrieval and tools, or Add segment. Expected result: Overflow is 0. If it fails: lower the retrieval or the history until Overflow is 0.

Check the plan with the Control Plane​

  1. Compute. Click Compute the plan with the API, so that the Context Manager of the Control Plane validates the same budget. Expected result: a JSON plan with budget.context_budget equal to Available B_context. If it fails: "Mandatory context does not fit in the model window." (see the Troubleshooting section).

  2. Compare with the command line. The same plan can be computed by the CLI (see docs/sdks/cli-reference.md):

    enterprise-ai context --window 200000 --output-tokens 8192 --reasoning 8192 --safety 2048 plan

    Expected result: the same budget as the screen. If it fails: check the values typed on both sides.

Troubleshooting​

SymptomCauseFix
Result in red, "Reserved budgets exceed the window"W - B_out - B_reasoning - B_safety is zero or negative.Lower the output, reasoning or safety reservations.
"Mandatory context does not fit in the model window." (context_overflow, 422) on Compute the plan with the APIThe segments sent by this screen carry no type: the Context Manager treats them as prompt, a mandatory type, so it cannot compress or drop them when they exceed the budget, or the budget is zero or negative.Reduce the segment tokens until Overflow is 0, or reduce the reservations.
"Parameter window is invalid." (parameter_invalid, 422)Window W is 0.Type a positive window.
Error panel forbidden (403) on Compute the plan with the APIRole outside the LLM readers.Ask an administrator for a reader role; the local formula still works.