fix(backends): reject empty user content before sending chat request

[simonyang08]

Fixes #1597

Root cause

SimpleContext.view_for_generation() returns [] by design — it is a stateless context. But .add() still exists and returns a chainable context, which reads like it records the turn for the next call. A caller who .add()s a user message and then passes an empty or whitespace-only action to generate_from_context ends up sending the model a conversation with no user-role content at all, and nothing errors. This is exactly what happened in #1587's live Ollama telemetry tests, where Granite 4.2 rambled for 2000+ tokens on the resulting empty prompt and stalled CI.

Fix

Add a shared invariant guard in the chat-message assembly path of the three backends that build user-role conversations for chat APIs — OpenAIBackend._generate_from_chat_context_standard, LiteLLMBackend._generate_from_chat_context_standard, and OllamaModelBackend.generate_from_chat_context:

• if the fully assembled messages list has no user-role message with non-whitespace content, raise ValueError before any HTTP/SDK call is issued;
• whitespace-only content counts as empty; user messages that carry images, audio, or documents (_docs) still pass, so vision/RAG paths keep working.

ValueError matches the existing repo convention for "call cannot proceed" (cf. context_lengths.py, intrinsic/_util.py). SimpleContext.add/view_for_generation docstrings now state explicitly that recorded turns are never forwarded, so the .add()-then-empty-action trap is documented at the API surface too.

Note on scope: WatsonxAIBackend and LocalHFBackend also assemble user-role conversations and would benefit from the same guard, but are intentionally left untouched to keep this change focused on the backends named in the issue. Happy to mirror the guard in a follow-up if preferred.

Verification

New regression suite test/backends/test_simple_context_guard.py (mocked providers, no network):

• empty / whitespace-only action raises on OpenAI, LiteLLM, and Ollama backends — verified RED on unpatched main (DID NOT RAISE ValueError), green after the fix;
• non-empty user content still sends the request on all three backends;
• a user message with images passes the guard (multimodal path);
• the guardian.py call pattern (non-empty context + empty assistant action) is not affected.

Focused backend/context suites: 170 passed. test/stdlib/ regression run shows no new failures relative to unpatched main.

DCO: Signed-off-by: simonyang08 <ppt5928@gmail.com>. AI-assisted contribution per CONTRIBUTING.md (Assisted-by: ZCode (GLM) trailer on the commit).

[planetf1]

Thanks for tracking this down — the root cause write-up (SimpleContext.add() not forwarding to generation) is clear, and the regression test deliberately targeting the guardian false-positive case shows good instinct for where this guard could misfire. Ran the new suite plus test/stdlib/components/test_chat.py: all green, no regressions.

Two things I'd like addressed before merge, both about maintainability rather than correctness of the guard itself:

1. The guard is copy-pasted three times, not shared. The identical ~17-line check (predicate, comment, and raised message) is duplicated verbatim across openai.py, litellm.py, and ollama.py. All three already import from mellea/helpers/openai_compatible_helpers.py, which already hosts message_to_openai_message and messages_to_docs on the same list[Message] input. Could you pull this into a has_user_content(messages: list[Message]) -> bool there and call it from all three sites? Otherwise the Watsonx/HF follow-up you mentioned turns this into five copies, and a future tweak (new attachment type, wording change) has to land in lockstep everywhere.

2. Attachment pass-through is barely tested. The guard treats images, audio, and _docs as "has content" so multimodal/RAG messages don't trip it — but only the images branch is actually tested, and only on OpenAI. audio and documents have no coverage on any backend, and LiteLLM is also missing the whitespace-only case the other two cover. Not asking for nine near-duplicate tests — one audio=-only and one documents=-only case (even just on OpenAI, since the logic is identical across backends) would close the gap.

One scoping note on the PR description: deferring WatsonxAIBackend makes sense, it's already marked deprecated in favour of LiteLLM/OpenAI. LocalHFBackend isn't deprecated and builds its chat messages the same way (view_for_generation() → to_chat_messages()), so the same empty-prompt trap likely reproduces there. Happy for that to be a fast follow-up rather than blocking this PR, but could you open an issue for it so it doesn't fall through?

A couple of small docstring/message nits inline below and noted at the end. Nothing here blocks the fix itself, which is correct and well-placed — once the dedup and the attachment tests are in, this looks good to merge.

On the docstrings (these fall outside the diff's hunks so I can't anchor inline suggestions to them, but worth doing while you're in these files):

• openai.py — _generate_from_context (the method the Backend ABC actually dispatches to, ~line 904) already has a Raises: section for the ALoraRequirement case. Add: ValueError: If the assembled conversation has no user-role message with non-whitespace content, images, audio, or documents.
• ollama.py — generate_from_chat_context (~line 1073) already has a Raises: section for the image/audio cases. Same addition there.
• litellm.py — _generate_from_context (~line 191) has no formal Raises: section yet, just prose ("raises NotImplementedError otherwise"). Worth adding one with both NotImplementedError: If ctx is not a chat context. and the new ValueError line.

[planetf1]

Minor: the raised message cites "issue #1597" directly. Worth dropping that from the user-facing string — a library consumer hitting this at runtime has no use for an internal tracking number. Keeping it in the comment above is fine.

Suggested change

	raise ValueError(
	"Refusing to call the model: no user-role content in the assembled "
	"conversation. This usually means a stateless context (e.g. "
	"SimpleContext) was combined with an empty or whitespace-only "
	"action; recorded turns are not forwarded to the model. See "
	"issue #1597."
	)
	raise ValueError(
	"Refusing to call the model: no user-role content in the assembled "
	"conversation. This usually means a stateless context (e.g. "
	"SimpleContext) was combined with an empty or whitespace-only "
	"action; recorded turns are not forwarded to the model."
	)

[planetf1]

Same note as the OpenAI backend — drop the issue number from the user-facing message.

Suggested change

	raise ValueError(
	"Refusing to call the model: no user-role content in the assembled "
	"conversation. This usually means a stateless context (e.g. "
	"SimpleContext) was combined with an empty or whitespace-only "
	"action; recorded turns are not forwarded to the model. See "
	"issue #1597."
	)
	raise ValueError(
	"Refusing to call the model: no user-role content in the assembled "
	"conversation. This usually means a stateless context (e.g. "
	"SimpleContext) was combined with an empty or whitespace-only "
	"action; recorded turns are not forwarded to the model."
	)

[planetf1]

Same note as the other two backends — drop the issue number from the user-facing message.

Suggested change

	raise ValueError(
	"Refusing to call the model: no user-role content in the assembled "
	"conversation. This usually means a stateless context (e.g. "
	"SimpleContext) was combined with an empty or whitespace-only "
	"action; recorded turns are not forwarded to the model. See "
	"issue #1597."
	)
	raise ValueError(
	"Refusing to call the model: no user-role content in the assembled "
	"conversation. This usually means a stateless context (e.g. "
	"SimpleContext) was combined with an empty or whitespace-only "
	"action; recorded turns are not forwarded to the model."
	)

[planetf1]

Requesting changes per the two warnings in my review above — the triplicated guard logic should be factored into a shared helper, and the untested attachment pass-through branches (audio, documents) need coverage before this merges. Everything else is non-blocking.

[simonyang08]

Both points addressed in 6142775:

1. Shared guard. The triplicated check now lives in mellea/helpers/openai_compatible_helpers.py as has_user_content(messages) (docstring carries the #1597/#1587 rationale, including why whitespace-only text counts as empty and why images/audio/documents count as content), re-exported through mellea.helpers and used by all three backends. The raised message is unchanged.

2. Attachment pass-through coverage. Two new tests pin the previously untested branches: a user message with empty text but an AudioBlock reaches chat.completions.create, and one with documents=[...] (coerced via Message's documents parameter) does too — both assert the guard does not fire and the request is issued.

Verification: guard suite 12/12 (10 existing + 2 new) and the test/stdlib/components/test_chat.py suite you ran both green locally (92 tests total across the two), ruff format + lint clean on the touched files.

[planetf1]

Thanks, both blocking points are fixed in 6142775:

1. Shared guard. has_user_content() in openai_compatible_helpers.py is now the single copy, called from the OpenAI, LiteLLM, and Ollama backends.
2. Attachment coverage. The new audio and documents tests pass, and each one fails if its branch is removed from the helper, so they pin the right thing.

At 6142775 the guard suite passes 12/12 with all extras installed (LiteLLM tests included) and test_chat.py passes 80/80. I've dismissed my changes-requested review. The inline comments are non-blocking and I'll follow those up separately.

Both blocking points addressed in 6142775 (shared has_user_content helper, audio and documents test coverage). Details in the comment above.

[planetf1]

The new has_user_content() docstring fails the docs quality gate (audit_coverage.py --quality --fail-on-quality): there's no Args: entry for messages and no Returns: for the bool. That job blocks, so CI will go red once the workflow runs are approved. It also uses double backticks, which AGENTS.md rules out (CI doesn't check those yet, see #1226). This suggestion fixes both, and passes the quality gate and the RST check locally:

Suggested change

	"""Whether the assembled conversation carries real user-role content.
	Issue #1597: ``SimpleContext`` intentionally discards recorded turns from
	``view_for_generation()``, so a caller who chains ``.add(...)`` and then
	passes an empty action would otherwise hit the model with no user-role
	content at all. Some chat models (e.g. Granite 4.2, see #1587) spin on
	empty prompts and burn tokens silently. Whitespace-only text counts as
	empty; images, audio, and documents count as content.
	"""
	"""Whether the assembled conversation carries real user-role content.
	Issue #1597: `SimpleContext` intentionally discards recorded turns from
	`view_for_generation()`, so a caller who chains `.add(...)` and then
	passes an empty action would otherwise hit the model with no user-role
	content at all. Some chat models (e.g. Granite 4.2, see #1587) spin on
	empty prompts and burn tokens silently. Whitespace-only text counts as
	empty; images, audio, and documents count as content.
	Args:
	messages: The chat messages about to be sent to the model.
	Returns:
	True if any user-role message has non-whitespace text, images,
	audio, or documents; False otherwise.
	"""

[planetf1]

generate_from_chat_context lists its other ValueError cases under Raises: (line 1074) but not this one. Could you add:

            ValueError: If no user-role message has non-whitespace text,
                images, audio, or documents.

[planetf1]

This error reaches callers through the public generate_from_chat_context (line 1343), whose docstring has no Raises: section yet. Could you add one:

        Raises:
            ValueError: If no user-role message has non-whitespace text,
                images, audio, or documents.

[planetf1]

For info: I've filed #1705 for the same gap in LocalHFBackend, which builds messages through to_chat() and has no guard. It's out of scope here, so no change needed in this PR.

[simonyang08]

All three docstring points addressed in cb6a106:

1. has_user_content now carries Args: / Returns: exactly as your suggestion (and the double backticks are gone), applied verbatim from the suggestion block.
2. ollama.py generate_from_chat_context gained the ValueError case in its existing Raises: section.
3. openai.py generate_from_chat_context gained a Raises: section with the same entry.

Verified locally: audit_coverage.py --quality --fail-on-quality reports 0 issues, ruff format + lint clean on the touched files, guard suite 12/12 green.