airbyte-agent-airtable 0.1.5__py3-none-any.whl

airbyte_agent_airtable/_vendored/connector_sdk/constants.py

@@ -0,0 +1,78 @@
+"""
+Constants used throughout the Airbyte SDK.
+
+This module centralizes configuration defaults and commonly used values to improve
+maintainability and consistency across the codebase.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+# ============================================================================
+# HTTP Connection and Timeout Defaults
+# ============================================================================
+
+# Connection pooling limits
+DEFAULT_MAX_CONNECTIONS = 100
+"""Maximum number of concurrent HTTP connections to maintain in the pool."""
+
+DEFAULT_MAX_KEEPALIVE_CONNECTIONS = 20
+"""Maximum number of keepalive connections to maintain in the pool."""
+
+# Timeout values (in seconds)
+DEFAULT_CONNECT_TIMEOUT = 5.0
+"""Default timeout for establishing a new connection (seconds)."""
+
+DEFAULT_READ_TIMEOUT = 30.0
+"""Default timeout for reading response data (seconds)."""
+
+DEFAULT_WRITE_TIMEOUT = 30.0
+"""Default timeout for writing request data (seconds)."""
+
+DEFAULT_POOL_TIMEOUT = 5.0
+"""Default timeout for acquiring a connection from the pool (seconds)."""
+
+DEFAULT_REQUEST_TIMEOUT = 30.0
+"""Default overall request timeout (seconds)."""
+
+# ============================================================================
+# OpenAPI Specification
+# ============================================================================
+
+OPENAPI_VERSION_PREFIX = "3.1."
+"""Required OpenAPI version prefix. Only 3.1.x specifications are supported."""
+
+OPENAPI_DEFAULT_VERSION = "1.0.0"
+"""Default version string for connectors that don't specify a version."""
+
+# ============================================================================
+# Performance and Metrics
+# ============================================================================
+
+MILLISECONDS_PER_SECOND = 1000
+"""Conversion factor from seconds to milliseconds."""
+
+# ============================================================================
+# Retry and Backoff Defaults
+# ============================================================================
+
+DEFAULT_INITIAL_DELAY_SECONDS = 1.0
+"""Default initial delay for retry backoff (seconds)."""
+
+DEFAULT_MAX_DELAY_SECONDS = 60.0
+"""Default maximum delay for retry backoff (seconds)."""
+
+# ============================================================================
+# SDK Version
+# ============================================================================
+
+try:
+    SDK_VERSION = version("connector-sdk")
+except PackageNotFoundError:
+    # Fallback for development when package isn't installed
+    SDK_VERSION = "0.0.0-dev"
+"""Current version of the Airbyte SDK."""
+
+MINIMUM_PYTHON_VERSION = "3.13"
+"""Minimum Python version required to run the SDK."""

airbyte_agent_airtable/_vendored/connector_sdk/exceptions.py

@@ -0,0 +1,23 @@
+"""Exceptions for the Airbyte SDK.
+
+DEPRECATED: HTTP exceptions have been moved to connector_sdk.http.exceptions.
+This module re-exports them for backward compatibility.
+"""
+
+from .http.exceptions import (
+    AuthenticationError,
+    HTTPClientError,
+    HTTPStatusError,
+    NetworkError,
+    RateLimitError,
+    TimeoutError,
+)
+
+__all__ = [
+    "HTTPClientError",
+    "HTTPStatusError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NetworkError",
+    "TimeoutError",
+]

airbyte_agent_airtable/_vendored/connector_sdk/executor/__init__.py

@@ -0,0 +1,31 @@
+"""Executor implementations for connector operations."""
+
+from .hosted_executor import HostedExecutor
+from .local_executor import LocalExecutor
+from .models import (
+    ActionNotSupportedError,
+    EntityNotFoundError,
+    ExecutionConfig,
+    ExecutionResult,
+    ExecutorError,
+    ExecutorProtocol,
+    InvalidParameterError,
+    MissingParameterError,
+)
+
+__all__ = [
+    # Config and Result types
+    "ExecutionConfig",
+    "ExecutionResult",
+    # Protocol
+    "ExecutorProtocol",
+    # Executors
+    "LocalExecutor",
+    "HostedExecutor",
+    # Exceptions
+    "ExecutorError",
+    "EntityNotFoundError",
+    "ActionNotSupportedError",
+    "MissingParameterError",
+    "InvalidParameterError",
+]

airbyte_agent_airtable/_vendored/connector_sdk/executor/hosted_executor.py

@@ -0,0 +1,230 @@
+"""Hosted executor for proxying operations through the cloud API."""
+
+from __future__ import annotations
+
+from opentelemetry import trace
+
+from ..cloud_utils import AirbyteCloudClient
+
+from .models import (
+    ExecutionConfig,
+    ExecutionResult,
+)
+
+
+class HostedExecutor:
+    """Executor that proxies execution through the Airbyte Cloud API.
+
+    This is the "hosted mode" executor that makes HTTP calls to the cloud API
+    instead of directly calling external services. The cloud API handles all
+    connector logic, secrets management, and execution.
+
+    The executor uses the AirbyteCloudClient to:
+    1. Authenticate with the Airbyte Platform (bearer token with caching)
+    2. Look up the user's connector (if connector_id not provided)
+    3. Execute the connector operation via the cloud API
+
+    Implements ExecutorProtocol.
+
+    Example:
+        # Create executor with explicit connector_id (no lookup needed)
+        executor = HostedExecutor(
+            airbyte_client_id="client_abc123",
+            airbyte_client_secret="secret_xyz789",
+            connector_id="existing-source-uuid",
+        )
+
+        # Or create executor with user ID for lookup
+        executor = HostedExecutor(
+            airbyte_client_id="client_abc123",
+            airbyte_client_secret="secret_xyz789",
+            external_user_id="user-123",
+            connector_definition_id="abc123-def456-ghi789",
+        )
+
+        # Execute an operation
+        execution_config = ExecutionConfig(
+            entity="customers",
+            action="list",
+            params={"limit": 10}
+        )
+
+        result = await executor.execute(execution_config)
+        if result.success:
+            print(f"Data: {result.data}")
+        else:
+            print(f"Error: {result.error}")
+    """
+
+    def __init__(
+        self,
+        airbyte_client_id: str,
+        airbyte_client_secret: str,
+        connector_id: str | None = None,
+        external_user_id: str | None = None,
+        connector_definition_id: str | None = None,
+    ):
+        """Initialize hosted executor.
+
+        Either provide connector_id directly OR (external_user_id + connector_definition_id)
+        for lookup.
+
+        Args:
+            airbyte_client_id: Airbyte client ID for authentication
+            airbyte_client_secret: Airbyte client secret for authentication
+            connector_id: Direct connector/source ID (skips lookup if provided)
+            external_user_id: User identifier in the Airbyte system (for lookup)
+            connector_definition_id: Connector definition ID (for lookup)
+
+        Raises:
+            ValueError: If neither connector_id nor (external_user_id + connector_definition_id) provided
+
+        Example:
+            # With explicit connector_id (no lookup)
+            executor = HostedExecutor(
+                airbyte_client_id="client_abc123",
+                airbyte_client_secret="secret_xyz789",
+                connector_id="existing-source-uuid",
+            )
+
+            # With lookup by user + definition
+            executor = HostedExecutor(
+                airbyte_client_id="client_abc123",
+                airbyte_client_secret="secret_xyz789",
+                external_user_id="user-123",
+                connector_definition_id="abc123-def456-ghi789",
+            )
+        """
+        # Validate: either connector_id OR (external_user_id + connector_definition_id) required
+        if not connector_id and not (external_user_id and connector_definition_id):
+            raise ValueError("Either connector_id OR (external_user_id + connector_definition_id) must be provided")
+
+        self._connector_id = connector_id
+        self._external_user_id = external_user_id
+        self._connector_definition_id = connector_definition_id
+
+        # Create AirbyteCloudClient for API interactions
+        self._cloud_client = AirbyteCloudClient(
+            client_id=airbyte_client_id,
+            client_secret=airbyte_client_secret,
+        )
+
+    async def execute(self, config: ExecutionConfig) -> ExecutionResult:
+        """Execute connector via cloud API (ExecutorProtocol implementation).
+
+        Flow:
+        1. Use provided connector_id or look up from external_user_id + definition_id
+        2. Execute the connector operation via the cloud API
+        3. Parse the response into ExecutionResult
+
+        Args:
+            config: Execution configuration (entity, action, params)
+
+        Returns:
+            ExecutionResult with success/failure status
+
+        Raises:
+            ValueError: If no connector or multiple connectors found for user (when doing lookup)
+            httpx.HTTPStatusError: If API returns 4xx/5xx status code
+            httpx.RequestError: If network request fails
+
+        Example:
+            config = ExecutionConfig(
+                entity="customers",
+                action="list",
+                params={"limit": 10}
+            )
+            result = await executor.execute(config)
+        """
+        tracer = trace.get_tracer("airbyte.connector-sdk.executor.hosted")
+
+        with tracer.start_as_current_span("airbyte.hosted_executor.execute") as span:
+            # Add span attributes for observability
+            if self._connector_definition_id:
+                span.set_attribute("connector.definition_id", self._connector_definition_id)
+            span.set_attribute("connector.entity", config.entity)
+            span.set_attribute("connector.action", config.action)
+            if self._external_user_id:
+                span.set_attribute("user.external_id", self._external_user_id)
+            if config.params:
+                # Only add non-sensitive param keys
+                span.set_attribute("connector.param_keys", list(config.params.keys()))
+
+            try:
+                # Use provided connector_id or look it up
+                if self._connector_id:
+                    connector_id = self._connector_id
+                else:
+                    # Look up connector by external_user_id + definition_id
+                    connector_id = await self._cloud_client.get_connector_id(
+                        external_user_id=self._external_user_id,  # type: ignore[arg-type]
+                        connector_definition_id=self._connector_definition_id,  # type: ignore[arg-type]
+                    )
+
+                span.set_attribute("connector.connector_id", connector_id)
+
+                # Step 3: Execute the connector via the cloud API
+                response = await self._cloud_client.execute_connector(
+                    connector_id=connector_id,
+                    entity=config.entity,
+                    action=config.action,
+                    params=config.params,
+                )
+
+                # Step 4: Parse the response into ExecutionResult
+                result = self._parse_execution_result(response)
+
+                # Mark span as successful
+                span.set_attribute("connector.success", result.success)
+
+                return result
+
+            except ValueError as e:
+                # Connector lookup validation error (0 or >1 connectors)
+                span.set_attribute("connector.success", False)
+                span.set_attribute("connector.error_type", "ValueError")
+                span.record_exception(e)
+                raise
+
+            except Exception as e:
+                # HTTP errors and other exceptions
+                span.set_attribute("connector.success", False)
+                span.set_attribute("connector.error_type", type(e).__name__)
+                span.record_exception(e)
+                raise
+
+    async def check(self) -> ExecutionResult:
+        """Perform a health check via the cloud API."""
+        config = ExecutionConfig(entity="*", action="check", params={})
+        return await self.execute(config)
+
+    def _parse_execution_result(self, response: dict) -> ExecutionResult:
+        """Parse API response into ExecutionResult.
+
+        Args:
+            response_data: Raw JSON response from the cloud API
+
+        Returns:
+            ExecutionResult with parsed data
+        """
+
+        return ExecutionResult(
+            success=True,
+            data=response["result"],
+            meta=response.get("connector_metadata"),
+            error=None,
+        )
+
+    async def close(self):
+        """Close the cloud client and cleanup resources.
+
+        Call this when you're done using the executor to clean up HTTP connections.
+
+        Example:
+            executor = HostedExecutor(...)
+            try:
+                result = await executor.execute(config)
+            finally:
+                await executor.close()
+        """
+        await self._cloud_client.close()