AgentSettings

Root configuration class using Pydantic Settings.

Quick Example

from mamba_agents import AgentSettings

# Load from environment, .env, config files
settings = AgentSettings()

# Override specific values
settings = AgentSettings(
    model_backend={
        "model": "gpt-4o",
        "api_key": "sk-...",
    },
    logging={"level": "DEBUG"},
)

Configuration Sections

Section	Type	Description
model_backend	ModelBackendSettings	Model connection
logging	LoggingConfig	Logging settings
retry	ErrorRecoveryConfig	Retry behavior
context	CompactionConfig	Default compaction
tokenizer	TokenizerConfig	Tokenizer settings
cost_rates	dict	Custom cost rates

Environment Variables

MAMBA_MODEL_BACKEND__MODEL=gpt-4o
MAMBA_MODEL_BACKEND__API_KEY=sk-...
MAMBA_LOGGING__LEVEL=INFO
MAMBA_RETRY__MAX_RETRIES=3

API Reference

AgentSettings

Bases: BaseSettings

Root configuration for the agent framework.

Configuration is loaded from multiple sources in priority order: 1. Constructor arguments (highest priority) 2. Environment variables (MAMBA_ prefix) 3. .env file (project-specific) 4. ~/mamba.env file (user-wide defaults) 5. config.toml file 6. Default values (lowest priority)

Environment variables use double underscore for nesting: - MAMBA_MODEL_BACKEND__BASE_URL -> model_backend.base_url - MAMBA_LOGGING__LEVEL -> logging.level

ATTRIBUTE	DESCRIPTION
model_backend	Model backend connection settings. TYPE: ModelBackendSettings
logging	Logging configuration. TYPE: LoggingConfig
retry	Error recovery and retry settings. TYPE: ErrorRecoveryConfig
context	Default context compaction settings. TYPE: CompactionConfig
tokenizer	Default tokenizer settings. TYPE: TokenizerConfig
prompts	Default prompt management settings. TYPE: PromptConfig
cost_rates	Custom cost rates per 1000 tokens by model. TYPE: dict[str, float]

settings_customise_sources classmethod

settings_customise_sources(
    settings_cls: type[BaseSettings],
    init_settings: PydanticBaseSettingsSource,
    env_settings: PydanticBaseSettingsSource,
    dotenv_settings: PydanticBaseSettingsSource,
    file_secret_settings: PydanticBaseSettingsSource,
) -> tuple[PydanticBaseSettingsSource, ...]

Customize settings sources to include TOML file support.

Order determines priority (first = highest priority): 1. init_settings (constructor args) 2. env_settings (environment variables) 3. dotenv_settings (.env file) 4. toml_settings (config.toml file) 5. file_secret_settings (secrets files)

Source code in src/mamba_agents/config/settings.py

@classmethod
def settings_customise_sources(
    cls,
    settings_cls: type[BaseSettings],
    init_settings: PydanticBaseSettingsSource,
    env_settings: PydanticBaseSettingsSource,
    dotenv_settings: PydanticBaseSettingsSource,
    file_secret_settings: PydanticBaseSettingsSource,
) -> tuple[PydanticBaseSettingsSource, ...]:
    """Customize settings sources to include TOML file support.

    Order determines priority (first = highest priority):
    1. init_settings (constructor args)
    2. env_settings (environment variables)
    3. dotenv_settings (.env file)
    4. toml_settings (config.toml file)
    5. file_secret_settings (secrets files)
    """
    return (
        init_settings,
        env_settings,
        dotenv_settings,
        TomlConfigSettingsSource(settings_cls),
        file_secret_settings,
    )

from_file classmethod

from_file(path: str | Path) -> AgentSettings

Load settings from a specific configuration file.

PARAMETER	DESCRIPTION
path	Path to TOML or YAML configuration file. TYPE: str | Path

RETURNS	DESCRIPTION
AgentSettings	AgentSettings instance with values from file.

RAISES	DESCRIPTION
FileNotFoundError	If configuration file doesn't exist.
ValueError	If file format is not supported.

Source code in src/mamba_agents/config/settings.py

@classmethod
def from_file(cls, path: str | Path) -> AgentSettings:
    """Load settings from a specific configuration file.

    Args:
        path: Path to TOML or YAML configuration file.

    Returns:
        AgentSettings instance with values from file.

    Raises:
        FileNotFoundError: If configuration file doesn't exist.
        ValueError: If file format is not supported.
    """
    path = Path(path)
    if not path.exists():
        raise FileNotFoundError(f"Configuration file not found: {path}")

    suffix = path.suffix.lower()
    if suffix == ".toml":
        return cls(_env_file=None, _toml_file=path)
    elif suffix in (".yaml", ".yml"):
        # For YAML, we need to load and pass as dict
        import yaml

        with path.open() as f:
            data = yaml.safe_load(f)
        return cls(_env_file=None, **data)
    else:
        raise ValueError(f"Unsupported configuration file format: {suffix}")

model_dump_safe

model_dump_safe() -> dict[str, Any]

Dump model to dict with secrets redacted.

RETURNS	DESCRIPTION
dict[str, Any]	Dictionary representation with sensitive values replaced.

Source code in src/mamba_agents/config/settings.py

def model_dump_safe(self) -> dict[str, Any]:
    """Dump model to dict with secrets redacted.

    Returns:
        Dictionary representation with sensitive values replaced.
    """
    data = self.model_dump()

    # Redact API key if present
    if data.get("model_backend", {}).get("api_key"):
        data["model_backend"]["api_key"] = "***REDACTED***"

    return data