From a018c17c470d836b788857e56afab6e39dc9a786 Mon Sep 17 00:00:00 2001
From: jsonbailey <jbailey@launchdarkly.com>
Date: Mon, 27 Apr 2026 16:24:59 -0500
Subject: [PATCH] feat: add runtime DeprecationWarnings to deprecated methods

Deprecated methods previously only noted their status in docstrings or
via log.warning. They now emit warnings.warn(DeprecationWarning) so
callers are notified at runtime, consistent with the parent
launchdarkly-server-sdk pattern.

Methods deprecated in client.py: config(), create_chat(), agent(),
agents(). Method deprecated in tracker.py: track_openai_metrics().

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/sdk/server-ai/src/ldai/client.py    | 11 ++++++-----
 packages/sdk/server-ai/src/ldai/tracker.py   | 10 ++++++++++
 packages/sdk/server-ai/tests/test_tracker.py | 14 ++++++++------
 3 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/packages/sdk/server-ai/src/ldai/client.py b/packages/sdk/server-ai/src/ldai/client.py
index 4023574..75d4488 100644
--- a/packages/sdk/server-ai/src/ldai/client.py
+++ b/packages/sdk/server-ai/src/ldai/client.py
@@ -1,4 +1,5 @@
 import uuid
+import warnings
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 import chevron
@@ -169,6 +170,7 @@ def config(
         :param variables: Additional variables for the model configuration.
         :return: The value of the model configuration along with a tracker used for gathering metrics.
         """
+        warnings.warn("config() is deprecated, use completion_config() instead", DeprecationWarning, stacklevel=2)
         return self.completion_config(key, context, default, variables)
 
     def _judge_config(
@@ -417,12 +419,9 @@ async def create_chat(
         default_ai_provider: Optional[str] = None,
     ) -> Optional[ManagedModel]:
         """
-        .. deprecated:: Use :meth:`create_model` instead.
-
-        Creates and returns a ManagedModel for AI conversations.
-        This method is a deprecated alias for :meth:`create_model`.
+        .. deprecated:: Use :meth:`create_model` instead. This method will be removed in a future version.
         """
-        log.warning('create_chat() is deprecated, use create_model() instead')
+        warnings.warn("create_chat() is deprecated, use create_model() instead", DeprecationWarning, stacklevel=2)
         return await self.create_model(key, context, default, variables, default_ai_provider)
 
     async def create_agent(
@@ -545,6 +544,7 @@ def agent(
         :param context: The context to evaluate the agent configuration in.
         :return: Configured AIAgentConfig instance.
         """
+        warnings.warn("agent() is deprecated, use agent_config() instead", DeprecationWarning, stacklevel=2)
         return self.agent_config(config.key, context, config.default, config.variables)
 
     def agent_configs(
@@ -791,6 +791,7 @@ def agents(
         :param context: The context to evaluate the agent configurations in.
         :return: Dictionary mapping agent keys to their AIAgentConfig configurations.
         """
+        warnings.warn("agents() is deprecated, use agent_configs() instead", DeprecationWarning, stacklevel=2)
         return self.agent_configs(agent_configs, context)
 
     def __evaluate(
diff --git a/packages/sdk/server-ai/src/ldai/tracker.py b/packages/sdk/server-ai/src/ldai/tracker.py
index ed5d3e7..0f5a32c 100644
--- a/packages/sdk/server-ai/src/ldai/tracker.py
+++ b/packages/sdk/server-ai/src/ldai/tracker.py
@@ -1,6 +1,7 @@
 import base64
 import json
 import time
+import warnings
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Callable, Dict, Iterable, List, Optional
@@ -391,6 +392,9 @@ def track_openai_metrics(self, func):
         """
         Track OpenAI-specific operations.
 
+        .. deprecated:: Use :meth:`track_metrics_of` with ``get_ai_metrics_from_response``
+            from ``ldai_openai`` instead. This method will be removed in a future version.
+
         This function will track the duration of the operation, the token
         usage, and the success or error status.
 
@@ -404,6 +408,12 @@ def track_openai_metrics(self, func):
         :param func: Function to track.
         :return: Result of the tracked function.
         """
+        warnings.warn(
+            "track_openai_metrics is deprecated. Use track_metrics_of with "
+            "get_ai_metrics_from_response from ldai_openai instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         start_ns = time.perf_counter_ns()
         try:
             result = func()
diff --git a/packages/sdk/server-ai/tests/test_tracker.py b/packages/sdk/server-ai/tests/test_tracker.py
index 09f12f0..c2ae2dd 100644
--- a/packages/sdk/server-ai/tests/test_tracker.py
+++ b/packages/sdk/server-ai/tests/test_tracker.py
@@ -294,7 +294,8 @@ def to_dict(self):
     def get_result():
         return Result()
 
-    tracker.track_openai_metrics(get_result)
+    with pytest.warns(DeprecationWarning, match="track_openai_metrics is deprecated"):
+        tracker.track_openai_metrics(get_result)
 
     calls = [
         call(
@@ -335,11 +336,12 @@ def test_tracks_openai_metrics_with_exception(client: LDClient):
     def raise_exception():
         raise ValueError("Something went wrong")
 
-    try:
-        tracker.track_openai_metrics(raise_exception)
-        assert False, "Should have thrown an exception"
-    except ValueError:
-        pass
+    with pytest.warns(DeprecationWarning, match="track_openai_metrics is deprecated"):
+        try:
+            tracker.track_openai_metrics(raise_exception)
+            assert False, "Should have thrown an exception"
+        except ValueError:
+            pass
 
     calls = [
         call(