mail-swarms 1.3.2__py3-none-any.whl

mail/config/__init__.py

@@ -0,0 +1,8 @@
+from .client import ClientConfig
+from .server import ServerConfig, SwarmConfig
+
+__all__ = [
+    "ServerConfig",
+    "SwarmConfig",
+    "ClientConfig",
+]

mail/config/client.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+from __future__ import annotations
+
+import logging
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - fallback for older runtimes
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ModuleNotFoundError:  # pragma: no cover - hard fallback
+        tomllib = None  # type: ignore[assignment]
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_mail_config_path() -> Path | None:
+    """
+    Determine the best candidate path for `mail.toml`.
+    """
+
+    env_path = os.getenv("MAIL_CONFIG_PATH")
+    if env_path:
+        candidate = Path(env_path).expanduser()
+        if candidate.is_file():
+            return candidate
+        logger.debug(f"MAIL_CONFIG_PATH set to {candidate} but file missing")
+
+    cwd_candidate = Path.cwd() / "mail.toml"
+    if cwd_candidate.is_file():
+        return cwd_candidate
+
+    for ancestor in Path(__file__).resolve().parents:
+        candidate = ancestor / "mail.toml"
+        if candidate.is_file():
+            return candidate
+
+    return None
+
+
+@lru_cache(maxsize=1)
+def _client_defaults() -> dict[str, Any]:
+    """
+    Resolve client defaults from `mail.toml`, falling back to literals.
+    """
+
+    defaults: dict[str, Any] = {
+        "timeout": 3600.0,
+        "verbose": False,
+    }
+
+    if tomllib is None:
+        logger.debug("tomllib not available; using built-in client defaults")
+        return defaults
+
+    config_path = _resolve_mail_config_path()
+    if config_path is None:
+        logger.debug("mail.toml not found; using built-in client defaults")
+        return defaults
+
+    try:
+        with config_path.open("rb") as config_file:
+            raw_config = tomllib.load(config_file)
+    except Exception as e:  # pragma: no cover - uncommon failure
+        logger.warning(f"failed to load {config_path}: {e}")
+        return defaults
+
+    client_section = raw_config.get("client")
+    if isinstance(client_section, dict):
+        if "timeout" in client_section:
+            defaults["timeout"] = float(client_section["timeout"])
+        if "verbose" in client_section:
+            defaults["verbose"] = bool(client_section["verbose"])
+    return defaults
+
+
+class ClientConfig(BaseModel):
+    timeout: float = Field(default_factory=lambda: _client_defaults()["timeout"])
+    verbose: bool = Field(default_factory=lambda: _client_defaults()["verbose"])

mail/config/server.py

@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+from __future__ import annotations
+
+import logging
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - fallback for older runtimes
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ModuleNotFoundError:  # pragma: no cover - hard fallback
+        tomllib = None  # type: ignore[assignment]
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_mail_config_path() -> Path | None:
+    """
+    Determine the best candidate path for `mail.toml`.
+    """
+
+    env_path = os.getenv("MAIL_CONFIG_PATH")
+    if env_path:
+        candidate = Path(env_path).expanduser()
+        if candidate.is_file():
+            return candidate
+        logger.warning(f"MAIL_CONFIG_PATH set to {candidate} but file missing")
+
+    cwd_candidate = Path.cwd() / "mail.toml"
+    if cwd_candidate.is_file():
+        return cwd_candidate
+
+    for ancestor in Path(__file__).resolve().parents:
+        candidate = ancestor / "mail.toml"
+        if candidate.is_file():
+            return candidate
+
+    return None
+
+
+@lru_cache(maxsize=1)
+def _load_defaults_from_toml() -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    """
+    Read default server + swarm fields from `mail.toml` if available.
+    """
+
+    server_defaults: dict[str, Any] = {
+        "port": 8000,
+        "host": "0.0.0.0",
+        "reload": False,
+        "debug": False,
+    }
+    swarm_defaults: dict[str, Any] = {
+        "name": "example-no-proxy",
+        "source": "swarms.json",
+        "registry_file": "registries/example-no-proxy.json",
+        "description": "",
+        "keywords": [],
+        "public": False,
+    }
+    settings_defaults: dict[str, Any] = {
+        "task_message_limit": 15,
+    }
+
+    if tomllib is None:
+        logger.warning("tomllib not available; using built-in defaults")
+        return server_defaults, swarm_defaults, settings_defaults
+
+    config_path = _resolve_mail_config_path()
+    if config_path is None:
+        logger.warning("mail.toml not found; using built-in defaults")
+        return server_defaults, swarm_defaults, settings_defaults
+
+    try:
+        with config_path.open("rb") as config_file:
+            raw_config = tomllib.load(config_file)
+    except Exception as e:  # pragma: no cover - uncommon failure
+        logger.warning(f"failed to load {config_path}: {e}")
+        return server_defaults, swarm_defaults, settings_defaults
+
+    server_section = raw_config.get("server")
+    if isinstance(server_section, dict):
+        server_defaults = {
+            "port": server_section.get("port", server_defaults["port"]),
+            "host": server_section.get("host", server_defaults["host"]),
+            "reload": server_section.get("reload", server_defaults["reload"]),
+            "debug": server_section.get("debug", server_defaults["debug"]),
+        }
+
+        swarm_section = server_section.get("swarm")
+        if isinstance(swarm_section, dict):
+            registry_value = swarm_section.get("registry")
+            if registry_value is None:
+                registry_value = swarm_section.get("registry_file")
+
+            swarm_defaults = {
+                "name": swarm_section.get("name", swarm_defaults["name"]),
+                "source": swarm_section.get("source", swarm_defaults["source"]),
+                "registry_file": registry_value or swarm_defaults["registry_file"],
+                "description": swarm_section.get(
+                    "description", swarm_defaults["description"]
+                ),
+                "keywords": swarm_section.get("keywords", swarm_defaults["keywords"]),
+                "public": swarm_section.get("public", swarm_defaults["public"]),
+            }
+
+            settings_section = server_section.get("settings")
+            if isinstance(settings_section, dict):
+                settings_defaults = {
+                    "task_message_limit": settings_section.get(
+                        "task_message_limit", settings_defaults["task_message_limit"]
+                    ),
+                }
+
+    logger.info(
+        f"server defaults resolved to {server_defaults} with swarm defaults {swarm_defaults}",
+    )
+    return server_defaults, swarm_defaults, settings_defaults
+
+
+def _server_defaults() -> dict[str, Any]:
+    return _load_defaults_from_toml()[0]
+
+
+def _swarm_defaults() -> dict[str, Any]:
+    return _load_defaults_from_toml()[1]
+
+
+def _settings_defaults() -> dict[str, Any]:
+    return _load_defaults_from_toml()[2]
+
+
+class SwarmConfig(BaseModel):
+    name: str = Field(default_factory=lambda: _swarm_defaults()["name"])
+    description: str = Field(default_factory=lambda: _swarm_defaults()["description"])
+    keywords: list[str] = Field(default_factory=lambda: _swarm_defaults()["keywords"])
+    public: bool = Field(default_factory=lambda: _swarm_defaults()["public"])
+    source: str = Field(default_factory=lambda: _swarm_defaults()["source"])
+    registry_file: str = Field(
+        default_factory=lambda: _swarm_defaults()["registry_file"]
+    )
+
+
+class SettingsConfig(BaseModel):
+    task_message_limit: int = Field(
+        default_factory=lambda: _settings_defaults()["task_message_limit"]
+    )
+
+
+class ServerConfig(BaseModel):
+    port: int = Field(default_factory=lambda: _server_defaults()["port"])
+    host: str = Field(default_factory=lambda: _server_defaults()["host"])
+    reload: bool = Field(default_factory=lambda: _server_defaults()["reload"])
+    debug: bool = Field(default_factory=lambda: _server_defaults()["debug"])
+
+    swarm: SwarmConfig = Field(default_factory=SwarmConfig)
+    settings: SettingsConfig = Field(default_factory=SettingsConfig)

mail/core/__init__.py

@@ -0,0 +1,72 @@
+from .actions import ActionFunction, ActionOverrideFunction
+from .agents import AgentCore, AgentFunction
+from .message import (
+    MAILAddress,
+    MAILBroadcast,
+    MAILInterrupt,
+    MAILInterswarmMessage,
+    MAILMessage,
+    MAILRequest,
+    MAILResponse,
+    create_admin_address,
+    create_agent_address,
+    create_system_address,
+    create_user_address,
+    format_agent_address,
+    parse_agent_address,
+)
+from .runtime import MAILRuntime
+from .tools import (
+    MAIL_TOOL_NAMES,
+    AgentToolCall,
+    convert_call_to_mail_message,
+    create_acknowledge_broadcast_tool,
+    create_broadcast_tool,
+    create_ignore_broadcast_tool,
+    create_interrupt_tool,
+    create_interswarm_broadcast_tool,
+    create_mail_tools,
+    create_request_tool,
+    create_response_tool,
+    create_supervisor_tools,
+    create_swarm_discovery_tool,
+    create_task_complete_tool,
+    pydantic_model_to_tool,
+)
+
+__all__ = [
+    "ActionFunction",
+    "ActionOverrideFunction",
+    "AgentFunction",
+    "AgentCore",
+    "AgentToolCall",
+    "MAILAddress",
+    "MAILBroadcast",
+    "MAILInterrupt",
+    "MAILInterswarmMessage",
+    "MAILMessage",
+    "MAILRequest",
+    "MAILResponse",
+    "create_agent_address",
+    "create_admin_address",
+    "create_system_address",
+    "create_user_address",
+    "format_agent_address",
+    "parse_agent_address",
+    "MAILRuntime",
+    "MAIL_TOOL_NAMES",
+    "AgentToolCall",
+    "convert_call_to_mail_message",
+    "create_acknowledge_broadcast_tool",
+    "create_broadcast_tool",
+    "create_ignore_broadcast_tool",
+    "create_interrupt_tool",
+    "create_interswarm_broadcast_tool",
+    "create_mail_tools",
+    "create_request_tool",
+    "create_response_tool",
+    "create_supervisor_tools",
+    "create_swarm_discovery_tool",
+    "create_task_complete_tool",
+    "pydantic_model_to_tool",
+]

mail/core/actions.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline, Ryan Heaton
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+import logging
+
+from mail.core.tools import AgentToolCall
+
+ActionFunction = Callable[[dict[str, Any]], Awaitable[str]]
+"""
+A function that executes an action tool and returns the response.
+"""
+
+ActionOverrideFunction = Callable[[dict[str, Any]], Awaitable[dict[str, Any] | str]]
+"""
+A function that overrides an action tool and returns the response.
+"""
+
+
+class ActionCore:
+    """
+    A bare-bones action structure.
+    Contains only the action function and essential metadata.
+    """
+
+    def __init__(
+        self,
+        function: ActionFunction,
+        name: str,
+        parameters: dict[str, Any],
+    ):
+        self.name = name
+        self.parameters = parameters
+        self.function = function
+
+    async def execute(
+        self,
+        call: AgentToolCall,
+        actions: dict[str, "ActionCore"] | None = None,
+        action_override: ActionOverrideFunction | None = None,
+    ) -> tuple[Literal["success", "error"], dict[str, str]]:
+        """
+        Execute an action tool and return the response within a MAIL runtime.
+        """
+        logger = logging.getLogger("mail.actions")
+        if actions:
+            action = actions.get(self.name)
+            if action:
+                return await action.execute(call, action_override=action_override)
+
+        if not action_override:
+            try:
+                content = await self.function(call.tool_args)
+                return ("success", {"content": content})
+            except Exception as e:
+                return ("error", {"content": f"failed to execute action tool: {e}"})
+        else:
+            try:
+                response = await action_override(call)  # type: ignore
+                logger.info(f"action override response: {response}")
+                if isinstance(response, str):
+                    return ("success", {"content": response})
+                return ("success", response)
+            except Exception as e:
+                return (
+                    "error",
+                    {"content": f"failed to execute action override tool: {e}"},
+                )

mail/core/agents.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline, Ryan Heaton
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from .actions import ActionCore
+from .tools import AgentToolCall
+
+AgentOutput = tuple[str | None, list[AgentToolCall]]
+"""
+Response type of a MAIL agent containing a response and tool calls.
+"""
+
+AgentFunction = Callable[
+    [list[dict[str, Any]], str | dict[str, str]],
+    Awaitable[AgentOutput],
+]
+"""
+A function that takes a chat history and returns a response and tool calls.
+"""
+
+
+class AgentCore:
+    """
+    A bare-bones agent structure.
+    Contains only the agent function and essential metadata.
+    """
+
+    def __init__(
+        self,
+        function: AgentFunction,
+        comm_targets: list[str],
+        actions: dict[str, ActionCore] | None = None,
+        enable_entrypoint: bool = False,
+        enable_interswarm: bool = False,
+        can_complete_tasks: bool = False,
+    ):
+        self.function = function
+        self.comm_targets = comm_targets
+        if actions is None:
+            self.actions = {}
+        else:
+            self.actions = actions
+        self.enable_entrypoint = enable_entrypoint
+        self.enable_interswarm = enable_interswarm
+        self.can_complete_tasks = can_complete_tasks
+
+    def can_access_action_or_tool(self, name: str) -> bool:
+        """
+        Check if the agent can access a tool by name.
+        """
+        match name:
+            case (
+                "send_request"
+                | "send_response"
+                | "send_interrupt"
+                | "send_broadcast"
+                | "acknowledge_broadcast"
+                | "ignore_broadcast"
+                | "help"
+            ):
+                return True
+            case "task_complete":
+                return self.can_complete_tasks
+            case _:
+                return name in self.actions
+
+    def can_access_action(self, action_name: str) -> bool:
+        """
+        Check if the agent can access an action by name.
+        """
+        return action_name in self.actions