core[patch]: utils for adding/subtracting usage metadata

libs/core/langchain_core/utils/usage.py

@@ -0,0 +1,80 @@
+import operator
+from typing import Callable, Optional, cast
+
+from langchain_core.messages.ai import UsageMetadata
+
+
+def add_usage(
+    left: Optional[UsageMetadata], right: Optional[UsageMetadata]
+) -> UsageMetadata:
+    if not (left or right):
+        return UsageMetadata(input_tokens=0, output_tokens=0, total_tokens=0)
+    if not (left and right):
+        return cast(UsageMetadata, left or right)
+
+    return UsageMetadata(
+        **cast(
+            UsageMetadata,
+            _dict_int_op(
+                cast(dict, left),
+                cast(dict, right),
+                operator.add,
+            ),
+        )
+    )
+
+
+def subtract_usage(
+    left: Optional[UsageMetadata], right: Optional[UsageMetadata]
+) -> UsageMetadata:
+    if not (left or right):
+        return UsageMetadata(input_tokens=0, output_tokens=0, total_tokens=0)
+    if not (left and right):
+        return cast(UsageMetadata, left or right)
+
+    return UsageMetadata(
+        **cast(
+            UsageMetadata,
+            _dict_int_op(
+                cast(dict, left),
+                cast(dict, right),
+                (lambda le, ri: max(le - ri, 0)),
+            ),
+        )
+    )
+
+
+def _dict_int_op(
+    left: dict,
+    right: dict,
+    op: Callable[[int, int], int],
+    *,
+    default: int = 0,
+    depth: int = 0,
+    max_depth: int = 100,
+) -> dict:
+    if depth >= max_depth:
+        msg = f"{max_depth=} exceeded, unable to combine dicts."
+        raise ValueError(msg)
+    combined: dict = {}
+    for k in set(left).union(right):
+        if isinstance(left.get(k, default), int) and isinstance(
+            right.get(k, default), int
+        ):
+            combined[k] = op(left.get(k, default), right.get(k, default))
+        elif isinstance(left.get(k, {}), dict) and isinstance(right.get(k, {}), dict):
+            combined[k] = _dict_int_op(
+                left.get(k, {}),
+                right.get(k, {}),
+                op,
+                default=default,
+                depth=depth + 1,
+                max_depth=max_depth,
+            )
+        else:
+            types = [type(d[k]) for d in (left, right) if k in d]
+            msg = (
+                f"Unknown value types: {types}. Only dict and int values are supported."
+            )
+            raise ValueError(msg)
+    return combined

libs/core/tests/unit_tests/utils/test_usage.py

@@ -0,0 +1,106 @@
+import pytest
+
+from langchain_core.messages.ai import (
+    InputTokenDetails,
+    OutputTokenDetails,
+    UsageMetadata,
+)
+from langchain_core.utils.usage import _dict_int_op, add_usage, subtract_usage
+
+
+def test_add_usage_both_none() -> None:
+    result = add_usage(None, None)
+    assert result == UsageMetadata(input_tokens=0, output_tokens=0, total_tokens=0)
+
+
+def test_add_usage_one_none() -> None:
+    usage = UsageMetadata(input_tokens=10, output_tokens=20, total_tokens=30)
+    result = add_usage(usage, None)
+    assert result == usage
+
+
+def test_add_usage_both_present() -> None:
+    usage1 = UsageMetadata(input_tokens=10, output_tokens=20, total_tokens=30)
+    usage2 = UsageMetadata(input_tokens=5, output_tokens=10, total_tokens=15)
+    result = add_usage(usage1, usage2)
+    assert result == UsageMetadata(input_tokens=15, output_tokens=30, total_tokens=45)
+
+
+def test_add_usage_with_details() -> None:
+    usage1 = UsageMetadata(
+        input_tokens=10,
+        output_tokens=20,
+        total_tokens=30,
+        input_token_details=InputTokenDetails(audio=5),
+        output_token_details=OutputTokenDetails(reasoning=10),
+    )
+    usage2 = UsageMetadata(
+        input_tokens=5,
+        output_tokens=10,
+        total_tokens=15,
+        input_token_details=InputTokenDetails(audio=3),
+        output_token_details=OutputTokenDetails(reasoning=5),
+    )
+    result = add_usage(usage1, usage2)
+    assert result["input_token_details"]["audio"] == 8
+    assert result["output_token_details"]["reasoning"] == 15
+
+
+def test_subtract_usage_both_none() -> None:
+    result = subtract_usage(None, None)
+    assert result == UsageMetadata(input_tokens=0, output_tokens=0, total_tokens=0)
+
+
+def test_subtract_usage_one_none() -> None:
+    usage = UsageMetadata(input_tokens=10, output_tokens=20, total_tokens=30)
+    result = subtract_usage(usage, None)
+    assert result == usage
+
+
+def test_subtract_usage_both_present() -> None:
+    usage1 = UsageMetadata(input_tokens=10, output_tokens=20, total_tokens=30)
+    usage2 = UsageMetadata(input_tokens=5, output_tokens=10, total_tokens=15)
+    result = subtract_usage(usage1, usage2)
+    assert result == UsageMetadata(input_tokens=5, output_tokens=10, total_tokens=15)
+
+
+def test_subtract_usage_with_negative_result() -> None:
+    usage1 = UsageMetadata(input_tokens=5, output_tokens=10, total_tokens=15)
+    usage2 = UsageMetadata(input_tokens=10, output_tokens=20, total_tokens=30)
+    result = subtract_usage(usage1, usage2)
+    assert result == UsageMetadata(input_tokens=0, output_tokens=0, total_tokens=0)
+
+
+def test_dict_int_op_add() -> None:
+    left = {"a": 1, "b": 2}
+    right = {"b": 3, "c": 4}
+    result = _dict_int_op(left, right, lambda x, y: x + y)
+    assert result == {"a": 1, "b": 5, "c": 4}
+
+
+def test_dict_int_op_subtract() -> None:
+    left = {"a": 5, "b": 10}
+    right = {"a": 2, "b": 3, "c": 1}
+    result = _dict_int_op(left, right, lambda x, y: max(x - y, 0))
+    assert result == {"a": 3, "b": 7, "c": 0}
+
+
+def test_dict_int_op_nested() -> None:
+    left = {"a": 1, "b": {"c": 2, "d": 3}}
+    right = {"a": 2, "b": {"c": 1, "e": 4}}
+    result = _dict_int_op(left, right, lambda x, y: x + y)
+    assert result == {"a": 3, "b": {"c": 3, "d": 3, "e": 4}}
+
+
+def test_dict_int_op_max_depth_exceeded() -> None:
+    left = {"a": {"b": {"c": 1}}}
+    right = {"a": {"b": {"c": 2}}}
+    with pytest.raises(ValueError):
+        _dict_int_op(left, right, lambda x, y: x + y, max_depth=2)
+
+
+def test_dict_int_op_invalid_types() -> None:
+    left = {"a": 1, "b": "string"}
+    right = {"a": 2, "b": 3}
+    with pytest.raises(ValueError):
+        _dict_int_op(left, right, lambda x, y: x + y)