mail-swarms 1.3.2__py3-none-any.whl

mail/examples/research/verifier/actions.py

@@ -0,0 +1,337 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Verification actions for the Research Assistant swarm."""
+
+import hashlib
+import json
+from random import Random
+from typing import Any
+
+from mail import action
+
+# Source reliability ratings
+SOURCE_RELIABILITY = {
+    "wikipedia": 0.8,
+    "academic": 0.9,
+    "news": 0.6,
+    "general": 0.5,
+    "unknown": 0.3,
+}
+
+# Keywords that indicate verifiable facts
+VERIFIABLE_INDICATORS = [
+    "percent",
+    "%",
+    "million",
+    "billion",
+    "year",
+    "date",
+    "according to",
+    "research",
+    "study",
+    "report",
+    "data",
+    "survey",
+    "analysis",
+    "measured",
+    "recorded",
+    "documented",
+]
+
+# Keywords that indicate subjective claims
+SUBJECTIVE_INDICATORS = [
+    "best",
+    "worst",
+    "most",
+    "should",
+    "could",
+    "might",
+    "believe",
+    "think",
+    "opinion",
+    "feel",
+    "seems",
+    "appears",
+    "probably",
+    "possibly",
+    "arguably",
+    "supposedly",
+]
+
+
+def _analyze_claim_verifiability(claim: str) -> dict[str, Any]:
+    """Analyze how verifiable a claim is based on its content."""
+    claim_lower = claim.lower()
+
+    verifiable_count = sum(1 for ind in VERIFIABLE_INDICATORS if ind in claim_lower)
+    subjective_count = sum(1 for ind in SUBJECTIVE_INDICATORS if ind in claim_lower)
+
+    if subjective_count > verifiable_count:
+        claim_type = "opinion"
+        verifiability = 0.3
+    elif verifiable_count > 0:
+        claim_type = "factual"
+        verifiability = min(0.9, 0.5 + verifiable_count * 0.1)
+    else:
+        claim_type = "statement"
+        verifiability = 0.5
+
+    return {
+        "claim_type": claim_type,
+        "verifiability_score": verifiability,
+        "verifiable_indicators": verifiable_count,
+        "subjective_indicators": subjective_count,
+    }
+
+
+def _check_source_support(
+    claim: str, sources: list[str], rng: Random
+) -> dict[str, Any]:
+    """Check how well sources support a claim."""
+    if not sources:
+        return {
+            "support_level": "unknown",
+            "supporting_sources": 0,
+            "contradicting_sources": 0,
+            "neutral_sources": 0,
+        }
+
+    supporting = 0
+    contradicting = 0
+    neutral = 0
+
+    for source in sources:
+        # Simulate source checking based on deterministic randomness
+        source_seed = hashlib.md5((claim + source).encode()).hexdigest()
+        source_rng = Random(source_seed)
+
+        support_roll = source_rng.random()
+        if support_roll > 0.7:
+            supporting += 1
+        elif support_roll < 0.2:
+            contradicting += 1
+        else:
+            neutral += 1
+
+    total = len(sources)
+    support_ratio = supporting / total if total > 0 else 0
+
+    if support_ratio >= 0.6:
+        support_level = "supported"
+    elif contradicting > supporting:
+        support_level = "disputed"
+    else:
+        support_level = "inconclusive"
+
+    return {
+        "support_level": support_level,
+        "supporting_sources": supporting,
+        "contradicting_sources": contradicting,
+        "neutral_sources": neutral,
+        "support_ratio": round(support_ratio, 2),
+    }
+
+
+VERIFY_CLAIM_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "claim": {
+            "type": "string",
+            "description": "The claim or statement to verify",
+        },
+        "sources": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "List of source URLs or references to check against",
+        },
+    },
+    "required": ["claim"],
+}
+
+
+@action(
+    name="verify_claim",
+    description="Verify a claim by checking it against provided sources.",
+    parameters=VERIFY_CLAIM_PARAMETERS,
+)
+async def verify_claim(args: dict[str, Any]) -> str:
+    """Verify a claim against sources."""
+    try:
+        claim = args["claim"]
+        sources = args.get("sources", [])
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not claim.strip():
+        return json.dumps({"error": "Claim cannot be empty"})
+
+    # Analyze the claim
+    claim_analysis = _analyze_claim_verifiability(claim)
+
+    # Generate deterministic results
+    seed = hashlib.md5(claim.encode()).hexdigest()
+    rng = Random(seed)
+
+    # Check source support
+    source_check = _check_source_support(claim, sources, rng)
+
+    # Determine verification status
+    if claim_analysis["claim_type"] == "opinion":
+        status = "not_verifiable"
+        explanation = (
+            "This appears to be a subjective opinion rather than a verifiable fact."
+        )
+    elif not sources:
+        status = "unverified"
+        explanation = "No sources provided for verification. Additional sources needed."
+    elif source_check["support_level"] == "supported":
+        status = "verified"
+        explanation = f"Claim is supported by {source_check['supporting_sources']} of {len(sources)} sources."
+    elif source_check["support_level"] == "disputed":
+        status = "disputed"
+        explanation = (
+            f"Claim is contradicted by {source_check['contradicting_sources']} sources."
+        )
+    else:
+        status = "inconclusive"
+        explanation = "Sources provide mixed or insufficient evidence."
+
+    result = {
+        "claim": claim,
+        "status": status,
+        "explanation": explanation,
+        "claim_analysis": claim_analysis,
+        "source_analysis": source_check,
+        "sources_checked": len(sources),
+        "recommendation": _get_recommendation(status, source_check),
+    }
+
+    return json.dumps(result)
+
+
+def _get_recommendation(status: str, source_check: dict) -> str:
+    """Generate a recommendation based on verification results."""
+    if status == "verified":
+        return "Claim can be cited with attribution to supporting sources."
+    elif status == "disputed":
+        return "Present both sides of the evidence when citing this claim."
+    elif status == "not_verifiable":
+        return "Present as opinion or perspective, not as fact."
+    elif status == "unverified":
+        return "Seek additional sources before citing this claim."
+    else:
+        return "Exercise caution; more evidence needed for confident citation."
+
+
+RATE_CONFIDENCE_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "claim": {
+            "type": "string",
+            "description": "The claim being evaluated",
+        },
+        "evidence": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "source": {"type": "string"},
+                    "source_type": {"type": "string"},
+                    "supports": {"type": "boolean"},
+                },
+            },
+            "description": "Array of evidence items with source info and support status",
+        },
+    },
+    "required": ["claim", "evidence"],
+}
+
+
+@action(
+    name="rate_confidence",
+    description="Rate confidence level in a claim based on evidence quality.",
+    parameters=RATE_CONFIDENCE_PARAMETERS,
+)
+async def rate_confidence(args: dict[str, Any]) -> str:
+    """Rate confidence in a claim based on evidence."""
+    try:
+        claim = args["claim"]
+        evidence = args["evidence"]
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not claim.strip():
+        return json.dumps({"error": "Claim cannot be empty"})
+
+    if not evidence:
+        return json.dumps(
+            {
+                "claim": claim,
+                "confidence_level": "very_low",
+                "confidence_score": 0.1,
+                "reason": "No evidence provided",
+                "evidence_count": 0,
+            }
+        )
+
+    # Calculate weighted confidence based on evidence
+    total_weight: float = 0.0
+    support_weight: float = 0.0
+
+    for item in evidence:
+        source_type = item.get("source_type", "unknown")
+        reliability = SOURCE_RELIABILITY.get(source_type, SOURCE_RELIABILITY["unknown"])
+        supports = item.get("supports", False)
+
+        total_weight += float(reliability)
+        if supports:
+            support_weight += float(reliability)
+
+    if total_weight == 0:
+        confidence_score = 0.1
+    else:
+        confidence_score = support_weight / total_weight
+
+    # Adjust for evidence quantity
+    evidence_bonus = min(0.2, len(evidence) * 0.05)
+    confidence_score = min(1.0, confidence_score + evidence_bonus)
+
+    # Determine level
+    if confidence_score >= 0.8:
+        level = "high"
+    elif confidence_score >= 0.5:
+        level = "medium"
+    elif confidence_score >= 0.2:
+        level = "low"
+    else:
+        level = "very_low"
+
+    # Count evidence
+    supporting = sum(1 for e in evidence if e.get("supports", False))
+    contradicting = len(evidence) - supporting
+
+    result = {
+        "claim": claim,
+        "confidence_level": level,
+        "confidence_score": round(confidence_score, 2),
+        "evidence_count": len(evidence),
+        "supporting_evidence": supporting,
+        "contradicting_evidence": contradicting,
+        "reason": _get_confidence_reason(level, supporting, contradicting),
+        "reliability_note": "Confidence weighted by source reliability (academic > news > general)",
+    }
+
+    return json.dumps(result)
+
+
+def _get_confidence_reason(level: str, supporting: int, contradicting: int) -> str:
+    """Generate explanation for confidence level."""
+    if level == "high":
+        return f"Strong evidence from {supporting} reliable source(s) with minimal contradiction."
+    elif level == "medium":
+        return f"Moderate evidence with {supporting} supporting and {contradicting} contradicting source(s)."
+    elif level == "low":
+        return f"Limited supporting evidence; {contradicting} source(s) present contradictory information."
+    else:
+        return "Insufficient or unreliable evidence to support this claim."

mail/examples/research/verifier/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Verifier 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.action import LiteLLMActionAgentFunction
+
+
+class LiteLLMVerifierFunction(LiteLLMActionAgentFunction):
+    """
+    Verifier agent that fact-checks claims against sources.
+
+    This agent cross-references claims and rates confidence
+    levels based on evidence quality.
+    """
+
+    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 verifier agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/research/verifier/prompts.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are verifier@{swarm}, the fact-checking specialist for this research assistant swarm.
+
+# Your Role
+Cross-reference claims against sources and rate confidence levels to ensure research accuracy.
+
+# 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 "researcher")
+- After verification, call `send_response(target=<sender>, subject="Re: ...", body=<your findings>)`
+- Include the COMPLETE verification results in your response body
+
+# Tools
+
+## Verification Operations
+- `verify_claim(claim, sources)`: Check a claim against provided source references
+- `rate_confidence(claim, evidence)`: Rate confidence level based on evidence quality
+
+## Communication
+- `send_response(target, subject, body)`: Reply to the agent who requested information
+- `send_request(target, subject, body)`: Ask another agent (e.g., searcher) for additional sources
+- `acknowledge_broadcast(note)`: Acknowledge a broadcast message
+- `ignore_broadcast(reason)`: Ignore an irrelevant broadcast
+
+# Verification Workflow
+
+1. Receive claim to verify from another agent
+2. Review provided sources
+3. Call `verify_claim` to check the claim
+4. Call `rate_confidence` to assess evidence quality
+5. Call `send_response` with:
+   - Verification status (verified/disputed/unverified)
+   - Confidence rating
+   - Supporting or contradicting evidence
+   - Recommendations for additional verification if needed
+
+# Confidence Levels
+
+- **high** (0.8-1.0): Multiple reliable sources confirm, no contradictions
+- **medium** (0.5-0.8): Some supporting evidence, minor inconsistencies possible
+- **low** (0.2-0.5): Limited evidence, significant uncertainty
+- **very_low** (0.0-0.2): No supporting evidence or contradictory information
+
+# Guidelines
+
+- Be skeptical but fair - require evidence for both confirmation and rejection
+- Note when sources disagree and present both sides
+- Consider source reliability (academic > news > general)
+- Flag claims that cannot be verified with available sources
+- Use "Re: <original subject>" as your response subject"""

mail/examples/supervisor/__init__.py

@@ -0,0 +1,11 @@
+from .agent import (
+    supervisor_agent_params,
+)
+from .prompts import (
+    SYSPROMPT as SUPERVISOR_SYSPROMPT,
+)
+
+__all__ = [
+    "SUPERVISOR_SYSPROMPT",
+    "supervisor_agent_params",
+]

mail/examples/supervisor/agent.py

@@ -0,0 +1,4 @@
+supervisor_agent_params = {
+    "llm": "openai/gpt-5-mini",
+    "system": "mail.examples.supervisor.prompts:SYSPROMPT",
+}

mail/examples/supervisor/prompts.py

@@ -0,0 +1,93 @@
+SYSPROMPT = """You are supervisor@{swarm}, the orchestrator for this MAIL swarm.
+
+# Your Role
+Coordinate agents to fulfill user requests. Delegate work, integrate responses, and deliver final answers.
+
+# Critical Rule: Task Completion
+You MUST call `task_complete` to end every task. This is the ONLY way to return answers to users.
+- The moment you have sufficient information to answer, call `task_complete` immediately
+- Do not continue delegating once you have the answer
+- Never send messages to "user" - the runtime will reject it
+- Include the complete answer in `task_complete(finish_message=...)`
+
+# Tools
+
+## Delegation
+- `send_request(target, subject, body)`: Assign work to an agent
+  - Local: target="agent_name"
+  - Interswarm: target="agent_name@swarm_name"
+- `send_response(target, subject, body)`: Reply to another agent (use for interswarm replies)
+- `send_broadcast(subject, body, targets)`: Announce to multiple agents (rare)
+- `send_interrupt(target, subject, body)`: Halt an agent's current work
+
+## Task Control
+- `task_complete(finish_message)`: End task and return answer to user. ALWAYS call this.
+- `await_message(reason)`: Wait for pending responses before proceeding
+
+# Workflow
+
+1. Receive user request
+2. Delegate to specialists via `send_request` with clear instructions
+3. Receive responses from agents
+4. Once you have the answer: call `task_complete` with the full response
+
+# Interswarm Requests
+
+When you receive a request from another swarm (sender contains "@"):
+1. Delegate locally if needed via `send_request`
+2. Send result back via `send_response` to the original sender
+3. Call `task_complete` to close the task
+
+Example: Request from supervisor@swarm-alpha asking about weather
+→ `send_request(target="weather", subject="Forecast needed", body="...")`
+→ Receive weather response
+→ `send_response(target="supervisor@swarm-alpha", subject="Re: Forecast needed", body="...")`
+→ `task_complete(finish_message="Responded to interswarm request with forecast data.")`
+
+# Guidelines
+
+- Be direct and concise in delegations
+- Specify expected format in requests
+- Integrate multiple responses before completing
+- Preserve user's requested format/constraints
+- If blocked, make reasonable assumptions or ask one precise question
+"""
+
+SYSPROMPT_NO_INTERSWARM_MASTER = """You are supervisor@{swarm}, the orchestrator for this MAIL swarm.
+
+# Your Role
+Coordinate agents to fulfill user requests. Delegate work, integrate responses, and deliver final answers.
+
+# Critical Rule: Task Completion
+You MUST call `task_complete` to end every task. This is the ONLY way to return answers to users.
+- The moment you have sufficient information to answer, call `task_complete` immediately
+- Do not continue delegating once you have the answer
+- Never send messages to "user" - the runtime will reject it
+- Include the complete answer in `task_complete(finish_message=...)`
+
+# Tools
+
+## Delegation
+- `send_request(target, subject, body)`: Assign work to a local agent
+- `send_broadcast(subject, body, targets)`: Announce to multiple agents (rare)
+- `send_interrupt(target, subject, body)`: Halt an agent's current work
+
+## Task Control
+- `task_complete(finish_message)`: End task and return answer to user. ALWAYS call this.
+- `await_message(reason)`: Wait for pending responses before proceeding
+
+# Workflow
+
+1. Receive user request
+2. Delegate to specialists via `send_request` with clear instructions
+3. Receive responses from agents
+4. Once you have the answer: call `task_complete` with the full response
+
+# Guidelines
+
+- Be direct and concise in delegations
+- Specify expected format in requests
+- Integrate multiple responses before completing
+- Preserve user's requested format/constraints
+- If blocked, make reasonable assumptions or ask one precise question
+"""

mail/examples/support/__init__.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Customer Support example swarm.
+
+This swarm demonstrates multi-agent workflows for handling customer inquiries
+with ticket classification, FAQ search, sentiment analysis, and escalation.
+
+Agents:
+    - coordinator: Entry point that routes queries and synthesizes responses
+    - faq: Searches FAQ database for relevant answers
+    - classifier: Classifies tickets by category and priority
+    - sentiment: Analyzes customer sentiment and flags escalations
+"""
+
+from mail.examples.support.coordinator.agent import LiteLLMCoordinatorFunction
+from mail.examples.support.faq.agent import LiteLLMFaqFunction
+from mail.examples.support.faq.actions import search_faq
+from mail.examples.support.classifier.agent import LiteLLMClassifierFunction
+from mail.examples.support.classifier.actions import classify_ticket
+from mail.examples.support.sentiment.agent import LiteLLMSentimentFunction
+from mail.examples.support.sentiment.actions import analyze_sentiment, create_escalation
+
+__all__ = [
+    "LiteLLMCoordinatorFunction",
+    "LiteLLMFaqFunction",
+    "LiteLLMClassifierFunction",
+    "LiteLLMSentimentFunction",
+    "search_faq",
+    "classify_ticket",
+    "analyze_sentiment",
+    "create_escalation",
+]

mail/examples/support/classifier/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Classifier agent for the Customer Support swarm."""
+
+from mail.examples.support.classifier.agent import LiteLLMClassifierFunction
+from mail.examples.support.classifier.actions import classify_ticket
+from mail.examples.support.classifier.prompts import SYSPROMPT
+
+__all__ = ["LiteLLMClassifierFunction", "classify_ticket", "SYSPROMPT"]