mail-swarms 1.3.2__py3-none-any.whl

mail/examples/support/faq/actions.py

@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""FAQ search action for the Customer Support swarm."""
+
+import json
+from typing import Any
+
+from mail import action
+
+# Dummy FAQ database for demonstration purposes
+FAQ_DATABASE = [
+    {
+        "id": "faq-001",
+        "question": "How do I reset my password?",
+        "answer": "To reset your password: 1) Go to the login page, 2) Click 'Forgot Password', 3) Enter your email address, 4) Check your email for a reset link, 5) Click the link and create a new password. The reset link expires after 24 hours.",
+        "category": "account",
+        "keywords": ["password", "reset", "forgot", "login", "account", "access"],
+    },
+    {
+        "id": "faq-002",
+        "question": "What is your refund policy?",
+        "answer": "We offer a 30-day money-back guarantee on all purchases. To request a refund: 1) Contact our support team within 30 days of purchase, 2) Provide your order number, 3) Explain the reason for the refund. Refunds are processed within 5-7 business days to your original payment method.",
+        "category": "billing",
+        "keywords": ["refund", "money", "return", "policy", "guarantee", "purchase"],
+    },
+    {
+        "id": "faq-003",
+        "question": "How do I cancel my subscription?",
+        "answer": "To cancel your subscription: 1) Log into your account, 2) Go to Settings > Subscription, 3) Click 'Cancel Subscription', 4) Confirm your cancellation. Your access continues until the end of the current billing period. You can resubscribe at any time.",
+        "category": "billing",
+        "keywords": ["cancel", "subscription", "unsubscribe", "stop", "billing"],
+    },
+    {
+        "id": "faq-004",
+        "question": "How do I contact customer support?",
+        "answer": "You can reach our support team through: 1) Email: support@example.com (response within 24 hours), 2) Live chat on our website (available 9am-6pm EST), 3) Phone: 1-800-EXAMPLE (Monday-Friday 9am-5pm EST). For urgent issues, please use phone support.",
+        "category": "general",
+        "keywords": ["contact", "support", "help", "phone", "email", "chat"],
+    },
+    {
+        "id": "faq-005",
+        "question": "Why is my account locked?",
+        "answer": "Accounts may be locked for security reasons including: 1) Multiple failed login attempts, 2) Suspicious activity detected, 3) Password expired. To unlock your account, use the 'Forgot Password' feature or contact support. If you believe this is an error, our security team can review your case.",
+        "category": "account",
+        "keywords": ["locked", "account", "security", "blocked", "access", "suspended"],
+    },
+    {
+        "id": "faq-006",
+        "question": "How do I update my billing information?",
+        "answer": "To update billing information: 1) Log into your account, 2) Go to Settings > Payment Methods, 3) Click 'Edit' next to your current payment method or 'Add New', 4) Enter your new card details, 5) Click 'Save'. Your next charge will use the updated payment method.",
+        "category": "billing",
+        "keywords": ["billing", "payment", "credit card", "update", "change", "card"],
+    },
+    {
+        "id": "faq-007",
+        "question": "What features are included in my plan?",
+        "answer": "Plan features vary by tier: Basic includes core features and email support. Pro adds advanced analytics, priority support, and API access. Enterprise includes all Pro features plus dedicated account manager, custom integrations, and 24/7 phone support. Visit our pricing page for detailed comparisons.",
+        "category": "general",
+        "keywords": [
+            "features",
+            "plan",
+            "tier",
+            "pricing",
+            "include",
+            "basic",
+            "pro",
+            "enterprise",
+        ],
+    },
+    {
+        "id": "faq-008",
+        "question": "How do I export my data?",
+        "answer": "To export your data: 1) Go to Settings > Data & Privacy, 2) Click 'Export Data', 3) Select the data types to include, 4) Choose your format (CSV or JSON), 5) Click 'Generate Export'. You'll receive an email with a download link within 24 hours. Exports are available for 7 days.",
+        "category": "technical",
+        "keywords": ["export", "data", "download", "backup", "csv", "json"],
+    },
+    {
+        "id": "faq-009",
+        "question": "Is my data secure?",
+        "answer": "Yes, we take security seriously. We use: 1) AES-256 encryption for data at rest, 2) TLS 1.3 for data in transit, 3) Regular security audits by third parties, 4) SOC 2 Type II certification, 5) GDPR and CCPA compliance. We never sell your data to third parties.",
+        "category": "technical",
+        "keywords": [
+            "security",
+            "data",
+            "encryption",
+            "privacy",
+            "secure",
+            "safe",
+            "gdpr",
+        ],
+    },
+    {
+        "id": "faq-010",
+        "question": "How do I enable two-factor authentication?",
+        "answer": "To enable 2FA: 1) Go to Settings > Security, 2) Click 'Enable Two-Factor Authentication', 3) Choose your method (authenticator app or SMS), 4) Follow the setup instructions, 5) Save your backup codes. We recommend using an authenticator app for better security.",
+        "category": "account",
+        "keywords": ["two-factor", "2fa", "authentication", "security", "mfa", "otp"],
+    },
+]
+
+SEARCH_FAQ_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "query": {
+            "type": "string",
+            "description": "The search query to find relevant FAQ entries",
+        },
+        "max_results": {
+            "type": "integer",
+            "description": "Maximum number of FAQ entries to return (default: 3)",
+            "minimum": 1,
+            "maximum": 10,
+        },
+    },
+    "required": ["query"],
+}
+
+
+def _calculate_relevance(query: str, faq_entry: dict[str, Any]) -> float:
+    """Calculate relevance score between query and FAQ entry."""
+    query_terms = set(query.lower().split())
+    keywords = set(faq_entry.get("keywords", []))
+    question_terms = set(faq_entry.get("question", "").lower().split())
+
+    # Score based on keyword matches (highest weight)
+    keyword_matches = len(query_terms & keywords)
+    # Score based on question word matches
+    question_matches = len(query_terms & question_terms)
+
+    # Combined score with weights
+    score = (keyword_matches * 2.0) + (question_matches * 1.0)
+    return score
+
+
+@action(
+    name="search_faq",
+    description="Search the FAQ database for entries relevant to a customer query.",
+    parameters=SEARCH_FAQ_PARAMETERS,
+)
+async def search_faq(args: dict[str, Any]) -> str:
+    """Search the FAQ database and return relevant entries."""
+    try:
+        query = args["query"]
+        max_results = args.get("max_results", 3)
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not query.strip():
+        return json.dumps({"error": "Query cannot be empty", "results": []})
+
+    # Calculate relevance scores for all FAQ entries
+    scored_entries = []
+    for entry in FAQ_DATABASE:
+        score = _calculate_relevance(query, entry)
+        if score > 0:
+            scored_entries.append((score, entry))
+
+    # Sort by relevance score (descending)
+    scored_entries.sort(key=lambda x: x[0], reverse=True)
+
+    # Take top results
+    results = []
+    for score, entry in scored_entries[:max_results]:
+        results.append(
+            {
+                "id": entry["id"],
+                "question": entry["question"],
+                "answer": entry["answer"],
+                "category": entry["category"],
+                "relevance_score": round(score, 2),
+            }
+        )
+
+    return json.dumps(
+        {
+            "query": query,
+            "total_matches": len(scored_entries),
+            "results_returned": len(results),
+            "results": results,
+        }
+    )

mail/examples/support/faq/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""FAQ 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 LiteLLMFaqFunction(LiteLLMActionAgentFunction):
+    """
+    FAQ specialist agent that searches the FAQ database.
+
+    This agent handles FAQ searches and returns relevant entries
+    to help answer customer questions.
+    """
+
+    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 FAQ agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/support/faq/prompts.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are faq@{swarm}, the FAQ specialist for this customer support swarm.
+
+# Your Role
+Search the FAQ database to find relevant answers to customer questions and report results back to the coordinator.
+
+# 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 searching the FAQ, call `send_response(target=<sender>, subject="Re: ...", body=<your answer>)`
+- Include ALL relevant FAQ entries in your response body - the recipient cannot see tool results
+
+# Tools
+
+## FAQ Search
+- `search_faq(query, max_results)`: Search the FAQ database for relevant entries
+
+## 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 (note the sender)
+2. Call `search_faq` with relevant search terms from the query
+3. Review the results and identify the most relevant answers
+4. Call `send_response` to the original sender with:
+   - The relevant FAQ entries found
+   - A brief summary of how they relate to the question
+   - Note if no relevant entries were found
+
+# Guidelines
+
+- Use specific keywords from the customer question for better search results
+- If the first search yields poor results, try alternative search terms
+- Report honestly if no relevant FAQ entries exist
+- Include the FAQ question and answer in your response, not just a summary
+- Use "Re: <original subject>" as your response subject"""

mail/examples/support/sentiment/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Sentiment agent for the Customer Support swarm."""
+
+from mail.examples.support.sentiment.agent import LiteLLMSentimentFunction
+from mail.examples.support.sentiment.actions import analyze_sentiment, create_escalation
+from mail.examples.support.sentiment.prompts import SYSPROMPT
+
+__all__ = [
+    "LiteLLMSentimentFunction",
+    "analyze_sentiment",
+    "create_escalation",
+    "SYSPROMPT",
+]

mail/examples/support/sentiment/actions.py

@@ -0,0 +1,341 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Sentiment analysis actions for the Customer Support swarm."""
+
+import json
+import re
+import uuid
+from datetime import datetime, UTC
+from typing import Any
+
+from mail import action
+
+# Sentiment indicators with associated scores
+POSITIVE_INDICATORS = {
+    "strong": [
+        ("love", 0.9),
+        ("amazing", 0.85),
+        ("excellent", 0.85),
+        ("fantastic", 0.85),
+        ("wonderful", 0.8),
+        ("great", 0.75),
+        ("awesome", 0.8),
+        ("perfect", 0.85),
+        ("best", 0.75),
+        ("thank you so much", 0.8),
+        ("really appreciate", 0.75),
+    ],
+    "moderate": [
+        ("good", 0.5),
+        ("nice", 0.5),
+        ("helpful", 0.6),
+        ("thanks", 0.4),
+        ("appreciate", 0.5),
+        ("pleased", 0.6),
+        ("happy", 0.6),
+        ("satisfied", 0.5),
+        ("works", 0.3),
+        ("resolved", 0.5),
+        ("fixed", 0.5),
+    ],
+}
+
+NEGATIVE_INDICATORS = {
+    "strong": [
+        ("terrible", -0.9),
+        ("horrible", -0.9),
+        ("worst", -0.85),
+        ("hate", -0.85),
+        ("disgusted", -0.8),
+        ("furious", -0.85),
+        ("outraged", -0.85),
+        ("scam", -0.9),
+        ("fraud", -0.9),
+        ("lawsuit", -0.9),
+        ("lawyer", -0.8),
+        ("sue", -0.85),
+        ("unacceptable", -0.75),
+        ("ridiculous", -0.7),
+    ],
+    "moderate": [
+        ("frustrated", -0.6),
+        ("annoyed", -0.5),
+        ("disappointed", -0.5),
+        ("upset", -0.55),
+        ("angry", -0.65),
+        ("bad", -0.5),
+        ("poor", -0.5),
+        ("awful", -0.7),
+        ("useless", -0.6),
+        ("broken", -0.4),
+        ("failed", -0.45),
+        ("doesn't work", -0.5),
+        ("not working", -0.5),
+        ("can't", -0.3),
+    ],
+}
+
+ESCALATION_PHRASES = [
+    "speak to manager",
+    "speak to a manager",
+    "talk to manager",
+    "supervisor",
+    "escalate",
+    "cancel my account",
+    "cancel my subscription",
+    "legal action",
+    "lawyer",
+    "sue you",
+    "report you",
+    "bbb",
+    "better business bureau",
+    "never again",
+    "worst company",
+    "stealing",
+    "theft",
+    "refund now",
+]
+
+EMOTION_PATTERNS = {
+    "anger": ["angry", "furious", "mad", "outraged", "infuriated", "livid"],
+    "frustration": ["frustrated", "annoyed", "irritated", "exasperated", "fed up"],
+    "disappointment": ["disappointed", "let down", "expected better", "underwhelmed"],
+    "anxiety": ["worried", "concerned", "anxious", "nervous", "stressed"],
+    "confusion": ["confused", "don't understand", "unclear", "lost", "puzzled"],
+    "satisfaction": ["satisfied", "happy", "pleased", "glad", "content"],
+    "gratitude": ["thank", "appreciate", "grateful", "thankful"],
+}
+
+
+def _detect_emotions(text: str) -> list[dict[str, Any]]:
+    """Detect emotions present in the text."""
+    text_lower = text.lower()
+    detected = []
+
+    for emotion, patterns in EMOTION_PATTERNS.items():
+        for pattern in patterns:
+            if pattern in text_lower:
+                detected.append(
+                    {
+                        "emotion": emotion,
+                        "indicator": pattern,
+                    }
+                )
+                break  # Only add each emotion once
+
+    return detected
+
+
+def _calculate_sentiment_score(text: str) -> tuple[float, list[str]]:
+    """Calculate sentiment score and return contributing factors."""
+    text_lower = text.lower()
+    score = 0.0
+    factors = []
+
+    # Check positive indicators
+    for strength, indicators in POSITIVE_INDICATORS.items():
+        for phrase, value in indicators:
+            if phrase in text_lower:
+                score += value
+                factors.append(f"+{value:.1f} ({phrase})")
+
+    # Check negative indicators
+    for strength, indicators in NEGATIVE_INDICATORS.items():
+        for phrase, value in indicators:
+            if phrase in text_lower:
+                score += value
+                factors.append(f"{value:.1f} ({phrase})")
+
+    # Normalize score to -1 to +1 range
+    if score > 1.0:
+        score = 1.0
+    elif score < -1.0:
+        score = -1.0
+
+    return round(score, 2), factors
+
+
+def _check_escalation_needed(text: str, score: float) -> tuple[bool, str | None]:
+    """Check if escalation to human agent is needed."""
+    text_lower = text.lower()
+
+    # Check for explicit escalation phrases
+    for phrase in ESCALATION_PHRASES:
+        if phrase in text_lower:
+            return (
+                True,
+                f"Customer explicitly requested escalation or used concerning phrase: '{phrase}'",
+            )
+
+    # Check for very negative sentiment
+    if score <= -0.6:
+        return True, f"Very negative sentiment detected (score: {score})"
+
+    # Check for strong negative emotions
+    if any(
+        word in text_lower
+        for word in ["furious", "outraged", "lawsuit", "lawyer", "sue"]
+    ):
+        return True, "Strong negative emotions or legal language detected"
+
+    return False, None
+
+
+ANALYZE_SENTIMENT_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "text": {
+            "type": "string",
+            "description": "The customer text to analyze for sentiment",
+        },
+    },
+    "required": ["text"],
+}
+
+
+@action(
+    name="analyze_sentiment",
+    description="Analyze the sentiment and emotional tone of customer text.",
+    parameters=ANALYZE_SENTIMENT_PARAMETERS,
+)
+async def analyze_sentiment(args: dict[str, Any]) -> str:
+    """Analyze sentiment of customer text."""
+    try:
+        text = args["text"]
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not text.strip():
+        return json.dumps({"error": "Text cannot be empty"})
+
+    # Calculate sentiment score
+    score, factors = _calculate_sentiment_score(text)
+
+    # Determine overall sentiment category
+    if score >= 0.3:
+        sentiment = "positive"
+    elif score <= -0.3:
+        sentiment = "negative"
+    else:
+        sentiment = "neutral"
+
+    # Detect specific emotions
+    emotions = _detect_emotions(text)
+
+    # Check if escalation is needed
+    escalation_needed, escalation_reason = _check_escalation_needed(text, score)
+
+    result = {
+        "sentiment": sentiment,
+        "score": score,
+        "score_factors": factors
+        if factors
+        else ["No strong sentiment indicators found"],
+        "emotions_detected": emotions
+        if emotions
+        else [{"emotion": "neutral", "indicator": "none detected"}],
+        "escalation_recommended": escalation_needed,
+        "escalation_reason": escalation_reason,
+        "analysis_summary": _generate_summary(
+            sentiment, score, emotions, escalation_needed
+        ),
+    }
+
+    return json.dumps(result)
+
+
+def _generate_summary(
+    sentiment: str, score: float, emotions: list[dict], escalation: bool
+) -> str:
+    """Generate a human-readable summary of the sentiment analysis."""
+    summary_parts = []
+
+    # Sentiment description
+    if score >= 0.5:
+        summary_parts.append("Customer expresses strong positive sentiment")
+    elif score >= 0.2:
+        summary_parts.append("Customer expresses mild positive sentiment")
+    elif score <= -0.5:
+        summary_parts.append("Customer expresses strong negative sentiment")
+    elif score <= -0.2:
+        summary_parts.append("Customer expresses mild negative sentiment")
+    else:
+        summary_parts.append("Customer sentiment is neutral")
+
+    # Emotion summary
+    if emotions:
+        emotion_names = [e["emotion"] for e in emotions]
+        if len(emotion_names) == 1:
+            summary_parts.append(f"Primary emotion detected: {emotion_names[0]}")
+        elif len(emotion_names) > 1:
+            summary_parts.append(f"Emotions detected: {', '.join(emotion_names)}")
+
+    # Escalation note
+    if escalation:
+        summary_parts.append(
+            "ESCALATION RECOMMENDED - Human agent intervention suggested"
+        )
+
+    return ". ".join(summary_parts) + "."
+
+
+CREATE_ESCALATION_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "ticket_id": {
+            "type": "string",
+            "description": "The ticket ID to escalate",
+        },
+        "reason": {
+            "type": "string",
+            "description": "The reason for escalation",
+        },
+        "priority": {
+            "type": "string",
+            "enum": ["high", "urgent"],
+            "description": "The escalation priority level",
+        },
+    },
+    "required": ["ticket_id", "reason", "priority"],
+}
+
+
+@action(
+    name="create_escalation",
+    description="Create an escalation record to flag a ticket for human agent review.",
+    parameters=CREATE_ESCALATION_PARAMETERS,
+)
+async def create_escalation(args: dict[str, Any]) -> str:
+    """Create an escalation record for a support ticket."""
+    try:
+        ticket_id = args["ticket_id"]
+        reason = args["reason"]
+        priority = args["priority"]
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if priority not in ("high", "urgent"):
+        return json.dumps({"error": "Priority must be 'high' or 'urgent'"})
+
+    # Generate escalation record (dummy implementation)
+    escalation = {
+        "escalation_id": f"ESC-{uuid.uuid4().hex[:8].upper()}",
+        "ticket_id": ticket_id,
+        "reason": reason,
+        "priority": priority,
+        "status": "pending",
+        "created_at": datetime.now(UTC).isoformat(),
+        "assigned_to": "support_supervisor_queue"
+        if priority == "high"
+        else "urgent_response_team",
+        "sla_target": "4 hours" if priority == "high" else "1 hour",
+    }
+
+    return json.dumps(
+        {
+            "success": True,
+            "message": f"Escalation created successfully with {priority} priority",
+            "escalation": escalation,
+        }
+    )