feat!: Move graph_key to AIConfigTracker instantiation

graph_key is now set once at tracker construction time rather than
passed as an optional parameter to every tracking method. When
agent_graph() builds nodes it uses the internal __evaluate_agent()
path so each node tracker is born with graph_key set to the parent
graph's key. Public tracking methods no longer accept graph_key.

BREAKING CHANGE: The graph_key parameter has been removed from all
LDAIConfigTracker tracking methods (track_duration, track_success,
track_error, track_tokens, track_tool_call, track_tool_calls,
track_feedback, track_eval_scores, track_judge_response,
track_time_to_first_token, track_metrics_of, track_metrics_of_async).
Pass graph_key to the LDAIConfigTracker constructor instead.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jsonbailey

packages/sdk/server-ai/src/ldai/client.py

@@ -606,9 +606,10 @@ def agent_graph(
             for single_edge in variation.get("edges", {}).get(edge_key, []):
                 all_agent_keys.add(single_edge.get("key", ""))
 
+        graph_key_value = key
         agent_configs = {
-            key: self.agent_config(key, context, AIAgentConfigDefault(enabled=False))
-            for key in all_agent_keys
+            agent_key: self.__evaluate_agent(agent_key, context, AIAgentConfigDefault(enabled=False), graph_key=graph_key_value)
+            for agent_key in all_agent_keys
         }
 
         if not all(config.enabled for config in agent_configs.values()):
@@ -748,6 +749,7 @@ def __evaluate(
         context: Context,
         default_dict: Dict[str, Any],
         variables: Optional[Dict[str, Any]] = None,
+        graph_key: Optional[str] = None,
     ) -> Tuple[
         Optional[ModelConfig], Optional[ProviderConfig], Optional[List[LDMessage]],
         Optional[str], LDAIConfigTracker, bool, Optional[Any], Dict[str, Any]
@@ -759,6 +761,7 @@ def __evaluate(
         :param context: The evaluation context.
         :param default_dict: Default configuration as dictionary.
         :param variables: Variables for interpolation.
+        :param graph_key: When set, passed to the tracker so all events include ``graphKey``.
         :return: Tuple of (model, provider, messages, instructions, tracker, enabled, judge_configuration, variation).
         """
         variation = self._client.variation(key, context, default_dict)
@@ -809,6 +812,7 @@ def __evaluate(
             model.name if model else '',
             provider_config.name if provider_config else '',
             context,
+            graph_key=graph_key,
         )
 
         enabled = variation.get('_ldMeta', {}).get('enabled', False)
@@ -836,6 +840,7 @@ def __evaluate_agent(
         context: Context,
         default: AIAgentConfigDefault,
         variables: Optional[Dict[str, Any]] = None,
+        graph_key: Optional[str] = None,
     ) -> AIAgentConfig:
         """
         Internal method to evaluate an agent configuration.
@@ -844,10 +849,11 @@ def __evaluate_agent(
         :param context: The evaluation context.
         :param default: Default agent values.
         :param variables: Variables for interpolation.
+        :param graph_key: When set, passed to the tracker so all events include ``graphKey``.
         :return: Configured AIAgentConfig instance.
         """
         model, provider, messages, instructions, tracker, enabled, judge_configuration, _ = self.__evaluate(
-            key, context, default.to_dict(), variables
+            key, context, default.to_dict(), variables, graph_key=graph_key
         )
 
         # For agents, prioritize instructions over messages

packages/sdk/server-ai/src/ldai/tracker.py

@@ -77,6 +77,7 @@ def __init__(
         model_name: str,
         provider_name: str,
         context: Context,
+        graph_key: Optional[str] = None,
     ):
         """
         Initialize an AI Config tracker.
@@ -88,6 +89,8 @@ def __init__(
         :param model_name: Name of the model used.
         :param provider_name: Name of the provider used.
         :param context: Context for evaluation.
+        :param graph_key: When set, include ``graphKey`` in all event payloads
+            (e.g. config-level metrics inside a graph).
         """
         self._ld_client = ld_client
         self._variation_key = variation_key
@@ -96,13 +99,13 @@ def __init__(
         self._model_name = model_name
         self._provider_name = provider_name
         self._context = context
+        self._graph_key = graph_key
         self._summary = LDAIMetricSummary()
 
-    def __get_track_data(self, graph_key: Optional[str] = None) -> dict:
+    def __get_track_data(self) -> dict:
         """
         Get tracking data for events.
 
-        :param graph_key: When set, include ``graphKey`` in the payload.
         :return: Dictionary containing variation and config keys.
         """
         data = {
@@ -112,82 +115,72 @@ def __get_track_data(self, graph_key: Optional[str] = None) -> dict:
             "modelName": self._model_name,
             "providerName": self._provider_name,
         }
-        if graph_key is not None:
-            data['graphKey'] = graph_key
+        if self._graph_key is not None:
+            data['graphKey'] = self._graph_key
         return data
 
-    def track_duration(self, duration: int, *, graph_key: Optional[str] = None) -> None:
+    def track_duration(self, duration: int) -> None:
         """
         Manually track the duration of an AI operation.
 
         :param duration: Duration in milliseconds.
-        :param graph_key: When set, include ``graphKey`` in the event payload
-            (e.g. config-level metrics inside a graph).
         """
         self._summary._duration = duration
         self._ld_client.track(
-            "$ld:ai:duration:total", self._context, self.__get_track_data(graph_key), duration
+            "$ld:ai:duration:total", self._context, self.__get_track_data(), duration
         )
 
-    def track_time_to_first_token(
-        self, time_to_first_token: int, *, graph_key: Optional[str] = None
-    ) -> None:
+    def track_time_to_first_token(self, time_to_first_token: int) -> None:
         """
         Manually track the time to first token of an AI operation.
 
         :param time_to_first_token: Time to first token in milliseconds.
-        :param graph_key: When set, include ``graphKey`` in the event payload.
         """
         self._summary._time_to_first_token = time_to_first_token
         self._ld_client.track(
             "$ld:ai:tokens:ttf",
             self._context,
-            self.__get_track_data(graph_key),
+            self.__get_track_data(),
             time_to_first_token,
         )
 
-    def track_duration_of(self, func, *, graph_key: Optional[str] = None):
+    def track_duration_of(self, func):
         """
         Automatically track the duration of an AI operation.
 
         An exception occurring during the execution of the function will still
         track the duration. The exception will be re-thrown.
 
         :param func: Function to track (synchronous only).
-        :param graph_key: When set, passed through to :meth:`track_duration`.
         :return: Result of the tracked function.
         """
         start_ns = time.perf_counter_ns()
         try:
             result = func()
         finally:
             duration = (time.perf_counter_ns() - start_ns) // 1_000_000  # duration in milliseconds
-            self.track_duration(duration, graph_key=graph_key)
+            self.track_duration(duration)
 
         return result
 
     def _track_from_metrics_extractor(
         self,
         result: Any,
         metrics_extractor: Callable[[Any], Any],
-        *,
-        graph_key: Optional[str] = None,
     ) -> Any:
         metrics = metrics_extractor(result)
         if metrics.success:
-            self.track_success(graph_key=graph_key)
+            self.track_success()
         else:
-            self.track_error(graph_key=graph_key)
+            self.track_error()
         if metrics.usage:
-            self.track_tokens(metrics.usage, graph_key=graph_key)
+            self.track_tokens(metrics.usage)
         return result
 
     def track_metrics_of(
         self,
         func: Callable[[], Any],
         metrics_extractor: Callable[[Any], Any],
-        *,
-        graph_key: Optional[str] = None,
     ) -> Any:
         """
         Track metrics for a synchronous AI operation.
@@ -203,33 +196,29 @@ def track_metrics_of(
 
         :param func: Synchronous callable that runs the operation
         :param metrics_extractor: Function that extracts LDAIMetrics from the operation result
-        :param graph_key: When set, include ``graphKey`` on emitted config-level events.
         :return: The result of the operation
         """
         start_ns = time.perf_counter_ns()
         try:
             result = func()
         except Exception as err:
             duration = (time.perf_counter_ns() - start_ns) // 1_000_000
-            self.track_duration(duration, graph_key=graph_key)
-            self.track_error(graph_key=graph_key)
+            self.track_duration(duration)
+            self.track_error()
             raise err
 
         duration = (time.perf_counter_ns() - start_ns) // 1_000_000
-        self.track_duration(duration, graph_key=graph_key)
-        return self._track_from_metrics_extractor(result, metrics_extractor, graph_key=graph_key)
+        self.track_duration(duration)
+        return self._track_from_metrics_extractor(result, metrics_extractor)
 
-    async def track_metrics_of_async(
-        self, func, metrics_extractor, *, graph_key: Optional[str] = None
-    ):
+    async def track_metrics_of_async(self, func, metrics_extractor):
         """
         Track metrics for an async AI operation (``func`` is awaited).
 
         Same event semantics as :meth:`track_metrics_of`.
 
         :param func: Async callable or zero-arg callable that returns an awaitable when called
         :param metrics_extractor: Function that extracts LDAIMetrics from the operation result
-        :param graph_key: When set, include ``graphKey`` on emitted config-level events.
         :return: The result of the operation
         """
         start_ns = time.perf_counter_ns()
@@ -238,20 +227,19 @@ async def track_metrics_of_async(
             result = await func()
         except Exception as err:
             duration = (time.perf_counter_ns() - start_ns) // 1_000_000
-            self.track_duration(duration, graph_key=graph_key)
-            self.track_error(graph_key=graph_key)
+            self.track_duration(duration)
+            self.track_error()
             raise err
 
         duration = (time.perf_counter_ns() - start_ns) // 1_000_000
-        self.track_duration(duration, graph_key=graph_key)
-        return self._track_from_metrics_extractor(result, metrics_extractor, graph_key=graph_key)
+        self.track_duration(duration)
+        return self._track_from_metrics_extractor(result, metrics_extractor)
 
-    def track_eval_scores(self, scores: Dict[str, Any], *, graph_key: Optional[str] = None) -> None:
+    def track_eval_scores(self, scores: Dict[str, Any]) -> None:
         """
         Track evaluation scores for multiple metrics.
 
         :param scores: Dictionary mapping metric keys to their evaluation scores (EvalScore objects)
-        :param graph_key: When set, include ``graphKey`` in the event payload.
         """
         from ldai.providers.types import EvalScore
 
@@ -261,23 +249,22 @@ def track_eval_scores(self, scores: Dict[str, Any], *, graph_key: Optional[str]
                 self._ld_client.track(
                     metric_key,
                     self._context,
-                    self.__get_track_data(graph_key=graph_key),
+                    self.__get_track_data(),
                     eval_score.score
                 )
 
-    def track_judge_response(self, judge_response: Any, *, graph_key: Optional[str] = None) -> None:
+    def track_judge_response(self, judge_response: Any) -> None:
         """
         Track a judge response, including evaluation scores with judge config key.
 
         :param judge_response: JudgeResponse object containing evals and success status
-        :param graph_key: When set, include ``graphKey`` in the event payload.
         """
         from ldai.providers.types import EvalScore, JudgeResponse
 
         if isinstance(judge_response, JudgeResponse):
             # Track evaluation scores with judge config key included in metadata
             if judge_response.evals:
-                track_data = self.__get_track_data(graph_key=graph_key)
+                track_data = self.__get_track_data()
                 if judge_response.judge_config_key:
                     track_data = {**track_data, 'judgeConfigKey': judge_response.judge_config_key}
 
@@ -290,49 +277,44 @@ def track_judge_response(self, judge_response: Any, *, graph_key: Optional[str]
                             eval_score.score
                         )
 
-    def track_feedback(self, feedback: Dict[str, FeedbackKind], *, graph_key: Optional[str] = None) -> None:
+    def track_feedback(self, feedback: Dict[str, FeedbackKind]) -> None:
         """
         Track user feedback for an AI operation.
 
         :param feedback: Dictionary containing feedback kind.
-        :param graph_key: When set, include ``graphKey`` in the event payload.
         """
         self._summary._feedback = feedback
         if feedback["kind"] == FeedbackKind.Positive:
             self._ld_client.track(
                 "$ld:ai:feedback:user:positive",
                 self._context,
-                self.__get_track_data(graph_key=graph_key),
+                self.__get_track_data(),
                 1,
             )
         elif feedback["kind"] == FeedbackKind.Negative:
             self._ld_client.track(
                 "$ld:ai:feedback:user:negative",
                 self._context,
-                self.__get_track_data(graph_key=graph_key),
+                self.__get_track_data(),
                 1,
             )
 
-    def track_success(self, *, graph_key: Optional[str] = None) -> None:
+    def track_success(self) -> None:
         """
         Track a successful AI generation.
-
-        :param graph_key: When set, include ``graphKey`` in the event payload.
         """
         self._summary._success = True
         self._ld_client.track(
-            "$ld:ai:generation:success", self._context, self.__get_track_data(graph_key=graph_key), 1
+            "$ld:ai:generation:success", self._context, self.__get_track_data(), 1
         )
 
-    def track_error(self, *, graph_key: Optional[str] = None) -> None:
+    def track_error(self) -> None:
         """
         Track an unsuccessful AI generation attempt.
-
-        :param graph_key: When set, include ``graphKey`` in the event payload.
         """
         self._summary._success = False
         self._ld_client.track(
-            "$ld:ai:generation:error", self._context, self.__get_track_data(graph_key=graph_key), 1
+            "$ld:ai:generation:error", self._context, self.__get_track_data(), 1
         )
 
     def track_openai_metrics(self, func):
@@ -390,15 +372,14 @@ def track_bedrock_converse_metrics(self, res: dict) -> dict:
             self.track_tokens(_bedrock_to_token_usage(res["usage"]))
         return res
 
-    def track_tokens(self, tokens: TokenUsage, *, graph_key: Optional[str] = None) -> None:
+    def track_tokens(self, tokens: TokenUsage) -> None:
         """
         Track token usage metrics.
 
         :param tokens: Token usage data from either custom, OpenAI, or Bedrock sources.
-        :param graph_key: When set, include ``graphKey`` in the event payload.
         """
         self._summary._usage = tokens
-        td = self.__get_track_data(graph_key=graph_key)
+        td = self.__get_track_data()
         if tokens.total > 0:
             self._ld_client.track(
                 "$ld:ai:tokens:total",
@@ -421,32 +402,28 @@ def track_tokens(self, tokens: TokenUsage, *, graph_key: Optional[str] = None) -
                 tokens.output,
             )
 
-    def track_tool_call(self, tool_key: str, *, graph_key: Optional[str] = None) -> None:
+    def track_tool_call(self, tool_key: str) -> None:
         """
         Track a tool invocation for this configuration (standalone or within a graph).
 
         :param tool_key: Identifier of the tool that was invoked.
-        :param graph_key: When set, include ``graphKey`` in the event payload.
         """
-        track_data = {**self.__get_track_data(graph_key=graph_key), "toolKey": tool_key}
+        track_data = {**self.__get_track_data(), "toolKey": tool_key}
         self._ld_client.track(
             "$ld:ai:tool_call",
             self._context,
             track_data,
             1,
         )
 
-    def track_tool_calls(
-        self, tool_keys: Iterable[str], *, graph_key: Optional[str] = None
-    ) -> None:
+    def track_tool_calls(self, tool_keys: Iterable[str]) -> None:
         """
         Track multiple tool invocations for this configuration.
 
         :param tool_keys: Tool identifiers (e.g. from a model response).
-        :param graph_key: When set, include ``graphKey`` on each event.
         """
         for tool_key in tool_keys:
-            self.track_tool_call(tool_key, graph_key=graph_key)
+            self.track_tool_call(tool_key)
 
     def get_summary(self) -> LDAIMetricSummary:
         """