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

aip_agents/utils/final_response_builder.py

@@ -0,0 +1,211 @@
+"""Utilities for assembling final response events with consistent structure.
+
+This module wraps the lower-level ``_build_final_response_event`` helper and
+provides a single entry point for producing final response payloads that may
+include accumulated artifacts, custom metadata overrides, and additional
+top-level fields.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from aip_agents.utils.metadata_helper import Kind, MetadataFieldKeys, Status
+
+_FINAL_METADATA_RESERVED_KEYS = {
+    MetadataFieldKeys.KIND.value,
+    MetadataFieldKeys.STATUS.value,
+    "timestamp",
+}
+
+
+@dataclass(slots=True)
+class FinalResponseMetadataOptions:
+    """Container for optional metadata fields on final response events."""
+
+    step_id: str | None = None
+    previous_step_ids: list[str] | None = None
+    tool_info: dict[str, Any] | None = None
+    thinking_and_activity_info: dict[str, Any] | None = None
+    completion_reason: str | None = None
+    timeout_seconds: float | None = None
+    message: dict[str, Any] | None = None
+    partial_result: str | None = None
+    metadata_extra: dict[str, Any] | None = None
+
+
+def _metadata_overrides_from_options(options: FinalResponseMetadataOptions) -> dict[str, Any]:
+    """Build a dictionary of metadata overrides from the provided options.
+
+    Args:
+        options: The metadata options to extract overrides from.
+    """
+    potential_overrides = {
+        "step_id": options.step_id,
+        "previous_step_ids": options.previous_step_ids,
+        MetadataFieldKeys.TOOL_INFO: options.tool_info,
+        MetadataFieldKeys.THINKING_AND_ACTIVITY_INFO: options.thinking_and_activity_info,
+        "completion_reason": options.completion_reason,
+        "timeout_seconds": options.timeout_seconds,
+        MetadataFieldKeys.MESSAGE: options.message,
+        "partial_result": options.partial_result,
+    }
+    return {key: value for key, value in potential_overrides.items() if value is not None}
+
+
+def _normalized_metadata_extras(metadata_extra: dict[str, Any] | None) -> dict[str, Any]:
+    """Return metadata extras filtered for reserved keys and normalized to strings.
+
+    Args:
+        metadata_extra: Additional metadata to normalize, or None.
+    """
+    if not metadata_extra:
+        return {}
+    normalized: dict[str, Any] = {}
+    for key, value in metadata_extra.items():
+        normalized_key = str(key)
+        if normalized_key in _FINAL_METADATA_RESERVED_KEYS:
+            continue
+        normalized[normalized_key] = value
+    return normalized
+
+
+def _update_optional_top_level_fields(
+    event: dict[str, Any],
+    status: str,
+    task_state: str,
+    artifacts: list[dict[str, Any]] | None,
+) -> None:
+    """Apply optional top-level fields when they are provided.
+
+    Args:
+        event: The event dictionary to update.
+        status: The status value to set.
+        task_state: The task state value to set.
+        artifacts: List of artifacts to include, or None.
+    """
+    for key, value in (("status", status), ("task_state", task_state)):
+        if value:
+            event[key] = value
+    if artifacts:
+        event["artifacts"] = artifacts
+
+
+def _ensure_timestamp_alignment(
+    event: dict[str, Any],
+    metadata: dict[str, Any],
+    timestamp: datetime | None,
+) -> None:
+    """Keep event-level and metadata timestamps synchronized.
+
+    Args:
+        event: The event dictionary containing timestamp information.
+        metadata: The metadata dictionary to update.
+        timestamp: The timestamp to align, or None.
+    """
+    event_timestamp = event.get("timestamp")
+    if event_timestamp is not None:
+        metadata["timestamp"] = event_timestamp
+        return
+
+    metadata_timestamp = metadata.get("timestamp")
+    if metadata_timestamp is not None:
+        event["timestamp"] = metadata_timestamp
+        return
+
+    resolved_timestamp = (timestamp or datetime.now(UTC)).isoformat()
+    metadata["timestamp"] = resolved_timestamp
+    event["timestamp"] = resolved_timestamp
+
+
+def _build_final_response_event(
+    *,
+    content: str,
+    metadata_options: FinalResponseMetadataOptions | None = None,
+    event_extra: dict[str, Any] | None = None,
+    timestamp: datetime | None = None,
+) -> dict[str, Any]:
+    """Build a standardized final_response event payload.
+
+    Args:
+        content: The human-readable message to include in the event.
+        metadata_options: Optional container for per-event metadata overrides such as
+            identifiers, tool info, localized messages, and completion details.
+        event_extra: Additional top-level event fields to merge (e.g., task_id).
+        timestamp: Explicit timestamp for the event; defaults to current UTC time.
+
+    Returns:
+        dict[str, Any]: Final response payload ready for SSE serialization.
+    """
+    timestamp_value = (timestamp or datetime.now(UTC)).isoformat()
+    metadata: dict[str, Any] = {
+        MetadataFieldKeys.KIND: Kind.FINAL_RESPONSE,
+        MetadataFieldKeys.STATUS: Status.FINISHED,
+        MetadataFieldKeys.TIME: 0.0,
+        "timestamp": timestamp_value,
+    }
+
+    if metadata_options is not None:
+        metadata.update(_metadata_overrides_from_options(metadata_options))
+        metadata.update(_normalized_metadata_extras(metadata_options.metadata_extra))
+
+    event: dict[str, Any] = {
+        "status": "success",
+        "task_state": "completed",
+        "content": content,
+        "event_type": "final_response",
+        "final": True,
+        "metadata": metadata,
+    }
+
+    if event_extra:
+        event.update(event_extra)
+
+    return event
+
+
+def assemble_final_response(
+    *,
+    content: str,
+    artifacts: list[dict[str, Any]] | None = None,
+    metadata_options: FinalResponseMetadataOptions | None = None,
+    status: str = "success",
+    task_state: str = "completed",
+    extra_fields: dict[str, Any] | None = None,
+    timestamp: datetime | None = None,
+) -> dict[str, Any]:
+    """Create a final response event with optional artifacts and overrides.
+
+    Args:
+        content: Human readable message for the final response.
+        artifacts: Optional list of artifact dictionaries to attach.
+        metadata_options: Metadata overrides passed through to the underlying builder.
+        status: Top-level status string; defaults to ``"success"``.
+        task_state: State string describing the task; defaults to ``"completed"``.
+        extra_fields: Additional top-level fields to merge onto the event.
+        timestamp: Explicit timestamp for the event. Defaults to ``datetime.now(UTC)``.
+
+    Returns:
+        dict[str, Any]: Final response event payload ready for downstream streaming.
+    """
+    event = _build_final_response_event(
+        content=content,
+        metadata_options=metadata_options,
+        event_extra=extra_fields,
+        timestamp=timestamp,
+    )
+
+    _update_optional_top_level_fields(event, status, task_state, artifacts)
+
+    metadata = event.setdefault("metadata", {})
+    _ensure_timestamp_alignment(event, metadata, timestamp)
+
+    return event
+
+
+__all__ = ["FinalResponseMetadataOptions", "assemble_final_response"]

aip_agents/utils/formatter_llm_client.py

@@ -0,0 +1,231 @@
+"""Utilities for working with the shared formatter LLM invoker.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import threading
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+from gllm_inference.builder import build_lm_invoker
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+FORMATTER_ENV_VAR = "DEFAULT_MODEL_FORMATTER"
+T = TypeVar("T")
+
+
+class FormatterInvokerUnavailableError(RuntimeError):
+    """Raised when no formatter LLM invoker can be resolved."""
+
+
+class FormatterInvocationError(RuntimeError):
+    """Raised when invoking the formatter LLM fails."""
+
+
+class FormatterLLMClient:
+    """Stateful helper that manages formatter invoker resolution and execution."""
+
+    def __init__(self) -> None:
+        """Initialize the formatter LLM client with caching and thread safety."""
+        self._failed_sentinel = object()
+        self._invoker_cache: dict[str, BaseLMInvoker | object] = {}
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    def seed_default(self, default_model_id: str | None) -> None:
+        """Populate ``DEFAULT_MODEL_FORMATTER`` when unset.
+
+        Args:
+            default_model_id: Preferred formatter model id to use as a fallback.
+        """
+        current = self._normalize_model_id(os.getenv(FORMATTER_ENV_VAR))
+        if current:
+            return
+
+        fallback = self._normalize_model_id(default_model_id)
+        if fallback:
+            os.environ[FORMATTER_ENV_VAR] = fallback
+
+    def resolve_invoker(self, *, reset_cache: bool = False) -> BaseLMInvoker | None:
+        """Return the cached formatter invoker, optionally refreshing it.
+
+        Args:
+            reset_cache: When True, clear the cached invoker before resolving.
+
+        Returns:
+            BaseLMInvoker | None: Cached invoker if the formatter is configured, otherwise None.
+        """
+        resolved = self._normalize_model_id(os.getenv(FORMATTER_ENV_VAR))
+        if not resolved:
+            logger.warning("DEFAULT_MODEL_FORMATTER is not set; formatter summaries are disabled.")
+            return None
+
+        with self._lock:
+            if reset_cache:
+                self._invoker_cache.pop(resolved, None)
+
+            cached = self._invoker_cache.get(resolved)
+            if cached is self._failed_sentinel:
+                return None
+            if cached is not None:
+                return cached  # type: ignore[return-value]
+
+            try:
+                invoker = build_lm_invoker(model_id=resolved)
+            except Exception as exc:  # pragma: no cover - best effort
+                logger.warning("Failed to initialize formatter LLM invoker (%s): %s", resolved, exc)
+                self._invoker_cache[resolved] = self._failed_sentinel
+                return None
+
+            self._invoker_cache[resolved] = invoker
+            return invoker
+
+    async def invoke(
+        self,
+        *args: Any,
+        invoker: BaseLMInvoker | None = None,
+        timeout: float | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Dispatch formatter prompts asynchronously with timeout/error handling.
+
+        Args:
+            *args: Positional arguments forwarded to the invoker.
+            invoker: Explicit invoker instance to reuse instead of resolving one.
+            timeout: Optional timeout (seconds) enforced with ``asyncio.timeout``.
+            **kwargs: Keyword arguments forwarded to the invoker.
+
+        Returns:
+            Any: Result returned by the formatter LLM.
+
+        Raises:
+            FormatterInvokerUnavailableError: If no formatter model is configured.
+            FormatterInvocationError: When the invocation fails or exceeds the timeout.
+        """
+        resolved = invoker or self.resolve_invoker()
+        if not resolved:
+            raise FormatterInvokerUnavailableError("Formatter LLM invoker is unavailable.")
+
+        try:
+            invocation = resolved.invoke(*args, **kwargs)
+            if timeout is not None:
+                async with asyncio.timeout(timeout):
+                    return await invocation
+            return await invocation
+        except asyncio.CancelledError:
+            raise
+        except TimeoutError:
+            raise FormatterInvocationError("Formatter LLM invocation timed out") from None
+        except Exception as exc:  # pragma: no cover - best effort
+            raise FormatterInvocationError(f"Formatter LLM invocation failed: {exc}") from exc
+
+    def invoke_blocking(
+        self,
+        *args: Any,
+        invoker: BaseLMInvoker | None = None,
+        timeout: float | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Invoke the formatter LLM from synchronous contexts.
+
+        Args:
+            *args: Positional arguments forwarded to ``invoke``.
+            invoker: Optional invoker to reuse.
+            timeout: Optional timeout (seconds) for the async invocation.
+            **kwargs: Keyword arguments forwarded to ``invoke``.
+
+        Returns:
+            Any: Result returned by the formatter LLM.
+        """
+
+        async def _runner() -> Any:
+            return await self.invoke(*args, invoker=invoker, timeout=timeout, **kwargs)
+
+        return self._run_coroutine_blocking(_runner)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _normalize_model_id(value: str | None) -> str | None:
+        """Strip whitespace and return the model id when a value was provided.
+
+        Args:
+            value: Raw model identifier pulled from the environment.
+
+        Returns:
+            str | None: Sanitized model id or None when the input was blank.
+        """
+        if isinstance(value, str):
+            stripped = value.strip()
+            if stripped:
+                return stripped
+        return None
+
+    def _run_coroutine_blocking(self, factory: Callable[[], Awaitable[T]]) -> T:
+        """Execute an awaitable from sync code, even when a loop is already running.
+
+        Args:
+            factory: Callable returning the coroutine to execute.
+
+        Returns:
+            T: Result of the awaited coroutine.
+        """
+
+        async def _wrapper() -> T:
+            return await factory()
+
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(_wrapper())
+
+        result: dict[str, T] = {}
+        error: list[BaseException] = []
+        done = threading.Event()
+
+        def _thread_runner() -> None:
+            try:
+                value = asyncio.run(_wrapper())
+                result["value"] = value
+            except Exception as exc:
+                error.append(exc)
+            finally:
+                done.set()
+
+        thread = threading.Thread(target=_thread_runner, daemon=True)
+        thread.start()
+        done.wait()
+        thread.join()
+
+        if error:
+            raise error[0]
+        return result["value"]
+
+
+_formatter_llm_client = FormatterLLMClient()
+
+
+def get_formatter_llm_client() -> FormatterLLMClient:
+    """Return the process-wide formatter LLM client."""
+    return _formatter_llm_client
+
+
+def seed_formatter_llm_default(default_model_id: str | None) -> None:
+    """Convenience wrapper for seeding the formatter default model.
+
+    Args:
+        default_model_id: Formatter model identifier to seed when missing.
+    """
+    get_formatter_llm_client().seed_default(default_model_id)

aip_agents/utils/langgraph/__init__.py

@@ -0,0 +1,19 @@
+"""Define __init__ for langgraph converter.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from aip_agents.utils.langgraph.converter import (
+    convert_gllm_tool_call_to_langchain_tool_call,
+    convert_langchain_messages_to_gllm_messages,
+    convert_langchain_tool_call_to_gllm_tool_call,
+    convert_lm_output_to_langchain_message,
+)
+
+__all__ = [
+    "convert_gllm_tool_call_to_langchain_tool_call",
+    "convert_langchain_tool_call_to_gllm_tool_call",
+    "convert_lm_output_to_langchain_message",
+    "convert_langchain_messages_to_gllm_messages",
+]

aip_agents/utils/langgraph/converter.py

@@ -0,0 +1,128 @@
+"""Bridge utilities for converting between LangChain and LM Invoker formats.
+
+This module provides conversion functions between LangChain's message format
+and gllm-inference's Message format, enabling seamless integration
+of LM Invoker with LangChain-based agents.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from collections.abc import Sequence
+
+from gllm_inference.schema import LMOutput, Message, ToolResult
+from gllm_inference.schema import ToolCall as GllmToolCall
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage
+from langchain_core.messages.tool import ToolCall as LangChainToolCall
+
+
+def convert_langchain_messages_to_gllm_messages(messages: Sequence[BaseMessage], instruction: str) -> list[Message]:
+    """Convert LangChain messages to gllm-inference Message format.
+
+    This function transforms a sequence of LangChain messages into the Message
+    format expected by LM Invoker. It handles system messages, human messages, AI messages
+    with tool calls, and tool result messages.
+
+    Args:
+        messages: Sequence of LangChain BaseMessage objects to convert.
+        instruction: System instruction to prepend if not already present in messages.
+
+    Returns:
+        List of Message objects containing the converted message sequence.
+    """
+    converted_messages = []
+
+    # Add system instruction first if provided
+    if instruction:
+        converted_messages.append(Message.system(instruction))
+
+    for msg in messages:
+        if isinstance(msg, SystemMessage):
+            # Skip if we already added instruction, or append if different
+            if not instruction or msg.content != instruction:
+                converted_messages.append(Message.system(msg.content))
+        elif isinstance(msg, HumanMessage):
+            converted_messages.append(Message.user(msg.content))
+        elif isinstance(msg, AIMessage):
+            if msg.tool_calls:
+                # Convert LangChain tool calls to gllm ToolCall objects
+                tool_calls = [convert_langchain_tool_call_to_gllm_tool_call(tc) for tc in msg.tool_calls]
+                converted_messages.append(Message.assistant(tool_calls))
+            else:
+                converted_messages.append(Message.assistant(msg.content))
+        elif isinstance(msg, ToolMessage):
+            # Convert ToolMessage to ToolResult
+            tool_result = ToolResult(id=msg.tool_call_id, output=msg.content)
+            converted_messages.append(Message.user([tool_result]))
+
+    return converted_messages
+
+
+def convert_lm_output_to_langchain_message(response: LMOutput | str) -> AIMessage:
+    """Convert LM Invoker output to LangChain AIMessage.
+
+    This function transforms the output from LM Invoker back into LangChain's
+    AIMessage format, handling both text responses and tool calls.
+
+    Args:
+        response: The response from LM Invoker (MultimodalOutput).
+
+    Returns:
+        AIMessage containing the converted response.
+    """
+    if not isinstance(response, LMOutput):
+        # when output_analytics lm_invoker is false
+        return AIMessage(
+            content=str(response),
+            response_metadata={
+                "finish_reason": "stop",
+            },
+        )
+
+    tool_calls = []
+    if response.tool_calls:
+        tool_calls = [convert_gllm_tool_call_to_langchain_tool_call(tc) for tc in response.tool_calls]
+
+    usage_metadata = None
+    if response.token_usage:
+        usage_metadata = {
+            "input_tokens": response.token_usage.input_tokens,
+            "output_tokens": response.token_usage.output_tokens,
+            "total_tokens": response.token_usage.input_tokens + response.token_usage.output_tokens,
+        }
+
+    # if add finish reason stop fo non-tool call ai messages
+    response_metadata = {}
+    if not tool_calls:
+        response_metadata["finish_reason"] = "stop"
+
+    return AIMessage(
+        content=str(response.response),
+        tool_calls=tool_calls,
+        usage_metadata=usage_metadata,
+        response_metadata=response_metadata,
+    )
+
+
+def convert_langchain_tool_call_to_gllm_tool_call(lc_tool_call: LangChainToolCall) -> GllmToolCall:
+    """Convert LangChain tool call to gllm ToolCall.
+
+    Args:
+        lc_tool_call: LangChain ToolCall (TypedDict).
+
+    Returns:
+        GllmToolCall object for gllm-inference.
+    """
+    return GllmToolCall(id=lc_tool_call["id"], name=lc_tool_call["name"], args=lc_tool_call["args"])
+
+
+def convert_gllm_tool_call_to_langchain_tool_call(gllm_tool_call: GllmToolCall) -> LangChainToolCall:
+    """Convert gllm ToolCall to LangChain ToolCall format.
+
+    Args:
+        gllm_tool_call: GllmToolCall object from gllm-inference.
+
+    Returns:
+        LangChain ToolCall (TypedDict) with proper type annotation.
+    """
+    return LangChainToolCall(id=gllm_tool_call.id, name=gllm_tool_call.name, args=gllm_tool_call.args)

aip_agents/utils/langgraph/tool_managers/__init__.py

@@ -0,0 +1,15 @@
+"""Tool managers for organizing LangGraph agent capabilities.
+
+This package contains tool managers that convert different types of capabilities
+(A2A communication, agent delegation) into unified LangChain tools for use in
+LangGraph agents.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from aip_agents.utils.langgraph.tool_managers.a2a_tool_manager import A2AToolManager
+from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager
+from aip_agents.utils.langgraph.tool_managers.delegation_tool_manager import DelegationToolManager
+
+__all__ = ["BaseLangGraphToolManager", "A2AToolManager", "DelegationToolManager"]