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

airbyte_agent_airtable/_vendored/connector_sdk/observability/session.py

@@ -0,0 +1,103 @@
+"""Shared session context for both logging and telemetry."""
+
+import logging
+import uuid
+from datetime import UTC, datetime
+from typing import Any, Dict
+
+from .config import SDKConfig, load_config
+
+logger = logging.getLogger(__name__)
+
+# Cache the config at module level to avoid repeated reads
+_cached_config: SDKConfig | None = None
+
+
+def _get_config() -> SDKConfig:
+    """Get cached SDK config or load from file."""
+    global _cached_config
+    if _cached_config is None:
+        _cached_config = load_config()
+    return _cached_config
+
+
+def _clear_config_cache() -> None:
+    """Clear the cached config. Used for testing."""
+    global _cached_config
+    _cached_config = None
+
+
+def get_persistent_user_id() -> str:
+    """
+    Get the persistent anonymous user ID.
+
+    Now reads from ~/.airbyte/connector-sdk/config.yaml
+
+    Returns:
+        An anonymous UUID string that uniquely identifies this user across sessions.
+    """
+    return _get_config().user_id
+
+
+def get_public_ip() -> str | None:
+    """
+    Fetch the public IP address of the user.
+
+    Returns None if unable to fetch (network issues, etc).
+    Uses httpx for a robust HTTP request to a public IP service.
+    """
+    try:
+        # NOTE: Import here intentionally - this is a non-critical network call
+        # that may fail. Importing at module level would make httpx a hard dependency.
+        import httpx
+
+        # Use a short timeout to avoid blocking
+        with httpx.Client(timeout=2.0) as client:
+            response = client.get("https://api.ipify.org?format=text")
+            response.raise_for_status()
+            return response.text.strip()
+    except Exception:
+        # Never fail - just return None
+        return None
+
+
+def get_is_internal_user() -> bool:
+    """
+    Check if the current user is an internal Airbyte user.
+
+    Now reads from ~/.airbyte/connector-sdk/config.yaml
+    Environment variable AIRBYTE_INTERNAL_USER can override.
+
+    Returns False if not set or on any error.
+    """
+    return _get_config().is_internal_user
+
+
+class ObservabilitySession:
+    """Shared session context for both logging and telemetry."""
+
+    def __init__(
+        self,
+        connector_name: str,
+        connector_version: str | None = None,
+        execution_context: str = "direct",
+        session_id: str | None = None,
+    ):
+        self.session_id = session_id or str(uuid.uuid4())
+        self.user_id = get_persistent_user_id()
+        self.connector_name = connector_name
+        self.connector_version = connector_version
+        self.execution_context = execution_context
+        self.started_at = datetime.now(UTC)
+        self.operation_count = 0
+        self.metadata: Dict[str, Any] = {}
+        self.public_ip = get_public_ip()
+        self.is_internal_user = get_is_internal_user()
+
+    def increment_operations(self):
+        """Increment the operation counter."""
+        self.operation_count += 1
+
+    def duration_seconds(self) -> float:
+        """Calculate session duration in seconds."""
+        return (datetime.now(UTC) - self.started_at).total_seconds()

airbyte_agent_airtable/_vendored/connector_sdk/performance/__init__.py

@@ -0,0 +1,6 @@
+"""Performance monitoring and instrumentation for async operations."""
+
+from .instrumentation import instrument
+from .metrics import PerformanceMonitor
+
+__all__ = ["instrument", "PerformanceMonitor"]

airbyte_agent_airtable/_vendored/connector_sdk/performance/instrumentation.py

@@ -0,0 +1,57 @@
+"""Performance instrumentation decorator for async functions."""
+
+import functools
+import logging
+import time
+from typing import Any, Callable, TypeVar
+
+# Type variable for generic function decoration
+F = TypeVar("F", bound=Callable[..., Any])
+
+logger = logging.getLogger(__name__)
+
+
+def instrument(metric_name: str) -> Callable[[F], F]:
+    """Decorator to instrument async functions with performance tracking.
+
+    Args:
+        metric_name: Name of the metric to track
+
+    Returns:
+        Decorator function
+
+    Example:
+        @instrument("stripe.customer.list")
+        async def list_customers():
+            ...
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            start_time = time.time()
+            success = True
+            error = None
+
+            try:
+                result = await func(*args, **kwargs)
+                return result
+
+            except Exception as e:
+                success = False
+                error = e
+                raise
+
+            finally:
+                duration = time.time() - start_time
+                duration_ms = duration * 1000
+
+                # Log performance metrics
+                if success:
+                    logger.debug(f"[{metric_name}] completed in {duration_ms:.2f}ms")
+                else:
+                    logger.warning(f"[{metric_name}] failed after {duration_ms:.2f}ms: {error}")
+
+        return wrapper  # type: ignore
+
+    return decorator

airbyte_agent_airtable/_vendored/connector_sdk/performance/metrics.py

@@ -0,0 +1,93 @@
+"""Performance metrics tracking."""
+
+import time
+from contextlib import asynccontextmanager
+from typing import Dict
+
+
+class PerformanceMonitor:
+    """Monitor and track performance metrics for operations."""
+
+    def __init__(self):
+        """Initialize performance monitor."""
+        self._metrics: Dict[str, Dict[str, float]] = {}
+
+    def record(self, metric_name: str, duration: float):
+        """Record a metric.
+
+        Args:
+            metric_name: Name of the metric
+            duration: Duration in seconds
+        """
+        if metric_name not in self._metrics:
+            self._metrics[metric_name] = {
+                "count": 0,
+                "total": 0.0,
+                "min": float("inf"),
+                "max": 0.0,
+            }
+
+        metrics = self._metrics[metric_name]
+        metrics["count"] += 1
+        metrics["total"] += duration
+        metrics["min"] = min(metrics["min"], duration)
+        metrics["max"] = max(metrics["max"], duration)
+
+    def get_stats(self, metric_name: str) -> Dict[str, float] | None:
+        """Get statistics for a metric.
+
+        Args:
+            metric_name: Name of the metric
+
+        Returns:
+            Dictionary with count, total, mean, min, max or None if metric not found
+        """
+        if metric_name not in self._metrics:
+            return None
+
+        metrics = self._metrics[metric_name]
+        return {
+            "count": metrics["count"],
+            "total": metrics["total"],
+            "mean": metrics["total"] / metrics["count"] if metrics["count"] > 0 else 0.0,
+            "min": metrics["min"] if metrics["min"] != float("inf") else 0.0,
+            "max": metrics["max"],
+        }
+
+    def get_all_stats(self) -> Dict[str, Dict[str, float]]:
+        """Get statistics for all metrics.
+
+        Returns:
+            Dictionary mapping metric names to their statistics
+        """
+        return {name: self.get_stats(name) for name in self._metrics.keys()}
+
+    def reset(self, metric_name: str | None = None):
+        """Reset metrics.
+
+        Args:
+            metric_name: Specific metric to reset, or None to reset all
+        """
+        if metric_name:
+            if metric_name in self._metrics:
+                del self._metrics[metric_name]
+        else:
+            self._metrics.clear()
+
+    @asynccontextmanager
+    async def track(self, metric_name: str):
+        """Context manager for tracking operation duration.
+
+        Args:
+            metric_name: Name of the metric to track
+
+        Example:
+            async with monitor.track("api_call"):
+                result = await some_async_operation()
+        """
+        start_time = time.time()
+        try:
+            yield
+        finally:
+            duration = time.time() - start_time
+            self.record(metric_name, duration)

airbyte_agent_airtable/_vendored/connector_sdk/schema/__init__.py

@@ -0,0 +1,75 @@
+"""
+Pydantic 2 schema models for OpenAPI 3.0 connector specifications.
+
+This package provides strongly-typed Pydantic models that mirror the OpenAPI 3.0
+specification while supporting Airbyte-specific extensions.
+
+Usage:
+    import yaml
+    from . import OpenAPIConnector
+
+    with open('connector.yaml') as f:
+        data = yaml.safe_load(f)
+
+    connector = OpenAPIConnector(**data)
+    print(connector.list_resources())
+"""
+
+from .base import Contact, Info, License, Server, ServerVariable
+from .components import (
+    Components,
+    Header,
+    MediaType,
+    Parameter,
+    RequestBody,
+    Response,
+    Schema,
+)
+from .connector import ExternalDocs, OpenAPIConnector, Tag
+from .extensions import PaginationConfig, RateLimitConfig, RetryConfig
+from .operations import Operation, PathItem
+from .security import (
+    AirbyteAuthConfig,
+    AuthConfigFieldSpec,
+    AuthConfigOption,
+    OAuth2Flow,
+    OAuth2Flows,
+    SecurityRequirement,
+    SecurityScheme,
+)
+
+__all__ = [
+    # Root model
+    "OpenAPIConnector",
+    "Tag",
+    "ExternalDocs",
+    # Base models
+    "Info",
+    "Server",
+    "ServerVariable",
+    "Contact",
+    "License",
+    # Security models
+    "SecurityScheme",
+    "SecurityRequirement",
+    "OAuth2Flow",
+    "OAuth2Flows",
+    "AirbyteAuthConfig",
+    "AuthConfigOption",
+    "AuthConfigFieldSpec",
+    # Component models
+    "Components",
+    "Schema",
+    "Parameter",
+    "RequestBody",
+    "Response",
+    "MediaType",
+    "Header",
+    # Operation models
+    "PathItem",
+    "Operation",
+    # Extension models (for future use)
+    "PaginationConfig",
+    "RateLimitConfig",
+    "RetryConfig",
+]

airbyte_agent_airtable/_vendored/connector_sdk/schema/base.py

@@ -0,0 +1,212 @@
+"""
+Base OpenAPI 3.1 models: Info, Server, Contact, License.
+
+References:
+- https://spec.openapis.org/oas/v3.1.0#info-object
+- https://spec.openapis.org/oas/v3.1.0#server-object
+"""
+
+from enum import StrEnum
+from typing import Any, Dict
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic_core import Url
+
+from .extensions import CacheConfig, ReplicationConfig, RetryConfig
+
+
+class ExampleQuestions(BaseModel):
+    """
+    Example questions for AI connector documentation.
+
+    Used to generate supported_questions.md and unsupported_questions.md files
+    that appear in the connector's README.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    supported: list[str] = Field(
+        default_factory=list,
+        description="Example questions the connector can handle",
+    )
+    unsupported: list[str] = Field(
+        default_factory=list,
+        description="Example questions the connector cannot handle",
+    )
+
+
+class Contact(BaseModel):
+    """
+    Contact information for the API.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#contact-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str | None = None
+    url: str | None = None
+    email: str | None = None
+
+
+class License(BaseModel):
+    """
+    License information for the API.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#license-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    url: str | None = None
+
+
+class DocUrlType(StrEnum):
+    API_DEPRECATIONS = "api_deprecations"
+    API_REFERENCE = "api_reference"
+    API_RELEASE_HISTORY = "api_release_history"
+    AUTHENTICATION_GUIDE = "authentication_guide"
+    CHANGELOG = "changelog"
+    DATA_MODEL_REFERENCE = "data_model_reference"
+    DEVELOPER_COMMUNITY = "developer_community"
+    MIGRATION_GUIDE = "migration_guide"
+    OPENAPI_SPEC = "openapi_spec"
+    OTHER = "other"
+    PERMISSIONS_SCOPES = "permissions_scopes"
+    RATE_LIMITS = "rate_limits"
+    SQL_REFERENCE = "sql_reference"
+    STATUS_PAGE = "status_page"
+
+
+class DocUrl(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    url: str
+    type: DocUrlType
+    title: str | None = None
+
+    @field_validator("url")
+    def validate_url(cls, v):
+        Url(v)
+        return v
+
+
+class Info(BaseModel):
+    """
+    API metadata information.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#info-object
+
+    Extensions:
+    - x-airbyte-connector-name: Name of the connector (Airbyte extension)
+    - x-airbyte-connector-id: UUID of the connector (Airbyte extension)
+    - x-airbyte-external-documentation-urls: List of external documentation URLs (Airbyte extension)
+    - x-airbyte-retry-config: Retry configuration for transient errors (Airbyte extension)
+    - x-airbyte-example-questions: Example questions for AI connector README (Airbyte extension)
+    - x-airbyte-cache: Cache configuration for field mapping between API and cache schemas (Airbyte extension)
+    - x-airbyte-replication-config: Replication configuration for MULTI mode connectors (Airbyte extension)
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    title: str
+    version: str
+    description: str | None = None
+    terms_of_service: str | None = Field(None, alias="termsOfService")
+    contact: Contact | None = None
+    license: License | None = None
+
+    # Airbyte extension
+    x_airbyte_connector_name: str | None = Field(None, alias="x-airbyte-connector-name")
+    x_airbyte_connector_id: UUID | None = Field(None, alias="x-airbyte-connector-id")
+    x_airbyte_external_documentation_urls: list[DocUrl] = Field(..., alias="x-airbyte-external-documentation-urls")
+    x_airbyte_retry_config: RetryConfig | None = Field(None, alias="x-airbyte-retry-config")
+    x_airbyte_example_questions: ExampleQuestions | None = Field(None, alias="x-airbyte-example-questions")
+    x_airbyte_cache: CacheConfig | None = Field(None, alias="x-airbyte-cache")
+    x_airbyte_replication_config: ReplicationConfig | None = Field(None, alias="x-airbyte-replication-config")
+    x_airbyte_skip_suggested_streams: list[str] = Field(
+        default_factory=list,
+        alias="x-airbyte-skip-suggested-streams",
+        description="List of Airbyte suggested streams to skip when validating cache entity coverage",
+    )
+    x_airbyte_skip_auth_methods: list[str] = Field(
+        default_factory=list,
+        alias="x-airbyte-skip-auth-methods",
+        description="List of Airbyte auth methods to skip when validating auth compatibility. "
+        "Use the SelectiveAuthenticator option key (e.g., 'Private App Credentials', 'oauth2.0')",
+    )
+
+
+class ServerVariable(BaseModel):
+    """
+    Variable for server URL templating.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#server-variable-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    enum: list[str] | None = None
+    default: str
+    description: str | None = None
+
+
+class EnvironmentMappingTransform(BaseModel):
+    """
+    Structured transform for environment mapping values.
+
+    Allows transforming environment values before storing in source_config.
+
+    Example:
+        source: subdomain
+        format: "{value}.atlassian.net"
+
+    The format string uses {value} as a placeholder for the source value.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    source: str = Field(description="The environment config key to read the value from")
+    format: str | None = Field(
+        default=None,
+        description="Optional format string to transform the value. Use {value} as placeholder.",
+    )
+
+
+# Type alias for environment mapping values: either a simple string (config key)
+# or a structured transform with source and optional transform template
+EnvironmentMappingValue = str | EnvironmentMappingTransform
+
+
+class Server(BaseModel):
+    """
+    Server URL and variable definitions.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#server-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    url: str
+    description: str | None = None
+    variables: Dict[str, ServerVariable] = Field(default_factory=dict)
+    x_airbyte_replication_environment_mapping: Dict[str, EnvironmentMappingValue] | None = Field(
+        default=None,
+        alias="x-airbyte-replication-environment-mapping",
+    )
+    x_airbyte_replication_environment_constants: Dict[str, Any] | None = Field(
+        default=None,
+        alias="x-airbyte-replication-environment-constants",
+        description="Constant values to always inject at environment config paths (e.g., 'region': 'us-east-1')",
+    )
+
+    @field_validator("url")
+    @classmethod
+    def validate_url(cls, v: str) -> str:
+        """Validate that server URL is properly formatted."""
+        if not v:
+            raise ValueError("Server URL cannot be empty")
+        # Allow both absolute URLs and relative paths
+        return v