core: fix trim_messages token_counter detection for lambdas, subclasses, and string annotations

[Maxwell Calkin (MaxwellCalkin)]

Description

Fixes #35629

trim_messages detects whether token_counter is a per-message callable (Callable[[BaseMessage], int]) or a per-list callable (Callable[[list[BaseMessage]], int]) by inspecting the first parameter's type annotation. The current check uses identity comparison (annotation is BaseMessage), which fails for five common cases:

Case	Annotation value	is BaseMessage
Lambda	inspect.Parameter.empty	False
Un-annotated function	inspect.Parameter.empty	False
String annotation ("BaseMessage")	str	False
Subclass annotation (HumanMessage)	type (not BaseMessage)	False
Postponed (from __future__ import annotations)	str	False

In all cases the per-message callable is silently misclassified as a per-list counter, and the user gets a confusing AttributeError: 'list' object has no attribute 'content' at runtime.

Fix

Introduces _is_per_message_token_counter() with a three-tier detection strategy:

1. Class annotation — issubclass(annotation, BaseMessage) instead of annotation is BaseMessage. Handles subclass annotations like HumanMessage.
2. String annotation — match against known message class names (BaseMessage, HumanMessage, AIMessage, etc.). Handles from __future__ import annotations and explicit string annotations.
3. No annotation — probe by calling the function with a single dummy HumanMessage and catching TypeError/AttributeError. Correctly classifies lambdas and un-annotated per-message counters, while still correctly classifying len as a per-list counter (since len(HumanMessage(...)) raises TypeError).

Tests

Added 5 new test cases covering all the failing scenarios from the issue, plus a regression test confirming token_counter=len (documented per-list usage) still works:

• test_trim_messages_lambda_token_counter
• test_trim_messages_unannotated_token_counter
• test_trim_messages_string_annotation_token_counter
• test_trim_messages_subclass_annotation_token_counter
• test_trim_messages_list_counter_len_still_works

Reproducer (from issue)

from __future__ import annotations
from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
from langchain_core.messages.utils import trim_messages

messages = [
    HumanMessage("What is 2 + 2?"),
    AIMessage("It is 4."),
    HumanMessage("What about 3 + 3?"),
]

# All five of these now work correctly:
trim_messages(messages, max_tokens=5, token_counter=lambda msg: len(msg.content.split()))

def counter_no_annotation(msg):
    return len(msg.content.split())
trim_messages(messages, max_tokens=5, token_counter=counter_no_annotation)

def counter_string(msg: "BaseMessage") -> int:
    return len(msg.content.split())
trim_messages(messages, max_tokens=5, token_counter=counter_string)

def counter_subclass(msg: HumanMessage) -> int:
    return len(msg.content.split())
trim_messages(messages, max_tokens=5, token_counter=counter_subclass)

def counter_postponed(msg: BaseMessage) -> int:  # with from __future__ import annotations
    return len(msg.content.split())
trim_messages(messages, max_tokens=5, token_counter=counter_postponed)

This PR was authored by Claude, an AI assistant by Anthropic, as part of an autonomous AI employment initiative. See https://github.com/MaxwellCalkin/career for details.

[codspeed-hq]

Merging this PR will not alter performance

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

✅ 13 untouched benchmarks
⏩ 23 skipped benchmarks¹

---

_{Comparing MaxwellCalkin:fix/trim-messages-token-counter-detection (b098b67) with master (29134dc)²}

Footnotes

1. 23 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on master (532b014) during the generation of this report, so 29134dc was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[GAUTAM V DATLA (gautamvarmadatla)]

Hi! Creator of the issue here

Thanks for working on this. However, I already have a PR open to fix it from when I originally opened the issue ( and there 4 other PRs too ) . Please try to avoid duplicates :)

[ccurme (ccurme)]

Duplicated with #35630.