subtract_usage() — langchain Function Reference

Architecture documentation for the subtract_usage() function in ai.py from the langchain codebase.

Function python CoreAbstractions MessageSchema

Entity Profile

CoreAbstractions→ MessageSchema→ subtract_usage() — langchain Function Reference

Dependency Diagram

graph TD
  cc5aa964_e109_cc22_851b_2d182afd14aa["subtract_usage()"]
  49c04e35_a53c_8d1b_eb09_1203ad7cdacf["ai.py"]
  cc5aa964_e109_cc22_851b_2d182afd14aa -->|defined in| 49c04e35_a53c_8d1b_eb09_1203ad7cdacf
  style cc5aa964_e109_cc22_851b_2d182afd14aa fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

libs/core/langchain_core/messages/ai.py lines 780–840

def subtract_usage(
    left: UsageMetadata | None, right: UsageMetadata | None
) -> UsageMetadata:
    """Recursively subtract two `UsageMetadata` objects.

    Token counts cannot be negative so the actual operation is `max(left - right, 0)`.

    Example:
        ```python
        from langchain_core.messages.ai import subtract_usage

        left = UsageMetadata(
            input_tokens=5,
            output_tokens=10,
            total_tokens=15,
            input_token_details=InputTokenDetails(cache_read=4),
        )
        right = UsageMetadata(
            input_tokens=3,
            output_tokens=8,
            total_tokens=11,
            output_token_details=OutputTokenDetails(reasoning=4),
        )

        subtract_usage(left, right)
        ```

        results in

        ```python
        UsageMetadata(
            input_tokens=2,
            output_tokens=2,
            total_tokens=4,
            input_token_details=InputTokenDetails(cache_read=4),
            output_token_details=OutputTokenDetails(reasoning=0),
        )
        ```
    Args:
        left: The first `UsageMetadata` object.
        right: The second `UsageMetadata` object.

    Returns:
        The resulting `UsageMetadata` after subtraction.

    """
    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)),
            ),
        )
    )