Add ordered content parts to UserMessage

[dmitriierokhin]

Problem

UserMessage holds a single text plus a List<Media> with no ordering relation between
them, so every provider converter can only ever serialize a user turn as all text, then all
media.

Some multimodal prompts depend on a finer ordering. The case that led me here is a per-page
document prompt: each page contributes a marker, its OCR text, and its page image, and the
image must directly follow that page's own text so the model associates the two. Flattened to
text-then-media, the page↔image association is gone. There is currently no way to express this
through the core message API, even for providers whose wire format is itself an ordered list of
parts.

Solution

Add ContentPart (spring-ai-commons, org.springframework.ai.content) — a sealed
TextPart | MediaPart — and let a UserMessage carry an ordered List<ContentPart>:

UserMessage.builder()
    .contentParts(
        ContentPart.text("--- page 1 ---"), ContentPart.media(page1Image),
        ContentPart.text("--- page 2 ---"), ContentPart.media(page2Image))
    .build();

The design point that keeps this additive: text and media remain faithful projections of
the parts, and vice versa. They are never a second source of truth.

• A message built the flat way exposes getContentParts() as the derived [text, media…]
  sequence, so providers need only one code path.
• A message built from parts exposes getText() (text parts joined with \n) and getMedia()
  (media parts in order).
• Because the projections stay faithful, providers that cannot express ordering keep working
  with no change at all, and token counting still sees one source of truth. I deliberately did
  not add anything to MediaContent, so JTokkitTokenCountEstimator cannot double-count.
• AbstractMessage's non-null-text invariant is untouched: a media-only message projects to
  "".

hasInterleavedContent() reports whether flattening would lose information (i.e. anything other
than one leading text followed by media). Providers with a flat text-plus-media shortcut keep
taking it while that is false, so existing requests are byte-identical; only genuinely ordered
content takes the parts path. This is what stops the change rewriting the wire format for every
existing Anthropic and OpenAI user message.

Provider adoption

Module	Native shape	Change
spring-ai-google-genai	List<Part>	parts walk; mediaToPart extracted for reuse
spring-ai-anthropic	List<ContentBlockParam>	parts walk; cache control moved to the last text block
spring-ai-openai	ChatCompletionContentPart[]	toContentPart(Media) extracted verbatim from the inline lambda, then parts walk
spring-ai-bedrock-converse	List<ContentBlock>	parts walk
spring-ai-mistral-ai	sealed ContentChunk	parts walk, hoisted above the non-null-text assertion
spring-ai-ollama	flat content + images	no code change; comment recording that parts are flattened
spring-ai-deepseek	text only	no change

Two pre-existing issues were fixed incidentally, because walking the parts replaced the code
that contained them:

• Bedrock Converse called ContentBlock.fromText(userMessage.getText()) unconditionally, so a
  media-only message produced an empty text block, which Bedrock rejects.
• Mistral asserted non-null text before looking at media, so a message whose content begins with
  media threw.

Backwards compatibility

Every existing UserMessage constructor, Builder method, getText(), getMedia() contents,
toString(), equals() and hashCode() keep their exact signatures and semantics. For a
message built the flat way getText() returns the identical string, including empty and
whitespace-only values, and getMedia() returns the identical contents in the identical order.
copy()/mutate() round-trip faithfully. No provider requires a change. Nothing is
deprecated.

Three behaviours do change, all intentional and covered by tests:

1. getMedia() now returns an unmodifiable view. Mutating the returned list was never a
   supported contract, and it would desynchronize the list from the content parts. One test in
   spring-ai-mistral-ai did this (userMessage.getMedia().add(...)) and is updated to use the
   builder.
2. Builder.text(...)/Builder.media(...) discard previously set content parts. This is
   enforced eagerly in each setter rather than validated in build(), deliberately: components
   that rewrite user text (ChatModelCallAdvisor, StructuredOutputValidationAdvisor,
   Prompt.augmentUserMessage) all do mutate().text(...), and throwing there would break the
   whole advisor chain the moment one interleaved message reached it. Flattening loses ordering
   but keeps all content, which is exactly today's behaviour. Builder.appendText(String) is
   added as the structure-preserving alternative for those callers to migrate to; I left the
   migration itself out of this PR.
3. Media-only user messages become representable, and their getText() is "". Components
   that treat user text as a query would see an empty query for such a message.

Known limitation

UserMessage still does not override equals/hashCode, so neither media nor part ordering
participates in equality — unchanged from today, and pinned by a test with a comment. Including
parts in equality now would give identity semantics, because Media has no equals/hashCode;
that would make messages round-tripped through the Redis and Neo4j chat-memory repositories stop
comparing equal to their originals. The follow-up is value-based equals on Media first.

Deliberately out of scope

ChatClient's fluent surface. DefaultChatClientUtils only materializes a UserMessage when
StringUtils.hasText(processedUserText), so a blocks-only spec would be silently dropped, and
DefaultPromptUserSpec holds media as a flat list. Threading parts through
PromptUserSpec → DefaultChatClientRequestSpec → DefaultChatClientUtils is a separate
design question (including how param() rendering should apply per part), and
ChatClientRequestSpec.messages(Message...) already accepts a pre-built UserMessage in the
meantime. Happy to follow up if you'd like it in the same change.

Tests

• ContentPartTests (new) — construction, null rejection, blank text allowed, record equality
  (and that MediaPart equality is necessarily identity-based given Media has no equals).
• UserMessageTests — all pre-existing tests pass unmodified, which is the main regression
  signal. Added: projection in both directions, the \n join separator, no media marker leaking
  into the text projection, builder channel exclusivity in both orders, copy()/mutate()
  fidelity including that mutate().text(...) leaves no stale part carrying the old text,
  appendText in both modes, hasInterleavedContent() truth table, immutability of both
  returned lists, and equality semantics pinned as-is.
• CreateGeminiRequestTests — interleaved parts asserted index-by-index on the resulting
  GeminiRequest (one Content, N parts, alternating text()/fileData().fileUri()), parts
  alongside a SystemMessage, and a case pinning the legacy flat path unchanged.

./mvnw clean package passes locally.

Notes

Happy to split this into a core-only PR plus per-provider follow-ups if that is easier to
review, or to reshape the API — the naming (ContentPart/TextPart/MediaPart) avoids
collisions with the Anthropic and Bedrock SDKs' own ContentBlock/TextBlock types, but I have
no attachment to it.

This was developed with the help of an AI coding agent; I have reviewed every line and am
accountable for it, per CONTRIBUTING.md. The per-commit Co-authored-by trailers record that.