mail-swarms 1.3.2__py3-none-any.whl

mail/examples/research/summarizer/actions.py

@@ -0,0 +1,255 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Summarization actions for the Research Assistant swarm."""
+
+import json
+import re
+from datetime import datetime, UTC
+from typing import Any
+
+from mail import action
+
+
+def _extract_sentences(text: str) -> list[str]:
+    """Extract sentences from text."""
+    # Simple sentence splitting
+    sentences = re.split(r"(?<=[.!?])\s+", text)
+    return [s.strip() for s in sentences if len(s.strip()) > 10]
+
+
+def _score_sentence_importance(sentence: str, all_sentences: list[str]) -> float:
+    """Score sentence importance based on content features."""
+    score = 0.0
+    sentence_lower = sentence.lower()
+
+    # Position bonus (first sentences are often important)
+    if sentence in all_sentences[:3]:
+        score += 0.3
+
+    # Contains important indicators
+    importance_words = [
+        "important",
+        "key",
+        "main",
+        "significant",
+        "primary",
+        "crucial",
+        "essential",
+        "critical",
+        "major",
+        "notable",
+        "first",
+        "second",
+        "third",
+        "finally",
+        "however",
+        "therefore",
+        "in conclusion",
+        "as a result",
+        "research shows",
+        "data indicates",
+    ]
+    for word in importance_words:
+        if word in sentence_lower:
+            score += 0.2
+
+    # Contains numbers (often factual/important)
+    if any(char.isdigit() for char in sentence):
+        score += 0.15
+
+    # Length penalty for very short or very long sentences
+    word_count = len(sentence.split())
+    if word_count < 5:
+        score -= 0.2
+    elif word_count > 50:
+        score -= 0.1
+    elif 15 <= word_count <= 30:
+        score += 0.1
+
+    return max(0, score)
+
+
+def _create_extractive_summary(text: str, max_sentences: int) -> str:
+    """Create an extractive summary by selecting important sentences."""
+    sentences = _extract_sentences(text)
+
+    if len(sentences) <= max_sentences:
+        return " ".join(sentences)
+
+    # Score sentences
+    scored = [(s, _score_sentence_importance(s, sentences)) for s in sentences]
+
+    # Sort by score but maintain some original order
+    # Take top-scoring sentences
+    scored.sort(key=lambda x: x[1], reverse=True)
+    selected = scored[:max_sentences]
+
+    # Reorder by original position
+    selected_sentences = [s[0] for s in selected]
+    ordered = [s for s in sentences if s in selected_sentences]
+
+    return " ".join(ordered)
+
+
+SUMMARIZE_TEXT_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "text": {
+            "type": "string",
+            "description": "The text to summarize",
+        },
+        "max_length": {
+            "type": "integer",
+            "minimum": 50,
+            "maximum": 2000,
+            "description": "Maximum length of summary in characters (default: 500)",
+        },
+    },
+    "required": ["text"],
+}
+
+
+@action(
+    name="summarize_text",
+    description="Create a concise summary of longer text.",
+    parameters=SUMMARIZE_TEXT_PARAMETERS,
+)
+async def summarize_text(args: dict[str, Any]) -> str:
+    """Summarize text to specified length."""
+    try:
+        text = args["text"]
+        max_length = args.get("max_length", 500)
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not text.strip():
+        return json.dumps({"error": "Text cannot be empty"})
+
+    original_length = len(text)
+    original_sentences = len(_extract_sentences(text))
+
+    # Estimate needed sentences for target length
+    avg_sentence_length = original_length / max(original_sentences, 1)
+    target_sentences = max(1, int(max_length / max(avg_sentence_length, 50)))
+
+    # Create summary
+    summary = _create_extractive_summary(text, target_sentences)
+
+    # Truncate if still too long
+    if len(summary) > max_length:
+        summary = summary[: max_length - 3].rsplit(" ", 1)[0] + "..."
+
+    compression_ratio = len(summary) / original_length if original_length > 0 else 1
+
+    result = {
+        "summary": summary,
+        "original_length": original_length,
+        "summary_length": len(summary),
+        "compression_ratio": round(compression_ratio, 2),
+        "original_sentences": original_sentences,
+        "summary_sentences": len(_extract_sentences(summary)),
+        "method": "extractive",
+    }
+
+    return json.dumps(result)
+
+
+CREATE_BIBLIOGRAPHY_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "sources": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string"},
+                    "author": {"type": "string"},
+                    "url": {"type": "string"},
+                    "date": {"type": "string"},
+                    "source_type": {"type": "string"},
+                },
+            },
+            "description": "Array of source objects with title, author, url, date, source_type",
+        },
+        "style": {
+            "type": "string",
+            "enum": ["apa", "mla", "chicago", "simple"],
+            "description": "Citation style (default: simple)",
+        },
+    },
+    "required": ["sources"],
+}
+
+
+@action(
+    name="create_bibliography",
+    description="Format sources into a properly formatted bibliography.",
+    parameters=CREATE_BIBLIOGRAPHY_PARAMETERS,
+)
+async def create_bibliography(args: dict[str, Any]) -> str:
+    """Create a formatted bibliography from sources."""
+    try:
+        sources = args["sources"]
+        style = args.get("style", "simple")
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not sources:
+        return json.dumps({"error": "At least one source is required"})
+
+    formatted_entries = []
+
+    for i, source in enumerate(sources, 1):
+        title = source.get("title", "Untitled")
+        author = source.get("author", "Unknown Author")
+        url = source.get("url", "")
+        date = source.get("date", "n.d.")
+        source_type = source.get("source_type", "web")
+
+        if style == "apa":
+            # APA style: Author. (Date). Title. URL
+            entry = f"{author}. ({date}). {title}."
+            if url:
+                entry += f" Retrieved from {url}"
+        elif style == "mla":
+            # MLA style: Author. "Title." Date. URL.
+            entry = f'{author}. "{title}." {date}.'
+            if url:
+                entry += f" {url}."
+        elif style == "chicago":
+            # Chicago style: Author. "Title." Accessed Date. URL.
+            entry = f'{author}. "{title}."'
+            if url:
+                entry += f" Accessed {datetime.now(UTC).strftime('%B %d, %Y')}. {url}."
+        else:  # simple
+            # Simple style: numbered list
+            entry = f"[{i}] {title}"
+            if author != "Unknown Author":
+                entry += f" by {author}"
+            if date != "n.d.":
+                entry += f" ({date})"
+            if url:
+                entry += f" - {url}"
+
+        formatted_entries.append(
+            {
+                "index": i,
+                "formatted": entry,
+                "source_type": source_type,
+                "original": source,
+            }
+        )
+
+    # Create bibliography text
+    bibliography_text = "\n".join([e["formatted"] for e in formatted_entries])
+
+    result = {
+        "style": style,
+        "entry_count": len(formatted_entries),
+        "entries": formatted_entries,
+        "bibliography": bibliography_text,
+        "generated_at": datetime.now(UTC).isoformat(),
+    }
+
+    return json.dumps(result)

mail/examples/research/summarizer/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Summarizer 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 LiteLLMSummarizerFunction(LiteLLMActionAgentFunction):
+    """
+    Summarizer agent that synthesizes research findings.
+
+    This agent creates concise summaries and formatted
+    bibliographies from research data.
+    """
+
+    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 summarizer agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/research/summarizer/prompts.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are summarizer@{swarm}, the synthesis specialist for this research assistant swarm.
+
+# Your Role
+Synthesize research findings into clear, well-organized summaries and create formatted bibliographies.
+
+# 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 summarizing, call `send_response(target=<sender>, subject="Re: ...", body=<your summary>)`
+- Include the COMPLETE summary in your response body
+
+# Tools
+
+## Summarization Operations
+- `summarize_text(text, max_length)`: Create a concise summary of longer text
+- `create_bibliography(sources)`: Format sources into a proper bibliography
+
+## Communication
+- `send_response(target, subject, body)`: Reply to the agent who requested information
+- `send_request(target, subject, body)`: Ask another agent for information
+- `acknowledge_broadcast(note)`: Acknowledge a broadcast message
+- `ignore_broadcast(reason)`: Ignore an irrelevant broadcast
+
+# Workflow
+
+1. Receive research findings from another agent
+2. Organize the information logically
+3. Call `summarize_text` to create a concise summary
+4. If sources provided, call `create_bibliography` to format them
+5. Call `send_response` with:
+   - Executive summary (key findings)
+   - Detailed summary (organized by theme)
+   - Bibliography (if applicable)
+   - Confidence notes or caveats
+
+# Summary Structure
+
+Good summaries include:
+- **Key Findings**: 2-3 main takeaways
+- **Background**: Brief context
+- **Details**: Organized supporting information
+- **Limitations**: What's uncertain or missing
+- **Sources**: Properly formatted references
+
+# Guidelines
+
+- Lead with the most important findings
+- Use clear, accessible language
+- Maintain original meaning while condensing
+- Preserve important nuances and caveats
+- Include all cited sources in bibliography
+- Use "Re: <original subject>" as your response subject"""

mail/examples/research/verifier/__init__.py

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