models

Model configuration classes and loading utilities.

This module defines configuration dataclasses used to describe provider-specific model settings for chat client creation. It includes base configuration behavior, OpenAI-compatible configuration, AWS Bedrock configuration, and a helper function for loading the appropriate configuration type from a dictionary.

`BaseModelConfig` `dataclass`

Base configuration for provider model settings.

This class stores common configuration fields shared across provider implementations and defines the interface for validation and conversion into chat client keyword arguments.

Attributes:

Name	Type	Description
`provider`	`str`	Name of the provider associated with the model configuration.
`model`	`str`	Requested model name.
`extra`	`Dict[str, Any]`	Additional provider-specific keyword arguments to pass to the chat client.

Methods:

Name	Description
`__post_init__`	Expand environment variables in common configuration fields.
`validate`	Validate the configuration.
`to_client_kwargs`	Convert the configuration into keyword arguments for chat client construction.

Source code in src/mada/core/config/models.py

@dataclass(kw_only=True)
class BaseModelConfig:
    """
    Base configuration for provider model settings.

    This class stores common configuration fields shared across provider
    implementations and defines the interface for validation and conversion
    into chat client keyword arguments.

    Attributes:
        provider:
            Name of the provider associated with the model configuration.
        model:
            Requested model name.
        extra:
            Additional provider-specific keyword arguments to pass to the chat
            client.

    Methods:
        __post_init__:
            Expand environment variables in common configuration fields.
        validate:
            Validate the configuration.
        to_client_kwargs:
            Convert the configuration into keyword arguments for chat client
            construction.
    """

    provider: str
    model: str
    extra: Dict[str, Any] = field(default_factory=dict)

    def __post_init__(self):
        """
        Expand environment variables in shared configuration fields.
        """
        self.provider = expand_env_vars(self.provider)
        self.model = expand_env_vars(self.model)

    def validate(self) -> None:
        """
        Validate the configuration.

        Subclasses should override this method to implement provider-specific
        validation rules.
        """
        pass

    def to_client_kwargs(self) -> Dict[str, Any]:
        """
        Convert the configuration into chat client keyword arguments.

        Returns:
            A dictionary of keyword arguments for chat client construction.

        Raises:
            NotImplementedError:
                Raised if the subclass does not implement this method.
        """
        raise NotImplementedError

`__post_init__()`

Expand environment variables in shared configuration fields.

Source code in src/mada/core/config/models.py

def __post_init__(self):
    """
    Expand environment variables in shared configuration fields.
    """
    self.provider = expand_env_vars(self.provider)
    self.model = expand_env_vars(self.model)

`to_client_kwargs()`

Convert the configuration into chat client keyword arguments.

Returns:

Type	Description
`Dict[str, Any]`	A dictionary of keyword arguments for chat client construction.

Raises:

Type	Description
`NotImplementedError`	Raised if the subclass does not implement this method.

Source code in src/mada/core/config/models.py

def to_client_kwargs(self) -> Dict[str, Any]:
    """
    Convert the configuration into chat client keyword arguments.

    Returns:
        A dictionary of keyword arguments for chat client construction.

    Raises:
        NotImplementedError:
            Raised if the subclass does not implement this method.
    """
    raise NotImplementedError

`validate()`

Validate the configuration.

Subclasses should override this method to implement provider-specific validation rules.

Source code in src/mada/core/config/models.py

def validate(self) -> None:
    """
    Validate the configuration.

    Subclasses should override this method to implement provider-specific
    validation rules.
    """
    pass

`BedrockModelConfig` `dataclass`

Bases: BaseModelConfig

Configuration for AWS Bedrock chat clients.

This configuration supports multiple authentication styles, including bearer-token authentication, AWS profile-based authentication, and direct AWS credential values.

Attributes:

Name	Type	Description
`provider`	`str`	Name of the provider associated with the model configuration.
`model`	`str`	Requested model name.
`extra`	`Dict[str, Any]`	Additional provider-specific keyword arguments to pass to the chat client.
`region`	`str`	AWS region for the Bedrock service.
`bearer_token`	`Optional[str]`	Optional bearer token value, or path to a file containing the token.
`aws_profile`	`Optional[str]`	Optional AWS profile name.
`aws_access_key_id`	`Optional[str]`	Optional AWS access key ID.
`aws_secret_access_key`	`Optional[str]`	Optional AWS secret access key.
`aws_session_token`	`Optional[str]`	Optional AWS session token.
`override_env_credentials`	`bool`	Whether adapter setup may overwrite existing AWS credential-related environment variables.

Methods:

Name	Description
`__post_init__`	Expand environment variables, resolve file-based bearer tokens, and validate the configuration.
`validate`	Validate required Bedrock region and authentication settings.
`to_client_kwargs`	Convert the configuration into keyword arguments for a Bedrock chat client.

Source code in src/mada/core/config/models.py

@dataclass(kw_only=True)
class BedrockModelConfig(BaseModelConfig):
    """
    Configuration for AWS Bedrock chat clients.

    This configuration supports multiple authentication styles, including
    bearer-token authentication, AWS profile-based authentication, and direct
    AWS credential values.

    Attributes:
        provider:
            Name of the provider associated with the model configuration.
        model:
            Requested model name.
        extra:
            Additional provider-specific keyword arguments to pass to the chat
            client.
        region:
            AWS region for the Bedrock service.
        bearer_token:
            Optional bearer token value, or path to a file containing the
            token.
        aws_profile:
            Optional AWS profile name.
        aws_access_key_id:
            Optional AWS access key ID.
        aws_secret_access_key:
            Optional AWS secret access key.
        aws_session_token:
            Optional AWS session token.
        override_env_credentials:
            Whether adapter setup may overwrite existing AWS credential-related
            environment variables.

    Methods:
        __post_init__:
            Expand environment variables, resolve file-based bearer tokens, and
            validate the configuration.
        validate:
            Validate required Bedrock region and authentication settings.
        to_client_kwargs:
            Convert the configuration into keyword arguments for a Bedrock chat
            client.
    """

    region: str

    # Pick whichever auth style your runtime actually uses
    bearer_token: Optional[str] = None  # can use API key from Bedrock
    aws_profile: Optional[str] = None
    aws_access_key_id: Optional[str] = None
    aws_secret_access_key: Optional[str] = None
    aws_session_token: Optional[str] = None

    # Choose whether we're allowed to override AWS_* env variables from these settings
    override_env_credentials: bool = False

    def __post_init__(self):
        """
        Expand environment variables, resolve file-based bearer tokens, and
        validate the configuration.
        """
        super().__post_init__()
        self.region = expand_env_vars(self.region)
        self.bearer_token = expand_env_vars(self.bearer_token)
        self.aws_profile = expand_env_vars(self.aws_profile)
        self.aws_access_key_id = expand_env_vars(self.aws_access_key_id)
        self.aws_secret_access_key = expand_env_vars(self.aws_secret_access_key)
        self.aws_session_token = expand_env_vars(self.aws_session_token)

        if self.bearer_token and os.path.exists(self.bearer_token):
            with open(self.bearer_token, "r") as token_file:
                self.bearer_token = token_file.read().strip()

        self.validate()

    def validate(self) -> None:
        """
        Validate required Bedrock configuration values and authentication
        settings.

        Raises:
            RuntimeError:
                Raised if `region` is missing, if no supported authentication
                method is provided, or if more than one authentication method
                is provided.
        """
        if not self.region:
            raise RuntimeError("BedrockModelConfig requires 'region'")

        if self.aws_access_key_id and not self.aws_secret_access_key:
            raise RuntimeError(
                "BedrockModelConfig received 'aws_access_key_id' without "
                "'aws_secret_access_key'"
            )

        if self.aws_secret_access_key and not self.aws_access_key_id:
            raise RuntimeError(
                "BedrockModelConfig received 'aws_secret_access_key' without "
                "'aws_access_key_id'"
            )

        has_bearer = bool(self.bearer_token)
        has_profile = bool(self.aws_profile)
        has_full_aws_creds = bool(self.aws_access_key_id and self.aws_secret_access_key)

        if self.aws_session_token and not has_full_aws_creds:
            raise RuntimeError(
                "BedrockModelConfig received 'aws_session_token' without "
                "both 'aws_access_key_id' and 'aws_secret_access_key'"
            )

        auth_method_count = sum(
            [
                has_bearer,
                has_profile,
                has_full_aws_creds,
            ]
        )

        if auth_method_count == 0:
            raise RuntimeError(
                "BedrockModelConfig requires exactly one authentication method: "
                "'bearer_token', 'aws_profile', or both "
                "'aws_access_key_id' and 'aws_secret_access_key'"
            )

        if auth_method_count > 1:
            raise RuntimeError(
                "BedrockModelConfig received multiple authentication methods. "
                "Specify exactly one of: 'bearer_token', 'aws_profile', or "
                "both 'aws_access_key_id' and 'aws_secret_access_key'"
            )

    def to_client_kwargs(self) -> Dict[str, Any]:
        """
        Convert the configuration into Bedrock chat client keyword arguments.

        Returns:
            A dictionary of keyword arguments for Bedrock chat client
            construction.
        """
        return {
            "model": self.model,
            "region": self.region,
            **self.extra,
        }

`__post_init__()`

Expand environment variables, resolve file-based bearer tokens, and validate the configuration.

Source code in src/mada/core/config/models.py

def __post_init__(self):
    """
    Expand environment variables, resolve file-based bearer tokens, and
    validate the configuration.
    """
    super().__post_init__()
    self.region = expand_env_vars(self.region)
    self.bearer_token = expand_env_vars(self.bearer_token)
    self.aws_profile = expand_env_vars(self.aws_profile)
    self.aws_access_key_id = expand_env_vars(self.aws_access_key_id)
    self.aws_secret_access_key = expand_env_vars(self.aws_secret_access_key)
    self.aws_session_token = expand_env_vars(self.aws_session_token)

    if self.bearer_token and os.path.exists(self.bearer_token):
        with open(self.bearer_token, "r") as token_file:
            self.bearer_token = token_file.read().strip()

    self.validate()

`to_client_kwargs()`

Convert the configuration into Bedrock chat client keyword arguments.

Returns:

Type	Description
`Dict[str, Any]`	A dictionary of keyword arguments for Bedrock chat client
`Dict[str, Any]`	construction.

Source code in src/mada/core/config/models.py

def to_client_kwargs(self) -> Dict[str, Any]:
    """
    Convert the configuration into Bedrock chat client keyword arguments.

    Returns:
        A dictionary of keyword arguments for Bedrock chat client
        construction.
    """
    return {
        "model": self.model,
        "region": self.region,
        **self.extra,
    }

`validate()`

Validate required Bedrock configuration values and authentication settings.

Raises:

Type	Description
`RuntimeError`	Raised if `region` is missing, if no supported authentication method is provided, or if more than one authentication method is provided.

Source code in src/mada/core/config/models.py

def validate(self) -> None:
    """
    Validate required Bedrock configuration values and authentication
    settings.

    Raises:
        RuntimeError:
            Raised if `region` is missing, if no supported authentication
            method is provided, or if more than one authentication method
            is provided.
    """
    if not self.region:
        raise RuntimeError("BedrockModelConfig requires 'region'")

    if self.aws_access_key_id and not self.aws_secret_access_key:
        raise RuntimeError(
            "BedrockModelConfig received 'aws_access_key_id' without "
            "'aws_secret_access_key'"
        )

    if self.aws_secret_access_key and not self.aws_access_key_id:
        raise RuntimeError(
            "BedrockModelConfig received 'aws_secret_access_key' without "
            "'aws_access_key_id'"
        )

    has_bearer = bool(self.bearer_token)
    has_profile = bool(self.aws_profile)
    has_full_aws_creds = bool(self.aws_access_key_id and self.aws_secret_access_key)

    if self.aws_session_token and not has_full_aws_creds:
        raise RuntimeError(
            "BedrockModelConfig received 'aws_session_token' without "
            "both 'aws_access_key_id' and 'aws_secret_access_key'"
        )

    auth_method_count = sum(
        [
            has_bearer,
            has_profile,
            has_full_aws_creds,
        ]
    )

    if auth_method_count == 0:
        raise RuntimeError(
            "BedrockModelConfig requires exactly one authentication method: "
            "'bearer_token', 'aws_profile', or both "
            "'aws_access_key_id' and 'aws_secret_access_key'"
        )

    if auth_method_count > 1:
        raise RuntimeError(
            "BedrockModelConfig received multiple authentication methods. "
            "Specify exactly one of: 'bearer_token', 'aws_profile', or "
            "both 'aws_access_key_id' and 'aws_secret_access_key'"
        )

`OpenAIModelConfig` `dataclass`

Bases: BaseModelConfig

Configuration for OpenAI-compatible chat clients.

This configuration supports literal API keys, environment-variable-expanded values, or file paths containing API keys, along with the base URL for the target service.

Attributes:

Name	Type	Description
`provider`	`str`	Name of the provider associated with the model configuration.
`model`	`str`	Requested model name.
`extra`	`Dict[str, Any]`	Additional provider-specific keyword arguments to pass to the chat client.
`api_key`	`str`	API key value, environment-expanded string, or path to a file containing the API key.
`base_url`	`str`	Base URL for the OpenAI-compatible endpoint.

Methods:

Name	Description
`__post_init__`	Expand environment variables, resolve file-based API keys, and validate the configuration.
`validate`	Validate that required OpenAI-compatible settings are present.
`to_client_kwargs`	Convert the configuration into keyword arguments for an OpenAI-compatible chat client.

Source code in src/mada/core/config/models.py

@dataclass(kw_only=True)
class OpenAIModelConfig(BaseModelConfig):
    """
    Configuration for OpenAI-compatible chat clients.

    This configuration supports literal API keys, environment-variable-expanded
    values, or file paths containing API keys, along with the base URL for the
    target service.

    Attributes:
        provider:
            Name of the provider associated with the model configuration.
        model:
            Requested model name.
        extra:
            Additional provider-specific keyword arguments to pass to the chat
            client.
        api_key:
            API key value, environment-expanded string, or path to a file
            containing the API key.
        base_url:
            Base URL for the OpenAI-compatible endpoint.

    Methods:
        __post_init__:
            Expand environment variables, resolve file-based API keys, and
            validate the configuration.
        validate:
            Validate that required OpenAI-compatible settings are present.
        to_client_kwargs:
            Convert the configuration into keyword arguments for an
            OpenAI-compatible chat client.
    """

    api_key: str  # Can be literal string, env var, or path to file containing API key
    base_url: str

    def __post_init__(self):
        """
        Expand environment variables, resolve file-based API keys, and validate
        the configuration.
        """
        super().__post_init__()
        self.api_key = expand_env_vars(self.api_key)
        self.base_url = expand_env_vars(self.base_url)

        if os.path.exists(self.api_key):
            with open(self.api_key, "r") as api_key_file:
                self.api_key = api_key_file.read().strip()

        self.validate()

    def validate(self) -> None:
        """
        Validate required OpenAI-compatible configuration values.

        Raises:
            RuntimeError:
                Raised if `api_key` or `base_url` is missing.
        """
        if not self.api_key:
            raise RuntimeError(
                "API key not found for OpenAI-compatible model config. "
                "Please specify 'api_key'."
            )
        if not self.base_url:
            raise RuntimeError(
                "Base URL not found for OpenAI-compatible model config. "
                "Please specify 'base_url'."
            )

    def to_client_kwargs(self) -> Dict[str, Any]:
        """
        Convert the configuration into OpenAI-compatible chat client keyword
        arguments.

        Returns:
            A dictionary of keyword arguments for OpenAI-compatible chat client
            construction.
        """
        return {
            "model": self.model,
            "api_key": self.api_key,
            "base_url": self.base_url,
            **self.extra,
        }

`__post_init__()`

Expand environment variables, resolve file-based API keys, and validate the configuration.

Source code in src/mada/core/config/models.py

def __post_init__(self):
    """
    Expand environment variables, resolve file-based API keys, and validate
    the configuration.
    """
    super().__post_init__()
    self.api_key = expand_env_vars(self.api_key)
    self.base_url = expand_env_vars(self.base_url)

    if os.path.exists(self.api_key):
        with open(self.api_key, "r") as api_key_file:
            self.api_key = api_key_file.read().strip()

    self.validate()

`to_client_kwargs()`

Convert the configuration into OpenAI-compatible chat client keyword arguments.

Returns:

Type	Description
`Dict[str, Any]`	A dictionary of keyword arguments for OpenAI-compatible chat client
`Dict[str, Any]`	construction.

Source code in src/mada/core/config/models.py

def to_client_kwargs(self) -> Dict[str, Any]:
    """
    Convert the configuration into OpenAI-compatible chat client keyword
    arguments.

    Returns:
        A dictionary of keyword arguments for OpenAI-compatible chat client
        construction.
    """
    return {
        "model": self.model,
        "api_key": self.api_key,
        "base_url": self.base_url,
        **self.extra,
    }

`validate()`

Validate required OpenAI-compatible configuration values.

Raises:

Type	Description
`RuntimeError`	Raised if `api_key` or `base_url` is missing.

Source code in src/mada/core/config/models.py

def validate(self) -> None:
    """
    Validate required OpenAI-compatible configuration values.

    Raises:
        RuntimeError:
            Raised if `api_key` or `base_url` is missing.
    """
    if not self.api_key:
        raise RuntimeError(
            "API key not found for OpenAI-compatible model config. "
            "Please specify 'api_key'."
        )
    if not self.base_url:
        raise RuntimeError(
            "Base URL not found for OpenAI-compatible model config. "
            "Please specify 'base_url'."
        )

`load_model_config(config_dict)`

Load a provider-specific model configuration object from a dictionary.

Parameters:

Name	Type	Description	Default
`config_dict`	`Dict[str, Any]`	Dictionary containing serialized model configuration values.	required

Returns:

Type	Description
`ModelConfig`	An initialized provider-specific model configuration instance.

Raises:

Type	Description
`ValueError`	Raised if `provider` is missing or unsupported.

Source code in src/mada/core/config/models.py

def load_model_config(config_dict: Dict[str, Any]) -> ModelConfig:
    """
    Load a provider-specific model configuration object from a dictionary.

    Args:
        config_dict:
            Dictionary containing serialized model configuration values.

    Returns:
        An initialized provider-specific model configuration instance.

    Raises:
        ValueError:
            Raised if `provider` is missing or unsupported.
    """
    provider = config_dict.get("provider")
    if not provider:
        raise ValueError("Model config must include 'provider'")

    if provider in {"openai", "livai"}:
        return OpenAIModelConfig(**config_dict)

    if provider == "aws-bedrock":
        return BedrockModelConfig(**config_dict)

    raise ValueError(f"Unsupported model provider: {provider}")

models

BaseModelConfig dataclass

__post_init__()

to_client_kwargs()

validate()

BedrockModelConfig dataclass

__post_init__()

to_client_kwargs()

validate()

OpenAIModelConfig dataclass

__post_init__()

to_client_kwargs()

validate()

load_model_config(config_dict)

`BaseModelConfig` `dataclass`

`__post_init__()`

`to_client_kwargs()`

`validate()`

`BedrockModelConfig` `dataclass`

`__post_init__()`

`to_client_kwargs()`

`validate()`

`OpenAIModelConfig` `dataclass`

`__post_init__()`

`to_client_kwargs()`

`validate()`

`load_model_config(config_dict)`