airbyte-agent-mcp 0.1.53__py3-none-any.whl → 0.1.64__py3-none-any.whl

airbyte_agent_mcp/_vendored/connector_sdk/performance/metrics.py

@@ -2,7 +2,7 @@
 
 import time
 from contextlib import asynccontextmanager
-from typing import Dict, Optional
+from typing import Dict
 
 
 class PerformanceMonitor:
@@ -33,7 +33,7 @@ class PerformanceMonitor:
         metrics["min"] = min(metrics["min"], duration)
         metrics["max"] = max(metrics["max"], duration)
 
-    def get_stats(self, metric_name: str) -> Optional[Dict[str, float]]:
+    def get_stats(self, metric_name: str) -> Dict[str, float] | None:
         """Get statistics for a metric.
 
         Args:
@@ -62,7 +62,7 @@ class PerformanceMonitor:
         """
         return {name: self.get_stats(name) for name in self._metrics.keys()}
 
-    def reset(self, metric_name: Optional[str] = None):
+    def reset(self, metric_name: str | None = None):
         """Reset metrics.
 
         Args:

airbyte_agent_mcp/_vendored/connector_sdk/schema/base.py

@@ -7,13 +7,13 @@ References:
 """
 
 from enum import StrEnum
-from typing import Dict, Optional
+from typing import Dict
 from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 from pydantic_core import Url
 
-from .extensions import RetryConfig
+from .extensions import CacheConfig, RetryConfig
 
 
 class ExampleQuestions(BaseModel):
@@ -45,9 +45,9 @@ class Contact(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    name: Optional[str] = None
-    url: Optional[str] = None
-    email: Optional[str] = None
+    name: str | None = None
+    url: str | None = None
+    email: str | None = None
 
 
 class License(BaseModel):
@@ -60,7 +60,7 @@ class License(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     name: str
-    url: Optional[str] = None
+    url: str | None = None
 
 
 class DocUrlType(StrEnum):
@@ -85,7 +85,7 @@ class DocUrl(BaseModel):
 
     url: str
     type: DocUrlType
-    title: Optional[str] = None
+    title: str | None = None
 
     @field_validator("url")
     def validate_url(cls, v):
@@ -105,23 +105,25 @@ class Info(BaseModel):
     - 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)
     """
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     title: str
     version: str
-    description: Optional[str] = None
-    terms_of_service: Optional[str] = Field(None, alias="termsOfService")
-    contact: Optional[Contact] = None
-    license: Optional[License] = None
+    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: Optional[str] = Field(None, alias="x-airbyte-connector-name")
-    x_airbyte_connector_id: Optional[UUID] = Field(None, alias="x-airbyte-connector-id")
+    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: Optional[RetryConfig] = Field(None, alias="x-airbyte-retry-config")
-    x_airbyte_example_questions: Optional[ExampleQuestions] = Field(None, alias="x-airbyte-example-questions")
+    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")
 
 
 class ServerVariable(BaseModel):
@@ -133,9 +135,9 @@ class ServerVariable(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    enum: Optional[list[str]] = None
+    enum: list[str] | None = None
     default: str
-    description: Optional[str] = None
+    description: str | None = None
 
 
 class Server(BaseModel):
@@ -148,8 +150,9 @@ class Server(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     url: str
-    description: Optional[str] = None
+    description: str | None = None
     variables: Dict[str, ServerVariable] = Field(default_factory=dict)
+    x_airbyte_replication_user_config_mapping: Dict[str, str] | None = Field(default=None, alias="x-airbyte-replication-user-config-mapping")
 
     @field_validator("url")
     @classmethod

airbyte_agent_mcp/_vendored/connector_sdk/schema/components.py

@@ -7,7 +7,7 @@ References:
 - https://spec.openapis.org/oas/v3.1.0#parameter-object
 """
 
-from typing import Any, Dict, List, Literal, Optional, Union
+from typing import Any, Dict, List, Literal, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -30,44 +30,44 @@ class Schema(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     # Core JSON Schema fields
-    type: Optional[str] = None
-    format: Optional[str] = None
-    title: Optional[str] = None
-    description: Optional[str] = None
-    default: Optional[Any] = None
-    example: Optional[Any] = None
+    type: str | None = None
+    format: str | None = None
+    title: str | None = None
+    description: str | None = None
+    default: Any | None = None
+    example: Any | None = None
 
     # Object properties
     properties: Dict[str, Any] = Field(default_factory=dict)  # May contain $ref
     required: List[str] = Field(default_factory=list)
-    additional_properties: Optional[Any] = Field(None, alias="additionalProperties")
+    additional_properties: Any | None = Field(None, alias="additionalProperties")
 
     # Array properties
-    items: Optional[Any] = None  # May be Schema or $ref
+    items: Any | None = None  # May be Schema or $ref
 
     # Validation
-    enum: Optional[List[Any]] = None
-    min_length: Optional[int] = Field(None, alias="minLength")
-    max_length: Optional[int] = Field(None, alias="maxLength")
-    minimum: Optional[float] = None
-    maximum: Optional[float] = None
-    pattern: Optional[str] = None
+    enum: List[Any] | None = None
+    min_length: int | None = Field(None, alias="minLength")
+    max_length: int | None = Field(None, alias="maxLength")
+    minimum: float | None = None
+    maximum: float | None = None
+    pattern: str | None = None
 
     # Composition
-    all_of: Optional[List[Any]] = Field(None, alias="allOf")
-    any_of: Optional[List[Any]] = Field(None, alias="anyOf")
-    one_of: Optional[List[Any]] = Field(None, alias="oneOf")
-    not_: Optional[Any] = Field(None, alias="not")
+    all_of: List[Any] | None = Field(None, alias="allOf")
+    any_of: List[Any] | None = Field(None, alias="anyOf")
+    one_of: List[Any] | None = Field(None, alias="oneOf")
+    not_: Any | None = Field(None, alias="not")
 
     # Metadata
-    nullable: Optional[bool] = Field(None, deprecated="Use type union with null instead (OpenAPI 3.1)")
-    read_only: Optional[bool] = Field(None, alias="readOnly")
-    write_only: Optional[bool] = Field(None, alias="writeOnly")
-    deprecated: Optional[bool] = None
+    nullable: bool | None = Field(None, deprecated="Use type union with null instead (OpenAPI 3.1)")
+    read_only: bool | None = Field(None, alias="readOnly")
+    write_only: bool | None = Field(None, alias="writeOnly")
+    deprecated: bool | None = None
 
     # Airbyte extensions
-    x_airbyte_entity_name: Optional[str] = Field(None, alias="x-airbyte-entity-name")
-    x_airbyte_stream_name: Optional[str] = Field(None, alias="x-airbyte-stream-name")
+    x_airbyte_entity_name: str | None = Field(None, alias="x-airbyte-entity-name")
+    x_airbyte_stream_name: str | None = Field(None, alias="x-airbyte-stream-name")
 
 
 class Parameter(BaseModel):
@@ -81,19 +81,19 @@ class Parameter(BaseModel):
 
     name: str
     in_: Literal["query", "header", "path", "cookie"] = Field(alias="in")
-    description: Optional[str] = None
-    required: Optional[bool] = None
-    deprecated: Optional[bool] = None
-    allow_empty_value: Optional[bool] = Field(None, alias="allowEmptyValue")
+    description: str | None = None
+    required: bool | None = None
+    deprecated: bool | None = None
+    allow_empty_value: bool | None = Field(None, alias="allowEmptyValue")
 
     # Schema can be inline or reference
-    schema_: Optional[Dict[str, Any]] = Field(None, alias="schema")
+    schema_: Dict[str, Any] | None = Field(None, alias="schema")
 
     # Style and examples
-    style: Optional[str] = None
-    explode: Optional[bool] = None
-    example: Optional[Any] = None
-    examples: Optional[Dict[str, Any]] = None
+    style: str | None = None
+    explode: bool | None = None
+    example: Any | None = None
+    examples: Dict[str, Any] | None = None
 
 
 class MediaType(BaseModel):
@@ -105,10 +105,10 @@ class MediaType(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    schema_: Optional[Dict[str, Any]] = Field(None, alias="schema")
-    example: Optional[Any] = None
-    examples: Optional[Dict[str, Any]] = None
-    encoding: Optional[Dict[str, Any]] = None
+    schema_: Dict[str, Any] | None = Field(None, alias="schema")
+    example: Any | None = None
+    examples: Dict[str, Any] | None = None
+    encoding: Dict[str, Any] | None = None
 
 
 class GraphQLBodyConfig(BaseModel):
@@ -125,12 +125,12 @@ class GraphQLBodyConfig(BaseModel):
         ...,
         description="GraphQL query or mutation string with optional template placeholders (e.g., {{ variable }})",
     )
-    variables: Optional[Dict[str, Any]] = Field(
+    variables: Dict[str, Any] | None = Field(
         None,
         description="Variables to substitute in the GraphQL query using template syntax (e.g., {{ param_name }})",
     )
-    operationName: Optional[str] = Field(None, description="Operation name for queries with multiple operations")
-    default_fields: Optional[Union[str, List[str]]] = Field(
+    operationName: str | None = Field(None, description="Operation name for queries with multiple operations")
+    default_fields: Union[str, List[str]] | None = Field(
         None,
         description="Default fields to select if not provided in request parameters. Can be a string or array of field names.",
     )
@@ -156,7 +156,7 @@ class PathOverrideConfig(BaseModel):
 
     path: str = Field(
         ...,
-        description=("Actual HTTP path to use for requests (e.g., '/graphql'). " "Must start with '/'"),
+        description=("Actual HTTP path to use for requests (e.g., '/graphql'). Must start with '/'"),
     )
 
 
@@ -173,17 +173,17 @@ class RequestBody(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    description: Optional[str] = None
+    description: str | None = None
     content: Dict[str, MediaType] = Field(default_factory=dict)
-    required: Optional[bool] = None
+    required: bool | None = None
 
     # Airbyte extensions for GraphQL support
     # See connector_sdk.extensions for AIRBYTE_BODY_TYPE constant
-    x_airbyte_body_type: Optional[BodyTypeConfig] = Field(
+    x_airbyte_body_type: BodyTypeConfig | None = Field(
         None,
         alias="x-airbyte-body-type",  # AIRBYTE_BODY_TYPE
         description=(
-            "Body type and configuration. Contains 'type' field (e.g., 'graphql') " "and type-specific configuration (query, variables, etc.)."
+            "Body type and configuration. Contains 'type' field (e.g., 'graphql') and type-specific configuration (query, variables, etc.)."
         ),
     )
 
@@ -197,11 +197,11 @@ class Header(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    description: Optional[str] = None
-    required: Optional[bool] = None
-    deprecated: Optional[bool] = None
-    schema_: Optional[Dict[str, Any]] = Field(None, alias="schema")
-    example: Optional[Any] = None
+    description: str | None = None
+    required: bool | None = None
+    deprecated: bool | None = None
+    schema_: Dict[str, Any] | None = Field(None, alias="schema")
+    example: Any | None = None
 
 
 class Response(BaseModel):
@@ -214,9 +214,9 @@ class Response(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     description: str
-    headers: Optional[Dict[str, Header]] = None
-    content: Optional[Dict[str, MediaType]] = None
-    links: Optional[Dict[str, Any]] = None
+    headers: Dict[str, Header] | None = None
+    content: Dict[str, MediaType] | None = None
+    links: Dict[str, Any] | None = None
 
 
 class Components(BaseModel):
@@ -231,9 +231,9 @@ class Components(BaseModel):
     schemas: Dict[str, Schema] = Field(default_factory=dict)
     responses: Dict[str, Response] = Field(default_factory=dict)
     parameters: Dict[str, Parameter] = Field(default_factory=dict)
-    examples: Optional[Dict[str, Any]] = None
+    examples: Dict[str, Any] | None = None
     request_bodies: Dict[str, RequestBody] = Field(default_factory=dict, alias="requestBodies")
-    headers: Optional[Dict[str, Header]] = None
+    headers: Dict[str, Header] | None = None
     security_schemes: Dict[str, SecurityScheme] = Field(default_factory=dict, alias="securitySchemes")
-    links: Optional[Dict[str, Any]] = None
-    callbacks: Optional[Dict[str, Any]] = None
+    links: Dict[str, Any] | None = None
+    callbacks: Dict[str, Any] | None = None

airbyte_agent_mcp/_vendored/connector_sdk/schema/connector.py

@@ -7,6 +7,7 @@ References:
 
 from __future__ import annotations
 
+from collections.abc import Iterator
 from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
@@ -15,7 +16,7 @@ from ..constants import OPENAPI_VERSION_PREFIX
 
 from .base import Info, Server
 from .components import Components
-from .operations import PathItem
+from .operations import Operation, PathItem
 from .security import SecurityRequirement
 
 
@@ -33,6 +34,10 @@ class Tag(BaseModel):
     external_docs: dict[str, Any] | None = Field(None, alias="externalDocs")
 
 
+# HTTP methods supported by OpenAPI operations
+HTTP_METHODS = frozenset({"get", "post", "put", "patch", "delete", "options", "head", "trace"})
+
+
 class ExternalDocs(BaseModel):
     """
     External documentation reference.
@@ -79,7 +84,7 @@ class OpenAPIConnector(BaseModel):
             raise ValueError(f"OpenAPI version must be {OPENAPI_VERSION_PREFIX}x, got: {v}")
         return v
 
-    def get_entity_operations(self, entity_name: str) -> list[tuple[str, str, Any]]:
+    def get_entity_operations(self, entity_name: str) -> list[tuple[str, str, Operation]]:
         """
         Get all operations for a specific entity.
 
@@ -89,22 +94,7 @@ class OpenAPIConnector(BaseModel):
         Returns:
             List of tuples: (path, method, operation)
         """
-        results = []
-        for path, path_item in self.paths.items():
-            for method in [
-                "get",
-                "post",
-                "put",
-                "patch",
-                "delete",
-                "options",
-                "head",
-                "trace",
-            ]:
-                operation = getattr(path_item, method, None)
-                if operation and operation.x_airbyte_entity == entity_name:
-                    results.append((path, method, operation))
-        return results
+        return [(path, method, op) for path, method, op in self._iter_operations() if op.x_airbyte_entity == entity_name]
 
     def list_entities(self) -> list[str]:
         """
@@ -113,19 +103,18 @@ class OpenAPIConnector(BaseModel):
         Returns:
             Sorted list of unique entity names
         """
-        entities = set()
-        for path_item in self.paths.values():
-            for method in [
-                "get",
-                "post",
-                "put",
-                "patch",
-                "delete",
-                "options",
-                "head",
-                "trace",
-            ]:
-                operation = getattr(path_item, method, None)
-                if operation and operation.x_airbyte_entity:
-                    entities.add(operation.x_airbyte_entity)
+        entities = {op.x_airbyte_entity for _, _, op in self._iter_operations() if op.x_airbyte_entity}
         return sorted(entities)
+
+    def _iter_operations(self) -> Iterator[tuple[str, str, Operation]]:
+        """
+        Iterate over all operations in the spec.
+
+        Yields:
+            Tuples of (path, method, operation) for each defined operation
+        """
+        for path, path_item in self.paths.items():
+            for method in HTTP_METHODS:
+                operation = getattr(path_item, method, None)
+                if operation:
+                    yield path, method, operation

airbyte_agent_mcp/_vendored/connector_sdk/schema/extensions.py

@@ -12,9 +12,9 @@ to Operation, Schema, or other models when their respective features
 are implemented.
 """
 
-from typing import Literal, Optional
+from typing import Literal
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class PaginationConfig(BaseModel):
@@ -33,22 +33,22 @@ class PaginationConfig(BaseModel):
     limit_param: str = "limit"
 
     # Cursor-based pagination
-    cursor_param: Optional[str] = None
-    cursor_source: Optional[Literal["body", "headers"]] = "body"
-    cursor_path: Optional[str] = None
+    cursor_param: str | None = None
+    cursor_source: Literal["body", "headers"] | None = "body"
+    cursor_path: str | None = None
 
     # Offset-based pagination
-    offset_param: Optional[str] = None
+    offset_param: str | None = None
 
     # Page-based pagination
-    page_param: Optional[str] = None
+    page_param: str | None = None
 
     # Response parsing
     data_path: str = "data"
-    has_more_path: Optional[str] = None
+    has_more_path: str | None = None
 
     # Limits
-    max_page_size: Optional[int] = None
+    max_page_size: int | None = None
     default_page_size: int = 100
 
 
@@ -66,7 +66,7 @@ class RateLimitConfig(BaseModel):
 
     max_requests: int
     time_window_seconds: int
-    retry_after_header: Optional[str] = "Retry-After"
+    retry_after_header: str | None = "Retry-After"
     respect_retry_after: bool = True
 
 
@@ -107,3 +107,124 @@ class RetryConfig(BaseModel):
     # Header-based delay extraction
     retry_after_header: str = "Retry-After"
     retry_after_format: Literal["seconds", "milliseconds", "unix_timestamp"] = "seconds"
+
+
+class CacheFieldProperty(BaseModel):
+    """
+    Nested property definition for object-type cache fields.
+
+    Supports recursive nesting to represent complex nested schemas in cache field definitions.
+    Used when a cache field has type 'object' and needs to define its internal structure.
+
+    Example YAML usage:
+        - name: collaboration
+          type: ['null', 'object']
+          description: "Collaboration data"
+          properties:
+            brief:
+              type: ['null', 'string']
+            comments:
+              type: ['null', 'array']
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    type: str | list[str]
+    properties: dict[str, "CacheFieldProperty"] | None = None
+
+
+class CacheFieldConfig(BaseModel):
+    """
+    Field configuration for cache mapping.
+
+    Defines a single field in a cache entity, with optional name aliasing
+    to map between user-facing field names and cache storage names.
+
+    For object-type fields, supports nested properties to define the internal structure
+    of complex nested schemas.
+
+    Used in x-airbyte-cache extension for api_search operations.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    x_airbyte_name: str | None = Field(default=None, alias="x-airbyte-name")
+    type: str | list[str]
+    description: str
+    properties: dict[str, CacheFieldProperty] | None = None
+
+    @property
+    def cache_name(self) -> str:
+        """Return cache name, falling back to name if alias not specified."""
+        return self.x_airbyte_name or self.name
+
+
+class CacheEntityConfig(BaseModel):
+    """
+    Entity configuration for cache mapping.
+
+    Defines a cache-enabled entity with its fields and optional name aliasing
+    to map between user-facing entity names and cache storage names.
+
+    Used in x-airbyte-cache extension for api_search operations.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    entity: str
+    x_airbyte_name: str | None = Field(default=None, alias="x-airbyte-name")
+    fields: list[CacheFieldConfig]
+
+    @property
+    def cache_name(self) -> str:
+        """Return cache entity name, falling back to entity if alias not specified."""
+        return self.x_airbyte_name or self.entity
+
+
+class CacheConfig(BaseModel):
+    """
+    Cache configuration extension (x-airbyte-cache).
+
+    Defines cache-enabled entities and their field mappings for api_search operations.
+    Supports optional name aliasing via x-airbyte-name for both entities and fields,
+    enabling bidirectional mapping between user-facing names and cache storage names.
+
+    This extension is added to the Info model and provides field-level mapping for
+    search operations that use cached data.
+
+    Example YAML usage:
+        info:
+          title: Stripe API
+          x-airbyte-cache:
+            entities:
+              - entity: customers
+                stream: customers
+                fields:
+                  - name: email
+                    type: ["null", "string"]
+                    description: "Customer email address"
+                  - name: customer_name
+                    x-airbyte-name: name
+                    type: ["null", "string"]
+                    description: "Customer full name"
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    entities: list[CacheEntityConfig]
+
+    def get_entity_mapping(self, user_entity: str) -> CacheEntityConfig | None:
+        """
+        Get entity config by user-facing name.
+
+        Args:
+            user_entity: User-facing entity name to look up
+
+        Returns:
+            CacheEntityConfig if found, None otherwise
+        """
+        for entity in self.entities:
+            if entity.entity == user_entity:
+                return entity
+        return None