enterprise_ai.llm.context

Source: sdks/python/src/enterprise_ai/llm/context/__init__.py. Back to the Python 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.

Model ContextBudget

Token budget of one model call.

Fields:

Name	Type	Required	Description
window	int	yes	Context window of the model, in tokens.
output_reserved	int	no	Tokens reserved for the model output.
reasoning_reserved	int	no	Tokens reserved for the model reasoning.
safety_margin	int	no	Tokens kept free as a safety margin.

Attributes:

Name	Type	Required	Description
context_budget	int	yes	Tokens available for input context.

ContextBudget.check

check() -> ContextBudget

Raise :class:ContextOverflow when the reservations exceed the window.

This element takes no parameter.

Returns: ContextBudget. A ContextBudget: Token budget of one model call.

Raises: ContextOverflow.

ContextBudget.for_model

for_model(model: dict[str, Any], effort: str | Effort | None = None, max_output_tokens: int | None = None, safety_ratio: float = 0.02, min_safety: int = 256) -> ContextBudget

Budget derived from a Model Manifest / registry entry and the requested effort.

Name	Type	Default	Required	Description
model	dict[str, Any]		yes	Model Manifest or registry entry; its spec.context_window gives the window.
effort	str | Effort | None	None	no	Requested reasoning effort, used to size the reasoning reservation.
max_output_tokens	int | None	None	no	Tokens reserved for the output; defaults to the model max_output_tokens capped at 4096.
safety_ratio	float	0.02	no	Share of the window kept as safety margin (default 0.02), at least min_safety.
min_safety	int	256	no	Minimum safety margin in tokens (default 256).

Returns: ContextBudget. A ContextBudget: Token budget of one model call.

ContextBudget.to_dict

to_dict(used: int = 0, estimator: str = 'heuristic:chars/4') -> dict[str, Any]

Budget as the budget block of the Context Contract.

Name	Type	Default	Required	Description
used	int	0	no	Tokens actually used by the context (default 0).
estimator	str	'heuristic:chars/4'	no	Name of the token estimator recorded in the block (default heuristic:chars/4).

Returns: dict[str, Any]. Dict with window, output_reserved, reasoning_reserved, safety_margin, context_budget, used and estimator.

Model Segment

One piece of context with its priority (0-100), classification and provenance.

Fields:

Name	Type	Required	Description
content	str	yes	Original text of the segment.
type	str	no	Segment type, such as system, prompt (default), history, tool_result or rag_document.
role	str	no	Chat role of the message built from the segment (default user).
priority	int	no	Priority of the segment from 0 to 100 (default 50): the higher ones are kept first when the budget is short.
classification	str	no	Data classification, from public to secret (default internal).
provenance	dict[str, Any] | None	no	Signed in-toto Statement v1 with a SLSA v1 predicate: {statement, signature: {value, signer}}.
segment_id	str	no	Identifier of the segment, 12 random hexadecimal characters by default.
compressible	bool	no	Segment may be truncated, summarized or dropped when the budget is short.
cacheable	bool	no	Segment is part of the cacheable prompt prefix.
tokens	int	no	Tokens counted for the segment after build (0 when dropped).
original_tokens	int	no	Estimated tokens of the original text.
included	bool	no	Segment is kept in the built context.
compression	str	no	What build did to the segment: none, truncated, summarized or dropped.
content_out	str	no	Text sent to the model after build (original, truncated or summarized).

Model BuiltContext

Output of :meth:ContextBuilder.build.

Fields:

Name	Type	Required	Description
messages	list[dict[str, Any]]	yes	Chat messages {role, content} of the included segments, in the order they were added.
contract	dict[str, Any]	yes	Context Contract document: budget, segments with provenance, highest classification, compression actions and cache prefix.
segments	list[Segment]	yes	Every segment of the builder, with its final tokens, inclusion and compression mode.
used	int	yes	Tokens used by the included segments, within the context budget.
budget	ContextBudget	yes	Token budget of one model call.

Class ContextBuilder

Assemble a context within a :class:ContextBudget.

Attributes:

Name	Type	Required	Description
budget		yes	Token budget the context must fit in.
min_segment_tokens		yes	Smallest remaining budget, in tokens, worth compressing a segment into.
model_id		yes	Model identifier written in the Context Contract.
segments	list[Segment]	yes	Segments added so far, in insertion order.
summarizer		yes	Summary function used instead of truncation, or None.
tenant_id		yes	Tenant written in the Context Contract.

Constructor ContextBuilder

ContextBuilder(budget: ContextBudget, model_id: str = 'unknown', tenant_id: str = 'local', summarizer: Callable[[str, int], str] | None = None, min_segment_tokens: int = 32) -> None

Create an empty builder for one model call within budget.

Name	Type	Default	Required	Description
budget	ContextBudget		yes	Token budget the context must fit in.
model_id	str	'unknown'	no	Model identifier written in the Context Contract (default unknown).
tenant_id	str	'local'	no	Tenant written in the Context Contract (default local).
summarizer	Callable[[str, int], str] | None	None	no	Function (text, target_tokens) -> str used to summarize a segment instead of truncating it.
min_segment_tokens	int	32	no	Smallest remaining budget, in tokens, worth compressing a segment into; below it the segment is dropped (default 32).

ContextBuilder.add

add(content: str, type: str = 'prompt', role: str = 'user', priority: int = 50, classification: str = 'internal', source_type: str = 'user_input', source_id: str | None = None, compressible: bool = True, cacheable: bool = False, **provenance: Any) -> Segment

Add a segment and return it.

Name	Type	Default	Required	Description
content	str		yes	Text of the segment.
type	str	'prompt'	no	Segment type: system, prompt (default), history, tool_result, rag_document, memory, image, audio, video or file.
role	str	'user'	no	Chat role of the message built from the segment (default user).
priority	int	50	no	Priority from 0 to 100 (default 50); higher segments are kept first.
classification	str	'internal'	no	Data classification: public, internal (default), confidential, restricted or secret.
source_type	str	'user_input'	no	Kind of source recorded in the provenance (default user_input).
source_id	str | None	None	no	Identifier of the source; defaults to <type>:<index>.
compressible	bool	True	no	Segment may be truncated, summarized or dropped when the budget is short (default True).
cacheable	bool	False	no	Segment is part of the cacheable prefix of the prompt (default False).
**provenance	Any		no	Extra provenance fields stored with source_type and source_id.

Returns: Segment. A Segment: One piece of context with its priority (0-100), classification and provenance.

ContextBuilder.build

build() -> BuiltContext

Select, compress and order the segments; raise :class:ContextOverflow if mandatory content overflows.

This element takes no parameter.

Returns: BuiltContext. A BuiltContext: Output of :meth:ContextBuilder.build.

Raises: ContextOverflow.

ContextBuilder.system

system(content: str, **kw: Any) -> Segment

Add the system prompt (priority 100, never compressed, cacheable).

Name	Type	Default	Required	Description
content	str		yes	Text of the system prompt.
**kw	Any		no	Other add options (classification, source_id, provenance); source_type defaults to system.

Returns: Segment. A Segment: One piece of context with its priority (0-100), classification and provenance.

Class ContextClient

/v1/context/plan: server side budget and compression plan.

Resource

ContextClient.plan

plan(window: int, output: int, reasoning: int = 0, safety: int = 0, segments: list[dict[str, Any]] | None = None, **extra: Any) -> Any

Plan the context window. Context Manager dry run: computes the token budget of a model window (output, reasoning and safety reserves) and which segments are kept, compressed or dropped by priority. With model, the window and output reserve come from the registry. A window that is not a positive integer answers 422 parameter_invalid; segments that cannot fit answer 422 context_overflow. Requires a reader role.

Route: /v1/context/plan (POST).

Name	Type	Default	Required	Description
window	int		yes	Context window of the model, in tokens.
output	int		yes	Output of the operation (transcript, image references...).
reasoning	int	0	no	Tokens reserved for reasoning (default 0).
safety	int	0	no	Tokens kept as safety margin (default 0).
segments	list[dict[str, Any]] | None	None	no	Segments to plan, as dicts; empty list by default.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Plan the context window".

Raises: the typed errors of the transport (Errors).

Functions

estimate_tokens

estimate_tokens(text: str) -> int

Heuristic token estimate (chars/4, at least 1 for non empty text).

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

Returns: int. Estimated number of tokens, 0 for an empty text.

truncate

truncate(text: str, tokens: int) -> str

Keep the head of text within tokens (heuristic estimator).

Name	Type	Default	Required	Description
text	str		yes	Text to shorten.
tokens	int		yes	Maximum number of tokens to keep (4 characters per token).

Returns: str. The text unchanged when it fits, otherwise its head ending with ...; empty when tokens is 0 or less.