fix(streaming): return final response for incomplete and failed events

[hsusul]

• I understand that this repository is auto-generated and my pull request may not be merged

Changes being requested

Summary

ResponseStream.get_final_response() / AsyncResponseStream.get_final_response() only stored a final ParsedResponse when a response.completed event arrived. Terminal response.incomplete and response.failed events already carry a full Response payload (for example after max_output_tokens truncation), but calling get_final_response() after those streams still raised:

RuntimeError: Didn't receive a `response.completed` event.

This change treats response.incomplete and response.failed as terminal events in ResponseStreamState.accumulate_event, matching:

• the OpenAI Node SDK ResponseAccumulator (response.completed | response.failed | response.incomplete)
• Assistants streaming helpers, which update the final run on incomplete/failed
• Chat Completions get_final_completion(), which returns the snapshot regardless of finish_reason

The touched code lives under src/openai/lib/, which CONTRIBUTING.md states is not modified by the generator.

Problem

Minimal reproduction (no API key):

from openai import omit
from openai._models import construct_type
from openai.types.responses import ResponseCreatedEvent, ResponseIncompleteEvent
from openai.lib.streaming.responses._responses import ResponseStreamState

minimal = {
    "id": "resp_test",
    "object": "response",
    "created_at": 0,
    "status": "in_progress",
    "model": "gpt-4o-mini",
    "output": [],
    "parallel_tool_calls": True,
    "tool_choice": "auto",
    "tools": [],
}

state = ResponseStreamState(input_tools=omit, text_format=omit)
state.handle_event(construct_type(type_=ResponseCreatedEvent, value={
    "type": "response.created",
    "sequence_number": 0,
    "response": minimal,
}))
state.handle_event(construct_type(type_=ResponseIncompleteEvent, value={
    "type": "response.incomplete",
    "sequence_number": 1,
    "response": {**minimal, "status": "incomplete"},
}))
assert state._completed_response is None  # bug: should be the incomplete ParsedResponse

Current behavior

• response.completed → _completed_response is set; get_final_response() succeeds
• response.incomplete / response.failed → _completed_response stays None; get_final_response() raises RuntimeError

Corrected behavior

All three terminal events populate _completed_response via parse_response(...). Sync and async get_final_response() return that parsed response. If no terminal event was seen, the error message now says a terminal response event was missing.

Root cause

accumulate_event only handled response.completed when assigning _completed_response.

Implementation

Smallest change in src/openai/lib/streaming/responses/_responses.py:

• store the parsed response for response.incomplete and response.failed
• document terminal-event requirement on sync/async get_final_response()
• update the missing-terminal-event RuntimeError message

No public request/response shapes changed. No generated API resources/types edited.

Regression tests

Added tests/lib/responses/test_response_stream_final.py:

• stream state stores final response for completed / incomplete / failed
• no terminal event → no final response
• sync + async get_final_response() for all three terminal events
• sync + async error when the stream ends without a terminal event

Validation

Pre-fix (expected failures on incomplete/failed paths):

PYTHONPATH=src python -m pytest tests/lib/streaming/test_response_stream_final.py -q
# 8 failed, 4 passed

Post-fix:

PYTHONPATH=src python -m pytest tests/lib/responses/test_response_stream_final.py tests/lib/responses/test_responses.py -q
# 19 passed

ruff format --check <changed files>   # pass
ruff check <changed files>            # pass
./scripts/run-pyright src/openai/lib/streaming/responses/_responses.py tests/lib/responses/test_response_stream_final.py
# 0 errors
mypy src/openai/lib/streaming/responses/_responses.py
# Success
python -m build
# Successfully built openai-2.48.0.tar.gz and openai-2.48.0-py3-none-any.whl
git diff --check
# clean

Not run / limitations:

• Full ./scripts/test against the Steady mock server (requires ./scripts/mock)
• Full ./scripts/lint via Rye (local validation used the project .venv tools equivalent to ruff/pyright/mypy/import check for the changed files)
• Chat completions inline-snapshot tests fail under pytest-xdist on clean upstream/main as well (pre-existing; unrelated)

Compatibility

• Successful response.completed streams are unchanged
• Callers that previously got RuntimeError on incomplete/failed streams now receive the terminal ParsedResponse (inspect status / incomplete_details / error as needed)
• Exception message text for the no-terminal-event case changed slightly

Additional context & links

• Analyzed against upstream/main @ 8a6adcb3 (release 2.48.0)
• Related but distinct open work: Responses streaming structured output parses incomplete JSON before terminal incomplete status #3263 / fix: defer parsing incomplete streamed text #3378 (defer structured-output parse until incomplete is known) — does not set _completed_response for incomplete/failed
• Node parity: openai-node ResponseAccumulator handles response.completed | response.failed | response.incomplete together

[gnanirahulnutakki]

Reviewed exact commit 9ebe10435f1184ca0852cadac531c3121fb491a5. The existing targeted suite passes (19 tests) and the changed files pass Ruff, but an isolated structured-output reproduction exposes one correctness issue on the new incomplete/failed paths.

[gnanirahulnutakki]

Avoid parsing truncated structured output on terminal failures

parse_response() calls the strict parse_text() path for every output text, so this raises before the terminal response can be stored whenever an incomplete structured output contains partial JSON. On this exact head I reproduced it with text_format=Answer and a response.incomplete payload whose text is {"value": and incomplete_details.reason == "max_output_tokens"; handle_event() raises Pydantic ValidationError. The same happens for response.failed, while the base commit accepts both events without attempting the parse. Consequently get_final_response() still cannot return the terminal response in the structured-output case this change is meant to fix. All new tests use text_format=omit, so they do not cover this branch. Please preserve the terminal response without strict structured parsing (for example, leave parsed unset for non-completed responses) and add incomplete/failed tests with a supplied Pydantic text format.

[hsusul]

Thanks — confirmed and fixed on this PR.

For response.incomplete / response.failed we now store the terminal response via parse_response(..., text_format=omit, input_tools=omit) so truncated structured JSON (and truncated tool args) no longer raise before get_final_response() can return. response.completed still uses the strict text_format path.

Added regression coverage with text_format=_Answer and truncated payload text {"value": for both incomplete and failed, plus sync/async get_final_response() cases and a completed-path sanity check that still parses successfully.

[gnanirahulnutakki]

Verified the fix on e896c03a2ac9136bfc348195faadf4b037194b28. Incomplete and failed terminal responses now bypass strict structured-output and tool-argument parsing, while the completed path still parses normally. The focused suite passes all 19 tests, including the new sync/async truncated-Pydantic cases, and both changed files pass Ruff lint and format checks.

[jnohclee-rgb]

AI-assisted independent offline check at e896c03a2ac9136bfc348195faadf4b037194b28, compared with pinned main 919b6236382f3f9f76d8453efb9f9ad03cff1126.

18/18 controls pass on this head versus 6/18 on pinned main. This supplements the existing text-output tests with Pydantic function tools converted by SDK _make_tools. Sync/async final accessors retain valid, truncated and schema-invalid arguments as raw strings with parsed_arguments=None for incomplete/failed terminal events, alongside usage/error/incomplete details. Completed valid arguments still parse and completed invalid/truncated arguments still raise ValidationError.

Scope: Constructed response.created + terminal event sequences over an in-memory iterator. No earlier function-arguments-done/text-done events are included, so this does not establish a fix for the earlier structured parsing concerns in #3378 or every provider event sequence. No transport or service calls. Python 3.14.7 / Pydantic 2.13.5 and shared local dependencies; this is a bounded matrix, not a full SDK suite or historical dependency matrix. Network denied by the sandbox.

Standalone reproducer (run separately with each source tree on PYTHONPATH)

import json,asyncio,pydantic,importlib
from openai import omit,pydantic_function_tool
from openai._models import construct_type_unchecked
from openai.types.responses import ResponseStreamEvent
from openai.lib.streaming.responses import ResponseStream,AsyncResponseStream
from openai.resources.responses.responses import _make_tools
class Tool(pydantic.BaseModel):n:int
class Raw:
 def __init__(self,events):self.events=events;self.response=None
 def __iter__(self):return iter(self.events)
 async def __aiter__(self):
  for e in self.events:yield e
 def close(self):pass
 async def aclose(self):pass
async def main():
 rows=[]
 for async_ in [False,True]:
  for status in ['completed','incomplete','failed']:
   for name,args in [('valid','{"n":3}'),('truncated','{"n":'),('invalid','{"n":"wrong"}')]:
    output={'type':'function_call','id':'fictional','call_id':'fictional','name':'Tool','arguments':args,'status':'completed' if status=='completed' else 'incomplete'}
    base={'id':'fictional','object':'response','created_at':0,'model':'fictional','parallel_tool_calls':True,'tool_choice':'auto','tools':[],'output':[],'status':'in_progress'}
    terminal={**base,'output':[output],'status':status,'usage':{'input_tokens':2,'output_tokens':3,'total_tokens':5,'input_tokens_details':{'cached_tokens':0},'output_tokens_details':{'reasoning_tokens':0}}}
    if status=='incomplete':terminal['incomplete_details']={'reason':'max_output_tokens'}
    if status=='failed':terminal['error']={'code':'server_error','message':'fictional'}
    events=[construct_type_unchecked(type_=ResponseStreamEvent,value={'type':'response.created','sequence_number':0,'response':base}),construct_type_unchecked(type_=ResponseStreamEvent,value={'type':'response.'+status,'sequence_number':1,'response':terminal})]
    stream=(AsyncResponseStream if async_ else ResponseStream)(raw_stream=Raw(events),text_format=omit,input_tools=_make_tools([pydantic_function_tool(Tool)]),starting_after=None)
    kind=None;actual=None
    try:
     result=await stream.get_final_response() if async_ else stream.get_final_response();call=result.output[0]
     actual={'status':result.status,'arguments':call.arguments,'parsed':call.parsed_arguments.model_dump() if isinstance(call.parsed_arguments,pydantic.BaseModel) else call.parsed_arguments,'tokens':result.usage.total_tokens,'error':result.error.message if result.error else None,'incomplete':result.incomplete_details.reason if result.incomplete_details else None}
    except Exception as exc:kind=type(exc).__name__
    expected_error='ValidationError' if status=='completed' and name!='valid' else None
    expected={'status':status,'arguments':args,'parsed':{'n':3} if status=='completed' else None,'tokens':5,'error':'fictional' if status=='failed' else None,'incomplete':'max_output_tokens' if status=='incomplete' else None}
    rows.append({'async':async_,'status':status,'arguments_case':name,'exception':kind,'actual':actual,'pass':kind==expected_error and (expected_error is not None or actual==expected)})
 print(json.dumps({'cases':rows,'passed':sum(x['pass'] for x in rows),'failed':sum(not x['pass'] for x in rows),'scope':'Actual final-response accessor over constructed terminal tool events; no earlier argument-done events, network or provider event sequence proof.'}))
asyncio.run(main())