ai-parrot 0.17.2__cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

parrot/tools/arxiv_tool.py

@@ -0,0 +1,188 @@
+"""
+ArxivTool - Search and retrieve papers from arXiv.org
+"""
+from typing import List, Dict, Any, Type
+from pydantic import BaseModel, Field
+from parrot.tools.abstract import AbstractTool, AbstractToolArgsSchema
+try:
+    import arxiv
+except ImportError:
+    arxiv = None
+
+
+class ArxivSearchArgsSchema(AbstractToolArgsSchema):
+    """Schema for arXiv search arguments."""
+    query: str = Field(
+        description="Search query for arXiv papers. Can include keywords, author names, or arXiv categories."
+    )
+    max_results: int = Field(
+        default=5,
+        description="Maximum number of results to return (default: 5, max: 100)",
+        ge=1,
+        le=100
+    )
+    sort_by: str = Field(
+        default="relevance",
+        description="Sort order: 'relevance', 'lastUpdatedDate', or 'submittedDate'",
+        pattern="^(relevance|lastUpdatedDate|submittedDate)$"
+    )
+    sort_order: str = Field(
+        default="descending",
+        description="Sort direction: 'ascending' or 'descending'",
+        pattern="^(ascending|descending)$"
+    )
+
+
+class ArxivTool(AbstractTool):
+    """
+    Tool for searching academic papers on arXiv.org.
+
+    This tool allows searching for papers by keywords, authors, categories, or any combination.
+    Returns comprehensive paper information including:
+    - Title
+    - Authors
+    - Publication date
+    - Abstract/Summary
+    - ArXiv ID
+    - PDF URL
+    - Categories
+
+    Example queries:
+    - "machine learning transformers"
+    - "quantum computing"
+    - "au:LeCun" (search by author)
+    - "cat:cs.AI" (search by category)
+
+    See https://info.arxiv.org/help/api/user-manual.html for advanced query syntax.
+    """
+
+    name: str = "arxiv_search"
+    description: str = (
+        "Search for academic papers on arXiv.org. "
+        "Supports keyword search, author search, and category filtering. "
+        "Returns paper title, authors, publication date, summary, and links."
+    )
+    args_schema: Type[BaseModel] = ArxivSearchArgsSchema
+    return_direct: bool = False
+
+    def __init__(self, **kwargs):
+        """Initialize the arXiv tool."""
+        super().__init__(**kwargs)
+
+        if arxiv is None:
+            raise ImportError(
+                "The 'arxiv' package is required for ArxivTool. "
+                "Install it with: pip install arxiv"
+            )
+
+    def _format_authors(self, authors: List[arxiv.Result.Author]) -> List[str]:
+        """Format author list from arXiv result."""
+        return [author.name for author in authors]
+
+    def _format_paper(self, paper: arxiv.Result) -> Dict[str, Any]:
+        """
+        Format a single arXiv paper result into a structured dictionary.
+
+        Args:
+            paper: arXiv Result object
+
+        Returns:
+            Dictionary with paper information
+        """
+        return {
+            "title": paper.title,
+            "authors": self._format_authors(paper.authors),
+            "published": paper.published.strftime("%Y-%m-%d") if paper.published else None,
+            "updated": paper.updated.strftime("%Y-%m-%d") if paper.updated else None,
+            "summary": paper.summary.replace("\n", " ").strip(),
+            "arxiv_id": paper.entry_id.split("/")[-1],
+            "pdf_url": paper.pdf_url,
+            "categories": paper.categories,
+            "primary_category": paper.primary_category,
+            "comment": paper.comment if hasattr(paper, "comment") else None,
+            "journal_ref": paper.journal_ref if hasattr(paper, "journal_ref") else None,
+        }
+
+    async def _execute(
+        self,
+        query: str,
+        max_results: int = 5,
+        sort_by: str = "relevance",
+        sort_order: str = "descending",
+        **kwargs
+    ) -> Any:
+        """
+        Execute arXiv search with given parameters.
+
+        Args:
+            query: Search query string
+            max_results: Maximum number of results to return
+            sort_by: Sort criterion (relevance, lastUpdatedDate, submittedDate)
+            sort_order: Sort direction (ascending, descending)
+            **kwargs: Additional arguments (ignored)
+
+        Returns:
+            List of paper dictionaries with metadata
+        """
+        try:
+            # Map string sort criteria to arxiv.SortCriterion enum
+            sort_criterion_map = {
+                "relevance": arxiv.SortCriterion.Relevance,
+                "lastUpdatedDate": arxiv.SortCriterion.LastUpdatedDate,
+                "submittedDate": arxiv.SortCriterion.SubmittedDate,
+            }
+
+            # Map string sort order to arxiv.SortOrder enum
+            sort_order_map = {
+                "ascending": arxiv.SortOrder.Ascending,
+                "descending": arxiv.SortOrder.Descending,
+            }
+
+            sort_criterion = sort_criterion_map.get(
+                sort_by, arxiv.SortCriterion.Relevance
+            )
+            sort_direction = sort_order_map.get(
+                sort_order, arxiv.SortOrder.Descending
+            )
+
+            # Create search client
+            client = arxiv.Client()
+
+            # Create search query
+            search = arxiv.Search(
+                query=query,
+                max_results=max_results,
+                sort_by=sort_criterion,
+                sort_order=sort_direction
+            )
+
+            # Execute search and collect results
+            papers = []
+            papers.extend(
+                self._format_paper(paper) for paper in client.results(search)
+            )
+
+            if not papers:
+                self.logger.warning(f"No results found for query: {query}")
+                return {
+                    "query": query,
+                    "count": 0,
+                    "papers": [],
+                    "message": "No papers found matching your query."
+                }
+
+            self.logger.info(
+                f"Found {len(papers)} papers for query: '{query}'"
+            )
+
+            return {
+                "query": query,
+                "count": len(papers),
+                "papers": papers,
+                "message": f"Found {len(papers)} paper(s)"
+            }
+
+        except Exception as e:
+            error_msg = f"Error searching arXiv: {str(e)}"
+            self.logger.error(error_msg)
+            raise ValueError(error_msg) from e

parrot/tools/calculator/__init__.py

@@ -0,0 +1,3 @@
+from .tool import CalculatorTool
+
+__all__ = ["CalculatorTool"]

parrot/tools/calculator/operations/__init__.py

@@ -0,0 +1,38 @@
+# calculator/operations/__init__.py
+"""
+Calculator operations module.
+
+Each operation should be a function that:
+1. Has clear type hints
+2. Includes a docstring
+3. Is decorated with @operation (optional, for metadata)
+"""
+
+from functools import wraps
+from typing import Callable
+
+
+def operation(name: str = None, description: str = None):
+    """
+    Decorator to mark a function as a calculator operation.
+
+    Args:
+        name: Operation name (defaults to function name)
+        description: Operation description (defaults to docstring)
+    """
+    def decorator(func: Callable) -> Callable:
+        func._is_operation = True
+        func._operation_name = name or func.__name__
+        func._operation_description = description or func.__doc__
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Preserve operation metadata
+        wrapper._is_operation = True
+        wrapper._operation_name = func._operation_name
+        wrapper._operation_description = func._operation_description
+
+        return wrapper
+    return decorator

parrot/tools/calculator/operations/calculus.py

@@ -0,0 +1,80 @@
+# calculator/operations/calculus.py
+"""Calculus operations."""
+from typing import Callable, List
+from . import operation
+
+
+@operation(name="derivative")
+def numerical_derivative(
+    expression: str = None,
+    x: float = None,
+    h: float = 1e-5,
+    **kwargs
+) -> float:
+    """
+    Calculate numerical derivative using central difference.
+
+    Args:
+        expression: Python expression as string (e.g., "x**2 + 3*x")
+        x: Point at which to evaluate derivative
+        h: Step size for numerical differentiation
+    """
+    if expression is None or x is None:
+        raise ValueError("Need both expression and x value")
+
+    # Compile expression for evaluation
+    # This uses Python's eval - in production, consider safer alternatives
+    import numpy as np
+
+    def f(val):
+        # Make common functions available
+        from math import sin, cos, tan, exp, log, sqrt, pi, e
+        return eval(expression, {"x": val, "np": np, "__builtins__": {}},
+                   {"sin": sin, "cos": cos, "tan": tan, "exp": exp,
+                    "log": log, "sqrt": sqrt, "pi": pi, "e": e})
+
+    # Central difference: f'(x) ≈ (f(x+h) - f(x-h)) / (2h)
+    return (f(x + h) - f(x - h)) / (2 * h)
+
+
+@operation(name="integrate")
+def numerical_integral(
+    expression: str = None,
+    a: float = None,
+    b: float = None,
+    n: int = 1000,
+    **kwargs
+) -> float:
+    """
+    Calculate numerical integral using Simpson's rule.
+
+    Args:
+        expression: Python expression as string
+        a: Lower bound
+        b: Upper bound
+        n: Number of intervals (must be even)
+    """
+    if any(v is None for v in [expression, a, b]):
+        raise ValueError("Need expression, a, and b")
+
+    if n % 2 != 0:
+        n += 1
+
+    from math import sin, cos, tan, exp, log, sqrt, pi, e
+
+    def f(val):
+        return eval(expression, {"x": val, "__builtins__": {}},
+                   {"sin": sin, "cos": cos, "tan": tan, "exp": exp,
+                    "log": log, "sqrt": sqrt, "pi": pi, "e": e})
+
+    h = (b - a) / n
+    result = f(a) + f(b)
+
+    for i in range(1, n):
+        x = a + i * h
+        if i % 2 == 0:
+            result += 2 * f(x)
+        else:
+            result += 4 * f(x)
+
+    return result * h / 3

parrot/tools/calculator/operations/statistics.py

@@ -0,0 +1,76 @@
+# calculator/operations/statistics.py
+"""Statistical operations."""
+import math
+from typing import List
+from . import operation
+
+
+@operation(name="mean", description="Calculate arithmetic mean")
+def calculate_mean(values: List[float], **kwargs) -> float:
+    """Calculate the arithmetic mean of a list of values."""
+    if not values:
+        raise ValueError("Cannot calculate mean of empty list")
+    return sum(values) / len(values)
+
+
+@operation(name="std", description="Calculate standard deviation")
+def calculate_std(values: List[float], sample: bool = True, **kwargs) -> float:
+    """
+    Calculate standard deviation.
+
+    Args:
+        values: List of numerical values
+        sample: If True, use sample std (n-1), else population std (n)
+    """
+    if not values:
+        raise ValueError("Cannot calculate std of empty list")
+
+    mean = sum(values) / len(values)
+    variance = sum((x - mean) ** 2 for x in values)
+
+    divisor = len(values) - 1 if sample else len(values)
+    if divisor == 0:
+        raise ValueError("Need at least 2 values for sample standard deviation")
+
+    return math.sqrt(variance / divisor)
+
+
+@operation(name="median")
+def calculate_median(values: List[float], **kwargs) -> float:
+    """Calculate median value."""
+    if not values:
+        raise ValueError("Cannot calculate median of empty list")
+
+    sorted_values = sorted(values)
+    n = len(sorted_values)
+
+    if n % 2 == 0:
+        return (sorted_values[n//2 - 1] + sorted_values[n//2]) / 2
+    else:
+        return sorted_values[n//2]
+
+
+@operation(name="correlation")
+def calculate_correlation(values: List[float], **kwargs) -> float:
+    """
+    Calculate Pearson correlation coefficient.
+    Expects values to be alternating [x1, y1, x2, y2, ...]
+    """
+    if len(values) < 4 or len(values) % 2 != 0:
+        raise ValueError("Need at least 2 pairs of values for correlation")
+
+    x_values = values[::2]
+    y_values = values[1::2]
+
+    n = len(x_values)
+    mean_x = sum(x_values) / n
+    mean_y = sum(y_values) / n
+
+    numerator = sum((x - mean_x) * (y - mean_y) for x, y in zip(x_values, y_values))
+    denominator_x = math.sqrt(sum((x - mean_x) ** 2 for x in x_values))
+    denominator_y = math.sqrt(sum((y - mean_y) ** 2 for y in y_values))
+
+    if denominator_x == 0 or denominator_y == 0:
+        raise ValueError("Standard deviation is zero, cannot calculate correlation")
+
+    return numerator / (denominator_x * denominator_y)

parrot/tools/calculator/tool.py

@@ -0,0 +1,150 @@
+# calculator/tool.py
+from typing import Dict, Any, Optional, List, Callable
+from pathlib import Path
+from pydantic import BaseModel, Field
+from parrot.tools.abstract import AbstractTool, ToolResult
+import importlib
+import inspect
+
+
+class CalculatorArgs(BaseModel):
+    """Arguments for calculator operations."""
+    operation: str = Field(
+        description="Operation to perform (e.g., 'mean', 'std', 'correlation', 'derivative')"
+    )
+    values: Optional[List[float]] = Field(
+        default=None,
+        description="List of numerical values for statistical operations"
+    )
+    x: Optional[float] = Field(default=None, description="First operand or x value")
+    y: Optional[float] = Field(default=None, description="Second operand or y value")
+    expression: Optional[str] = Field(
+        default=None,
+        description="Mathematical expression for evaluation"
+    )
+    params: Optional[Dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Additional parameters for specific operations"
+    )
+
+
+class CalculatorTool(AbstractTool):
+    """
+    Advanced calculator tool with dynamically loaded operations.
+
+    Supports mathematical, statistical, and scientific computations
+    by loading operation functions from the operations/ folder.
+    """
+
+    name = "CalculatorTool"
+    description = (
+        "Advanced calculator supporting mathematical, statistical, and scientific operations. "
+        "Available operations are dynamically loaded from operation modules."
+    )
+    args_schema = CalculatorArgs
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.operations: Dict[str, Callable] = {}
+        self._load_operations()
+
+    def _load_operations(self):
+        """Dynamically load all operations from the operations/ folder."""
+        operations_dir = Path(__file__).parent / "operations"
+
+        if not operations_dir.exists():
+            self.logger.warning(f"Operations directory not found: {operations_dir}")
+            return
+
+        # Discover all Python files in operations/
+        for py_file in operations_dir.glob("*.py"):
+            if py_file.name.startswith("_"):
+                continue
+
+            module_name = f"parrot.tools.calculator.operations.{py_file.stem}"
+
+            try:
+                module = importlib.import_module(module_name)
+
+                # Load all functions marked with @operation decorator
+                # or all public functions
+                for name, obj in inspect.getmembers(module, inspect.isfunction):
+                    if not name.startswith("_"):
+                        # Check if function has operation metadata
+                        if hasattr(obj, "_is_operation"):
+                            operation_name = obj._operation_name or name
+                            self.operations[operation_name] = obj
+                            self.logger.debug(
+                                f"Loaded operation: {operation_name} from {py_file.name}"
+                            )
+
+            except Exception as e:
+                self.logger.error(f"Failed to load operations from {py_file}: {e}")
+
+    async def _execute(
+        self,
+        operation: str,
+        values: Optional[List[float]] = None,
+        x: Optional[float] = None,
+        y: Optional[float] = None,
+        expression: Optional[str] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Execute the requested operation."""
+
+        if operation not in self.operations:
+            available = ", ".join(sorted(self.operations.keys()))
+            return {
+                "status": "error",
+                "error": f"Unknown operation '{operation}'. Available: {available}",
+                "result": None
+            }
+
+        try:
+            func = self.operations[operation]
+
+            # Build kwargs for the operation function
+            op_kwargs = {
+                "values": values,
+                "x": x,
+                "y": y,
+                "expression": expression,
+            }
+
+            if params:
+                op_kwargs.update(params)
+
+            # Filter None values
+            op_kwargs = {k: v for k, v in op_kwargs.items() if v is not None}
+
+            # Execute operation
+            result = await self._call_operation(func, op_kwargs)
+
+            return {
+                "status": "success",
+                "result": result,
+                "operation": operation,
+                "metadata": {
+                    "available_operations": list(self.operations.keys())
+                }
+            }
+
+        except Exception as e:
+            self.logger.error(f"Error executing operation '{operation}': {e}")
+            return {
+                "status": "error",
+                "error": str(e),
+                "result": None
+            }
+
+    async def _call_operation(self, func: Callable, kwargs: Dict[str, Any]) -> Any:
+        """Call operation function (sync or async)."""
+        if inspect.iscoroutinefunction(func):
+            return await func(**kwargs)
+        else:
+            return func(**kwargs)
+
+    def list_operations(self) -> List[str]:
+        """List all available operations."""
+        return sorted(self.operations.keys())