mail-swarms 1.3.2__py3-none-any.whl

mail/stdlib/interswarm/actions.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+from typing import Any
+
+import aiohttp
+
+from mail import action
+
+SWARM_URL_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "url": {
+            "type": "string",
+            "description": "The URL of the remote swarm.",
+        },
+    },
+    "required": ["url"],
+}
+
+
+@action(
+    name="ping_swarm",
+    description="Check if a remote URL hosts an active MAIL swarm.",
+    parameters=SWARM_URL_PARAMETERS,
+)
+async def ping_swarm(args: dict[str, Any]) -> str:
+    """
+    Check if a remote URL is a valid, active MAIL swarm.
+
+    Args:
+        url: The URL of the remote swarm.
+
+    Returns:
+        "pong" if the URL represents an active MAIL swarm, otherwise an error message.
+    """
+    url = args.get("url")
+    if url is None:
+        return "Error: `url` is required"
+    if not isinstance(url, str):
+        return "Error: `url` must be a string"
+
+    # attempt to ping (`GET /`) the remote swarm
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url) as response:
+                if response.status == 200:
+                    if await _is_valid_mail_root_response(response):
+                        return "pong"
+                    else:
+                        return "Error: remote URL is not a valid MAIL swarm"
+                else:
+                    return f"Error: remote URL returned status code {response.status}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+@action(
+    name="get_swarm_health",
+    description="Get the health status of a remote MAIL swarm.",
+    parameters=SWARM_URL_PARAMETERS,
+)
+async def get_swarm_health(args: dict[str, Any]) -> str:
+    """
+    Get the health of a remote MAIL swarm.
+
+    Args:
+        url: The URL of the remote swarm.
+
+    Returns:
+        The health status string of the swarm, otherwise an error message.
+    """
+    url = args.get("url")
+    if url is None:
+        return "Error: `url` is required"
+    if not isinstance(url, str):
+        return "Error: `url` must be a string"
+
+    # attempt to `GET /health` on the remote swarm
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url + "/health") as response:
+                if response.status == 200:
+                    if await _is_valid_mail_health_response(response):
+                        json = await response.json()
+                        return json.get("status")
+                    else:
+                        return "Error: remote URL is not a valid MAIL swarm"
+                else:
+                    return f"Error: remote URL returned status code {response.status}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+@action(
+    name="get_swarm_registry",
+    description="Fetch the registry listing for a remote MAIL swarm.",
+    parameters=SWARM_URL_PARAMETERS,
+)
+async def get_swarm_registry(args: dict[str, Any]) -> str:
+    """
+    Get the registry of the remote MAIL swarm.
+
+    Args:
+        url: The URL of the remote swarm.
+
+    Returns:
+        The registry of the remote MAIL swarm, otherwise an error message.
+    """
+    url = args.get("url")
+    if url is None:
+        return "Error: `url` is required"
+    if not isinstance(url, str):
+        return "Error: `url` must be a string"
+
+    # attempt to `GET /swarms` on the remote swarm
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url + "/swarms") as response:
+                if response.status == 200:
+                    if await _is_valid_mail_swarms_response(response):
+                        return await _swarm_registry_response_str(response)
+                    else:
+                        return "Error: remote URL is not a valid MAIL swarm"
+                else:
+                    return f"Error: remote URL returned status code {response.status}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+async def _is_valid_mail_root_response(response: aiohttp.ClientResponse) -> bool:
+    """
+    Based on the response to `GET /`, determine if the remote URL is in fact a valid MAIL swarm.
+    """
+    json = await response.json()
+    name = json.get("name")
+    swarm = json.get("swarm")
+    status = json.get("status")
+
+    if not name or not swarm or not status:
+        return False
+    if (
+        not isinstance(name, str)
+        or not isinstance(swarm, dict)
+        or not isinstance(status, str)
+    ):
+        return False
+    if name != "mail" or status != "running":
+        return False
+    if not isinstance(swarm.get("name"), str) or not isinstance(
+        swarm.get("entrypoint"), str
+    ):
+        return False
+
+    return True
+
+
+async def _is_valid_mail_health_response(response: aiohttp.ClientResponse) -> bool:
+    """
+    Based on the response to `GET /health`, determine if the remote URL is in fact a valid MAIL swarm.
+    """
+    json = await response.json()
+    status = json.get("status")
+    swarm_name = json.get("swarm_name")
+
+    if not status or not swarm_name:
+        return False
+    if not isinstance(status, str) or not isinstance(swarm_name, str):
+        return False
+
+    return True
+
+
+async def _is_valid_mail_swarms_response(response: aiohttp.ClientResponse) -> bool:
+    """
+    Based on the response to `GET /swarms`, determine if the remote URL is in fact a valid MAIL swarm.
+    """
+    json = await response.json()
+    swarms = json.get("swarms")
+
+    if not swarms:
+        return False
+    if not isinstance(swarms, list):
+        return False
+    for swarm in swarms:
+        if not isinstance(swarm, dict):
+            return False
+        if not isinstance(swarm.get("swarm_name"), str) or not isinstance(
+            swarm.get("base_url"), str
+        ):
+            return False
+
+    return True
+
+
+async def _swarm_registry_response_str(response: aiohttp.ClientResponse) -> str:
+    """
+    Convert the response to `GET /swarms` to a string representation of the registry.
+    """
+    json = await response.json()
+    swarms = json.get("swarms")
+
+    if not swarms:
+        return "No swarms found"
+    if not isinstance(swarms, list):
+        return "Error: `swarms` is not a list"
+
+    return "\n".join([f"{swarm['swarm_name']}@{swarm['base_url']}" for swarm in swarms])

mail/stdlib/mcp/__init__.py

@@ -0,0 +1,19 @@
+from .actions import (
+    mcp_call_tool,
+    mcp_get_prompt,
+    mcp_list_prompts,
+    mcp_list_resources,
+    mcp_list_tools,
+    mcp_ping,
+    mcp_read_resource,
+)
+
+__all__ = [
+    "mcp_ping",
+    "mcp_list_tools",
+    "mcp_call_tool",
+    "mcp_get_prompt",
+    "mcp_list_prompts",
+    "mcp_list_resources",
+    "mcp_read_resource",
+]

mail/stdlib/mcp/actions.py

@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+from typing import Any
+
+from fastmcp import Client
+
+from mail import action
+
+MCP_PING_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "server_url": {
+            "type": "string",
+            "description": "The URL of the remote MCP server.",
+        },
+    },
+    "required": ["server_url"],
+}
+
+
+@action(
+    name="mcp_ping",
+    description="Ping a remote MCP server.",
+    parameters=MCP_PING_PARAMETERS,
+)
+async def mcp_ping(args: dict[str, Any]) -> str:
+    """
+    Ping a remote MCP server.
+    """
+    server_url = args.get("server_url")
+
+    if server_url is None:
+        return "Error: `server_url` is required"
+    if not isinstance(server_url, str):
+        return "Error: `server_url` must be a string"
+
+    try:
+        client = Client(server_url)
+        async with client:
+            result = await client.ping()
+            return str(result)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+MCP_LIST_TOOLS_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "server_url": {
+            "type": "string",
+            "description": "The URL of the remote MCP server.",
+        },
+    },
+    "required": ["server_url"],
+}
+
+
+@action(
+    name="mcp_list_tools",
+    description="List the tools on a remote MCP server.",
+    parameters=MCP_LIST_TOOLS_PARAMETERS,
+)
+async def mcp_list_tools(args: dict[str, Any]) -> str:
+    """
+    List the tools on a remote MCP server.
+    """
+
+    server_url = args.get("server_url")
+
+    if server_url is None:
+        return "Error: `server_url` is required"
+    if not isinstance(server_url, str):
+        return "Error: `server_url` must be a string"
+
+    try:
+        client = Client(server_url)
+        async with client:
+            result = await client.list_tools()
+            return str(result)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+MCP_CALL_TOOL_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "server_url": {
+            "type": "string",
+            "description": "The URL of the remote MCP server.",
+        },
+        "tool_name": {
+            "type": "string",
+            "description": "The name of the tool to call.",
+        },
+        "tool_input": {
+            "type": "object",
+            "description": "The input to the tool.",
+        },
+    },
+    "required": ["server_url", "tool_name", "tool_input"],
+}
+
+
+@action(
+    name="mcp_call_tool",
+    description="Call a tool on a remote MCP server.",
+    parameters=MCP_CALL_TOOL_PARAMETERS,
+)
+async def mcp_call_tool(args: dict[str, Any]) -> str:
+    """
+    Call a tool on a remote MCP server.
+    """
+    server_url = args.get("server_url")
+    tool_name = args.get("tool_name")
+    tool_input = args.get("tool_input")
+
+    if server_url is None:
+        return "Error: `server_url` is required"
+    if tool_name is None:
+        return "Error: `tool_name` is required"
+    if tool_input is None:
+        return "Error: `tool_input` is required"
+
+    if not isinstance(server_url, str):
+        return "Error: `server_url` must be a string"
+    if not isinstance(tool_name, str):
+        return "Error: `tool_name` must be a string"
+    if not isinstance(tool_input, dict):
+        return "Error: `tool_input` must be a dictionary"
+
+    try:
+        client = Client(server_url)
+        async with client:
+            result = await client.call_tool(tool_name, tool_input)
+            return str(result)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+MCP_GET_PROMPT_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "server_url": {
+            "type": "string",
+            "description": "The URL of the remote MCP server.",
+        },
+        "prompt_name": {
+            "type": "string",
+            "description": "The name of the prompt to get.",
+        },
+    },
+    "required": ["server_url", "prompt_name"],
+}
+
+
+@action(
+    name="mcp_get_prompt",
+    description="Get a prompt from a remote MCP server.",
+    parameters=MCP_GET_PROMPT_PARAMETERS,
+)
+async def mcp_get_prompt(args: dict[str, Any]) -> str:
+    """
+    Get a prompt from a remote MCP server.
+    """
+    server_url = args.get("server_url")
+    prompt_name = args.get("prompt_name")
+
+    if server_url is None:
+        return "Error: `server_url` is required"
+    if prompt_name is None:
+        return "Error: `prompt_name` is required"
+
+    if not isinstance(server_url, str):
+        return "Error: `server_url` must be a string"
+    if not isinstance(prompt_name, str):
+        return "Error: `prompt_name` must be a string"
+
+    try:
+        client = Client(server_url)
+        async with client:
+            result = await client.get_prompt(prompt_name)
+            return str(result)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+@action(
+    name="mcp_list_prompts",
+    description="List the prompts on a remote MCP server.",
+    parameters=MCP_PING_PARAMETERS,
+)
+async def mcp_list_prompts(args: dict[str, Any]) -> str:
+    """
+    List the prompts on a remote MCP server.
+    """
+    server_url = args.get("server_url")
+
+    if server_url is None:
+        return "Error: `server_url` is required"
+    if not isinstance(server_url, str):
+        return "Error: `server_url` must be a string"
+
+    try:
+        client = Client(server_url)
+        async with client:
+            result = await client.list_prompts()
+            return str(result)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+MCP_READ_RESOURCE_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "server_url": {
+            "type": "string",
+            "description": "The URL of the remote MCP server.",
+        },
+        "resource_uri": {
+            "type": "string",
+            "description": "The URI of the resource to read.",
+        },
+    },
+    "required": ["server_url", "resource_uri"],
+}
+
+
+@action(
+    name="mcp_read_resource",
+    description="Read a resource from a remote MCP server.",
+    parameters=MCP_READ_RESOURCE_PARAMETERS,
+)
+async def mcp_read_resource(args: dict[str, Any]) -> str:
+    """
+    Read a resource from a remote MCP server.
+    """
+    server_url = args.get("server_url")
+    resource_uri = args.get("resource_uri")
+
+    if server_url is None:
+        return "Error: `server_url` is required"
+    if resource_uri is None:
+        return "Error: `resource_uri` is required"
+
+    if not isinstance(server_url, str):
+        return "Error: `server_url` must be a string"
+    if not isinstance(resource_uri, str):
+        return "Error: `resource_uri` must be a string"
+
+    try:
+        client = Client(server_url)
+        async with client:
+            result = await client.read_resource(resource_uri)
+            return str(result)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+MCP_LIST_RESOURCES_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "server_url": {
+            "type": "string",
+            "description": "The URL of the remote MCP server.",
+        },
+    },
+    "required": ["server_url"],
+}
+
+
+@action(
+    name="mcp_list_resources",
+    description="List the resources on a remote MCP server.",
+    parameters=MCP_LIST_RESOURCES_PARAMETERS,
+)
+async def mcp_list_resources(args: dict[str, Any]) -> str:
+    """
+    List the resources on a remote MCP server.
+    """
+    server_url = args.get("server_url")
+
+    if server_url is None:
+        return "Error: `server_url` is required"
+    if not isinstance(server_url, str):
+        return "Error: `server_url` must be a string"
+
+    try:
+        client = Client(server_url)
+        async with client:
+            result = await client.list_resources()
+            return str(result)
+    except Exception as e:
+        return f"Error: {e}"

mail/stdlib/openai/__init__.py

@@ -0,0 +1,13 @@
+from .agents import (
+    OpenAIChatCompletionsAgentFunction,
+    OpenAIChatCompletionsSupervisorFunction,
+    OpenAIResponsesAgentFunction,
+    OpenAIResponsesSupervisorFunction,
+)
+
+__all__ = [
+    "OpenAIChatCompletionsAgentFunction",
+    "OpenAIChatCompletionsSupervisorFunction",
+    "OpenAIResponsesAgentFunction",
+    "OpenAIResponsesSupervisorFunction",
+]