airbyte-agent-zendesk-support 0.18.28__py3-none-any.whl → 0.18.29__py3-none-any.whl

airbyte_agent_zendesk_support/_vendored/connector_sdk/__init__.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 from .auth_strategies import AuthStrategy
 from .connector_model_loader import load_connector_model
 from .constants import SDK_VERSION
+from .decorators import airbyte_description
 from .exceptions import (
     AuthenticationError,
     HTTPClientError,
@@ -79,4 +80,6 @@ __all__ = [
     "instrument",
     # Utilities
     "save_download",
+    # Decorators for AI integration
+    "airbyte_description",
 ]

airbyte_agent_zendesk_support/_vendored/connector_sdk/decorators.py

@@ -0,0 +1,128 @@
+"""
+Decorators for AI agent tool integration.
+
+Provides utilities to auto-generate comprehensive tool descriptions
+from connector metadata, enabling easy integration with AI frameworks.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any, Callable, TypeVar
+
+from .introspection import (
+    MAX_EXAMPLE_QUESTIONS,
+    ConnectorModelProtocol,
+    EndpointProtocol,
+    generate_tool_description,
+)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+__all__ = [
+    "airbyte_description",
+    "EndpointProtocol",
+    "ConnectorModelProtocol",
+    "MAX_EXAMPLE_QUESTIONS",
+    # Private function exposed for testing
+    "_load_connector_model",
+]
+
+
+def airbyte_description(connector_name: str) -> Callable[[F], F]:
+    """
+    Decorator that generates comprehensive tool descriptions from connector metadata.
+
+    Automatically populates the function's docstring with:
+    - Connector description
+    - Available entities and their actions
+    - Example questions the connector can answer
+
+    Args:
+        connector_name: Name of the connector (e.g., "hubspot", "stripe")
+                       Must match the generated package name pattern:
+                       airbyte_agent_{connector_name}
+
+    Returns:
+        Decorator that updates the function's __doc__ attribute
+
+    Example:
+        from airbyte_agent_hubspot import HubspotConnector
+
+        connector = HubspotConnector(
+            external_user_id=external_user_id,
+            airbyte_client_id=airbyte_client_id,
+            airbyte_client_secret=airbyte_client_secret
+        )
+
+        # IMPORTANT: @airbyte_description must be the INNER decorator (closest to function)
+        # This ensures __doc__ is expanded BEFORE frameworks like FastMCP capture it
+        @agent.tool_plain  # or @mcp.tool() for FastMCP
+        @airbyte_description("hubspot")
+        async def hubspot_exec(entity: str, action: str, params: dict | None = None):
+            '''Execute HubSpot operations.'''
+            return await connector.execute(entity, action, params or {})
+
+    The decorator will update hubspot_exec.__doc__ with a comprehensive
+    description including all available entities, actions, and example questions.
+    """
+
+    def decorator(func: F) -> F:
+        # Load connector model from generated package
+        model = _load_connector_model(connector_name)
+
+        # Generate description using shared introspection module
+        description = generate_tool_description(model)
+
+        # Preserve original docstring if present, append to it
+        original_doc = func.__doc__ or ""
+        if original_doc.strip():
+            func.__doc__ = f"{original_doc.strip()}\n\n{description}"
+        else:
+            func.__doc__ = description
+
+        return func
+
+    return decorator
+
+
+def _load_connector_model(connector_name: str) -> Any:
+    """
+    Load connector model from generated package.
+
+    Args:
+        connector_name: Connector name (e.g., "hubspot")
+
+    Returns:
+        ConnectorModel instance from the generated package
+
+    Raises:
+        ImportError: If connector package is not installed
+        AttributeError: If connector model constant not found
+    """
+    # Normalize connector name to package name
+    package_name = f"airbyte_agent_{connector_name.replace('-', '_')}"
+
+    try:
+        # Import the connector_model module from the generated package
+        module = importlib.import_module(f"{package_name}.connector_model")
+    except ImportError as e:
+        raise ImportError(f"Could not import connector package '{package_name}'. " f"Ensure the package is installed. Error: {e}") from e
+
+    # Find the ConnectorModel constant (named like HubspotConnectorModel)
+    # Convention: {PascalCase connector name}ConnectorModel
+    pascal_name = "".join(word.capitalize() for word in connector_name.replace("-", "_").split("_"))
+    model_name = f"{pascal_name}ConnectorModel"
+
+    model = getattr(module, model_name, None)
+    if model is None:
+        # Fallback: look for any ConnectorModel attribute
+        for attr_name in dir(module):
+            if attr_name.endswith("ConnectorModel"):
+                model = getattr(module, attr_name)
+                break
+
+    if model is None:
+        raise AttributeError(f"Could not find ConnectorModel in {package_name}.connector_model. " f"Expected constant named '{model_name}'")
+
+    return model

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 @airbyte_description 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/connector.py

@@ -4,6 +4,7 @@ zendesk-support connector.
 
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING, Any, AsyncIterator, overload
 try:
     from typing import Literal
@@ -11,6 +12,7 @@ except ImportError:
     from typing_extensions import Literal
 
 from .connector_model import ZendeskSupportConnectorModel
+from ._vendored.connector_sdk.introspection import describe_entities
 
 from .types import (
     ArticleAttachmentsDownloadParams,
@@ -712,6 +714,51 @@ class ZendeskSupportConnector:
             # No extractors - return raw response data
             return result.data
 
+    # ===== INTROSPECTION METHODS =====
+
+    def describe(self) -> list[dict[str, Any]]:
+        """
+        Describe 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.describe()
+            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-0.18.28.dist-info → airbyte_agent_zendesk_support-0.18.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airbyte-agent-zendesk-support
-Version: 0.18.28
+Version: 0.18.29
 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
@@ -141,6 +141,6 @@ For the service's official API docs, see the [Zendesk-Support API reference](htt
 
 ## Version information
 
-- **Package version:** 0.18.28
+- **Package version:** 0.18.29
 - **Connector version:** 0.1.4
-- **Generated with Connector SDK commit SHA:** 0580c7278394ff52ee3bec5d5192905ac3b15878
+- **Generated with Connector SDK commit SHA:** d023e05f2b7a1ddabf81fab7640c64de1e0aa6a1

{airbyte_agent_zendesk_support-0.18.28.dist-info → airbyte_agent_zendesk_support-0.18.29.dist-info}/RECORD

@@ -1,17 +1,19 @@
 airbyte_agent_zendesk_support/__init__.py,sha256=MPz4HU055DRA3-1qgbGXh2E0YHmhcexQCFl-Tz21gm4,6227
-airbyte_agent_zendesk_support/connector.py,sha256=GMwMxScJ9EW9KxPvs5W3BJXsvbv618v13pTREUGLKH0,63878
+airbyte_agent_zendesk_support/connector.py,sha256=-myr_jxv7k37t-j3Gk0FaTL9ZuLOG1uxr0fcavTNuww,65663
 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/__init__.py,sha256=wcf0bwjYCV6fZtMtkugUjsuUbMUl_8LjM7ojgh32eNI,2056
 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/constants.py,sha256=uH4rjBX6WsBP8M0jt7AUJI9w5Adn4wvJwib7Gdfkr1M,2736
+airbyte_agent_zendesk_support/_vendored/connector_sdk/decorators.py,sha256=849qEYLCbEI7bPbpnKaB_hYyb5SrFoWe4XMwg_vzc7Q,4376
 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/http_client.py,sha256=NdccrrBHI5rW56XnXcP54arCwywIVKnMeSQPas6KlOM,27466
+airbyte_agent_zendesk_support/_vendored/connector_sdk/introspection.py,sha256=_fdhYJIX-BsH3c55wDD7Nos2Fa6CEVmGHr-i5hEAInU,10320
 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/utils.py,sha256=G4LUXOC2HzPoND2v4tQW68R9uuPX9NQyCjaGxb7Kpl0,1958
@@ -50,6 +52,6 @@ airbyte_agent_zendesk_support/_vendored/connector_sdk/telemetry/__init__.py,sha2
 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.28.dist-info/METADATA,sha256=OmUL-2Sj134KaJgTKDH-chSYfqZhlj7jCn8m1ai0SeI,6267
-airbyte_agent_zendesk_support-0.18.28.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-airbyte_agent_zendesk_support-0.18.28.dist-info/RECORD,,
+airbyte_agent_zendesk_support-0.18.29.dist-info/METADATA,sha256=_xUrBuX_Yo44RTyD4LjQ4x_QhRbf-cjlLjg7zRM2L-c,6267
+airbyte_agent_zendesk_support-0.18.29.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+airbyte_agent_zendesk_support-0.18.29.dist-info/RECORD,,