Normalize finish_reason across providers#321
Merged
Merged
Conversation
|
FYI, I've extended the list of standard values in tidyverse/ellmer#1039 to also include "tool_use" as it was raising unnecessary warnings. |
Maps provider-specific stop reasons to a common vocabulary: "success", "max_tokens", "content_filter", "stop_sequence", "context_window". Unknown reasons pass through as-is. Also fixes OpenAI streaming to handle `response.incomplete` events so truncated responses are returned rather than silently dropped. Mirrors tidyverse/ellmer#1015.
cpsievert
force-pushed
the
feat/finish-reason-normalization
branch
from
July 21, 2026 18:07
1615e61 to
b9b9dd4
Compare
Anthropic's stop_reason and OpenAI completions' finish_reason both use provider-specific spellings for "the model wants to call a tool" (tool_use / tool_calls). Map both explicitly to "tool_use" so callers get a consistent value instead of a provider-specific string leaking through unnormalized. Mirrors tidyverse/ellmer#1039.
Now that finish_reason is normalized to a shared vocabulary across providers, type it as a Literal (with a str fallback for reasons chatlas doesn't yet recognize) instead of a bare str.
Each provider's _*_FINISH_REASON_MAP now declares its value type as FinishReason, documenting that every mapped value is one of the known reasons. normalize_finish_reason()'s return type drops the redundant `FinishReason |` prefix (pyright collapses `Literal[...] | str` down to plain `str` anyway) since these functions pass unrecognized reasons through unchanged, matching ellmer's value_finish_reason() behavior.
- Normalize OpenAI Responses API finish_reason to "tool_use" when the output contains a function_call, since status alone is "completed" even for tool-calling turns. - Fix line length in test_provider_google.py import. - Correct misleading comment on FinishReason type alias. - Soften changelog wording since SnowflakeProvider doesn't yet set finish_reason.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mirrors tidyverse/ellmer#1015 (and #1039 for the
tool_useaddition below).What's now possible
turn.finish_reasonreturns a consistent vocabulary regardless of which provider you're using:"success""tool_use""max_tokens""content_filter""stop_sequence""context_window"Unknown provider-specific reasons pass through as-is so callers can still inspect them.
Changes
normalize_finish_reason()function with a mapping dict keyed to the upstream API docsAssistantTurn.finish_reasonis now set by calling that function rather than storing the raw provider stringresponse.incompleteevents are now handled instream_merge_chunksso truncated streaming responses are returned rather than silently droppedfinish_reason == "stop"/"end_turn"/"STOP"assertions in provider tests updated to"success"Nonehandlingtool_useand OpenAI completions'tool_callsnow both normalize to"tool_use"instead of leaking through as provider-specific strings, per thisisnic's comment