calute.core.config

calute.core.config#

Configuration management system for Calute.

This module provides a comprehensive configuration management system for the Calute framework. It includes: - Pydantic-based configuration models with validation - Support for JSON and YAML configuration files - Environment variable configuration loading - Configuration merging and persistence - Separate config sections for executor, memory, security, LLM, logging, and observability

The configuration system follows a hierarchical structure with sensible defaults and extensive validation to ensure configuration integrity.

Example

>>> config = CaluteConfig.from_file("config.yaml")
>>> config.llm.model = "gpt-4"
>>> config.to_file("updated_config.yaml")

class calute.core.config.CaluteConfig(*, environment: ~calute.core.config.EnvironmentType = EnvironmentType.DEVELOPMENT, debug: bool = False, executor: ~calute.core.config.ExecutorConfig = <factory>, memory: ~calute.core.config.MemoryConfig = <factory>, security: ~calute.core.config.SecurityConfig = <factory>, llm: ~calute.core.config.LLMConfig = <factory>, logging: ~calute.core.config.LoggingConfig = <factory>, observability: ~calute.core.config.ObservabilityConfig = <factory>, plugins: dict[str, typing.Any] = <factory>, features: dict[str, bool] = <factory>)[source]#

Bases: BaseModel

Main Calute configuration container.

Root configuration object that aggregates all configuration sections and provides methods for loading, saving, and merging configurations from various sources.

environment#

Deployment environment type.

Type: calute.core.config.EnvironmentType

debug#

Whether debug mode is enabled.

Type: bool

executor#

Executor configuration section.

Type: calute.core.config.ExecutorConfig

memory#

Memory configuration section.

Type: calute.core.config.MemoryConfig

security#

Security configuration section.

Type: calute.core.config.SecurityConfig

llm#

LLM configuration section.

Type: calute.core.config.LLMConfig

logging#

Logging configuration section.

Type: calute.core.config.LoggingConfig

observability#

Observability configuration section.

Type: calute.core.config.ObservabilityConfig

plugins#

Plugin-specific configurations.

Type: dict[str, Any]

features#

Feature flags for enabling/disabling capabilities.

Type: dict[str, bool]

debug: bool#

environment: EnvironmentType#

executor: ExecutorConfig#

features: dict[str, bool]#

classmethod from_env(prefix: str = 'CALUTE_') → CaluteConfig[source]#

Load configuration from environment variables.

Environment variables are parsed hierarchically using underscores as separators. JSON values are automatically parsed.

Parameters: prefix – Prefix for environment variables (default: “CALUTE_”).
Returns: CaluteConfig instance loaded from environment variables.

Example

>>>
>>> config = CaluteConfig.from_env()
>>> print(config.llm.model)

classmethod from_file(path: str | pathlib.Path) → CaluteConfig[source]#

Load configuration from a JSON or YAML file.

Parameters

path – Path to the configuration file.

Returns

CaluteConfig instance loaded from the file.

Raises

FileNotFoundError – If the configuration file doesn’t exist.
ImportError – If YAML file is specified but PyYAML is not installed.
ValueError – If the file format is not supported.

Example

>>> config = CaluteConfig.from_file("config.yaml")

llm: LLMConfig#

logging: LoggingConfig#

memory: MemoryConfig#

merge(other: CaluteConfig) → CaluteConfig[source]#

Merge with another configuration.

Creates a new configuration by deep merging this configuration with another. The other configuration takes precedence for conflicting values.

Parameters: other – Configuration to merge with.
Returns: New CaluteConfig with merged values.

Example

>>> base_config = CaluteConfig.from_file("base.yaml")
>>> override_config = CaluteConfig.from_file("override.yaml")
>>> final_config = base_config.merge(override_config)

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

observability: ObservabilityConfig#

plugins: dict[str, Any]#

security: SecurityConfig#

to_file(path: str | pathlib.Path) → None[source]#

Save configuration to a JSON or YAML file.

Parameters: path – Path where the configuration should be saved.
Raises: ValueError – If the file format is not supported.

Note

If YAML format is specified but PyYAML is not installed, the configuration will be saved as JSON instead.

class calute.core.config.EnvironmentType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

Enumeration of deployment environment types.

Used to configure different behaviors and settings based on the deployment environment.

DEVELOPMENT = 'development'#

PRODUCTION = 'production'#

STAGING = 'staging'#

TESTING = 'testing'#

class calute.core.config.ExecutorConfig(*, default_timeout: float = 30.0, max_retries: int = 3, retry_delay: float = 1.0, max_concurrent_executions: int = 10, enable_metrics: bool = True, enable_caching: bool = False, cache_ttl: int = 3600)[source]#

Bases: BaseModel

Configuration for function execution behavior.

Controls timeout, retry, concurrency, and caching settings for function/tool execution within agents.

default_timeout#

Default timeout in seconds for function execution.

Type: float

max_retries#

Maximum number of retry attempts on failure.

Type: int

retry_delay#

Delay in seconds between retry attempts.

Type: float

max_concurrent_executions#

Maximum concurrent function executions.

Type: int

enable_metrics#

Whether to collect execution metrics.

Type: bool

enable_caching#

Whether to cache function results.

Type: bool

cache_ttl#

Cache time-to-live in seconds.

Type: int

cache_ttl: int#

default_timeout: float#

enable_caching: bool#

enable_metrics: bool#

max_concurrent_executions: int#

max_retries: int#

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

retry_delay: float#

class calute.core.config.LLMConfig(*, provider: LLMProvider = LLMProvider.OPENAI, model: str = 'gpt-4', api_key: str | None = None, api_key_env_var: str = 'OPENAI_API_KEY', base_url: str | None = None, temperature: float = 0.7, max_tokens: int = 2048, top_p: float = 0.95, top_k: int = 0, frequency_penalty: float = 0.0, presence_penalty: float = 0.0, repetition_penalty: float = 1.0, timeout: float = 60.0, max_retries: int = 3, enable_streaming: bool = True, enable_caching: bool = False)[source]#

Bases: BaseModel

Configuration for LLM provider and model settings.

Controls LLM provider selection, model parameters, and generation settings for agent responses.

provider#

The LLM provider to use.

Type: calute.core.config.LLMProvider

model#

Model identifier (e.g., ‘gpt-4’, ‘claude-3’).

Type: str

api_key#

API key for the provider.

Type: str | None

api_key_env_var#

Environment variable for API key.

Type: str

base_url#

Optional custom base URL for API.

Type: str | None

temperature#

Sampling temperature (0.0-2.0).

Type: float

max_tokens#

Maximum tokens to generate.

Type: int

top_p#

Nucleus sampling parameter.

Type: float

top_k#

Top-k sampling parameter.

Type: int

frequency_penalty#

Frequency penalty for repetition.

Type: float

presence_penalty#

Presence penalty for repetition.

Type: float

repetition_penalty#

Repetition penalty multiplier.

Type: float

timeout#

Request timeout in seconds.

Type: float

max_retries#

Maximum retry attempts.

Type: int

enable_streaming#

Whether to enable streaming responses.

Type: bool

enable_caching#

Whether to cache LLM responses.

Type: bool

api_key: str | None#

api_key_env_var: str#

base_url: str | None#

enable_caching: bool#

enable_streaming: bool#

frequency_penalty: float#

max_retries: int#

max_tokens: int#

model: str#

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

presence_penalty: float#

provider: LLMProvider#

repetition_penalty: float#

temperature: float#

timeout: float#

top_k: int#

top_p: float#

classmethod validate_api_key(v, info)[source]#

Validate or load API key from environment.

Parameters

v – The API key value.
info – Validation context information.

Returns

The validated API key, loaded from environment if not provided.

class calute.core.config.LLMProvider(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

Enumeration of supported LLM provider backends.

Defines the available LLM providers that can be configured for use with Calute agents.

ANTHROPIC = 'anthropic'#

COHERE = 'cohere'#

GEMINI = 'gemini'#

HUGGINGFACE = 'huggingface'#

LOCAL = 'local'#

OPENAI = 'openai'#

class calute.core.config.LogLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

Enumeration of available logging levels.

Standard Python logging levels for controlling log verbosity throughout the application.

CRITICAL = 'CRITICAL'#

DEBUG = 'DEBUG'#

ERROR = 'ERROR'#

INFO = 'INFO'#

WARNING = 'WARNING'#

class calute.core.config.LoggingConfig(*, level: LogLevel = LogLevel.INFO, format: str = '%(asctime)s - %(name)s - %(levelname)s - %(message)s', file_path: str | None = None, enable_console: bool = True, enable_file: bool = False, max_file_size: int = 10485760, backup_count: int = 5, enable_json_format: bool = False)[source]#

Bases: BaseModel

Configuration for logging behavior.

Controls log formatting, output destinations, and rotation settings for application logging.

level#

Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).

Type: calute.core.config.LogLevel

format#

Log message format string.

Type: str

file_path#

Path to log file.

Type: str | None

enable_console#

Whether to log to console.

Type: bool

enable_file#

Whether to log to file.

Type: bool

max_file_size#

Maximum log file size in bytes.

Type: int

backup_count#

Number of backup log files to keep.

Type: int

enable_json_format#

Whether to use JSON log format.

Type: bool

backup_count: int#

enable_console: bool#

enable_file: bool#

enable_json_format: bool#

file_path: str | None#

format: str#

level: LogLevel#

max_file_size: int#

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class calute.core.config.MemoryConfig(*, max_short_term: int = 10, max_working: int = 5, max_long_term: int = 1000, enable_embeddings: bool = False, embedding_model: str | None = None, enable_persistence: bool = False, persistence_path: str | None = None, auto_consolidate: bool = True, consolidation_threshold: float = 0.8)[source]#

Bases: BaseModel

Configuration for the memory management system.

Controls memory capacity, persistence, and consolidation settings for agent memory systems.

max_short_term#

Maximum short-term memory entries.

Type: int

max_working#

Maximum working memory entries.

Type: int

max_long_term#

Maximum long-term memory entries.

Type: int

enable_embeddings#

Whether to use embeddings for memory.

Type: bool

embedding_model#

Model to use for embeddings.

Type: str | None

enable_persistence#

Whether to persist memory to disk.

Type: bool

persistence_path#

Path for memory persistence.

Type: str | None

auto_consolidate#

Whether to automatically consolidate memories.

Type: bool

consolidation_threshold#

Threshold for memory consolidation.

Type: float

auto_consolidate: bool#

consolidation_threshold: float#

embedding_model: str | None#

enable_embeddings: bool#

enable_persistence: bool#

max_long_term: int#

max_short_term: int#

max_working: int#

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

persistence_path: str | None#

class calute.core.config.ObservabilityConfig(*, enable_tracing: bool = False, enable_metrics: bool = True, enable_profiling: bool = False, trace_endpoint: str | None = None, metrics_endpoint: str | None = None, service_name: str = 'calute', service_version: str = '0.0.18', enable_request_logging: bool = True, enable_response_logging: bool = False, enable_function_logging: bool = True)[source]#

Bases: BaseModel

Configuration for observability and monitoring.

Controls tracing, metrics, profiling, and request/response logging for system observability.

enable_tracing#

Whether to enable distributed tracing.

Type: bool

enable_metrics#

Whether to collect metrics.

Type: bool

enable_profiling#

Whether to enable performance profiling.

Type: bool

trace_endpoint#

Endpoint for trace collection.

Type: str | None

metrics_endpoint#

Endpoint for metrics collection.

Type: str | None

service_name#

Name of the service for identification.

Type: str

service_version#

Version of the service.

Type: str

enable_request_logging#

Whether to log requests.

Type: bool

enable_response_logging#

Whether to log responses.

Type: bool

enable_function_logging#

Whether to log function calls.

Type: bool

enable_function_logging: bool#

enable_metrics: bool#

enable_profiling: bool#

enable_request_logging: bool#

enable_response_logging: bool#

enable_tracing: bool#

metrics_endpoint: str | None#

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

service_name: str#

service_version: str#

trace_endpoint: str | None#

class calute.core.config.SecurityConfig(*, enable_input_validation: bool = True, enable_output_sanitization: bool = True, max_input_length: int = 10000, max_output_length: int = 10000, allowed_functions: list[str] | None = None, blocked_functions: list[str] | None = None, enable_rate_limiting: bool = True, rate_limit_per_minute: int = 60, rate_limit_per_hour: int = 1000, enable_authentication: bool = False, api_key: str | None = None, api_key_env_var: str = 'CALUTE_API_KEY')[source]#

Bases: BaseModel

Security and safety configuration.

Controls input validation, output sanitization, rate limiting, and authentication settings for secure operation.

enable_input_validation#

Whether to validate inputs.

Type: bool

enable_output_sanitization#

Whether to sanitize outputs.

Type: bool

max_input_length#

Maximum allowed input length.

Type: int

max_output_length#

Maximum allowed output length.

Type: int

allowed_functions#

Whitelist of allowed function names.

Type: list[str] | None

blocked_functions#

Blacklist of blocked function names.

Type: list[str] | None

enable_rate_limiting#

Whether to enable rate limiting.

Type: bool

rate_limit_per_minute#

Maximum requests per minute.

Type: int

rate_limit_per_hour#

Maximum requests per hour.

Type: int

enable_authentication#

Whether to require authentication.

Type: bool

api_key#

API key for authentication.

Type: str | None

api_key_env_var#

Environment variable for API key.

Type: str

allowed_functions: list[str] | None#

api_key: str | None#

api_key_env_var: str#

blocked_functions: list[str] | None#

enable_authentication: bool#

enable_input_validation: bool#

enable_output_sanitization: bool#

enable_rate_limiting: bool#

max_input_length: int#

max_output_length: int#

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

rate_limit_per_hour: int#

rate_limit_per_minute: int#

calute.core.config.get_config() → CaluteConfig[source]#

Get the global configuration instance.

Returns: The global CaluteConfig instance, creating a default one if needed.

Example

>>> config = get_config()
>>> config.llm.model = "gpt-4"

calute.core.config.load_config(path: str | pathlib.Path | None = None) → CaluteConfig[source]#

Load configuration from file or environment.

Attempts to load configuration in the following order: 1. From specified path 2. From CALUTE_CONFIG_FILE environment variable 3. From default file locations (current dir, home dir) 4. From environment variables

Parameters: path – Optional specific path to configuration file.
Returns: Loaded CaluteConfig instance (also sets as global).

Example

>>> config = load_config("my_config.yaml")
>>>
>>> config = load_config()

calute.core.config.set_config(config: CaluteConfig) → None[source]#

Set the global configuration instance.

Parameters: config – The configuration to set as global.

Example

>>> new_config = CaluteConfig(debug=True)
>>> set_config(new_config)

calute.core.config

Contents

calute.core.config#