feat!: rename LDAIMetrics.usage and AIGraphMetrics.usage to .tokens

[jsonbailey]

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): https://github.com/launchdarkly/sdk-specs/pull/163
• python-server-sdk-ai (this PR): targets main
• js-core (sibling impl): feat!: Rename LDAIMetrics.usage and LDAIGraphMetrics.usage to .tokens js-core#1366 (targets feat/next-ai-release)

Test plan

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

---

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.

^{Reviewed by Cursor Bugbot for commit ccdc00e. Bugbot is set up for automated code reviews on this repo. Configure here.}