haive.core.schema.prebuilt.llm_state¶
LLM-specific state with single engine and token tracking.
This module provides a state schema optimized for LLM-based agents that need to track token usage against thresholds and metadata.
Classes¶
State schema for LLM-based agents with single engine, tool management and token tracking. |
Module Contents¶
- class haive.core.schema.prebuilt.llm_state.LLMState(/, **data)[source]¶
Bases:
haive.core.schema.prebuilt.tool_state.ToolStateState schema for LLM-based agents with single engine, tool management and token tracking.
This schema is designed for agents that: - Use a single primary LLM engine (with optional additional engines) - Need automatic tool management and routing (inherited from ToolState) - Need automatic token usage tracking for all messages (inherited from ToolState → MessagesStateWithTokenUsage) - Want to compare token usage against engine metadata/thresholds - Require cost tracking and capacity monitoring
The schema combines: - ToolState for tool management, routing, and token tracking - Single primary engine field for cleaner LLM agent design - Computed properties for threshold comparison - Automatic context length detection from model names
Input Schema: Just messages (from MessagesStateWithTokenUsage) Output Schema: Full state including engine, messages, token usage, etc.
Examples
from haive.core.schema.prebuilt import LLMState from haive.core.engine.aug_llm import AugLLMConfig
# Create state with engine state = LLMState(
- engine=AugLLMConfig(
name=”gpt4_engine”, model=”gpt-4-turbo”, # Automatically detects 128k context temperature=0.7
)
)
# Messages automatically track tokens state.add_message(ai_message)
# Check against model-specific thresholds if state.is_approaching_token_limit:
print(f”Warning: {state.token_usage_percentage:.1f}% of {state.context_length} tokens used”)
# Set custom thresholds state.warning_threshold = 0.75 # Warn at 75% usage state.critical_threshold = 0.90 # Critical at 90% usage
# Get cost analysis analysis = state.get_conversation_cost_analysis() print(f”Total cost: ${analysis[‘total_cost’]:.4f}”)
Create a new model by parsing and validating input data from keyword arguments.
Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.
self is explicitly positional-only to allow self as a field name.
- Parameters:
data (Any)
- classmethod from_engine(engine, **kwargs)[source]¶
Create LLMState from an AugLLMConfig engine.
- Parameters:
engine (haive.core.engine.aug_llm.AugLLMConfig) – The AugLLMConfig engine
**kwargs – Additional fields for the state
- Returns:
New LLMState instance
- Return type:
- setup_primary_engine_references()[source]¶
Ensure the primary LLM engine is available in engines dict with standard keys.
This works with ToolState’s engine management to provide consistent access.
- Return type:
Self
- should_summarize_context(threshold=0.75)[source]¶
Determine if context should be summarized based on token usage.
- property is_approaching_token_limit: bool¶
Check if token usage is approaching the warning threshold.
- Return type:
- property is_at_critical_limit: bool¶
Check if token usage has reached the critical threshold.
- Return type:
- property is_at_token_limit: bool¶
Check if token usage has reached or exceeded the limit.
- Return type: