airbyte-agent-zendesk-support 0.18.57__py3-none-any.whl → 0.18.61__py3-none-any.whl

airbyte_agent_zendesk_support/connector.py

@@ -4,8 +4,11 @@ Zendesk-Support connector.
 
 from __future__ import annotations
 
+import inspect
+import json
 import logging
-from typing import TYPE_CHECKING, Any, Callable, TypeVar, AsyncIterator, overload
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, Mapping, TypeVar, AsyncIterator, overload
 try:
     from typing import Literal
 except ImportError:
@@ -162,6 +165,38 @@ from .models import (
 # TypeVar for decorator type preservation
 _F = TypeVar("_F", bound=Callable[..., Any])
 
+DEFAULT_MAX_OUTPUT_CHARS = 50_000  # ~50KB default, configurable per-tool
+
+
+def _raise_output_too_large(message: str) -> None:
+    try:
+        from pydantic_ai import ModelRetry  # type: ignore[import-not-found]
+    except Exception as exc:
+        raise RuntimeError(message) from exc
+    raise ModelRetry(message)
+
+
+def _check_output_size(result: Any, max_chars: int | None, tool_name: str) -> Any:
+    if max_chars is None or max_chars <= 0:
+        return result
+
+    try:
+        serialized = json.dumps(result, default=str)
+    except (TypeError, ValueError):
+        return result
+
+    if len(serialized) > max_chars:
+        truncated_preview = serialized[:500] + "..." if len(serialized) > 500 else serialized
+        _raise_output_too_large(
+            f"Tool '{tool_name}' output too large ({len(serialized):,} chars, limit {max_chars:,}). "
+            "Please narrow your query by: using the 'fields' parameter to select only needed fields, "
+            "adding filters, or reducing the 'limit'. "
+            f"Preview: {truncated_preview}"
+        )
+
+    return result
+
+
 
 
 class ZendeskSupportConnector:
@@ -172,7 +207,7 @@ class ZendeskSupportConnector:
     """
 
     connector_name = "zendesk-support"
-    connector_version = "0.1.7"
+    connector_version = "0.1.8"
     vendored_sdk_version = "0.1.0"  # Version of vendored connector-sdk
 
     # Map of (entity, action) -> needs_envelope for envelope wrapping decision
@@ -704,15 +739,15 @@ class ZendeskSupportConnector:
     async def execute(
         self,
         entity: str,
-        action: str,
-        params: dict[str, Any]
+        action: Literal["list", "get", "download", "search"],
+        params: Mapping[str, Any]
     ) -> ZendeskSupportExecuteResult[Any] | ZendeskSupportExecuteResultWithMeta[Any, Any] | Any: ...
 
     async def execute(
         self,
         entity: str,
-        action: str,
-        params: dict[str, Any] | None = None
+        action: Literal["list", "get", "download", "search"],
+        params: Mapping[str, Any] | None = None
     ) -> Any:
         """
         Execute an entity operation with full type safety.
@@ -740,16 +775,17 @@ class ZendeskSupportConnector:
         from ._vendored.connector_sdk.executor import ExecutionConfig
 
         # Remap parameter names from snake_case (TypedDict keys) to API parameter names
-        if params:
+        resolved_params = dict(params) if params is not None else None
+        if resolved_params:
             param_map = self._PARAM_MAP.get((entity, action), {})
             if param_map:
-                params = {param_map.get(k, k): v for k, v in params.items()}
+                resolved_params = {param_map.get(k, k): v for k, v in resolved_params.items()}
 
         # Use ExecutionConfig for both local and hosted executors
         config = ExecutionConfig(
             entity=entity,
             action=action,
-            params=params
+            params=resolved_params
         )
 
         result = await self._executor.execute(config)
@@ -776,41 +812,67 @@ class ZendeskSupportConnector:
     # ===== INTROSPECTION METHODS =====
 
     @classmethod
-    def describe(cls, func: _F) -> _F:
+    def tool_utils(
+        cls,
+        func: _F | None = None,
+        *,
+        update_docstring: bool = True,
+        max_output_chars: int | None = DEFAULT_MAX_OUTPUT_CHARS,
+    ) -> _F | Callable[[_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.
+        Decorator that adds tool utilities like docstring augmentation and output limits.
 
         Usage:
             @mcp.tool()
-            @ZendeskSupportConnector.describe
+            @ZendeskSupportConnector.tool_utils
             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)
+            @mcp.tool()
+            @ZendeskSupportConnector.tool_utils(update_docstring=False, max_output_chars=None)
+            async def execute(entity: str, action: str, params: dict):
+                ...
 
         Args:
-            func: The function to decorate
+            update_docstring: When True, append connector capabilities to __doc__.
+            max_output_chars: Max serialized output size before raising. Use None to disable.
+        """
+
+        def decorate(inner: _F) -> _F:
+            if update_docstring:
+                description = generate_tool_description(ZendeskSupportConnectorModel)
+                original_doc = inner.__doc__ or ""
+                if original_doc.strip():
+                    full_doc = f"{original_doc.strip()}\n{description}"
+                else:
+                    full_doc = description
+            else:
+                full_doc = ""
 
-        Returns:
-            The same function with updated __doc__
-        """
-        description = generate_tool_description(ZendeskSupportConnectorModel)
+            if inspect.iscoroutinefunction(inner):
 
-        original_doc = func.__doc__ or ""
-        if original_doc.strip():
-            func.__doc__ = f"{original_doc.strip()}\n{description}"
-        else:
-            func.__doc__ = description
+                @wraps(inner)
+                async def aw(*args: Any, **kwargs: Any) -> Any:
+                    result = await inner(*args, **kwargs)
+                    return _check_output_size(result, max_output_chars, inner.__name__)
+
+                wrapped = aw
+            else:
+
+                @wraps(inner)
+                def sw(*args: Any, **kwargs: Any) -> Any:
+                    result = inner(*args, **kwargs)
+                    return _check_output_size(result, max_output_chars, inner.__name__)
+
+                wrapped = sw
+
+            if update_docstring:
+                wrapped.__doc__ = full_doc
+            return wrapped  # type: ignore[return-value]
 
-        return func
+        if func is not None:
+            return decorate(func)
+        return decorate
 
     def list_entities(self) -> list[dict[str, Any]]:
         """
@@ -948,7 +1010,7 @@ class TicketsQuery:
         - created_at: Timestamp indicating when the ticket was created
         - custom_fields: Array of custom field values specific to the account's ticket configuration
         - custom_status_id: Unique identifier of the custom status applied to the ticket
-        - deleted_ticket_form_id: Unique identifier of the ticket form if it was deleted after the ticket was created
+        - deleted_ticket_form_id: The ID of the ticket form that was previously associated with this ticket but has since been deleted
         - description: Initial description or content of the ticket when it was created
         - due_at: Timestamp indicating when the ticket is due for completion or resolution
         - email_cc_ids: Array of user identifiers who are CC'd on ticket email notifications
@@ -958,7 +1020,7 @@ class TicketsQuery:
         - followup_ids: Array of identifiers for follow-up tickets related to this ticket
         - forum_topic_id: Unique identifier linking the ticket to a forum topic if applicable
         - from_messaging_channel: Boolean indicating whether the ticket originated from a messaging channel
-        - generated_timestamp: Timestamp updated for all ticket updates including system changes, used for incremental export co...
+        - generated_timestamp: Timestamp updated for all ticket updates including system changes, used for incremental export
         - group_id: Unique identifier of the agent group assigned to handle the ticket
         - has_incidents: Boolean indicating whether this problem ticket has related incident tickets
         - id: Unique identifier for the ticket
@@ -1982,9 +2044,9 @@ class TicketFieldsQuery:
         Available filter fields (TicketFieldsSearchFilter):
         - active: Whether this field is currently available for use
         - agent_description: A description of the ticket field that only agents can see
-        - collapsed_for_agents: If true, the field is shown to agents by default; if false, it is hidden alongside infrequently u...
+        - collapsed_for_agents: If true, the field is shown to agents by default; if false, it is hidden alongside infrequently used fields
         - created_at: Timestamp when the custom ticket field was created
-        - custom_field_options: Array of option objects for custom ticket fields of type multiselect or tagger, containing name a...
+        - custom_field_options: Array of option objects for custom ticket fields of type multiselect or tagger
         - custom_statuses: List of customized ticket statuses, only present for system ticket fields of type custom_status
         - description: Text describing the purpose of the ticket field to users
         - editable_in_portal: Whether this field is editable by end users in Help Center
@@ -2003,7 +2065,7 @@ class TicketFieldsQuery:
         - tag: For checkbox fields only, a tag added to tickets when the checkbox field is selected
         - title: The title of the ticket field displayed to agents
         - title_in_portal: The title of the ticket field displayed to end users in Help Center
-        - type: Field type such as text, textarea, checkbox, date, integer, decimal, regexp, multiselect, tagger,...
+        - type: Field type such as text, textarea, checkbox, date, integer, decimal, regexp, multiselect, or tagger
         - updated_at: Timestamp when the custom ticket field was last updated
         - url: The API URL for this ticket field resource
         - visible_in_portal: Whether this field is visible to end users in Help Center
@@ -2666,7 +2728,7 @@ class SatisfactionRatingsQuery:
         - group_id: The identifier of the group assigned to the ticket at the time the rating was submitted
         - id: Unique identifier for the satisfaction rating, automatically assigned upon creation
         - reason: Free-text reason for a bad rating provided by the requester in a follow-up question
-        - reason_id: Identifier for the predefined reason given for a negative rating, only applicable when score is '...
+        - reason_id: Identifier for the predefined reason given for a negative rating
         - requester_id: The identifier of the ticket requester who submitted the satisfaction rating
         - score: The satisfaction rating value: 'offered', 'unoffered', 'good', or 'bad'
         - ticket_id: The identifier of the ticket being rated
@@ -2947,7 +3009,7 @@ class TicketFormsQuery:
         - raw_display_name: The dynamic content placeholder if present, or the display_name value if not
         - raw_name: The dynamic content placeholder if present, or the name value if not
         - restricted_brand_ids: IDs of all brands that this ticket form is restricted to
-        - ticket_field_ids: IDs of all ticket fields included in this ticket form, ordered to determine field display sequenc...
+        - ticket_field_ids: IDs of all ticket fields included in this ticket form
         - updated_at: Timestamp of the last update to the ticket form
         - url: URL of the ticket form
 

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.7',
+    version='0.1.8',
     base_url='https://{subdomain}.zendesk.com/api/v2',
     auth=AuthConfig(
         options=[
@@ -3945,4 +3945,290 @@ ZendeskSupportConnectorModel: ConnectorModel = ConnectorModel(
             },
         ),
     ],
+    search_field_paths={
+        'brands': [
+            'active',
+            'brand_url',
+            'created_at',
+            'default',
+            'has_help_center',
+            'help_center_state',
+            'host_mapping',
+            'id',
+            'is_deleted',
+            'logo',
+            'name',
+            'signature_template',
+            'subdomain',
+            'ticket_form_ids',
+            'ticket_form_ids[]',
+            'updated_at',
+            'url',
+        ],
+        'groups': [
+            'created_at',
+            'default',
+            'deleted',
+            'description',
+            'id',
+            'is_public',
+            'name',
+            'updated_at',
+            'url',
+        ],
+        'organizations': [
+            'created_at',
+            'deleted_at',
+            'details',
+            'domain_names',
+            'domain_names[]',
+            'external_id',
+            'group_id',
+            'id',
+            'name',
+            'notes',
+            'organization_fields',
+            'shared_comments',
+            'shared_tickets',
+            'tags',
+            'tags[]',
+            'updated_at',
+            'url',
+        ],
+        'satisfaction_ratings': [
+            'assignee_id',
+            'comment',
+            'created_at',
+            'group_id',
+            'id',
+            'reason',
+            'reason_id',
+            'requester_id',
+            'score',
+            'ticket_id',
+            'updated_at',
+            'url',
+        ],
+        'tags': ['count', 'name'],
+        'ticket_audits': [
+            'attachments',
+            'attachments[]',
+            'author_id',
+            'created_at',
+            'events',
+            'events[]',
+            'id',
+            'metadata',
+            'ticket_id',
+            'via',
+        ],
+        'ticket_comments': [
+            'attachments',
+            'attachments[]',
+            'audit_id',
+            'author_id',
+            'body',
+            'created_at',
+            'event_type',
+            'html_body',
+            'id',
+            'metadata',
+            'plain_body',
+            'public',
+            'ticket_id',
+            'timestamp',
+            'type',
+            'uploads',
+            'uploads[]',
+            'via',
+            'via_reference_id',
+        ],
+        'ticket_fields': [
+            'active',
+            'agent_description',
+            'collapsed_for_agents',
+            'created_at',
+            'custom_field_options',
+            'custom_field_options[]',
+            'custom_statuses',
+            'custom_statuses[]',
+            'description',
+            'editable_in_portal',
+            'id',
+            'key',
+            'position',
+            'raw_description',
+            'raw_title',
+            'raw_title_in_portal',
+            'regexp_for_validation',
+            'removable',
+            'required',
+            'required_in_portal',
+            'sub_type_id',
+            'system_field_options',
+            'system_field_options[]',
+            'tag',
+            'title',
+            'title_in_portal',
+            'type',
+            'updated_at',
+            'url',
+            'visible_in_portal',
+        ],
+        'ticket_forms': [
+            'active',
+            'agent_conditions',
+            'agent_conditions[]',
+            'created_at',
+            'default',
+            'display_name',
+            'end_user_conditions',
+            'end_user_conditions[]',
+            'end_user_visible',
+            'id',
+            'in_all_brands',
+            'name',
+            'position',
+            'raw_display_name',
+            'raw_name',
+            'restricted_brand_ids',
+            'restricted_brand_ids[]',
+            'ticket_field_ids',
+            'ticket_field_ids[]',
+            'updated_at',
+            'url',
+        ],
+        'ticket_metric_events': [
+            'id',
+            'instance_id',
+            'metric',
+            'ticket_id',
+            'time',
+            'type',
+        ],
+        'ticket_metrics': [
+            'agent_wait_time_in_minutes',
+            'assigned_at',
+            'assignee_stations',
+            'assignee_updated_at',
+            'created_at',
+            'custom_status_updated_at',
+            'first_resolution_time_in_minutes',
+            'full_resolution_time_in_minutes',
+            'generated_timestamp',
+            'group_stations',
+            'id',
+            'initially_assigned_at',
+            'instance_id',
+            'latest_comment_added_at',
+            'metric',
+            'on_hold_time_in_minutes',
+            'reopens',
+            'replies',
+            'reply_time_in_minutes',
+            'reply_time_in_seconds',
+            'requester_updated_at',
+            'requester_wait_time_in_minutes',
+            'solved_at',
+            'status',
+            'status_updated_at',
+            'ticket_id',
+            'time',
+            'type',
+            'updated_at',
+            'url',
+        ],
+        'tickets': [
+            'allow_attachments',
+            'allow_channelback',
+            'assignee_id',
+            'brand_id',
+            'collaborator_ids',
+            'collaborator_ids[]',
+            'created_at',
+            'custom_fields',
+            'custom_fields[]',
+            'custom_status_id',
+            'deleted_ticket_form_id',
+            'description',
+            'due_at',
+            'email_cc_ids',
+            'email_cc_ids[]',
+            'external_id',
+            'fields',
+            'fields[]',
+            'follower_ids',
+            'follower_ids[]',
+            'followup_ids',
+            'followup_ids[]',
+            'forum_topic_id',
+            'from_messaging_channel',
+            'generated_timestamp',
+            'group_id',
+            'has_incidents',
+            'id',
+            'is_public',
+            'organization_id',
+            'priority',
+            'problem_id',
+            'raw_subject',
+            'recipient',
+            'requester_id',
+            'satisfaction_rating',
+            'sharing_agreement_ids',
+            'sharing_agreement_ids[]',
+            'status',
+            'subject',
+            'submitter_id',
+            'tags',
+            'tags[]',
+            'ticket_form_id',
+            'type',
+            'updated_at',
+            'url',
+            'via',
+        ],
+        'users': [
+            'active',
+            'alias',
+            'chat_only',
+            'created_at',
+            'custom_role_id',
+            'default_group_id',
+            'details',
+            'email',
+            'external_id',
+            'iana_time_zone',
+            'id',
+            'last_login_at',
+            'locale',
+            'locale_id',
+            'moderator',
+            'name',
+            'notes',
+            'only_private_comments',
+            'organization_id',
+            'permanently_deleted',
+            'phone',
+            'photo',
+            'report_csv',
+            'restricted_agent',
+            'role',
+            'role_type',
+            'shared',
+            'shared_agent',
+            'shared_phone_number',
+            'signature',
+            'suspended',
+            'tags',
+            'tags[]',
+            'ticket_restriction',
+            'time_zone',
+            'two_factor_auth_enabled',
+            'updated_at',
+            'url',
+            'user_fields',
+            'verified',
+        ],
+    },
 )

airbyte_agent_zendesk_support/models.py

@@ -789,7 +789,7 @@ class SatisfactionRatingsSearchData(BaseModel):
     reason: str | None = None
     """Free-text reason for a bad rating provided by the requester in a follow-up question"""
     reason_id: int | None = None
-    """Identifier for the predefined reason given for a negative rating, only applicable when score is '..."""
+    """Identifier for the predefined reason given for a negative rating"""
     requester_id: int | None = None
     """The identifier of the ticket requester who submitted the satisfaction rating"""
     score: str | None = None
@@ -883,11 +883,11 @@ class TicketFieldsSearchData(BaseModel):
     agent_description: str | None = None
     """A description of the ticket field that only agents can see"""
     collapsed_for_agents: bool | None = None
-    """If true, the field is shown to agents by default; if false, it is hidden alongside infrequently u..."""
+    """If true, the field is shown to agents by default; if false, it is hidden alongside infrequently used fields"""
     created_at: str | None = None
     """Timestamp when the custom ticket field was created"""
     custom_field_options: list[Any] | None = None
-    """Array of option objects for custom ticket fields of type multiselect or tagger, containing name a..."""
+    """Array of option objects for custom ticket fields of type multiselect or tagger"""
     custom_statuses: list[Any] | None = None
     """List of customized ticket statuses, only present for system ticket fields of type custom_status"""
     description: str | None = None
@@ -925,7 +925,7 @@ class TicketFieldsSearchData(BaseModel):
     title_in_portal: str | None = None
     """The title of the ticket field displayed to end users in Help Center"""
     type: str | None = None
-    """Field type such as text, textarea, checkbox, date, integer, decimal, regexp, multiselect, tagger,..."""
+    """Field type such as text, textarea, checkbox, date, integer, decimal, regexp, multiselect, or tagger"""
     updated_at: str | None = None
     """Timestamp when the custom ticket field was last updated"""
     url: str | None = None
@@ -967,7 +967,7 @@ class TicketFormsSearchData(BaseModel):
     restricted_brand_ids: list[Any] | None = None
     """IDs of all brands that this ticket form is restricted to"""
     ticket_field_ids: list[Any] | None = None
-    """IDs of all ticket fields included in this ticket form, ordered to determine field display sequenc..."""
+    """IDs of all ticket fields included in this ticket form"""
     updated_at: str | None = None
     """Timestamp of the last update to the ticket form"""
     url: str | None = None
@@ -1061,7 +1061,7 @@ class TicketsSearchData(BaseModel):
     custom_status_id: int | None = None
     """Unique identifier of the custom status applied to the ticket"""
     deleted_ticket_form_id: int | None = None
-    """Unique identifier of the ticket form if it was deleted after the ticket was created"""
+    """The ID of the ticket form that was previously associated with this ticket but has since been deleted"""
     description: str | None = None
     """Initial description or content of the ticket when it was created"""
     due_at: str | None = None
@@ -1081,7 +1081,7 @@ class TicketsSearchData(BaseModel):
     from_messaging_channel: bool | None = None
     """Boolean indicating whether the ticket originated from a messaging channel"""
     generated_timestamp: int | None = None
-    """Timestamp updated for all ticket updates including system changes, used for incremental export co..."""
+    """Timestamp updated for all ticket updates including system changes, used for incremental export"""
     group_id: int | None = None
     """Unique identifier of the agent group assigned to handle the ticket"""
     has_incidents: bool | None = None