aip-agents-binary 0.5.20__py3-none-any.whl

aip_agents/examples/tools/data_visualization_tool.py

@@ -0,0 +1,312 @@
+"""Tool that creates visualizations from data with automatic output storage.
+
+This tool demonstrates the tool output management system by creating
+visual charts from data (including referenced data from other tools).
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import io
+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
+
+# Optional PIL import for image generation
+try:
+    from PIL import Image, ImageDraw  # type: ignore
+
+    PIL_AVAILABLE = True
+except ImportError:
+    PIL_AVAILABLE = False
+    Image = None
+    ImageDraw = None
+
+
+class ChartInput(BaseModel):
+    """Input schema for chart generation."""
+
+    data_source: Any = Field(
+        description="Data to visualize (can be a reference like $tool_output.xyz)",
+    )
+    chart_type: str = Field(
+        default="bar",
+        description="Type of chart to generate (bar or line).",
+        pattern="^(bar|line)$",
+    )
+    title: str = Field(
+        default="Chart",
+        description="Title for the visualization",
+    )
+
+
+class DataVisualizerTool(BaseTool):
+    """Tool that creates visualizations with automatic output storage."""
+
+    name: str = "data_visualizer"
+    description: str = "Create visual charts from data (supports tool output references)"
+    args_schema: type[BaseModel] = ChartInput
+
+    def _run(
+        self,
+        data_source: Any,
+        chart_type: str = "bar",
+        title: str = "Chart",
+        **kwargs,
+    ) -> Command:
+        """Create a visualization from data.
+
+        Args:
+            data_source: Data to visualize (can be a reference)
+            chart_type: Type of chart (bar or line)
+            title: Chart title
+            **kwargs: Additional arguments including tool output context
+
+        Returns:
+            Command with visualization artifact and metadata
+        """
+        try:
+            # Extract chartable data
+            chart_data = self._extract_chart_data(data_source)
+            if not chart_data:
+                return Command(
+                    update={
+                        "result": f"❌ Cannot create {chart_type} chart: No valid data found",
+                        "metadata": {"error": "No valid data found"},
+                    }
+                )
+
+            # Generate the image
+            image_bytes = self._create_chart_image(chart_data, chart_type, title)
+
+            # Create artifact with proper encoding
+            return create_artifact_command(
+                result=f"✅ Created {chart_type} chart '{title}' with {len(chart_data['values'])} data points",
+                artifact_data=image_bytes,
+                artifact_name=f"{title.lower().replace(' ', '_')}_{chart_type}.png",
+                artifact_description=f"{chart_type.capitalize()} chart: {title}",
+                mime_type=MimeType.IMAGE_PNG,
+                metadata_update={
+                    "visualization": {
+                        "success": True,
+                        "chart_type": chart_type,
+                        "title": title,
+                        "data_points": len(chart_data["values"]),
+                    }
+                },
+            )
+
+        except Exception as e:
+            return Command(
+                update={"result": f"❌ Error creating visualization: {str(e)}", "metadata": {"error": str(e)}}
+            )
+
+    async def _arun(
+        self,
+        data_source: Any,
+        chart_type: str = "bar",
+        title: str = "Chart",
+        **kwargs,
+    ) -> Command:
+        """Async version of _run.
+
+        Args:
+            data_source (Any): Data to visualize (can be a reference).
+            chart_type (str, optional): Type of chart (bar or line). Defaults to "bar".
+            title (str, optional): Chart title. Defaults to "Chart".
+            **kwargs: Additional arguments including tool output context.
+
+        Returns:
+            Command: Command with visualization artifact and metadata.
+        """
+        return self._run(data_source, chart_type, title, **kwargs)
+
+    def _extract_chart_data(self, data_source: Any) -> dict[str, Any]:
+        """Extract chartable data from various formats.
+
+        Args:
+            data_source (Any): Data source to extract chartable data from.
+
+        Returns:
+            dict[str, Any]: Dictionary containing labels and values for charting.
+        """
+        if isinstance(data_source, dict):
+            # Handle dict with values
+            if "values" in data_source:
+                return {
+                    "values": data_source["values"][:10],  # Limit to 10 points
+                    "labels": data_source.get("labels", [f"Point {i + 1}" for i in range(len(data_source["values"]))]),
+                }
+            # Handle dict with numbers
+            numeric_items = [(str(k), float(v)) for k, v in data_source.items() if isinstance(v, int | float)][:10]
+            if numeric_items:
+                return {
+                    "labels": [k for k, v in numeric_items],
+                    "values": [v for k, v in numeric_items],
+                }
+
+        elif isinstance(data_source, list | tuple):
+            # Handle numeric lists
+            if all(isinstance(x, int | float) for x in data_source):
+                return {
+                    "values": data_source[:10],
+                    "labels": [f"Point {i + 1}" for i in range(len(data_source[:10]))],
+                }
+
+        # Fallback for strings - character frequency
+        elif isinstance(data_source, str):
+            char_counts = {}
+            for c in data_source[:100]:  # Limit input size
+                if c.isalnum():
+                    char_counts[c] = char_counts.get(c, 0) + 1
+            if char_counts:
+                items = sorted(char_counts.items(), key=lambda x: x[1], reverse=True)[:10]
+                return {
+                    "labels": [k for k, v in items],
+                    "values": [v for k, v in items],
+                }
+
+        return {}
+
+    def _create_chart_image(
+        self,
+        chart_data: dict[str, Any],
+        chart_type: str,
+        title: str,
+    ) -> bytes:
+        """Create a chart image using PIL.
+
+        Args:
+            chart_data (dict[str, Any]): Data to visualize containing labels and values.
+            chart_type (str): Type of chart to create.
+            title (str): Title for the chart.
+
+        Returns:
+            bytes: Image data as PNG bytes.
+        """
+        if not PIL_AVAILABLE:
+            # Fallback to text representation
+            return self._create_text_chart(chart_data, chart_type, title)
+
+        # Canvas setup
+        width, height = 400, 300
+        image = Image.new("RGB", (width, height), "white")
+        draw = ImageDraw.Draw(image)
+
+        # Draw title
+        draw.text((10, 10), title[:40], fill="black")
+
+        # Chart area
+        chart_x, chart_y = 40, 40
+        chart_width = width - 60
+        chart_height = height - 80
+
+        values = chart_data.get("values", [])
+        labels = chart_data.get("labels", [])
+
+        if not values:
+            draw.text((chart_x, chart_y + 50), "No data to visualize", fill="red")
+            buf = io.BytesIO()
+            image.save(buf, format="PNG")
+            return buf.getvalue()
+
+        # Normalize values
+        max_val = max(values)
+        min_val = min(values)
+        val_range = max_val - min_val if max_val != min_val else 1
+
+        if chart_type == "bar":
+            # Bar chart
+            bar_width = chart_width // len(values)
+            for i, (label, value) in enumerate(zip(labels, values, strict=False)):
+                x = chart_x + i * bar_width
+                normalized_height = ((value - min_val) / val_range) * chart_height
+                y = chart_y + chart_height - normalized_height
+
+                # Draw bar
+                draw.rectangle(
+                    [x + 2, y, x + bar_width - 2, chart_y + chart_height],
+                    fill="#4C78A8",
+                    outline="black",
+                )
+
+                # Draw label
+                label_text = str(label)[:8]
+                draw.text(
+                    (x + 2, chart_y + chart_height + 5),
+                    label_text,
+                    fill="black",
+                )
+
+        else:  # line chart
+            # Calculate points
+            points = []
+            step = chart_width / (len(values) - 1) if len(values) > 1 else chart_width
+            for i, value in enumerate(values):
+                x = chart_x + i * step
+                normalized_height = ((value - min_val) / val_range) * chart_height
+                y = chart_y + chart_height - normalized_height
+                points.append((x, y))
+
+            # Draw lines
+            MIN_POINTS_FOR_LINE = 2
+            if len(points) >= MIN_POINTS_FOR_LINE:
+                draw.line(points, fill="#F58518", width=2)
+
+            # Draw points
+            for x, y in points:
+                draw.ellipse(
+                    [x - 3, y - 3, x + 3, y + 3],
+                    fill="#F58518",
+                    outline="black",
+                )
+
+                # Draw value
+                draw.text((x - 10, y - 15), str(round(values[points.index((x, y))], 1)), fill="black")
+
+        # Save to bytes
+        buf = io.BytesIO()
+        image.save(buf, format="PNG")
+        return buf.getvalue()
+
+    def _create_text_chart(
+        self,
+        chart_data: dict[str, Any],
+        chart_type: str,
+        title: str,
+    ) -> bytes:
+        """Fallback text-based chart when PIL is not available.
+
+        Args:
+            chart_data (dict[str, Any]): Data to visualize containing labels and values.
+            chart_type (str): Type of chart to create.
+            title (str): Title for the chart.
+
+        Returns:
+            bytes: Text chart data encoded as UTF-8 bytes.
+        """
+        values = chart_data.get("values", [])
+        labels = chart_data.get("labels", [])
+
+        lines = [
+            f"=== {title} ===",
+            f"Chart Type: {chart_type}",
+            f"Data Points: {len(values)}",
+            "",
+        ]
+
+        if values:
+            max_val = max(values)
+            for label, value in zip(labels, values, strict=False):
+                bar_length = int((value / max_val) * 20) if max_val > 0 else 0
+                bar = "█" * bar_length
+                lines.append(f"{label[:10]:10} |{bar:20}| {value}")
+        else:
+            lines.append("No data to display")
+
+        return "\n".join(lines).encode("utf-8")

aip_agents/examples/tools/image_artifact_tool.py

@@ -0,0 +1,136 @@
+"""Image artifact tool for demonstrating artifact generation.
+
+This tool generates simple images and returns them as artifacts to demonstrate
+the standardized artifact format for binary data.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import io
+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, create_error_response
+
+# Optional PIL import for image generation
+try:
+    from PIL import Image, ImageDraw, ImageFont  # type: ignore
+
+    PIL_AVAILABLE = True
+except ImportError:
+    PIL_AVAILABLE = False
+    Image = None
+    ImageDraw = None
+    ImageFont = None
+
+
+class ImageArtifactInput(BaseModel):
+    """Input schema for image artifact tool."""
+
+    width: int = Field(default=400, description="Width of the image in pixels", ge=100, le=1000)
+    height: int = Field(default=300, description="Height of the image in pixels", ge=100, le=1000)
+    color: str = Field(default="blue", description="Primary color for the image")
+    text: str = Field(default="Sample Image", description="Text to display on the image")
+    image_name: str = Field(default="generated_image", description="Name for the generated image")
+
+
+class ImageArtifactTool(BaseTool):
+    """Tool that generates simple images with artifact support.
+
+    This tool demonstrates the standardized artifact format for binary data by:
+    1. Generating a simple image using PIL
+    2. Providing a confirmation message for the agent
+    3. Creating an image file artifact for the user
+    """
+
+    name: str = "image_generator"
+    description: str = "Generate simple images with text and colors"
+    args_schema: type[BaseModel] = ImageArtifactInput
+
+    def _run(
+        self,
+        width: int = 400,
+        height: int = 300,
+        color: str = "blue",
+        text: str = "Sample Image",
+        image_name: str = "generated_image",
+    ) -> dict[str, Any]:
+        """Generate an image synchronously.
+
+        Args:
+            width (int, optional): Width of the image in pixels. Defaults to 400.
+            height (int, optional): Height of the image in pixels. Defaults to 300.
+            color (str, optional): Primary color for the image. Defaults to "blue".
+            text (str, optional): Text to display on the image. Defaults to "Sample Image".
+            image_name (str, optional): Name for the generated image. Defaults to "generated_image".
+
+        Returns:
+            dict[str, Any]: Response containing artifact data and metadata.
+        """
+        if not PIL_AVAILABLE:
+            return create_error_response("PIL (Pillow) library is not installed. Cannot generate images.")
+
+        # Create image
+        image = Image.new("RGB", (width, height), color=color)
+        draw = ImageDraw.Draw(image)
+
+        # Try to use a default font, fall back to basic font if not available
+        try:
+            font = ImageFont.load_default()
+        except Exception:
+            font = None
+
+        # Calculate text position (center)
+        if font:
+            bbox = draw.textbbox((0, 0), text, font=font)
+            text_width = bbox[2] - bbox[0]
+            text_height = bbox[3] - bbox[1]
+        else:
+            # Rough estimation for basic font
+            text_width = len(text) * 6
+            text_height = 11
+
+        x = (width - text_width) // 2
+        y = (height - text_height) // 2
+
+        # Draw text
+        draw.text((x, y), text, fill="white", font=font)
+
+        # Convert to bytes
+        img_buffer = io.BytesIO()
+        image.save(img_buffer, format="PNG")
+        img_bytes = img_buffer.getvalue()
+
+        return create_artifact_response(
+            result=f"I have generated a {width}x{height} {color} image with the text '{text}'.",
+            artifact_data=img_bytes,
+            artifact_name=f"{image_name}.png",
+            artifact_description=f"Generated {width}x{height} {color} image with text: {text}",
+            mime_type=MimeType.IMAGE_PNG,
+        )
+
+    async def _arun(
+        self,
+        width: int = 400,
+        height: int = 300,
+        color: str = "blue",
+        text: str = "Sample Image",
+        image_name: str = "generated_image",
+    ) -> dict[str, Any]:
+        """Generate an image asynchronously.
+
+        Args:
+            width (int, optional): Width of the image in pixels. Defaults to 400.
+            height (int, optional): Height of the image in pixels. Defaults to 300.
+            color (str, optional): Primary color for the image. Defaults to "blue".
+            text (str, optional): Text to display on the image. Defaults to "Sample Image".
+            image_name (str, optional): Name for the generated image. Defaults to "generated_image".
+
+        Returns:
+            dict[str, Any]: Response containing artifact data and metadata.
+        """
+        return self._run(width, height, color, text, image_name)

aip_agents/examples/tools/langchain_arithmetic_tools.py

@@ -0,0 +1,26 @@
+"""LangChain-specific arithmetic tools for GLLM agent examples."""
+
+from langchain_core.tools import tool
+
+
+# Decorate the plain function to create a LangChain Tool
+@tool
+def add_numbers(a: int, b: int) -> str:
+    """Adds two numbers and returns the result as a string.
+
+    This is a self-contained LangChain tool.
+    For example:
+    add_numbers(a=5, b=3)
+
+    Args:
+        a (int): First number to add.
+        b (int): Second number to add.
+
+    Returns:
+        str: Sum of the two numbers as a string.
+    """
+    try:
+        result = a + b
+        return str(result)
+    except Exception as e:
+        return f"Error: Could not add numbers. Reason: {str(e)}"

aip_agents/examples/tools/langchain_currency_exchange_tool.py

@@ -0,0 +1,88 @@
+"""Simple currency exchange tool demonstrating RunnableConfig tool configuration."""
+
+import asyncio
+
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from langgraph.types import Command
+from pydantic import BaseModel, Field
+
+
+class CurrencyConfig(BaseModel):
+    """Tool configuration schema."""
+
+    tenant_id: str = Field(description="Tenant identifier")
+    auth_key: str = Field(description="Authentication key")
+
+
+class CurrencyInput(BaseModel):
+    """Input schema for currency exchange."""
+
+    amount: float = Field(description="Amount to convert", gt=0)
+    from_currency: str = Field(description="Source currency (USD, EUR)")
+    to_currency: str = Field(description="Target currency (USD, EUR)")
+
+
+class CurrencyExchangeTool(BaseTool):
+    """Simple currency exchange tool with SDK auto-injection configuration."""
+
+    name: str = "currency_exchange"
+    description: str = "Convert currencies with tenant-specific rates"
+    args_schema: type[BaseModel] = CurrencyInput
+    tool_config_schema: type[BaseModel] = CurrencyConfig
+
+    def _run(self, amount: float, from_currency: str, to_currency: str, config: RunnableConfig, **kwargs) -> str:
+        """Run the tool asynchronously.
+
+        Args:
+            amount (float): Amount to convert.
+            from_currency (str): Source currency (USD, EUR).
+            to_currency (str): Target currency (USD, EUR).
+            config (RunnableConfig): Tool configuration containing tenant and auth info.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            str: Conversion result text.
+        """
+        return asyncio.run(self._arun(amount, from_currency, to_currency, config, **kwargs))
+
+    async def _arun(self, amount: float, from_currency: str, to_currency: str, config: RunnableConfig, **kwargs) -> str:
+        """Convert currency using effective configuration.
+
+        Args:
+            amount (float): Amount to convert.
+            from_currency (str): Source currency (USD, EUR).
+            to_currency (str): Target currency (USD, EUR).
+            config (RunnableConfig): Tool configuration containing tenant and auth info.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            str: Command with conversion result and metadata.
+        """
+        # Get effective config (runtime override or agent default)
+        effective_config = self.get_tool_config(config)
+
+        if not effective_config:
+            return "❌ No configuration provided"
+
+        # Simple tenant validation
+        rates = {"premium_corp": 0.85, "standard_business": 1.5}
+        keys = {"premium_corp": "premium_key_123", "standard_business": "standard_key_456"}
+
+        if effective_config.tenant_id not in rates or effective_config.auth_key != keys.get(effective_config.tenant_id):
+            return f"❌ Invalid tenant: {effective_config.tenant_id}"
+
+        # Simple USD/EUR conversion
+        rate = rates[effective_config.tenant_id] if from_currency == "USD" else 1 / rates[effective_config.tenant_id]
+        result = amount * rate
+
+        result_text = f"💱 {amount} {from_currency} = {result:.2f} {to_currency} (tenant: {effective_config.tenant_id})"
+
+        return Command(
+            update={
+                "result": result_text,
+                "metadata": {
+                    "message": "Conversion successful",
+                },
+            }
+        )