airbyte-agent-mcp 0.1.33__py3-none-any.whl → 0.1.60__py3-none-any.whl

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

@@ -14,7 +14,7 @@ are implemented.
 
 from typing import Literal, Optional
 
-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,96 @@ class RetryConfig(BaseModel):
     # Header-based delay extraction
     retry_after_header: str = "Retry-After"
     retry_after_format: Literal["seconds", "milliseconds", "unix_timestamp"] = "seconds"
+
+
+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.
+
+    Used in x-airbyte-cache extension for api_search operations.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    x_airbyte_name: Optional[str] = Field(default=None, alias="x-airbyte-name")
+    type: str | list[str]
+    description: str
+
+    @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: Optional[str] = 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) -> Optional[CacheEntityConfig]:
+        """
+        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

airbyte_agent_mcp/_vendored/connector_sdk/schema/operations.py

@@ -6,7 +6,7 @@ References:
 - https://spec.openapis.org/oas/v3.1.0#path-item-object
 """
 
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
@@ -34,38 +34,38 @@ class Operation(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     # Standard OpenAPI fields
-    tags: Optional[List[str]] = None
-    summary: Optional[str] = None
-    description: Optional[str] = None
-    external_docs: Optional[Dict[str, Any]] = Field(None, alias="externalDocs")
-    operation_id: Optional[str] = Field(None, alias="operationId")
-    parameters: Optional[List[Parameter]] = None
-    request_body: Optional[RequestBody] = Field(None, alias="requestBody")
+    tags: List[str] | None = None
+    summary: str | None = None
+    description: str | None = None
+    external_docs: Dict[str, Any] | None = Field(None, alias="externalDocs")
+    operation_id: str | None = Field(None, alias="operationId")
+    parameters: List[Parameter] | None = None
+    request_body: RequestBody | None = Field(None, alias="requestBody")
     responses: Dict[str, Response] = Field(default_factory=dict)
-    callbacks: Optional[Dict[str, Any]] = None
-    deprecated: Optional[bool] = None
-    security: Optional[List[SecurityRequirement]] = None
-    servers: Optional[List[Any]] = None  # Can override root servers
+    callbacks: Dict[str, Any] | None = None
+    deprecated: bool | None = None
+    security: List[SecurityRequirement] | None = None
+    servers: List[Any] | None = None  # Can override root servers
 
     # Airbyte extensions
     x_airbyte_entity: str = Field(..., alias="x-airbyte-entity")
     x_airbyte_action: ActionTypeLiteral = Field(..., alias="x-airbyte-action")
-    x_airbyte_path_override: Optional[PathOverrideConfig] = Field(
+    x_airbyte_path_override: PathOverrideConfig | None = Field(
         None,
         alias="x-airbyte-path-override",
-        description=("Override path for HTTP requests when OpenAPI path " "differs from actual endpoint"),
+        description=("Override path for HTTP requests when OpenAPI path differs from actual endpoint"),
     )
-    x_airbyte_record_extractor: Optional[str] = Field(
+    x_airbyte_record_extractor: str | None = Field(
         None,
         alias="x-airbyte-record-extractor",
         description=(
             "JSONPath expression to extract records from API response envelopes. "
             "When specified, executor extracts data at this path instead of returning "
-            "full response. Returns array for list/search actions, single record for "
+            "full response. Returns array for list/api_search actions, single record for "
             "get/create/update/delete actions."
         ),
     )
-    x_airbyte_meta_extractor: Optional[Dict[str, str]] = Field(
+    x_airbyte_meta_extractor: Dict[str, str] | None = Field(
         None,
         alias="x-airbyte-meta-extractor",
         description=(
@@ -76,8 +76,8 @@ class Operation(BaseModel):
             "Example: {'pagination': '$.pagination', 'request_id': '$.requestId'}"
         ),
     )
-    x_airbyte_file_url: Optional[str] = Field(None, alias="x-airbyte-file-url")
-    x_airbyte_untested: Optional[bool] = Field(
+    x_airbyte_file_url: str | None = Field(None, alias="x-airbyte-file-url")
+    x_airbyte_untested: bool | None = Field(
         None,
         alias="x-airbyte-untested",
         description=(
@@ -127,20 +127,20 @@ class PathItem(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     # Common fields for all operations
-    summary: Optional[str] = None
-    description: Optional[str] = None
-    servers: Optional[List[Any]] = None
-    parameters: Optional[List[Parameter]] = None
+    summary: str | None = None
+    description: str | None = None
+    servers: List[Any] | None = None
+    parameters: List[Parameter] | None = None
 
     # HTTP methods (all optional)
-    get: Optional[Operation] = None
-    put: Optional[Operation] = None
-    post: Optional[Operation] = None
-    delete: Optional[Operation] = None
-    options: Optional[Operation] = None
-    head: Optional[Operation] = None
-    patch: Optional[Operation] = None
-    trace: Optional[Operation] = None
+    get: Operation | None = None
+    put: Operation | None = None
+    post: Operation | None = None
+    delete: Operation | None = None
+    options: Operation | None = None
+    head: Operation | None = None
+    patch: Operation | None = None
+    trace: Operation | None = None
 
     # Reference support
-    ref: Optional[str] = Field(None, alias="$ref")
+    ref: str | None = Field(None, alias="$ref")

airbyte_agent_mcp/_vendored/connector_sdk/schema/security.py

@@ -6,7 +6,7 @@ References:
 - https://spec.openapis.org/oas/v3.1.0#oauth-flows-object
 """
 
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Dict, List, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
@@ -20,9 +20,9 @@ class OAuth2Flow(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    authorization_url: Optional[str] = Field(None, alias="authorizationUrl")
-    token_url: Optional[str] = Field(None, alias="tokenUrl")
-    refresh_url: Optional[str] = Field(None, alias="refreshUrl")
+    authorization_url: str | None = Field(None, alias="authorizationUrl")
+    token_url: str | None = Field(None, alias="tokenUrl")
+    refresh_url: str | None = Field(None, alias="refreshUrl")
     scopes: Dict[str, str] = Field(default_factory=dict)
 
 
@@ -35,10 +35,10 @@ class OAuth2Flows(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    implicit: Optional[OAuth2Flow] = None
-    password: Optional[OAuth2Flow] = None
-    client_credentials: Optional[OAuth2Flow] = Field(None, alias="clientCredentials")
-    authorization_code: Optional[OAuth2Flow] = Field(None, alias="authorizationCode")
+    implicit: OAuth2Flow | None = None
+    password: OAuth2Flow | None = None
+    client_credentials: OAuth2Flow | None = Field(None, alias="clientCredentials")
+    authorization_code: OAuth2Flow | None = Field(None, alias="authorizationCode")
 
 
 class AuthConfigFieldSpec(BaseModel):
@@ -51,12 +51,12 @@ class AuthConfigFieldSpec(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     type: Literal["string", "integer", "boolean", "number"] = "string"
-    title: Optional[str] = None
-    description: Optional[str] = None
-    format: Optional[str] = None  # e.g., "email", "uri"
-    pattern: Optional[str] = None  # Regex validation
+    title: str | None = None
+    description: str | None = None
+    format: str | None = None  # e.g., "email", "uri"
+    pattern: str | None = None  # Regex validation
     airbyte_secret: bool = Field(False, alias="airbyte_secret")
-    default: Optional[Any] = None
+    default: Any | None = None
 
 
 class AuthConfigOption(BaseModel):
@@ -68,8 +68,8 @@ class AuthConfigOption(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    title: Optional[str] = None
-    description: Optional[str] = None
+    title: str | None = None
+    description: str | None = None
     type: Literal["object"] = "object"
     required: List[str] = Field(default_factory=list)
     properties: Dict[str, AuthConfigFieldSpec] = Field(default_factory=dict)
@@ -77,6 +77,10 @@ class AuthConfigOption(BaseModel):
         default_factory=dict,
         description="Mapping from auth parameters (e.g., 'username', 'password', 'token') to template strings using ${field} syntax",
     )
+    replication_auth_key_mapping: Dict[str, str] | None = Field(
+        None,
+        description="Mapping from source config paths (e.g., 'credentials.api_key') to auth config keys for direct connectors",
+    )
 
 
 class AirbyteAuthConfig(BaseModel):
@@ -92,15 +96,21 @@ class AirbyteAuthConfig(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     # Single option fields
-    title: Optional[str] = None
-    description: Optional[str] = None
-    type: Optional[Literal["object"]] = None
-    required: Optional[List[str]] = None
-    properties: Optional[Dict[str, AuthConfigFieldSpec]] = None
-    auth_mapping: Optional[Dict[str, str]] = None
+    title: str | None = None
+    description: str | None = None
+    type: Literal["object"] | None = None
+    required: List[str] | None = None
+    properties: Dict[str, AuthConfigFieldSpec] | None = None
+    auth_mapping: Dict[str, str] | None = None
+
+    # Replication connector auth mapping
+    replication_auth_key_mapping: Dict[str, str] | None = Field(
+        None,
+        description="Mapping from source config paths (e.g., 'credentials.api_key') to auth config keys for direct connectors",
+    )
 
     # Multiple options (oneOf)
-    one_of: Optional[List[AuthConfigOption]] = Field(None, alias="oneOf")
+    one_of: List[AuthConfigOption] | None = Field(None, alias="oneOf")
 
     @model_validator(mode="after")
     def validate_config_structure(self) -> "AirbyteAuthConfig":
@@ -151,27 +161,27 @@ class SecurityScheme(BaseModel):
 
     # Standard OpenAPI fields
     type: Literal["apiKey", "http", "oauth2", "openIdConnect"]
-    description: Optional[str] = None
+    description: str | None = None
 
     # apiKey specific
-    name: Optional[str] = None
-    in_: Optional[Literal["query", "header", "cookie"]] = Field(None, alias="in")
+    name: str | None = None
+    in_: Literal["query", "header", "cookie"] | None = Field(None, alias="in")
 
     # http specific
-    scheme: Optional[str] = None  # e.g., "basic", "bearer", "digest"
-    bearer_format: Optional[str] = Field(None, alias="bearerFormat")
+    scheme: str | None = None  # e.g., "basic", "bearer", "digest"
+    bearer_format: str | None = Field(None, alias="bearerFormat")
 
     # oauth2 specific
-    flows: Optional[OAuth2Flows] = None
+    flows: OAuth2Flows | None = None
 
     # openIdConnect specific
-    open_id_connect_url: Optional[str] = Field(None, alias="openIdConnectUrl")
+    open_id_connect_url: str | None = Field(None, alias="openIdConnectUrl")
 
     # Airbyte extensions
-    x_token_path: Optional[str] = Field(None, alias="x-airbyte-token-path")
-    x_token_refresh: Optional[Dict[str, Any]] = Field(None, alias="x-airbyte-token-refresh")
-    x_airbyte_auth_config: Optional[AirbyteAuthConfig] = Field(None, alias="x-airbyte-auth-config")
-    x_airbyte_token_extract: Optional[List[str]] = Field(
+    x_token_path: str | None = Field(None, alias="x-airbyte-token-path")
+    x_token_refresh: Dict[str, Any] | None = Field(None, alias="x-airbyte-token-refresh")
+    x_airbyte_auth_config: AirbyteAuthConfig | None = Field(None, alias="x-airbyte-auth-config")
+    x_airbyte_token_extract: List[str] | None = Field(
         None,
         alias="x-airbyte-token-extract",
         description="List of fields to extract from OAuth2 token responses and use as server variables",
@@ -179,7 +189,7 @@ class SecurityScheme(BaseModel):
 
     @field_validator("x_airbyte_token_extract", mode="after")
     @classmethod
-    def validate_token_extract(cls, v: Optional[List[str]]) -> Optional[List[str]]:
+    def validate_token_extract(cls, v: List[str] | None) -> List[str] | None:
         """Validate x-airbyte-token-extract has no duplicates."""
         if v is not None:
             if len(v) != len(set(v)):

airbyte_agent_mcp/_vendored/connector_sdk/secrets.py

@@ -14,7 +14,7 @@ Example:
 
 import os
 import re
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
 from pydantic import SecretStr
 
@@ -72,7 +72,7 @@ class SecretResolutionError(Exception):
 def resolve_env_var_references(
     secret_mappings: Dict[str, Any],
     strict: bool = True,
-    env_vars: Optional[Dict[str, str]] = None,
+    env_vars: Dict[str, str] | None = None,
 ) -> Dict[str, str]:
     """Resolve environment variable references in secret values.
 

airbyte_agent_mcp/_vendored/connector_sdk/telemetry/events.py

@@ -1,8 +1,8 @@
 """Telemetry event models."""
 
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, field
 from datetime import datetime
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
 
 @dataclass
@@ -13,6 +13,7 @@ class BaseEvent:
     session_id: str
     user_id: str
     execution_context: str
+    is_internal_user: bool = field(default=False, kw_only=True)
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert event to dictionary with ISO formatted timestamp."""
@@ -29,8 +30,8 @@ class ConnectorInitEvent(BaseEvent):
     python_version: str
     os_name: str
     os_version: str
-    public_ip: Optional[str] = None
-    connector_version: Optional[str] = None
+    public_ip: str | None = None
+    connector_version: str | None = None
 
 
 @dataclass
@@ -41,9 +42,9 @@ class OperationEvent(BaseEvent):
     entity: str
     action: str
     timing_ms: float
-    public_ip: Optional[str] = None
-    status_code: Optional[int] = None
-    error_type: Optional[str] = None
+    public_ip: str | None = None
+    status_code: int | None = None
+    error_type: str | None = None
 
 
 @dataclass
@@ -55,4 +56,4 @@ class SessionEndEvent(BaseEvent):
     operation_count: int
     success_count: int
     failure_count: int
-    public_ip: Optional[str] = None
+    public_ip: str | None = None

airbyte_agent_mcp/_vendored/connector_sdk/telemetry/tracker.py

@@ -4,7 +4,6 @@ import logging
 import platform
 import sys
 from datetime import datetime
-from typing import Optional
 
 from ..observability import ObservabilitySession
 
@@ -20,7 +19,7 @@ class SegmentTracker:
     def __init__(
         self,
         session: ObservabilitySession,
-        mode: Optional[TelemetryMode] = None,
+        mode: TelemetryMode | None = None,
     ):
         self.session = session
         self.mode = mode or TelemetryConfig.get_mode()
@@ -31,6 +30,8 @@ class SegmentTracker:
 
         if self.enabled:
             try:
+                # NOTE: Import here intentionally - segment is an optional dependency.
+                # This allows the SDK to work without telemetry if segment is not installed.
                 import segment.analytics as analytics
 
                 analytics.write_key = SEGMENT_WRITE_KEY
@@ -47,7 +48,7 @@ class SegmentTracker:
 
     def track_connector_init(
         self,
-        connector_version: Optional[str] = None,
+        connector_version: str | None = None,
     ) -> None:
         """Track connector initialization."""
         if not self.enabled or not self._analytics:
@@ -59,6 +60,7 @@ class SegmentTracker:
                 session_id=self.session.session_id,
                 user_id=self.session.user_id,
                 execution_context=self.session.execution_context,
+                is_internal_user=self.session.is_internal_user,
                 public_ip=self.session.public_ip,
                 connector_name=self.session.connector_name,
                 connector_version=connector_version,
@@ -81,9 +83,9 @@ class SegmentTracker:
         self,
         entity: str,
         action: str,
-        status_code: Optional[int],
+        status_code: int | None,
         timing_ms: float,
-        error_type: Optional[str] = None,
+        error_type: str | None = None,
     ) -> None:
         """Track API operation."""
         # Always track success/failure counts (useful even when tracking is disabled)
@@ -101,6 +103,7 @@ class SegmentTracker:
                 session_id=self.session.session_id,
                 user_id=self.session.user_id,
                 execution_context=self.session.execution_context,
+                is_internal_user=self.session.is_internal_user,
                 public_ip=self.session.public_ip,
                 connector_name=self.session.connector_name,
                 entity=entity,
@@ -130,6 +133,7 @@ class SegmentTracker:
                 session_id=self.session.session_id,
                 user_id=self.session.user_id,
                 execution_context=self.session.execution_context,
+                is_internal_user=self.session.is_internal_user,
                 public_ip=self.session.public_ip,
                 connector_name=self.session.connector_name,
                 duration_seconds=self.session.duration_seconds(),

airbyte_agent_mcp/_vendored/connector_sdk/types.py

@@ -22,7 +22,7 @@ class Action(str, Enum):
     UPDATE = "update"
     DELETE = "delete"
     LIST = "list"
-    SEARCH = "search"
+    API_SEARCH = "api_search"
     DOWNLOAD = "download"
     AUTHORIZE = "authorize"
 
@@ -140,7 +140,7 @@ class AuthConfig(BaseModel):
             ValueError: If this is a multi-auth config or invalid
         """
         if self.is_multi_auth():
-            raise ValueError("Cannot call get_single_option() on multi-auth config. " "Use options list instead.")
+            raise ValueError("Cannot call get_single_option() on multi-auth config. Use options list instead.")
 
         if self.type is None:
             raise ValueError("Invalid AuthConfig: neither single-auth nor multi-auth")
@@ -161,7 +161,7 @@ class EndpointDefinition(BaseModel):
     path: str  # e.g., /v1/customers/{id} (OpenAPI path)
     path_override: PathOverrideConfig | None = Field(
         None,
-        description=("Path override config from x-airbyte-path-override. " "When set, overrides the path for actual HTTP requests."),
+        description=("Path override config from x-airbyte-path-override. When set, overrides the path for actual HTTP requests."),
     )
     action: Action | None = None  # Semantic action (get, list, create, update, delete)
     description: str | None = None
@@ -221,6 +221,10 @@ class EntityDefinition(BaseModel):
     model_config = {"populate_by_name": True}
 
     name: str
+    stream_name: str | None = Field(
+        default=None,
+        description="Airbyte stream name for cache lookup (from x-airbyte-stream-name schema extension)",
+    )
     actions: list[Action]
     endpoints: dict[Action, EndpointDefinition]
     entity_schema: dict[str, Any] | None = Field(default=None, alias="schema")