mail-swarms 1.3.2__py3-none-any.whl

mail/examples/support/classifier/actions.py

@@ -0,0 +1,307 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Ticket classification action for the Customer Support swarm."""
+
+import json
+import re
+from typing import Any
+
+from mail import action
+
+# Keyword mappings for classification
+CATEGORY_KEYWORDS = {
+    "billing": [
+        "payment",
+        "pay",
+        "charge",
+        "charged",
+        "invoice",
+        "bill",
+        "refund",
+        "subscription",
+        "cancel",
+        "price",
+        "pricing",
+        "cost",
+        "credit card",
+        "card",
+        "money",
+        "fee",
+        "upgrade",
+        "downgrade",
+        "renew",
+        "renewal",
+    ],
+    "technical": [
+        "bug",
+        "error",
+        "crash",
+        "not working",
+        "broken",
+        "issue",
+        "problem",
+        "feature",
+        "slow",
+        "loading",
+        "api",
+        "integration",
+        "code",
+        "export",
+        "import",
+        "sync",
+        "download",
+        "upload",
+        "connect",
+        "connection",
+    ],
+    "account": [
+        "login",
+        "password",
+        "reset",
+        "account",
+        "profile",
+        "email",
+        "locked",
+        "access",
+        "sign in",
+        "sign up",
+        "register",
+        "2fa",
+        "authentication",
+        "security",
+        "verify",
+        "verification",
+        "username",
+        "settings",
+    ],
+    "general": [
+        "question",
+        "help",
+        "support",
+        "information",
+        "info",
+        "how to",
+        "what is",
+        "where",
+        "when",
+        "feedback",
+        "suggestion",
+        "thanks",
+        "thank you",
+        "appreciate",
+        "curious",
+        "wondering",
+    ],
+}
+
+PRIORITY_KEYWORDS = {
+    "urgent": [
+        "urgent",
+        "emergency",
+        "asap",
+        "immediately",
+        "critical",
+        "outage",
+        "down",
+        "breach",
+        "hacked",
+        "compromised",
+        "lost all",
+        "cannot access",
+        "locked out",
+        "deadline",
+        "now",
+        "right now",
+    ],
+    "high": [
+        "important",
+        "serious",
+        "major",
+        "significant",
+        "blocking",
+        "stuck",
+        "cannot",
+        "can't",
+        "unable",
+        "frustrated",
+        "angry",
+        "unacceptable",
+        "terrible",
+        "awful",
+        "horrible",
+        "worst",
+    ],
+    "medium": [
+        "issue",
+        "problem",
+        "help",
+        "need",
+        "want",
+        "would like",
+        "please",
+        "soon",
+        "when",
+        "how long",
+        "waiting",
+        "expected",
+    ],
+    "low": [
+        "question",
+        "curious",
+        "wondering",
+        "just",
+        "maybe",
+        "might",
+        "feedback",
+        "suggestion",
+        "idea",
+        "thanks",
+        "fyi",
+        "minor",
+    ],
+}
+
+
+def _count_keyword_matches(text: str, keywords: list[str]) -> int:
+    """Count how many keywords appear in the text."""
+    text_lower = text.lower()
+    count = 0
+    for keyword in keywords:
+        # Use word boundary matching for better accuracy
+        pattern = r"\b" + re.escape(keyword) + r"\b"
+        if re.search(pattern, text_lower):
+            count += 1
+    return count
+
+
+def _classify_category(text: str) -> tuple[str, float]:
+    """Classify the ticket category based on keyword matching."""
+    scores = {}
+    for category, keywords in CATEGORY_KEYWORDS.items():
+        scores[category] = _count_keyword_matches(text, keywords)
+
+    # Find the category with highest score
+    max_category = max(scores, key=lambda x: scores[x])
+    max_score = scores[max_category]
+
+    # Calculate confidence based on score differential
+    total_score = sum(scores.values())
+    if total_score == 0:
+        return "general", 0.3  # Default to general with low confidence
+
+    confidence = max_score / total_score if total_score > 0 else 0.5
+    return max_category, round(confidence, 2)
+
+
+def _classify_priority(text: str) -> tuple[str, float]:
+    """Classify the ticket priority based on keyword matching."""
+    scores = {}
+    for priority, keywords in PRIORITY_KEYWORDS.items():
+        scores[priority] = _count_keyword_matches(text, keywords)
+
+    # Apply priority weighting (urgent keywords should have more weight)
+    weighted_scores = {
+        "urgent": scores["urgent"] * 4,
+        "high": scores["high"] * 3,
+        "medium": scores["medium"] * 2,
+        "low": scores["low"] * 1,
+    }
+
+    # Find the priority with highest weighted score
+    max_priority = max(weighted_scores, key=lambda x: weighted_scores[x])
+    max_score = weighted_scores[max_priority]
+
+    # Default to medium if no clear signal
+    if max_score == 0:
+        return "medium", 0.5
+
+    total_score = sum(weighted_scores.values())
+    confidence = max_score / total_score if total_score > 0 else 0.5
+    return max_priority, round(confidence, 2)
+
+
+CLASSIFY_TICKET_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "text": {
+            "type": "string",
+            "description": "The customer support ticket text to classify",
+        },
+    },
+    "required": ["text"],
+}
+
+
+@action(
+    name="classify_ticket",
+    description="Classify a customer support ticket by category and priority level.",
+    parameters=CLASSIFY_TICKET_PARAMETERS,
+)
+async def classify_ticket(args: dict[str, Any]) -> str:
+    """Classify a support ticket and return category and priority."""
+    try:
+        text = args["text"]
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not text.strip():
+        return json.dumps({"error": "Ticket text cannot be empty"})
+
+    # Perform classification
+    category, category_confidence = _classify_category(text)
+    priority, priority_confidence = _classify_priority(text)
+
+    # Generate reasoning
+    reasoning_parts = []
+    if category_confidence >= 0.6:
+        reasoning_parts.append(f"Strong match for '{category}' category")
+    else:
+        reasoning_parts.append(f"Moderate match for '{category}' category")
+
+    if priority == "urgent":
+        reasoning_parts.append("Contains urgent/critical language")
+    elif priority == "high":
+        reasoning_parts.append(
+            "Indicates significant user frustration or blocking issue"
+        )
+    elif priority == "low":
+        reasoning_parts.append("Appears to be a general inquiry or minor issue")
+
+    result = {
+        "category": category,
+        "category_confidence": category_confidence,
+        "priority": priority,
+        "priority_confidence": priority_confidence,
+        "reasoning": ". ".join(reasoning_parts) + ".",
+        "suggested_actions": _get_suggested_actions(category, priority),
+    }
+
+    return json.dumps(result)
+
+
+def _get_suggested_actions(category: str, priority: str) -> list[str]:
+    """Get suggested actions based on classification."""
+    actions = []
+
+    if priority == "urgent":
+        actions.append("Escalate to senior support immediately")
+        actions.append("Consider immediate callback if phone available")
+    elif priority == "high":
+        actions.append("Prioritize in support queue")
+        actions.append("Provide detailed response within 4 hours")
+
+    if category == "billing":
+        actions.append("Check customer's billing history")
+        actions.append("Verify subscription status")
+    elif category == "technical":
+        actions.append("Check for known issues or outages")
+        actions.append("Gather technical details if needed")
+    elif category == "account":
+        actions.append("Verify customer identity")
+        actions.append("Check account security flags")
+
+    if not actions:
+        actions.append("Respond with standard FAQ or support resources")
+
+    return actions

mail/examples/support/classifier/agent.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Classifier 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 LiteLLMClassifierFunction(LiteLLMActionAgentFunction):
+    """
+    Ticket classifier agent that categorizes and prioritizes support tickets.
+
+    This agent analyzes customer messages to determine the appropriate
+    category (billing, technical, account, general) and priority level
+    (low, medium, high, urgent).
+    """
+
+    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 classifier agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/support/classifier/prompts.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are classifier@{swarm}, the ticket classification specialist for this customer support swarm.
+
+# Your Role
+Classify customer support tickets by category and priority level to ensure proper routing and handling.
+
+# 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 classifying the ticket, call `send_response(target=<sender>, subject="Re: ...", body=<your classification>)`
+- Include the FULL classification results in your response body
+
+# Tools
+
+## Classification
+- `classify_ticket(text)`: Analyze ticket text and return category + priority
+
+## Communication
+- `send_response(target, subject, body)`: Reply to the agent who requested information
+- `send_request(target, subject, body)`: Ask another agent for information (e.g., sentiment for urgent cases)
+- `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 `classify_ticket` with the customer's message text
+3. Review the classification results
+4. Optionally request sentiment analysis for borderline cases
+5. Call `send_response` to the original sender with:
+   - Category (billing, technical, account, general)
+   - Priority (low, medium, high, urgent)
+   - Brief reasoning for the classification
+
+# Classification Guidelines
+
+**Categories:**
+- billing: Payment issues, refunds, subscription changes, invoices
+- technical: Bugs, errors, feature requests, how-to questions
+- account: Login issues, profile changes, security concerns
+- general: General inquiries, feedback, other topics
+
+**Priority Levels:**
+- urgent: Service outage, security breach, financial loss
+- high: Significant issue affecting user's ability to use the service
+- medium: Important but not blocking, workaround available
+- low: Minor issue, general question, feedback
+
+# Guidelines
+
+- Be consistent in your classifications
+- When in doubt, err on the side of higher priority
+- Report the classification clearly with category and priority
+- Use "Re: <original subject>" as your response subject"""

mail/examples/support/coordinator/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Coordinator agent for the Customer Support swarm."""
+
+from mail.examples.support.coordinator.agent import LiteLLMCoordinatorFunction
+from mail.examples.support.coordinator.prompts import SYSPROMPT
+
+__all__ = ["LiteLLMCoordinatorFunction", "SYSPROMPT"]

mail/examples/support/coordinator/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Coordinator 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.base import LiteLLMAgentFunction
+
+
+class LiteLLMCoordinatorFunction(LiteLLMAgentFunction):
+    """
+    Coordinator agent that orchestrates the customer support workflow.
+
+    This agent serves as the entry point for customer inquiries and delegates
+    to specialist agents (faq, classifier, sentiment) as 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 = 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 coordinator agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/support/coordinator/prompts.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are coordinator@{swarm}, the lead support coordinator for this customer service swarm.
+
+# Your Role
+Orchestrate the customer support workflow by routing inquiries to specialist agents and synthesizing their responses into helpful, professional answers.
+
+# Critical Rules
+
+1. **You MUST call task_complete to end every task** - this is how the user receives their answer
+2. Delegate work to specialist agents based on the inquiry type:
+   - `faq` - For common questions that might be in the FAQ database
+   - `classifier` - To categorize and prioritize tickets
+   - `sentiment` - To analyze customer tone and detect escalation needs
+
+# Available Agents
+
+- **faq**: Searches the FAQ database for relevant answers. Use for common questions about products, policies, or procedures.
+- **classifier**: Categorizes tickets by type (billing, technical, general, etc.) and assigns priority levels.
+- **sentiment**: Analyzes customer sentiment and identifies if escalation to a human agent is needed.
+
+# 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 customer inquiry
+2. Analyze what type of support is needed
+3. Delegate to appropriate agents:
+   - FAQ lookup for knowledge-based questions
+   - Classification for ticket routing
+   - Sentiment analysis for tone assessment
+4. Collect responses using `await_message`
+5. Synthesize information into a helpful response
+6. Call `task_complete` with your final answer
+
+# Guidelines
+
+- Be professional and empathetic in your final responses
+- If sentiment analysis indicates high frustration, acknowledge it in your response
+- If no FAQ answer exists, provide general guidance or suggest contacting support
+- Always prioritize customer satisfaction
+- Keep responses concise but complete"""

mail/examples/support/faq/__init__.py

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