mail-swarms 1.3.2__py3-none-any.whl

mail/examples/math_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
+
+math_agent_params = {
+    "llm": "openai/gpt-5-mini",
+    "system": "mail.examples.math_dummy.prompts:SYSPROMPT",
+}
+
+
+def factory_math_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 = "math",
+    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.math_dummy:factory_math_dummy` is deprecated and will be removed in a future version. "
+        "Use `mail.examples.math_dummy:LiteLLMMathFunction` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    litellm_math = LiteLLMMathFunction(
+        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 math agent function.
+        """
+        return await litellm_math(messages, tool_choice)
+
+    return run
+
+
+class LiteLLMMathFunction(LiteLLMAgentFunction):
+    """
+    Class that represents a LiteLLM-based math 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 math agent function.
+        """
+        return super().__call__(messages, tool_choice)

mail/examples/math_dummy/prompts.py

@@ -0,0 +1,46 @@
+SYSPROMPT = """You are math@{swarm}, a specialist agent for mathematical calculations.
+
+# Your Role
+Solve mathematical problems using `calculate_expression` 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 solving the problem, call `send_response(target=<sender>, subject="Re: ...", body=<your answer>)`
+- Include your complete solution in the response body - the recipient cannot see tool results
+
+# Tools
+
+## Math
+- `calculate_expression(expression, precision?)`: Evaluate arithmetic expressions
+  - Supports: +, -, *, /, //, %, **, parentheses
+  - Constants: pi, e, tau
+  - Returns: result (exact), formatted_result (rounded), is_integer
+
+## Communication
+- `send_response(target, subject, body)`: Reply to the agent who requested the calculation
+- `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. Parse the mathematical problem from the request
+3. Use `calculate_expression` for arithmetic, or solve algebraically
+4. Call `send_response` to the original sender with the solution
+
+# Response Format
+
+Include in your response body:
+- Brief explanation of approach (if non-trivial)
+- Key calculation steps
+- Final answer clearly marked (e.g., "Result: 42")
+- Units if applicable
+
+# Guidelines
+
+- Use `calculate_expression` for precise arithmetic
+- State assumptions if the problem is ambiguous
+- If a problem is outside your scope, explain the limitation
+- Use "Re: <original subject>" as your response subject"""

mail/examples/math_dummy/types.py

@@ -0,0 +1,5 @@
+from mail.examples.math_dummy.actions import calculate_expression
+
+action_calculate_expression = calculate_expression
+
+__all__ = ["action_calculate_expression"]

mail/examples/research/__init__.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Research Assistant example swarm.
+
+This swarm demonstrates research workflows with information gathering,
+fact verification, and summarization. It includes real HTTP integrations
+where available with dummy fallbacks.
+
+Agents:
+    - researcher: Entry point that coordinates research tasks
+    - searcher: Searches for information on topics
+    - verifier: Cross-references and verifies claims
+    - summarizer: Synthesizes and summarizes findings
+"""
+
+from mail.examples.research.researcher.agent import LiteLLMResearcherFunction
+from mail.examples.research.searcher.agent import LiteLLMSearcherFunction
+from mail.examples.research.searcher.actions import search_topic, extract_facts
+from mail.examples.research.verifier.agent import LiteLLMVerifierFunction
+from mail.examples.research.verifier.actions import verify_claim, rate_confidence
+from mail.examples.research.summarizer.agent import LiteLLMSummarizerFunction
+from mail.examples.research.summarizer.actions import (
+    summarize_text,
+    create_bibliography,
+)
+
+__all__ = [
+    "LiteLLMResearcherFunction",
+    "LiteLLMSearcherFunction",
+    "LiteLLMVerifierFunction",
+    "LiteLLMSummarizerFunction",
+    "search_topic",
+    "extract_facts",
+    "verify_claim",
+    "rate_confidence",
+    "summarize_text",
+    "create_bibliography",
+]

mail/examples/research/researcher/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Researcher agent for the Research Assistant swarm."""
+
+from mail.examples.research.researcher.agent import LiteLLMResearcherFunction
+from mail.examples.research.researcher.prompts import SYSPROMPT
+
+__all__ = ["LiteLLMResearcherFunction", "SYSPROMPT"]

mail/examples/research/researcher/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Researcher agent for the Research Assistant swarm."""
+
+from collections.abc import Awaitable
+from typing import Any, Literal
+
+from mail.core.agents import AgentOutput
+from mail.factories.base import LiteLLMAgentFunction
+
+
+class LiteLLMResearcherFunction(LiteLLMAgentFunction):
+    """
+    Lead researcher agent that orchestrates research workflows.
+
+    This agent serves as the entry point for research requests and
+    coordinates searcher, verifier, and summarizer 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 researcher agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/research/researcher/prompts.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are researcher@{swarm}, the lead researcher for this research assistant swarm.
+
+# Your Role
+Orchestrate research workflows by coordinating specialist agents to gather information, verify facts, and synthesize findings into clear summaries.
+
+# Critical Rules
+
+1. **You MUST call task_complete to end every task** - this is how the user receives their research results
+2. Delegate work to specialist agents based on research needs:
+   - `searcher` - For finding information and extracting facts
+   - `verifier` - For cross-referencing and verifying claims
+   - `summarizer` - For synthesizing and formatting results
+
+# Available Agents
+
+- **searcher**: Searches for information on topics using various sources (Wikipedia, academic, news, general). Can also extract key facts from text.
+- **verifier**: Cross-references claims against sources and rates confidence levels based on evidence quality.
+- **summarizer**: Synthesizes information into clear summaries and creates formatted bibliographies.
+
+# 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 research request from user
+2. Break down the research question into searchable topics
+3. Send search requests to searcher agent for each topic
+4. Have verifier check important claims
+5. Send all findings to summarizer for synthesis
+6. Review the summary and ensure it answers the original question
+7. Call `task_complete` with the final research summary
+
+# Research Quality Guidelines
+
+- Always verify important factual claims
+- Note when information is uncertain or conflicting
+- Include source references in final output
+- Be transparent about limitations of the research
+- Present balanced perspectives on controversial topics
+
+# Guidelines
+
+- Start with broad searches, then narrow down
+- Verify statistics and specific claims
+- Include confidence levels in final output
+- Always provide source attribution
+- If a topic is too broad, ask for clarification"""

mail/examples/research/searcher/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Searcher agent for the Research Assistant swarm."""
+
+from mail.examples.research.searcher.agent import LiteLLMSearcherFunction
+from mail.examples.research.searcher.actions import search_topic, extract_facts
+from mail.examples.research.searcher.prompts import SYSPROMPT
+
+__all__ = ["LiteLLMSearcherFunction", "search_topic", "extract_facts", "SYSPROMPT"]