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

aip_agents/a2ui/models.py

@@ -0,0 +1,153 @@
+"""A2UI data and action models.
+
+These models represent the minimal runtime contract for A2UI validation across
+the supported standard-catalog schema versions (v0.8, v0.9) and public
+URL-backed custom catalogs.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from a2ui.schema.constants import VERSION_0_9
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from aip_agents.a2ui.public_url import validate_public_url_shape
+
+ModelConfig = ConfigDict(extra="allow")
+
+STANDARD_SCHEMA_VERSION = VERSION_0_9
+
+
+class A2UIContentMetadataStatus(StrEnum):
+    """Status of the A2UI content metadata."""
+
+    VALID = "valid"
+    FALLBACK = "fallback"
+
+
+class A2UIActionStatus(StrEnum):
+    """Status of the A2UI action."""
+
+    VALID = "valid"
+    INVALID = "invalid"
+
+
+class A2UICatalogConfig(BaseModel):
+    """Public URL-backed catalog configuration with optional example fixtures."""
+
+    catalog_url: str
+    example_urls: list[str] = Field(default_factory=list)
+
+    model_config = ModelConfig
+
+    @field_validator("catalog_url")
+    @classmethod
+    def _validate_catalog_url(cls, value: str) -> str:
+        validate_public_url_shape(value)
+        return value
+
+    @field_validator("example_urls")
+    @classmethod
+    def _validate_example_urls(cls, value: list[str]) -> list[str]:
+        for url in value:
+            validate_public_url_shape(url)
+        return value
+
+
+class A2UIContext(BaseModel):
+    """Agent-provided A2UI capability context."""
+
+    enabled: bool = False
+    schema_version: str = STANDARD_SCHEMA_VERSION
+    catalog_configs: list[A2UICatalogConfig] = Field(default_factory=list)
+    allow_user_actions: bool = True
+    fallback_to_text: bool = True
+
+    model_config = ModelConfig
+
+
+class A2UIContentMetadata(BaseModel):
+    """Final-response metadata payload stored in ``metadata.a2ui_content``."""
+
+    schema_version: str = STANDARD_SCHEMA_VERSION
+    messages: list[dict[str, Any]]
+    validation: dict[str, Any] | None = None
+
+    model_config = ModelConfig
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if the content is valid."""
+        return bool(self.validation and self.validation.get("status") == A2UIContentMetadataStatus.VALID)
+
+
+class A2UIActionContext(BaseModel):
+    """Normalized inbound `userAction` context."""
+
+    name: str
+    surface_id: str
+    source_component_id: str
+    timestamp: str
+    context: dict[str, Any] | None = None
+
+    model_config = ModelConfig
+
+    @classmethod
+    def from_normalized_payload(
+        cls, name: str, surface_id: str, source_component_id: str, timestamp: str, context: Any
+    ) -> A2UIActionContext:
+        """Create an action context from a normalized payload."""
+        if not isinstance(context, dict):
+            context_dict: dict[str, Any] = {}
+        else:
+            context_dict = context
+
+        if not timestamp:
+            raise ValueError("timestamp is required")
+        normalized_timestamp = _normalize_iso_timestamp(timestamp)
+
+        return cls(
+            name=name,
+            surface_id=surface_id,
+            source_component_id=source_component_id,
+            timestamp=normalized_timestamp,
+            context=context_dict,
+        )
+
+
+class A2UIActionValidationResult(BaseModel):
+    """Result container for inbound action normalization."""
+
+    status: A2UIActionStatus = A2UIActionStatus.VALID
+    normalized_action: A2UIActionContext | None = None
+    errors: list[str] = Field(default_factory=list)
+
+    model_config = ModelConfig
+
+
+def _normalize_iso_timestamp(value: str) -> str:
+    """Convert incoming timestamp input into a stable ISO-8601 string."""
+    try:
+        normalized = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+        return normalized.isoformat()
+    except Exception:
+        raise ValueError("timestamp must be ISO-8601 parsable")
+
+
+__all__ = [
+    "A2UICatalogConfig",
+    "A2UIContext",
+    "A2UIContentMetadata",
+    "A2UIActionContext",
+    "A2UIActionValidationResult",
+    "A2UIContentMetadataStatus",
+    "A2UIActionStatus",
+    "STANDARD_SCHEMA_VERSION",
+    "_normalize_iso_timestamp",
+]

aip_agents/a2ui/public_url.py

@@ -0,0 +1,138 @@
+"""Public HTTP/HTTPS URL validation for A2UI catalog and example endpoints.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from urllib.parse import urlparse
+
+import requests
+
+_BLOCKED_HOSTNAMES = frozenset({"localhost", "metadata"})
+
+DEFAULT_PUBLIC_URL_FETCH_TIMEOUT_SECONDS = 10.0
+
+
+def _is_non_public_ip(address: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    return (
+        address.is_private
+        or address.is_loopback
+        or address.is_link_local
+        or address.is_multicast
+        or address.is_reserved
+        or address.is_unspecified
+    )
+
+
+def _reject_blocked_hostname(hostname: str) -> None:
+    normalized = hostname.rstrip(".").lower()
+    if normalized in _BLOCKED_HOSTNAMES or normalized.endswith(".localhost") or normalized.endswith(".internal"):
+        raise ValueError(f"Non-public URL host is not allowed: {hostname}")
+
+
+def _reject_literal_non_public_ip(hostname: str) -> None:
+    normalized = hostname.rstrip(".").lower()
+    try:
+        ip_address = ipaddress.ip_address(normalized)
+    except ValueError:
+        return
+
+    if _is_non_public_ip(ip_address):
+        raise ValueError(f"Non-public URL host is not allowed: {hostname}")
+
+
+def _resolve_host_addresses(hostname: str) -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    try:
+        addrinfos = socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM)
+    except socket.gaierror as exc:
+        raise ValueError(f"Could not resolve URL host: {hostname}") from exc
+
+    addresses: list[ipaddress.IPv4Address | ipaddress.IPv6Address] = []
+    seen: set[str] = set()
+
+    for _family, _type, _proto, _canonname, sockaddr in addrinfos:
+        ip_str = sockaddr[0]
+        if ip_str in seen:
+            continue
+        seen.add(ip_str)
+
+        try:
+            addresses.append(ipaddress.ip_address(ip_str))
+        except ValueError:
+            continue
+
+    if not addresses:
+        raise ValueError(f"Could not resolve URL host: {hostname}")
+
+    return addresses
+
+
+def validate_public_url_shape(url: str) -> None:
+    """Reject invalid URL schemes and obviously non-public host forms without DNS."""
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"Unsupported URL scheme: {url}")
+
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError(f"Invalid URL: {url}")
+
+    _reject_blocked_hostname(hostname)
+    _reject_literal_non_public_ip(hostname)
+
+
+def validate_public_url(url: str) -> None:
+    """Reject non-public URL schemes and hosts, including DNS-resolved hostnames."""
+    validate_public_url_shape(url)
+    hostname = urlparse(url).hostname
+    if not hostname:
+        raise ValueError(f"Invalid URL: {url}")
+
+    normalized = hostname.rstrip(".").lower()
+    try:
+        ipaddress.ip_address(normalized)
+    except ValueError:
+        for resolved in _resolve_host_addresses(normalized):
+            if _is_non_public_ip(resolved):
+                raise ValueError(f"Non-public URL host is not allowed: {hostname}")
+
+
+def fetch_public_url(
+    url: str,
+    *,
+    session: requests.Session | None = None,
+    timeout: float = DEFAULT_PUBLIC_URL_FETCH_TIMEOUT_SECONDS,
+) -> requests.Response:
+    """Fetch a validated public URL without following redirects."""
+    try:
+        validate_public_url(url)
+    except ValueError as exc:
+        raise OSError(f"Invalid public URL {url}: {exc}") from exc
+
+    http_session = session or requests.Session()
+    try:
+        response = http_session.get(url, timeout=timeout, allow_redirects=False)
+    except requests.RequestException as exc:
+        raise OSError(f"Could not fetch public URL {url}: {exc}") from exc
+
+    if 300 <= response.status_code < 400:
+        raise OSError(f"Redirect responses are not allowed for public URL: {url}")
+
+    try:
+        response.raise_for_status()
+    except requests.RequestException as exc:
+        raise OSError(f"Could not fetch public URL {url}: {exc}") from exc
+
+    return response
+
+
+__all__ = [
+    "DEFAULT_PUBLIC_URL_FETCH_TIMEOUT_SECONDS",
+    "fetch_public_url",
+    "validate_public_url",
+    "validate_public_url_shape",
+]

aip_agents/a2ui/stream_filter.py

@@ -0,0 +1,67 @@
+"""Incremental A2UI markup suppression for token streaming.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from a2ui.schema.constants import A2UI_CLOSE_TAG, A2UI_OPEN_TAG
+
+
+class A2UIStreamTextFilter:
+    """Strip ``<a2ui-json>`` regions from streamed text chunks.
+
+    The filter buffers partial open/close tag boundaries across chunks so token
+    streaming can stay text-oriented while final-response middleware remains the
+    authoritative A2UI validation path.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the A2UI stream text filter."""
+        self._buffer = ""
+        self._inside_a2ui = False
+
+    def feed(self, chunk: str) -> str:
+        """Return visible text extracted from ``chunk``, suppressing A2UI regions."""
+        if not chunk:
+            return ""
+
+        self._buffer += chunk
+        visible_parts: list[str] = []
+
+        while self._buffer:
+            if self._inside_a2ui:
+                close_index = self._buffer.find(A2UI_CLOSE_TAG)
+                if close_index == -1:
+                    _, self._buffer = _split_partial_tag_suffix(self._buffer, A2UI_CLOSE_TAG)
+                    break
+
+                self._buffer = self._buffer[close_index + len(A2UI_CLOSE_TAG) :]
+                self._inside_a2ui = False
+                continue
+
+            open_index = self._buffer.find(A2UI_OPEN_TAG)
+            if open_index == -1:
+                safe_text, self._buffer = _split_partial_tag_suffix(self._buffer, A2UI_OPEN_TAG)
+                if safe_text:
+                    visible_parts.append(safe_text)
+                break
+
+            if open_index > 0:
+                visible_parts.append(self._buffer[:open_index])
+
+            self._buffer = self._buffer[open_index + len(A2UI_OPEN_TAG) :]
+            self._inside_a2ui = True
+
+        return "".join(visible_parts)
+
+
+def _split_partial_tag_suffix(text: str, tag: str) -> tuple[str, str]:
+    """Emit safe prefix text and retain a possible partial tag suffix."""
+    max_suffix = len(tag) - 1
+    for suffix_len in range(min(len(text), max_suffix), 0, -1):
+        suffix = text[-suffix_len:]
+        if tag.startswith(suffix):
+            return text[:-suffix_len], suffix
+    return text, ""

aip_agents/agent/__init__.py

@@ -0,0 +1,72 @@
+"""This module initializes the agent package.
+
+Exposes the core agent classes and interfaces.
+
+Author:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from typing import TYPE_CHECKING, Any
+
+from aip_agents.agent.base_agent import BaseAgent
+from aip_agents.agent.google_adk_constants import GOOGLE_ADK_IMPORT_ERROR_MESSAGE
+
+if TYPE_CHECKING:
+    from aip_agents.agent.google_adk_agent import GoogleADKAgent
+    from aip_agents.agent.langflow_agent import LangflowAgent
+from aip_agents.agent.base_langgraph_agent import BaseLangGraphAgent
+from aip_agents.agent.interface import AgentInterface
+from aip_agents.agent.langgraph_react_agent import (
+    LangChainAgent,
+    LangGraphAgent,
+    LangGraphReactAgent,
+)
+
+__all__ = [
+    "AgentInterface",
+    "BaseAgent",
+    "BaseLangGraphAgent",
+    "LangGraphReactAgent",
+    "LangGraphAgent",
+    "LangChainAgent",
+    "LangflowAgent",
+]
+
+if importlib.util.find_spec("google.adk") is not None:
+    __all__.append("GoogleADKAgent")
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import of heavy agent implementations.
+
+    This avoids importing heavy dependencies (Google ADK, etc.)
+    when they are not needed.
+
+    Args:
+        name: Attribute name to import.
+
+    Returns:
+        The requested class.
+
+    Raises:
+        AttributeError: If attribute is not found.
+    """
+    if name == "GoogleADKAgent":
+        try:
+            from aip_agents.agent.google_adk_agent import (
+                GoogleADKAgent as _GoogleADKAgent,
+            )
+        except ModuleNotFoundError as e:
+            if e.name and e.name.startswith("google"):
+                raise ImportError(GOOGLE_ADK_IMPORT_ERROR_MESSAGE) from e
+            raise
+
+        return _GoogleADKAgent
+    elif name == "LangflowAgent":
+        from aip_agents.agent.langflow_agent import LangflowAgent as _LangflowAgent
+
+        return _LangflowAgent
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")