feat!: Add per-execution runId and at-most-once event tracking

- Each tracker now carries a runId (UUIDv4) included in all emitted
  events, scoping every metric to a single execution
- At-most-once semantics: duplicate calls to track_duration,
  track_tokens, track_success/track_error, track_feedback, and
  track_time_to_first_token on the same tracker are dropped with a
  warning

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

Author: jsonbailey

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

@@ -1,10 +1,14 @@
+import logging
 import time
+import uuid
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 from ldclient import Context, LDClient
 
+logger = logging.getLogger(__name__)
+
 
 class FeedbackKind(Enum):
     """
@@ -97,6 +101,8 @@ def __init__(
         self._provider_name = provider_name
         self._context = context
         self._summary = LDAIMetricSummary()
+        self._run_id = str(uuid.uuid4())
+        self._tracked: Dict[str, bool] = {}
 
     def __get_track_data(self, graph_key: Optional[str] = None) -> dict:
         """
@@ -106,6 +112,7 @@ def __get_track_data(self, graph_key: Optional[str] = None) -> dict:
         :return: Dictionary containing variation and config keys.
         """
         data = {
+            "runId": self._run_id,
             "variationKey": self._variation_key,
             "configKey": self._config_key,
             "version": self._version,
@@ -124,6 +131,10 @@ def track_duration(self, duration: int, *, graph_key: Optional[str] = None) -> N
         :param graph_key: When set, include ``graphKey`` in the event payload
             (e.g. config-level metrics inside a graph).
         """
+        if 'duration' in self._tracked:
+            logger.warning("Duration has already been tracked for this execution.")
+            return
+        self._tracked['duration'] = True
         self._summary._duration = duration
         self._ld_client.track(
             "$ld:ai:duration:total", self._context, self.__get_track_data(graph_key), duration
@@ -138,6 +149,10 @@ def track_time_to_first_token(
         :param time_to_first_token: Time to first token in milliseconds.
         :param graph_key: When set, include ``graphKey`` in the event payload.
         """
+        if 'time_to_first_token' in self._tracked:
+            logger.warning("Time to first token has already been tracked for this execution.")
+            return
+        self._tracked['time_to_first_token'] = True
         self._summary._time_to_first_token = time_to_first_token
         self._ld_client.track(
             "$ld:ai:tokens:ttf",
@@ -297,6 +312,10 @@ def track_feedback(self, feedback: Dict[str, FeedbackKind], *, graph_key: Option
         :param feedback: Dictionary containing feedback kind.
         :param graph_key: When set, include ``graphKey`` in the event payload.
         """
+        if 'feedback' in self._tracked:
+            logger.warning("Feedback has already been tracked for this execution.")
+            return
+        self._tracked['feedback'] = True
         self._summary._feedback = feedback
         if feedback["kind"] == FeedbackKind.Positive:
             self._ld_client.track(
@@ -319,6 +338,10 @@ def track_success(self, *, graph_key: Optional[str] = None) -> None:
 
         :param graph_key: When set, include ``graphKey`` in the event payload.
         """
+        if 'success' in self._tracked:
+            logger.warning("Success has already been tracked for this execution.")
+            return
+        self._tracked['success'] = True
         self._summary._success = True
         self._ld_client.track(
             "$ld:ai:generation:success", self._context, self.__get_track_data(graph_key=graph_key), 1
@@ -330,6 +353,10 @@ def track_error(self, *, graph_key: Optional[str] = None) -> None:
 
         :param graph_key: When set, include ``graphKey`` in the event payload.
         """
+        if 'success' in self._tracked:
+            logger.warning("Success has already been tracked for this execution.")
+            return
+        self._tracked['success'] = True
         self._summary._success = False
         self._ld_client.track(
             "$ld:ai:generation:error", self._context, self.__get_track_data(graph_key=graph_key), 1
@@ -397,6 +424,10 @@ def track_tokens(self, tokens: TokenUsage, *, graph_key: Optional[str] = None) -
         :param tokens: Token usage data from either custom, OpenAI, or Bedrock sources.
         :param graph_key: When set, include ``graphKey`` in the event payload.
         """
+        if 'tokens' in self._tracked:
+            logger.warning("Tokens have already been tracked for this execution.")
+            return
+        self._tracked['tokens'] = True
         self._summary._usage = tokens
         td = self.__get_track_data(graph_key=graph_key)
         if tokens.total > 0: