aip-agents-binary 0.0.0b2__py3-none-any.whl → 0.5.12__py3-none-any.whl

aip_agents/examples/tools/random_chart_tool.py

@@ -0,0 +1,142 @@
+"""Tool that generates random bar chart artifacts for streaming demos."""
+
+import io
+import random
+from typing import Any
+
+from langchain_core.tools import BaseTool
+from langgraph.types import Command
+from pydantic import BaseModel, Field
+
+from aip_agents.a2a.types import MimeType
+from aip_agents.utils.artifact_helpers import create_artifact_command
+
+DEFAULT_RANDOM_CHART_TITLE = "Random Insights"
+
+try:
+    from PIL import Image, ImageDraw  # type: ignore
+
+    PIL_AVAILABLE = True
+except ImportError:  # pragma: no cover - PIL optional
+    PIL_AVAILABLE = False
+    Image = None
+    ImageDraw = None
+
+
+class RandomChartInput(BaseModel):
+    """Input schema for random chart generation."""
+
+    title: str = Field(
+        default=DEFAULT_RANDOM_CHART_TITLE,
+        description="Title rendered at the top of the chart.",
+    )
+    num_bars: int = Field(
+        default=5,
+        ge=3,
+        le=10,
+        description="How many bars to render.",
+    )
+    min_value: int = Field(
+        default=10,
+        ge=0,
+        description="Minimum possible value for a bar.",
+    )
+    max_value: int = Field(
+        default=100,
+        gt=10,
+        description="Maximum possible value for a bar.",
+    )
+
+
+class RandomChartTool(BaseTool):
+    """Generate random bar chart images without relying on upstream data."""
+
+    name: str = "random_chart_tool"
+    description: str = "Create a random bar chart image artifact to showcase image streaming."
+    args_schema: type[BaseModel] = RandomChartInput
+
+    def _run(  # noqa: D401
+        self,
+        title: str = DEFAULT_RANDOM_CHART_TITLE,
+        num_bars: int = 5,
+        min_value: int = 10,
+        max_value: int = 100,
+        **kwargs: Any,
+    ) -> Command:
+        """Generate the chart synchronously."""
+        if min_value >= max_value:
+            return Command(
+                update={"result": "❌ min_value must be less than max_value", "metadata": {"error": "invalid_range"}}
+            )
+
+        rng = random.Random()
+        values = [rng.randint(min_value, max_value) for _ in range(num_bars)]
+        labels = [f"Bar {i + 1}" for i in range(num_bars)]
+
+        if PIL_AVAILABLE:
+            image_bytes = self._create_image_with_pil(title, labels, values)
+        else:
+            image_bytes = self._create_text_artifact(title, labels, values)
+
+        artifact_mime_type = MimeType.IMAGE_PNG if PIL_AVAILABLE else MimeType.TEXT_PLAIN
+        return create_artifact_command(
+            result=f"📊 Generated random bar chart '{title}' with {num_bars} bars",
+            artifact_data=image_bytes,
+            artifact_name=f"{title.lower().replace(' ', '_')}_random_chart.png",
+            artifact_description=f"Random bar chart ({num_bars} bars)",
+            mime_type=artifact_mime_type,
+            metadata_update={
+                "visualization": {
+                    "chart_type": "bar",
+                    "title": title,
+                    "data_points": num_bars,
+                    "randomized": True,
+                }
+            },
+        )
+
+    async def _arun(
+        self,
+        title: str = DEFAULT_RANDOM_CHART_TITLE,
+        num_bars: int = 5,
+        min_value: int = 10,
+        max_value: int = 100,
+        **kwargs: Any,
+    ) -> Command:
+        """Async wrapper for random chart generation."""
+        return self._run(title=title, num_bars=num_bars, min_value=min_value, max_value=max_value, **kwargs)
+
+    def _create_image_with_pil(self, title: str, labels: list[str], values: list[int]) -> bytes:
+        width, height = 400, 300
+        image = Image.new("RGB", (width, height), "white")
+        draw = ImageDraw.Draw(image)
+        draw.text((10, 10), title[:40], fill="black")
+
+        chart_x, chart_y = 40, 50
+        chart_width = width - 80
+        chart_height = height - 100
+
+        max_val = max(values)
+        min_val = min(values)
+        val_range = max_val - min_val if max_val != min_val else 1
+        bar_width = chart_width // len(values)
+
+        for idx, (label, value) in enumerate(zip(labels, values, strict=False)):
+            x = chart_x + idx * bar_width
+            normalized = (value - min_val) / val_range
+            y = chart_y + chart_height - (normalized * chart_height)
+
+            draw.rectangle([x + 2, y, x + bar_width - 4, chart_y + chart_height], fill="#4C78A8", outline="black")
+            draw.text((x + 2, chart_y + chart_height + 5), label[:8], fill="black")
+
+        buf = io.BytesIO()
+        image.save(buf, format="PNG")
+        return buf.getvalue()
+
+    def _create_text_artifact(self, title: str, labels: list[str], values: list[int]) -> bytes:
+        max_val = max(values)
+        lines = [f"=== {title} ===", "", "Random bar chart artifact", ""]
+        for label, value in zip(labels, values, strict=False):
+            length = int((value / max_val) * 30) if max_val else 0
+            lines.append(f"{label:>8}: {'█' * length} ({value})")
+        return "\n".join(lines).encode("utf-8")

aip_agents/examples/tools/serper_tool.py

@@ -0,0 +1,202 @@
+"""Tool to search Google Serper API.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+import json
+import logging
+from typing import Any
+
+from gllm_core.schema import Chunk
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class GoogleSerperInput(BaseModel):
+    """Input schema for the GoogleSerperTool."""
+
+    query: str = Field(..., description="Search query")
+
+
+class MockGoogleSerperTool(BaseTool):
+    """Mock Tool to simulate Google Serper API results for testing."""
+
+    name: str = "google_serper"
+    description: str = """
+    Useful for searching the web using the Google Serper API (mocked).
+    Input should be a search query.
+    """
+    save_output_history: bool = True
+    args_schema: type[BaseModel] = GoogleSerperInput
+
+    def _run(self, query: str) -> str:
+        """Return a hardcoded mock response as a JSON string.
+
+        Args:
+            query (str): The search query to process.
+
+        Returns:
+            str: JSON string containing mock search results.
+        """
+        normalized_query = query.lower()
+
+        # Special-case oncology AI drug discovery queries so the agent
+        # naturally sees stock-oriented company context and can call
+        # stock tools (get_stock_price, get_stock_news) afterwards.
+        if "oncology" in normalized_query or "drug discovery" in normalized_query:
+            mock_result = {
+                "organic": [
+                    {
+                        "title": "NVIDIA (NVDA) - AI infrastructure for healthcare and drug discovery",
+                        "link": "https://nvidia.example.com/healthcare-ai",
+                        "snippet": (
+                            "NVIDIA (ticker: NVDA) provides GPU-accelerated platforms widely used in AI-driven "
+                            "drug discovery and oncology research. Investors closely watch NVDA stock as demand "
+                            "for healthcare and life-sciences AI workloads grows."
+                        ),
+                    },
+                    {
+                        "title": "Microsoft (MSFT) - Azure AI partnerships with pharma and oncology",
+                        "link": "https://microsoft.example.com/azure-health",
+                        "snippet": (
+                            "Microsoft (MSFT) collaborates with leading pharma companies to apply Azure AI to "
+                            "oncology and drug discovery workflows. Analysts frequently reference MSFT stock when "
+                            "discussing enterprise AI in healthcare."
+                        ),
+                    },
+                    {
+                        "title": "Apple (AAPL) - Devices and AI ecosystems in digital health",
+                        "link": "https://apple.example.com/health-ai",
+                        "snippet": (
+                            "Apple (AAPL) integrates AI into health and wellness features that support oncology "
+                            "patients and clinical research. Market commentary often links AAPL stock to long-term "
+                            "growth in digital health and AI."
+                        ),
+                    },
+                ],
+                "news": [
+                    {
+                        "title": "NVDA rallies on new healthcare AI partnerships",
+                        "link": "https://news.example.com/nvda-oncology-ai",
+                        "snippet": (
+                            "NVIDIA (NVDA) announced expanded collaborations focused on oncology and AI-driven "
+                            "drug discovery, prompting renewed interest in NVDA stock among growth investors."
+                        ),
+                    },
+                    {
+                        "title": "MSFT deepens AI oncology collaborations on Azure",
+                        "link": "https://news.example.com/msft-azure-oncology",
+                        "snippet": (
+                            "Microsoft (MSFT) reported new Azure AI partnerships with oncology research centers, "
+                            "and analysts highlighted MSFT stock as a key AI infrastructure play in healthcare."
+                        ),
+                    },
+                    {
+                        "title": "AAPL explores AI-enabled health insights for cancer care",
+                        "link": "https://news.example.com/aapl-health-oncology",
+                        "snippet": (
+                            "Apple (AAPL) is reportedly piloting AI-enabled health features that could support "
+                            "oncology patient monitoring, adding another angle to the long-term AAPL stock story."
+                        ),
+                    },
+                ],
+            }
+        else:
+            # Default mock result used for generic queries.
+            mock_result = {
+                "organic": [
+                    {
+                        "title": "NeoAI - Artificial Intelligence Research",
+                        "link": "https://neoai.example.com/",
+                        "snippet": (
+                            "NeoAI is an AI research and deployment company. Our mission is to ensure that "
+                            "artificial general intelligence benefits all of humanity."
+                        ),
+                    },
+                    {
+                        "title": "Wikipedia - NeoAI",
+                        "link": "https://en.wikipedia.org/wiki/NeoAI",
+                        "snippet": (
+                            "NeoAI is a fictional artificial intelligence research organization consisting of the "
+                            "for-profit NeoAI LP and its parent company, the non-profit NeoAI Foundation."
+                        ),
+                    },
+                ],
+                "news": [
+                    {
+                        "title": "NeoAI unveils new LLM model",
+                        "link": "https://news.example.com/neoai-llm",
+                        "snippet": (
+                            "NeoAI has announced the release of NeoAI-LLM, a new large multimodal model that accepts "
+                            "image and text inputs."
+                        ),
+                    }
+                ],
+            }
+
+        return json.dumps(mock_result)
+
+    def _format_agent_reference(self, tool_output: str) -> list[Chunk]:
+        parsed_output = self._parse_tool_output(tool_output)
+        if not parsed_output:
+            return []
+        formatted_chunks = []
+        file_id_counter = 0
+        for section_name, section_data in parsed_output.items():
+            if not isinstance(section_data, list):
+                continue
+            results = self._process_section_items(section_name, section_data, file_id_counter)
+            formatted_chunks.extend(results["chunks"])
+            file_id_counter = results["counter"]
+        return formatted_chunks
+
+    def _parse_tool_output(self, tool_output: str) -> dict[str, Any]:
+        if isinstance(tool_output, str):
+            try:
+                return json.loads(tool_output)
+            except json.JSONDecodeError:
+                logger.error("Error: Unable to parse tool_output as JSON when formatting agent references.")
+                return {}
+        return tool_output
+
+    def _process_section_items(self, section_name: str, section_data: list[dict], start_counter: int) -> dict[str, Any]:
+        chunks = []
+        counter = start_counter
+        for item in section_data:
+            if not isinstance(item, dict):
+                continue
+            try:
+                chunk = self._create_chunk_from_item(section_name, item, counter)
+                if chunk:
+                    chunks.append(chunk)
+                    counter += 1
+            except Exception as e:
+                logger.error(f"Error processing {section_name} result: {e}")
+        return {"chunks": chunks, "counter": counter}
+
+    def _create_chunk_from_item(self, section_name: str, item: dict[str, Any], file_id: int) -> Chunk | None:
+        link = item.get("link")
+        if not link:
+            logger.warning(f"Skipping item {file_id} from {section_name} result: Missing link")
+            return None
+        content = ""
+        if "snippet" in item:
+            content = item["snippet"]
+        elif "title" in item:
+            content = item["title"]
+        if not content:
+            logger.warning(f"Skipping item {file_id} from {section_name} result: Missing content")
+            return None
+        metadata = {
+            "source": item.get("title", "Untitled Source"),
+            "section_type": section_name,
+            "source_type": "website",
+            "title": item.get("title", "Untitled"),
+            "link": link,
+            "file_id": str(file_id),
+        }
+        return Chunk(content=content, metadata=metadata)

aip_agents/examples/tools/stock_tools.py

@@ -0,0 +1,82 @@
+"""Defines tools for stock market data.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import random
+from typing import Any
+
+from langchain_core.tools import tool
+from pydantic import BaseModel, Field
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class StockPriceInput(BaseModel):
+    """Input for the stock price tool."""
+
+    symbol: str = Field(description="The stock symbol (e.g., AAPL, MSFT) to get the price for.")
+
+
+@tool(args_schema=StockPriceInput)
+def get_stock_price(symbol: str) -> dict[str, Any]:
+    """Get current stock price and performance data for a given symbol.
+
+    Args:
+        symbol (str): The stock symbol (e.g., AAPL, MSFT) to get the price for.
+
+    Returns:
+        dict[str, Any]: Dictionary containing stock price and performance data.
+    """
+    logger.info(f"Getting stock price for {symbol}")
+    # Simulate stock price data
+    price = round(random.uniform(100, 1000), 2)
+    change = round(random.uniform(-10, 10), 2)
+    change_percent = round((change / price) * 100, 2)
+    return {
+        "symbol": symbol.upper(),
+        "price": price,
+        "change": change,
+        "change_percent": change_percent,
+        "currency": "USD",
+    }
+
+
+class StockNewsInput(BaseModel):
+    """Input for the stock news tool."""
+
+    symbol: str = Field(description="The stock symbol (e.g., AAPL, MSFT) to get news for.")
+    days: int = Field(default=7, description="Number of days of news to retrieve.")
+
+
+@tool(args_schema=StockNewsInput)
+def get_stock_news(symbol: str, days: int = 7) -> dict[str, Any]:
+    """Get recent news for a stock for a specified number of days.
+
+    Args:
+        symbol (str): The stock symbol (e.g., AAPL, MSFT) to get news for.
+        days (int, optional): Number of days of news to retrieve. Defaults to 7.
+
+    Returns:
+        dict[str, Any]: Dictionary containing stock news data.
+    """
+    logger.info(f"Getting stock news for {symbol} for the last {days} days")
+    # Simulate news data
+    news_items = [
+        f"{symbol.upper()} announces breakthrough in AI technology",
+        f"Analysts raise price target for {symbol.upper()}",
+        f"{symbol.upper()} reports better than expected earnings",
+        f"New product launch boosts {symbol.upper()} shares",
+        f"{symbol.upper()} partners with a major tech firm",
+        f"Regulatory changes impact {symbol.upper()}'s sector",
+        f"{symbol.upper()} to release new sustainability report",
+    ]
+    return {
+        "symbol": symbol.upper(),
+        "news": random.sample(news_items, min(days, len(news_items))),
+        "days": days,
+    }

aip_agents/examples/tools/table_generator_tool.py

@@ -0,0 +1,167 @@
+"""Table generator tool for demonstrating artifact generation.
+
+This tool generates sample data tables and returns both a markdown representation
+for the agent and a CSV file artifact for the user.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import csv
+import io
+import random
+from typing import Any
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from aip_agents.a2a.types import MimeType
+from aip_agents.utils.artifact_helpers import create_artifact_response
+
+
+class TableGeneratorInput(BaseModel):
+    """Input schema for table generator tool."""
+
+    rows: int = Field(default=5, description="Number of rows to generate", ge=1, le=100)
+    columns: list[str] = Field(default=["Name", "Age", "City"], description="Column names for the table")
+    table_name: str = Field(default="sample_data", description="Name for the generated table")
+
+
+class TableGeneratorTool(BaseTool):
+    """Tool that generates sample data tables with artifact support.
+
+    This tool demonstrates the standardized artifact format by:
+    1. Generating sample data
+    2. Creating a markdown table for the agent's context
+    3. Creating a CSV file artifact for the user
+    """
+
+    name: str = "table_generator"
+    description: str = "Generate sample data tables with specified columns and rows"
+    args_schema: type[BaseModel] = TableGeneratorInput
+
+    def _run(self, rows: int = 5, columns: list[str] = None, table_name: str = "sample_data") -> dict[str, Any]:
+        """Generate a table synchronously.
+
+        Args:
+            rows (int, optional): Number of rows to generate. Defaults to 5.
+            columns (list[str], optional): Column names for the table. Defaults to None.
+            table_name (str, optional): Name for the generated table. Defaults to "sample_data".
+
+        Returns:
+            dict[str, Any]: Response containing artifact data and metadata.
+        """
+        if columns is None:
+            columns = ["Name", "Age", "City"]
+
+        # Generate sample data
+        sample_data = self._generate_sample_data(rows, columns)
+
+        # Create markdown table for agent
+        markdown_table = self._create_markdown_table(sample_data, columns)
+
+        # Create CSV data for artifact
+        csv_data = self._create_csv_data(sample_data, columns)
+        csv_bytes = csv_data.encode("utf-8")
+
+        # Return standardized format using utility function
+        return create_artifact_response(
+            result=f"I have generated a {rows}-row table with columns: {', '.join(columns)}.\n\n{markdown_table}",
+            artifact_data=csv_bytes,
+            artifact_name=f"{table_name}.csv",
+            artifact_description=f"Generated table with {rows} rows and {len(columns)} columns",
+            mime_type=MimeType.TEXT_CSV,
+        )
+
+    async def _arun(self, rows: int = 5, columns: list[str] = None, table_name: str = "sample_data") -> dict[str, Any]:
+        """Generate a table asynchronously.
+
+        Args:
+            rows (int, optional): Number of rows to generate. Defaults to 5.
+            columns (list[str], optional): Column names for the table. Defaults to None.
+            table_name (str, optional): Name for the generated table. Defaults to "sample_data".
+
+        Returns:
+            dict[str, Any]: Response containing artifact data and metadata.
+        """
+        return self._run(rows, columns, table_name)
+
+    def _generate_sample_data(self, rows: int, columns: list[str]) -> list[list[str]]:
+        """Generate sample data based on column names.
+
+        Args:
+            rows (int): Number of rows to generate.
+            columns (list[str]): Column names for the table.
+
+        Returns:
+            list[list[str]]: Generated sample data as list of rows.
+        """
+        data = []
+        for i in range(rows):
+            row = []
+            for col in columns:
+                col_lower = col.lower()
+                if "name" in col_lower:
+                    names = ["Alice", "Bob", "Charlie", "Diana", "Eve", "Frank", "Grace", "Henry"]
+                    row.append(random.choice(names))
+                elif "age" in col_lower:
+                    row.append(str(random.randint(20, 65)))
+                elif "city" in col_lower:
+                    cities = ["New York", "London", "Tokyo", "Paris", "Sydney", "Berlin", "Toronto", "Mumbai"]
+                    row.append(random.choice(cities))
+                elif "email" in col_lower:
+                    domains = ["gmail.com", "yahoo.com", "outlook.com", "company.com"]
+                    username = f"user{i + 1}"
+                    row.append(f"{username}@{random.choice(domains)}")
+                elif "score" in col_lower or "rating" in col_lower:
+                    row.append(str(random.randint(1, 100)))
+                else:
+                    row.append(f"Value{i + 1}")
+            data.append(row)
+        return data
+
+    def _create_markdown_table(self, data: list[list[str]], columns: list[str]) -> str:
+        """Create a markdown table representation.
+
+        Args:
+            data (list[list[str]]): Table data as list of rows.
+            columns (list[str]): Column names for the table.
+
+        Returns:
+            str: Markdown formatted table string.
+        """
+        if not data:
+            return "| No data |\n|---------|"
+
+        # Header
+        header = "| " + " | ".join(columns) + " |"
+        separator = "| " + " | ".join(["---"] * len(columns)) + " |"
+
+        # Rows
+        rows = []
+        for row in data:
+            rows.append("| " + " | ".join(row) + " |")
+
+        return "\n".join([header, separator] + rows)
+
+    def _create_csv_data(self, data: list[list[str]], columns: list[str]) -> str:
+        """Create CSV data string.
+
+        Args:
+            data (list[list[str]]): Table data as list of rows.
+            columns (list[str]): Column names for the table.
+
+        Returns:
+            str: CSV formatted data string.
+        """
+        output = io.StringIO()
+        writer = csv.writer(output)
+
+        # Write header
+        writer.writerow(columns)
+
+        # Write data
+        for row in data:
+            writer.writerow(row)
+
+        return output.getvalue()

aip_agents/examples/tools/time_tool.py

@@ -0,0 +1,82 @@
+"""Tool to get the current time.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from datetime import datetime
+
+from gllm_core.schema import Chunk
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+FORMAT_STRING = "%m/%d/%y %H:%M:%S"
+
+
+class TimeToolInput(BaseModel):
+    """Input schema for the TimeTool."""
+
+    datetime_format: str = Field(
+        default=FORMAT_STRING,
+        description="""
+        Optional datetime format string. Default: '%m/%d/%y %H:%M:%S'
+
+        Common format codes:
+        %Y: Year with century (2024)
+        %m: Month as number (01-12)
+        %d: Day of month (01-31)
+        %A: Full weekday name (Wednesday)
+        %a: Short weekday name (Wed)
+        %H: Hour (00-23)
+        %M: Minute (00-59)
+        %S: Second (00-59)
+        %Z: Timezone name
+        %j: Day of year (001-366)
+        %W: Week number (00-53, Monday first)
+        %U: Week number (00-53, Sunday first)
+        %c: Locale's date and time
+        %x: Locale's date
+        %X: Locale's time
+        """,
+    )
+
+
+class TimeTool(BaseTool):
+    """Tool to get the current time."""
+
+    name: str = "time_tool"
+    description: str = """
+    Useful for getting the current time in a specified format or the default format.
+    Default format: '%m/%d/%y %H:%M:%S' (e.g., '05/15/24 17:30:00')
+    """
+    save_output_history: bool = True
+    args_schema: type[BaseModel] = TimeToolInput
+
+    def _run(self, datetime_format: str = FORMAT_STRING) -> str:
+        """Get the current time formatted as a string.
+
+        Args:
+            datetime_format (str): The format string to use for the datetime output. Defaults to FORMAT_STRING.
+
+        Returns:
+            str: The current time formatted according to the provided format string.
+        """
+        return datetime.now().strftime(datetime_format)
+
+    def _format_agent_reference(self, tool_output: str) -> list[Chunk]:
+        """Format the tool output as a reference chunk for agent use.
+
+        Args:
+            tool_output (str): The output string from the tool execution.
+
+        Returns:
+            list[Chunk]: A list containing a single reference chunk with the tool output and metadata.
+        """
+        return [
+            Chunk(
+                content=tool_output,
+                metadata={
+                    "tool_name": self.name,
+                },
+            )
+        ]