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

aip_agents/utils/event_handler_registry.pyi

@@ -0,0 +1,23 @@
+from _typeshed import Incomplete
+from aip_agents.schema.a2a import A2AStreamEventType as A2AStreamEventType
+from aip_agents.utils.logger import get_logger as get_logger
+from typing import Any
+
+logger: Incomplete
+
+class EventHandlerRegistry:
+    """Registry for tracking known streaming events with pass-through behaviour."""
+    def __init__(self) -> None:
+        """Initialize the event handler registry with known event types."""
+    def handle(self, event_type: A2AStreamEventType | str | None, payload: dict[str, Any]) -> dict[str, Any]:
+        """Return the payload unchanged while logging unknown events.
+
+        Args:
+            event_type (A2AStreamEventType | str | None): The type of the streaming event.
+            payload (dict[str, Any]): The event payload data.
+
+        Returns:
+            dict[str, Any]: The payload unchanged (pass-through).
+        """
+
+DEFAULT_EVENT_HANDLER_REGISTRY: Incomplete

aip_agents/utils/file_prompt_utils.py

@@ -0,0 +1,176 @@
+"""Utilities for augmenting prompts with local file path notes.
+
+This module adds file path metadata to queries but does not read file contents.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+import os
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+FILE_PATH_SYSTEM_NOTE = (
+    "\n\n[System Note: The user has provided a file named '{filename}'. "
+    "It is available at the following local path: {path}]"
+)
+FILE_PATH_INACCESSIBLE_NOTE = (
+    "\n\n[System Note: A file path was provided ({path}), but the file is not accessible. "
+    "Please inform the user about this issue.]"
+)
+FILE_URL_SYSTEM_NOTE = (
+    "\n\n[System Note: The file is also available at the following URL: {url} (expires in {expires_in} {hour_unit}).]"
+)
+
+
+def _normalize_file_entry(entry: str | dict[str, object]) -> dict[str, object] | None:
+    """Normalize a single file entry into a dict.
+
+    Args:
+        entry: A string file path or a metadata dict.
+
+    Returns:
+        A normalized metadata dict or None if the entry is falsy.
+
+    Raises:
+        ValueError: If metadata dicts do not include a valid path.
+    """
+    if not entry:
+        return None
+
+    if isinstance(entry, str):
+        return {"path": entry}
+
+    if isinstance(entry, dict):
+        path = entry.get("path") or entry.get("local_path")
+        if not isinstance(path, str) or not path:
+            raise ValueError("file metadata dicts must include a non-empty 'path'")
+        return {
+            "path": path,
+            "filename": entry.get("filename"),
+            "s3_url": entry.get("s3_url") or entry.get("url") or entry.get("file_uri"),
+            "expires_in_hours": entry.get("expires_in_hours"),
+        }
+
+    raise ValueError("files must be a list of strings or dicts")
+
+
+def _dedupe_file_entries(files: list[str | dict[str, object]]) -> list[dict[str, object]]:
+    """Normalize and deduplicate file entries by their resolved path.
+
+    Args:
+        files: List of local filesystem paths or file metadata dicts.
+
+    Returns:
+        Deduplicated list of normalized dict entries.
+    """
+    seen: set[str] = set()
+    deduped_entries: list[dict[str, object]] = []
+
+    for raw_entry in files:
+        try:
+            normalized = _normalize_file_entry(raw_entry)
+        except ValueError as exc:
+            logger.warning(f"Skipping invalid file entry: {exc}")
+            continue
+        if not normalized:
+            continue
+        path_value = normalized.get("path")
+        path = path_value if isinstance(path_value, str) else str(path_value)
+        if path in seen:
+            continue
+        seen.add(path)
+        deduped_entries.append(normalized)
+
+    return deduped_entries
+
+
+def _format_expiration_hours(expires_in_hours: object) -> tuple[object, str]:
+    """Format expiration hours for display.
+
+    Args:
+        expires_in_hours: Expiration hours value.
+
+    Returns:
+        Tuple of (expires_value, hour_unit).
+    """
+    if isinstance(expires_in_hours, int):
+        return expires_in_hours, "hour" if expires_in_hours == 1 else "hours"
+
+    if isinstance(expires_in_hours, str) and expires_in_hours.isdigit():
+        expires_value = int(expires_in_hours)
+        return expires_value, "hour" if expires_value == 1 else "hours"
+
+    return "unknown", "hours"
+
+
+def _build_file_path_note(entry: dict[str, object]) -> str:
+    """Build the system note for a file path entry.
+
+    Args:
+        entry: Normalized file metadata dict.
+
+    Returns:
+        System note string describing the file path accessibility.
+    """
+    path = str(entry["path"])
+    is_accessible = os.path.isfile(path) and os.access(path, os.R_OK)
+    if is_accessible:
+        filename_value = entry.get("filename")
+        filename = filename_value if isinstance(filename_value, str) and filename_value else os.path.basename(path)
+        return FILE_PATH_SYSTEM_NOTE.format(filename=filename, path=path)
+
+    logger.warning(f"File path is not accessible: {path}")
+    return FILE_PATH_INACCESSIBLE_NOTE.format(path=path)
+
+
+def _build_file_url_note(entry: dict[str, object]) -> str:
+    """Build the system note for a file URL entry.
+
+    Args:
+        entry: Normalized file metadata dict.
+
+    Returns:
+        System note string describing the URL, or an empty string if no URL exists.
+    """
+    url = entry.get("s3_url")
+    if not isinstance(url, str) or not url:
+        return ""
+
+    expires_value, hour_unit = _format_expiration_hours(entry.get("expires_in_hours"))
+    return FILE_URL_SYSTEM_NOTE.format(
+        url=url,
+        expires_in=expires_value,
+        hour_unit=hour_unit,
+    )
+
+
+def augment_query_with_file_paths(query: str, files: list[str | dict[str, object]]) -> str:
+    """Augment query with file path system notes.
+
+    Args:
+        query: The original user query string.
+        files: List of local filesystem paths or file metadata dicts to include.
+
+    Returns:
+        The query with system notes appended for each file path.
+
+    Raises:
+        ValueError: If files is not a list of strings or metadata dicts.
+    """
+    if not isinstance(files, list):
+        raise ValueError("files must be a list of strings or dicts")
+
+    deduped_entries = _dedupe_file_entries(files)
+
+    if not deduped_entries:
+        return query
+
+    augmented_query = query
+    for entry in deduped_entries:
+        augmented_query += _build_file_path_note(entry)
+        augmented_query += _build_file_url_note(entry)
+
+    return augmented_query

aip_agents/utils/file_prompt_utils.pyi

@@ -0,0 +1,21 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+FILE_PATH_SYSTEM_NOTE: str
+FILE_PATH_INACCESSIBLE_NOTE: str
+FILE_URL_SYSTEM_NOTE: str
+
+def augment_query_with_file_paths(query: str, files: list[str | dict[str, object]]) -> str:
+    """Augment query with file path system notes.
+
+    Args:
+        query: The original user query string.
+        files: List of local filesystem paths or file metadata dicts to include.
+
+    Returns:
+        The query with system notes appended for each file path.
+
+    Raises:
+        ValueError: If files is not a list of strings or metadata dicts.
+    """

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)