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

aip_agents/schema/hitl.py

@@ -0,0 +1,157 @@
+"""Schema definitions for Human-in-the-Loop approval workflows."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "ApprovalDecisionType",
+    "ApprovalRequest",
+    "ApprovalDecision",
+    "ApprovalLogEntry",
+    "HitlMetadata",
+]
+
+
+class ApprovalDecisionType(StrEnum):
+    """Enumeration of possible approval decision types."""
+
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    SKIPPED = "skipped"
+    TIMEOUT_SKIP = "timeout_skip"
+    PENDING = "pending"
+
+
+@dataclass
+class ApprovalRequest:
+    """Represents an in-flight prompt shown to the operator."""
+
+    request_id: str
+    tool_name: str
+    arguments_preview: str
+    context: dict[str, str] | None = None
+    created_at: datetime | None = None
+    timeout_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize timestamps if not provided."""
+        if self.created_at is None:
+            self.created_at = datetime.now()
+        if self.timeout_at is None and self.created_at is not None:
+            # Timeout is set externally when configuration is available
+            pass
+
+    @classmethod
+    def create(
+        cls,
+        tool_name: str,
+        arguments_preview: str,
+        context: dict[str, str] | None = None,
+    ) -> "ApprovalRequest":
+        """Create a new approval request with generated request_id.
+
+        Args:
+            tool_name (str): The name of the tool requiring approval.
+            arguments_preview (str): A preview of the arguments for display.
+            context (dict[str, str] | None, optional): Additional context information.
+
+        Returns:
+            ApprovalRequest: A new approval request instance.
+        """
+        return cls(
+            request_id=str(uuid4()),
+            tool_name=tool_name,
+            arguments_preview=arguments_preview,
+            context=context,
+        )
+
+
+@dataclass
+class ApprovalDecision:
+    """Captures the operator outcome."""
+
+    request_id: str
+    decision: ApprovalDecisionType
+    operator_input: str
+    decided_at: datetime | None = None
+    latency_ms: int | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize timestamp if not provided."""
+        if self.decided_at is None:
+            self.decided_at = datetime.now()
+
+
+@dataclass
+class ApprovalLogEntry:
+    """Structured log entry for HITL decisions."""
+
+    request_id: str
+    tool_name: str
+    decision: str
+    event: str = "hitl_decision"
+    agent_id: str | None = None
+    thread_id: str | None = None
+    additional_context: dict[str, Any] | None = None
+    timestamp: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize timestamp if not provided."""
+        if self.timestamp is None:
+            self.timestamp = datetime.now()
+
+
+class HitlMetadata(BaseModel):
+    """Structured metadata payload included in agent streaming events."""
+
+    required: bool = Field(default=True)
+    decision: ApprovalDecisionType
+    request_id: str
+    timeout_seconds: int | None = Field(default=None, ge=0)
+    timeout_at: datetime | None = None
+
+    model_config = ConfigDict(extra="forbid", use_enum_values=True)
+
+    def as_payload(self) -> dict[str, Any]:
+        """Return a JSON-ready metadata payload."""
+        payload = self.model_dump(mode="json", exclude_none=True)
+
+        # Pydantic emits UTC datetimes as Zulu strings when dumping to JSON.
+        # Preserve the canonical ``+00:00`` suffix expected by downstream tests.
+        if "timeout_at" in payload and isinstance(self.timeout_at, datetime):
+            payload["timeout_at"] = self.timeout_at.isoformat()
+
+        return payload
+
+    @classmethod
+    def from_decision(
+        cls,
+        decision: ApprovalDecision,
+        *,
+        required: bool = True,
+        timeout_seconds: int | None = None,
+        timeout_at: datetime | None = None,
+    ) -> "HitlMetadata":
+        """Build metadata from an ``ApprovalDecision``.
+
+        Args:
+            decision (ApprovalDecision): The approval decision to build metadata from.
+            required (bool, optional): Whether approval is required. Defaults to True.
+            timeout_seconds (int | None, optional): Timeout in seconds for the decision.
+            timeout_at (datetime | None, optional): Specific timeout datetime.
+
+        Returns:
+            HitlMetadata: The constructed metadata instance.
+        """
+        return cls(
+            required=required,
+            decision=decision.decision,
+            request_id=decision.request_id,
+            timeout_seconds=timeout_seconds,
+            timeout_at=timeout_at,
+        )

aip_agents/schema/langgraph.py

@@ -0,0 +1,47 @@
+"""LangGraph-related schema definitions for agent tool interactions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from gllm_core.schema import Chunk
+from langchain_core.messages import ToolMessage
+from langchain_core.messages.ai import UsageMetadata
+from langchain_core.tools import BaseTool
+
+from aip_agents.schema.artifacts import ArtifactPayload
+from aip_agents.schema.model_usage import ModelUsageDelta, ModelUsageRow
+from aip_agents.schema.runtime_metadata import RuntimeMetadata
+
+__all__ = ["ToolCallResult", "ToolStorageParams"]
+
+
+@dataclass
+class ToolCallResult:
+    """Container for the results of a single tool call execution."""
+
+    messages: list[ToolMessage]
+    artifacts: list[ArtifactPayload]
+    # Standard event keys are typed via RuntimeMetadata. Transient internal or
+    # tool-injected keys (e.g. ``previous_step_ids``) may also ride along here;
+    # they are merged into the accumulator and consumed/stripped downstream, not
+    # read off this field.
+    metadata_delta: RuntimeMetadata
+    references: list[Chunk]
+    step_usage: UsageMetadata | None
+    model_usage_delta: ModelUsageDelta | None = None
+    model_usage: list[ModelUsageRow] | None = None
+    pii_mapping: dict[str, str] | None = None
+
+
+@dataclass
+class ToolStorageParams:
+    """Parameters required for automatically storing tool outputs."""
+
+    tool: BaseTool
+    tool_output: Any
+    tool_call: dict[str, Any]
+    tool_call_id: str
+    resolved_args: dict[str, Any]
+    state: dict[str, Any]

aip_agents/schema/model_id.py

@@ -0,0 +1,103 @@
+"""Model identifiers and provider definitions for the AI agent platform."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ModelProvider(StrEnum):
+    """Enumeration of supported model providers for the AI agent platform."""
+
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    AZURE_OPENAI = "azure-openai"
+    GOOGLE_GENAI = "google"
+    GROQ = "groq"
+    TOGETHER_AI = "together"
+    DEEPINFRA = "deepinfra"
+    DEEPSEEK = "deepseek"
+    OPENAI_COMPATIBLE = "openai-compatible"
+
+
+class ModelId:
+    """Model identifier class for representing language models."""
+
+    def __init__(self, provider: str, name: str, path: str | None = None):
+        """Initialize a ModelId.
+
+        Args:
+            provider: The model provider (e.g., 'openai', 'anthropic')
+            name: The specific model name
+            path: Optional path component for some providers
+        """
+        self.provider = provider
+        self.name = name
+        self.path = path
+
+    @classmethod
+    def from_string(cls, model_string: str) -> ModelId:
+        """Create a ModelId from a string representation.
+
+        Args:
+            model_string: String in format 'provider/name' or 'provider/path:name'
+
+        Returns:
+            ModelId instance
+
+        Raises:
+            ValueError: If the string format is invalid
+        """
+        if "/" not in model_string:
+            raise ValueError(
+                f"Invalid model string format: {model_string}. Expected 'provider/name' or 'provider/path:name'"
+            )
+
+        provider, remainder = model_string.split("/", 1)
+
+        if ":" in remainder:
+            last_colon_idx = remainder.rindex(":")
+            potential_path = remainder[:last_colon_idx]
+            # Only treat ':' as a path/name separator when the left side contains '/',
+            # which indicates a URL or sub-path. A bare ':' inside a model name (e.g.
+            # bedrock's 'us.anthropic.claude-...-v1:0') is part of the name itself.
+            if "/" in potential_path:
+                path = potential_path
+                name = remainder[last_colon_idx + 1 :]
+            else:
+                path = None  # pragma: no cover
+                name = remainder  # pragma: no cover
+        else:
+            path = None
+            name = remainder
+
+        return cls(provider, name, path)
+
+    def __str__(self) -> str:
+        """String representation of the ModelId."""
+        if self.path:
+            return f"{self.provider}/{self.path}:{self.name}"
+        return f"{self.provider}/{self.name}"
+
+    def __repr__(self) -> str:
+        """String representation of the ModelId for debugging."""
+        return f"ModelId(provider='{self.provider}', name='{self.name}', path='{self.path}')"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality with another ModelId object.
+
+        Args:
+            other (object): The object to compare with.
+
+        Returns:
+            bool: True if the objects are equal, False otherwise.
+        """
+        if not isinstance(other, ModelId):
+            return NotImplemented
+        return self.provider == other.provider and self.name == other.name and self.path == other.path
+
+    def __hash__(self) -> int:
+        """Return hash of the ModelId."""
+        return hash((self.provider, self.name, self.path))
+
+
+__all__ = ["ModelId", "ModelProvider"]

aip_agents/schema/model_usage.py

@@ -0,0 +1,50 @@
+"""Schema contracts for model-level usage reporting.
+
+These types define a stable contract for per-call model usage deltas and
+final aggregated model usage rows.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ModelUsageDelta(TypedDict, total=False):
+    """Per-model-call usage delta emitted by runtime paths.
+
+    Fields intentionally mirror usage metadata counters while adding model
+    identity and a dedupe key (`usage_call_id`).
+    """
+
+    provider: str
+    model_name: str
+    model_id: str
+    language_model_id: str | None
+    usage_call_id: str
+    source: str
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    input_token_details: dict[str, int]
+    output_token_details: dict[str, int]
+
+
+class ModelUsageRow(TypedDict, total=False):
+    """Final run-level model usage row aggregated by model identity."""
+
+    provider: str
+    model_name: str
+    model_id: str
+    language_model_id: str | None
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    usage_call_ids: list[str]
+    input_token_details: dict[str, int]
+    output_token_details: dict[str, int]
+
+
+__all__ = ["ModelUsageDelta", "ModelUsageRow"]

aip_agents/schema/runtime_metadata.py

@@ -0,0 +1,78 @@
+"""Shared typed contracts for runtime metadata payloads.
+
+These contracts name the metadata dict shapes currently typed as
+``dict[str, Any]`` in ``aip_agents.utils.metadata_helper``. The canonical key
+set is governed by ``metadata_helper.MetadataFieldKeys``; this module keeps
+``schema/`` a pure leaf package by defining the TypedDict with string-literal
+keys that match those enum values instead of importing from ``utils/`` (which
+would invert the dependency direction).
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+from aip_agents.schema.a2a import ToolCallInfo, ToolResultInfo
+from aip_agents.schema.attachments import AttachmentEntryPayload
+from aip_agents.schema.model_usage import ModelUsageDelta, ModelUsageRow
+
+__all__ = [
+    "LocalizedMessages",
+    "RuntimeMetadata",
+]
+
+
+class LocalizedMessages(TypedDict):
+    """Localized message content produced by ``metadata_helper._create_message_metadata``."""
+
+    en: str
+    id: str
+
+
+class RuntimeMetadata(TypedDict, total=False):
+    """Runtime metadata dict exchanged across agent steps and A2A events.
+
+    Keys track ``metadata_helper.MetadataFieldKeys`` plus three additional
+    families that have no ``MetadataFieldKeys`` entry:
+
+    - ``attachments`` / ``attachment_registry``: merged in by the attachment
+      helpers.
+    - ``previous_step_ids`` / ``step_id`` / ``agent_name``: transient linkage
+      keys injected by the legacy-metadata (``_process_legacy_metadata``) and
+      task-delegation paths. They ride on this dict only to be merged into the
+      accumulator and consumed/stripped downstream — they are not read as event
+      fields, but they *are* real keys on the dict, so declaring them keeps the
+      contract honest instead of lying about a closed key set.
+
+    ``tool_info`` reuses ``ToolCallInfo`` / ``ToolResultInfo`` from
+    ``schema.a2a`` — the exact shapes the agent emits for tool-call and
+    tool-result metadata events — rather than re-declaring them.
+
+    All keys are optional because different event kinds populate different
+    subsets; callers that need a required key should validate explicitly.
+    """
+
+    kind: str
+    status: str
+    time: float
+    message: LocalizedMessages
+    tool_info: ToolCallInfo | ToolResultInfo
+    references: list[Any]
+    thinking_and_activity_info: dict[str, Any]
+    hitl: dict[str, Any]
+    step_usage: dict[str, Any]
+    total_usage: dict[str, Any]
+    model_usage_delta: ModelUsageDelta | None
+    model_usage: list[ModelUsageRow]
+    token_streaming: bool
+    canonical: dict[str, Any]
+    pii_mapping: dict[str, str]
+    # Transient linkage keys (no MetadataFieldKeys entry); see class docstring.
+    previous_step_ids: list[str]
+    step_id: str
+    agent_name: str
+    attachments: list[AttachmentEntryPayload]
+    attachment_registry: dict[str, AttachmentEntryPayload]

aip_agents/schema/step_limit.py

@@ -0,0 +1,108 @@
+"""Step limit configuration and error classes for agent execution limits."""
+
+import os
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class StepLimitErrorType(StrEnum):
+    """Types of step-related limit violations."""
+
+    STEP_LIMIT_EXCEEDED = "STEP_LIMIT_EXCEEDED"
+    DELEGATION_DEPTH_EXCEEDED = "DELEGATION_DEPTH_EXCEEDED"
+
+
+@dataclass
+class StepLimitConfig:
+    """Configuration for agent step and delegation limits.
+
+    Attributes:
+        max_steps: Maximum number of execution steps allowed per invocation.
+                   Includes agent node (LLM call) and every tool call (parallel batches count per call).
+        max_delegation_depth: Maximum depth of delegation chain allowed.
+                              Depth 0 means no delegation allowed.
+    """
+
+    max_steps: int = field(
+        default_factory=lambda: int(os.getenv("STEP_LIMIT_MAX_STEPS_DEFAULT", "100")),
+    )
+    max_delegation_depth: int = field(
+        default_factory=lambda: int(os.getenv("STEP_LIMIT_MAX_DELEGATION_DEPTH_DEFAULT", "5")),
+    )
+
+    def __post_init__(self):
+        """Validate configuration values and normalize range."""
+        from aip_agents.utils.logger import get_logger
+
+        logger = get_logger(__name__)
+
+        # Validate and clamp max_steps
+        if self.max_steps < 1:
+            logger.warning(f"Invalid max_steps={self.max_steps}, resetting to default (25). max_steps must be >= 1.")
+            self.max_steps = 25
+        elif self.max_steps > 1000:
+            logger.warning(f"Invalid max_steps={self.max_steps}, capping at 1000.")
+            self.max_steps = 1000
+
+        # Validate and clamp max_delegation_depth
+        if self.max_delegation_depth < 0:
+            logger.warning(
+                f"Invalid max_delegation_depth={self.max_delegation_depth}, resetting to default (5). "
+                "max_delegation_depth must be >= 0."
+            )
+            self.max_delegation_depth = 5
+        elif self.max_delegation_depth > 10:
+            logger.warning(f"Invalid max_delegation_depth={self.max_delegation_depth}, capping at 10.")
+            self.max_delegation_depth = 10
+
+
+@dataclass
+class StepLimitErrorResponse:
+    """Structured error response for step limit violations.
+
+    Attributes:
+        error_type: The type of limit that was exceeded.
+        agent_name: Name of the agent that hit the limit.
+        current_value: Current step count or delegation depth.
+        configured_limit: The configured limit that was exceeded.
+        message: Human-readable error message.
+        delegation_chain: Full chain for delegation errors.
+        partial_result: Any output generated before hitting the limit.
+    """
+
+    error_type: StepLimitErrorType
+    agent_name: str
+    current_value: int
+    configured_limit: int
+    message: str
+    delegation_chain: list[str] | None = None
+    partial_result: str | None = None
+
+
+class StepLimitError(Exception):
+    """Base exception for step and delegation limit violations.
+
+    Attributes:
+        error_response: Structured error response with details.
+    """
+
+    def __init__(self, error_response: StepLimitErrorResponse):
+        """Initialize with error response.
+
+        Args:
+            error_response: Structured error details.
+        """
+        self.error_response = error_response
+        super().__init__(error_response.message)
+
+
+class MaxStepsExceededError(StepLimitError):
+    """Raised when agent exceeds configured max_steps limit."""
+
+    pass
+
+
+class MaxDelegationDepthExceededError(StepLimitError):
+    """Raised when delegation would exceed max_delegation_depth limit."""
+
+    pass

aip_agents/schema/storage.py

@@ -0,0 +1,40 @@
+"""Schema definitions for storage configuration."""
+
+import os
+from dataclasses import dataclass
+from enum import StrEnum
+
+__all__ = ["OBJECT_STORAGE_PREFIX", "StorageType", "StorageConfig"]
+
+OBJECT_STORAGE_PREFIX = "tool_outputs/"
+
+
+class StorageType(StrEnum):
+    """Supported storage types."""
+
+    MEMORY = "memory"
+    OBJECT_STORAGE = "object_storage"
+
+
+@dataclass
+class StorageConfig:
+    """Configuration for storage providers."""
+
+    storage_type: StorageType = StorageType.MEMORY
+    object_prefix: str = OBJECT_STORAGE_PREFIX
+    object_use_json: bool = False
+
+    @classmethod
+    def from_env(cls) -> "StorageConfig":
+        """Create StorageConfig from environment variables."""
+        storage_type_str = os.getenv("TOOL_OUTPUT_STORAGE_TYPE", StorageType.MEMORY.value).lower()
+        if storage_type_str == StorageType.MEMORY.value:
+            storage_type = StorageType.MEMORY
+        else:
+            storage_type = StorageType.OBJECT_STORAGE
+
+        object_prefix = os.getenv("TOOL_OUTPUT_OBJECT_PREFIX", OBJECT_STORAGE_PREFIX)
+        use_json_str = os.getenv("TOOL_OUTPUT_USE_JSON", "false").lower()
+        use_json = use_json_str in ("true", "1", "yes", "on")
+
+        return cls(storage_type=storage_type, object_prefix=object_prefix, object_use_json=use_json)

aip_agents/schema/tool_payloads.py

@@ -0,0 +1,68 @@
+"""Shared typed contracts for tool input/output payloads.
+
+These contracts name the high-fanout tool argument and tool-output summary
+shapes currently typed as ``dict[str, Any]`` in
+``aip_agents.utils.langgraph.tool_output_management`` and the tool-call event
+surfaces. They are intentionally narrow: full value typing for ``ToolArgs`` is
+deferred to a later typing wave.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Required, TypedDict
+
+__all__ = [
+    "ToolArgs",
+    "ToolInvocationPayload",
+    "ToolOutputSummaryEntry",
+    "ToolOutputStorageStats",
+]
+
+ToolArgs = dict[str, Any]
+"""Named alias for the tool-argument payload hotspot.
+
+Narrowing the value type fully is deferred to a later typing wave; naming the
+surface now lets adoption slices reference a single canonical alias.
+"""
+
+
+class ToolInvocationPayload(TypedDict, total=False):
+    """Serialized tool-call invocation shape exchanged with LangGraph tool messages.
+
+    Aligns with the ``tool_call`` dict produced by LangGraph and consumed by
+    ``schema.langgraph.ToolStorageParams.tool_call``. ``name``, ``args``, and
+    ``id`` are always present on a LangGraph tool call (``id`` correlates the
+    call with its ``ToolMessage`` result); ``total=False`` is kept for
+    structural parity with the other payload contracts.
+    """
+
+    name: Required[str]
+    args: Required[ToolArgs]
+    id: Required[str]
+
+
+class ToolOutputSummaryEntry(TypedDict, total=False):
+    """One entry in the JSON summary emitted by ``ToolOutputManager.generate_summary``.
+
+    ``reference`` and ``tool`` are always present; ``description``, ``agent``,
+    and ``data_preview`` are conditional on stored metadata.
+    """
+
+    reference: Required[str]
+    tool: Required[str]
+    description: str
+    agent: str
+    data_preview: str
+
+
+class ToolOutputStorageStats(TypedDict):
+    """Shape returned by ``ToolOutputManager.get_storage_stats``."""
+
+    total_outputs: int
+    total_size_bytes: int
+    external_storage_count: int
+    memory_storage_count: int
+    storage_provider_type: str

aip_agents/sentry/__init__.py

@@ -0,0 +1,11 @@
+"""This module provides a centralized way to handle Sentry and OpenTelemetry configuration for GL Connectors SDK.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from aip_agents.sentry.sentry import setup_telemetry
+
+__all__ = [
+    "setup_telemetry",
+]