agentconnect.utils package

Utility functions for the AgentConnect framework.

This module provides various utility functions and classes used throughout the framework, including interaction control for rate limiting, token usage tracking, and logging configuration.

Key components:

• InteractionControl: Controls agent interactions with rate limiting and turn tracking

• InteractionState: Enum for interaction states (CONTINUE, STOP, WAIT)

• TokenConfig: Configuration for token-based rate limiting

• Logging utilities: Configurable logging setup with colored output

class InteractionControl(token_config, max_turns=20, current_turn=0, last_interaction_time=1743055959.3145032, _cooldown_callback=None, _conversation_stats=None)

Bases: object

High-level control for agent interactions.

This class provides rate limiting, turn tracking, and conversation statistics for agent interactions.

Parameters:

• token_config (TokenConfig)

• max_turns (int)

• current_turn (int)

• last_interaction_time (float)

• _cooldown_callback (Callable[[int], None] | None)

• _conversation_stats (Dict[str, Dict[str, Any]])

token_config

Configuration for token-based rate limiting

max_turns

Maximum number of turns in a conversation

current_turn

Current turn number

last_interaction_time

Timestamp of the last interaction

_cooldown_callback

Optional callback function to call when cooldown is triggered

_conversation_stats

Dictionary of conversation statistics

__post_init__()

Initialize conversation stats dictionary.

current_turn: int = 0

get_callback_manager()

Create a callback manager with rate limiting for LangChain/LangGraph.

Return type:

CallbackManager

Returns:

CallbackManager with rate limiting callbacks

get_conversation_stats(conversation_id=None)

Get statistics for a specific conversation or all conversations.

Parameters:

conversation_id (Optional[str]) – Optional ID of the conversation to get stats for

Return type:

Dict[str, Any]

Returns:

Dictionary of conversation statistics

last_interaction_time: float = 1743055959.3145032

max_turns: int = 20

async process_interaction(token_count, conversation_id=None)

Process an interaction and return the state.

Parameters:

• token_count (int) – Number of tokens used in the interaction

• conversation_id (Optional[str]) – Optional conversation ID for tracking stats

Return type:

InteractionState

Returns:

InteractionState indicating whether to continue, stop, or wait

reset_turn_counter()

Reset the turn counter to zero.

Return type:

None

set_cooldown_callback(callback)

Set a callback function to be called when cooldown is triggered.

Parameters:

callback (Callable[[int], None]) – Function that takes cooldown duration in seconds as argument

Return type:

None

token_config: TokenConfig

class InteractionState(*values)

Bases: Enum

Enum for interaction states.

CONTINUE

Continue the interaction

STOP

Stop the interaction

WAIT

Wait before continuing the interaction

CONTINUE = 'continue'

STOP = 'stop'

WAIT = 'wait'

class TokenConfig(max_tokens_per_minute, max_tokens_per_hour, current_minute_tokens=0, current_hour_tokens=0, last_minute_reset=1743055959.313969, last_hour_reset=1743055959.3139696)

Bases: object

Configuration for token-based rate limiting.

Parameters:

• max_tokens_per_minute (int)

• max_tokens_per_hour (int)

• current_minute_tokens (int)

• current_hour_tokens (int)

• last_minute_reset (float)

• last_hour_reset (float)

max_tokens_per_minute

Maximum tokens allowed per minute

max_tokens_per_hour

Maximum tokens allowed per hour

current_minute_tokens

Current token count for the minute

current_hour_tokens

Current token count for the hour

last_minute_reset

Timestamp of the last minute reset

last_hour_reset

Timestamp of the last hour reset

add_tokens(token_count)

Add tokens to the current count.

Parameters:

token_count (int) – Number of tokens to add

Return type:

None

current_hour_tokens: int = 0

current_minute_tokens: int = 0

get_cooldown_duration()

Get the cooldown duration in seconds if rate limits are exceeded.

Return type:

Optional[int]

Returns:

Cooldown duration in seconds, or None if no cooldown is needed

last_hour_reset: float = 1743055959.3139696

last_minute_reset: float = 1743055959.313969

max_tokens_per_minute: int

max_tokens_per_hour: int

class RateLimitingCallbackHandler(max_tokens_per_minute=5500, max_tokens_per_hour=100000, cooldown_callback=None)

Bases: BaseCallbackHandler

Callback handler that implements rate limiting for LLM calls.

This handler tracks token usage and enforces rate limits for LLM calls, triggering cooldown periods when limits are reached.

Parameters:

• max_tokens_per_minute (int)

• max_tokens_per_hour (int)

• cooldown_callback (Callable[[int], None] | None)

max_tokens_per_minute

Maximum tokens allowed per minute

max_tokens_per_hour

Maximum tokens allowed per hour

current_minute_tokens

Current token count for the minute

current_hour_tokens

Current token count for the hour

last_minute_reset

Timestamp of the last minute reset

last_hour_reset

Timestamp of the last hour reset

in_cooldown

Whether the handler is in cooldown

cooldown_until

Timestamp when cooldown ends

cooldown_callback

Optional callback function to call when cooldown is triggered

on_chain_end(outputs, **kwargs)

Handle chain end event.

Parameters:

• outputs (Dict[str, Any]) – Chain outputs

• **kwargs (Any) – Additional arguments

Return type:

None

on_llm_end(response, **kwargs)

Handle LLM end event.

Parameters:

• response – LLM response

• **kwargs (Any) – Additional arguments

Return type:

None

on_llm_start(serialized, prompts, **kwargs)

Handle LLM start event.

Parameters:

• serialized (Dict[str, Any]) – Serialized LLM data

• prompts (List[str]) – List of prompts

• **kwargs (Any) – Additional arguments

Return type:

None

setup_logging(level=LogLevel.INFO, module_levels=None)

Configure logging with colors and per-module settings.

Parameters:

• level (LogLevel) – Default log level for all modules

• module_levels (Optional[Dict[str, LogLevel]]) – Dict of module names and their specific log levels

Return type:

None

class LogLevel(*values)

Bases: Enum

Enum for log levels.

DEBUG

Debug log level

INFO

Info log level

WARNING

Warning log level

ERROR

Error log level

DEBUG = 10

INFO = 20

WARNING = 30

ERROR = 40

disable_all_logging()

Disable all logging output.

This is useful for examples and tests where logging output is not needed.

Return type:

None

get_module_levels_for_development()

Get recommended log levels for development.

Return type:

Dict[str, LogLevel]

Returns:

Dictionary of module names and their recommended log levels for development

Submodules

• agentconnect.utils.interaction_control module
  • InteractionState
    • InteractionState.CONTINUE
    • InteractionState.STOP
    • InteractionState.WAIT
    • InteractionState.CONTINUE
    • InteractionState.STOP
    • InteractionState.WAIT
  • RateLimitingCallbackHandler
    • RateLimitingCallbackHandler.max_tokens_per_minute
    • RateLimitingCallbackHandler.max_tokens_per_hour
    • RateLimitingCallbackHandler.current_minute_tokens
    • RateLimitingCallbackHandler.current_hour_tokens
    • RateLimitingCallbackHandler.last_minute_reset
    • RateLimitingCallbackHandler.last_hour_reset
    • RateLimitingCallbackHandler.in_cooldown
    • RateLimitingCallbackHandler.cooldown_until
    • RateLimitingCallbackHandler.cooldown_callback
    • RateLimitingCallbackHandler.on_llm_start()
    • RateLimitingCallbackHandler.on_llm_end()
    • RateLimitingCallbackHandler.on_chain_end()
  • TokenConfig
    • TokenConfig.max_tokens_per_minute
    • TokenConfig.max_tokens_per_hour
    • TokenConfig.current_minute_tokens
    • TokenConfig.current_hour_tokens
    • TokenConfig.last_minute_reset
    • TokenConfig.last_hour_reset
    • TokenConfig.max_tokens_per_minute
    • TokenConfig.max_tokens_per_hour
    • TokenConfig.current_minute_tokens
    • TokenConfig.current_hour_tokens
    • TokenConfig.last_minute_reset
    • TokenConfig.last_hour_reset
    • TokenConfig.add_tokens()
    • TokenConfig.get_cooldown_duration()
  • InteractionControl
    • InteractionControl.token_config
    • InteractionControl.max_turns
    • InteractionControl.current_turn
    • InteractionControl.last_interaction_time
    • InteractionControl._cooldown_callback
    • InteractionControl._conversation_stats
    • InteractionControl.token_config
    • InteractionControl.max_turns
    • InteractionControl.current_turn
    • InteractionControl.last_interaction_time
    • InteractionControl.__post_init__()
    • InteractionControl.process_interaction()
    • InteractionControl.set_cooldown_callback()
    • InteractionControl.reset_turn_counter()
    • InteractionControl.get_conversation_stats()
    • InteractionControl.get_callback_manager()
• agentconnect.utils.logging_config module
  • LogLevel
    • LogLevel.DEBUG
    • LogLevel.INFO
    • LogLevel.WARNING
    • LogLevel.ERROR
    • LogLevel.DEBUG
    • LogLevel.INFO
    • LogLevel.WARNING
    • LogLevel.ERROR
  • ColoredFormatter
    • ColoredFormatter.COLORS
    • ColoredFormatter.COLORS
    • ColoredFormatter.format()
  • setup_logging()
  • disable_all_logging()
  • get_module_levels_for_development()
  • setup_langgraph_logging()