mada 0.1.0__py3-none-any.whl

mada/__init__.py

@@ -0,0 +1,11 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+MADA - Multi-agent orchestration system for MADA workflows.
+
+This package provides orchestration capabilities for coordinating multiple
+autonomous agents that interact with MCP servers to execute complex workflows.
+"""
+
+__version__ = "0.1.0"

mada/common/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+The common package includes code commonly used across the entire
+MADA project.
+
+Modules:
+    exceptions: Custom exceptions for MADA.
+"""
+
+from mada.common.exceptions import MADAUnsupportedDatabase
+
+__all__ = ["MADAUnsupportedDatabase"]

mada/common/exceptions.py

@@ -0,0 +1,12 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+Custom exceptions for MADA.
+"""
+
+class MADAUnsupportedDatabase(Exception):
+    """
+    Used when trying to initialize a connection to an unsupported
+    database type.
+    """

mada/core/__init__.py

@@ -0,0 +1,64 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+Core orchestration functionality.
+
+This module contains the fundamental components for orchestrating multi-agent workflows.
+"""
+
+
+from mada.core.chat_clients import (
+    BedrockAdapter,
+    LivAIAdapter,
+    MADAChatClientFactory,
+    OpenAIAdapter,
+    ProviderAdapter,
+    chat_client_factory,
+)
+from mada.core.config import (
+    AgentConfig,
+    AppConfig,
+    BaseModelConfig,
+    BedrockModelConfig,
+    DatabaseConfig,
+    InterfaceConfig,
+    MCPServerConfig,
+    ModelConfig,
+    OpenAIModelConfig,
+    PostgreSQLConfig,
+    SQLiteConfig,
+    expand_env_vars,
+    load_config_from_json,
+    load_database_config,
+    load_model_config,
+)
+from mada.core.coordinator import MCPAgentManager
+from mada.core.orchestrator import MADAOrchestrator
+
+
+__all__ = [
+    "AgentConfig",
+    "AppConfig",
+    "BaseModelConfig",
+    "BedrockAdapter",
+    "BedrockModelConfig",
+    "DatabaseConfig",
+    "InterfaceConfig",
+    "LivAIAdapter",
+    "MADAChatClientFactory",
+    "MADAOrchestrator",
+    "MCPAgentManager",
+    "MCPServerConfig",
+    "ModelConfig",
+    "OpenAIAdapter",
+    "OpenAIModelConfig",
+    "PostgreSQLConfig",
+    "ProviderAdapter",
+    "SQLiteConfig",
+    "chat_client_factory",
+    "expand_env_vars",
+    "load_config_from_json",
+    "load_database_config",
+    "load_model_config",
+]

mada/core/chat_clients/__init__.py

@@ -0,0 +1,47 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+Chat client adapter package.
+
+This package provides provider-specific chat client adapters and factory
+utilities for creating chat clients from model configuration objects. It
+exposes adapter implementations for supported providers, along with the shared
+[`ProviderAdapter`][core.chat_clients.provider_adapter.ProviderAdapter] base
+class and the
+[`MADAChatClientFactory`][core.chat_clients.chat_client_factory.MADAChatClientFactory]
+used to create chat clients.
+
+Modules:
+    bedrock_adapter:
+        Provides the [`BedrockAdapter`][core.chat_clients.bedrock_adapter.BedrockAdapter]
+        implementation for AWS Bedrock models.
+    chat_client_factory:
+        Provides [`MADAChatClientFactory`][core.chat_clients.chat_client_factory.MADAChatClientFactory]
+        and the shared `chat_client_factory` instance for constructing chat clients.
+    livai_adapter:
+        Provides the [`LivAIAdapter`][core.chat_clients.livai_adapter.LivAIAdapter]
+        implementation for LivAI-hosted models.
+    openai_adapter:
+        Provides the [`OpenAIAdapter`][core.chat_clients.openai_adapter.OpenAIAdapter]
+        implementation for OpenAI models.
+    provider_adapter:
+        Provides the shared [`ProviderAdapter`][core.chat_clients.provider_adapter.ProviderAdapter]
+        base class and related model metadata utilities.
+"""
+
+from mada.core.chat_clients.bedrock_adapter import BedrockAdapter
+from mada.core.chat_clients.chat_client_factory import MADAChatClientFactory, chat_client_factory
+from mada.core.chat_clients.livai_adapter import LivAIAdapter
+from mada.core.chat_clients.openai_adapter import OpenAIAdapter
+from mada.core.chat_clients.provider_adapter import ProviderAdapter
+
+
+__all__ = [
+    "BedrockAdapter",
+    "LivAIAdapter",
+    "MADAChatClientFactory",
+    "OpenAIAdapter",
+    "ProviderAdapter",
+    "chat_client_factory",
+]

mada/core/chat_clients/bedrock_adapter.py

@@ -0,0 +1,120 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+AWS Bedrock provider adapter implementation.
+
+This module defines [`BedrockAdapter`][core.chat_clients.bedrock_adapter.BedrockAdapter],
+a [`ProviderAdapter`][core.chat_clients.provider_adapter.ProviderAdapter] implementation
+for AWS Bedrock chat models. It validates that incoming model configuration objects are
+instances of [`BedrockModelConfig`][core.config.models.BedrockModelConfig] and prepares
+AWS authentication environment variables before chat client creation.
+"""
+
+import os
+
+from agent_framework.amazon import BedrockChatClient
+
+from mada.core.config import BaseModelConfig, BedrockModelConfig
+from mada.core.chat_clients.provider_adapter import ProviderAdapter
+
+
+class BedrockAdapter(ProviderAdapter):
+    """
+    Provider adapter for AWS Bedrock chat models.
+
+    This adapter validates Bedrock-specific model configuration objects and sets
+    AWS credential-related environment variables before constructing a chat
+    client.
+
+    Attributes:
+        provider_name:
+            Name of the provider handled by this adapter.
+        chat_client:
+            Chat client class used to create Bedrock chat clients.
+
+    Methods:
+        validate_model_config:
+            Validate that `model_config` is a `BedrockModelConfig` instance.
+        _set_env_if_allowed:
+            Set an environment variable if permitted by the current
+            configuration.
+        pre_create:
+            Apply environment-based credential configuration before client
+            creation.
+    """
+
+    provider_name = "aws-bedrock"
+    chat_client = BedrockChatClient
+
+    def validate_model_config(self, model_config: BaseModelConfig) -> None:
+        """
+        Validate that `model_config` is compatible with the Bedrock adapter.
+
+        Args:
+            model_config:
+                Model configuration to validate.
+
+        Raises:
+            TypeError:
+                Raised if `model_config` is not a `BedrockModelConfig`
+                instance.
+        """
+        if not isinstance(model_config, BedrockModelConfig):
+            raise TypeError(
+                f"{self.provider_name} adapter requires BedrockModelConfig, "
+                f"got {type(model_config).__name__}"
+            )
+
+    def _set_env_if_allowed(self, name: str, value: str, override: bool = False) -> None:
+        """
+        Set an environment variable if a value is provided and overwriting is
+        allowed.
+
+        Args:
+            name:
+                Name of the environment variable to set.
+            value:
+                Value to assign to `name`.
+            override:
+                Whether an existing conflicting environment variable may be
+                overwritten.
+
+        Raises:
+            RuntimeError:
+                Raised if `name` is already set to a different value and
+                `override` is `False`.
+        """
+        if not value:
+            return
+
+        existing = os.environ.get(name)
+        if existing and existing != value and not override:
+            raise RuntimeError(
+                f"Refusing to overwrite existing environment variable '{name}'. "
+                f"Set override_env_credentials=True to allow this."
+            )
+
+        os.environ[name] = value
+
+    def pre_create(self, model_config: BedrockModelConfig) -> None:
+        """
+        Prepare AWS credential environment variables before client creation.
+
+        Args:
+            model_config:
+                Bedrock model configuration containing credential values and
+                override settings.
+
+        Raises:
+            RuntimeError:
+                Raised if an existing environment variable would be overwritten
+                without permission.
+        """
+        override = getattr(model_config, "override_env_credentials", False)
+
+        self._set_env_if_allowed("AWS_BEARER_TOKEN_BEDROCK", model_config.bearer_token, override)
+        self._set_env_if_allowed("AWS_PROFILE", model_config.aws_profile, override)
+        self._set_env_if_allowed("AWS_ACCESS_KEY_ID", model_config.aws_access_key_id, override)
+        self._set_env_if_allowed("AWS_SECRET_ACCESS_KEY", model_config.aws_secret_access_key, override)
+        self._set_env_if_allowed("AWS_SESSION_TOKEN", model_config.aws_session_token, override)

mada/core/chat_clients/chat_client_factory.py

@@ -0,0 +1,123 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+Factory utilities for creating chat clients from provider-specific adapters.
+
+This module exposes
+[`MADAChatClientFactory`][core.chat_clients.chat_client_factory.MADAChatClientFactory],
+which registers built-in provider adapters and creates
+[`agent_framework.BaseChatClient`](https://learn.microsoft.com/en-us/python/api/agent-framework-core/agent_framework.basechatclient?view=agent-framework-python-latest)
+instances from a [`BaseModelConfig`][core.config.models.BaseModelConfig].
+"""
+
+import logging
+from typing import Dict, Optional
+
+from agent_framework import BaseChatClient
+
+from mada.core.config import BaseModelConfig
+from mada.core.chat_clients.bedrock_adapter import BedrockAdapter
+from mada.core.chat_clients.livai_adapter import LivAIAdapter
+from mada.core.chat_clients.openai_adapter import OpenAIAdapter
+from mada.core.chat_clients.provider_adapter import ProviderAdapter
+
+
+LOG = logging.getLogger("mada-interface")
+
+
+class MADAChatClientFactory:
+    """
+    Factory for registering provider adapters and creating chat clients.
+
+    The factory maintains a mapping of provider names to `ProviderAdapter`
+    instances. Each adapter is responsible for validating configuration and
+    constructing the provider-specific client.
+
+    Attributes:
+        _adapters:
+            Mapping of provider names to registered provider adapters.
+
+    Methods:
+        register_provider_adapter:
+            Register a provider adapter with the factory.
+        get_adapter:
+            Return the adapter registered for a provider.
+        create:
+            Create a chat client from a model configuration.
+    """
+
+    def __init__(self):
+        """
+        Initialize the factory and register built-in provider adapters.
+        """
+        self._adapters: Dict[str, ProviderAdapter] = {}
+        self._register_builtins()
+
+    def _register_builtins(self) -> None:
+        """
+        Register the default provider adapters supported by the application.
+        """
+        self.register_provider_adapter(OpenAIAdapter())
+        self.register_provider_adapter(LivAIAdapter())
+        self.register_provider_adapter(BedrockAdapter())
+
+    def register_provider_adapter(self, adapter: ProviderAdapter) -> None:
+        """
+        Register a provider adapter with the factory.
+
+        Args:
+            adapter:
+                Provider adapter to register, keyed by its `provider_name`
+                attribute.
+        """
+        self._adapters[adapter.provider_name] = adapter
+        LOG.debug("Registered provider adapter '%s'", adapter.provider_name)
+
+    def get_adapter(self, provider: str) -> Optional[ProviderAdapter]:
+        """
+        Return the registered adapter for a provider, if available.
+
+        Args:
+            provider:
+                Provider name.
+
+        Returns:
+            The matching provider adapter, or `None` if the provider is not
+            registered.
+        """
+        return self._adapters.get(provider)
+
+    def create(self, model_config: BaseModelConfig) -> BaseChatClient:
+        """
+        Create a chat client for the provider and model in `model_config`.
+
+        Args:
+            model_config:
+                Model configuration containing the target provider and model
+                details.
+
+        Returns:
+            A provider-specific chat client instance.
+
+        Raises:
+            ValueError:
+                If no adapter is registered for the requested provider, or if
+                client creation fails.
+        """
+        adapter = self._adapters.get(model_config.provider)
+        if adapter is None:
+            raise ValueError(
+                f"No provider adapter registered for provider '{model_config.provider}'"
+            )
+
+        try:
+            return adapter.create_client(model_config)
+        except Exception as e:
+            raise ValueError(
+                f"Failed to create chat client for provider='{model_config.provider}', "
+                f"model='{model_config.model}': {e}"
+            ) from e
+
+
+chat_client_factory = MADAChatClientFactory()

mada/core/chat_clients/livai_adapter.py

@@ -0,0 +1,34 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+LivAI provider adapter implementation.
+
+This module defines [`LivAIAdapter`][core.chat_clients.livai_adapter.LivAIAdapter],
+an [`OpenAIAdapter`][core.chat_clients.openai_adapter.OpenAIAdapter] specialization
+for LivAI-hosted models.
+"""
+
+from agent_framework.openai import OpenAIChatClient
+
+from mada.core.chat_clients.openai_adapter import OpenAIAdapter
+
+
+class LivAIAdapter(OpenAIAdapter):
+    """
+    Provider adapter for LivAI-hosted chat models.
+
+    LivAI models are served through OpenAI's API, so we can re-use the
+    same behavior as the
+    [`OpenAIAdapter`][core.chat_clients.openai_adapter.OpenAIAdapter],
+    while exposing a different provider name.
+
+    Attributes:
+        provider_name:
+            Name of the provider handled by this adapter.
+        chat_client:
+            Chat client class used to create LivAI chat clients.
+    """
+
+    provider_name = "livai"
+    chat_client = OpenAIChatClient

mada/core/chat_clients/openai_adapter.py

@@ -0,0 +1,58 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+OpenAI provider adapter implementation.
+
+This module defines [`OpenAIAdapter`][core.chat_clients.openai_adapter.OpenAIAdapter],
+a [`ProviderAdapter`][core.chat_clients.provider_adapter.ProviderAdapter] implementation
+for OpenAI chat models. It validates that incoming model configuration objects are
+instances of [`OpenAIModelConfig`][core.config.models.OpenAIModelConfig] before client
+creation.
+"""
+
+from agent_framework.openai import OpenAIChatClient
+
+from mada.core.config import BaseModelConfig, OpenAIModelConfig
+from mada.core.chat_clients.provider_adapter import ProviderAdapter
+
+
+class OpenAIAdapter(ProviderAdapter):
+    """
+    Provider adapter for OpenAI chat models.
+
+    This adapter ensures that client creation uses `OpenAIModelConfig`
+    instances.
+
+    Attributes:
+        provider_name:
+            Name of the provider handled by this adapter.
+        chat_client:
+            Chat client class used to create OpenAI chat clients.
+
+    Methods:
+        validate_model_config:
+            Validate that `model_config` is an `OpenAIModelConfig` instance.
+    """
+
+    provider_name = "openai"
+    chat_client = OpenAIChatClient
+
+    def validate_model_config(self, model_config: BaseModelConfig) -> None:
+        """
+        Validate that `model_config` is compatible with the OpenAI adapter.
+
+        Args:
+            model_config:
+                Model configuration to validate.
+
+        Raises:
+            TypeError:
+                Raised if `model_config` is not an `OpenAIModelConfig`
+                instance.
+        """
+        if not isinstance(model_config, OpenAIModelConfig):
+            raise TypeError(
+                f"{self.provider_name} adapter requires OpenAIModelConfig, "
+                f"got {type(model_config).__name__}"
+            )

mada/core/chat_clients/provider_adapter.py

@@ -0,0 +1,96 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+Provider adapter abstractions.
+
+This module defines the shared abstract base class used to implement
+provider-specific chat client adapters.
+
+A provider adapter is responsible for:
+
+- validating that a model configuration object is compatible with the provider
+- performing any provider-specific setup before client creation
+- constructing a Microsoft Agent Framework chat client instance directly from
+  the user-supplied model configuration
+"""
+
+
+from abc import ABC, abstractmethod
+from typing import Type
+
+from agent_framework import BaseChatClient
+
+from mada.core.config import BaseModelConfig
+
+
+class ProviderAdapter(ABC):
+    """
+    Abstract base class for provider-specific chat client adapters.
+
+    Attributes:
+        provider_name:
+            Name of the provider handled by the adapter.
+        chat_client:
+            Chat client class used to instantiate provider-specific clients.
+
+    Methods:
+        validate_model_config:
+            Validate a model configuration before client creation.
+        pre_create:
+            Perform provider-specific setup before client creation.
+        create_client:
+            Validate configuration and create a chat client instance.
+    """
+
+    provider_name: str
+    chat_client: Type[BaseChatClient]
+
+    @abstractmethod
+    def validate_model_config(self, model_config: BaseModelConfig) -> None:
+        """
+        Validate a model configuration for this provider.
+
+        Args:
+            model_config:
+                Model configuration to validate.
+
+        Raises:
+            ValueError:
+                If the configuration is invalid for the provider.
+        """
+        pass
+
+    def pre_create(self, model_config: BaseModelConfig) -> None:
+        """
+        Run provider-specific logic before constructing the chat client.
+
+        This hook allows subclasses to inspect configuration or perform setup
+        before the client instance is created.
+
+        Args:
+            model_config:
+                Model configuration being used to create the client.
+        """
+        pass
+
+    def create_client(self, model_config: BaseModelConfig) -> BaseChatClient:
+        """
+        Create a provider-specific chat client from a model configuration.
+
+        This method validates the configuration, executes any provider-specific
+        pre-creation hook, and instantiates the configured chat client using
+        the exact user-supplied model name.
+
+        Args:
+            model_config:
+                Model configuration used to build the client.
+
+        Returns:
+            An initialized provider-specific chat client.
+        """
+        self.validate_model_config(model_config)
+        self.pre_create(model_config)
+
+        kwargs = model_config.to_client_kwargs()
+        return self.chat_client(**kwargs)

mada/core/config/__init__.py

@@ -0,0 +1,65 @@
+# Copyright 2026, Lawrence Livermore National Security, LLC and MADA contributors
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+Configuration package for the MADA orchestrator.
+
+This package provides configuration models and helper utilities used to define
+application behavior, model backends, agents, database settings, MCP server
+connections, interface settings, and environment variable expansion.
+
+Modules:
+    agents:
+        Defines [`AgentConfig`][core.config.agents.AgentConfig] for individual
+        agent configuration and serialization helpers.
+    app:
+        Defines [`AppConfig`][core.config.app.AppConfig] and utilities for loading
+        full application configuration from JSON.
+    database:
+        Defines database configuration models for SQLite and PostgreSQL, along
+        with database config loading helpers.
+    interface:
+        Defines [`InterfaceConfig`][core.config.interface.InterfaceConfig] for
+        multi-agent interface layout and UI customization settings.
+    mcp_servers:
+        Defines [`MCPServerConfig`][core.config.mcp_servers.MCPServerConfig] for
+        individual MCP server connection and launch settings.
+    models:
+        Defines provider model configuration classes and model config loading
+        helpers.
+    utils:
+        Defines shared utility helpers, including environment variable
+        expansion.
+"""
+
+from mada.core.config.agents import AgentConfig
+from mada.core.config.app import AppConfig, load_config_from_json
+from mada.core.config.database import DatabaseConfig, PostgreSQLConfig, SQLiteConfig, load_database_config
+from mada.core.config.interface import InterfaceConfig
+from mada.core.config.mcp_servers import MCPServerConfig
+from mada.core.config.models import (
+    ModelConfig,
+    BaseModelConfig,
+    BedrockModelConfig,
+    OpenAIModelConfig,
+    load_model_config,
+)
+from mada.core.config.utils import expand_env_vars
+
+__all__ = [
+    "AgentConfig",
+    "AppConfig",
+    "BaseModelConfig",
+    "BedrockModelConfig",
+    "DatabaseConfig",
+    "InterfaceConfig",
+    "MCPServerConfig",
+    "ModelConfig",
+    "OpenAIModelConfig",
+    "PostgreSQLConfig",
+    "SQLiteConfig",
+    "expand_env_vars",
+    "load_config_from_json",
+    "load_database_config",
+    "load_model_config",
+]