aip-agents-binary 0.5.20__py3-none-manylinux_2_31_x86_64.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/final_response_builder.pyi

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+__all__ = ['FinalResponseMetadataOptions', 'assemble_final_response']
+
+@dataclass(slots=True)
+class FinalResponseMetadataOptions:
+    """Container for optional metadata fields on final response events."""
+    step_id: str | None = ...
+    previous_step_ids: list[str] | None = ...
+    tool_info: dict[str, Any] | None = ...
+    thinking_and_activity_info: dict[str, Any] | None = ...
+    completion_reason: str | None = ...
+    timeout_seconds: float | None = ...
+    message: dict[str, Any] | None = ...
+    partial_result: str | None = ...
+    metadata_extra: dict[str, Any] | None = ...
+
+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.
+    '''

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/formatter_llm_client.pyi

@@ -0,0 +1,71 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from collections.abc import Awaitable as Awaitable
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+from typing import Any, TypeVar
+
+logger: Incomplete
+FORMATTER_ENV_VAR: str
+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."""
+    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.
+        """
+    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.
+        """
+    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.
+        """
+    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.
+        """
+
+def get_formatter_llm_client() -> FormatterLLMClient:
+    """Return the process-wide 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.
+    """

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/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.utils.langgraph.converter import convert_gllm_tool_call_to_langchain_tool_call as convert_gllm_tool_call_to_langchain_tool_call, convert_langchain_messages_to_gllm_messages as convert_langchain_messages_to_gllm_messages, convert_langchain_tool_call_to_gllm_tool_call as convert_langchain_tool_call_to_gllm_tool_call, convert_lm_output_to_langchain_message as 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']