mail-swarms 1.3.2__py3-none-any.whl

mail/examples/data_analysis/processor/actions.py

@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Data processing actions for the Data Analysis swarm."""
+
+import csv
+import io
+import json
+from datetime import UTC, datetime, timedelta
+from random import Random
+from typing import Any
+
+from mail import action
+
+# Dataset templates with generators
+DATASET_GENERATORS = {
+    "sales": {
+        "columns": ["date", "product", "quantity", "revenue", "region"],
+        "description": "Sales transaction data",
+    },
+    "users": {
+        "columns": [
+            "user_id",
+            "signup_date",
+            "age",
+            "subscription_type",
+            "activity_score",
+        ],
+        "description": "User account data",
+    },
+    "inventory": {
+        "columns": [
+            "product_id",
+            "category",
+            "stock_level",
+            "reorder_point",
+            "unit_cost",
+        ],
+        "description": "Inventory tracking data",
+    },
+    "weather": {
+        "columns": ["date", "temperature", "humidity", "precipitation", "wind_speed"],
+        "description": "Daily weather observations",
+    },
+}
+
+PRODUCTS = [
+    "Widget A",
+    "Widget B",
+    "Gadget Pro",
+    "Gadget Lite",
+    "Service Plan",
+    "Accessory Pack",
+]
+REGIONS = ["North", "South", "East", "West", "Central"]
+SUBSCRIPTION_TYPES = ["free", "basic", "pro", "enterprise"]
+CATEGORIES = ["Electronics", "Furniture", "Clothing", "Food", "Tools"]
+
+
+def _generate_sales_row(
+    rng: Random, row_idx: int, base_date: datetime
+) -> dict[str, Any]:
+    """Generate a single sales row."""
+    date = base_date + timedelta(days=rng.randint(0, 365))
+    product = rng.choice(PRODUCTS)
+    quantity = rng.randint(1, 100)
+    unit_price = rng.uniform(10.0, 500.0)
+    revenue = round(quantity * unit_price, 2)
+    region = rng.choice(REGIONS)
+
+    return {
+        "date": date.strftime("%Y-%m-%d"),
+        "product": product,
+        "quantity": quantity,
+        "revenue": revenue,
+        "region": region,
+    }
+
+
+def _generate_users_row(
+    rng: Random, row_idx: int, base_date: datetime
+) -> dict[str, Any]:
+    """Generate a single user row."""
+    signup_date = base_date + timedelta(days=rng.randint(0, 730))
+    age = rng.randint(18, 75)
+    subscription = rng.choice(SUBSCRIPTION_TYPES)
+    activity = round(rng.uniform(0.0, 100.0), 1)
+
+    return {
+        "user_id": f"USR-{1000 + row_idx:05d}",
+        "signup_date": signup_date.strftime("%Y-%m-%d"),
+        "age": age,
+        "subscription_type": subscription,
+        "activity_score": activity,
+    }
+
+
+def _generate_inventory_row(
+    rng: Random, row_idx: int, base_date: datetime
+) -> dict[str, Any]:
+    """Generate a single inventory row."""
+    stock = rng.randint(0, 1000)
+    reorder = rng.randint(10, 200)
+    cost = round(rng.uniform(1.0, 100.0), 2)
+
+    return {
+        "product_id": f"PROD-{row_idx + 1:04d}",
+        "category": rng.choice(CATEGORIES),
+        "stock_level": stock,
+        "reorder_point": reorder,
+        "unit_cost": cost,
+    }
+
+
+def _generate_weather_row(
+    rng: Random, row_idx: int, base_date: datetime
+) -> dict[str, Any]:
+    """Generate a single weather row."""
+    date = base_date + timedelta(days=row_idx)
+    # Temperature varies seasonally
+    day_of_year = (date - datetime(date.year, 1, 1, tzinfo=UTC)).days
+    seasonal_factor = abs(day_of_year - 182) / 182  # 0 at mid-year, 1 at ends
+    base_temp = 20 - (seasonal_factor * 15)  # Warmer in summer
+    temp = round(base_temp + rng.uniform(-10, 10), 1)
+
+    return {
+        "date": date.strftime("%Y-%m-%d"),
+        "temperature": temp,
+        "humidity": rng.randint(20, 95),
+        "precipitation": round(rng.uniform(0, 50) if rng.random() < 0.3 else 0, 1),
+        "wind_speed": round(rng.uniform(0, 40), 1),
+    }
+
+
+GENERATORS = {
+    "sales": _generate_sales_row,
+    "users": _generate_users_row,
+    "inventory": _generate_inventory_row,
+    "weather": _generate_weather_row,
+}
+
+
+GENERATE_SAMPLE_DATA_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "dataset": {
+            "type": "string",
+            "enum": ["sales", "users", "inventory", "weather"],
+            "description": "The type of sample dataset to generate",
+        },
+        "rows": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "description": "Number of rows to generate (default: 50, max: 1000)",
+        },
+    },
+    "required": ["dataset"],
+}
+
+
+@action(
+    name="generate_sample_data",
+    description="Generate sample data for testing and demonstration purposes.",
+    parameters=GENERATE_SAMPLE_DATA_PARAMETERS,
+)
+async def generate_sample_data(args: dict[str, Any]) -> str:
+    """Generate sample data for a specified dataset type."""
+    try:
+        dataset = args["dataset"]
+        rows = args.get("rows", 50)
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if dataset not in DATASET_GENERATORS:
+        return json.dumps(
+            {
+                "error": f"Unknown dataset: {dataset}",
+                "available_datasets": list(DATASET_GENERATORS.keys()),
+            }
+        )
+
+    if rows < 1 or rows > 1000:
+        return json.dumps({"error": "Rows must be between 1 and 1000"})
+
+    # Generate deterministic data based on dataset name and current day
+    today = datetime.now(UTC)
+    seed = hash(dataset + today.strftime("%Y-%m-%d"))
+    rng = Random(seed)
+
+    base_date = datetime(today.year - 1, 1, 1, tzinfo=UTC)
+    generator = GENERATORS[dataset]
+
+    data = []
+    for i in range(rows):
+        row = generator(rng, i, base_date)
+        data.append(row)
+
+    return json.dumps(
+        {
+            "dataset": dataset,
+            "description": DATASET_GENERATORS[dataset]["description"],
+            "columns": DATASET_GENERATORS[dataset]["columns"],
+            "row_count": len(data),
+            "data": data,
+        }
+    )
+
+
+PARSE_CSV_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "data": {
+            "type": "string",
+            "description": "The CSV data as a string (with headers in first row)",
+        },
+    },
+    "required": ["data"],
+}
+
+
+@action(
+    name="parse_csv",
+    description="Parse CSV data string into structured JSON format.",
+    parameters=PARSE_CSV_PARAMETERS,
+)
+async def parse_csv(args: dict[str, Any]) -> str:
+    """Parse CSV data into structured JSON."""
+    try:
+        csv_data = args["data"]
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not csv_data.strip():
+        return json.dumps({"error": "CSV data cannot be empty"})
+
+    try:
+        reader = csv.DictReader(io.StringIO(csv_data))
+        columns = reader.fieldnames
+
+        if not columns:
+            return json.dumps({"error": "No header row found in CSV"})
+
+        data = []
+        errors: list[str] = []
+        for i, row in enumerate(reader):
+            # Try to convert numeric values
+            parsed_row: dict[str, Any] = {}
+            for col, val in row.items():
+                if val is None or val == "":
+                    parsed_row[col] = None  # type: ignore
+                else:
+                    # Try to parse as number
+                    try:
+                        if "." in val:
+                            parsed_row[col] = float(val)
+                        else:
+                            parsed_row[col] = int(val)
+                    except ValueError:
+                        parsed_row[col] = val
+
+            data.append(parsed_row)
+
+        # Detect column types
+        column_types = {}
+        for col in columns:
+            types_seen = set()
+            for row in data[:100]:  # Sample first 100 rows
+                val = row.get(col)
+                if val is None:
+                    continue
+                types_seen.add(type(val).__name__)
+
+            if types_seen == {"int"}:
+                column_types[col] = "integer"
+            elif types_seen <= {"int", "float"}:
+                column_types[col] = "numeric"
+            else:
+                column_types[col] = "string"
+
+        return json.dumps(
+            {
+                "success": True,
+                "columns": list(columns),
+                "column_types": column_types,
+                "row_count": len(data),
+                "data": data,
+                "parse_errors": errors if errors else None,
+            }
+        )
+
+    except csv.Error as e:
+        return json.dumps({"error": f"CSV parsing error: {str(e)}"})

mail/examples/data_analysis/processor/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Processor agent for the Data Analysis swarm."""
+
+from collections.abc import Awaitable
+from typing import Any, Literal
+
+from mail.core.agents import AgentOutput
+from mail.factories.action import LiteLLMActionAgentFunction
+
+
+class LiteLLMProcessorFunction(LiteLLMActionAgentFunction):
+    """
+    Data processor agent that handles data generation and parsing.
+
+    This agent generates sample datasets and parses CSV data
+    for use in analysis workflows.
+    """
+
+    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 processor agent function."""
+        return super().__call__(messages, tool_choice)

mail/examples/data_analysis/processor/prompts.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+SYSPROMPT = """You are processor@{swarm}, the data processing specialist for this data analysis swarm.
+
+# Your Role
+Handle data generation, parsing, cleaning, and transformation to prepare data for analysis.
+
+# 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 "analyst")
+- After processing data, call `send_response(target=<sender>, subject="Re: ...", body=<your data/results>)`
+- Include the FULL processed data in your response body
+
+# Tools
+
+## Data Operations
+- `generate_sample_data(dataset, rows)`: Generate sample data for testing/demo
+- `parse_csv(data)`: Parse CSV string into structured data
+
+## 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
+
+# Available Datasets
+
+- **sales**: Sales data with columns: date, product, quantity, revenue, region
+- **users**: User data with columns: user_id, signup_date, age, subscription_type, activity_score
+- **inventory**: Inventory data with columns: product_id, category, stock_level, reorder_point, unit_cost
+- **weather**: Weather data with columns: date, temperature, humidity, precipitation, wind_speed
+
+# Workflow
+
+1. Receive request from another agent (note the sender)
+2. Determine what data operation is needed:
+   - Generate sample data if no data provided
+   - Parse CSV data if raw data is provided
+3. Execute the appropriate action
+4. Call `send_response` to the original sender with the processed data
+
+# Guidelines
+
+- Return data in a format ready for analysis (JSON structure)
+- Include metadata about the data (row count, columns, types)
+- Report any data quality issues found during parsing
+- Use "Re: <original subject>" as your response subject"""

mail/examples/data_analysis/reporter/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Reporter agent for the Data Analysis swarm."""
+
+from mail.examples.data_analysis.reporter.agent import LiteLLMReporterFunction
+from mail.examples.data_analysis.reporter.actions import format_report
+from mail.examples.data_analysis.reporter.prompts import SYSPROMPT
+
+__all__ = ["LiteLLMReporterFunction", "format_report", "SYSPROMPT"]

mail/examples/data_analysis/reporter/actions.py

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Report formatting action for the Data Analysis swarm."""
+
+import json
+from datetime import datetime, UTC
+from typing import Any
+
+from mail import action
+
+
+def _format_table(data: list[dict[str, Any]], columns: list[str] | None = None) -> str:
+    """Format data as a markdown table."""
+    if not data:
+        return "_No data available_"
+
+    # Determine columns
+    if columns is None:
+        columns = list(data[0].keys())
+
+    # Build header
+    header = "| " + " | ".join(str(col) for col in columns) + " |"
+    separator = "| " + " | ".join("---" for _ in columns) + " |"
+
+    # Build rows
+    rows = []
+    for row in data[:50]:  # Limit to 50 rows
+        row_values = []
+        for col in columns:
+            val = row.get(col, "")
+            if isinstance(val, float):
+                row_values.append(f"{val:.4f}")
+            else:
+                row_values.append(str(val))
+        rows.append("| " + " | ".join(row_values) + " |")
+
+    table = "\n".join([header, separator] + rows)
+
+    if len(data) > 50:
+        table += f"\n\n_...and {len(data) - 50} more rows_"
+
+    return table
+
+
+def _format_statistics_table(metrics: dict[str, Any]) -> str:
+    """Format statistics metrics as a table."""
+    if not metrics:
+        return "_No statistics available_"
+
+    rows = ["| Metric | Value |", "| --- | --- |"]
+    for metric, value in metrics.items():
+        if isinstance(value, dict):
+            if "error" in value:
+                rows.append(f"| {metric} | Error: {value['error']} |")
+            else:
+                rows.append(f"| {metric} | {json.dumps(value)} |")
+        elif isinstance(value, float):
+            rows.append(f"| {metric} | {value:.4f} |")
+        else:
+            rows.append(f"| {metric} | {value} |")
+
+    return "\n".join(rows)
+
+
+def _format_section(section_type: str, content: Any) -> str:
+    """Format a single section based on its type."""
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, dict):
+        if "table" in content:
+            return _format_table(content["table"], content.get("columns"))
+        if "metrics" in content:
+            return _format_statistics_table(content["metrics"])
+        if "text" in content:
+            return content["text"]
+        # Generic dict formatting
+        return "\n".join(f"- **{k}**: {v}" for k, v in content.items())
+
+    if isinstance(content, list):
+        if all(isinstance(item, dict) for item in content):
+            return _format_table(content)
+        return "\n".join(f"- {item}" for item in content)
+
+    return str(content)
+
+
+FORMAT_REPORT_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "title": {
+            "type": "string",
+            "description": "The report title",
+        },
+        "sections": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "heading": {
+                        "type": "string",
+                        "description": "Section heading",
+                    },
+                    "content": {
+                        "description": "Section content (string, object, or array)",
+                    },
+                },
+                "required": ["heading", "content"],
+            },
+            "description": "Array of report sections with heading and content",
+        },
+    },
+    "required": ["title", "sections"],
+}
+
+
+@action(
+    name="format_report",
+    description="Generate a formatted markdown report with sections, tables, and summaries.",
+    parameters=FORMAT_REPORT_PARAMETERS,
+)
+async def format_report(args: dict[str, Any]) -> str:
+    """Format data into a structured markdown report."""
+    try:
+        title = args["title"]
+        sections = args["sections"]
+    except KeyError as e:
+        return f"Error: {e} is required"
+
+    if not title.strip():
+        return json.dumps({"error": "Report title cannot be empty"})
+
+    if not sections:
+        return json.dumps({"error": "Report must have at least one section"})
+
+    # Build report
+    report_parts = []
+
+    # Title and metadata
+    report_parts.append(f"# {title}")
+    report_parts.append("")
+    report_parts.append(
+        f"_Generated: {datetime.now(UTC).strftime('%Y-%m-%d %H:%M:%S UTC')}_"
+    )
+    report_parts.append("")
+    report_parts.append("---")
+    report_parts.append("")
+
+    # Table of contents (if more than 2 sections)
+    if len(sections) > 2:
+        report_parts.append("## Table of Contents")
+        report_parts.append("")
+        for i, section in enumerate(sections, 1):
+            heading = section.get("heading", f"Section {i}")
+            anchor = heading.lower().replace(" ", "-").replace(":", "")
+            report_parts.append(f"{i}. [{heading}](#{anchor})")
+        report_parts.append("")
+        report_parts.append("---")
+        report_parts.append("")
+
+    # Sections
+    for section in sections:
+        heading = section.get("heading", "Untitled Section")
+        content = section.get("content", "")
+
+        report_parts.append(f"## {heading}")
+        report_parts.append("")
+        report_parts.append(_format_section(heading.lower(), content))
+        report_parts.append("")
+
+    # Footer
+    report_parts.append("---")
+    report_parts.append("")
+    report_parts.append("_End of Report_")
+
+    report_text = "\n".join(report_parts)
+
+    return json.dumps(
+        {
+            "success": True,
+            "title": title,
+            "section_count": len(sections),
+            "character_count": len(report_text),
+            "report": report_text,
+        }
+    )

mail/examples/data_analysis/reporter/agent.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Charon Labs
+
+"""Reporter agent for the Data Analysis swarm."""
+
+from collections.abc import Awaitable
+from typing import Any, Literal
+
+from mail.core.agents import AgentOutput
+from mail.factories.action import LiteLLMActionAgentFunction
+
+
+class LiteLLMReporterFunction(LiteLLMActionAgentFunction):
+    """
+    Reporter agent that formats analysis results into reports.
+
+    This agent takes analysis data and formats it into clear,
+    professional markdown reports.
+    """
+
+    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 reporter agent function."""
+        return super().__call__(messages, tool_choice)