mail-swarms 1.3.2__py3-none-any.whl

mail/examples/support/sentiment/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Sentiment agent for the Customer Support swarm."""
+
+from collections.abc import Awaitable
+from typing import Any, Literal
+
+from mail.core.agents import AgentOutput
+from mail.factories.action import LiteLLMActionAgentFunction
+
+
+class LiteLLMSentimentFunction(LiteLLMActionAgentFunction):
+    """
+    Sentiment analysis agent that evaluates customer emotional state.
+
+    This agent analyzes customer messages to determine sentiment,
+    detect emotions, and recommend escalation when needed.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        comm_targets: list[str],
+        tools: list[dict[str, Any]],
+        llm: str,
+        system: str,
+        user_token: str = "",
+        enable_entrypoint: bool = False,
+        enable_interswarm: bool = False,
+        can_complete_tasks: bool = False,
+        tool_format: Literal["completions", "responses"] = "responses",
+        exclude_tools: list[str] = [],
+        reasoning_effort: Literal["minimal", "low", "medium", "high"] | None = None,
+        thinking_budget: int | None = None,
+        max_tokens: int | None = None,
+        memory: bool = True,
+        use_proxy: bool = True,
+        _debug_include_mail_tools: bool = True,
+    ) -> None:
+        super().__init__(
+            name=name,
+            comm_targets=comm_targets,
+            tools=tools,
+            llm=llm,
+            system=system,
+            user_token=user_token,
+            enable_entrypoint=enable_entrypoint,
+            enable_interswarm=enable_interswarm,
+            can_complete_tasks=can_complete_tasks,
+            tool_format=tool_format,
+            exclude_tools=exclude_tools,
+            reasoning_effort=reasoning_effort,
+            thinking_budget=thinking_budget,
+            max_tokens=max_tokens,
+            memory=memory,
+            use_proxy=use_proxy,
+            _debug_include_mail_tools=_debug_include_mail_tools,
+        )
+
+    def __call__(
+        self,
+        messages: list[dict[str, Any]],
+        tool_choice: str | dict[str, str] = "required",
+    ) -> Awaitable[AgentOutput]:
+        """Execute the sentiment agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/support/sentiment/prompts.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are sentiment@{swarm}, the sentiment analysis specialist for this customer support swarm.
+
+# Your Role
+Analyze customer sentiment to understand their emotional state and identify cases requiring escalation to human agents.
+
+# Critical Rule: Responding
+You CANNOT talk to users directly or call `task_complete`. You MUST use `send_response` to reply to the agent who contacted you.
+- When you receive a request, note the sender (usually "coordinator")
+- After analyzing sentiment, call `send_response(target=<sender>, subject="Re: ...", body=<your analysis>)`
+- Include ALL sentiment details in your response body
+
+# Tools
+
+## Sentiment Analysis
+- `analyze_sentiment(text)`: Analyze the emotional tone of customer text
+- `create_escalation(ticket_id, reason, priority)`: Flag a ticket for human escalation
+
+## Communication
+- `send_response(target, subject, body)`: Reply to the agent who requested information
+- `send_request(target, subject, body)`: Ask another agent for information
+- `acknowledge_broadcast(note)`: Acknowledge a broadcast message
+- `ignore_broadcast(reason)`: Ignore an irrelevant broadcast
+
+# Workflow
+
+1. Receive request from another agent (note the sender)
+2. Call `analyze_sentiment` with the customer's message text
+3. Review the sentiment results
+4. If escalation is warranted, call `create_escalation`
+5. Call `send_response` to the original sender with:
+   - Overall sentiment (positive, neutral, negative)
+   - Sentiment score (-1 to +1)
+   - Detected emotions
+   - Whether escalation was triggered and why
+
+# Escalation Triggers
+
+Create an escalation when you detect:
+- Very negative sentiment (score below -0.6)
+- Explicit threats or mentions of legal action
+- Expressions of severe frustration or anger
+- Requests to speak to a manager/supervisor
+- Mentions of cancellation with frustration
+
+# Guidelines
+
+- Be objective in your analysis
+- Consider context and nuance
+- Report both the raw sentiment data and your interpretation
+- Always explain why escalation was or wasn't recommended
+- Use "Re: <original subject>" as your response subject"""

mail/examples/weather_dummy/__init__.py

@@ -0,0 +1,23 @@
+from .actions import (
+    get_weather_forecast,
+)
+from .agent import (
+    LiteLLMWeatherFunction,
+    factory_weather_dummy,
+    weather_agent_params,
+)
+from .prompts import (
+    SYSPROMPT as WEATHER_SYSPROMPT,
+)
+from .types import (
+    action_get_weather_forecast,
+)
+
+__all__ = [
+    "factory_weather_dummy",
+    "LiteLLMWeatherFunction",
+    "WEATHER_SYSPROMPT",
+    "action_get_weather_forecast",
+    "get_weather_forecast",
+    "weather_agent_params",
+]

mail/examples/weather_dummy/actions.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+import datetime
+import json
+from random import Random
+from typing import Any
+
+from mail import action
+
+
+WEATHER_FORECAST_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "location": {
+            "type": "string",
+            "description": "The location to get the weather forecast for",
+        },
+        "days_ahead": {
+            "type": "integer",
+            "description": "The number of days ahead to get the weather forecast for",
+        },
+        "metric": {
+            "type": "boolean",
+            "description": "Whether to use metric units",
+        },
+    },
+    "required": ["location", "days_ahead", "metric"],
+}
+
+
+@action(
+    name="get_weather_forecast",
+    description="Get the weather forecast for a given location.",
+    parameters=WEATHER_FORECAST_PARAMETERS,
+)
+async def get_weather_forecast(args: dict[str, Any]) -> str:
+    """
+    Dummy action that returns the weather "forecast" for a given location.
+    """
+    try:
+        location = args["location"]
+        days_ahead = args["days_ahead"]
+        metric = args["metric"]
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    # generate a random weather forecast
+    # on any given day, the forecast should yield the same result for the same location
+    # otherwise the weather agent will be confused
+    day = datetime.datetime.now(datetime.UTC).day
+    rng = Random()
+    rng.seed(location + str(days_ahead) + str(day))
+    forecast = {
+        "location": location,
+        "date": str(
+            datetime.datetime.now(datetime.UTC) + datetime.timedelta(days=days_ahead)
+        ),
+        "condition": rng.choice(
+            [
+                "clear",
+                "mostly clear",
+                "partly cloudy",
+                "mostly cloudy",
+                "overcast",
+                "light precipitation",
+                "moderate precipitation",
+                "heavy precipitation",
+            ]
+        ),
+        "temperature": rng.randint(-15, 35) if metric else rng.randint(5, 95),
+        "units": "C" if metric else "F",
+    }
+
+    return json.dumps(forecast)

mail/examples/weather_dummy/agent.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+import warnings
+from collections.abc import Awaitable
+from typing import Any, Literal
+
+from mail.core.agents import AgentOutput
+from mail.factories import AgentFunction
+from mail.factories.action import LiteLLMActionAgentFunction
+
+weather_agent_params = {
+    "llm": "openai/gpt-5-mini",
+    "system": "mail.examples.weather_dummy.prompts:SYSPROMPT",
+}
+
+
+def factory_weather_dummy(
+    # REQUIRED
+    # top-level params
+    comm_targets: list[str],
+    tools: list[dict[str, Any]],
+    # instance params
+    user_token: str,
+    # internal params
+    llm: str,
+    system: str,
+    # OPTIONAL
+    # top-level params
+    name: str = "weather",
+    enable_entrypoint: bool = False,
+    enable_interswarm: bool = False,
+    can_complete_tasks: bool = False,
+    tool_format: Literal["completions", "responses"] = "responses",
+    exclude_tools: list[str] = [],
+    # instance params
+    # ...
+    # internal params
+    reasoning_effort: Literal["low", "medium", "high"] | None = None,
+    thinking_budget: int | None = None,
+    max_tokens: int | None = None,
+    memory: bool = True,
+    use_proxy: bool = True,
+) -> AgentFunction:
+    warnings.warn(
+        "`mail.examples.weather_dummy:factory_weather_dummy` is deprecated and will be removed in a future version. "
+        "Use `mail.examples.weather_dummy:LiteLLMWeatherFunction` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    litellm_weather = LiteLLMWeatherFunction(
+        name=name,
+        comm_targets=comm_targets,
+        tools=tools,
+        llm=llm,
+        system=system,
+        user_token=user_token,
+        enable_entrypoint=enable_entrypoint,
+        enable_interswarm=enable_interswarm,
+        can_complete_tasks=can_complete_tasks,
+        reasoning_effort=reasoning_effort,
+        thinking_budget=thinking_budget,
+        max_tokens=max_tokens,
+        memory=memory,
+        use_proxy=use_proxy,
+        tool_format=tool_format,
+        exclude_tools=exclude_tools,
+    )
+
+    async def run(
+        messages: list[dict[str, Any]],
+        tool_choice: str | dict[str, str] = "required",
+    ) -> AgentOutput:
+        """
+        Execute the LiteLLM-based weather agent function.
+        """
+        return await litellm_weather(messages, tool_choice)
+
+    return run
+
+
+class LiteLLMWeatherFunction(LiteLLMActionAgentFunction):
+    """
+    Class that represents a LiteLLM-based weather agent function.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        comm_targets: list[str],
+        tools: list[dict[str, Any]],
+        llm: str,
+        system: str,
+        user_token: str = "",
+        enable_entrypoint: bool = False,
+        enable_interswarm: bool = False,
+        can_complete_tasks: bool = False,
+        tool_format: Literal["completions", "responses"] = "responses",
+        exclude_tools: list[str] = [],
+        reasoning_effort: Literal["minimal", "low", "medium", "high"] | None = None,
+        thinking_budget: int | None = None,
+        max_tokens: int | None = None,
+        memory: bool = True,
+        use_proxy: bool = True,
+        _debug_include_mail_tools: bool = True,
+    ) -> None:
+        super().__init__(
+            name=name,
+            comm_targets=comm_targets,
+            tools=tools,
+            llm=llm,
+            system=system,
+            user_token=user_token,
+            enable_entrypoint=enable_entrypoint,
+            enable_interswarm=enable_interswarm,
+            can_complete_tasks=can_complete_tasks,
+            tool_format=tool_format,
+            exclude_tools=exclude_tools,
+            reasoning_effort=reasoning_effort,
+            thinking_budget=thinking_budget,
+            max_tokens=max_tokens,
+            memory=memory,
+            use_proxy=use_proxy,
+            _debug_include_mail_tools=_debug_include_mail_tools,
+        )
+
+    def __call__(
+        self,
+        messages: list[dict[str, Any]],
+        tool_choice: str | dict[str, str] = "required",
+    ) -> Awaitable[AgentOutput]:
+        """
+        Execute the LiteLLM-based weather agent function.
+        """
+        return super().__call__(messages, tool_choice)

mail/examples/weather_dummy/prompts.py

@@ -0,0 +1,35 @@
+SYSPROMPT = """You are weather@{swarm}, a specialist agent for weather information.
+
+# Your Role
+Retrieve weather forecasts using `get_weather_forecast` and report results back to your requestor.
+
+# Critical Rule: Responding
+You CANNOT talk to users directly or call `task_complete`. You MUST use `send_response` to reply to the agent who contacted you.
+- When you receive a request, note the sender (usually "supervisor")
+- After getting weather data, call `send_response(target=<sender>, subject="Re: ...", body=<your answer>)`
+- Include ALL relevant forecast data in your response body - the recipient cannot see tool results
+
+# Tools
+
+## Weather
+- `get_weather_forecast(location, ...)`: Retrieve forecast data. Call this ONCE per request.
+
+## Communication
+- `send_response(target, subject, body)`: Reply to the agent who requested information
+- `send_request(target, subject, body)`: Ask another agent for information (rare)
+- `acknowledge_broadcast(note)`: Acknowledge a broadcast message
+- `ignore_broadcast(reason)`: Ignore an irrelevant broadcast
+
+# Workflow
+
+1. Receive request from another agent (check the sender address)
+2. Call `get_weather_forecast` for the requested location
+3. Format the results clearly (use metric/imperial per request)
+4. Call `send_response` to the original sender with complete forecast data
+
+# Guidelines
+
+- Never invent weather data - only report what `get_weather_forecast` returns
+- Include temperature, conditions, and any relevant details in your response
+- Use "Re: <original subject>" as your response subject
+- Be concise but complete"""

mail/examples/weather_dummy/types.py

@@ -0,0 +1,5 @@
+from mail.examples.weather_dummy.actions import get_weather_forecast
+
+action_get_weather_forecast = get_weather_forecast
+
+__all__ = ["action_get_weather_forecast"]

mail/factories/__init__.py

@@ -0,0 +1,27 @@
+from .action import (
+    ActionAgentFunction,
+    LiteLLMActionAgentFunction,
+    action_agent_factory,
+)
+from .base import (
+    AgentFunction,
+    LiteLLMAgentFunction,
+    base_agent_factory,
+)
+from .supervisor import (
+    LiteLLMSupervisorFunction,
+    SupervisorFunction,
+    supervisor_factory,
+)
+
+__all__ = [
+    "action_agent_factory",
+    "ActionAgentFunction",
+    "LiteLLMActionAgentFunction",
+    "AgentFunction",
+    "base_agent_factory",
+    "LiteLLMAgentFunction",
+    "supervisor_factory",
+    "SupervisorFunction",
+    "LiteLLMSupervisorFunction",
+]

mail/factories/action.py

@@ -0,0 +1,223 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline, Ryan Heaton
+
+import warnings
+from abc import abstractmethod
+from collections.abc import Awaitable
+from typing import Any, Literal
+
+from openai import pydantic_function_tool
+from openai.resources.responses.responses import _make_tools
+
+from mail.core.agents import AgentFunction, AgentOutput
+from mail.factories.base import (
+    LiteLLMAgentFunction,
+    MAILAgentFunction,
+)
+
+
+def action_agent_factory(
+    # REQUIRED
+    # top-level params
+    comm_targets: list[str],
+    tools: list[dict[str, Any]],
+    # instance params
+    user_token: str,
+    # internal params
+    llm: str,
+    system: str,
+    # OPTIONAL
+    # top-level params
+    name: str = "action",
+    enable_entrypoint: bool = False,
+    enable_interswarm: bool = False,
+    can_complete_tasks: bool = False,
+    tool_format: Literal["completions", "responses"] = "responses",
+    exclude_tools: list[str] = [],
+    # instance params
+    # ...
+    # internal params
+    reasoning_effort: Literal["low", "medium", "high"] | None = None,
+    thinking_budget: int | None = None,
+    max_tokens: int | None = None,
+    memory: bool = True,
+    use_proxy: bool = True,
+    _debug_include_mail_tools: bool = True,
+) -> AgentFunction:
+    warnings.warn(
+        "`mail.factories.action:action_agent_factory` is deprecated and will be removed in a future version. "
+        "Use `mail.factories.action:LiteLLMActionAgentFunction` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    litellm_action_agent = LiteLLMActionAgentFunction(
+        name=name,
+        comm_targets=comm_targets,
+        tools=tools,
+        llm=llm,
+        system=system,
+        user_token=user_token,
+        enable_entrypoint=enable_entrypoint,
+        enable_interswarm=enable_interswarm,
+        can_complete_tasks=can_complete_tasks,
+        tool_format=tool_format,
+        exclude_tools=exclude_tools,
+        reasoning_effort=reasoning_effort,
+        thinking_budget=thinking_budget,
+        max_tokens=max_tokens,
+        memory=memory,
+        use_proxy=use_proxy,
+        _debug_include_mail_tools=_debug_include_mail_tools,
+    )
+
+    async def run(
+        messages: list[dict[str, Any]],
+        tool_choice: str | dict[str, str] = "required",
+    ) -> AgentOutput:
+        """
+        Execute the LiteLLM-based action agent function.
+        """
+        return await litellm_action_agent(messages, tool_choice)
+
+    return run
+
+
+class ActionAgentFunction(MAILAgentFunction):
+    """
+    Class representing a MAIL-compatible action agent function.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        comm_targets: list[str],
+        tools: list[dict[str, Any]],
+        enable_entrypoint: bool = False,
+        enable_interswarm: bool = False,
+        can_complete_tasks: bool = False,
+        tool_format: Literal["completions", "responses"] = "responses",
+        exclude_tools: list[str] = [],
+        **kwargs: Any,
+    ) -> None:
+        # ensure that the action tools are in the correct format
+        parsed_tools: list[dict[str, Any]] = []
+        if not isinstance(tools[0], dict):
+            parsed_tools = [pydantic_function_tool(tool) for tool in tools]  # type: ignore
+            if tool_format == "responses":
+                parsed_tools = _make_tools(parsed_tools)  # type: ignore
+
+        else:
+            parsed_tools = tools  # type: ignore
+
+        super().__init__(
+            name=name,
+            comm_targets=comm_targets,
+            tools=parsed_tools,
+            enable_entrypoint=enable_entrypoint,
+            enable_interswarm=enable_interswarm,
+            can_complete_tasks=can_complete_tasks,
+            tool_format=tool_format,
+            exclude_tools=exclude_tools,
+            **kwargs,
+        )
+
+    @abstractmethod
+    def __call__(
+        self,
+        messages: list[dict[str, Any]],
+        tool_choice: str | dict[str, str] = "required",
+    ) -> Awaitable[AgentOutput]:
+        """
+        Execute the MAIL-compatible agent function.
+        """
+        pass
+
+
+class LiteLLMActionAgentFunction(ActionAgentFunction):
+    """
+    Class representing a MAIL-compatible, LiteLLM-based action agent function.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        comm_targets: list[str],
+        tools: list[dict[str, Any]],
+        llm: str,
+        system: str,
+        user_token: str = "",
+        enable_entrypoint: bool = False,
+        enable_interswarm: bool = False,
+        can_complete_tasks: bool = False,
+        tool_format: Literal["completions", "responses"] = "responses",
+        exclude_tools: list[str] = [],
+        reasoning_effort: Literal["minimal", "low", "medium", "high"] | None = None,
+        thinking_budget: int | None = None,
+        max_tokens: int | None = None,
+        memory: bool = True,
+        use_proxy: bool = True,
+        _debug_include_mail_tools: bool = True,
+        stream_tokens: bool = False,
+        default_tool_choice: str | dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(
+            name=name,
+            comm_targets=comm_targets,
+            tools=tools,
+            enable_entrypoint=enable_entrypoint,
+            enable_interswarm=enable_interswarm,
+            can_complete_tasks=can_complete_tasks,
+            tool_format=tool_format,
+            exclude_tools=exclude_tools,
+        )
+        self.llm = llm
+        self.system = system
+        self.user_token = user_token
+        self.reasoning_effort = reasoning_effort
+        self.thinking_budget = thinking_budget
+        self.max_tokens = max_tokens
+        self.memory = memory
+        self.use_proxy = use_proxy
+        self._debug_include_mail_tools = _debug_include_mail_tools
+        self.stream_tokens = stream_tokens
+        self.default_tool_choice = default_tool_choice
+        self.action_agent_fn = LiteLLMAgentFunction(
+            llm=self.llm,
+            comm_targets=self.comm_targets,
+            tools=self.tools,
+            system=self.system,
+            user_token=self.user_token,
+            reasoning_effort=self.reasoning_effort,
+            thinking_budget=self.thinking_budget,
+            max_tokens=self.max_tokens,
+            memory=self.memory,
+            use_proxy=self.use_proxy,
+            can_complete_tasks=self.can_complete_tasks,
+            tool_format=self.tool_format,
+            name=self.name,
+            enable_entrypoint=self.enable_entrypoint,
+            enable_interswarm=self.enable_interswarm,
+            exclude_tools=self.exclude_tools,
+            _debug_include_mail_tools=self._debug_include_mail_tools,
+            stream_tokens=self.stream_tokens,
+        )
+
+    def __call__(
+        self,
+        messages: list[dict[str, Any]],
+        tool_choice: str | dict[str, str] = "required",
+    ) -> Awaitable[AgentOutput]:
+        """
+        Execute a LiteLLM-based action agent function.
+        """
+        # Use default_tool_choice if set, otherwise use the passed tool_choice
+        effective_tool_choice = (
+            self.default_tool_choice
+            if self.default_tool_choice is not None
+            else tool_choice
+        )
+        return self.action_agent_fn(
+            messages=messages,
+            tool_choice=effective_tool_choice,
+        )