aip-agents-binary 0.5.25b1__py3-none-macosx_13_0_arm64.whl

aip_agents/schema/step_limit.pyi

@@ -0,0 +1,63 @@
+from _typeshed import Incomplete
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+class StepLimitErrorType(StrEnum):
+    """Types of step-related limit violations."""
+    STEP_LIMIT_EXCEEDED: str
+    DELEGATION_DEPTH_EXCEEDED: str
+
+@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=Incomplete)
+    max_delegation_depth: int = field(default_factory=Incomplete)
+    def __post_init__(self) -> None:
+        """Validate configuration values and normalize range."""
+
+@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 = ...
+    partial_result: str | None = ...
+
+class StepLimitError(Exception):
+    """Base exception for step and delegation limit violations.
+
+    Attributes:
+        error_response: Structured error response with details.
+    """
+    error_response: Incomplete
+    def __init__(self, error_response: StepLimitErrorResponse) -> None:
+        """Initialize with error response.
+
+        Args:
+            error_response: Structured error details.
+        """
+
+class MaxStepsExceededError(StepLimitError):
+    """Raised when agent exceeds configured max_steps limit."""
+class MaxDelegationDepthExceededError(StepLimitError):
+    """Raised when delegation would exceed max_delegation_depth limit."""

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

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+from enum import StrEnum
+
+__all__ = ['OBJECT_STORAGE_PREFIX', 'StorageType', 'StorageConfig']
+
+OBJECT_STORAGE_PREFIX: str
+
+class StorageType(StrEnum):
+    """Supported storage types."""
+    MEMORY: str
+    OBJECT_STORAGE: str
+
+@dataclass
+class StorageConfig:
+    """Configuration for storage providers."""
+    storage_type: StorageType = ...
+    object_prefix: str = ...
+    object_use_json: bool = ...
+    @classmethod
+    def from_env(cls) -> StorageConfig:
+        """Create StorageConfig from environment variables."""

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",
+]

aip_agents/sentry/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.sentry.sentry import setup_telemetry as setup_telemetry
+
+__all__ = ['setup_telemetry']

aip_agents/sentry/sentry.py

@@ -0,0 +1,151 @@
+"""This file contains the Sentry and OpenTelemetry configuration for GL Connectors SDK.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+import inspect
+import os
+
+from bosa_core.telemetry import (
+    FastAPIConfig,
+    OpenTelemetryConfig,
+    SentryConfig,
+    TelemetryConfig,
+    init_telemetry,
+)
+from bosa_core.telemetry.opentelemetry.instrument.functions import (
+    BOSAFunctionsInstrumentor,
+)
+from dotenv import load_dotenv
+from fastapi import FastAPI
+
+from aip_agents.agent import BaseAgent, GoogleADKAgent, LangChainAgent, LangGraphAgent
+from aip_agents.utils.logger import get_logger
+
+load_dotenv()
+
+
+logger = get_logger(__name__)
+
+SENTRY_DSN = os.getenv("SENTRY_DSN")
+SENTRY_ENVIRONMENT = os.getenv("SENTRY_ENVIRONMENT", "development")
+SENTRY_PROJECT = os.getenv("SENTRY_PROJECT")
+VERSION_NUMBER = os.getenv("VERSION_NUMBER", "0.0.0")
+BUILD_NUMBER = os.getenv("BUILD_NUMBER", "0")
+USE_OPENTELEMETRY = os.getenv("USE_OPENTELEMETRY", "true").lower() == "true"
+
+CLASSES_TO_INSTRUMENT = [
+    BaseAgent,
+    LangGraphAgent,
+    LangChainAgent,
+    GoogleADKAgent,
+]
+
+
+def get_all_methods(cls: type) -> list:
+    """Get all methods from a class.
+
+    Args:
+        cls: The class to get methods from.
+
+    Returns:
+        list: A list of methods.
+    """
+    methods = []
+    for name, member in inspect.getmembers(cls):
+        if name.startswith("_"):
+            continue  # skip dunder and private
+        if inspect.isfunction(member) or inspect.ismethod(member) or inspect.iscoroutinefunction(member):
+            methods.append(member)
+    return methods
+
+
+def instrument_gl_functions() -> None:
+    """Instrument GL functions."""
+    if BOSAFunctionsInstrumentor is None:
+        return
+    agent_methods = []
+    for cls in CLASSES_TO_INSTRUMENT:
+        agent_methods.extend(get_all_methods(cls))
+    BOSAFunctionsInstrumentor().instrument(methods=agent_methods)
+
+
+def traces_sampler(*args) -> float:
+    """Determine appropriate sampling rate for Sentry transactions.
+
+    Args:
+        *args: Additional positional arguments
+
+    Returns:
+        float: Sampling rate between 0 and 1
+    """
+    # TODO: Dont sample healthcheck endpoints (return 0.0)
+    return 1.0
+
+
+def setup_sentry_with_open_telemetry(app: FastAPI) -> None:
+    """Configure telemetry with both Sentry and OpenTelemetry.
+
+    Args:
+        app: FastAPI application instance
+    """
+    try:
+        fastapi_config = FastAPIConfig(app)
+
+        # Create OpenTelemetry configuration
+        opentelemetry_init = OpenTelemetryConfig(
+            use_langchain=True,
+            fastapi_config=fastapi_config,
+        )
+
+        # Sentry configuration with OpenTelemetry
+        sentry_config = SentryConfig(
+            dsn=SENTRY_DSN,
+            traces_sampler=traces_sampler,
+            environment=SENTRY_ENVIRONMENT,
+            release=f"{SENTRY_PROJECT}@{VERSION_NUMBER}+{BUILD_NUMBER}",
+            send_default_pii=True,
+            open_telemetry_config=opentelemetry_init,
+        )
+
+        telemetry_config = TelemetryConfig(sentry_config=sentry_config)
+        init_telemetry(telemetry_config)
+        logger.info(f"Telemetry initialized with OpenTelemetry for environment: {SENTRY_ENVIRONMENT}")
+    except Exception as e:
+        logger.error(f"Failed to initialize telemetry with OpenTelemetry: {e}")
+
+
+def setup_sentry_only() -> None:
+    """Configure telemetry with Sentry only (no OpenTelemetry)."""
+    try:
+        # Sentry configuration without OpenTelemetry
+        sentry_config = SentryConfig(
+            dsn=SENTRY_DSN,
+            traces_sampler=traces_sampler,
+            environment=SENTRY_ENVIRONMENT,
+            release=f"{SENTRY_PROJECT}@{VERSION_NUMBER}+{BUILD_NUMBER}",
+            send_default_pii=True,
+        )
+
+        telemetry_config = TelemetryConfig(sentry_config=sentry_config)
+        init_telemetry(telemetry_config)
+        logger.info(f"Telemetry initialized with Sentry only for environment: {SENTRY_ENVIRONMENT}")
+    except Exception as e:
+        logger.error(f"Failed to initialize telemetry with Sentry only: {e}")
+
+
+def setup_telemetry(app: FastAPI) -> None:
+    """Configure and initialize telemetry based on configuration.
+
+    Args:
+        app: FastAPI application instance
+    """
+    if not SENTRY_DSN:
+        logger.warning("Warning: SENTRY_DSN not set. Sentry will not be enabled.")
+        return
+    if USE_OPENTELEMETRY:
+        setup_sentry_with_open_telemetry(app)
+    else:
+        setup_sentry_only()
+    instrument_gl_functions()

aip_agents/sentry/sentry.pyi

@@ -0,0 +1,48 @@
+from _typeshed import Incomplete
+from aip_agents.agent import BaseAgent as BaseAgent, GoogleADKAgent as GoogleADKAgent, LangChainAgent as LangChainAgent, LangGraphAgent as LangGraphAgent
+from aip_agents.utils.logger import get_logger as get_logger
+from fastapi import FastAPI
+
+logger: Incomplete
+SENTRY_DSN: Incomplete
+SENTRY_ENVIRONMENT: Incomplete
+SENTRY_PROJECT: Incomplete
+VERSION_NUMBER: Incomplete
+BUILD_NUMBER: Incomplete
+USE_OPENTELEMETRY: Incomplete
+CLASSES_TO_INSTRUMENT: Incomplete
+
+def get_all_methods(cls) -> list:
+    """Get all methods from a class.
+
+    Args:
+        cls: The class to get methods from.
+
+    Returns:
+        list: A list of methods.
+    """
+def instrument_gl_functions() -> None:
+    """Instrument GL functions."""
+def traces_sampler(*args) -> float:
+    """Determine appropriate sampling rate for Sentry transactions.
+
+    Args:
+        *args: Additional positional arguments
+
+    Returns:
+        float: Sampling rate between 0 and 1
+    """
+def setup_sentry_with_open_telemetry(app: FastAPI) -> None:
+    """Configure telemetry with both Sentry and OpenTelemetry.
+
+    Args:
+        app: FastAPI application instance
+    """
+def setup_sentry_only() -> None:
+    """Configure telemetry with Sentry only (no OpenTelemetry)."""
+def setup_telemetry(app: FastAPI) -> None:
+    """Configure and initialize telemetry based on configuration.
+
+    Args:
+        app: FastAPI application instance
+    """

aip_agents/storage/__init__.py

@@ -0,0 +1,41 @@
+"""Storage module for aip_agents.
+
+This module provides comprehensive storage functionality including object storage
+clients, storage providers for tool outputs, and configuration management.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+# Object storage clients
+from aip_agents.storage.base import BaseObjectStorageClient
+from aip_agents.storage.clients.minio_client import MinioConfig, MinioObjectStorage
+
+# Configuration and factory
+from aip_agents.storage.config import (
+    StorageConfig,
+    StorageProviderFactory,
+    StorageType,
+)
+
+# Storage providers
+from aip_agents.storage.providers.base import BaseStorageProvider, StorageError
+from aip_agents.storage.providers.memory import InMemoryStorageProvider
+from aip_agents.storage.providers.object_storage import ObjectStorageProvider
+
+__all__ = [
+    # Object storage
+    "BaseObjectStorageClient",
+    "MinioConfig",
+    "MinioObjectStorage",
+    # Storage providers
+    "BaseStorageProvider",
+    "StorageError",
+    "InMemoryStorageProvider",
+    "ObjectStorageProvider",
+    # Configuration
+    "StorageConfig",
+    "StorageType",
+    "StorageProviderFactory",
+]

aip_agents/storage/__init__.pyi

@@ -0,0 +1,8 @@
+from aip_agents.storage.base import BaseObjectStorageClient as BaseObjectStorageClient
+from aip_agents.storage.clients.minio_client import MinioConfig as MinioConfig, MinioObjectStorage as MinioObjectStorage
+from aip_agents.storage.config import StorageConfig as StorageConfig, StorageProviderFactory as StorageProviderFactory, StorageType as StorageType
+from aip_agents.storage.providers.base import BaseStorageProvider as BaseStorageProvider, StorageError as StorageError
+from aip_agents.storage.providers.memory import InMemoryStorageProvider as InMemoryStorageProvider
+from aip_agents.storage.providers.object_storage import ObjectStorageProvider as ObjectStorageProvider
+
+__all__ = ['BaseObjectStorageClient', 'MinioConfig', 'MinioObjectStorage', 'BaseStorageProvider', 'StorageError', 'InMemoryStorageProvider', 'ObjectStorageProvider', 'StorageConfig', 'StorageType', 'StorageProviderFactory']

aip_agents/storage/base.py

@@ -0,0 +1,85 @@
+"""Base class for object storage clients.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from abc import ABC, abstractmethod
+from typing import BinaryIO
+
+
+class BaseObjectStorageClient(ABC):
+    """Abstract base class for object storage clients."""
+
+    @abstractmethod
+    def object_exists(self, object_key: str) -> bool:
+        """Check if an object exists in the storage.
+
+        Args:
+            object_key: The key of the object to check.
+
+        Returns:
+            True if the object exists, False otherwise.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def upload(
+        self,
+        object_key: str,
+        file_stream: bytes | BinaryIO,
+        filename: str | None = None,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> str:
+        """Upload data to object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+            file_stream: The binary data to upload
+            filename: The name of the file
+            content_type: The content type of the file
+            metadata: Additional metadata to store with the object
+
+        Returns:
+            The key of the uploaded object
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get(self, object_key: str) -> bytes:
+        """Get data from object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+
+        Returns:
+            The binary data of the object
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete(self, object_key: str) -> None:
+        """Delete data from object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def generate_presigned_url(
+        self, object_key: str, expires: int = 24, response_headers: dict[str, str] | None = None
+    ) -> str:
+        """Generate a presigned URL for accessing the object.
+
+        Args:
+            object_key: The key of the object in the storage
+            expires: The number of hours the URL is valid for
+            response_headers: Additional headers to include in the response
+
+        Returns:
+            The presigned URL
+        """
+        raise NotImplementedError

aip_agents/storage/base.pyi

@@ -0,0 +1,58 @@
+from abc import ABC, abstractmethod
+from typing import BinaryIO
+
+class BaseObjectStorageClient(ABC):
+    """Abstract base class for object storage clients."""
+    @abstractmethod
+    def object_exists(self, object_key: str) -> bool:
+        """Check if an object exists in the storage.
+
+        Args:
+            object_key: The key of the object to check.
+
+        Returns:
+            True if the object exists, False otherwise.
+        """
+    @abstractmethod
+    def upload(self, object_key: str, file_stream: bytes | BinaryIO, filename: str | None = None, content_type: str | None = None, metadata: dict[str, str] | None = None) -> str:
+        """Upload data to object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+            file_stream: The binary data to upload
+            filename: The name of the file
+            content_type: The content type of the file
+            metadata: Additional metadata to store with the object
+
+        Returns:
+            The key of the uploaded object
+        """
+    @abstractmethod
+    def get(self, object_key: str) -> bytes:
+        """Get data from object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+
+        Returns:
+            The binary data of the object
+        """
+    @abstractmethod
+    def delete(self, object_key: str) -> None:
+        """Delete data from object storage.
+
+        Args:
+            object_key: The key of the object in the storage
+        """
+    @abstractmethod
+    def generate_presigned_url(self, object_key: str, expires: int = 24, response_headers: dict[str, str] | None = None) -> str:
+        """Generate a presigned URL for accessing the object.
+
+        Args:
+            object_key: The key of the object in the storage
+            expires: The number of hours the URL is valid for
+            response_headers: Additional headers to include in the response
+
+        Returns:
+            The presigned URL
+        """

aip_agents/storage/clients/__init__.py

@@ -0,0 +1,12 @@
+"""Storage client implementations.
+
+This module contains concrete implementations of object storage clients
+for various backends like MinIO, AWS S3, etc.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from aip_agents.storage.clients.minio_client import MinioConfig, MinioObjectStorage
+
+__all__ = ["MinioConfig", "MinioObjectStorage"]

aip_agents/storage/clients/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.storage.clients.minio_client import MinioConfig as MinioConfig, MinioObjectStorage as MinioObjectStorage
+
+__all__ = ['MinioConfig', 'MinioObjectStorage']