feat: surface reasoning-only truncation on the chat completions API

[bebekim]

Summary

Adds an additive reasoning_only: true field to chat completion responses (both streaming and non-streaming) when a generation produced tokens but content came back empty because everything stayed in the reasoning channel — today that case is silent and indistinguishable from a clean, intentionally empty response.

Related issues

Closes #1745
Refs #467
Refs #1721

(Neither #467 nor #1721 is a full duplicate: #467's fix only logs server-side, and only when the prompt itself primed an open thinking block; #1721 only fixed the CLI's generate/chat display. This generalizes past both to cover the far more common shape — a plain, unprimed request that opens its own <think> block and exhausts its token budget — and surfaces it to the actual API response, not just a log or a terminal.)

Type of change

• feat — new user-visible feature

Test plan

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --features metal,accelerate -- -D warnings
• cargo test --workspace --profile test-fast --features metal,accelerate --no-fail-fast -- --test-threads=1 (full workspace: 10,605 passed, 0 failed)
• cargo deny check
• Validated with a real checkpoint: mlx-community/Qwen3.5-4B-MLX-4bit. Built baseline and patched release binaries from the same commit (stash/build/pop, mirroring ab_output_equality.sh's own pattern) and compared live server responses:
  • Truncated mid-thought, non-streaming: before → content:"", finish_reason:"length", no signal. After → same, plus "reasoning_only": true.
  • Truncated mid-thought, streaming: before → delta:{} on the finish chunk. After → delta:{"reasoning_only":true}.
  • Real completion (--reasoning-budget 40, reaches finish_reason:"stop"): field correctly absent in both paths, before and after — no regression on the common case.
• N/A — no arithmetic/generation-numerics touched (pure response-shaping), so the teacher-forced logit trace doesn't apply here.

Notes for reviewers

• Design choice: an additive boolean field rather than overloading finish_reason, matching the precedent already set for reasoning_content — existing OpenAI-schema clients that validate finish_reason as an enum are unaffected.
• reasoning_stream::is_reasoning_only (added for feat(cli): say when a generation went entirely to the reasoning channel #1721) is reused as-is with show_reasoning: false fixed at both server call sites — the server never suppresses reasoning into a hidden channel, so passing false correctly fires whenever content is empty and generation happened, independent of priming.
• Non-streaming: threaded through the two response arms where empty content is actually anomalous; deliberately not attached in the tool-calls-succeeded arm, where empty content is normal/expected by OpenAI convention.
• Streaming: added StreamCallbackState::saw_content, updated from a single check over the finalized per-token chunk batch (chunk_carries_content) plus the end-of-stream flush, read once at the terminal chunk.
• primed_thinking_unclosed keeps its original job (driving strip_unclosed_primed_thinking's content-emptying) — only the log that used to key off it directly was generalized.

Checklist

• PR title uses a Conventional Commits prefix (feat:)
• One logical change per PR
• Updated docs/: N/A — no existing doc describes the chat completions response schema field-by-field
• Updated // Used by: ... — extended is_reasoning_only's doc comment to name the new server call site
• No secrets, credentials, or .env files committed

[cla-assistant]

All committers have signed the CLA.

[inureyes]

Hardening pass on this PR

Reviewed against #1745 (and the #467 / #1721 framing). The design holds: an additive Option<bool> that is never Some(false), reusing is_reasoning_only so the CLI and the API agree, and excluding the non-streaming tool-calls arm were all the right calls. The type-level work, the skip_serializing_if omission, and the end-of-stream flush accounting are correct as authored. One commit on top, 88816432, closes two false positives.

Streaming tool calls were flagged as reasoning-only

is_reasoning_only reduces to "raw text non-empty and shaped content empty", which never checks that reasoning happened. FilterState::ToolCall suppresses the whole tool-call payload from delta.content, so a model answering with nothing but a tool call, the ordinary shape, reaches the finish chunk with saw_content false and a non-empty result.text. That chunk carried reasoning_only: true beside finish_reason: "tool_calls". You excluded exactly this arm in the non-streaming path and called it out in the PR body; the streaming path had no equivalent, so the two surfaces disagreed on the same turn.

Marker-only output claimed a channel it never used

clean_structural_tokens empties content for a generation containing no thinking block at all. A Gemma 4 turn that is nothing but <turn|> / <channel|> / <|tool_call> markers, which its own doc comment says happens when a request carries no tools, leaves reasoning_content None and still reported reasoning-only.

Fix

Both paths now require that reasoning reached the client: non-streaming gates on the shaped reasoning_content, streaming tracks saw_reasoning_content over the same finalized chunk batch saw_content already used, flush included. The finish-time decision moved into stream_reasoning_only, so its three conditions are testable without a live model. This cannot suppress a true positive: deepseek / auto populate reasoning_content, and none / deepseek-legacy keep thoughts in content, which is then non-empty and fails the emptiness check anyway.

Validation

31 targeted tests pass. Reverting each gate separately fails exactly its own test and no others. cargo fmt --all -- --check and cargo clippy -p mlxcel --lib --tests -- -D warnings both exit 0.

Not re-run here: your real-checkpoint check against mlx-community/Qwen3.5-4B-MLX-4bit. This box is Linux/CUDA, and the gates added are pure response-shaping with no generation numerics, so the live comparison you recorded still stands. Worth one streamed tool-call request against a tools-capable checkpoint before merge if you have one handy.

Security and performance: no auth, input-validation, or allocation behavior touched; the added work is one bool per chunk batch on a path that already scanned it.

Refs #1745