feat: add X-Glean headers for experimental features and deprecation testing

- Add XGlean beforeRequest hook that sets X-Glean-Exclude-Deprecated-After
  and X-Glean-Experimental headers
- Introduce new SDK options exclude_deprecated_after and include_experimental
  with corresponding environment variable support
- Add documentation for testing experimental features and deprecation testing
- Add comprehensive test suite for the XGlean hook

Author: travis-hoover-glean

README.md

@@ -56,6 +56,7 @@ Remember that each namespace requires its own authentication token type as descr
   * [Custom HTTP Client](#custom-http-client)
   * [Resource Management](#resource-management)
   * [Debugging](#debugging)
+  * [Experimental Features and Deprecation Testing](#experimental-features-and-deprecation-testing)
 * [Development](#development)
   * [Maturity](#maturity)
   * [Contributions](#contributions)
@@ -960,6 +961,62 @@ s = Glean(debug_logger=logging.getLogger("glean.api_client"))
 You can also enable a default debug logger by setting an environment variable `GLEAN_DEBUG` to true.
 <!-- End Debugging [debug] -->
 
+## Experimental Features and Deprecation Testing
+
+The SDK provides options to test upcoming API changes before they become the default behavior. This is useful for:
+
+- **Testing experimental features** before they are generally available
+- **Preparing for deprecations** by excluding deprecated endpoints ahead of their removal
+
+### Configuration Options
+
+You can configure these options either via environment variables or SDK constructor options:
+
+#### Using Environment Variables
+
+```python
+import os
+
+# Set environment variables before initializing the SDK
+os.environ["X_GLEAN_EXCLUDE_DEPRECATED_AFTER"] = "2026-10-15"
+os.environ["X_GLEAN_INCLUDE_EXPERIMENTAL"] = "true"
+
+from glean.api_client import Glean
+
+glean = Glean(
+    api_token=os.environ.get("GLEAN_API_TOKEN", ""),
+    instance=os.environ.get("GLEAN_INSTANCE", ""),
+)
+```
+
+#### Using SDK Constructor Options
+
+```python
+import os
+
+from glean.api_client import Glean
+
+glean = Glean(
+    api_token=os.environ.get("GLEAN_API_TOKEN", ""),
+    instance=os.environ.get("GLEAN_INSTANCE", ""),
+    exclude_deprecated_after="2026-10-15",
+    include_experimental=True,
+)
+```
+
+### Option Reference
+
+| Option | Environment Variable | Type | Description |
+| ------ | -------------------- | ---- | ----------- |
+| `exclude_deprecated_after` | `X_GLEAN_EXCLUDE_DEPRECATED_AFTER` | `str` (date) | Exclude API endpoints that will be deprecated after this date (format: `YYYY-MM-DD`). Use this to test your integration against upcoming deprecations. |
+| `include_experimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `bool` | When `True`, enables experimental API features that are not yet generally available. Use this to preview and test new functionality. |
+
+> [!NOTE]
+> Environment variables take precedence over SDK constructor options when both are set.
+
+> [!WARNING]
+> Experimental features may change or be removed without notice. Do not rely on experimental features in production environments.
+
 <!-- Placeholder for Future Speakeasy SDK Sections -->
 
 # Development

src/glean/api_client/_hooks/registration.py

@@ -1,6 +1,7 @@
 from .types import Hooks
 from .multipart_fix_hook import MultipartFileFieldFixHook
 from .agent_file_upload_error_hook import AgentFileUploadErrorHook
+from .x_glean import XGlean
 
 
 # This file is only ever generated once on the first generation and then is free to be modified.
@@ -19,3 +20,6 @@ def init_hooks(hooks: Hooks):
 
     # Register hook to provide helpful error messages for agent file upload issues
     hooks.register_after_error_hook(AgentFileUploadErrorHook())
+
+    # Register hook for X-Glean headers (experimental features and deprecation testing)
+    hooks.register_before_request_hook(XGlean())

src/glean/api_client/_hooks/x_glean.py

@@ -0,0 +1,80 @@
+"""Hook to set X-Glean headers for experimental features and deprecation testing."""
+
+import os
+from typing import Optional, Union
+import httpx
+from glean.api_client._hooks.types import BeforeRequestContext, BeforeRequestHook
+
+
+def _get_first_value(
+    env_value: Optional[str],
+    config_value: Optional[str],
+) -> Optional[str]:
+    """Get the first non-empty value from the provided arguments.
+
+    Environment variables take precedence over SDK constructor options.
+    """
+    if env_value:
+        return env_value
+    if config_value:
+        return config_value
+    return None
+
+
+class XGlean(BeforeRequestHook):
+    """
+    Hook that sets X-Glean headers for experimental features and deprecation testing.
+
+    This hook adds the following headers when configured:
+    - X-Glean-Exclude-Deprecated-After: Excludes API endpoints deprecated after this date
+    - X-Glean-Experimental: Enables experimental API features
+
+    Configuration can be done via environment variables or SDK constructor options.
+    Environment variables take precedence over SDK constructor options.
+    """
+
+    def before_request(
+        self, hook_ctx: BeforeRequestContext, request: httpx.Request
+    ) -> Union[httpx.Request, Exception]:
+        """
+        Add X-Glean headers to the request based on configuration.
+
+        Args:
+            hook_ctx: Context containing SDK configuration
+            request: The HTTP request being made
+
+        Returns:
+            The modified request with X-Glean headers added
+        """
+        # Get deprecated value - env var takes precedence
+        deprecated_value = _get_first_value(
+            os.environ.get("X_GLEAN_EXCLUDE_DEPRECATED_AFTER"),
+            hook_ctx.config.exclude_deprecated_after,
+        )
+
+        # Get experimental value - env var takes precedence
+        config_experimental = (
+            "true" if hook_ctx.config.include_experimental is True else None
+        )
+        experimental_value = _get_first_value(
+            os.environ.get("X_GLEAN_INCLUDE_EXPERIMENTAL"),
+            config_experimental,
+        )
+
+        # Create new headers dict with existing headers
+        new_headers = dict(request.headers)
+
+        if deprecated_value:
+            new_headers["X-Glean-Exclude-Deprecated-After"] = deprecated_value
+
+        if experimental_value:
+            new_headers["X-Glean-Experimental"] = experimental_value
+
+        # Return new request with updated headers
+        return httpx.Request(
+            method=request.method,
+            url=request.url,
+            headers=new_headers,
+            content=request.content,
+            extensions=request.extensions,
+        )

src/glean/api_client/sdk.py

@@ -61,6 +61,8 @@ def __init__(
         retry_config: OptionalNullable[RetryConfig] = UNSET,
         timeout_ms: Optional[int] = None,
         debug_logger: Optional[Logger] = None,
+        exclude_deprecated_after: Optional[str] = None,
+        include_experimental: Optional[bool] = None,
     ) -> None:
         r"""Instantiates the SDK configuring it with the provided parameters.
 
@@ -73,6 +75,8 @@ def __init__(
         :param async_client: The Async HTTP client to use for all asynchronous methods
         :param retry_config: The retry configuration to use for all supported methods
         :param timeout_ms: Optional request timeout applied to each operation in milliseconds
+        :param exclude_deprecated_after: Exclude API endpoints deprecated after this date (YYYY-MM-DD)
+        :param include_experimental: When True, enables experimental API features
         """
         client_supplied = True
         if client is None:
@@ -125,6 +129,8 @@ def __init__(
                 retry_config=retry_config,
                 timeout_ms=timeout_ms,
                 debug_logger=debug_logger,
+                exclude_deprecated_after=exclude_deprecated_after,
+                include_experimental=include_experimental,
             ),
             parent_ref=self,
         )

src/glean/api_client/sdkconfiguration.py

@@ -39,6 +39,19 @@ class SDKConfiguration:
     user_agent: str = __user_agent__
     retry_config: OptionalNullable[RetryConfig] = Field(default_factory=lambda: UNSET)
     timeout_ms: Optional[int] = None
+    exclude_deprecated_after: Optional[str] = None
+    """
+    Exclude API endpoints that will be deprecated after this date.
+    Use this to test your integration against upcoming deprecations.
+    Format: YYYY-MM-DD (e.g., '2026-10-15')
+
+    More information: https://developers.glean.com/deprecations/overview
+    """
+    include_experimental: Optional[bool] = None
+    """
+    When True, enables experimental API features that are not yet generally available.
+    Use this to preview and test new functionality.
+    """
 
     def get_server_details(self) -> Tuple[str, Dict[str, str]]:
         if self.server_url is not None and self.server_url: