feat!: Return Result from from_resumption_token instead of raising

from_resumption_token and LDAIClient.create_tracker now return
ldclient.Result instead of raising ValueError on invalid tokens,
letting callers handle errors without try/except.

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

Author: jsonbailey

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

@@ -2,7 +2,7 @@
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 import chevron
-from ldclient import Context
+from ldclient import Context, Result
 from ldclient.client import LDClient
 
 from ldai import log
@@ -62,7 +62,7 @@ def __init__(self, client: LDClient):
             1,
         )
 
-    def create_tracker(self, token: str, context: Context) -> LDAIConfigTracker:
+    def create_tracker(self, token: str, context: Context) -> Result:
         """
         Reconstruct a tracker from a resumption token.
 
@@ -71,9 +71,9 @@ def create_tracker(self, token: str, context: Context) -> LDAIConfigTracker:
         :param token: A URL-safe Base64-encoded resumption token obtained from
             :attr:`LDAIConfigTracker.resumption_token`.
         :param context: The context to use for track events.
-        :return: A new :class:`LDAIConfigTracker` bound to the original
-            ``runId`` from the token.
-        :raises ValueError: If the token is invalid or missing required fields.
+        :return: A :class:`Result` whose ``value`` is a new
+            :class:`LDAIConfigTracker` on success, or whose ``error`` describes
+            the problem on failure.
         """
         return LDAIConfigTracker.from_resumption_token(token, self._client, context)
 

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

@@ -5,7 +5,7 @@
 from enum import Enum
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
-from ldclient import Context, LDClient
+from ldclient import Context, LDClient, Result
 
 from ldai import log
 
@@ -132,7 +132,7 @@ def resumption_token(self) -> str:
         return base64.urlsafe_b64encode(payload.encode("utf-8")).rstrip(b"=").decode("utf-8")
 
     @classmethod
-    def from_resumption_token(cls, token: str, ld_client: LDClient, context: Context) -> 'LDAIConfigTracker':
+    def from_resumption_token(cls, token: str, ld_client: LDClient, context: Context) -> Result:
         """
         Reconstruct a tracker from a resumption token.
 
@@ -144,25 +144,25 @@ def from_resumption_token(cls, token: str, ld_client: LDClient, context: Context
             :attr:`resumption_token`.
         :param ld_client: LaunchDarkly client instance.
         :param context: The context to use for track events.
-        :return: A new :class:`LDAIConfigTracker` bound to the original
-            ``runId`` from the token.
-        :raises ValueError: If the token is invalid or missing required fields.
+        :return: A :class:`Result` whose ``value`` is a new
+            :class:`LDAIConfigTracker` bound to the original ``runId`` from the
+            token on success, or whose ``error`` describes the problem on failure.
         """
         try:
             padded = token + "=" * (-len(token) % 4)
             payload = json.loads(
                 base64.urlsafe_b64decode(padded.encode("utf-8")).decode("utf-8")
             )
         except (json.JSONDecodeError, Exception) as e:
-            raise ValueError(f"Invalid resumption token: {e}") from e
+            return Result.fail(f"Invalid resumption token: {e}", e)
 
         for field in ("runId", "configKey", "version"):
             if field not in payload:
-                raise ValueError(
+                return Result.fail(
                     f"Invalid resumption token: missing required field '{field}'"
                 )
 
-        return cls(
+        return Result.success(cls(
             ld_client=ld_client,
             run_id=payload["runId"],
             config_key=payload["configKey"],
@@ -172,7 +172,7 @@ def from_resumption_token(cls, token: str, ld_client: LDClient, context: Context
             model_name="",
             provider_name="",
             graph_key=payload.get("graphKey"),
-        )
+        ))
 
     def __get_track_data(self) -> dict:
         """

packages/sdk/server-ai/tests/test_tracker.py

@@ -788,7 +788,9 @@ def test_resumption_token_round_trip_with_graph_key(client: LDClient):
     )
 
     token = tracker.resumption_token
-    restored = LDAIConfigTracker.from_resumption_token(token, client, context)
+    result = LDAIConfigTracker.from_resumption_token(token, client, context)
+    assert result.is_success()
+    restored = result.value
 
     assert restored._run_id == "test-run-id"
     assert restored._config_key == "cfg-key"
@@ -829,7 +831,9 @@ def test_client_create_tracker_from_resumption_token():
     token = original.resumption_token
 
     # Reconstruct from token
-    restored = ai_client.create_tracker(token, context)
+    result = ai_client.create_tracker(token, context)
+    assert result.is_success()
+    restored = result.value
 
     # The restored tracker should use the same runId
     restored.track_feedback({"kind": FeedbackKind.Positive})
@@ -851,7 +855,7 @@ def test_client_create_tracker_from_resumption_token():
     assert feedback_calls[0].args[1] == context
 
 
-def test_client_create_tracker_raises_on_invalid_base64():
+def test_client_create_tracker_fails_on_invalid_base64():
     from unittest.mock import Mock
 
     from ldai.client import LDAIClient
@@ -860,11 +864,12 @@ def test_client_create_tracker_raises_on_invalid_base64():
     ai_client = LDAIClient(mock_client)
     context = Context.create("user-key")
 
-    with pytest.raises(ValueError, match="Invalid resumption token"):
-        ai_client.create_tracker("not-valid-base64!!!", context)
+    result = ai_client.create_tracker("not-valid-base64!!!", context)
+    assert not result.is_success()
+    assert "Invalid resumption token" in result.error
 
 
-def test_client_create_tracker_raises_on_missing_fields():
+def test_client_create_tracker_fails_on_missing_fields():
     import base64
     import json
 
@@ -881,11 +886,12 @@ def test_client_create_tracker_raises_on_missing_fields():
         json.dumps({"configKey": "k", "version": 1}).encode()
     ).rstrip(b"=").decode()
 
-    with pytest.raises(ValueError, match="missing required field 'runId'"):
-        ai_client.create_tracker(incomplete, context)
+    result = ai_client.create_tracker(incomplete, context)
+    assert not result.is_success()
+    assert "missing required field 'runId'" in result.error
 
 
-def test_client_create_tracker_raises_on_invalid_json():
+def test_client_create_tracker_fails_on_invalid_json():
     import base64
 
     from unittest.mock import Mock
@@ -898,5 +904,6 @@ def test_client_create_tracker_raises_on_invalid_json():
 
     bad_token = base64.urlsafe_b64encode(b"not json").rstrip(b"=").decode()
 
-    with pytest.raises(ValueError, match="Invalid resumption token"):
-        ai_client.create_tracker(bad_token, context)
+    result = ai_client.create_tracker(bad_token, context)
+    assert not result.is_success()
+    assert "Invalid resumption token" in result.error