airbyte-agent-zendesk-support 0.18.21__py3-none-any.whl → 0.18.32__py3-none-any.whl

airbyte_agent_zendesk_support/_vendored/connector_sdk/connector_model_loader.py

@@ -393,16 +393,24 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
     for entity_name, endpoints_dict in entities_map.items():
         actions = list(endpoints_dict.keys())
 
-        # Get schema from components if available
+        # Get schema and stream_name from components if available
         schema = None
+        entity_stream_name = None
         if spec.components:
             # Look for a schema matching the entity name
             for schema_name, schema_def in spec.components.schemas.items():
                 if schema_def.x_airbyte_entity_name == entity_name or schema_name.lower() == entity_name.lower():
                     schema = schema_def.model_dump(by_alias=True)
+                    entity_stream_name = schema_def.x_airbyte_stream_name
                     break
 
-        entity = EntityDefinition(name=entity_name, actions=actions, endpoints=endpoints_dict, schema=schema)
+        entity = EntityDefinition(
+            name=entity_name,
+            stream_name=entity_stream_name,
+            actions=actions,
+            endpoints=endpoints_dict,
+            schema=schema,
+        )
         entities.append(entity)
 
     # Extract retry config from x-airbyte-retry-config extension

airbyte_agent_zendesk_support/_vendored/connector_sdk/executor/local_executor.py

@@ -674,16 +674,16 @@ class LocalExecutor:
         return {key: value for key, value in params.items() if key in allowed_params}
 
     def _extract_body(self, allowed_fields: list[str], params: dict[str, Any]) -> dict[str, Any]:
-        """Extract body fields from params.
+        """Extract body fields from params, filtering out None values.
 
         Args:
             allowed_fields: List of allowed body field names
             params: All parameters
 
         Returns:
-            Dictionary of body fields
+            Dictionary of body fields with None values filtered out
         """
-        return {key: value for key, value in params.items() if key in allowed_fields}
+        return {key: value for key, value in params.items() if key in allowed_fields and value is not None}
 
     def _serialize_deep_object_params(self, params: dict[str, Any], deep_object_param_names: list[str]) -> dict[str, Any]:
         """Serialize deepObject parameters to bracket notation format.
@@ -837,15 +837,65 @@ class LocalExecutor:
             Request body dict or None if no body needed
         """
         if endpoint.graphql_body:
-            return self._build_graphql_body(endpoint.graphql_body, params)
+            # Extract defaults from query_params_schema for GraphQL variable interpolation
+            param_defaults = {name: schema.get("default") for name, schema in endpoint.query_params_schema.items() if "default" in schema}
+            return self._build_graphql_body(endpoint.graphql_body, params, param_defaults)
         elif endpoint.body_fields:
             return self._extract_body(endpoint.body_fields, params)
         return None
 
+    def _flatten_form_data(self, data: dict[str, Any], parent_key: str = "") -> dict[str, Any]:
+        """Flatten nested dict/list structures into bracket notation for form encoding.
+
+        Stripe and similar APIs require nested arrays/objects to be encoded using bracket
+        notation when using application/x-www-form-urlencoded content type.
+
+        Args:
+            data: Nested dict with arrays/objects to flatten
+            parent_key: Parent key for nested structures (used in recursion)
+
+        Returns:
+            Flattened dict with bracket notation keys
+
+        Examples:
+            >>> _flatten_form_data({"items": [{"price": "p1", "qty": 1}]})
+            {"items[0][price]": "p1", "items[0][qty]": 1}
+
+            >>> _flatten_form_data({"customer": "cus_123", "metadata": {"key": "value"}})
+            {"customer": "cus_123", "metadata[key]": "value"}
+        """
+        flattened = {}
+
+        for key, value in data.items():
+            new_key = f"{parent_key}[{key}]" if parent_key else key
+
+            if isinstance(value, dict):
+                # Recursively flatten nested dicts
+                flattened.update(self._flatten_form_data(value, new_key))
+            elif isinstance(value, list):
+                # Flatten arrays with indexed bracket notation
+                for i, item in enumerate(value):
+                    indexed_key = f"{new_key}[{i}]"
+                    if isinstance(item, dict):
+                        # Nested dict in array - recurse
+                        flattened.update(self._flatten_form_data(item, indexed_key))
+                    elif isinstance(item, list):
+                        # Nested list in array - recurse
+                        flattened.update(self._flatten_form_data({str(i): item}, new_key))
+                    else:
+                        # Primitive value in array
+                        flattened[indexed_key] = item
+            else:
+                # Primitive value - add directly
+                flattened[new_key] = value
+
+        return flattened
+
     def _determine_request_format(self, endpoint: EndpointDefinition, body: dict[str, Any] | None) -> dict[str, Any]:
         """Determine json/data parameters for HTTP request.
 
         GraphQL always uses JSON, regardless of content_type setting.
+        For form-encoded requests, nested structures are flattened into bracket notation.
 
         Args:
             endpoint: Endpoint definition
@@ -862,7 +912,9 @@ class LocalExecutor:
         if is_graphql or endpoint.content_type.value == "application/json":
             return {"json": body}
         elif endpoint.content_type.value == "application/x-www-form-urlencoded":
-            return {"data": body}
+            # Flatten nested structures for form encoding
+            flattened_body = self._flatten_form_data(body)
+            return {"data": flattened_body}
 
         return {}
 
@@ -903,12 +955,18 @@ class LocalExecutor:
 
         return query
 
-    def _build_graphql_body(self, graphql_config: dict[str, Any], params: dict[str, Any]) -> dict[str, Any]:
+    def _build_graphql_body(
+        self,
+        graphql_config: dict[str, Any],
+        params: dict[str, Any],
+        param_defaults: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
         """Build GraphQL request body with variable substitution and field selection.
 
         Args:
             graphql_config: GraphQL configuration from x-airbyte-body-type extension
             params: Parameters from execute() call
+            param_defaults: Default values for params from query_params_schema
 
         Returns:
             GraphQL request body: {"query": "...", "variables": {...}}
@@ -922,7 +980,7 @@ class LocalExecutor:
 
         # Substitute variables from params
         if "variables" in graphql_config and graphql_config["variables"]:
-            body["variables"] = self._interpolate_variables(graphql_config["variables"], params)
+            body["variables"] = self._interpolate_variables(graphql_config["variables"], params, param_defaults)
 
         # Add operation name if specified
         if "operationName" in graphql_config:
@@ -981,7 +1039,12 @@ class LocalExecutor:
         fields_str = " ".join(graphql_fields)
         return query.replace("{{ fields }}", fields_str)
 
-    def _interpolate_variables(self, variables: dict[str, Any], params: dict[str, Any]) -> dict[str, Any]:
+    def _interpolate_variables(
+        self,
+        variables: dict[str, Any],
+        params: dict[str, Any],
+        param_defaults: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
         """Recursively interpolate variables using params.
 
         Preserves types (doesn't stringify everything).
@@ -990,15 +1053,18 @@ class LocalExecutor:
         - Direct replacement: "{{ owner }}" → params["owner"] (preserves type)
         - Nested objects: {"input": {"name": "{{ name }}"}}
         - Arrays: [{"id": "{{ id }}"}]
-        - Unsubstituted placeholders: "{{ states }}" → None (for optional params)
+        - Default values: "{{ per_page }}" → param_defaults["per_page"] if not in params
+        - Unsubstituted placeholders: "{{ states }}" → None (for optional params without defaults)
 
         Args:
             variables: Variables dict with template placeholders
             params: Parameters to substitute
+            param_defaults: Default values for params from query_params_schema
 
         Returns:
             Interpolated variables dict with types preserved
         """
+        defaults = param_defaults or {}
 
         def interpolate_value(value: Any) -> Any:
             if isinstance(value, str):
@@ -1012,8 +1078,15 @@ class LocalExecutor:
                         value = value.replace(placeholder, str(param_value))
 
                 # Check if any unsubstituted placeholders remain
-                # If so, return None (treats as "not provided" for optional params)
                 if re.search(r"\{\{\s*\w+\s*\}\}", value):
+                    # Extract placeholder name and check for default value
+                    match = re.search(r"\{\{\s*(\w+)\s*\}\}", value)
+                    if match:
+                        param_name = match.group(1)
+                        if param_name in defaults:
+                            # Use default value (preserves type)
+                            return defaults[param_name]
+                    # No default found - return None (for optional params)
                     return None
 
                 return value
@@ -1151,21 +1224,18 @@ class LocalExecutor:
         if action not in (Action.CREATE, Action.UPDATE):
             return
 
-        # Check if endpoint has body fields defined
-        if not endpoint.body_fields:
+        # Get the request schema to find truly required fields
+        request_schema = endpoint.request_schema
+        if not request_schema:
             return
 
-        # For now, we treat all body_fields as potentially required for CREATE/UPDATE
-        # In a more advanced implementation, we could parse the request schema
-        # to identify truly required fields
-        missing_fields = []
-        for field in endpoint.body_fields:
-            if field not in params:
-                missing_fields.append(field)
+        # Only validate fields explicitly marked as required in the schema
+        required_fields = request_schema.get("required", [])
+        missing_fields = [field for field in required_fields if field not in params]
 
         if missing_fields:
             raise MissingParameterError(
-                f"Missing required body fields for {entity}.{action.value}: {missing_fields}. Provided parameters: {list(params.keys())}"
+                f"Missing required body fields for {entity}.{action.value}: {missing_fields}. " f"Provided parameters: {list(params.keys())}"
             )
 
     async def close(self):

airbyte_agent_zendesk_support/_vendored/connector_sdk/extensions.py

@@ -159,6 +159,38 @@ Example:
     ```
 """
 
+AIRBYTE_STREAM_NAME = "x-airbyte-stream-name"
+"""
+Extension: x-airbyte-stream-name
+Location: Schema object (in components.schemas)
+Type: string
+Required: No
+
+Description:
+    Specifies the Airbyte stream name for cache lookup purposes. This maps the entity
+    to the corresponding Airbyte stream, enabling cache-based data retrieval. When
+    specified, the EntityDefinition.stream_name field will be populated with this value.
+
+    This extension is placed on Schema objects alongside x-airbyte-entity-name, following
+    the same pattern. The stream name is an entity-level property (not operation-level)
+    since an entity maps to exactly one Airbyte stream.
+
+Example:
+    ```yaml
+    components:
+      schemas:
+        Customer:
+          type: object
+          x-airbyte-entity-name: customers
+          x-airbyte-stream-name: customers
+          properties:
+            id:
+              type: string
+            name:
+              type: string
+    ```
+"""
+
 AIRBYTE_TOKEN_PATH = "x-airbyte-token-path"
 """
 Extension: x-airbyte-token-path
@@ -548,6 +580,7 @@ def get_all_extension_names() -> list[str]:
         AIRBYTE_ENTITY,
         AIRBYTE_ACTION,
         AIRBYTE_ENTITY_NAME,
+        AIRBYTE_STREAM_NAME,
         AIRBYTE_TOKEN_PATH,
         AIRBYTE_BODY_TYPE,
         AIRBYTE_PATH_OVERRIDE,
@@ -594,6 +627,12 @@ EXTENSION_REGISTRY = {
         "required": False,
         "description": "Links schema to an entity/stream",
     },
+    AIRBYTE_STREAM_NAME: {
+        "location": "schema",
+        "type": "string",
+        "required": False,
+        "description": "Maps entity to Airbyte stream for cache lookup",
+    },
     AIRBYTE_TOKEN_PATH: {
         "location": "securityScheme",
         "type": "string",

airbyte_agent_zendesk_support/_vendored/connector_sdk/introspection.py

@@ -0,0 +1,262 @@
+"""
+Shared introspection utilities for connector metadata.
+
+This module provides utilities for introspecting connector metadata,
+generating descriptions, and formatting parameter signatures. These
+functions are used by both the runtime decorators and the generated
+connector code.
+
+The module is designed to work with any object conforming to the
+ConnectorModel and EndpointDefinition interfaces from connector_sdk.types.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+# Constants
+MAX_EXAMPLE_QUESTIONS = 5  # Maximum number of example questions to include in description
+
+
+class EndpointProtocol(Protocol):
+    """Protocol defining the expected interface for endpoint parameters.
+
+    This allows functions to work with any endpoint-like object
+    that has these attributes, including EndpointDefinition and mock objects.
+    """
+
+    path_params: list[str]
+    path_params_schema: dict[str, dict[str, Any]]
+    query_params: list[str]
+    query_params_schema: dict[str, dict[str, Any]]
+    body_fields: list[str]
+    request_schema: dict[str, Any] | None
+
+
+class EntityProtocol(Protocol):
+    """Protocol defining the expected interface for entity definitions."""
+
+    name: str
+    actions: list[Any]
+    endpoints: dict[Any, EndpointProtocol]
+
+
+class ConnectorModelProtocol(Protocol):
+    """Protocol defining the expected interface for connector model parameters.
+
+    This allows functions to work with any connector-like object
+    that has these attributes, including ConnectorModel and mock objects.
+    """
+
+    @property
+    def entities(self) -> list[EntityProtocol]: ...
+
+    @property
+    def openapi_spec(self) -> Any: ...
+
+
+def format_param_signature(endpoint: EndpointProtocol) -> str:
+    """Format parameter signature for an endpoint action.
+
+    Returns a string like: (id*) or (limit?, starting_after?, email?)
+    where * = required, ? = optional
+
+    Args:
+        endpoint: Object conforming to EndpointProtocol (e.g., EndpointDefinition)
+
+    Returns:
+        Formatted parameter signature string
+    """
+    params = []
+
+    # Defensive: safely access attributes with defaults for malformed endpoints
+    path_params = getattr(endpoint, "path_params", []) or []
+    query_params = getattr(endpoint, "query_params", []) or []
+    query_params_schema = getattr(endpoint, "query_params_schema", {}) or {}
+    body_fields = getattr(endpoint, "body_fields", []) or []
+    request_schema = getattr(endpoint, "request_schema", None)
+
+    # Path params (always required)
+    for name in path_params:
+        params.append(f"{name}*")
+
+    # Query params
+    for name in query_params:
+        schema = query_params_schema.get(name, {})
+        required = schema.get("required", False)
+        params.append(f"{name}{'*' if required else '?'}")
+
+    # Body fields
+    if request_schema:
+        required_fields = set(request_schema.get("required", []))
+        for name in body_fields:
+            params.append(f"{name}{'*' if name in required_fields else '?'}")
+
+    return f"({', '.join(params)})" if params else "()"
+
+
+def describe_entities(model: ConnectorModelProtocol) -> list[dict[str, Any]]:
+    """Generate entity descriptions from ConnectorModel.
+
+    Returns a list of entity descriptions with detailed parameter information
+    for each action. This is used by generated connectors' describe() method.
+
+    Args:
+        model: Object conforming to ConnectorModelProtocol (e.g., ConnectorModel)
+
+    Returns:
+        List of entity description dicts with keys:
+        - entity_name: Name of the entity (e.g., "contacts", "deals")
+        - description: Entity description from the first endpoint
+        - available_actions: List of actions (e.g., ["list", "get", "create"])
+        - parameters: Dict mapping action -> list of parameter dicts
+    """
+    entities = []
+    for entity_def in model.entities:
+        description = ""
+        parameters: dict[str, list[dict[str, Any]]] = {}
+
+        endpoints = getattr(entity_def, "endpoints", {}) or {}
+        if endpoints:
+            for action, endpoint in endpoints.items():
+                # Get description from first endpoint that has one
+                if not description:
+                    endpoint_desc = getattr(endpoint, "description", None)
+                    if endpoint_desc:
+                        description = endpoint_desc
+
+                action_params: list[dict[str, Any]] = []
+
+                # Defensive: safely access endpoint attributes
+                path_params = getattr(endpoint, "path_params", []) or []
+                path_params_schema = getattr(endpoint, "path_params_schema", {}) or {}
+                query_params = getattr(endpoint, "query_params", []) or []
+                query_params_schema = getattr(endpoint, "query_params_schema", {}) or {}
+                body_fields = getattr(endpoint, "body_fields", []) or []
+                request_schema = getattr(endpoint, "request_schema", None)
+
+                # Path params (always required)
+                for param_name in path_params:
+                    schema = path_params_schema.get(param_name, {})
+                    action_params.append(
+                        {
+                            "name": param_name,
+                            "in": "path",
+                            "required": True,
+                            "type": schema.get("type", "string"),
+                            "description": schema.get("description", ""),
+                        }
+                    )
+
+                # Query params
+                for param_name in query_params:
+                    schema = query_params_schema.get(param_name, {})
+                    action_params.append(
+                        {
+                            "name": param_name,
+                            "in": "query",
+                            "required": schema.get("required", False),
+                            "type": schema.get("type", "string"),
+                            "description": schema.get("description", ""),
+                        }
+                    )
+
+                # Body fields
+                if request_schema:
+                    required_fields = request_schema.get("required", [])
+                    properties = request_schema.get("properties", {})
+                    for param_name in body_fields:
+                        prop = properties.get(param_name, {})
+                        action_params.append(
+                            {
+                                "name": param_name,
+                                "in": "body",
+                                "required": param_name in required_fields,
+                                "type": prop.get("type", "string"),
+                                "description": prop.get("description", ""),
+                            }
+                        )
+
+                if action_params:
+                    # Action is an enum, use .value to get string
+                    action_key = action.value if hasattr(action, "value") else str(action)
+                    parameters[action_key] = action_params
+
+        actions = getattr(entity_def, "actions", []) or []
+        entities.append(
+            {
+                "entity_name": entity_def.name,
+                "description": description,
+                "available_actions": [a.value if hasattr(a, "value") else str(a) for a in actions],
+                "parameters": parameters,
+            }
+        )
+
+    return entities
+
+
+def generate_tool_description(model: ConnectorModelProtocol) -> str:
+    """Generate AI tool description from connector metadata.
+
+    Produces a detailed description that includes:
+    - Per-entity/action parameter signatures with required (*) and optional (?) markers
+    - Response structure documentation with pagination hints
+    - Example questions if available in the OpenAPI spec
+
+    This is used by the Connector.describe class method decorator to populate
+    function docstrings for AI framework integration.
+
+    Args:
+        model: Object conforming to ConnectorModelProtocol (e.g., ConnectorModel)
+
+    Returns:
+        Formatted description string suitable for AI tool documentation
+    """
+    lines = []
+
+    # Entity/action parameter details (including pagination params like limit, starting_after)
+    lines.append("ENTITIES AND PARAMETERS:")
+    for entity in model.entities:
+        lines.append(f"  {entity.name}:")
+        actions = getattr(entity, "actions", []) or []
+        endpoints = getattr(entity, "endpoints", {}) or {}
+        for action in actions:
+            action_str = action.value if hasattr(action, "value") else str(action)
+            endpoint = endpoints.get(action)
+            if endpoint:
+                param_sig = format_param_signature(endpoint)
+                lines.append(f"    - {action_str}{param_sig}")
+            else:
+                lines.append(f"    - {action_str}()")
+
+    # Response structure (brief, includes pagination hint)
+    lines.append("")
+    lines.append("RESPONSE STRUCTURE:")
+    lines.append("  - list/search: {data: [...], meta: {has_more: bool}}")
+    lines.append("  - get: Returns entity directly (no envelope)")
+    lines.append("  To paginate: pass starting_after=<last_id> while has_more is true")
+
+    # Add example questions if available in openapi_spec
+    openapi_spec = getattr(model, "openapi_spec", None)
+    if openapi_spec:
+        info = getattr(openapi_spec, "info", None)
+        if info:
+            example_questions = getattr(info, "x_airbyte_example_questions", None)
+            if example_questions:
+                supported = getattr(example_questions, "supported", None)
+                if supported:
+                    lines.append("")
+                    lines.append("EXAMPLE QUESTIONS:")
+                    for q in supported[:MAX_EXAMPLE_QUESTIONS]:
+                        lines.append(f"  - {q}")
+
+    # Generic parameter description for function signature
+    lines.append("")
+    lines.append("FUNCTION PARAMETERS:")
+    lines.append("  - entity: Entity name (string)")
+    lines.append("  - action: Operation to perform (string)")
+    lines.append("  - params: Operation parameters (dict) - see entity details above")
+    lines.append("")
+    lines.append("Parameter markers: * = required, ? = optional")
+
+    return "\n".join(lines)

airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/components.py

@@ -65,8 +65,9 @@ class Schema(BaseModel):
     write_only: Optional[bool] = Field(None, alias="writeOnly")
     deprecated: Optional[bool] = None
 
-    # Airbyte extension
+    # 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")
 
 
 class Parameter(BaseModel):

airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/security.py

@@ -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: Optional[Dict[str, str]] = Field(
+        None,
+        description="Mapping from source config paths (e.g., 'credentials.api_key') to auth config keys for direct connectors",
+    )
 
 
 class AirbyteAuthConfig(BaseModel):
@@ -99,6 +103,12 @@ class AirbyteAuthConfig(BaseModel):
     properties: Optional[Dict[str, AuthConfigFieldSpec]] = None
     auth_mapping: Optional[Dict[str, str]] = None
 
+    # Replication connector auth mapping
+    replication_auth_key_mapping: Optional[Dict[str, str]] = 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")
 

airbyte_agent_zendesk_support/_vendored/connector_sdk/types.py

@@ -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")

airbyte_agent_zendesk_support/connector.py

@@ -4,14 +4,15 @@ zendesk-support connector.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, AsyncIterator, overload
+import logging
+from typing import TYPE_CHECKING, Any, Callable, TypeVar, AsyncIterator, overload
 try:
     from typing import Literal
 except ImportError:
     from typing_extensions import Literal
 
 from .connector_model import ZendeskSupportConnectorModel
-
+from ._vendored.connector_sdk.introspection import describe_entities, generate_tool_description
 from .types import (
     ArticleAttachmentsDownloadParams,
     ArticleAttachmentsGetParams,
@@ -53,7 +54,6 @@ from .types import (
     ViewsGetParams,
     ViewsListParams,
 )
-
 if TYPE_CHECKING:
     from .models import ZendeskSupportAuthConfig
 # Import specific auth config classes for multi-auth isinstance checks
@@ -102,6 +102,9 @@ from .models import (
     ArticleAttachmentsGetResult,
 )
 
+# TypeVar for decorator type preservation
+_F = TypeVar("_F", bound=Callable[..., Any])
+
 
 class ZendeskSupportConnector:
     """
@@ -111,7 +114,7 @@ class ZendeskSupportConnector:
     """
 
     connector_name = "zendesk-support"
-    connector_version = "0.1.3"
+    connector_version = "0.1.4"
     vendored_sdk_version = "0.1.0"  # Version of vendored connector-sdk
 
     # Map of (entity, action) -> has_extractors for envelope wrapping decision
@@ -712,6 +715,88 @@ class ZendeskSupportConnector:
             # No extractors - return raw response data
             return result.data
 
+    # ===== INTROSPECTION METHODS =====
+
+    @classmethod
+    def describe(cls, func: _F) -> _F:
+        """
+        Decorator that populates a function's docstring with connector capabilities.
+
+        This class method can be used as a decorator to automatically generate
+        comprehensive documentation for AI tool functions.
+
+        Usage:
+            @mcp.tool()
+            @ZendeskSupportConnector.describe
+            async def execute(entity: str, action: str, params: dict):
+                '''Execute operations.'''
+                ...
+
+        The decorated function's __doc__ will be updated with:
+        - Available entities and their actions
+        - Parameter signatures with required (*) and optional (?) markers
+        - Response structure documentation
+        - Example questions (if available in OpenAPI spec)
+
+        Args:
+            func: The function to decorate
+
+        Returns:
+            The same function with updated __doc__
+        """
+        description = generate_tool_description(ZendeskSupportConnectorModel)
+
+        original_doc = func.__doc__ or ""
+        if original_doc.strip():
+            func.__doc__ = f"{original_doc.strip()}\n\n{description}"
+        else:
+            func.__doc__ = description
+
+        return func
+
+    def list_entities(self) -> list[dict[str, Any]]:
+        """
+        Get structured data about available entities, actions, and parameters.
+
+        Returns a list of entity descriptions with:
+        - entity_name: Name of the entity (e.g., "contacts", "deals")
+        - description: Entity description from the first endpoint
+        - available_actions: List of actions (e.g., ["list", "get", "create"])
+        - parameters: Dict mapping action -> list of parameter dicts
+
+        Example:
+            entities = connector.list_entities()
+            for entity in entities:
+                print(f"{entity['entity_name']}: {entity['available_actions']}")
+        """
+        return describe_entities(ZendeskSupportConnectorModel)
+
+    def entity_schema(self, entity: str) -> dict[str, Any] | None:
+        """
+        Get the JSON schema for an entity.
+
+        Args:
+            entity: Entity name (e.g., "contacts", "companies")
+
+        Returns:
+            JSON schema dict describing the entity structure, or None if not found.
+
+        Example:
+            schema = connector.entity_schema("contacts")
+            if schema:
+                print(f"Contact properties: {list(schema.get('properties', {}).keys())}")
+        """
+        entity_def = next(
+            (e for e in ZendeskSupportConnectorModel.entities if e.name == entity),
+            None
+        )
+        if entity_def is None:
+            logging.getLogger(__name__).warning(
+                f"Entity '{entity}' not found. Available entities: "
+                f"{[e.name for e in ZendeskSupportConnectorModel.entities]}"
+            )
+        return entity_def.entity_schema if entity_def else None
+
 
 
 class TicketsQuery:

airbyte_agent_zendesk_support/connector_model.py

@@ -30,7 +30,7 @@ from uuid import (
 ZendeskSupportConnectorModel: ConnectorModel = ConnectorModel(
     id=UUID('79c1aa37-dae3-42ae-b333-d1c105477715'),
     name='zendesk-support',
-    version='0.1.3',
+    version='0.1.4',
     base_url='https://{subdomain}.zendesk.com/api/v2',
     auth=AuthConfig(
         options=[

{airbyte_agent_zendesk_support-0.18.21.dist-info → airbyte_agent_zendesk_support-0.18.32.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airbyte-agent-zendesk-support
-Version: 0.18.21
+Version: 0.18.32
 Summary: Airbyte Zendesk-Support Connector for AI platforms
 Project-URL: Homepage, https://github.com/airbytehq/airbyte-embedded
 Project-URL: Documentation, https://github.com/airbytehq/airbyte-embedded/tree/main/integrations
@@ -43,22 +43,26 @@ for customer support analytics and service performance insights.
 
 ## Example questions
 
+The Zendesk-Support connector is optimized to handle prompts like these.
+
 - Show me the tickets assigned to me last week
 - What are the top 5 support issues our organization has faced this month?
-- List all unresolved tickets for [customerX]
+- List all unresolved tickets for \{customer\}
 - Analyze the satisfaction ratings for our support team in the last 30 days
 - Compare ticket resolution times across different support groups
-- Show me the details of recent tickets tagged with [specific tag]
+- Show me the details of recent tickets tagged with \{tag\}
 - Identify the most common ticket fields used in our support workflow
 - Summarize the performance of our SLA policies this quarter
 
 ## Unsupported questions
 
-- Create a new support ticket for [customerX]
+The Zendesk-Support connector isn't currently able to handle prompts like these.
+
+- Create a new support ticket for \{customer\}
 - Update the priority of this ticket
-- Assign this ticket to [teamMember]
+- Assign this ticket to \{team_member\}
 - Delete these old support tickets
-- Send an automatic response to [customerX]
+- Send an automatic response to \{customer\}
 
 ## Installation
 
@@ -68,11 +72,16 @@ uv pip install airbyte-agent-zendesk-support
 
 ## Usage
 
+This connector supports multiple authentication methods:
+
+### OAuth 2.0
+
 ```python
-from airbyte_agent_zendesk_support import ZendeskSupportConnector, ZendeskSupportAuthConfig
+from airbyte_agent_zendesk_support import ZendeskSupportConnector
+from airbyte_agent_zendesk_support.models import ZendeskSupportOauth20AuthConfig
 
 connector = ZendeskSupportConnector(
-  auth_config=ZendeskSupportAuthConfig(
+  auth_config=ZendeskSupportOauth20AuthConfig(
     access_token="...",
     refresh_token="..."
   )
@@ -80,6 +89,22 @@ connector = ZendeskSupportConnector(
 result = await connector.tickets.list()
 ```
 
+### API Token
+
+```python
+from airbyte_agent_zendesk_support import ZendeskSupportConnector
+from airbyte_agent_zendesk_support.models import ZendeskSupportApiTokenAuthConfig
+
+connector = ZendeskSupportConnector(
+  auth_config=ZendeskSupportApiTokenAuthConfig(
+    email="...",
+    api_token="..."
+  )
+)
+result = await connector.tickets.list()
+```
+
+
 ## Full documentation
 
 This connector supports the following entities and actions.
@@ -116,6 +141,6 @@ For the service's official API docs, see the [Zendesk-Support API reference](htt
 
 ## Version information
 
-- **Package version:** 0.18.21
-- **Connector version:** 0.1.3
-- **Generated with Connector SDK commit SHA:** f7c55d3e3cdc7568cab2da9d736285eec58f044b
+- **Package version:** 0.18.32
+- **Connector version:** 0.1.4
+- **Generated with Connector SDK commit SHA:** 3c7bfdfd1100dd20420a61cec56549b65820ea0f

{airbyte_agent_zendesk_support-0.18.21.dist-info → airbyte_agent_zendesk_support-0.18.32.dist-info}/RECORD

@@ -1,26 +1,27 @@
 airbyte_agent_zendesk_support/__init__.py,sha256=MPz4HU055DRA3-1qgbGXh2E0YHmhcexQCFl-Tz21gm4,6227
-airbyte_agent_zendesk_support/connector.py,sha256=7AYDMDbkygncAVYtxo0q880C6SrVZQhaCvK8p0bKiOQ,63878
-airbyte_agent_zendesk_support/connector_model.py,sha256=q-rn6aRvFt4H-neQ1HQRX7oq2MDEJY7MMuSaEAhGYCk,241131
+airbyte_agent_zendesk_support/connector.py,sha256=VYOTY7bEtXsvjyZSggoeS4lbSbGUsnVmtq3B2awkW5o,67058
+airbyte_agent_zendesk_support/connector_model.py,sha256=SAEWsLhW517Gc5eajkkYV1fQEGpsLlMALs2pTJ9BcPk,241131
 airbyte_agent_zendesk_support/models.py,sha256=31bsOmf4nBdf8EXN3JpYzXW8mx6gv1xaZjeuEBgSzws,36399
 airbyte_agent_zendesk_support/types.py,sha256=3CxJ8HosRMyzNEbVmRbybNCTVj9Ycxr7io25TP3YcCQ,6337
 airbyte_agent_zendesk_support/_vendored/__init__.py,sha256=ILl7AHXMui__swyrjxrh9yRa4dLiwBvV6axPWFWty80,38
 airbyte_agent_zendesk_support/_vendored/connector_sdk/__init__.py,sha256=T5o7roU6NSpH-lCAGZ338sE5dlh4ZU6i6IkeG1zpems,1949
 airbyte_agent_zendesk_support/_vendored/connector_sdk/auth_strategies.py,sha256=0BfIISVzuvZTAYZjQFOOhKTpw0QuKDlLQBQ1PQo-V2M,39967
 airbyte_agent_zendesk_support/_vendored/connector_sdk/auth_template.py,sha256=vKnyA21Jp33EuDjkIUAf1PGicwk4t9kZAPJuAgAZKzU,4458
-airbyte_agent_zendesk_support/_vendored/connector_sdk/connector_model_loader.py,sha256=BeX4QykMUQZk5qY--WuwxXClI7FBDxxbGguqcztAd8A,34663
+airbyte_agent_zendesk_support/_vendored/connector_sdk/connector_model_loader.py,sha256=nKrXfe-FAyvNMkW7AqGzxrp5wXdaHiqC0yIFJoIVwlY,34890
 airbyte_agent_zendesk_support/_vendored/connector_sdk/constants.py,sha256=uH4rjBX6WsBP8M0jt7AUJI9w5Adn4wvJwib7Gdfkr1M,2736
 airbyte_agent_zendesk_support/_vendored/connector_sdk/exceptions.py,sha256=ss5MGv9eVPmsbLcLWetuu3sDmvturwfo6Pw3M37Oq5k,481
-airbyte_agent_zendesk_support/_vendored/connector_sdk/extensions.py,sha256=iWA2i0kiiGZY84H8P25A6QmfbuZwu7euMcj4-Vx2DOQ,20185
+airbyte_agent_zendesk_support/_vendored/connector_sdk/extensions.py,sha256=fWy9uwGUCjPO1KDYuGZo9nkrNU35P-dLcqi4K6UF4uA,21371
 airbyte_agent_zendesk_support/_vendored/connector_sdk/http_client.py,sha256=NdccrrBHI5rW56XnXcP54arCwywIVKnMeSQPas6KlOM,27466
+airbyte_agent_zendesk_support/_vendored/connector_sdk/introspection.py,sha256=6v3YNdca8qe8qIz3m97GZ_ll_Ih3oUKMrqrdipPcpRk,10331
 airbyte_agent_zendesk_support/_vendored/connector_sdk/secrets.py,sha256=UWcO9fP-vZwcfkAuvlZahlOCTOwdNN860BIwe8X4jxw,6868
-airbyte_agent_zendesk_support/_vendored/connector_sdk/types.py,sha256=sS9olOyT-kVemHmcFll2ePFRhTdGMbWcz7bSgV-MuSw,8114
+airbyte_agent_zendesk_support/_vendored/connector_sdk/types.py,sha256=TI-O7EyWAoppGc9G7kXHwceYWekt_sxXmXKxD1xC_7U,8285
 airbyte_agent_zendesk_support/_vendored/connector_sdk/utils.py,sha256=G4LUXOC2HzPoND2v4tQW68R9uuPX9NQyCjaGxb7Kpl0,1958
 airbyte_agent_zendesk_support/_vendored/connector_sdk/validation.py,sha256=CDjCux1eg35a0Y4BegSivzIwZjiTqOxYWotWNLqTSVU,31792
 airbyte_agent_zendesk_support/_vendored/connector_sdk/cloud_utils/__init__.py,sha256=4799Hv9f2zxDVj1aLyQ8JpTEuFTp_oOZMRz-NZCdBJg,134
 airbyte_agent_zendesk_support/_vendored/connector_sdk/cloud_utils/client.py,sha256=HoDgZuEgGHj78P-BGwUf6HGPVWynbdKjGOmjb-JDk58,7188
 airbyte_agent_zendesk_support/_vendored/connector_sdk/executor/__init__.py,sha256=EmG9YQNAjSuYCVB4D5VoLm4qpD1KfeiiOf7bpALj8p8,702
 airbyte_agent_zendesk_support/_vendored/connector_sdk/executor/hosted_executor.py,sha256=YQ-qfT7PZh9izNFHHe7SAcETiZOKrWjTU-okVb0_VL8,7079
-airbyte_agent_zendesk_support/_vendored/connector_sdk/executor/local_executor.py,sha256=hHlBTtvykrUcfypzyW0e61fU4e3vlxc90mypCFzgSl0,61879
+airbyte_agent_zendesk_support/_vendored/connector_sdk/executor/local_executor.py,sha256=IPe4q3FsN22zqCQfT836uQwhnnl3Y9g6o_ZBrZEjTuc,65271
 airbyte_agent_zendesk_support/_vendored/connector_sdk/executor/models.py,sha256=lYVT_bNcw-PoIks4WHNyl2VY-lJVf2FntzINSOBIheE,5845
 airbyte_agent_zendesk_support/_vendored/connector_sdk/http/__init__.py,sha256=y8fbzZn-3yV9OxtYz8Dy6FFGI5v6TOqADd1G3xHH3Hw,911
 airbyte_agent_zendesk_support/_vendored/connector_sdk/http/config.py,sha256=6J7YIIwHC6sRu9i-yKa5XvArwK2KU60rlnmxzDZq3lw,3283
@@ -41,15 +42,15 @@ airbyte_agent_zendesk_support/_vendored/connector_sdk/performance/instrumentatio
 airbyte_agent_zendesk_support/_vendored/connector_sdk/performance/metrics.py,sha256=3-wPwlJyfVLUIG3y7ESxk0avhkILk3z8K7zSrnlZf5U,2833
 airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/__init__.py,sha256=Uymu-QuzGJuMxexBagIvUxpVAigIuIhz3KeBl_Vu4Ko,1638
 airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/base.py,sha256=eN6YfHwsYNz_0CE-S715Me8x3gQWTtaRk1vhFjEZF8I,4799
-airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/components.py,sha256=2ivMNhUAcovw88qvDkW221ILf1L63eXteztTDZL46us,7989
+airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/components.py,sha256=4clYbIJNqfmFj7Te31ZqC3Rr5E2v33BeXyQx1wp3oj0,8076
 airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/connector.py,sha256=VFBOzIkLgYBR1XUTmyrPGqBkX8PP-zsG8avQcdJUqXs,3864
 airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/extensions.py,sha256=LdoCuMLNdCj68O47qAL4v8xmqGz5tJgRiNZL5JnL9uw,3311
 airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/operations.py,sha256=zInMjx9iOEVZo-CCWw06Uk2SFg7HtUAXXpO5kFGUwNk,5825
-airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/security.py,sha256=Jtrhb58d1zssN5yR7LhLJi-QK0PsZKT7uIvPqanF0co,8114
+airbyte_agent_zendesk_support/_vendored/connector_sdk/schema/security.py,sha256=Xo6Z0-NCryMY4EDZgvg8ABSPglskpXANvm_iI34meV8,8588
 airbyte_agent_zendesk_support/_vendored/connector_sdk/telemetry/__init__.py,sha256=RaLgkBU4dfxn1LC5Y0Q9rr2PJbrwjxvPgBLmq8_WafE,211
 airbyte_agent_zendesk_support/_vendored/connector_sdk/telemetry/config.py,sha256=tLmQwAFD0kP1WyBGWBS3ysaudN9H3e-3EopKZi6cGKg,885
 airbyte_agent_zendesk_support/_vendored/connector_sdk/telemetry/events.py,sha256=NvqjlUbkm6cbGh4ffKxYxtjdwwgzfPF4MKJ2GfgWeFg,1285
 airbyte_agent_zendesk_support/_vendored/connector_sdk/telemetry/tracker.py,sha256=KacNdbHatvPPhnNrycp5YUuD5xpkp56AFcHd-zguBgk,5247
-airbyte_agent_zendesk_support-0.18.21.dist-info/METADATA,sha256=h_eKn-nbGYB3MCSchx0bZNgcJcpCCSKAImsE8EQwnSA,5629
-airbyte_agent_zendesk_support-0.18.21.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-airbyte_agent_zendesk_support-0.18.21.dist-info/RECORD,,
+airbyte_agent_zendesk_support-0.18.32.dist-info/METADATA,sha256=cfq9fi6SsUk98-QqBlnLPfX6Bvtw9wcRpG5AteNq2Nw,6267
+airbyte_agent_zendesk_support-0.18.32.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+airbyte_agent_zendesk_support-0.18.32.dist-info/RECORD,,