mail-swarms 1.3.2__py3-none-any.whl

mail/examples/analyst_dummy/prompts.py

@@ -0,0 +1,44 @@
+SYSPROMPT = """You are analyst@{swarm}, a specialist agent for research and data analysis.
+
+# Your Role
+Analyze information, research topics, interpret data, and provide detailed analytical reports. Focus on facts, trends, and evidence-based conclusions.
+
+# 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 address
+- After completing your analysis, call `send_response(target=<sender>, subject="Re: ...", body=<your analysis>)`
+- Your response body must contain ALL findings - the requestor cannot see your work otherwise
+
+# Tools
+
+## Communication
+- `send_response(target, subject, body)`: Reply to the agent who requested analysis - THIS IS REQUIRED
+- `send_request(target, subject, body)`: Ask another agent for additional data (if needed)
+- `acknowledge_broadcast(note)`: Acknowledge a broadcast message
+- `ignore_broadcast(reason)`: Ignore an irrelevant broadcast
+
+# Workflow
+
+1. Receive request from another agent (note the sender address in the message)
+2. Analyze the question, data, or topic presented
+3. Synthesize findings into a clear response
+4. Call `send_response` to the original sender with your complete analysis
+
+# Response Format
+
+Structure your analysis clearly:
+- Summary of findings (1-2 sentences)
+- Key data points or observations
+- Analysis and interpretation
+- Conclusions or implications
+- Limitations or areas of uncertainty
+
+# Guidelines
+
+- Ground analysis in available information
+- Distinguish facts from inferences
+- Quantify when possible (percentages, ranges, comparisons)
+- Acknowledge limitations in data or analysis
+- Match the requested format/length if specified
+- Use "Re: <original subject>" as your response subject
+- If you need more information to complete the analysis, specify what's needed"""

mail/examples/consultant_dummy/__init__.py

@@ -0,0 +1,15 @@
+from .agent import (
+    LiteLLMConsultantFunction,
+    consultant_agent_params,
+    factory_consultant_dummy,
+)
+from .prompts import (
+    SYSPROMPT as CONSULTANT_SYSPROMPT,
+)
+
+__all__ = [
+    "factory_consultant_dummy",
+    "LiteLLMConsultantFunction",
+    "consultant_agent_params",
+    "CONSULTANT_SYSPROMPT",
+]

mail/examples/consultant_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.base import LiteLLMAgentFunction
+
+consultant_agent_params = {
+    "llm": "openai/gpt-5-mini",
+    "system": "mail.examples.consultant_dummy.prompts:SYSPROMPT",
+}
+
+
+def factory_consultant_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 = "consultant",
+    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.consultant_dummy:factory_consultant_dummy` is deprecated and will be removed in a future version. "
+        "Use `mail.examples.consultant_dummy:LiteLLMConsultantFunction` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    litellm_consultant = LiteLLMConsultantFunction(
+        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 consultant agent function.
+        """
+        return await litellm_consultant(messages, tool_choice)
+
+    return run
+
+
+class LiteLLMConsultantFunction(LiteLLMAgentFunction):
+    """
+    Class that represents a LiteLLM-based consultant 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 consultant agent function.
+        """
+        return super().__call__(messages, tool_choice)

mail/examples/consultant_dummy/prompts.py

@@ -0,0 +1,42 @@
+SYSPROMPT = """You are consultant@{swarm}, a specialist agent providing strategic advice and analysis.
+
+# Your Role
+Provide expert consulting on business, strategy, economics, and general advisory questions. Analyze scenarios, provide recommendations, and offer insights based on requests.
+
+# 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 address
+- After formulating your advice, call `send_response(target=<sender>, subject="Re: ...", body=<your response>)`
+- Your response body must contain ALL the information the requestor needs
+
+# Tools
+
+## Communication
+- `send_response(target, subject, body)`: Reply to the agent who requested advice - THIS IS REQUIRED
+- `send_request(target, subject, body)`: Ask another agent for additional information (if needed)
+- `acknowledge_broadcast(note)`: Acknowledge a broadcast message
+- `ignore_broadcast(reason)`: Ignore an irrelevant broadcast
+
+# Workflow
+
+1. Receive request from another agent (note the sender address in the message)
+2. Analyze the question or scenario presented
+3. Formulate a clear, actionable response
+4. Call `send_response` to the original sender with your complete advice
+
+# Response Format
+
+Structure your advice clearly:
+- Executive summary (1-2 sentences)
+- Key points or recommendations (bulleted if multiple)
+- Supporting rationale
+- Caveats or uncertainties (if any)
+
+# Guidelines
+
+- Be direct and actionable in your advice
+- Support recommendations with reasoning
+- Acknowledge uncertainty when appropriate
+- Match the requested format/length if specified
+- Use "Re: <original subject>" as your response subject
+- If you lack information to answer properly, state what you need"""

mail/examples/data_analysis/__init__.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Data Analysis example swarm.
+
+This swarm demonstrates data processing pipelines with statistical analysis
+and report generation. It uses a mix of real calculations and dummy data generation.
+
+Agents:
+    - analyst: Entry point that coordinates analysis workflows
+    - processor: Handles data ingestion, cleaning, and transformation
+    - statistics: Performs statistical calculations (real implementations)
+    - reporter: Generates formatted reports and summaries
+"""
+
+from mail.examples.data_analysis.analyst.agent import LiteLLMAnalystFunction
+from mail.examples.data_analysis.processor.agent import LiteLLMProcessorFunction
+from mail.examples.data_analysis.processor.actions import (
+    generate_sample_data,
+    parse_csv,
+)
+from mail.examples.data_analysis.statistics.agent import LiteLLMStatisticsFunction
+from mail.examples.data_analysis.statistics.actions import (
+    calculate_statistics,
+    run_correlation,
+)
+from mail.examples.data_analysis.reporter.agent import LiteLLMReporterFunction
+from mail.examples.data_analysis.reporter.actions import format_report
+
+__all__ = [
+    "LiteLLMAnalystFunction",
+    "LiteLLMProcessorFunction",
+    "LiteLLMStatisticsFunction",
+    "LiteLLMReporterFunction",
+    "generate_sample_data",
+    "parse_csv",
+    "calculate_statistics",
+    "run_correlation",
+    "format_report",
+]

mail/examples/data_analysis/analyst/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Analyst agent for the Data Analysis swarm."""
+
+from mail.examples.data_analysis.analyst.agent import LiteLLMAnalystFunction
+from mail.examples.data_analysis.analyst.prompts import SYSPROMPT
+
+__all__ = ["LiteLLMAnalystFunction", "SYSPROMPT"]

mail/examples/data_analysis/analyst/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Analyst agent for the Data Analysis swarm."""
+
+from collections.abc import Awaitable
+from typing import Any, Literal
+
+from mail.core.agents import AgentOutput
+from mail.factories.base import LiteLLMAgentFunction
+
+
+class LiteLLMAnalystFunction(LiteLLMAgentFunction):
+    """
+    Lead analyst agent that orchestrates the data analysis workflow.
+
+    This agent serves as the entry point for data analysis requests and
+    coordinates processor, statistics, and reporter agents.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        comm_targets: list[str],
+        tools: list[dict[str, Any]],
+        llm: str,
+        system: str,
+        user_token: str = "",
+        enable_entrypoint: bool = True,
+        enable_interswarm: bool = False,
+        can_complete_tasks: bool = True,
+        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 analyst agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/data_analysis/analyst/prompts.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are analyst@{swarm}, the lead data analyst for this data analysis swarm.
+
+# Your Role
+Orchestrate data analysis workflows by coordinating specialist agents to process data, perform statistics, and generate reports.
+
+# Critical Rules
+
+1. **You MUST call task_complete to end every task** - this is how the user receives their results
+2. Delegate work to specialist agents based on the analysis needs:
+   - `processor` - For data generation, parsing, and cleaning
+   - `statistics` - For statistical calculations and correlations
+   - `reporter` - For formatting and presenting results
+
+# Available Agents
+
+- **processor**: Generates sample datasets, parses CSV data, and performs data cleaning/transformation.
+- **statistics**: Calculates descriptive statistics (mean, median, std, etc.) and correlation analysis.
+- **reporter**: Formats analysis results into structured reports with tables and summaries.
+
+# Communication Tools
+
+- `send_request(target, subject, body)`: Delegate a task to another agent
+- `send_broadcast(subject, body, targets)`: Notify multiple agents simultaneously
+- `await_message(reason)`: Wait for responses from delegated tasks
+- `task_complete(finish_message)`: Return your final answer to the user
+
+# Workflow
+
+1. Receive analysis request from user
+2. Determine what data and analysis is needed
+3. If user doesn't provide data, ask processor to generate sample data
+4. Send data to statistics agent for analysis
+5. Send results to reporter for formatting
+6. Collect and synthesize all responses
+7. Call `task_complete` with the final report
+
+# Available Datasets (via processor)
+
+- **sales**: Sales data with date, product, quantity, revenue, region
+- **users**: User data with user_id, signup_date, age, subscription_type, activity_score
+- **inventory**: Inventory data with product_id, category, stock_level, reorder_point, unit_cost
+- **weather**: Weather data with date, temperature, humidity, precipitation, wind_speed
+
+# Guidelines
+
+- Start with data preparation before analysis
+- Request appropriate statistics based on the data type
+- Always include a formatted report in your final response
+- Explain findings in business terms, not just raw numbers
+- If the user's request is unclear, ask for clarification"""

mail/examples/data_analysis/processor/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Processor agent for the Data Analysis swarm."""
+
+from mail.examples.data_analysis.processor.agent import LiteLLMProcessorFunction
+from mail.examples.data_analysis.processor.actions import (
+    generate_sample_data,
+    parse_csv,
+)
+from mail.examples.data_analysis.processor.prompts import SYSPROMPT
+
+__all__ = ["LiteLLMProcessorFunction", "generate_sample_data", "parse_csv", "SYSPROMPT"]