Add attribution headers to outbound API requests

Inject X-Title header on all provider requests when telemetry is
enabled, and add OpenRouter-specific attribution headers (HTTP-Referer,
X-OpenRouter-Title, X-OpenRouter-Categories) to the predefined
OpenRouter provider entry.

- Add ATTRIBUTION_TITLE, ATTRIBUTION_REFERER, and
  OPENROUTER_ATTRIBUTION_HEADERS constants
- Add extra_headers to the OpenRouter predefined provider
- Inject X-Title in ModelFacade.consolidate_kwargs() gated on
  TELEMETRY_ENABLED, with user/provider headers taking precedence
- Update and extend tests for both config and engine packages

Fixes #519

Signed-off-by: Eric W. Tramel <eric.tramel@gmail.com>

Author: eric-tramel

packages/data-designer-config/src/data_designer/config/utils/constants.py

@@ -298,6 +298,15 @@ class NordColor(Enum):
 
 OPENROUTER_API_KEY_ENV_VAR_NAME = "OPENROUTER_API_KEY"
 
+ATTRIBUTION_TITLE = "NeMo Data Designer"
+ATTRIBUTION_REFERER = "https://github.com/NVIDIA-NeMo/DataDesigner"
+
+OPENROUTER_ATTRIBUTION_HEADERS: dict[str, str] = {
+    "HTTP-Referer": ATTRIBUTION_REFERER,
+    "X-OpenRouter-Title": ATTRIBUTION_TITLE,
+    "X-OpenRouter-Categories": "programming-app",
+}
+
 PREDEFINED_PROVIDERS = [
     {
         "name": NVIDIA_PROVIDER_NAME,
@@ -316,6 +325,7 @@ class NordColor(Enum):
         "endpoint": "https://openrouter.ai/api/v1",
         "provider_type": "openai",
         "api_key": OPENROUTER_API_KEY_ENV_VAR_NAME,
+        "extra_headers": OPENROUTER_ATTRIBUTION_HEADERS,
     },
 ]
 

packages/data-designer-config/tests/config/test_default_model_settings.py

@@ -100,14 +100,21 @@ def test_get_builtin_model_providers():
     assert builtin_model_providers[0].endpoint == "https://integrate.api.nvidia.com/v1"
     assert builtin_model_providers[0].provider_type == "openai"
     assert builtin_model_providers[0].api_key == "NVIDIA_API_KEY"
+    assert builtin_model_providers[0].extra_headers is None
     assert builtin_model_providers[1].name == "openai"
     assert builtin_model_providers[1].endpoint == "https://api.openai.com/v1"
     assert builtin_model_providers[1].provider_type == "openai"
     assert builtin_model_providers[1].api_key == "OPENAI_API_KEY"
+    assert builtin_model_providers[1].extra_headers is None
     assert builtin_model_providers[2].name == "openrouter"
     assert builtin_model_providers[2].endpoint == "https://openrouter.ai/api/v1"
     assert builtin_model_providers[2].provider_type == "openai"
     assert builtin_model_providers[2].api_key == "OPENROUTER_API_KEY"
+    assert builtin_model_providers[2].extra_headers == {
+        "HTTP-Referer": "https://github.com/NVIDIA-NeMo/DataDesigner",
+        "X-OpenRouter-Title": "NeMo Data Designer",
+        "X-OpenRouter-Categories": "programming-app",
+    }
 
 
 def test_get_default_model_configs_path_exists(tmp_path: Path):

packages/data-designer-engine/src/data_designer/engine/models/facade.py

@@ -10,6 +10,7 @@
 from typing import TYPE_CHECKING, Any
 
 from data_designer.config.models import GenerationType, ModelConfig, ModelProvider
+from data_designer.config.utils.constants import ATTRIBUTION_TITLE
 from data_designer.config.utils.image_helpers import is_image_diffusion_model
 from data_designer.engine.mcp.errors import MCPConfigurationError
 from data_designer.engine.model_provider import ModelProviderRegistry
@@ -30,6 +31,7 @@
     get_exception_primary_cause,
 )
 from data_designer.engine.models.parsers.errors import ParserException
+from data_designer.engine.models.telemetry import TELEMETRY_ENABLED
 from data_designer.engine.models.usage import ImageUsageStats, ModelUsageStats, RequestUsageStats, TokenUsageStats
 from data_designer.engine.models.utils import ChatMessage, prompt_to_messages
 
@@ -157,6 +159,12 @@ def consolidate_kwargs(self, **kwargs: Any) -> dict[str, Any]:
             kwargs["extra_body"] = {**kwargs.get("extra_body", {}), **self.model_provider.extra_body}
         if self.model_provider.extra_headers:
             kwargs["extra_headers"] = {**kwargs.get("extra_headers", {}), **self.model_provider.extra_headers}
+        # Inject framework-level attribution header when telemetry is enabled.
+        # Applied last so that user-supplied or provider-level headers take precedence.
+        if TELEMETRY_ENABLED:
+            headers = kwargs.get("extra_headers", {})
+            if "X-Title" not in headers:
+                kwargs["extra_headers"] = {"X-Title": ATTRIBUTION_TITLE, **headers}
         return kwargs
 
     # --- completion / acompletion ---

packages/data-designer-engine/tests/engine/models/test_facade.py

@@ -202,20 +202,29 @@ def test_usage_stats_property(stub_model_facade: ModelFacade) -> None:
 
 
 def test_consolidate_kwargs(stub_model_configs: list[Any], stub_model_facade: ModelFacade) -> None:
-    # Model config generate kwargs are used as base, and purpose is removed
+    # Model config generate kwargs are used as base, and purpose is removed.
+    # When telemetry is enabled (default), X-Title is injected.
     result = stub_model_facade.consolidate_kwargs(purpose="test")
-    assert result == stub_model_configs[0].inference_parameters.generate_kwargs
+    assert result == {
+        **stub_model_configs[0].inference_parameters.generate_kwargs,
+        "extra_headers": {"X-Title": "NeMo Data Designer"},
+    }
 
     # kwargs overrides model config generate kwargs
     result = stub_model_facade.consolidate_kwargs(temperature=0.01, purpose="test")
-    assert result == {**stub_model_configs[0].inference_parameters.generate_kwargs, "temperature": 0.01}
+    assert result == {
+        **stub_model_configs[0].inference_parameters.generate_kwargs,
+        "temperature": 0.01,
+        "extra_headers": {"X-Title": "NeMo Data Designer"},
+    }
 
     # Provider extra_body overrides all other kwargs
     stub_model_facade.model_provider.extra_body = {"foo_provider": "bar_provider"}
     result = stub_model_facade.consolidate_kwargs(extra_body={"foo": "bar"}, purpose="test")
     assert result == {
         **stub_model_configs[0].inference_parameters.generate_kwargs,
         "extra_body": {"foo_provider": "bar_provider", "foo": "bar"},
+        "extra_headers": {"X-Title": "NeMo Data Designer"},
     }
 
     # Provider extra_headers merges with caller headers (provider takes precedence)
@@ -224,10 +233,31 @@ def test_consolidate_kwargs(stub_model_configs: list[Any], stub_model_facade: Mo
     result = stub_model_facade.consolidate_kwargs(extra_headers={"hello": "caller", "X-Trace-ID": "abc"})
     assert result == {
         **stub_model_configs[0].inference_parameters.generate_kwargs,
-        "extra_headers": {"hello": "world", "hola": "mundo", "X-Trace-ID": "abc"},
+        "extra_headers": {"X-Title": "NeMo Data Designer", "hello": "world", "hola": "mundo", "X-Trace-ID": "abc"},
     }
 
 
+@patch("data_designer.engine.models.facade.TELEMETRY_ENABLED", False)
+def test_consolidate_kwargs_telemetry_disabled(stub_model_configs: list[Any], stub_model_facade: ModelFacade) -> None:
+    """Framework attribution headers are omitted when telemetry is disabled."""
+    result = stub_model_facade.consolidate_kwargs()
+    assert "extra_headers" not in result
+
+    # Provider extra_headers still applied even with telemetry off
+    stub_model_facade.model_provider.extra_headers = {"Custom": "header"}
+    result = stub_model_facade.consolidate_kwargs()
+    assert result["extra_headers"] == {"Custom": "header"}
+
+
+def test_consolidate_kwargs_user_x_title_override(
+    stub_model_configs: list[Any], stub_model_facade: ModelFacade
+) -> None:
+    """User-supplied X-Title via provider extra_headers takes precedence over framework default."""
+    stub_model_facade.model_provider.extra_headers = {"X-Title": "My Custom App"}
+    result = stub_model_facade.consolidate_kwargs()
+    assert result["extra_headers"]["X-Title"] == "My Custom App"
+
+
 @pytest.mark.parametrize(
     "skip_usage_tracking",
     [