airbyte-agent-salesforce 0.1.14__tar.gz → 0.1.25__tar.gz

{airbyte_agent_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Salesforce changelog
 
+## [0.1.25] - 2026-01-09
+- Updated connector definition (YAML version 1.0.4)
+- Source commit: 3c7bfdfd
+- SDK version: 0.1.0
+
+## [0.1.24] - 2026-01-09
+- Updated connector definition (YAML version 1.0.4)
+- Source commit: 3bcb33e8
+- SDK version: 0.1.0
+
+## [0.1.23] - 2026-01-09
+- Updated connector definition (YAML version 1.0.4)
+- Source commit: da9b741b
+- SDK version: 0.1.0
+
+## [0.1.22] - 2026-01-07
+- Updated connector definition (YAML version 1.0.4)
+- Source commit: d023e05f
+- SDK version: 0.1.0
+
+## [0.1.21] - 2026-01-06
+- Updated connector definition (YAML version 1.0.4)
+- Source commit: 0580c727
+- SDK version: 0.1.0
+
+## [0.1.20] - 2026-01-06
+- Updated connector definition (YAML version 1.0.4)
+- Source commit: e0e2f989
+- SDK version: 0.1.0
+
+## [0.1.19] - 2026-01-05
+- Updated connector definition (YAML version 1.0.4)
+- Source commit: 3e274293
+- SDK version: 0.1.0
+
+## [0.1.18] - 2025-12-22
+- Updated connector definition (YAML version 1.0.4)
+- Source commit: 0eb1b1c4
+- SDK version: 0.1.0
+
+## [0.1.17] - 2025-12-19
+- Updated connector definition (YAML version 1.0.3)
+- Source commit: 12f6b994
+- SDK version: 0.1.0
+
+## [0.1.16] - 2025-12-19
+- Updated connector definition (YAML version 1.0.3)
+- Source commit: 5d11bfdf
+- SDK version: 0.1.0
+
+## [0.1.15] - 2025-12-19
+- Updated connector definition (YAML version 1.0.3)
+- Source commit: e996e848
+- SDK version: 0.1.0
+
 ## [0.1.14] - 2025-12-18
 - Updated connector definition (YAML version 1.0.3)
 - Source commit: f7c55d3e

{airbyte_agent_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airbyte-agent-salesforce
-Version: 0.1.14
+Version: 0.1.25
 Summary: Airbyte Salesforce 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
@@ -42,21 +42,25 @@ notes, and attachments for sales analytics and customer relationship management.
 
 ## Example questions
 
+The Salesforce connector is optimized to handle prompts like these.
+
 - Show me my top 5 opportunities this month
-- List all contacts from [Company] in the last quarter
+- List all contacts from \{company\} in the last quarter
 - Search for leads in the technology sector with revenue over $10M
 - What trends can you identify in my recent sales pipeline?
 - Summarize the open cases for my key accounts
 - Find upcoming events related to my most important opportunities
 - Analyze the performance of my recent marketing campaigns
 - Identify the highest value opportunities I'm currently tracking
-- Show me the notes and attachments for [customerX]'s account
+- Show me the notes and attachments for \{customer\}'s account
 
 ## Unsupported questions
 
-- Create a new lead for [personX]
+The Salesforce connector isn't currently able to handle prompts like these.
+
+- Create a new lead for \{person\}
 - Update the status of my sales opportunity
-- Schedule a follow-up meeting with [customerX]
+- Schedule a follow-up meeting with \{customer\}
 - Delete this old contact record
 - Send an email to all contacts in this campaign
 
@@ -81,6 +85,7 @@ connector = SalesforceConnector(
 result = await connector.accounts.list()
 ```
 
+
 ## Full documentation
 
 This connector supports the following entities and actions.
@@ -107,6 +112,6 @@ For the service's official API docs, see the [Salesforce API reference](https://
 
 ## Version information
 
-- **Package version:** 0.1.14
-- **Connector version:** 1.0.3
-- **Generated with Connector SDK commit SHA:** f7c55d3e3cdc7568cab2da9d736285eec58f044b
+- **Package version:** 0.1.25
+- **Connector version:** 1.0.4
+- **Generated with Connector SDK commit SHA:** 3c7bfdfd1100dd20420a61cec56549b65820ea0f

{airbyte_agent_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/README.md

@@ -8,21 +8,25 @@ notes, and attachments for sales analytics and customer relationship management.
 
 ## Example questions
 
+The Salesforce connector is optimized to handle prompts like these.
+
 - Show me my top 5 opportunities this month
-- List all contacts from [Company] in the last quarter
+- List all contacts from \{company\} in the last quarter
 - Search for leads in the technology sector with revenue over $10M
 - What trends can you identify in my recent sales pipeline?
 - Summarize the open cases for my key accounts
 - Find upcoming events related to my most important opportunities
 - Analyze the performance of my recent marketing campaigns
 - Identify the highest value opportunities I'm currently tracking
-- Show me the notes and attachments for [customerX]'s account
+- Show me the notes and attachments for \{customer\}'s account
 
 ## Unsupported questions
 
-- Create a new lead for [personX]
+The Salesforce connector isn't currently able to handle prompts like these.
+
+- Create a new lead for \{person\}
 - Update the status of my sales opportunity
-- Schedule a follow-up meeting with [customerX]
+- Schedule a follow-up meeting with \{customer\}
 - Delete this old contact record
 - Send an email to all contacts in this campaign
 
@@ -47,6 +51,7 @@ connector = SalesforceConnector(
 result = await connector.accounts.list()
 ```
 
+
 ## Full documentation
 
 This connector supports the following entities and actions.
@@ -73,6 +78,6 @@ For the service's official API docs, see the [Salesforce API reference](https://
 
 ## Version information
 
-- **Package version:** 0.1.14
-- **Connector version:** 1.0.3
-- **Generated with Connector SDK commit SHA:** f7c55d3e3cdc7568cab2da9d736285eec58f044b
+- **Package version:** 0.1.25
+- **Connector version:** 1.0.4
+- **Generated with Connector SDK commit SHA:** 3c7bfdfd1100dd20420a61cec56549b65820ea0f

{airbyte_agent_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/airbyte_agent_salesforce/_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_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/airbyte_agent_salesforce/_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_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/airbyte_agent_salesforce/_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_salesforce-0.1.25/airbyte_agent_salesforce/_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_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/airbyte_agent_salesforce/_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_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/airbyte_agent_salesforce/_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_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/airbyte_agent_salesforce/_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_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/airbyte_agent_salesforce/connector.py

@@ -4,14 +4,15 @@ salesforce 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 SalesforceConnectorModel
-
+from ._vendored.connector_sdk.introspection import describe_entities, generate_tool_description
 from .types import (
     AccountsGetParams,
     AccountsListParams,
@@ -48,7 +49,6 @@ from .types import (
     TasksListParams,
     TasksSearchParams,
 )
-
 if TYPE_CHECKING:
     from .models import SalesforceAuthConfig
 # Import response models and envelope models at runtime
@@ -81,6 +81,9 @@ from .models import (
     TaskQueryResult,
 )
 
+# TypeVar for decorator type preservation
+_F = TypeVar("_F", bound=Callable[..., Any])
+
 
 class SalesforceConnector:
     """
@@ -90,7 +93,7 @@ class SalesforceConnector:
     """
 
     connector_name = "salesforce"
-    connector_version = "1.0.3"
+    connector_version = "1.0.4"
     vendored_sdk_version = "0.1.0"  # Version of vendored connector-sdk
 
     # Map of (entity, action) -> has_extractors for envelope wrapping decision
@@ -613,6 +616,88 @@ class SalesforceConnector:
             # 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()
+            @SalesforceConnector.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(SalesforceConnectorModel)
+
+        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(SalesforceConnectorModel)
+
+    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 SalesforceConnectorModel.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 SalesforceConnectorModel.entities]}"
+            )
+        return entity_def.entity_schema if entity_def else None
+
 
 
 class AccountsQuery:

{airbyte_agent_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/airbyte_agent_salesforce/connector_model.py

@@ -29,7 +29,7 @@ from uuid import (
 SalesforceConnectorModel: ConnectorModel = ConnectorModel(
     id=UUID('b117307c-14b6-41aa-9422-947e34922962'),
     name='salesforce',
-    version='1.0.3',
+    version='1.0.4',
     base_url='{instance_url}/services/data/v59.0',
     auth=AuthConfig(
         type=AuthType.OAUTH2,

{airbyte_agent_salesforce-0.1.14 → airbyte_agent_salesforce-0.1.25}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "airbyte-agent-salesforce"
-version = "0.1.14"
+version = "0.1.25"
 description = "Airbyte Salesforce Connector for AI platforms"
 readme = "README.md"
 requires-python = ">=3.9"