add_usage() — langchain Function Reference

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

Function python LangChainCore ApiManagement called by 1

Entity Profile

LangChainCore→ ApiManagement→ add_usage() — langchain Function Reference

Dependency Diagram

graph TD
  cdc88fbc_bcc4_c962_2ddc_7ed8e732b6d7["add_usage()"]
  98b3055e_a59b_3f72_0c70_bc2d048efeb0["ai.py"]
  cdc88fbc_bcc4_c962_2ddc_7ed8e732b6d7 -->|defined in| 98b3055e_a59b_3f72_0c70_bc2d048efeb0
  e7bc6592_4344_324e_6e97_eb4a3e90f81b["add_ai_message_chunks()"]
  e7bc6592_4344_324e_6e97_eb4a3e90f81b -->|calls| cdc88fbc_bcc4_c962_2ddc_7ed8e732b6d7
  style cdc88fbc_bcc4_c962_2ddc_7ed8e732b6d7 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

libs/core/langchain_core/messages/ai.py lines 721–777

def add_usage(left: UsageMetadata | None, right: UsageMetadata | None) -> UsageMetadata:
    """Recursively add two UsageMetadata objects.

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

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

        add_usage(left, right)
        ```

        results in

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

    Returns:
        The sum of the two `UsageMetadata` objects.

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