context.ts

Source: sdks/typescript/packages/sdk/src/context.ts. Back to the TypeScript SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Interface ContextBudgetInit

Sizes given to the ContextBudget constructor.

Fields:

Name	Type	Required	Description
window	number	yes	W: model context window in tokens.
output	number	yes	B_out: tokens reserved for the answer.
reasoning	number	no	B_reasoning: tokens reserved for internal reasoning.
safety	number	no	B_safety: safety margin in tokens (default 2 percent of the window).
locale	Locale	no	Language of the error messages, en (default) or fr.

Interface BudgetSegment

A piece of context given to ContextBudget.plan: id, token count, priority and required flag.

Fields:

Name	Type	Required	Description
id	string	yes	Id of the segment, returned in included or dropped.
tokens	number	yes	Size of the segment in tokens.
priority	number	no	Higher priority segments are kept first (default 0).
required	boolean	no	Required segments are always kept, an overflow is raised if they do not fit.

Interface BudgetPlan

Result of ContextBudget.plan: the reserved tokens, the context budget, the tokens used and the kept and dropped segment ids.

Fields:

Name	Type	Required	Description
window	number	yes	Context window of the model in tokens.
output_reserved	number	yes	Tokens reserved for the answer.
reasoning_reserved	number	yes	Tokens reserved for internal reasoning.
safety_margin	number	yes	Safety margin in tokens.
context_budget	number	yes	Tokens available for the prompt context.
used	number	yes	Tokens of the kept segments.
remaining	number	yes	Context budget left after the kept segments.
included	string[]	yes	Ids of the segments kept, in input order.
dropped	string[]	yes	Ids of the segments left out, in input order.

Class ContextBudget

Local Context Manager helper: B_context = W - B_out - B_reasoning - B_safety.

Attributes:

Name	Type	Required	Description
output	number	yes	Tokens reserved for the answer (B_out).
reasoning	number	yes	Tokens reserved for internal reasoning (B_reasoning).
safety	number	yes	Safety margin in tokens (B_safety), 2 percent of the window by default.
window	number	yes	Context window of the model in tokens (W).

Constructor ContextBudget

new ContextBudget(init: ContextBudgetInit)

Rounds the sizes down and checks them; throws RangeError on a negative size and ContextOverflowError when the reserves exceed the window.

Name	Type	Default	Required	Description
init	ContextBudgetInit		yes	Window, output, reasoning and safety sizes in tokens, and the locale of the messages.

ContextBudget.assertFits

assertFits(tokens: number): void

Throws ContextOverflowError when the given token count does not fit.

Name	Type	Default	Required	Description
tokens	number		yes	Number of tokens to check against the context budget.

Returns: void.

Raises: ContextOverflowError.

ContextBudget.contextBudget

contextBudget(): number

Tokens available for the prompt context: window minus output, reasoning and safety.

This element takes no parameter.

Returns: number. Context budget in tokens.

ContextBudget.fits

fits(tokens: number): boolean

Tells whether a token count fits in the context budget.

Name	Type	Default	Required	Description
tokens	number		yes	Number of tokens to check.

Returns: boolean. True when tokens is at most the context budget.

ContextBudget.plan

plan(segments: BudgetSegment[]): BudgetPlan

Greedy selection: required segments first, then by descending priority, keeping input order on ties.

Name	Type	Default	Required	Description
segments	BudgetSegment[]		yes	Segments to fit; the required ones must fit or ContextOverflowError is thrown.

Returns: BudgetPlan. Budget figures and the kept and dropped segment ids.

Functions

isEffort

isEffort(value: unknown): value is Effort

Tells whether a value is one of the efforts none, low, medium, high or max.

Name	Type	Default	Required	Description
value	unknown		yes	Value to check.

Returns: value is Effort. True when the value is a known effort string.

compareEffort

compareEffort(a: Effort, b: Effort): number

Compares two efforts on the ordered scale none < low < medium < high < max.

Name	Type	Default	Required	Description
a	Effort		yes	First effort.
b	Effort		yes	Second effort.

Returns: number. Negative when a is lower than b, 0 when equal, positive when higher.

estimateTokens

estimateTokens(text: string): number

Rough token estimate (about 4 characters per token) used when no tokenizer is available.

Name	Type	Default	Required	Description
text	string		yes	Text to measure.

Returns: number. Length of the text divided by 4, rounded up; 0 for an empty text.