enterprise_ai.llm.context

Source : sdks/python/src/enterprise_ai/llm/context/__init__.py. Retour à l'index de la référence du SDK Python.

remarque

Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.

Modèle ContextBudget

Budget de tokens d'un appel au modèle.

Champs :

Nom	Type	Requis	Description
window	int	oui	Fenêtre de contexte du modèle, en tokens.
output_reserved	int	non	Tokens réservés à la sortie du modèle.
reasoning_reserved	int	non	Tokens réservés au raisonnement du modèle.
safety_margin	int	non	Tokens laissés libres comme marge de sécurité.

Attributs :

Nom	Type	Requis	Description
context_budget	int	oui	Tokens disponibles pour le contexte d'entrée.

ContextBudget.check

check() -> ContextBudget

Lève :class:ContextOverflow quand les réservations dépassent la fenêtre.

Cet élément ne prend aucun paramètre.

Retour : ContextBudget. Un ContextBudget : budget de tokens d'un appel au modèle.

Erreurs levées : 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 déduit d'un Model Manifest ou d'une entrée du registre et de l'effort demandé.

Nom	Type	Défaut	Requis	Description
model	dict[str, Any]		oui	Model Manifest ou entrée du registre ; son spec.context_window donne la fenêtre.
effort	str | Effort | None	None	non	Effort de raisonnement demandé, qui sert à dimensionner la réserve de raisonnement.
max_output_tokens	int | None	None	non	Tokens réservés à la sortie ; par défaut, le max_output_tokens du modèle plafonné à 4096.
safety_ratio	float	0.02	non	Part de la fenêtre gardée comme marge de sécurité (0.02 par défaut), au moins min_safety.
min_safety	int	256	non	Marge de sécurité minimale en tokens (256 par défaut).

Retour : ContextBudget. Un ContextBudget : budget de tokens d'un appel au modèle.

ContextBudget.to_dict

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

Budget sous la forme du bloc budget du Context Contract.

Nom	Type	Défaut	Requis	Description
used	int	0	non	Tokens réellement consommés par le contexte (0 par défaut).
estimator	str	'heuristic:chars/4'	non	Nom de l'estimateur de tokens inscrit dans le bloc (heuristic:chars/4 par défaut).

Retour : dict[str, Any]. Dict avec window, output_reserved, reasoning_reserved, safety_margin, context_budget, used et estimator.

Modèle Segment

Élément de contexte avec sa priorité (0-100), sa classification et sa provenance.

Champs :

Nom	Type	Requis	Description
content	str	oui	Texte d'origine du segment.
type	str	non	Type de segment, par exemple system, prompt (par défaut), history, tool_result ou rag_document.
role	str	non	Rôle de chat du message construit à partir du segment (user par défaut).
priority	int	non	Priorité du segment de 0 à 100 (50 par défaut) : les plus hautes sont gardées en premier quand le budget manque.
classification	str	non	Classification des données, de public à secret (internal par défaut).
provenance	dict[str, Any] | None	non	Déclaration in-toto v1 signée avec un prédicat SLSA v1 : {statement, signature: {value, signer}}.
segment_id	str	non	Identifiant du segment, 12 caractères hexadécimaux aléatoires par défaut.
compressible	bool	non	Le segment peut être tronqué, résumé ou écarté si le budget manque.
cacheable	bool	non	Le segment fait partie du préfixe du prompt pouvant être mis en cache.
tokens	int	non	Tokens comptés pour le segment après build (0 s'il est écarté).
original_tokens	int	non	Tokens estimés du texte d'origine.
included	bool	non	Le segment est conservé dans le contexte construit.
compression	str	non	Ce que build a fait du segment : none, truncated, summarized ou dropped.
content_out	str	non	Texte envoyé au modèle après build (d'origine, tronqué ou résumé).

Modèle BuiltContext

Sortie de :meth:ContextBuilder.build.

Champs :

Nom	Type	Requis	Description
messages	list[dict[str, Any]]	oui	Messages de chat {role, content} des segments retenus, dans l'ordre où ils ont été ajoutés.
contract	dict[str, Any]	oui	Document Context Contract : budget, segments avec provenance, classification maximale, actions de compression et préfixe de cache.
segments	list[Segment]	oui	Tous les segments du constructeur, avec leurs tokens finaux, leur inclusion et leur mode de compression.
used	int	oui	Tokens consommés par les segments retenus, dans la limite du budget de contexte.
budget	ContextBudget	oui	Budget de tokens d'un appel au modèle.

Classe ContextBuilder

Assemble un contexte dans les limites d'un :class:ContextBudget.

Attributs :

Nom	Type	Requis	Description
budget		oui	Budget de tokens dans lequel le contexte doit tenir.
min_segment_tokens		oui	Plus petit budget restant, en tokens, pour lequel un segment est compressé.
model_id		oui	Identifiant du modèle inscrit dans le Context Contract.
segments	list[Segment]	oui	Segments ajoutés jusqu'ici, dans l'ordre d'insertion.
summarizer		oui	Fonction de résumé utilisée à la place de la troncature, ou None.
tenant_id		oui	Tenant inscrit dans le Context Contract.

Constructeur 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

Crée un constructeur vide pour un appel au modèle dans les limites de budget.

Nom	Type	Défaut	Requis	Description
budget	ContextBudget		oui	Budget de tokens dans lequel le contexte doit tenir.
model_id	str	'unknown'	non	Identifiant du modèle inscrit dans le Context Contract (unknown par défaut).
tenant_id	str	'local'	non	Tenant inscrit dans le Context Contract (local par défaut).
summarizer	Callable[[str, int], str] | None	None	non	Fonction (text, target_tokens) -> str qui résume un segment au lieu de le tronquer.
min_segment_tokens	int	32	non	Plus petit budget restant, en tokens, pour lequel un segment est compressé ; en dessous, il est écarté (32 par défaut).

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

Ajoute un segment et le renvoie.

Nom	Type	Défaut	Requis	Description
content	str		oui	Texte du segment.
type	str	'prompt'	non	Type de segment : system, prompt (par défaut), history, tool_result, rag_document, memory, image, audio, video ou file.
role	str	'user'	non	Rôle de chat du message construit à partir du segment (user par défaut).
priority	int	50	non	Priorité de 0 à 100 (50 par défaut) ; les segments les plus prioritaires sont gardés en premier.
classification	str	'internal'	non	Classification des données : public, internal (par défaut), confidential, restricted ou secret.
source_type	str	'user_input'	non	Type de source inscrit dans la provenance (user_input par défaut).
source_id	str | None	None	non	Identifiant de la source ; par défaut <type>:<index>.
compressible	bool	True	non	Le segment peut être tronqué, résumé ou écarté si le budget manque (True par défaut).
cacheable	bool	False	non	Le segment fait partie du préfixe du prompt pouvant être mis en cache (False par défaut).
**provenance	Any		non	Champs de provenance supplémentaires enregistrés avec source_type et source_id.

Retour : Segment. Un Segment : élément de contexte avec sa priorité (0-100), sa classification et sa provenance.

ContextBuilder.build

build() -> BuiltContext

Sélectionne, compresse et ordonne les segments ; lève :class:ContextOverflow si un contenu obligatoire dépasse.

Cet élément ne prend aucun paramètre.

Retour : BuiltContext. Un BuiltContext : sortie de :meth:ContextBuilder.build.

Erreurs levées : ContextOverflow.

ContextBuilder.system

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

Ajoute le prompt système (priorité 100, jamais compressé, mis en cache).

Nom	Type	Défaut	Requis	Description
content	str		oui	Texte du prompt système.
**kw	Any		non	Autres options de add (classification, source_id, provenance) ; source_type vaut system par défaut.

Retour : Segment. Un Segment : élément de contexte avec sa priorité (0-100), sa classification et sa provenance.

Classe ContextClient

LLM et passerelle de modèles. Fournisseurs de modèles, registre des modèles, règles de routage et passerelle de modèles (Model Gateway) : le seul chemin par lequel agents et applications appellent les modèles.

Resource

ContextClient.plan

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

Planifier la fenêtre de contexte. Simulation du Context Manager : calcule le budget de jetons d'une fenêtre de modèle (réserves de sortie, de raisonnement et de sécurité) et les segments conservés, compressés ou écartés selon leur priorité. Avec model, la fenêtre et la réserve de sortie viennent du registre. Une fenêtre qui n'est pas un entier positif répond 422 parameter_invalid ; des segments qui ne peuvent pas tenir répondent 422 context_overflow. Demande un rôle de lecteur.

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

Nom	Type	Défaut	Requis	Description
window	int		oui	Fenêtre de contexte du modèle, en tokens.
output	int		oui	Sortie de l'opération (transcription, références d'images...).
reasoning	int	0	non	Tokens réservés au raisonnement (0 par défaut).
safety	int	0	non	Tokens gardés comme marge de sécurité (0 par défaut).
segments	list[dict[str, Any]] | None	None	non	Segments à planifier, sous forme de dicts ; liste vide par défaut.
**extra	Any		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Planifier la fenêtre de contexte ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Fonctions

estimate_tokens

estimate_tokens(text: str) -> int

Estimation heuristique des tokens (chars/4, au moins 1 pour un texte non vide).

Nom	Type	Défaut	Requis	Description
text	str		oui	Texte à mesurer.

Retour : int. Nombre estimé de tokens, 0 pour un texte vide.

truncate

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

Garde le début de text dans la limite de tokens (estimateur heuristique).

Nom	Type	Défaut	Requis	Description
text	str		oui	Texte à raccourcir.
tokens	int		oui	Nombre maximal de tokens à garder (4 caractères par token).

Retour : str. Le texte inchangé s'il tient, sinon son début terminé par ... ; vide si tokens vaut 0 ou moins.