aip-agents-binary 0.5.25b1__py3-none-macosx_13_0_arm64.whl

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",
+                },
+            }
+        )

aip_agents/examples/tools/langchain_currency_exchange_tool.pyi

@@ -0,0 +1,20 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+class CurrencyConfig(BaseModel):
+    """Tool configuration schema."""
+    tenant_id: str
+    auth_key: str
+
+class CurrencyInput(BaseModel):
+    """Input schema for currency exchange."""
+    amount: float
+    from_currency: str
+    to_currency: str
+
+class CurrencyExchangeTool(BaseTool):
+    """Simple currency exchange tool with SDK auto-injection configuration."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    tool_config_schema: type[BaseModel]

aip_agents/examples/tools/langchain_graph_artifact_tool.py

@@ -0,0 +1,172 @@
+"""This is a tool that generates a tiny bar/line chart and returns it as a Command artifact.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+# Optional imports for chart rendering
+import io
+
+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
+
+try:
+    from PIL import Image, ImageDraw  # type: ignore
+
+    PIL_AVAILABLE = True
+except ImportError:
+    PIL_AVAILABLE = False
+    Image = None
+    ImageDraw = None
+
+
+class GraphCommandInput(BaseModel):
+    """Input schema for a tiny bar/line chart artifact tool.
+
+    Note: width/height are clamped to a small size to keep artifacts lightweight.
+    """
+
+    chart_type: str = Field(
+        default="bar",
+        description="Type of chart to generate (bar or line).",
+        pattern="^(bar|line)$",
+    )
+    labels: list[str] = Field(
+        default_factory=lambda: ["A", "B", "C"],
+        description="Labels for categories",
+    )
+    values: list[float] = Field(
+        default_factory=lambda: [10.0, 20.0, 15.0],
+        description="Values corresponding to labels",
+    )
+    title: str = Field(default="Chart", description="Chart title (metadata only)")
+    width: int = Field(default=64, ge=16, le=128, description="Desired image width in px (will be clamped)")
+    height: int = Field(default=64, ge=16, le=128, description="Desired image height in px (will be clamped)")
+    image_name: str = Field(default="chart", description="Base filename (without extension)")
+
+
+class GraphArtifactCommandTool(BaseTool):
+    """Generate a very small PNG chart and return it as a Command artifact."""
+
+    name: str = "graph_generator_command"
+    description: str = "Generate a tiny bar/line chart and return a lightweight PNG artifact using Command."
+    args_schema: type[BaseModel] = GraphCommandInput
+
+    def _run(  # noqa: PLR0913
+        self,
+        chart_type: str = "bar",
+        labels: list[str] | None = None,
+        values: list[float] | None = None,
+        title: str = "Chart",
+        width: int = 64,
+        height: int = 64,
+        image_name: str = "chart",
+    ) -> Command:
+        labels = labels or ["A", "B", "C"]
+        values = values or [10.0, 20.0, 15.0]
+
+        if not labels or len(labels) != len(values):
+            return Command(update={"result": "Invalid input: labels and values must be non-empty and equal length."})
+
+        # Clamp to very small size to keep base64 short
+        img_w = max(16, min(int(width), 64))
+        img_h = max(16, min(int(height), 64))
+
+        png_bytes = self._render_tiny_chart(chart_type, labels, values, img_w, img_h)
+
+        result_text = f"Generated tiny {chart_type} chart '{title}' with {len(labels)} points as {image_name}.png"
+        metadata_delta = {
+            "last_chart": {
+                "name": f"{image_name}.png",
+                "chart_type": chart_type,
+                "title": title,
+                "num_points": len(labels),
+                "size": f"{img_w}x{img_h}",
+            }
+        }
+
+        return create_artifact_command(
+            result=result_text,
+            artifact_data=png_bytes,
+            artifact_name=f"{image_name}.png",
+            artifact_description=f"Tiny {chart_type} chart: {title}",
+            mime_type=MimeType.IMAGE_PNG,
+            metadata_update=metadata_delta,
+        )
+
+    @staticmethod
+    def _render_tiny_chart(
+        chart_type: str,
+        labels: list[str],
+        values: list[float],
+        width: int,
+        height: int,
+    ) -> bytes:
+        """Render a tiny chart using only PIL to keep artifact size minimal.
+
+        Args:
+            chart_type (str): Type of chart to render ("bar" or "line").
+            labels (list[str]): Labels for the data points.
+            values (list[float]): Values to plot.
+            width (int): Width of the chart image in pixels.
+            height (int): Height of the chart image in pixels.
+
+        Returns:
+            bytes: PNG image data as bytes.
+        """
+        if not PIL_AVAILABLE:
+            raise ImportError("PIL is not available for chart rendering")
+
+        # Canvas and basic layout
+        image = Image.new("RGB", (width, height), color="white")
+        draw = ImageDraw.Draw(image)
+
+        # Small margins for axes
+        margin_left = max(3, width // 12)
+        margin_right = max(2, width // 20)
+        margin_top = max(3, height // 12)
+        margin_bottom = max(6, height // 8)
+
+        plot_w = max(1, width - margin_left - margin_right)
+        plot_h = max(1, height - margin_top - margin_bottom)
+
+        # Axes
+        x0, y0 = margin_left, height - margin_bottom
+        x1, y1 = width - margin_right, margin_top
+        draw.line((x0, y0, x1, y0), fill="black")
+        draw.line((x0, y0, x0, y1), fill="black")
+
+        # Normalize values to plot height
+        max_val = max(values + [1.0])
+        n = len(values)
+        if chart_type == "bar":
+            # Thin bars to keep readable at tiny sizes
+            bar_spacing = plot_w / max(n, 1)
+            bar_w = max(1, int(bar_spacing * 0.6))
+            for i, val in enumerate(values):
+                x_center = x0 + int((i + 0.5) * bar_spacing)
+                bar_h = int((val / max_val) * plot_h)
+                x_left = x_center - bar_w // 2
+                x_right = x_center + bar_w // 2
+                y_top = y0 - bar_h
+                draw.rectangle((x_left, y_top, x_right, y0), fill="#4C78A8")
+        else:
+            # Polyline with small points
+            points = []
+            step = plot_w / max(n, 1)
+            for i, val in enumerate(values):
+                x = x0 + int((i + 0.5) * step)
+                y = y0 - int((val / max_val) * plot_h)
+                points.append((x, y))
+            if len(points) >= 2:  # noqa: PLR2004
+                draw.line(points, fill="#F58518")
+            for px, py in points:
+                draw.ellipse((px - 1, py - 1, px + 1, py + 1), fill="#F58518")
+
+        buf = io.BytesIO()
+        image.save(buf, format="PNG", optimize=True)
+        return buf.getvalue()

aip_agents/examples/tools/langchain_graph_artifact_tool.pyi

@@ -0,0 +1,25 @@
+from aip_agents.a2a.types import MimeType as MimeType
+from aip_agents.utils.artifact_helpers import create_artifact_command as create_artifact_command
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+PIL_AVAILABLE: bool
+
+class GraphCommandInput(BaseModel):
+    """Input schema for a tiny bar/line chart artifact tool.
+
+    Note: width/height are clamped to a small size to keep artifacts lightweight.
+    """
+    chart_type: str
+    labels: list[str]
+    values: list[float]
+    title: str
+    width: int
+    height: int
+    image_name: str
+
+class GraphArtifactCommandTool(BaseTool):
+    """Generate a very small PNG chart and return it as a Command artifact."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]

aip_agents/examples/tools/langchain_weather_tool.py

@@ -0,0 +1,48 @@
+"""Defines a weather tool that can be used to get the weather for a specified city.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from langchain_core.tools import tool
+from pydantic import BaseModel
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class WeatherToolInputSchema(BaseModel):
+    """Schema for weather tool input."""
+
+    city: str
+
+
+@tool(args_schema=WeatherToolInputSchema)
+def weather_tool(city: str) -> str:
+    """Gets the weather for a specified city.
+
+    Args:
+        city: The name of the city to get weather for.
+
+    Returns:
+        A string describing the weather conditions.
+    """
+    weather_data = {
+        "Jakarta": "32°C, Partly cloudy with high humidity",
+        "Singapore": "30°C, Scattered thunderstorms",
+        "Tokyo": "25°C, Clear skies",
+        "London": "18°C, Light rain",
+        "New York": "22°C, Sunny",
+    }
+
+    city_name = city.strip().title()
+
+    weather = weather_data.get(city_name)
+    if weather:
+        logger.info(f"Found weather for {city_name}: {weather}")
+        return weather
+    else:
+        message = f"Weather data not available for {city}"
+        logger.warning(message)
+        return message

aip_agents/examples/tools/langchain_weather_tool.pyi

@@ -0,0 +1,19 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from pydantic import BaseModel
+
+logger: Incomplete
+
+class WeatherToolInputSchema(BaseModel):
+    """Schema for weather tool input."""
+    city: str
+
+def weather_tool(city: str) -> str:
+    """Gets the weather for a specified city.
+
+    Args:
+        city: The name of the city to get weather for.
+
+    Returns:
+        A string describing the weather conditions.
+    """

aip_agents/examples/tools/langgraph_streaming_tool.py

@@ -0,0 +1,130 @@
+"""Tool that wraps a LangGraph agent with time and weather tools.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+import os
+from typing import Any
+
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, PrivateAttr
+
+from aip_agents.agent.langgraph_react_agent import LangGraphReactAgent
+from aip_agents.examples.tools.langchain_weather_tool import weather_tool
+from aip_agents.examples.tools.time_tool import TimeTool
+
+
+class StreamingToolConfig(BaseModel):
+    """Tool configuration schema for the LangGraph streaming tool."""
+
+    time_format: str = Field(
+        default="%m/%d/%y %H:%M:%S",
+        description="DateTime format for time-related queries (e.g., '%Y-%m-%d %H:%M:%S', '%A, %B %d, %Y')",
+    )
+
+
+class LangGraphStreamingToolInput(BaseModel):
+    """Input schema for the LangGraphStreamingTool."""
+
+    query: str = Field(..., description="Query prompt for the LangGraph agent to execute")
+
+
+class LangGraphStreamingTool(BaseTool):
+    """Tool that wraps a LangGraph agent with time and weather forecast capabilities."""
+
+    name: str = "langgraph_streaming_tool"
+    description: str = (
+        "Execute tasks using a LangGraph agent with time and weather capabilities. "
+        "Can get current time in various formats and weather information for specific cities. "
+        "Supports configuration for time format settings."
+    )
+    args_schema: type[BaseModel] = LangGraphStreamingToolInput
+    tool_config_schema: type[BaseModel] = StreamingToolConfig
+    _agent: Any = PrivateAttr()
+
+    def __init__(self, model: Any = None, **kwargs):
+        """Initialize the LangGraphStreamingTool.
+
+        Args:
+            model: The model to use for the agent.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(**kwargs)
+
+        if model is None:
+            model = os.getenv("DEFAULT_MODEL", "openai/gpt-4o")
+
+        self._agent = LangGraphReactAgent(
+            name="internal_time_weather_agent",
+            instruction="You are a helpful assistant with access to time and weather tools. "
+            "When users ask for both time and weather information, use BOTH tools: "
+            "1. Use the time_tool to get current time information "
+            "2. Use the weather_tool to get weather for specific cities "
+            "Always provide complete answers using all relevant tools.",
+            model=model,
+            tools=[TimeTool(), weather_tool],
+            description="Internal agent for time and weather tasks",
+        )
+
+    @property
+    def agent(self):
+        """Access the internal agent."""
+        return self._agent
+
+    def _run(self, query: str) -> str:
+        """Run the tool synchronously.
+
+        Args:
+            query: The query to execute.
+
+        Returns:
+            The final output from the tool execution.
+        """
+        result = self.agent.run(query)
+        if isinstance(result, dict) and "output" in result:
+            return str(result["output"])
+        return str(result)
+
+    async def _arun(self, query: str) -> str:
+        """Run the tool asynchronously.
+
+        Args:
+            query: The query to execute.
+
+        Returns:
+            The final output from the tool execution.
+        """
+        result = await self.agent.arun(query)
+        if isinstance(result, dict) and "output" in result:
+            return str(result["output"])
+        return str(result)
+
+    async def arun_streaming(self, query: str = None, config: RunnableConfig = None, **kwargs):
+        """Execute the LangGraph agent asynchronously with A2A streaming output.
+
+        Args:
+            query: The query to execute.
+            config: Tool configuration containing user context and preferences.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            An async generator that yields streaming events.
+        """
+        if query is None:
+            query = kwargs.get("query") or kwargs.get("task")
+
+        effective_config = self.get_tool_config(config)
+
+        if not effective_config:
+            effective_config = StreamingToolConfig(time_format="%m/%d/%y %H:%M:%S")
+
+        try:
+            enhanced_query = f"[Time format: {effective_config.time_format}] {query}"
+
+            async for event in self.agent.arun_a2a_stream(enhanced_query, **kwargs):
+                if event is not None and isinstance(event, dict):
+                    yield event
+        except Exception as e:
+            yield {"event_type": "error", "content": f"Error in agent wrapper streaming: {str(e)}", "is_final": True}

aip_agents/examples/tools/langgraph_streaming_tool.pyi

@@ -0,0 +1,43 @@
+from aip_agents.agent.langgraph_react_agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.examples.tools.langchain_weather_tool import weather_tool as weather_tool
+from aip_agents.examples.tools.time_tool import TimeTool as TimeTool
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+from typing import Any
+
+class StreamingToolConfig(BaseModel):
+    """Tool configuration schema for the LangGraph streaming tool."""
+    time_format: str
+
+class LangGraphStreamingToolInput(BaseModel):
+    """Input schema for the LangGraphStreamingTool."""
+    query: str
+
+class LangGraphStreamingTool(BaseTool):
+    """Tool that wraps a LangGraph agent with time and weather forecast capabilities."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    tool_config_schema: type[BaseModel]
+    def __init__(self, model: Any = None, **kwargs) -> None:
+        """Initialize the LangGraphStreamingTool.
+
+        Args:
+            model: The model to use for the agent.
+            **kwargs: Additional keyword arguments.
+        """
+    @property
+    def agent(self):
+        """Access the internal agent."""
+    async def arun_streaming(self, query: str = None, config: RunnableConfig = None, **kwargs):
+        """Execute the LangGraph agent asynchronously with A2A streaming output.
+
+        Args:
+            query: The query to execute.
+            config: Tool configuration containing user context and preferences.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            An async generator that yields streaming events.
+        """

aip_agents/examples/tools/mock_retrieval_tool.py

@@ -0,0 +1,56 @@
+"""Simple mock tool that returns references for testing reference propagation.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from gllm_core.schema import Chunk
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class MockRetrievalInput(BaseModel):
+    """Input schema for the MockRetrievalTool."""
+
+    query: str = Field(..., description="Search query")
+
+
+class MockRetrievalTool(BaseTool):
+    """Mock tool that returns hardcoded references for testing."""
+
+    name: str = "mock_retrieval"
+    description: str = "Mock retrieval tool that returns sample references for testing reference propagation."
+    args_schema: type[BaseModel] = MockRetrievalInput
+    save_output_history: bool = True
+
+    def _run(self, query: str) -> str:
+        """Return a simple mock response.
+
+        Args:
+            query (str): The search query to process.
+
+        Returns:
+            str: Mock retrieval result for the query.
+        """
+        return f"Mock retrieval result for: {query}"
+
+    def _format_agent_reference(self, tool_output: str) -> list[Chunk]:
+        """Return hardcoded references for testing.
+
+        Args:
+            tool_output (str): The tool output to format as references.
+
+        Returns:
+            list[Chunk]: List of formatted chunks for the query.
+        """
+        query = tool_output.split(":")[-1].strip()
+        return [
+            Chunk(
+                content=f"Mock reference 1 for query: {query}",
+                metadata={"tool_name": "mock_retrieval", "source": "Mock Database", "title": "Mock Reference 1"},
+            ),
+            Chunk(
+                content=f"Mock reference 2 for query: {query}",
+                metadata={"tool_name": "mock_retrieval", "source": "Mock Database", "title": "Mock Reference 2"},
+            ),
+        ]

aip_agents/examples/tools/mock_retrieval_tool.pyi

@@ -0,0 +1,13 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+class MockRetrievalInput(BaseModel):
+    """Input schema for the MockRetrievalTool."""
+    query: str
+
+class MockRetrievalTool(BaseTool):
+    """Mock tool that returns hardcoded references for testing."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    save_output_history: bool