airbyte-agent-hubspot 0.15.28__py3-none-any.whl → 0.15.43__py3-none-any.whl

airbyte_agent_hubspot/_vendored/connector_sdk/executor/local_executor.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import inspect
 import logging
 import os
 import re
@@ -11,6 +12,7 @@ from collections.abc import AsyncIterator
 from typing import Any, Protocol
 from urllib.parse import quote
 
+from jinja2 import Environment, StrictUndefined
 from jsonpath_ng import parse as parse_jsonpath
 from opentelemetry import trace
 
@@ -506,8 +508,6 @@ class LocalExecutor:
             result = handler.execute_operation(config.entity, action, params)
 
             # Check if it's an async generator (download) or awaitable (standard)
-            import inspect
-
             if inspect.isasyncgen(result):
                 # Download operation: return generator directly
                 return ExecutionResult(
@@ -814,7 +814,6 @@ class LocalExecutor:
             >>> _substitute_file_field_params("attachments[{attachment_index}].url", {"attachment_index": 0})
             "attachments[0].url"
         """
-        from jinja2 import Environment, StrictUndefined
 
         # Use custom delimiters to match OpenAPI path parameter syntax {var}
         # StrictUndefined raises clear error if a template variable is missing
@@ -844,10 +843,58 @@ class LocalExecutor:
             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
@@ -864,7 +911,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 {}
 
@@ -1049,37 +1098,95 @@ class LocalExecutor:
 
         return interpolate_value(variables)
 
+    def _wrap_primitives(self, data: Any) -> dict[str, Any] | list[dict[str, Any]] | None:
+        """Wrap primitive values in dict format for consistent response structure.
+
+        Transforms primitive API responses into dict format so downstream code
+        can always expect dict-based data structures.
+
+        Args:
+            data: Response data (could be primitive, list, dict, or None)
+
+        Returns:
+            - If data is a primitive (str, int, float, bool): {"value": data}
+            - If data is a list: wraps all non-dict elements as {"value": item}
+            - If data is already a dict or list of dicts: unchanged
+            - If data is None: None
+
+        Examples:
+            >>> executor._wrap_primitives(42)
+            {"value": 42}
+            >>> executor._wrap_primitives([1, 2, 3])
+            [{"value": 1}, {"value": 2}, {"value": 3}]
+            >>> executor._wrap_primitives([1, {"id": 2}, 3])
+            [{"value": 1}, {"id": 2}, {"value": 3}]
+            >>> executor._wrap_primitives([[1, 2], 3])
+            [{"value": [1, 2]}, {"value": 3}]
+            >>> executor._wrap_primitives({"id": 1})
+            {"id": 1}  # unchanged
+        """
+        if data is None:
+            return None
+
+        # Handle primitive scalars
+        if isinstance(data, (bool, str, int, float)):
+            return {"value": data}
+
+        # Handle lists - wrap non-dict elements
+        if isinstance(data, list):
+            if not data:
+                return []  # Empty list unchanged
+
+            wrapped = []
+            for item in data:
+                if isinstance(item, dict):
+                    wrapped.append(item)
+                else:
+                    wrapped.append({"value": item})
+            return wrapped
+
+        # Dict - return unchanged
+        if isinstance(data, dict):
+            return data
+
+        # Unknown type - wrap for safety
+        return {"value": data}
+
     def _extract_records(
         self,
-        response_data: dict[str, Any],
+        response_data: Any,
         endpoint: EndpointDefinition,
-    ) -> dict[str, Any] | list[Any] | None:
+    ) -> dict[str, Any] | list[dict[str, Any]] | None:
         """Extract records from response using record extractor.
 
         Type inference based on action:
         - list, search: Returns array ([] if not found)
         - get, create, update, delete: Returns single record (None if not found)
 
+        Automatically wraps primitive values (int, str, float, bool) in {"value": primitive}
+        format to ensure consistent dict-based responses for downstream code.
+
         Args:
-            response_data: Full API response
+            response_data: Full API response (can be dict, list, primitive, or None)
             endpoint: Endpoint with optional record extractor and action
 
         Returns:
             - Extracted data if extractor configured and path found
             - [] or None if path not found (based on action)
             - Original response if no extractor configured or on error
+            - Primitives are wrapped as {"value": primitive}
         """
         # Check if endpoint has record extractor
         extractor = endpoint.record_extractor
         if not extractor:
-            return response_data
+            return self._wrap_primitives(response_data)
 
         # Determine if this action returns array or single record
         action = endpoint.action
         if not action:
-            return response_data
+            return self._wrap_primitives(response_data)
 
-        is_array_action = action in (Action.LIST, Action.SEARCH)
+        is_array_action = action in (Action.LIST, Action.API_SEARCH)
 
         try:
             # Parse and apply JSONPath expression
@@ -1090,17 +1197,19 @@ class LocalExecutor:
                 # Path not found - return empty based on action
                 return [] if is_array_action else None
 
-            # Return extracted data
+            # Return extracted data with primitive wrapping
             if is_array_action:
                 # For array actions, return the array (or list of matches)
-                return matches[0] if len(matches) == 1 else matches
+                result = matches[0] if len(matches) == 1 else matches
             else:
                 # For single record actions, return first match
-                return matches[0]
+                result = matches[0]
+
+            return self._wrap_primitives(result)
 
         except Exception as e:
             logging.warning(f"Failed to apply record extractor '{extractor}': {e}. Returning original response.")
-            return response_data
+            return self._wrap_primitives(response_data)
 
     def _extract_metadata(
         self,
@@ -1185,7 +1294,7 @@ class LocalExecutor:
 
         if missing_fields:
             raise MissingParameterError(
-                f"Missing required body fields for {entity}.{action.value}: {missing_fields}. " f"Provided parameters: {list(params.keys())}"
+                f"Missing required body fields for {entity}.{action.value}: {missing_fields}. Provided parameters: {list(params.keys())}"
             )
 
     async def close(self):
@@ -1209,7 +1318,7 @@ class LocalExecutor:
 
 
 class _StandardOperationHandler:
-    """Handler for standard REST operations (GET, LIST, CREATE, UPDATE, DELETE, SEARCH, AUTHORIZE)."""
+    """Handler for standard REST operations (GET, LIST, CREATE, UPDATE, DELETE, API_SEARCH, AUTHORIZE)."""
 
     def __init__(self, context: _OperationContext):
         self.ctx = context
@@ -1222,7 +1331,7 @@ class _StandardOperationHandler:
             Action.CREATE,
             Action.UPDATE,
             Action.DELETE,
-            Action.SEARCH,
+            Action.API_SEARCH,
             Action.AUTHORIZE,
         }
 

airbyte_agent_hubspot/_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
@@ -495,8 +527,8 @@ class ActionType(str, Enum):
     DELETE = "delete"
     """Delete a record"""
 
-    SEARCH = "search"
-    """Search for records matching specific query criteria"""
+    API_SEARCH = "api_search"
+    """Search for records matching specific query criteria via API"""
 
     DOWNLOAD = "download"
     """Download file content from a URL specified in the metadata response"""
@@ -514,7 +546,7 @@ class BodyType(str, Enum):
 
 
 # Type alias for use in Pydantic models
-ActionTypeLiteral = Literal["get", "list", "create", "update", "delete", "search", "download"]
+ActionTypeLiteral = Literal["get", "list", "create", "update", "delete", "api_search", "download"]
 
 
 # =============================================================================
@@ -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",
@@ -627,8 +666,7 @@ EXTENSION_REGISTRY = {
         "type": "dict[str, str]",
         "required": False,
         "description": (
-            "Dictionary mapping field names to JSONPath expressions for extracting metadata "
-            "(pagination, request IDs, etc.) from response envelopes"
+            "Dictionary mapping field names to JSONPath expressions for extracting metadata (pagination, request IDs, etc.) from response envelopes"
         ),
     },
     AIRBYTE_FILE_URL: {

airbyte_agent_hubspot/_vendored/connector_sdk/http/response.py

@@ -80,6 +80,8 @@ class HTTPResponse:
             HTTPStatusError: For 4xx or 5xx status codes.
         """
         if 400 <= self._status_code < 600:
+            # NOTE: Import here intentionally to avoid circular import.
+            # exceptions.py imports HTTPResponse for type hints.
             from .exceptions import HTTPStatusError
 
             raise HTTPStatusError(

airbyte_agent_hubspot/_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/api_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_hubspot/_vendored/connector_sdk/logging/logger.py

@@ -5,7 +5,7 @@ import json
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Dict, Optional, Set
+from typing import Any, Dict, Set
 
 from .types import LogSession, RequestLog
 
@@ -31,9 +31,9 @@ class RequestLogger:
 
     def __init__(
         self,
-        log_file: Optional[str] = None,
-        connector_name: Optional[str] = None,
-        max_logs: Optional[int] = 10000,
+        log_file: str | None = None,
+        connector_name: str | None = None,
+        max_logs: int | None = 10000,
     ):
         """
         Initialize the request logger.
@@ -99,9 +99,9 @@ class RequestLogger:
         method: str,
         url: str,
         path: str,
-        headers: Optional[Dict[str, str]] = None,
-        params: Optional[Dict[str, Any]] = None,
-        body: Optional[Any] = None,
+        headers: Dict[str, str] | None = None,
+        params: Dict[str, Any] | None = None,
+        body: Any | None = None,
     ) -> str:
         """
         Log the start of an HTTP request.
@@ -133,7 +133,7 @@ class RequestLogger:
         self,
         request_id: str,
         status_code: int,
-        response_body: Optional[Any] = None,
+        response_body: Any | None = None,
     ) -> None:
         """
         Log a successful HTTP response.
@@ -176,7 +176,7 @@ class RequestLogger:
         self,
         request_id: str,
         error: str,
-        status_code: Optional[int] = None,
+        status_code: int | None = None,
     ) -> None:
         """
         Log an HTTP request error.