mail-swarms 1.3.2__py3-none-any.whl

mail/swarms_json/__init__.py

@@ -0,0 +1,27 @@
+from .types import (
+    SwarmsJSONAction,
+    SwarmsJSONAgent,
+    SwarmsJSONFile,
+    SwarmsJSONSwarm,
+)
+from .utils import (
+    build_action_from_swarms_json,
+    build_agent_from_swarms_json,
+    build_swarm_from_swarms_json,
+    build_swarms_from_swarms_json,
+    load_swarms_json_from_file,
+    load_swarms_json_from_string,
+)
+
+__all__ = [
+    "SwarmsJSONAction",
+    "SwarmsJSONAgent",
+    "SwarmsJSONFile",
+    "SwarmsJSONSwarm",
+    "build_action_from_swarms_json",
+    "build_agent_from_swarms_json",
+    "build_swarm_from_swarms_json",
+    "build_swarms_from_swarms_json",
+    "load_swarms_json_from_file",
+    "load_swarms_json_from_string",
+]

mail/swarms_json/types.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+from typing import Any, Literal, TypedDict
+
+
+class SwarmsJSONFile(TypedDict):
+    """
+    A standardized container for MAIL swarms and their configuration.
+    """
+
+    swarms: list["SwarmsJSONSwarm"]
+
+
+class SwarmsJSONSwarm(TypedDict):
+    """
+    A MAIL swarm and its configuration, following the `swarms.json` format.
+    """
+
+    name: str
+    """The swarm's name."""
+    version: str
+    """The version of `mail` to build this swarm with."""
+    description: str  # default: ""
+    """The description of the swarm."""
+    keywords: list[str]  # default: []
+    """The keywords of the swarm."""
+    public: bool  # default: False
+    """Whether this swarm is publicly accessible."""
+    entrypoint: str
+    """The name of the swarm's default entrypoint agent."""
+    enable_interswarm: bool  # default: False
+    """Whether to enable interswarm communication for this swarm."""
+    action_imports: list[str]  # default: []
+    """Python import strings that resolve to pre-built MAILAction instances."""
+    agents: list["SwarmsJSONAgent"]
+    """The agents in this swarm."""
+    actions: list["SwarmsJSONAction"]
+    """The actions in this swarm."""
+    breakpoint_tools: list[str]  # default: []
+    """The tools that can be used to breakpoint the swarm."""
+    exclude_tools: list[str]  # default: []
+    """The names of MAIL tools that should not be available to the swarm."""
+    enable_db_agent_histories: bool  # default: False
+    """Whether to enable database persistence for agent histories."""
+
+
+class SwarmsJSONAgent(TypedDict):
+    """
+    A MAIL agent and its configuration, following the `swarms.json` format.
+    """
+
+    name: str
+    """The agent's name."""
+    factory: str
+    """The agent's factory function as a Python import string."""
+    comm_targets: list[str]
+    """The names of the agents this agent can communicate with."""
+    enable_entrypoint: bool  # default: False
+    """Whether this agent can be used as a swarm entrypoint."""
+    enable_interswarm: bool  # default: False
+    """Whether this agent can communicate with other swarms."""
+    can_complete_tasks: bool  # default: False
+    """Whether this agent can complete tasks."""
+    tool_format: Literal["completions", "responses"]  # default: "responses"
+    """The format of the tools this agent can use."""
+    actions: list[str]  # default: []
+    """The names of the actions this agent can use."""
+    agent_params: dict[str, Any]
+    """The parameters for this agent."""
+    exclude_tools: list[str]  # default: []
+    """The names ofMAIL tools that should not be available to this agent."""
+
+
+class SwarmsJSONAction(TypedDict):
+    """
+    A MAIL action and its configuration, following the `swarms.json` format.
+    """
+
+    name: str
+    """The action's name."""
+    description: str
+    """The action's description."""
+    parameters: dict[str, Any]
+    """The parameters for this action."""
+    function: str
+    """The action's function as a Python import string."""

mail/swarms_json/utils.py

@@ -0,0 +1,255 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+import json
+import warnings
+from typing import Any
+
+from .types import (
+    SwarmsJSONAction,
+    SwarmsJSONAgent,
+    SwarmsJSONFile,
+    SwarmsJSONSwarm,
+)
+
+
+def load_swarms_json_from_file(path: str) -> SwarmsJSONFile:
+    """
+    Load a `swarms.json` file from a given path.
+    """
+    with open(path) as f:
+        contents = json.load(f)
+        if not isinstance(contents, list):
+            raise ValueError(
+                f"swarms.json file at {path} must contain a list of swarms, actually got {type(contents)}"
+            )
+        for swarm in contents:
+            validate_swarm_from_swarms_json(swarm)
+        return SwarmsJSONFile(swarms=contents)
+
+
+def load_swarms_json_from_string(contents: str) -> SwarmsJSONFile:
+    """
+    Load a `swarms.json` string from a given string of contents.
+    """
+    contents = json.loads(contents)
+    if not isinstance(contents, list):
+        raise ValueError(
+            f"swarms.json string must contain a list of swarms, actually got {type(contents)}"
+        )
+    for swarm in contents:
+        validate_swarm_from_swarms_json(swarm)
+    return SwarmsJSONFile(swarms=contents)
+
+
+def build_swarms_from_swarms_json(contents: list[Any]) -> list[SwarmsJSONSwarm]:
+    """
+    Build a list of `SwarmsJSONSwarm` from a list of `SwarmsJSONFile` contents.
+    """
+    for swarm_candidate in contents:
+        validate_swarm_from_swarms_json(swarm_candidate)
+
+    return [
+        build_swarm_from_swarms_json(swarm_candidate) for swarm_candidate in contents
+    ]
+
+
+def validate_swarm_from_swarms_json(swarm_candidate: Any) -> None:
+    """
+    Ensure the candidate is a valid `SwarmsJSONSwarm`.
+    """
+    if not isinstance(swarm_candidate, dict):
+        raise ValueError(
+            f"swarm candidate must be a dict, actually got {type(swarm_candidate)}"
+        )
+
+    REQUIRED_FIELDS: dict[str, type] = {
+        "name": str,
+        "version": str,
+        "entrypoint": str,
+        "agents": list,
+        "actions": list,
+    }
+
+    OPTIONAL_FIELDS: dict[str, type] = {
+        "enable_interswarm": bool,
+        "breakpoint_tools": list,
+        "exclude_tools": list,
+        "action_imports": list,
+    }
+
+    for field, field_type in REQUIRED_FIELDS.items():
+        if field not in swarm_candidate:
+            raise ValueError(f"swarm candidate must contain a '{field}' field")
+        if not isinstance(swarm_candidate[field], field_type):
+            raise ValueError(
+                f"swarm candidate field '{field}' must be a {field_type.__name__}, actually got {type(swarm_candidate[field])}"
+            )
+
+    for field, field_type in OPTIONAL_FIELDS.items():
+        if field not in swarm_candidate:
+            continue
+        if not isinstance(swarm_candidate[field], field_type):
+            raise ValueError(
+                f"swarm candidate field '{field}' must be a {field_type.__name__}, actually got {type(swarm_candidate[field])}"
+            )
+
+    if "action_imports" in swarm_candidate:
+        imports = swarm_candidate["action_imports"]
+        if any(not isinstance(item, str) for item in imports):
+            raise ValueError(
+                "swarm candidate field 'action_imports' must be a list of strings"
+            )
+
+    return
+
+
+def build_swarm_from_swarms_json(swarm_candidate: Any) -> SwarmsJSONSwarm:
+    """
+    Build a `SwarmsJSONSwarm` from a candidate.
+    """
+    validate_swarm_from_swarms_json(swarm_candidate)
+    return SwarmsJSONSwarm(
+        name=swarm_candidate["name"],
+        version=swarm_candidate["version"],
+        description=swarm_candidate.get("description", ""),
+        keywords=swarm_candidate.get("keywords", []),
+        public=swarm_candidate.get("public", False),
+        entrypoint=swarm_candidate["entrypoint"],
+        agents=[
+            build_agent_from_swarms_json(agent) for agent in swarm_candidate["agents"]
+        ],
+        actions=[
+            build_action_from_swarms_json(action)
+            for action in swarm_candidate["actions"]
+        ],
+        action_imports=swarm_candidate.get("action_imports", []),
+        enable_interswarm=swarm_candidate.get("enable_interswarm", False),
+        breakpoint_tools=swarm_candidate.get("breakpoint_tools", []),
+        exclude_tools=swarm_candidate.get("exclude_tools", []),
+        enable_db_agent_histories=swarm_candidate.get(
+            "enable_db_agent_histories", False
+        ),
+    )
+
+
+def validate_agent_from_swarms_json(agent_candidate: Any) -> None:
+    """
+    Ensure the candidate is a valid `SwarmsJSONAgent`.
+    """
+    if not isinstance(agent_candidate, dict):
+        raise ValueError(
+            f"agent candidate must be a dict, actually got {type(agent_candidate)}"
+        )
+
+    REQUIRED_FIELDS: dict[str, type] = {
+        "name": str,
+        "factory": str,
+        "comm_targets": list,
+        "agent_params": dict,
+    }
+
+    OPTIONAL_FIELDS: dict[str, type] = {
+        "enable_entrypoint": bool,
+        "enable_interswarm": bool,
+        "can_complete_tasks": bool,
+        "tool_format": str,
+        "actions": list,
+    }
+
+    for field, field_type in REQUIRED_FIELDS.items():
+        if field not in agent_candidate:
+            raise ValueError(f"agent candidate must contain a '{field}' field")
+        if not isinstance(agent_candidate[field], field_type):
+            raise ValueError(
+                f"agent candidate field '{field}' must be a {field_type.__name__}, actually got {type(agent_candidate[field])}"
+            )
+
+    for field, field_type in OPTIONAL_FIELDS.items():
+        if field not in agent_candidate:
+            continue
+        if not isinstance(agent_candidate[field], field_type):
+            raise ValueError(
+                f"agent candidate field '{field}' must be a {field_type.__name__}, actually got {type(agent_candidate[field])}"
+            )
+
+    # Warn about deprecated tool_format placement
+    if "agent_params" in agent_candidate:
+        if "tool_format" in agent_candidate["agent_params"]:
+            warnings.warn(
+                f"agent '{agent_candidate.get('name', '?')}' has tool_format inside agent_params; "
+                "this is deprecated, use top-level tool_format instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+    return
+
+
+def build_agent_from_swarms_json(agent_candidate: Any) -> SwarmsJSONAgent:
+    """
+    Build a `SwarmsJSONAgent` from a candidate.
+    """
+    validate_agent_from_swarms_json(agent_candidate)
+    return SwarmsJSONAgent(
+        name=agent_candidate["name"],
+        factory=agent_candidate["factory"],
+        comm_targets=agent_candidate["comm_targets"],
+        agent_params=agent_candidate["agent_params"],
+        enable_entrypoint=agent_candidate.get("enable_entrypoint", False),
+        enable_interswarm=agent_candidate.get("enable_interswarm", False),
+        can_complete_tasks=agent_candidate.get("can_complete_tasks", False),
+        tool_format=agent_candidate.get("tool_format", "responses"),
+        actions=agent_candidate.get("actions", []),
+        exclude_tools=agent_candidate.get("exclude_tools", []),
+    )
+
+
+def validate_action_from_swarms_json(action_candidate: Any) -> None:
+    """
+    Ensure the candidate is a valid `SwarmsJSONAction`.
+    """
+    if not isinstance(action_candidate, dict):
+        raise ValueError(
+            f"action candidate must be a dict, actually got {type(action_candidate)}"
+        )
+
+    REQUIRED_FIELDS: dict[str, type] = {
+        "name": str,
+        "description": str,
+        "parameters": dict,
+        "function": str,
+    }
+
+    OPTIONAL_FIELDS: dict[str, type] = {}
+
+    for field, field_type in REQUIRED_FIELDS.items():
+        if field not in action_candidate:
+            raise ValueError(f"action candidate must contain a '{field}' field")
+        if not isinstance(action_candidate[field], field_type):
+            raise ValueError(
+                f"action candidate field '{field}' must be a {field_type.__name__}, actually got {type(action_candidate[field])}"
+            )
+
+    for field, field_type in OPTIONAL_FIELDS.items():
+        if field not in action_candidate:
+            continue
+        if not isinstance(action_candidate[field], field_type):
+            raise ValueError(
+                f"action candidate field '{field}' must be a {field_type.__name__}, actually got {type(action_candidate[field])}"
+            )
+
+    return
+
+
+def build_action_from_swarms_json(action_candidate: Any) -> SwarmsJSONAction:
+    """
+    Build a `SwarmsJSONAction` from a candidate.
+    """
+    validate_action_from_swarms_json(action_candidate)
+    return SwarmsJSONAction(
+        name=action_candidate["name"],
+        description=action_candidate["description"],
+        parameters=action_candidate["parameters"],
+        function=action_candidate["function"],
+    )

mail/url_scheme.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+"""
+URL scheme parsing for swarm:// URLs.
+
+Supports:
+    swarm://connect?server=<host>&token=<api_key>
+    swarm://invite?server=<host>&token=<api_key>
+"""
+
+from dataclasses import dataclass
+from urllib.parse import parse_qs, urlparse
+
+
+@dataclass
+class SwarmURL:
+    """Parsed swarm:// URL."""
+
+    action: str  # "connect" or "invite"
+    server: str | None = None
+    token: str | None = None
+
+
+def parse_swarm_url(url: str) -> SwarmURL | None:
+    """
+    Parse a swarm:// URL into its components.
+
+    Args:
+        url: The URL to parse (e.g., "swarm://connect?server=example.com&token=abc")
+
+    Returns:
+        SwarmURL if the URL is a valid swarm:// URL, None otherwise.
+    """
+    if not url.startswith("swarm://"):
+        return None
+
+    parsed = urlparse(url)
+
+    # For swarm://connect?server=x, parsed.netloc = "connect", parsed.query = "server=x"
+    action = parsed.netloc
+
+    if action in ("connect", "invite"):
+        params = parse_qs(parsed.query)
+        return SwarmURL(
+            action=action,
+            server=params.get("server", [None])[0],
+            token=params.get("token", [None])[0],
+        )
+
+    return None

mail/utils/__init__.py

@@ -0,0 +1,53 @@
+from .auth import (
+    caller_is_admin,
+    caller_is_admin_or_user,
+    caller_is_agent,
+    caller_is_user,
+    extract_token,
+    extract_token_info,
+    get_token_info,
+    login,
+    require_debug,
+)
+from .logger import (
+    get_loggers,
+    init_logger,
+)
+from .parsing import (
+    read_python_string,
+    resolve_prefixed_string_references,
+    target_address_is_interswarm,
+)
+from .serialize import (
+    export,
+    serialize_mail_value,
+)
+from .store import (
+    get_langmem_store,
+)
+from .version import (
+    get_protocol_version,
+    get_version,
+)
+
+__all__ = [
+    "login",
+    "get_token_info",
+    "get_loggers",
+    "init_logger",
+    "read_python_string",
+    "resolve_prefixed_string_references",
+    "target_address_is_interswarm",
+    "get_langmem_store",
+    "caller_is_admin",
+    "caller_is_user",
+    "caller_is_admin_or_user",
+    "caller_is_agent",
+    "extract_token_info",
+    "extract_token",
+    "get_version",
+    "get_protocol_version",
+    "export",
+    "serialize_mail_value",
+    "require_debug",
+]

mail/utils/auth.py

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+import logging
+import os
+from typing import Any
+
+import aiohttp
+from fastapi import HTTPException, Request
+
+JWT_SECRET = os.getenv("JWT_SECRET")
+
+logger = logging.getLogger("mail.auth")
+
+
+async def check_auth_endpoints() -> None:
+    """
+    Check if the auth endpoints are set.
+    This is necessary for the server to start.
+    """
+    AUTH_ENDPOINTS = ["AUTH_ENDPOINT", "TOKEN_INFO_ENDPOINT"]
+    for endpoint in AUTH_ENDPOINTS:
+        if endpoint not in os.environ or os.getenv(endpoint) is None:
+            logger.error(f"required environment variable '{endpoint}' is not set")
+            raise Exception(f"required environment variable '{endpoint}' is not set")
+
+
+def extract_token(request: Request) -> str:
+    """
+    Extract the token from the request.
+    """
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        return auth_header.split(" ")[1]
+    else:
+        raise HTTPException(status_code=401, detail="invalid API key format")
+
+
+async def login(api_key: str) -> str:
+    """
+    Authenticate a user with an API key.
+
+    Args:
+        api_key: The API key to validate
+
+    Returns:
+        A user token if authentication is successful
+
+    Raises:
+        ValueError: If the API key is invalid
+    """
+    await check_auth_endpoints()
+    AUTH_ENDPOINT = os.getenv("AUTH_ENDPOINT")
+
+    # hit the login endpoint in the auth service
+    async with aiohttp.ClientSession() as session:
+        response = await session.post(
+            f"{AUTH_ENDPOINT}", headers={"Authorization": f"Bearer {api_key}"}
+        )
+        if response.status == 200:
+            data = await response.json()
+            logger.info(
+                f"[[green]{api_key[:8]}...[/green]] user or agent authenticated with API key"
+            )
+            return data["token"]
+        elif response.status == 401:
+            logger.warning(f"invalid API key: '{api_key}'")
+            raise HTTPException(status_code=401, detail="invalid API key")
+        else:
+            logger.error(
+                f"failed to authenticate user or agent with API key: '{api_key}': '{response.status}'"
+            )
+            raise HTTPException(
+                status_code=500,
+                detail="failed to authenticate user or agent with API key",
+            )
+
+
+async def get_token_info(token: str) -> dict[str, Any]:
+    """
+    Get information about a JWT.
+    """
+    await check_auth_endpoints()
+    TOKEN_INFO_ENDPOINT = os.getenv("TOKEN_INFO_ENDPOINT")
+
+    async with aiohttp.ClientSession() as session:
+        response = await session.get(
+            f"{TOKEN_INFO_ENDPOINT}", headers={"Authorization": f"Bearer {token}"}
+        )
+        if response.status == 200:
+            data = await response.json()
+            return data
+        elif response.status == 401:
+            logger.warning(f"invalid token: '{token}'")
+            raise HTTPException(status_code=401, detail="invalid token")
+        else:
+            logger.error(f"failed to get token info: '{token}': '{response.status}'")
+            raise HTTPException(status_code=500, detail="failed to get token info")
+
+
+async def caller_is_role(
+    request: Request, role: str, raise_on_false: bool = True
+) -> bool:
+    """
+    Check if the caller is a specific role.
+    """
+    token = request.headers.get("Authorization")
+    if token is None:
+        logger.warning("no API key provided")
+        raise HTTPException(status_code=401, detail="no API key provided")
+
+    if token.startswith("Bearer "):
+        token = token.split(" ")[1]
+    else:
+        logger.warning("invalid API key format: missing 'Bearer' prefix")
+        if raise_on_false:
+            raise HTTPException(status_code=401, detail="invalid API key format")
+        return False
+
+    # login to the auth service
+    jwt = await login(token)
+
+    token_info = await get_token_info(jwt)
+    if token_info["role"] != role:
+        if raise_on_false:
+            logger.warning(f"invalid role: '{token_info['role']}' != '{role}'")
+            raise HTTPException(status_code=401, detail="invalid role")
+        return False
+
+    return True
+
+
+async def caller_is_admin(request: Request, raise_on_false: bool = True) -> bool:
+    """
+    Check if the caller is an `admin`.
+    """
+    return await caller_is_role(request, "admin", raise_on_false)
+
+
+async def caller_is_user(request: Request, raise_on_false: bool = True) -> bool:
+    """
+    Check if the caller is a `user`.
+    """
+    return await caller_is_role(request, "user", raise_on_false)
+
+
+async def caller_is_admin_or_user(request: Request) -> bool:
+    """
+    Check if the caller is an `admin` or a `user`.
+    """
+    is_admin = await caller_is_admin(request, raise_on_false=False)
+    is_user = await caller_is_user(request, raise_on_false=False)
+    if is_admin or is_user:
+        return True
+
+    logger.warning("invalid role: caller is not admin or user")
+    raise HTTPException(status_code=401, detail="invalid role")
+
+
+async def caller_is_agent(request: Request, raise_on_false: bool = True) -> bool:
+    """
+    Check if the caller is an `agent`.
+    """
+    return await caller_is_role(request, "agent", raise_on_false)
+
+
+async def extract_token_info(request: Request) -> dict[str, Any]:
+    """
+    Extract the token info from the request.
+    """
+    token = request.headers.get("Authorization")
+
+    if token is None:
+        logger.warning("no API key provided")
+        raise HTTPException(status_code=401, detail="no API key provided")
+    if token.startswith("Bearer "):
+        token = token.split(" ")[1]
+    else:
+        logger.warning("invalid API key format: missing 'Bearer' prefix")
+        raise HTTPException(status_code=401, detail="invalid API key format")
+
+    # login to the auth service
+    jwt = await login(token)
+
+    return await get_token_info(jwt)
+
+
+def require_debug(request: Request) -> None:
+    """
+    Require the debug mode to be enabled.
+    """
+    if not request.app.state.debug:
+        logger.warning("debug mode is not enabled")
+        raise HTTPException(status_code=404, detail="Not found")

mail/utils/context.py

@@ -0,0 +1,17 @@
+from functools import lru_cache
+
+import litellm
+
+
+@lru_cache(maxsize=1000)
+def get_model_ctx_len(llm: str) -> int:
+    """
+    Get the context length of a model from the LiteLLM model cost map.
+    """
+    item = litellm.model_cost.get(llm)
+    if item is None:
+        _, slug = llm.split("/")
+        item = litellm.model_cost.get(slug)
+    if item is None:
+        return 0
+    return item.get("max_input_tokens", 0)