feat!: Rename LDAIMetrics.usage and AIGraphMetrics.usage to .tokens (#175)

## Summary

Standardizes on `tokens` as the field name for token usage across all AI
metric types, aligning with the canonical spec rename. Renames:

- `LDAIMetrics.usage` → `LDAIMetrics.tokens` (runner-level single-model
metrics)
- `AIGraphMetrics.usage` → `AIGraphMetrics.tokens` (runner-level graph
metrics)
- `LDAIMetricSummary.usage` → `LDAIMetricSummary.tokens` (managed-layer
single-model summary)
- `AIGraphMetricSummary.usage` → `AIGraphMetricSummary.tokens`
(managed-layer graph summary)

Updates the type definitions in `ldai/providers/types.py` and
`ldai/tracker.py`, all internal usages across the SDK (`tracker.py`,
`managed_agent_graph.py`) and provider packages (openai model + agent +
agent-graph runners; langchain model + agent + langgraph runners;
langgraph callback handler), tests, and README docstrings. The
`to_dict()` serialization key on `LDAIMetrics` also changes from `usage`
to `tokens`.

No backward-compat aliases are kept -- these types are part of the
in-progress unreleased SDK iteration after PR #173 (the prior rename
batch).

## Coordinated PRs

This is one of three coordinated PRs landing this rename together:

- **sdk-specs** (canonical name source):
launchdarkly/sdk-specs#163
- **python-server-sdk-ai** (this PR): targets `main`
- **js-core** (sibling impl):
launchdarkly/js-core#1366 (targets
`feat/next-ai-release`)

## Test plan

- [x] `make test` -- all 325 tests pass (server-ai 196, langchain 85,
openai 44)
- [x] `make lint` -- mypy, isort, pycodestyle all clean across all three
packages
- [ ] e2e validation via `hello-python-ai` chat-judge example (sibling
agent)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Broad breaking API rename from `usage` to `tokens` across SDK/provider
metric types and serialization, which will require downstream code
updates and could silently drop token tracking if any call sites were
missed.
> 
> **Overview**
> Standardizes token accounting field names by renaming **`usage` →
`tokens`** across core metric types (`LDAIMetrics`, `AIGraphMetrics`)
and their managed summaries, including `LDAIMetrics.to_dict()` now
emitting a `tokens` key.
> 
> Updates all affected runners (LangChain, LangGraph, OpenAI
models/agents/graphs), tracker integration (`track_tokens`, graph total
token tracking), docs, and tests to use the new `tokens` field with no
backward-compatible alias.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
ccdc00e. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jsonbailey

packages/ai-providers/server-ai-langchain/README.md

@@ -126,7 +126,7 @@ model = await ai_client.create_model("ai-config-key", context)
 if model:
     result = await model.run("Explain feature flags.")
     # Metrics are tracked automatically; access them via result.metrics
-    print(result.metrics.usage)
+    print(result.metrics.tokens)
 ```
 
 ### Static Utility Methods
@@ -155,7 +155,7 @@ from ldai_langchain.langchain_helper import get_ai_metrics_from_response
 # After getting a response from LangChain
 metrics = get_ai_metrics_from_response(ai_message)
 print(f"Success: {metrics.success}")
-print(f"Tokens used: {metrics.usage.total if metrics.usage else 'N/A'}")
+print(f"Tokens used: {metrics.tokens.total if metrics.tokens else 'N/A'}")
 ```
 
 #### Provider Name Mapping

packages/ai-providers/server-ai-langchain/src/ldai_langchain/langchain_agent_runner.py

@@ -59,7 +59,7 @@ async def run(
                 content=output,
                 metrics=LDAIMetrics(
                     success=True,
-                    usage=sum_token_usage_from_messages(messages),
+                    tokens=sum_token_usage_from_messages(messages),
                     tool_calls=tool_calls if tool_calls else None,
                 ),
                 raw=result,
@@ -68,7 +68,7 @@ async def run(
             log.warning(f"LangChain agent run failed: {error}")
             return RunnerResult(
                 content="",
-                metrics=LDAIMetrics(success=False, usage=None),
+                metrics=LDAIMetrics(success=False, tokens=None),
             )
 
     def get_agent(self) -> Any:

packages/ai-providers/server-ai-langchain/src/ldai_langchain/langchain_helper.py

@@ -217,7 +217,7 @@ def get_ai_metrics_from_response(response: Any) -> LDAIMetrics:
     :param response: The response from a LangChain model (BaseMessage or similar)
     :return: LDAIMetrics with success status and token usage
     """
-    return LDAIMetrics(success=True, usage=get_ai_usage_from_response(response))
+    return LDAIMetrics(success=True, tokens=get_ai_usage_from_response(response))
 
 
 def get_tool_calls_from_response(response: Any) -> List[str]:

packages/ai-providers/server-ai-langchain/src/ldai_langchain/langchain_model_runner.py

@@ -82,7 +82,7 @@ async def _run_completion(self, messages: List[BaseMessage]) -> RunnerResult:
                 )
                 return RunnerResult(
                     content='',
-                    metrics=LDAIMetrics(success=False, usage=metrics.usage),
+                    metrics=LDAIMetrics(success=False, tokens=metrics.tokens),
                     raw=response,
                 )
 
@@ -91,7 +91,7 @@ async def _run_completion(self, messages: List[BaseMessage]) -> RunnerResult:
             log.warning(f'LangChain model invocation failed: {error}')
             return RunnerResult(
                 content='',
-                metrics=LDAIMetrics(success=False, usage=None),
+                metrics=LDAIMetrics(success=False, tokens=None),
             )
 
     async def _run_structured(
@@ -107,11 +107,11 @@ async def _run_structured(
                 log.warning(f'Structured output did not return a dict. Got: {type(response)}')
                 return RunnerResult(
                     content='',
-                    metrics=LDAIMetrics(success=False, usage=None),
+                    metrics=LDAIMetrics(success=False, tokens=None),
                 )
 
             raw_response = response.get('raw')
-            usage = None
+            tokens = None
             raw_content = ''
             if raw_response is not None:
                 if hasattr(raw_response, 'content'):
@@ -122,26 +122,26 @@ async def _run_structured(
                             f'Multimodal response not supported in structured mode. '
                             f'Content type: {type(raw_response.content)}, Content: {raw_response.content}'
                         )
-                usage = get_ai_usage_from_response(raw_response)
+                tokens = get_ai_usage_from_response(raw_response)
 
             if response.get('parsing_error'):
                 log.warning('LangChain structured model invocation had a parsing error')
                 return RunnerResult(
                     content=raw_content,
-                    metrics=LDAIMetrics(success=False, usage=usage),
+                    metrics=LDAIMetrics(success=False, tokens=tokens),
                     raw=raw_response,
                 )
 
             parsed = response.get('parsed') or {}
             return RunnerResult(
                 content=raw_content,
-                metrics=LDAIMetrics(success=True, usage=usage),
+                metrics=LDAIMetrics(success=True, tokens=tokens),
                 raw=raw_response,
                 parsed=parsed,
             )
         except Exception as error:
             log.warning(f'LangChain structured model invocation failed: {error}')
             return RunnerResult(
                 content='',
-                metrics=LDAIMetrics(success=False, usage=None),
+                metrics=LDAIMetrics(success=False, tokens=None),
             )

packages/ai-providers/server-ai-langchain/src/ldai_langchain/langgraph_agent_graph_runner.py

@@ -313,7 +313,7 @@ async def run(self, input: Any) -> AgentGraphRunnerResult:
                     success=True,
                     path=handler.path,
                     duration_ms=duration_ms,
-                    usage=total_usage if (total_usage is not None and total_usage.total > 0) else None,
+                    tokens=total_usage if (total_usage is not None and total_usage.total > 0) else None,
                     node_metrics=node_metrics,
                 ),
             )

packages/ai-providers/server-ai-langchain/src/ldai_langchain/langgraph_callback_handler.py

@@ -142,11 +142,11 @@ def on_llm_end(
         metrics = self._node_metrics.get(node_key)
         if metrics is None:
             return
-        existing = metrics.usage
+        existing = metrics.tokens
         if existing is None:
-            metrics.usage = usage
+            metrics.tokens = usage
         else:
-            metrics.usage = TokenUsage(
+            metrics.tokens = TokenUsage(
                 total=existing.total + usage.total,
                 input=existing.input + usage.input,
                 output=existing.output + usage.output,

packages/ai-providers/server-ai-langchain/tests/test_langchain_provider.py

@@ -95,10 +95,10 @@ def test_creates_metrics_with_success_true_and_token_usage(self):
         result = get_ai_metrics_from_response(mock_response)
 
         assert result.success is True
-        assert result.usage is not None
-        assert result.usage.total == 100
-        assert result.usage.input == 50
-        assert result.usage.output == 50
+        assert result.tokens is not None
+        assert result.tokens.total == 100
+        assert result.tokens.input == 50
+        assert result.tokens.output == 50
 
     def test_creates_metrics_with_snake_case_token_usage(self):
         """Should create metrics with snake_case token usage keys."""
@@ -114,10 +114,10 @@ def test_creates_metrics_with_snake_case_token_usage(self):
         result = get_ai_metrics_from_response(mock_response)
 
         assert result.success is True
-        assert result.usage is not None
-        assert result.usage.total == 150
-        assert result.usage.input == 75
-        assert result.usage.output == 75
+        assert result.tokens is not None
+        assert result.tokens.total == 150
+        assert result.tokens.input == 75
+        assert result.tokens.output == 75
 
     def test_creates_metrics_with_success_true_and_no_usage_when_metadata_missing(self):
         """Should create metrics with success=True and no usage when metadata is missing."""
@@ -126,7 +126,7 @@ def test_creates_metrics_with_success_true_and_no_usage_when_metadata_missing(se
         result = get_ai_metrics_from_response(mock_response)
 
         assert result.success is True
-        assert result.usage is None
+        assert result.tokens is None
 
     def test_usage_metadata_preferred_over_response_metadata(self):
         """usage_metadata should be used when it has non-zero counts."""
@@ -355,7 +355,7 @@ async def test_returns_success_false_when_structured_model_invocation_throws_err
         assert result.metrics.success is False
         assert result.parsed is None
         assert result.raw is None
-        assert result.metrics.usage is None
+        assert result.metrics.tokens is None
 
 
 class TestGetToolCallsFromResponse:
@@ -546,10 +546,10 @@ async def test_aggregates_token_usage_across_messages(self):
 
         assert result.content == "final answer"
         assert result.metrics.success is True
-        assert result.metrics.usage is not None
-        assert result.metrics.usage.total == 30
-        assert result.metrics.usage.input == 18
-        assert result.metrics.usage.output == 12
+        assert result.metrics.tokens is not None
+        assert result.metrics.tokens.total == 30
+        assert result.metrics.tokens.input == 18
+        assert result.metrics.tokens.output == 12
 
     @pytest.mark.asyncio
     async def test_returns_failure_when_exception_thrown(self):

packages/ai-providers/server-ai-langchain/tests/test_langgraph_callback_handler.py

@@ -148,7 +148,7 @@ def test_on_llm_end_accumulates_tokens():
     result = _llm_result(total=15, prompt=10, completion=5)
     handler.on_llm_end(result, run_id=uuid4(), parent_run_id=node_run_id)
 
-    usage = handler.node_metrics['root-agent'].usage
+    usage = handler.node_metrics['root-agent'].tokens
     assert usage is not None
     assert usage.total == 15
     assert usage.input == 10
@@ -166,7 +166,7 @@ def test_on_llm_end_accumulates_across_multiple_calls():
     handler.on_llm_end(result1, run_id=uuid4(), parent_run_id=node_run_id)
     handler.on_llm_end(result2, run_id=uuid4(), parent_run_id=node_run_id)
 
-    usage = handler.node_metrics['root-agent'].usage
+    usage = handler.node_metrics['root-agent'].tokens
     assert usage.total == 16
     assert usage.input == 11
     assert usage.output == 5
@@ -203,7 +203,7 @@ def test_on_llm_end_camel_case_token_keys():
     )
     handler.on_llm_end(result, run_id=uuid4(), parent_run_id=node_run_id)
 
-    usage = handler.node_metrics['root-agent'].usage
+    usage = handler.node_metrics['root-agent'].tokens
     assert usage is not None
     assert usage.total == 20
     assert usage.input == 12
@@ -279,10 +279,10 @@ def test_node_metrics_includes_tokens():
 
     assert 'root-agent' in metrics
     node = metrics['root-agent']
-    assert node.usage is not None
-    assert node.usage.total == 15
-    assert node.usage.input == 10
-    assert node.usage.output == 5
+    assert node.tokens is not None
+    assert node.tokens.total == 15
+    assert node.tokens.input == 10
+    assert node.tokens.output == 5
 
 
 def test_node_metrics_includes_duration():
@@ -339,8 +339,8 @@ def test_node_metrics_multiple_nodes():
 
     assert 'root-agent' in metrics
     assert 'child-agent' in metrics
-    assert metrics['root-agent'].usage.total == 15
-    assert metrics['child-agent'].usage.total == 5
+    assert metrics['root-agent'].tokens.total == 15
+    assert metrics['child-agent'].tokens.total == 5
 
 
 def test_node_metrics_no_tool_calls_returns_none():
@@ -364,7 +364,7 @@ def test_node_metrics_no_usage_returns_none():
 
     metrics = handler.node_metrics
 
-    assert metrics['root-agent'].usage is None
+    assert metrics['root-agent'].tokens is None
 
 
 # ---------------------------------------------------------------------------

packages/ai-providers/server-ai-langchain/tests/test_tracking_langgraph.py

@@ -269,10 +269,10 @@ async def test_tracks_node_and_graph_tokens_on_success():
     node_metrics = handler.node_metrics
     assert 'root-agent' in node_metrics
     node = node_metrics['root-agent']
-    assert node.usage is not None
-    assert node.usage.total == 15
-    assert node.usage.input == 10
-    assert node.usage.output == 5
+    assert node.tokens is not None
+    assert node.tokens.total == 15
+    assert node.tokens.input == 10
+    assert node.tokens.output == 5
     assert node.success is True
     assert node.duration_ms is not None
 
@@ -495,8 +495,8 @@ def model_factory(node_config, **kwargs):
     node_metrics = handler.node_metrics
 
     # Per-node token usage is keyed by node key
-    assert node_metrics['root-agent'].usage.total == 15
-    assert node_metrics['child-agent'].usage.total == 5
+    assert node_metrics['root-agent'].tokens.total == 15
+    assert node_metrics['child-agent'].tokens.total == 5
 
     # Graph-level total from the real runner run
     ev = _events(mock_ld_client)

packages/ai-providers/server-ai-openai/README.md

@@ -112,7 +112,7 @@ model = await ai_client.create_model("ai-config-key", context)
 if model:
     result = await model.run("Explain feature flags.")
     # Metrics are tracked automatically; access them via result.metrics
-    print(result.metrics.usage)
+    print(result.metrics.tokens)
 ```
 
 ### Static Utility Methods
@@ -141,7 +141,7 @@ from ldai_openai import get_ai_metrics_from_response
 # After getting a response from OpenAI
 metrics = get_ai_metrics_from_response(response)
 print(f"Success: {metrics.success}")
-print(f"Tokens used: {metrics.usage.total if metrics.usage else 'N/A'}")
+print(f"Tokens used: {metrics.tokens.total if metrics.tokens else 'N/A'}")
 ```
 
 ## Documentation