airbyte-agent-github 0.18.128__tar.gz → 0.18.129__tar.gz

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Github changelog
 
+## [0.18.129] - 2026-04-07
+- Updated connector definition (YAML version 0.1.17)
+- Source commit: fbc0bacd
+- SDK version: 0.1.0
+
 ## [0.18.128] - 2026-04-01
 - Updated connector definition (YAML version 0.1.17)
 - Source commit: e4c74933

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airbyte-agent-github
-Version: 0.18.128
+Version: 0.18.129
 Summary: Airbyte Github Connector for AI platforms
 Project-URL: Homepage, https://github.com/airbytehq/airbyte-agent-connectors
 Project-URL: Documentation, https://docs.airbyte.com/ai-agents/
@@ -167,7 +167,7 @@ See the official [Github API reference](https://docs.github.com/en/rest).
 
 ## Version information
 
-- **Package version:** 0.18.128
+- **Package version:** 0.18.129
 - **Connector version:** 0.1.17
-- **Generated with Connector SDK commit SHA:** e4c7493336bcabf5bea5a761ab7b4edfe2a606a5
+- **Generated with Connector SDK commit SHA:** fbc0bacdabf9b1de67621333cd97edee9c444de4
 - **Changelog:** [View changelog](https://github.com/airbytehq/airbyte-agent-connectors/blob/main/connectors/github/CHANGELOG.md)

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/README.md

@@ -134,7 +134,7 @@ See the official [Github API reference](https://docs.github.com/en/rest).
 
 ## Version information
 
-- **Package version:** 0.18.128
+- **Package version:** 0.18.129
 - **Connector version:** 0.1.17
-- **Generated with Connector SDK commit SHA:** e4c7493336bcabf5bea5a761ab7b4edfe2a606a5
+- **Generated with Connector SDK commit SHA:** fbc0bacdabf9b1de67621333cd97edee9c444de4
 - **Changelog:** [View changelog](https://github.com/airbytehq/airbyte-agent-connectors/blob/main/connectors/github/CHANGELOG.md)

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/connector_model_loader.py

@@ -412,7 +412,6 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
             path_override = operation.x_airbyte_path_override
             record_extractor = operation.x_airbyte_record_extractor
             meta_extractor = operation.x_airbyte_meta_extractor
-            param_sources = operation.x_airbyte_param_sources or {}
 
             if not entity_name:
                 raise InvalidOpenAPIError(
@@ -531,7 +530,6 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
                 file_field=file_field,
                 untested=untested,
                 preferred_for_check=preferred_for_check,
-                param_sources=param_sources,
                 upload_file_param=upload_file_param,
                 no_content_response=has_no_content_response,
             )
@@ -550,15 +548,18 @@ 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 and stream_name from components if available
+        # Get schema, stream_name, and ai_hints from components if available
         schema = None
         entity_stream_name = None
+        entity_ai_hints = 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
+                    if schema_def.x_airbyte_ai_hints is not None:
+                        entity_ai_hints = schema_def.x_airbyte_ai_hints.model_dump(by_alias=True)
                     break
 
         entity = EntityDefinition(
@@ -567,9 +568,16 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
             actions=actions,
             endpoints=endpoints_dict,
             schema=schema,
+            ai_hints=entity_ai_hints,
         )
         entities.append(entity)
 
+    # Attach entity relationships from spec
+    _attach_entity_relationships(entities, spec)
+
+    # Read scoping config from spec
+    scoping = list(spec.info.x_airbyte_scoping)
+
     # Extract retry config from x-airbyte-retry-config extension
     retry_config = spec.info.x_airbyte_retry_config
     connector_definition_id = spec.info.x_airbyte_connector_definition_id
@@ -578,6 +586,9 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
 
     search_field_paths = _extract_search_field_paths(spec)
 
+    # Extract example questions from spec (serialized separately from openapi_spec)
+    example_questions = getattr(spec.info, "x_airbyte_example_questions", None)
+
     # Create ConnectorModel
     model = ConnectorModel(
         id=connector_definition_id,
@@ -589,12 +600,32 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
         openapi_spec=spec,
         retry_config=retry_config,
         search_field_paths=search_field_paths,
+        example_questions=example_questions,
         server_variable_defaults=server_variable_defaults,
+        scoping=scoping,
     )
 
     return model
 
 
+def _attach_entity_relationships(
+    entities: list[EntityDefinition],
+    spec: OpenAPIConnector,
+) -> None:
+    """Attach relationships to EntityDefinitions from x-airbyte-entity-relationships.
+
+    Reads the connector-wide relationship declarations from the spec's info
+    object and attaches them to the matching EntityDefinition by source_entity name.
+    """
+    entity_relationships = spec.info.x_airbyte_entity_relationships
+    if entity_relationships:
+        entity_map = {e.name: e for e in entities}
+        for rel in entity_relationships:
+            entity = entity_map.get(rel.source_entity)
+            if entity is not None:
+                entity.relationships.append(rel)
+
+
 def _get_attribute_flexible(obj: Any, *names: str) -> Any:
     """Get attribute from object, trying multiple name variants.
 
@@ -1063,9 +1094,7 @@ def load_connector_model(definition_path: str | Path) -> ConnectorModel:
         raise ValueError("Invalid connector.yaml: empty file")
 
     if "openapi" not in raw_definition:
-        raise ValueError(
-            "Invalid connector.yaml: missing 'openapi' key. Only OpenAPI 3.1 format is supported."
-        )
+        raise ValueError("Invalid connector.yaml: missing 'openapi' key. Only OpenAPI 3.1 format is supported.")
 
     spec = parse_openapi_spec(raw_definition)
     return convert_openapi_to_connector_model(spec)

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/executor/local_executor.py

@@ -254,6 +254,18 @@ class LocalExecutor:
                 if endpoint:
                     self._operation_index[(entity.name, action)] = endpoint
 
+        # Build O(1) scoping index: param_name -> config_key
+        self._scoping_index: dict[str, str] = {s.param: (s.config_key or s.param) for s in self.model.scoping}
+
+        # Build O(1) global foreign-key index: fk_name -> (target_entity, target_key)
+        # Used as a fallback when the current entity has no relationship for a param
+        # but another entity in the connector declares one with the same foreign_key.
+        self._global_fk_index: dict[str, tuple[str, str]] = {}
+        for entity in self.model.entities:
+            for rel in entity.relationships:
+                if rel.foreign_key not in self._global_fk_index:
+                    self._global_fk_index[rel.foreign_key] = (rel.target_entity, rel.target_key)
+
         # Register operation handlers (order matters for can_handle priority)
         op_context = _OperationContext(self)
         self._operation_handlers: list[_OperationHandler] = [
@@ -696,21 +708,29 @@ class LocalExecutor:
             params = {"limit": 1} if action == Action.LIST else {}
             # Inject query param defaults from schema so that required params
             # with defaults (e.g. Salesforce SOQL `q` parameter) are included
-            # in the probe request without needing explicit param_sources.
+            # in the probe request without needing explicit configuration.
             for param_name, schema in endpoint.query_params_schema.items():
                 if param_name not in params and schema.get("default") is not None:
                     params[param_name] = schema["default"]
-            # Collect all params that need resolution: path params plus any
-            # query/body params that have explicit param_sources annotations
-            # (covers GraphQL connectors where all params are query params).
+            # Collect all params that need resolution: path params, entity-
+            # relationship foreign_keys, and query params with matching config
+            # keys (so config values can override schema defaults).
             params_needing_resolution = list(endpoint.path_params)
-            if endpoint.param_sources:
-                for param_name in endpoint.param_sources:
-                    if param_name not in params_needing_resolution:
-                        params_needing_resolution.append(param_name)
+            entity_def = self._entity_index.get(entity_name)
+            if entity_def:
+                for rel in entity_def.relationships:
+                    if rel.foreign_key not in params_needing_resolution:
+                        params_needing_resolution.append(rel.foreign_key)
+            # Also resolve query params that have a matching scoping or config
+            # key, so explicit config values take precedence over defaults.
+            for qp in endpoint.query_params:
+                if qp not in params_needing_resolution and (
+                    qp in self._scoping_index or qp in self.config_values
+                ):
+                    params_needing_resolution.append(qp)
             if params_needing_resolution:
                 try:
-                    resolved = await self._resolve_param_sources(
+                    resolved = await self._resolve_path_params(
                         entity_name,
                         endpoint,
                         standard_handler,
@@ -743,7 +763,7 @@ class LocalExecutor:
                 "checked_action": action.value,
             }
 
-    async def _resolve_param_sources(
+    async def _resolve_path_params(
         self,
         entity_name: str,
         endpoint: EndpointDefinition,
@@ -752,7 +772,12 @@ class LocalExecutor:
         depth: int = 0,
         params_to_resolve: list[str] | None = None,
     ) -> dict[str, Any]:
-        """Resolve params using x-airbyte-param-sources annotations and config_values.
+        """Resolve params using scoping, config fallback, and entity relationships.
+
+        Resolution priority for each path param:
+        1. Scoping index (from ConnectorModel.scoping) -> config_values
+        2. Config fallback (param name matches a config_values key)
+        3. Entity relationships (from entity.relationships by foreign_key)
 
         Returns dict of {param_name: resolved_value}.
         Raises ParamResolutionError if any param cannot be resolved.
@@ -760,20 +785,35 @@ class LocalExecutor:
         if depth > MAX_PARAM_RESOLUTION_DEPTH:
             raise ParamResolutionError(f"Max resolution depth exceeded for '{entity_name}'")
 
+        # Build relationship index for this entity: foreign_key -> (target_entity, target_key)
+        entity_def = self._entity_index.get(entity_name)
+        rel_index: dict[str, tuple[str, str]] = {}
+        if entity_def:
+            for rel in entity_def.relationships:
+                rel_index[rel.foreign_key] = (rel.target_entity, rel.target_key)
+
         target_params = params_to_resolve if params_to_resolve is not None else list(endpoint.path_params)
 
         resolved: dict[str, Any] = {}
         for param_name in target_params:
-            source = endpoint.param_sources.get(param_name, {})
+            # 1. Check scoping index
+            scoping_key = self._scoping_index.get(param_name)
+            if scoping_key and scoping_key in self.config_values:
+                resolved[param_name] = self.config_values[scoping_key]
+                continue
 
-            config_key = source.get("config") or param_name
-            if config_key in self.config_values:
-                resolved[param_name] = self.config_values[config_key]
+            # 2. Config fallback: param name matches a config_values key
+            if param_name in self.config_values:
+                resolved[param_name] = self.config_values[param_name]
                 continue
 
-            parent_entity_name = source.get("parent_entity")
-            parent_key = source.get("parent_key")
-            if not parent_entity_name or not parent_key:
+            # 3. Check entity relationships by foreign_key
+            if param_name in rel_index:
+                parent_entity_name, parent_key = rel_index[param_name]
+            elif param_name in self._global_fk_index:
+                # Fallback: another entity declares a relationship for this foreign key
+                parent_entity_name, parent_key = self._global_fk_index[param_name]
+            else:
                 raise ParamResolutionError(f"Cannot resolve param '{param_name}' for entity '{entity_name}'")
             if parent_entity_name == entity_name:
                 raise ParamResolutionError(f"Self-referential param '{param_name}' on entity '{entity_name}'")
@@ -788,7 +828,7 @@ class LocalExecutor:
                     if pname not in parent_params and pschema.get("default") is not None:
                         parent_params[pname] = pschema["default"]
                 if parent_endpoint.path_params:
-                    parent_resolved = await self._resolve_param_sources(
+                    parent_resolved = await self._resolve_path_params(
                         parent_entity_name,
                         parent_endpoint,
                         standard_handler,

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/extensions.py

@@ -450,41 +450,6 @@ Example:
     ```
 """
 
-AIRBYTE_PARAM_SOURCES = "x-airbyte-param-sources"
-"""
-Extension: x-airbyte-param-sources
-Location: Operation object (on individual HTTP operations)
-Type: dict[str, dict[str, str]] (param name → source declaration)
-Required: No
-
-Description:
-    Per-param source declarations for entity dependency resolution. Each key is
-    a parameter name; each value is a dict describing where that parameter's
-    value comes from at runtime.
-
-    Two source patterns are supported:
-
-    Pattern 1 — Parent entity (param value comes from another entity's field):
-        parent_entity: Name of the parent entity
-        parent_key: Field on the parent entity that supplies the value
-
-    Pattern 2 — Config (param value comes from user-provided configuration):
-        config: Name of the config key
-
-Example:
-    ```yaml
-    paths:
-      /accounts/{account_id}/contacts:
-        get:
-          x-airbyte-entity: contacts
-          x-airbyte-action: list
-          x-airbyte-param-sources:
-            account_id:
-              parent_entity: accounts
-              parent_key: id
-    ```
-"""
-
 AIRBYTE_TOKEN_EXTRACT = "x-airbyte-token-extract"
 """
 Extension: x-airbyte-token-extract
@@ -534,6 +499,66 @@ Example:
     ```
 """
 
+AIRBYTE_ENTITY_RELATIONSHIPS = "x-airbyte-entity-relationships"
+"""
+Extension: x-airbyte-entity-relationships
+Location: OpenAPI Info object
+Type: list[EntityRelationshipConfig]
+Required: No
+
+Description:
+    Declares foreign-key relationships between entities. Each entry specifies
+    which entity holds the foreign key (source_entity), which entity is
+    referenced (target_entity), the foreign key field, and optional cardinality.
+
+    Provides a single, connector-wide relationship graph that the runtime
+    uses for dependency resolution and agent introspection.
+
+Example:
+    ```yaml
+    info:
+      title: My API
+      x-airbyte-entity-relationships:
+        - source_entity: contacts
+          target_entity: accounts
+          foreign_key: account_id
+          cardinality: many_to_one
+          description: "Contact belongs to an account"
+        - source_entity: deals
+          target_entity: contacts
+          foreign_key: contact_id
+          target_key: id
+          cardinality: many_to_one
+    ```
+"""
+
+AIRBYTE_SCOPING = "x-airbyte-scoping"
+"""
+Extension: x-airbyte-scoping
+Location: OpenAPI Info object
+Type: list[ScopingParamConfig]
+Required: No
+
+Description:
+    Declares path parameters that should be resolved from the connector's
+    config values at runtime, rather than being supplied per-request. This
+    is used for tenant-scoped APIs where a path segment (e.g., account_id)
+    is fixed for the lifetime of the connector instance.
+
+    Each entry maps a path parameter name to an optional config key. If
+    config_key is omitted, the param name itself is used as the config key.
+
+Example:
+    ```yaml
+    info:
+      title: My API
+      x-airbyte-scoping:
+        - param: account_id
+          config_key: account_id
+        - param: workspace_id
+    ```
+"""
+
 
 # =============================================================================
 # Enums and Type Definitions
@@ -622,8 +647,9 @@ def get_all_extension_names() -> list[str]:
         AIRBYTE_RECORD_EXTRACTOR,
         AIRBYTE_META_EXTRACTOR,
         AIRBYTE_FILE_URL,
-        AIRBYTE_PARAM_SOURCES,
         AIRBYTE_TOKEN_EXTRACT,
+        AIRBYTE_ENTITY_RELATIONSHIPS,
+        AIRBYTE_SCOPING,
     ]
 
 
@@ -711,18 +737,24 @@ EXTENSION_REGISTRY = {
         "required": "conditional",  # Required when action is 'download'
         "description": "Field in metadata response containing download URL (required for download action)",
     },
-    AIRBYTE_PARAM_SOURCES: {
-        "location": "operation",
-        "type": "dict[str, dict[str, str]]",
-        "required": False,
-        "description": "Per-param source declarations for entity dependency resolution (parent_entity+parent_key or config)",
-    },
     AIRBYTE_TOKEN_EXTRACT: {
         "location": "securityScheme",
         "type": "list[str]",
         "required": False,
         "description": "List of fields to extract from OAuth2 token responses and use as server variables",
     },
+    AIRBYTE_ENTITY_RELATIONSHIPS: {
+        "location": "info",
+        "type": "EntityRelationshipConfig",
+        "required": False,
+        "description": "Foreign-key relationships between entities for dependency resolution and agent introspection",
+    },
+    AIRBYTE_SCOPING: {
+        "location": "info",
+        "type": "ScopingParamConfig",
+        "required": False,
+        "description": "Path parameters resolved from connector config at runtime for tenant-scoped APIs",
+    },
 }
 """
 Complete registry of all Airbyte extensions with metadata.

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/introspection.py

@@ -411,7 +411,25 @@ def generate_tool_description(
     # Avoid a "PARAMETERS:" header because some docstring parsers treat it as a params section marker.
     lines.append("ENTITIES (ACTIONS + PARAMS):")
     for entity in model.entities:
-        lines.append(f"  {entity.name}:")
+        # Emit per-entity AI hints if available
+        ai_hints = getattr(entity, "ai_hints", None) or {}
+        hint_summary = ai_hints.get("summary") if isinstance(ai_hints, dict) else None
+        if hint_summary:
+            lines.append(f"  {entity.name}: {hint_summary}")
+        else:
+            lines.append(f"  {entity.name}:")
+        hint_when = ai_hints.get("when_to_use") if isinstance(ai_hints, dict) else None
+        if hint_when:
+            lines.append(f"    WHEN TO USE: {hint_when}")
+        hint_freshness = ai_hints.get("freshness") if isinstance(ai_hints, dict) else None
+        if hint_freshness:
+            lines.append(f"    FRESHNESS: {hint_freshness.upper()}")
+        hint_triggers = ai_hints.get("trigger_phrases", []) if isinstance(ai_hints, dict) else []
+        if hint_triggers:
+            lines.append(f"    Trigger phrases: {', '.join(hint_triggers)}")
+        hint_search = ai_hints.get("search_strategy") if isinstance(ai_hints, dict) else None
+        if hint_search:
+            lines.append(f"    SEARCH STRATEGY: {hint_search}")
         actions = getattr(entity, "actions", []) or []
         endpoints = getattr(entity, "endpoints", {}) or {}
         for action in actions:
@@ -425,6 +443,17 @@ def generate_tool_description(
         if entity.name in search_field_paths:
             search_sig = _format_search_param_signature()
             lines.append(f"    - search{search_sig}")
+        # Per-entity example questions from ai_hints
+        hint_examples = ai_hints.get("example_questions", []) if isinstance(ai_hints, dict) else []
+        if hint_examples:
+            lines.append(f"    Examples: {'; '.join(hint_examples[:3])}")
+
+    # Entity relationships
+    all_relationships = [r for e in model.entities for r in e.relationships]
+    if all_relationships:
+        lines.append("ENTITY RELATIONSHIPS:")
+        for rel in all_relationships:
+            lines.append(f"  {rel.format_line()}")
 
     # Response structure (brief, includes pagination hint)
     lines.append("RESPONSE STRUCTURE:")
@@ -458,30 +487,32 @@ def generate_tool_description(
             else:
                 lines.append(f"  {entity_name}: (no fields listed)")
 
-    # 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:
-                direct_questions = getattr(example_questions, "direct", None)
-                search_questions = getattr(example_questions, "search", None)
-
-                direct_questions = direct_questions if isinstance(direct_questions, list) else []
-                search_questions = search_questions if isinstance(search_questions, list) else []
-
-                selected_questions: list[str] = []
-                if direct_questions or search_questions:
-                    if enable_hosted_mode_features and search_questions:
-                        selected_questions = list(search_questions)
-                    else:
-                        selected_questions = list(direct_questions) or list(search_questions)
-
-                if selected_questions:
-                    lines.append("EXAMPLE QUESTIONS:")
-                    for q in selected_questions[:MAX_EXAMPLE_QUESTIONS]:
-                        lines.append(f"  - {q}")
+    # Add example questions — try direct model field first, fall back to openapi_spec
+    example_questions = getattr(model, "example_questions", None)
+    if not example_questions:
+        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:
+        direct_questions = getattr(example_questions, "direct", None)
+        search_questions = getattr(example_questions, "search", None)
+
+        direct_questions = direct_questions if isinstance(direct_questions, list) else []
+        search_questions = search_questions if isinstance(search_questions, list) else []
+
+        selected_questions: list[str] = []
+        if direct_questions or search_questions:
+            if enable_hosted_mode_features and search_questions:
+                selected_questions = list(search_questions)
+            else:
+                selected_questions = list(direct_questions) or list(search_questions)
+
+        if selected_questions:
+            lines.append("EXAMPLE QUESTIONS:")
+            for q in selected_questions[:MAX_EXAMPLE_QUESTIONS]:
+                lines.append(f"  - {q}")
 
     # Generic parameter description for function signature
     lines.append("FUNCTION PARAMETERS:")

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/schema/__init__.py

@@ -26,7 +26,7 @@ from .components import (
     Schema,
 )
 from .connector import ExternalDocs, OpenAPIConnector, Tag
-from .extensions import RetryConfig
+from .extensions import EntityRelationshipConfig, RetryConfig, ScopingParamConfig
 from .operations import Operation, PathItem
 from .security import (
     AirbyteAuthConfig,
@@ -68,4 +68,6 @@ __all__ = [
     "Operation",
     # Extension models
     "RetryConfig",
+    "EntityRelationshipConfig",
+    "ScopingParamConfig",
 ]

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/schema/base.py

@@ -13,7 +13,7 @@ from uuid import UUID
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 from pydantic_core import Url
 
-from .extensions import CacheConfig, ReplicationConfig, RetryConfig
+from .extensions import CacheConfig, EntityRelationshipConfig, ReplicationConfig, RetryConfig, ScopingParamConfig
 
 
 class ExampleQuestions(BaseModel):
@@ -111,6 +111,8 @@ class Info(BaseModel):
     - x-airbyte-example-questions: Example questions for AI connector README (Airbyte extension)
     - x-airbyte-cache: Cache configuration for field mapping between API and cache schemas (Airbyte extension)
     - x-airbyte-replication-config: Replication configuration for MULTI mode connectors (Airbyte extension)
+    - x-airbyte-entity-relationships: Entity relationship declarations (Airbyte extension)
+    - x-airbyte-scoping: Scoping parameter resolution from config (Airbyte extension)
     """
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
@@ -129,6 +131,10 @@ class Info(BaseModel):
     x_airbyte_retry_config: RetryConfig | None = Field(None, alias="x-airbyte-retry-config")
     x_airbyte_example_questions: ExampleQuestions | None = Field(None, alias="x-airbyte-example-questions")
     x_airbyte_cache: CacheConfig | None = Field(None, alias="x-airbyte-cache")
+    x_airbyte_entity_relationships: list[EntityRelationshipConfig] = Field(
+        default_factory=list, alias="x-airbyte-entity-relationships"
+    )
+    x_airbyte_scoping: list[ScopingParamConfig] = Field(default_factory=list, alias="x-airbyte-scoping")
     x_airbyte_replication_config: ReplicationConfig | None = Field(None, alias="x-airbyte-replication-config")
     x_airbyte_replication_version: str | None = Field(
         default=None,

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/schema/components.py

@@ -14,6 +14,24 @@ from pydantic import BaseModel, ConfigDict, Field
 from .security import SecurityScheme
 
 
+class AiHints(BaseModel):
+    """
+    AI hints for entity schemas — helps LLMs understand when and how to use an entity.
+
+    Attached to entity response schemas via x-airbyte-ai-hints extension.
+    Used by generate_tool_description() to emit per-entity guidance.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    summary: str | None = Field(None, description="One-line description of what this entity contains")
+    when_to_use: str | None = Field(None, description="When an LLM should query this entity")
+    trigger_phrases: List[str] = Field(default_factory=list, description="Example user queries that should trigger this entity")
+    freshness: Literal["live", "static"] | None = Field(None, description="Whether data is live or static")
+    example_questions: List[str] = Field(default_factory=list, description="Example questions answerable by this entity")
+    search_strategy: str | None = Field(None, description="Hint for LLMs on how to construct effective search queries for this entity")
+
+
 class Schema(BaseModel):
     """
     JSON Schema definition for data models.
@@ -68,6 +86,7 @@ class Schema(BaseModel):
     # Airbyte extensions
     x_airbyte_entity_name: str | None = Field(None, alias="x-airbyte-entity-name")
     x_airbyte_stream_name: str | None = Field(None, alias="x-airbyte-stream-name")
+    x_airbyte_ai_hints: AiHints | None = Field(None, alias="x-airbyte-ai-hints")
 
 
 class Parameter(BaseModel):

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/schema/extensions.py

@@ -5,6 +5,8 @@ Provides Pydantic models for OpenAPI x-airbyte-* extensions:
 - RetryConfig: retry strategy with exponential backoff
 - CacheConfig / CacheEntityConfig / CacheFieldConfig: cache mapping for api_search
 - ReplicationConfig: replication settings for MULTI mode connectors
+- EntityRelationshipConfig: entity relationship declarations
+- ScopingParamConfig: scoping parameter resolution from config
 """
 
 from typing import Literal
@@ -284,3 +286,73 @@ class CacheConfig(BaseModel):
             if entity.entity == user_entity:
                 return entity
         return None
+
+
+class EntityRelationshipConfig(BaseModel):
+    """
+    Entity relationship declaration for cross-entity navigation.
+
+    Defines a foreign-key relationship between two entities, enabling
+    the runtime to resolve parent-child dependencies and provide
+    relationship metadata to agents.
+
+    Used in x-airbyte-entity-relationships extension in the Info object.
+
+    Example YAML usage:
+        info:
+          title: My API
+          x-airbyte-entity-relationships:
+            - source_entity: contacts
+              target_entity: accounts
+              foreign_key: account_id
+              cardinality: many_to_one
+              description: "Contact belongs to an account"
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    source_entity: str = Field(description="Entity that holds the foreign key")
+    target_entity: str = Field(description="Entity being referenced")
+    foreign_key: str = Field(description="Field on source_entity that references target_entity")
+    target_key: str = Field(default="id", description="Field on target_entity being referenced")
+    cardinality: Literal["one_to_one", "one_to_many", "many_to_one", "many_to_many"] | None = Field(
+        None, description="Optional relationship cardinality"
+    )
+    description: str | None = Field(
+        None, description="Human-readable description of the relationship"
+    )
+
+    def format_line(self) -> str:
+        """Format as a human-readable line for tool descriptions."""
+        line = f"{self.source_entity} -> {self.target_entity} (via {self.foreign_key}"
+        if self.cardinality:
+            line += f", {self.cardinality.replace('_', '-')}"
+        line += ")"
+        if self.description:
+            line += f" -- {self.description}"
+        return line
+
+
+class ScopingParamConfig(BaseModel):
+    """
+    Scoping parameter resolution from connector configuration.
+
+    Declares a path parameter that should be resolved from the connector's
+    config values at runtime, rather than being supplied per-request.
+
+    Used in x-airbyte-scoping extension in the Info object.
+
+    Example YAML usage:
+        info:
+          title: My API
+          x-airbyte-scoping:
+            - param: account_id
+              config_key: account_id
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    param: str = Field(description="Path parameter name to resolve from config")
+    config_key: str | None = Field(
+        None, description="Config key to read. Defaults to param name if omitted."
+    )

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/schema/operations.py

@@ -74,14 +74,6 @@ class Operation(BaseModel):
             "Example: {'pagination': '$.pagination', 'request_id': '$.requestId'}"
         ),
     )
-    x_airbyte_param_sources: Dict[str, Dict[str, str]] | None = Field(
-        None,
-        alias="x-airbyte-param-sources",
-        description=(
-            "Per-param source declarations for entity dependency resolution. "
-            "Keys are param names; values have 'parent_entity'+'parent_key' or 'config' keys."
-        ),
-    )
     x_airbyte_file_url: str | None = Field(None, alias="x-airbyte-file-url")
     x_airbyte_untested: bool | None = Field(
         None,

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/types.py

@@ -10,7 +10,7 @@ from pydantic import AliasChoices, BaseModel, ConfigDict, Field
 
 from .constants import OPENAPI_DEFAULT_VERSION
 from .schema.components import PathOverrideConfig
-from .schema.extensions import RetryConfig
+from .schema.extensions import EntityRelationshipConfig, RetryConfig, ScopingParamConfig
 from .schema.security import AirbyteAuthConfig
 
 
@@ -304,14 +304,6 @@ class EndpointDefinition(BaseModel):
         description="Mark this operation as preferred for health checks (from x-airbyte-preferred-for-check extension)",
     )
 
-    param_sources: dict[str, dict[str, str]] = Field(
-        default_factory=dict,
-        description=(
-            "Per-param source declarations: "
-            "{param_name: {'parent_entity': ..., 'parent_key': ...} | {'config': ...}}."
-        ),
-    )
-
     upload_file_param: str | None = Field(
         None,
         description="Parameter name containing base64-encoded file content for multipart/related uploads (from x-airbyte-upload-file-param)",
@@ -336,6 +328,14 @@ class EntityDefinition(BaseModel):
     actions: list[Action]
     endpoints: dict[Action, EndpointDefinition]
     entity_schema: dict[str, Any] | None = Field(default=None, alias="schema")
+    ai_hints: dict[str, Any] | None = Field(
+        default=None,
+        description="AI hints for this entity (from x-airbyte-ai-hints schema extension)",
+    )
+    relationships: list[EntityRelationshipConfig] = Field(
+        default_factory=list,
+        description="Relationships where this entity is the source (from x-airbyte-entity-relationships)",
+    )
 
 
 class ConnectorModel(BaseModel):
@@ -352,6 +352,11 @@ class ConnectorModel(BaseModel):
     openapi_spec: Any | None = None  # Optional reference to OpenAPIConnector
     retry_config: RetryConfig | None = None  # Optional retry configuration
     search_field_paths: dict[str, list[str]] | None = None
+    example_questions: Any | None = None  # ExampleQuestions from x-airbyte-example-questions
+    scoping: list[ScopingParamConfig] = Field(
+        default_factory=list,
+        description="Scoping parameters resolved from config at runtime (from x-airbyte-scoping)",
+    )
     server_variable_defaults: dict[str, str] = Field(
         default_factory=dict,
         description="Default values for server URL variables from the OpenAPI spec. "

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/_vendored/connector_sdk/validation/readiness.py

@@ -632,16 +632,33 @@ def validate_meta_extractor_fields(
     return True, errors, warnings
 
 
-def _check_param_sources_coverage(config: ConnectorModel) -> List[str]:
-    """Check that endpoints with path params have x-airbyte-param-sources declarations.
+def _check_entity_relationships(config: ConnectorModel) -> List[str]:
+    """Check that entity relationship target_entity values reference real entities.
+
+    Returns a list of warning strings for relationships where target_entity
+    does not match any defined entity name.
+    """
+    warnings: List[str] = []
+    entity_names = {e.name for e in config.entities}
+    for entity in config.entities:
+        for rel in entity.relationships:
+            if rel.target_entity not in entity_names:
+                warnings.append(
+                    f"Entity '{entity.name}' has relationship with target_entity " f"'{rel.target_entity}' which does not match any defined entity."
+                )
+    return warnings
+
+
+def _check_entity_relationships_coverage(config: ConnectorModel) -> List[str]:
+    """Check that endpoints with path params are covered by entity relationships or scoping.
 
     Returns a list of warning strings for endpoints where path parameters
-    are not covered by param_sources and are not implicitly resolvable from
-    config (auth properties, server variables).
+    are not covered by entity relationships, scoping, or implicit config
+    resolution.
 
     Skips single-record actions (get, update, delete) when the entity also has
     a list action, since those path params are the entity's own primary key
-    resolved from list results — not a parent dependency.
+    resolved from list results -- not a parent dependency.
     """
     warnings: List[str] = []
 
@@ -656,10 +673,15 @@ def _check_param_sources_coverage(config: ConnectorModel) -> List[str]:
         implicit_config_keys.update(config.auth.user_config_spec.properties.keys())
     implicit_config_keys.update(config.server_variable_defaults.keys())
 
-    single_record_actions = {Action.GET, Action.UPDATE, Action.DELETE}
+    # Collect scoping param names
+    scoping_params = {s.param for s in config.scoping}
+
+    single_record_actions = {Action.GET, Action.UPDATE, Action.DELETE, Action.DOWNLOAD}
 
     for entity in config.entities:
         has_list = Action.LIST in entity.endpoints
+        # Build set of foreign_keys covered by entity relationships
+        relationship_keys = {rel.foreign_key for rel in entity.relationships}
         for action, endpoint in entity.endpoints.items():
             if not endpoint.path_params:
                 continue
@@ -668,16 +690,18 @@ def _check_param_sources_coverage(config: ConnectorModel) -> List[str]:
             if has_list and action in single_record_actions:
                 continue
             for param in endpoint.path_params:
-                if param in endpoint.param_sources:
+                if param in relationship_keys:
+                    continue
+                if param in scoping_params:
                     continue
                 # SDK resolves implicitly when param name matches a config key
                 if param in implicit_config_keys:
                     continue
                 warnings.append(
                     f"Entity '{entity.name}' operation '{action.value}' has path parameter "
-                    f"'{param}' with no x-airbyte-param-sources declaration. "
-                    f"Add param-sources to enable per-entity health checks. "
-                    f"See get_connector_yaml_schema_docs('extensions') for guidance."
+                    f"'{param}' with no entity relationship or scoping declaration. "
+                    f"Add an x-airbyte-entity-relationships entry or x-airbyte-scoping entry "
+                    f"to enable per-entity health checks."
                 )
     return warnings
 
@@ -992,8 +1016,7 @@ def validate_connector_readiness(connector_dir: str | Path) -> Dict[str, Any]:
     # All agent connectors must have a replication counterpart in the Airbyte registry
     if not replication_result.get("registry_found", False):
         replication_errors.append(
-            "No replication connector found in Airbyte registry. "
-            "All agent connectors must have a corresponding replication connector."
+            "No replication connector found in Airbyte registry. " "All agent connectors must have a corresponding replication connector."
         )
 
     total_errors += len(replication_errors)
@@ -1054,10 +1077,25 @@ def validate_connector_readiness(connector_dir: str | Path) -> Dict[str, Any]:
             "to enable reliable health checks."
         )
 
-    # Check for missing x-airbyte-param-sources declarations
-    param_source_warnings = _check_param_sources_coverage(config)
-    readiness_warnings.extend(param_source_warnings)
-    total_warnings += len(param_source_warnings)
+    # Check for missing entity relationship / scoping declarations
+    relationship_coverage_warnings = _check_entity_relationships_coverage(config)
+    readiness_warnings.extend(relationship_coverage_warnings)
+    total_warnings += len(relationship_coverage_warnings)
+
+    # Check entity relationship target_entity references
+    relationship_warnings = _check_entity_relationships(config)
+    readiness_warnings.extend(relationship_warnings)
+    total_warnings += len(relationship_warnings)
+
+    # Check for missing x-airbyte-ai-hints on entities
+    entities_missing_hints = [entity.name for entity in config.entities if not getattr(entity, "ai_hints", None)]
+    if entities_missing_hints:
+        readiness_warnings.append(
+            f"Entities missing x-airbyte-ai-hints: {', '.join(entities_missing_hints)}. "
+            "Add AI hints (summary, when_to_use, trigger_phrases, freshness) to each entity schema "
+            "to improve LLM tool selection. See get_connector_yaml_schema_docs('extensions') for details."
+        )
+        total_warnings += 1
 
     if total_cassettes > 0:
         readiness_warnings.append(

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/connector.py

@@ -108,7 +108,7 @@ 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
+DEFAULT_MAX_OUTPUT_CHARS = 100_000  # ~100KB default, configurable per-tool
 
 
 def _raise_output_too_large(message: str) -> None:

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/airbyte_agent_github/connector_model.py

@@ -20,6 +20,9 @@ from ._vendored.connector_sdk.schema.security import (
     AirbyteAuthConfig,
     AuthConfigFieldSpec,
 )
+from ._vendored.connector_sdk.schema.base import (
+    ExampleQuestions,
+)
 from ._vendored.connector_sdk.schema.components import (
     PathOverrideConfig,
 )
@@ -2899,4 +2902,27 @@ GithubConnectorModel: ConnectorModel = ConnectorModel(
             },
         ),
     ],
+    example_questions=ExampleQuestions(
+        direct=[
+            'Show me all open issues in my repositories this month',
+            "List the top 5 repositories I've starred recently",
+            'Analyze the commit trends in my main project over the last quarter',
+            'Find all pull requests created in the past two weeks',
+            'Search for repositories related to machine learning in my organizations',
+            'Compare the number of contributors across my different team projects',
+            'Identify the most active branches in my main repository',
+            'Get details about the most recent releases in my organization',
+            'List all milestones for our current development sprint',
+            'Show me insights about pull request review patterns in our team',
+            'List all unanswered discussions in a repository',
+            'Show me recent discussions in the General category',
+        ],
+        unsupported=[
+            'Create a new issue in the project repository',
+            'Update the status of this pull request',
+            'Delete an old branch from the repository',
+            'Schedule a team review for this code',
+            'Assign a new label to this issue',
+        ],
+    ),
 )

{airbyte_agent_github-0.18.128 → airbyte_agent_github-0.18.129}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "airbyte-agent-github"
-version = "0.18.128"
+version = "0.18.129"
 description = "Airbyte Github Connector for AI platforms"
 readme = "README.md"
 requires-python = ">=3.13"