feat(core): add to_message_state and as_message_state helpers for LCEL message normalization

[davicaetano]

Description

This PR introduces two new utilities to the langchain_core.messages module:

• to_message_state
• as_message_state

These helpers provide a consistent and centralized way to normalize various message-like inputs into the canonical LCEL message state:

{"messages": [BaseMessage, ...]}

They allow LCEL pipelines to seamlessly handle strings, BaseMessage instances, mixed lists, and pre-existing {"messages": [...]} dicts without needing to duplicate normalization logic across runnables.

This change follows the discussion in Issue #34061 and places the implementation in the appropriate module (messages.utils), preserving clear domain boundaries and avoiding unnecessary coupling with runnables.

Fixes #34061

---

Issue

The absence of a standardized message-normalization helper required LCEL chains to implement small variations of the same logic.
This PR resolves that by providing a unified, well-tested implementation.

---

Dependencies

No new dependencies were added.
No modifications to pyproject.toml or uv.lock.
Changes are limited to:

langchain_core/messages/utils.py
tests/unit_tests/messages/test_message_state.py

---

Tests

This PR includes a dedicated test file:

tests/unit_tests/messages/test_message_state.py

Test coverage includes:

• string → HumanMessage
• BaseMessage passthrough
• mixed lists (string + BaseMessage)
• message-state passthrough
• None normalization
• LCEL integration via as_message_state

All tests pass locally:

7 passed in 0.04s

Linting and formatting also pass (ruff check . is clean).

---

Notes

An earlier community PR attempted to introduce message normalization inside runnables, but message transformation belongs to the messages domain.
This PR follows the expected architecture of LangChain Core, keeps responsibilities separated, and avoids circular dependencies.

Happy to adjust naming or behavior based on reviewer feedback.

[codspeed-hq]

CodSpeed Performance Report

Merging #34094 will not alter performance

_{Comparing davicaetano:feature-to-message-state (61ae9e3) with master (880652b)¹}

⚠️ 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.

Summary

✅ 13 untouched
⏩ 21 skipped²

Footnotes

1. No successful run was found on master (9c21f83) during the generation of this report, so 880652b was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

2. 21 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. ↩