chore: import upstream snapshot with attribution

sdks/python/tests/unit/llm_usage/test_anthropic_usage.py

@@ -0,0 +1,100 @@
+import pytest
+import pydantic
+from opik.llm_usage.anthropic_usage import AnthropicUsage
+
+
+def test_anthropic_usage_creation__happyflow():
+    usage_data = {
+        "input_tokens": 200,
+        "output_tokens": 100,
+        "cache_creation_input_tokens": 50,
+        "cache_read_input_tokens": 30,
+    }
+    usage = AnthropicUsage.from_original_usage_dict(usage_data)
+    assert usage.input_tokens == 200
+    assert usage.output_tokens == 100
+    assert usage.cache_creation_input_tokens == 50
+    assert usage.cache_read_input_tokens == 30
+
+
+def test_anthropic_usage_creation__no_cache_keys__cache_values_are_None():
+    usage_data = {
+        "input_tokens": 200,
+        "output_tokens": 100,
+    }
+    usage = AnthropicUsage.from_original_usage_dict(usage_data)
+    assert usage.input_tokens == 200
+    assert usage.output_tokens == 100
+    assert usage.cache_creation_input_tokens is None
+    assert usage.cache_read_input_tokens is None
+
+
+def test_anthropic_usage__to_backend_compatible_flat_dict__happyflow():
+    usage_data = {
+        "input_tokens": 200,
+        "output_tokens": 100,
+        "cache_creation_input_tokens": 50,
+        "cache_read_input_tokens": 30,
+    }
+    usage = AnthropicUsage.from_original_usage_dict(usage_data)
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.input_tokens": 200,
+        "original_usage.output_tokens": 100,
+        "original_usage.cache_creation_input_tokens": 50,
+        "original_usage.cache_read_input_tokens": 30,
+    }
+
+
+def test_anthropic_usage__to_backend_compatible_flat_dict__no_cache_keys():
+    usage_data = {
+        "input_tokens": 200,
+        "output_tokens": 100,
+    }
+    usage = AnthropicUsage.from_original_usage_dict(usage_data)
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.input_tokens": 200,
+        "original_usage.output_tokens": 100,
+    }
+
+
+def test_anthropic_usage__invalid_data_passed__validation_error_is_raised():
+    usage_data = {
+        "input_tokens": "invalid",
+        "output_tokens": None,
+        "cache_creation_input_tokens": "wrong_type",
+    }
+    with pytest.raises(pydantic.ValidationError):
+        AnthropicUsage.from_original_usage_dict(usage_data)
+
+
+def test_anthropic_usage__extra_unknown_keys_are_passed__fields_are_accepted__all_integers_included_to_the_resulting_flat_dict():
+    usage_data = {
+        "input_tokens": 200,
+        "output_tokens": 100,
+        "cache_creation_input_tokens": 50,
+        "cache_read_input_tokens": 30,
+        "some_newly_added_int": 42,
+        "some_newly_added_details_dict": {
+            "detail_int": 333,
+            "detail_string": "some-string",
+        },
+    }
+
+    usage = AnthropicUsage.from_original_usage_dict(usage_data)
+    assert usage.some_newly_added_int == 42
+    assert usage.some_newly_added_details_dict == {
+        "detail_int": 333,
+        "detail_string": "some-string",
+    }
+
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.input_tokens": 200,
+        "original_usage.output_tokens": 100,
+        "original_usage.cache_creation_input_tokens": 50,
+        "original_usage.cache_read_input_tokens": 30,
+        "original_usage.some_newly_added_int": 42,
+        "original_usage.some_newly_added_details_dict.detail_int": 333,
+    }

sdks/python/tests/unit/llm_usage/test_client_with_usage_logged.py

@@ -0,0 +1,250 @@
+import opik
+from ...testlib import TraceModel, SpanModel, ANY_BUT_NONE, assert_equal
+
+
+def test_span__provider_supported__usage_format_is_correct__usage_converted_to_opik_format(
+    fake_backend,
+):
+    opik_client = opik.Opik(batching=True)
+
+    opik_client.span(
+        type="llm",
+        name="some-name",
+        usage={
+            "completion_tokens": 10,
+            "prompt_tokens": 20,
+            "total_tokens": 30,
+        },
+        provider="openai",
+    )
+    opik_client.end()
+
+    EXPECTED_TRACE_TREE = TraceModel(
+        id=ANY_BUT_NONE,
+        start_time=ANY_BUT_NONE,
+        last_updated_at=ANY_BUT_NONE,
+        name="some-name",
+        spans=[
+            SpanModel(
+                id=ANY_BUT_NONE,
+                start_time=ANY_BUT_NONE,
+                type="llm",
+                name="some-name",
+                usage={
+                    "completion_tokens": 10,
+                    "prompt_tokens": 20,
+                    "total_tokens": 30,
+                    "original_usage.completion_tokens": 10,
+                    "original_usage.prompt_tokens": 20,
+                    "original_usage.total_tokens": 30,
+                },
+                spans=[],
+                provider="openai",
+                source="sdk",
+            )
+        ],
+        source="sdk",
+    )
+
+    assert len(fake_backend.trace_trees) == 1
+    trace_tree = fake_backend.trace_trees[0]
+
+    assert_equal(EXPECTED_TRACE_TREE, trace_tree)
+
+
+def test_span__provider_not_passed__usage_format_is_correct_for_some_provider__usage_converted_to_opik_format(
+    fake_backend,
+):
+    opik_client = opik.Opik(batching=True)
+
+    opik_client.span(
+        type="llm",
+        name="some-name",
+        usage={  # Anthropic format
+            "input_tokens": 10,
+            "output_tokens": 20,
+        },
+    )
+    opik_client.end()
+
+    EXPECTED_TRACE_TREE = TraceModel(
+        id=ANY_BUT_NONE,
+        start_time=ANY_BUT_NONE,
+        last_updated_at=ANY_BUT_NONE,
+        name="some-name",
+        spans=[
+            SpanModel(
+                id=ANY_BUT_NONE,
+                start_time=ANY_BUT_NONE,
+                type="llm",
+                name="some-name",
+                usage={
+                    "completion_tokens": 20,
+                    "prompt_tokens": 10,
+                    "total_tokens": 30,
+                    "original_usage.input_tokens": 10,
+                    "original_usage.output_tokens": 20,
+                },
+                spans=[],
+                source="sdk",
+            )
+        ],
+        source="sdk",
+    )
+
+    assert len(fake_backend.trace_trees) == 1
+    trace_tree = fake_backend.trace_trees[0]
+
+    assert_equal(EXPECTED_TRACE_TREE, trace_tree)
+
+
+def test_span__unknown_provider_passed__usage_format_is_correct_for_some_provider__usage_converted_to_opik_format(
+    fake_backend,
+):
+    opik_client = opik.Opik(batching=True)
+
+    opik_client.span(
+        type="llm",
+        name="some-name",
+        usage={  # Anthropic format
+            "input_tokens": 10,
+            "output_tokens": 20,
+        },
+        provider="my-llm-provider",
+    )
+    opik_client.end()
+
+    EXPECTED_TRACE_TREE = TraceModel(
+        id=ANY_BUT_NONE,
+        start_time=ANY_BUT_NONE,
+        last_updated_at=ANY_BUT_NONE,
+        name="some-name",
+        spans=[
+            SpanModel(
+                id=ANY_BUT_NONE,
+                start_time=ANY_BUT_NONE,
+                type="llm",
+                name="some-name",
+                usage={
+                    "completion_tokens": 20,
+                    "prompt_tokens": 10,
+                    "total_tokens": 30,
+                    "original_usage.input_tokens": 10,
+                    "original_usage.output_tokens": 20,
+                },
+                provider="my-llm-provider",
+                spans=[],
+                source="sdk",
+            )
+        ],
+        source="sdk",
+    )
+
+    assert len(fake_backend.trace_trees) == 1
+    trace_tree = fake_backend.trace_trees[0]
+
+    assert_equal(EXPECTED_TRACE_TREE, trace_tree)
+
+
+def test_span__unknown_provider_passed__usage_format_is_also_unknown__usage_flattened__prefix_added_to_keys__only_int_values_are_kept(
+    fake_backend,
+):
+    opik_client = opik.Opik(batching=True)
+
+    opik_client.span(
+        type="llm",
+        name="some-name",
+        usage={
+            "abc_input_tokens": 10,
+            "abc_output_tokens": 20,
+            "abc_nested_dict": {
+                "nested_int": 10,
+                "nested_str": "abc",
+            },
+        },
+        provider="my-llm-provider",
+    )
+    opik_client.end()
+
+    EXPECTED_TRACE_TREE = TraceModel(
+        id=ANY_BUT_NONE,
+        start_time=ANY_BUT_NONE,
+        last_updated_at=ANY_BUT_NONE,
+        name="some-name",
+        spans=[
+            SpanModel(
+                id=ANY_BUT_NONE,
+                start_time=ANY_BUT_NONE,
+                type="llm",
+                name="some-name",
+                usage={
+                    "original_usage.abc_input_tokens": 10,
+                    "original_usage.abc_output_tokens": 20,
+                    "original_usage.abc_nested_dict.nested_int": 10,
+                },
+                provider="my-llm-provider",
+                spans=[],
+                source="sdk",
+            )
+        ],
+        source="sdk",
+    )
+
+    assert len(fake_backend.trace_trees) == 1
+    trace_tree = fake_backend.trace_trees[0]
+
+    assert_equal(EXPECTED_TRACE_TREE, trace_tree)
+
+
+def test_span__user_added_openai_keys_to_unknown_usage_themselves__they_are_included_to_usage_dict_without_prefix(
+    fake_backend,
+):
+    opik_client = opik.Opik(batching=True)
+
+    opik_client.span(
+        type="llm",
+        name="some-name",
+        usage={
+            "prompt_tokens": 10,
+            "completion_tokens": 20,
+            "total_tokens": 30,
+            "abc_input_tokens": 10,
+            "abc_output_tokens": 20,
+        },
+        provider="my-llm-provider",
+    )
+    opik_client.end()
+
+    EXPECTED_TRACE_TREE = TraceModel(
+        id=ANY_BUT_NONE,
+        start_time=ANY_BUT_NONE,
+        last_updated_at=ANY_BUT_NONE,
+        name="some-name",
+        spans=[
+            SpanModel(
+                id=ANY_BUT_NONE,
+                start_time=ANY_BUT_NONE,
+                type="llm",
+                name="some-name",
+                usage={
+                    "prompt_tokens": 10,
+                    "completion_tokens": 20,
+                    "total_tokens": 30,
+                    "original_usage.prompt_tokens": 10,
+                    "original_usage.completion_tokens": 20,
+                    "original_usage.total_tokens": 30,
+                    "original_usage.abc_input_tokens": 10,
+                    "original_usage.abc_output_tokens": 20,
+                },
+                provider="my-llm-provider",
+                spans=[],
+                source="sdk",
+            )
+        ],
+        source="sdk",
+    )
+
+    assert len(fake_backend.trace_trees) == 1
+    trace_tree = fake_backend.trace_trees[0]
+
+    assert_equal(EXPECTED_TRACE_TREE, trace_tree)

sdks/python/tests/unit/llm_usage/test_google_usage.py

@@ -0,0 +1,104 @@
+import pytest
+import pydantic
+from opik.llm_usage.google_usage import GoogleGeminiUsage
+
+
+def test_google_gemini_usage_creation__happyflow():
+    usage_data = {
+        "candidates_token_count": 100,
+        "prompt_token_count": 50,
+        "total_token_count": 150,
+        "cached_content_token_count": 20,
+    }
+    usage = GoogleGeminiUsage.from_original_usage_dict(usage_data)
+    assert usage.candidates_token_count == 100
+    assert usage.prompt_token_count == 50
+    assert usage.total_token_count == 150
+    assert usage.cached_content_token_count == 20
+
+
+def test_google_gemini_usage_creation__no_cache_key__cached_content_token_count_is_None():
+    usage_data = {
+        "candidates_token_count": 100,
+        "prompt_token_count": 50,
+        "total_token_count": 150,
+    }
+    usage = GoogleGeminiUsage.from_original_usage_dict(usage_data)
+    assert usage.candidates_token_count == 100
+    assert usage.prompt_token_count == 50
+    assert usage.total_token_count == 150
+    assert usage.cached_content_token_count is None
+
+
+def test_google_gemini_usage__to_backend_compatible_flat_dict__happyflow():
+    usage_data = {
+        "candidates_token_count": 100,
+        "prompt_token_count": 50,
+        "total_token_count": 150,
+        "cached_content_token_count": 10,
+    }
+    usage = GoogleGeminiUsage.from_original_usage_dict(usage_data)
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.candidates_token_count": 100,
+        "original_usage.prompt_token_count": 50,
+        "original_usage.total_token_count": 150,
+        "original_usage.cached_content_token_count": 10,
+    }
+
+
+def test_google_gemini_usage__to_backend_compatible_flat_dict__no_cache_tokens_key():
+    usage_data = {
+        "candidates_token_count": 100,
+        "prompt_token_count": 50,
+        "total_token_count": 150,
+    }
+    usage = GoogleGeminiUsage.from_original_usage_dict(usage_data)
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.candidates_token_count": 100,
+        "original_usage.prompt_token_count": 50,
+        "original_usage.total_token_count": 150,
+    }
+
+
+def test_google_gemini_usage__invalid_data_passed__validation_error_is_raised():
+    usage_data = {
+        "candidates_token_count": "invalid",
+        "prompt_token_count": None,
+        "total_token_count": 150,
+        "cached_content_token_count": "wrong_type",
+    }
+    with pytest.raises(pydantic.ValidationError):
+        GoogleGeminiUsage.from_original_usage_dict(usage_data)
+
+
+def test_google_gemini_usage__extra_unknown_keys_are_passed__fields_are_accepted__all_integers_included_to_the_resulting_flat_dict():
+    usage_data = {
+        "candidates_token_count": 100,
+        "prompt_token_count": 50,
+        "total_token_count": 150,
+        "cached_content_token_count": 10,
+        "some_newly_added_int": 42,
+        "some_newly_added_details_dict": {
+            "detail_int": 333,
+            "detail_string": "some-string",
+        },
+    }
+
+    usage = GoogleGeminiUsage.from_original_usage_dict(usage_data)
+    assert usage.some_newly_added_int == 42
+    assert usage.some_newly_added_details_dict == {
+        "detail_int": 333,
+        "detail_string": "some-string",
+    }
+
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.candidates_token_count": 100,
+        "original_usage.prompt_token_count": 50,
+        "original_usage.total_token_count": 150,
+        "original_usage.cached_content_token_count": 10,
+        "original_usage.some_newly_added_int": 42,
+        "original_usage.some_newly_added_details_dict.detail_int": 333,
+    }

sdks/python/tests/unit/llm_usage/test_litellm_provider_mapping.py

@@ -0,0 +1,64 @@
+import pytest
+
+from opik.llm_usage import litellm_provider_mapping
+from opik.types import LLMProvider
+
+
+@pytest.mark.parametrize(
+    "model,expected_provider",
+    [
+        ("gemini/gemini-3.1-flash-lite-preview", LLMProvider.GOOGLE_AI),
+        ("vertex_ai/gemini-2.5-pro", LLMProvider.GOOGLE_VERTEXAI),
+        ("vertex_ai-language-models/gemini-1.5-pro", LLMProvider.GOOGLE_VERTEXAI),
+        (
+            "vertex_ai-anthropic_models/claude-3-5-sonnet",
+            LLMProvider.ANTHROPIC_VERTEXAI,
+        ),
+        ("anthropic/claude-3-5-sonnet", LLMProvider.ANTHROPIC),
+        ("bedrock/anthropic.claude-3-haiku", LLMProvider.BEDROCK),
+        ("bedrock_converse/anthropic.claude-3-haiku", LLMProvider.BEDROCK),
+        ("groq/llama-3.1-70b-versatile", LLMProvider.GROQ),
+        ("openai/gpt-4o", LLMProvider.OPENAI),
+    ],
+)
+def test_infer_provider_from_litellm_model_prefix__known_prefix__returns_provider_enum(
+    model, expected_provider
+):
+    assert (
+        litellm_provider_mapping.infer_provider_from_litellm_model_prefix(model)
+        == expected_provider
+    )
+
+
+@pytest.mark.parametrize(
+    "model,expected_raw_prefix",
+    [
+        ("cohere/command-r", "cohere"),
+        ("mistralai/mixtral-8x7b", "mistralai"),
+        ("perplexity/sonar-medium-online", "perplexity"),
+        ("unknown_provider/some-model", "unknown_provider"),
+    ],
+)
+def test_infer_provider_from_litellm_model_prefix__unknown_prefix__returns_raw_prefix_string(
+    model, expected_raw_prefix
+):
+    assert (
+        litellm_provider_mapping.infer_provider_from_litellm_model_prefix(model)
+        == expected_raw_prefix
+    )
+
+
+@pytest.mark.parametrize(
+    "model",
+    [
+        None,
+        "",
+        "gpt-4o",
+        "claude-3-5-sonnet",
+        "some-standalone-model-name",
+    ],
+)
+def test_infer_provider_from_litellm_model_prefix__no_prefix__returns_none(model):
+    assert (
+        litellm_provider_mapping.infer_provider_from_litellm_model_prefix(model) is None
+    )

sdks/python/tests/unit/llm_usage/test_mistral_usage.py

@@ -0,0 +1,85 @@
+import pytest
+import pydantic
+
+from opik.llm_usage import build_opik_usage
+from opik.llm_usage.mistral_usage import MistralUsage
+from opik.types import LLMProvider
+
+
+def test_mistral_usage_creation__happyflow():
+    usage_data = {
+        "prompt_tokens": 22,
+        "completion_tokens": 3,
+        "total_tokens": 25,
+        "prompt_tokens_details": {"cached_tokens": 0},
+    }
+    usage = MistralUsage.from_original_usage_dict(usage_data)
+    assert usage.prompt_tokens == 22
+    assert usage.completion_tokens == 3
+    assert usage.total_tokens == 25
+    assert usage.prompt_tokens_details.cached_tokens == 0
+
+
+def test_mistral_usage_creation__no_details__details_is_None():
+    usage_data = {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}
+    usage = MistralUsage.from_original_usage_dict(usage_data)
+    assert usage.prompt_tokens_details is None
+
+
+def test_mistral_usage__to_backend_compatible_flat_dict__happyflow():
+    usage_data = {
+        "prompt_tokens": 22,
+        "completion_tokens": 3,
+        "total_tokens": 25,
+        "prompt_tokens_details": {"cached_tokens": 0},
+    }
+    usage = MistralUsage.from_original_usage_dict(usage_data)
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.prompt_tokens": 22,
+        "original_usage.completion_tokens": 3,
+        "original_usage.total_tokens": 25,
+        "original_usage.prompt_tokens_details.cached_tokens": 0,
+    }
+
+
+def test_mistral_usage__non_int_extra_field_dropped_from_flat_dict():
+    # prompt_audio_seconds is a float; only integer values survive in the
+    # backend-compatible flat dict.
+    usage_data = {
+        "prompt_tokens": 10,
+        "completion_tokens": 5,
+        "total_tokens": 15,
+        "prompt_audio_seconds": 1.5,
+    }
+    usage = MistralUsage.from_original_usage_dict(usage_data)
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.prompt_tokens": 10,
+        "original_usage.completion_tokens": 5,
+        "original_usage.total_tokens": 15,
+    }
+
+
+def test_mistral_usage__invalid_data_passed__validation_error_is_raised():
+    usage_data = {
+        "prompt_tokens": "invalid",
+        "completion_tokens": None,
+        "total_tokens": 15,
+    }
+    with pytest.raises(pydantic.ValidationError):
+        MistralUsage.from_original_usage_dict(usage_data)
+
+
+def test_build_opik_usage__mistral_provider__produces_opik_usage():
+    usage_data = {
+        "prompt_tokens": 22,
+        "completion_tokens": 3,
+        "total_tokens": 25,
+        "prompt_tokens_details": {"cached_tokens": 0},
+    }
+    opik_usage = build_opik_usage(provider=LLMProvider.MISTRALAI, usage=usage_data)
+    assert opik_usage.prompt_tokens == 22
+    assert opik_usage.completion_tokens == 3
+    assert opik_usage.total_tokens == 25
+    assert isinstance(opik_usage.provider_usage, MistralUsage)

sdks/python/tests/unit/llm_usage/test_openai_chat_completions_usage.py

@@ -0,0 +1,126 @@
+import pydantic
+import pytest
+
+from opik.llm_usage.openai_chat_completions_usage import OpenAICompletionsUsage
+
+
+def test_openai_completions_usage_creation__happyflow():
+    usage_data = {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+        "completion_tokens_details": {
+            "accepted_prediction_tokens": 50,
+            "audio_tokens": 20,
+        },
+        "prompt_tokens_details": {
+            "audio_tokens": 10,
+            "cached_tokens": 30,
+        },
+    }
+    usage = OpenAICompletionsUsage.from_original_usage_dict(usage_data)
+    assert usage.completion_tokens == 100
+    assert usage.prompt_tokens == 200
+    assert usage.total_tokens == 300
+    assert usage.completion_tokens_details.accepted_prediction_tokens == 50
+    assert usage.completion_tokens_details.audio_tokens == 20
+    assert usage.prompt_tokens_details.audio_tokens == 10
+    assert usage.prompt_tokens_details.cached_tokens == 30
+
+
+def test_openai_completions_usage_creation__no_details_keys__details_are_None():
+    usage_data = {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+    }
+    usage = OpenAICompletionsUsage.from_original_usage_dict(usage_data)
+    assert usage.completion_tokens == 100
+    assert usage.prompt_tokens == 200
+    assert usage.total_tokens == 300
+    assert usage.completion_tokens_details is None
+    assert usage.prompt_tokens_details is None
+
+
+def test_openai_completions_usage__to_backend_compatible_flat_dict__happyflow():
+    usage_data = {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+        "completion_tokens_details": {
+            "accepted_prediction_tokens": 50,
+            "audio_tokens": 20,
+        },
+        "prompt_tokens_details": {
+            "audio_tokens": 10,
+            "cached_tokens": 30,
+        },
+    }
+    usage = OpenAICompletionsUsage.from_original_usage_dict(usage_data)
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.completion_tokens": 100,
+        "original_usage.prompt_tokens": 200,
+        "original_usage.total_tokens": 300,
+        "original_usage.completion_tokens_details.accepted_prediction_tokens": 50,
+        "original_usage.completion_tokens_details.audio_tokens": 20,
+        "original_usage.prompt_tokens_details.audio_tokens": 10,
+        "original_usage.prompt_tokens_details.cached_tokens": 30,
+    }
+
+
+def test_openai_completions_usage__invalid_data_passed__validation_error_is_raised():
+    usage_data = {
+        "completion_tokens": "invalid",
+        "prompt_tokens": None,
+        "total_tokens": 300,
+        "completion_tokens_details": "not_a_dict",
+    }
+    with pytest.raises(pydantic.ValidationError):
+        OpenAICompletionsUsage.from_original_usage_dict(usage_data)
+
+
+def test_openai_completions_usage__extra_unknown_keys_are_passed__fields_are_accepted__all_integers_included_to_the_resulting_flat_dict():
+    usage_data = {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+        "extra_integer": 99,
+        "completion_tokens_details": {
+            "accepted_prediction_tokens": 40,
+            "extra_completion_detail_int": 888,
+            "ignored_string": "ignored",
+        },
+        "prompt_tokens_details": {
+            "audio_tokens": 10,
+            "cached_tokens": 30,
+            "extra_prompt_detail_int": 111,
+            "ignored_string": "ignored",
+        },
+        "extra_details_dict": {
+            "extra_detail_int": 0,
+            "ignored_string": "ignored",
+        },
+    }
+    usage = OpenAICompletionsUsage.from_original_usage_dict(usage_data)
+    assert usage.extra_integer == 99
+    assert usage.extra_details_dict == {
+        "extra_detail_int": 0,
+        "ignored_string": "ignored",
+    }
+    assert usage.completion_tokens_details.extra_completion_detail_int == 888
+    assert usage.prompt_tokens_details.extra_prompt_detail_int == 111
+
+    flat_dict = usage.to_backend_compatible_flat_dict("original_usage")
+    assert flat_dict == {
+        "original_usage.completion_tokens": 100,
+        "original_usage.prompt_tokens": 200,
+        "original_usage.total_tokens": 300,
+        "original_usage.extra_integer": 99,
+        "original_usage.completion_tokens_details.accepted_prediction_tokens": 40,
+        "original_usage.completion_tokens_details.extra_completion_detail_int": 888,
+        "original_usage.prompt_tokens_details.audio_tokens": 10,
+        "original_usage.prompt_tokens_details.cached_tokens": 30,
+        "original_usage.prompt_tokens_details.extra_prompt_detail_int": 111,
+        "original_usage.extra_details_dict.extra_detail_int": 0,
+    }

sdks/python/tests/unit/llm_usage/test_opik_usage.py

@@ -0,0 +1,280 @@
+import pytest
+import pydantic
+from opik.llm_usage.opik_usage import OpikUsage
+
+
+def test_opik_usage__from_openai_completions_dict__happyflow():
+    usage_data = {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+        "completion_tokens_details": {
+            "accepted_prediction_tokens": 50,
+            "audio_tokens": 20,
+        },
+        "prompt_tokens_details": {
+            "audio_tokens": 10,
+            "cached_tokens": 30,
+        },
+        "video_seconds": 10,
+    }
+    usage = OpikUsage.from_openai_completions_dict(usage_data)
+    assert usage.completion_tokens == 100
+    assert usage.prompt_tokens == 200
+    assert usage.total_tokens == 300
+    assert usage.provider_usage.completion_tokens == 100
+    assert usage.provider_usage.prompt_tokens == 200
+    assert usage.provider_usage.total_tokens == 300
+    assert usage.provider_usage.video_seconds == 10
+
+
+def test_opik_usage__from_google_dict__happyflow():
+    usage_data = {
+        "candidates_token_count": 100,
+        "prompt_token_count": 200,
+        "total_token_count": 300,
+        "cached_content_token_count": 50,
+    }
+    usage = OpikUsage.from_google_dict(usage_data)
+    assert usage.completion_tokens == 100
+    assert usage.prompt_tokens == 200
+    assert usage.total_tokens == 300
+    assert usage.provider_usage.candidates_token_count == 100
+    assert usage.provider_usage.prompt_token_count == 200
+    assert usage.provider_usage.total_token_count == 300
+
+
+def test_opik_usage__to_backend_compatible_full_usage_dict__openai_source():
+    usage_data = {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+        "completion_tokens_details": {
+            "accepted_prediction_tokens": 50,
+            "audio_tokens": 20,
+        },
+        "prompt_tokens_details": {
+            "audio_tokens": 10,
+            "cached_tokens": 30,
+        },
+    }
+    usage = OpikUsage.from_openai_completions_dict(usage_data)
+    full_dict = usage.to_backend_compatible_full_usage_dict()
+    assert full_dict == {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+        "original_usage.completion_tokens": 100,
+        "original_usage.prompt_tokens": 200,
+        "original_usage.total_tokens": 300,
+        "original_usage.completion_tokens_details.accepted_prediction_tokens": 50,
+        "original_usage.completion_tokens_details.audio_tokens": 20,
+        "original_usage.prompt_tokens_details.audio_tokens": 10,
+        "original_usage.prompt_tokens_details.cached_tokens": 30,
+    }
+
+
+def test_opik_usage__to_backend_compatible_full_usage_dict__google_source():
+    usage_data = {
+        "candidates_token_count": 100,
+        "prompt_token_count": 200,
+        "total_token_count": 300,
+        "cached_content_token_count": 50,
+    }
+    usage = OpikUsage.from_google_dict(usage_data)
+    full_dict = usage.to_backend_compatible_full_usage_dict()
+    assert full_dict == {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+        "original_usage.candidates_token_count": 100,
+        "original_usage.prompt_token_count": 200,
+        "original_usage.total_token_count": 300,
+        "original_usage.cached_content_token_count": 50,
+    }
+
+
+def test_opik_usage__to_backend_compatible_full_usage_dict__anthropic_source():
+    usage_data = {
+        "input_tokens": 200,
+        "output_tokens": 100,
+        "cache_creation_input_tokens": 50,
+        "cache_read_input_tokens": 30,
+    }
+    usage = OpikUsage.from_anthropic_dict(usage_data)
+    full_dict = usage.to_backend_compatible_full_usage_dict()
+    assert full_dict == {
+        "completion_tokens": 100,
+        "prompt_tokens": 280,  # 200 + 30 cache_read + 50 cache_creation
+        "total_tokens": 380,
+        "original_usage.input_tokens": 200,
+        "original_usage.output_tokens": 100,
+        "original_usage.cache_creation_input_tokens": 50,
+        "original_usage.cache_read_input_tokens": 30,
+    }
+
+
+def test_opik_usage__from_unknown_usage_dict__both_tokens_present__total_is_calculated():
+    usage_data = {
+        "prompt_tokens": 200,
+        "completion_tokens": 100,
+    }
+    usage = OpikUsage.from_unknown_usage_dict(usage_data)
+    assert usage.prompt_tokens == 200
+    assert usage.completion_tokens == 100
+    assert usage.total_tokens == 300
+
+
+def test_opik_usage__from_unknown_usage_dict__only_prompt_tokens__total_is_none():
+    usage_data = {
+        "prompt_tokens": 200,
+    }
+    usage = OpikUsage.from_unknown_usage_dict(usage_data)
+    assert usage.prompt_tokens == 200
+    assert usage.completion_tokens is None
+    assert usage.total_tokens is None
+
+
+def test_opik_usage__from_unknown_usage_dict__only_completion_tokens__total_is_none():
+    usage_data = {
+        "completion_tokens": 100,
+    }
+    usage = OpikUsage.from_unknown_usage_dict(usage_data)
+    assert usage.prompt_tokens is None
+    assert usage.completion_tokens == 100
+    assert usage.total_tokens is None
+
+
+def test_opik_usage__from_unknown_usage_dict__empty_dict__all_none():
+    usage = OpikUsage.from_unknown_usage_dict({})
+    assert usage.prompt_tokens is None
+    assert usage.completion_tokens is None
+    assert usage.total_tokens is None
+
+
+def test_opik_usage__to_backend_compatible_full_usage_dict__unknown_source__total_tokens_present():
+    usage_data = {
+        "prompt_tokens": 200,
+        "completion_tokens": 100,
+    }
+    usage = OpikUsage.from_unknown_usage_dict(usage_data)
+    full_dict = usage.to_backend_compatible_full_usage_dict()
+    assert full_dict == {
+        "completion_tokens": 100,
+        "prompt_tokens": 200,
+        "total_tokens": 300,
+        "original_usage.prompt_tokens": 200,
+        "original_usage.completion_tokens": 100,
+    }
+
+
+def test_opik_usage__from_unknown_usage_dict__string_tokens__coerced_to_int():
+    usage_data = {
+        "prompt_tokens": "200",
+        "completion_tokens": "100",
+    }
+    usage = OpikUsage.from_unknown_usage_dict(usage_data)
+    assert usage.prompt_tokens == 200
+    assert usage.completion_tokens == 100
+    assert usage.total_tokens == 300
+
+
+def test_opik_usage__from_unknown_usage_dict__invalid_token_values__total_is_none():
+    usage_data = {
+        "prompt_tokens": "not-a-number",
+        "completion_tokens": "also-invalid",
+    }
+    usage = OpikUsage.from_unknown_usage_dict(usage_data)
+    assert usage.prompt_tokens is None
+    assert usage.completion_tokens is None
+    assert usage.total_tokens is None
+
+
+def test_opik_usage__from_anthropic_dict__with_compaction_iterations__sums_all_iterations():
+    # When compaction fires, top-level input/output_tokens reflect only the non-compaction
+    # iterations (i.e. the message iterations). The compaction iteration is excluded from
+    # the top-level but IS billed — summing all iterations gives the true billed cost.
+    # https://platform.claude.com/docs/en/build-with-claude/compaction#understanding-usage
+    usage_data = {
+        # top-level = sum of non-compaction ("message") iterations only
+        "input_tokens": 23000,
+        "output_tokens": 1000,
+        "cache_creation_input_tokens": 0,
+        "cache_read_input_tokens": 0,
+        "iterations": [
+            {
+                "type": "compaction",
+                "input_tokens": 180000,
+                "output_tokens": 3500,
+                "cache_creation_input_tokens": 0,
+                "cache_read_input_tokens": 0,
+            },
+            {
+                "type": "message",
+                "input_tokens": 23000,
+                "output_tokens": 1000,
+                "cache_creation_input_tokens": 0,
+                "cache_read_input_tokens": 0,
+            },
+        ],
+    }
+    usage = OpikUsage.from_anthropic_dict(usage_data)
+    assert usage.prompt_tokens == 203000  # 180000 + 23000
+    assert usage.completion_tokens == 4500  # 3500 + 1000
+    assert usage.total_tokens == 207500
+
+
+def test_opik_usage__from_anthropic_dict__compaction_with_caching__includes_cache_tokens_per_iteration():
+    # When both compaction and prompt caching are active, each iteration always carries
+    # cache_creation_input_tokens and cache_read_input_tokens (required fields per SDK types).
+    # top-level tokens reflect only the non-compaction iterations.
+    usage_data = {
+        # top-level = message iteration only: input=23000, cache_read=5000
+        "input_tokens": 23000,
+        "output_tokens": 1000,
+        "cache_creation_input_tokens": 500,
+        "cache_read_input_tokens": 5000,
+        "iterations": [
+            {
+                "type": "compaction",
+                "input_tokens": 180000,
+                "output_tokens": 3500,
+                "cache_read_input_tokens": 10000,
+                "cache_creation_input_tokens": 2000,
+            },
+            {
+                "type": "message",
+                "input_tokens": 23000,
+                "output_tokens": 1000,
+                "cache_read_input_tokens": 5000,
+                "cache_creation_input_tokens": 500,
+            },
+        ],
+    }
+    usage = OpikUsage.from_anthropic_dict(usage_data)
+    assert usage.prompt_tokens == 220500  # (180000+10000+2000) + (23000+5000+500)
+    assert usage.completion_tokens == 4500  # 3500 + 1000
+    assert usage.total_tokens == 225000
+
+
+def test_opik_usage__from_anthropic_dict__no_compaction__uses_top_level_tokens():
+    usage_data = {
+        "input_tokens": 200,
+        "output_tokens": 100,
+        "cache_creation_input_tokens": 50,
+        "cache_read_input_tokens": 30,
+    }
+    usage = OpikUsage.from_anthropic_dict(usage_data)
+    assert usage.prompt_tokens == 280  # 200 + 30 cache_read + 50 cache_creation
+    assert usage.completion_tokens == 100
+    assert usage.total_tokens == 380
+
+
+def test_opik_usage__invalid_data_passed__validation_error_is_raised():
+    usage_data = {"a": 123}
+    with pytest.raises(pydantic.ValidationError):
+        OpikUsage.from_openai_completions_dict(usage_data)
+    with pytest.raises(pydantic.ValidationError):
+        OpikUsage.from_google_dict(usage_data)
+    with pytest.raises(pydantic.ValidationError):
+        OpikUsage.from_anthropic_dict(usage_data)

sdks/python/tests/unit/llm_usage/test_opik_usage_factory.py

@@ -0,0 +1,48 @@
+import opik
+from opik import llm_usage
+
+
+def test_opik_usage_factory__openai_happyflow():
+    result = llm_usage.build_opik_usage(
+        provider=opik.LLMProvider.OPENAI,
+        usage={"completion_tokens": 10, "prompt_tokens": 20, "total_tokens": 30},
+    )
+
+    assert result.completion_tokens == 10
+    assert result.prompt_tokens == 20
+    assert result.total_tokens == 30
+
+    assert result.provider_usage.completion_tokens == 10
+    assert result.provider_usage.prompt_tokens == 20
+    assert result.provider_usage.total_tokens == 30
+
+
+def test_opik_usage_factory__anthropic_happyflow():
+    result = llm_usage.build_opik_usage(
+        provider=opik.LLMProvider.ANTHROPIC,
+        usage={"input_tokens": 10, "output_tokens": 20},
+    )
+
+    assert result.completion_tokens == 20
+    assert result.prompt_tokens == 10
+    assert result.total_tokens == 30
+
+    assert result.provider_usage.input_tokens == 10
+    assert result.provider_usage.output_tokens == 20
+
+
+def test_opik_usage_factory__vertex_ai_none_candidates_token_count__happy_flow():
+    result = llm_usage.build_opik_usage(
+        provider=opik.LLMProvider.GOOGLE_VERTEXAI,
+        usage={
+            "cached_content_token_count": None,
+            "candidates_token_count": None,
+            "prompt_token_count": 7859,
+            "thoughts_token_count": None,
+            "total_token_count": 7859,
+        },
+    )
+
+    assert result.completion_tokens == 0
+    assert result.prompt_tokens == 7859
+    assert result.total_tokens == 7859