**Structural Suggestion: MessageCleaner Utility to Minimize Ad-hoc Handling**

[SongChiYoung]

💡 Structural Suggestion: MessageCleaner Utility to Minimize Ad-hoc Handling

While resolving #6167 and implementing the fix in #6168, I ran into a pattern that might be worth exploring more broadly — especially as model-specific quirks become more common.

Right now, we're beginning to see small but vendor-specific tweaks (e.g., trimming whitespace for Claude, merging multiple system messages for Gemini/Anthropic) that can be hard to isolate cleanly within per-message transformers. If left unstructured, these could slowly accumulate into ad-hoc logic inside ModelClient.create() or similar places.

To avoid that, I’d like to propose a minimal utility-based pattern that lets us chain cleanups while keeping the core architecture untouched.

---

✅ Suggested Structure

messages = MessageCleaner(messages) \
    .merge_system_message() \
    .rstrip_last_assistant() \
    .get_messages()

• .merge_system_message(): Merges multiple SystemMessages — same logic from FIX: Anthropic and Gemini could take multiple system message #6118
• .rstrip_last_assistant(): Trims trailing whitespace from the final AssistantMessage (fixes Claude errors)
• .get_messages(): Returns the cleaned message list

This design keeps the flow declarative and avoids altering any core interfaces like ModelClient.

---

✨ Benefits

Feature	Description
📦 Clean separation	Keeps post-processing logic outside of message-to-SDK transformers
🔁 Chainable	Easy to extend later: .remove_empty_messages(), .sanitize_names(), etc.
🧩 Compatible	Works directly with current client.create(messages=...) usage
🕊️ Low-friction	No need to introduce registries or structural change just yet

---

🔍 Example Implementation

class MessageCleaner:
    def __init__(self, messages: list[LLMMessage]):
        self._messages = messages

    def merge_system_message(self):
        self._messages = _merge_system_messages(self._messages)
        return self

    def rstrip_last_assistant(self):
        if isinstance(self._messages[-1], AssistantMessage):
            self._messages[-1].content = self._messages[-1].content.rstrip()
        return self

    def get_messages(self):
        return self._messages

---

If this feels like a reasonable direction, I’d be happy to open a PR to get the ball rolling.
That said, it's small enough that we could even just keep it as an internal helper for now.

Thanks again for your time and consideration! 🙏