fix(streaming): retain usage and system_fingerprint across chunks that omit them

[feiiiiii5]

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

Changes being requested

ChatCompletionStreamState._accumulate_chunk wrote snapshot.usage and snapshot.system_fingerprint from every chunk unconditionally:

completion_snapshot.usage = chunk.usage
completion_snapshot.system_fingerprint = chunk.system_fingerprint
if chunk.moderation is not None:
    completion_snapshot.moderation = cast(...)

The two lines above the moderation guard overwrite with whatever the current chunk carries, which for most chunks is None. So a stream that reports usage on one chunk and then sends a trailing chunk that omits it loses both fields — from current_completion_snapshot, from every subsequent ChunkEvent.snapshot, and from get_final_completion().

That trailing-chunk shape is not hypothetical: it is what tests/lib/chat/test_stream_moderation.py models, where a metadata chunk arrives after the content chunks. #3864 established the rule for moderation — a later chunk that omits the field retains the last report — but the two siblings immediately above it were left unconditional. This applies the same guard to both.

if chunk.usage is not None:
    completion_snapshot.usage = chunk.usage
if chunk.system_fingerprint is not None:
    completion_snapshot.system_fingerprint = chunk.system_fingerprint

src/openai/lib/streaming/chat/_completions.py +4/-2, plus a new test tests/lib/chat/test_stream_metadata_retention.py that mirrors the moderation test's structure with usage and the fingerprint reported on the first chunk and a trailing moderation chunk after them.

Reproduction

Before the change, driving the real .stream() path through a mocked SSE response (usage and system_fingerprint on chunk 0, a trailing moderation chunk at index 2), the per-chunk snapshots of usage.total_tokens are:

[11, None, None]        expected [11, 11, 11]

Driving ChatCompletionStreamState directly with the same chunk order — which is what .stream() accumulates through — shows the final object losing both fields while the sibling keeps its value:

get_final_completion().usage                 -> None
get_final_completion().system_fingerprint    -> None
get_final_completion().moderation            -> retained

The same stream with usage on the last chunk loses nothing, which is why the existing suite did not catch it — the loss is order-dependent. Reported values are never cleared by this change: a later chunk that does report usage still replaces the earlier one.

Verification

main @ bccad312, openai 3.16.1, Python 3.10.16, pydantic 2.12.5, macOS arm64, uv sync --frozen --all-extras then uv run --frozen --no-sync. The new test file is present in both runs, so the totals are directly comparable.

command (pytest -o addopts= -q)	base (main, fix reverted)	with this change
tests/lib/chat/test_stream_metadata_retention.py	2 failed — At index 1 diff: None != 11	2 passed
tests/lib/chat/test_stream_moderation.py	12 passed	12 passed
tests/lib/chat tests/lib/streaming tests/lib/responses	—	564 passed, 2 skipped
tests/lib (full)	42 failed, 2518 passed, 85 skipped	40 failed, 2520 passed, 85 skipped

I diffed the sorted FAILED lists from the two full runs: the only difference is the two new tests disappearing from it. The remaining 40 failures are pre-existing and identical on both trees — all in tests/lib/test_fine_tuning_positional_arguments.py, which needs a local echo server.

ruff format --check and ruff check are clean on both changed files.

Notes

• This is consistency with the file's own convention rather than a new rule. Every other metadata assignment in _accumulate_chunk is already guarded: finish_reason (if choice.finish_reason:), logprobs (if choice.logprobs is not None:) and moderation (if chunk.moderation is not None:, added by fix: preserve chat stream moderation results #3864). usage and system_fingerprint were the only two unconditional ones left.
• One downstream effect worth naming: at finish_reason == "length" the code raises LengthFinishReasonError(completion=completion_snapshot) with the comment "at the time of writing, .usage will always be None but we include it here in case that is changed in the future". After this change the snapshot can carry a retained usage, so that error now reports accurate usage — which is what the comment anticipates, not a behaviour it depends on being absent.
• No exported API changes, and no behaviour change for the first-party flow: with stream_options.include_usage the API sends usage on the final chunk, so the guard is a no-op there.
• The change is confined to hand-written src/openai/lib/; the Castiron report should show no new custom-code files and no changed customizations.
• Possibly worth knowing while triaging: open fix(streaming): keep chat moderation results in the accumulated snapshot #3808 also touches this function, but its source change is the moderation guard that fix: preserve chat stream moderation results #3864 already merged, so it does not cover these two fields.

Additional context & links

Follows the rule #3864 set for moderation in the same function.

[jnohclee-rgb]

Independent offline verification (AI-assisted): I independently exercised the actual ChatCompletionStreamState through seven constructed sequences: early metadata followed by omission, last-only metadata, later updates followed by omission, usage-only, fingerprint-only, never reported, and zero usage. I checked each intermediate snapshot and get_final_completion(). Main passed 2/7 sequences; this head passed 7/7. The later-update control checks replacement with the most recent non-null value; never-reported stays null. Zero usage is a constructed boundary control, not a claim about provider behavior. No SSE client or provider was exercised.

Compared main 919b6236382f3f9f76d8453efb9f9ad03cff1126 with this PR head 838fc65d70865c6d2bdb92cdd2608eb0a3ffe809 using Python 3.14.7 and a shared existing dependency environment (not a historical lockfile matrix). Source trees were isolated; runs denied network access. This is bounded additional evidence, not full SDK or merge approval.

Reproducer, runnable separately against each source tree:

import json
from openai.types.chat import ChatCompletionChunk
from openai.lib.streaming.chat import ChatCompletionStreamState
import openai.lib.streaming.chat._completions as source
sequences=[('early_then_omitted',[(11,'fp-a'),(None,None),(None,None)]),('last_only',[(None,None),(None,None),(11,'fp-a')]),('later_update',[(11,'fp-a'),(13,'fp-b'),(None,None)]),('usage_only',[(11,None),(None,None)]),('fingerprint_only',[(None,'fp-a'),(None,None)]),('never_reported',[(None,None),(None,None)]),('zero_usage',[(0,'fp-a'),(None,None)])]
rows=[]
for label,parts in sequences:
 state=ChatCompletionStreamState();expected_usage=None;expected_fp=None;observations=[]
 for i,(tokens,fp) in enumerate(parts):
  usage=None if tokens is None else {'prompt_tokens':tokens,'completion_tokens':0,'total_tokens':tokens}
  delta={'role':'assistant','content':'fictional'} if i==0 else {}
  chunk=ChatCompletionChunk(id='fictional',object='chat.completion.chunk',created=0,model='fictional',choices=[{'index':0,'delta':delta,'finish_reason':'stop' if i==len(parts)-1 else None}],usage=usage,system_fingerprint=fp)
  list(state.handle_chunk(chunk))
  if tokens is not None:expected_usage=tokens
  if fp is not None:expected_fp=fp
  snapshot=state.current_completion_snapshot
  observations.append({'actual_usage':snapshot.usage.total_tokens if snapshot.usage else None,'expected_usage':expected_usage,'actual_fp':snapshot.system_fingerprint,'expected_fp':expected_fp})
 final=state.get_final_completion()
 ok=all(o['actual_usage']==o['expected_usage'] and o['actual_fp']==o['expected_fp'] for o in observations)
 ok=ok and (final.usage.total_tokens if final.usage else None)==expected_usage and final.system_fingerprint==expected_fp
 rows.append({'case':label,'pass':ok,'snapshots':observations})
print(json.dumps({'source_module':source.__file__,'passed':sum(r['pass'] for r in rows),'failed':sum(not r['pass'] for r in rows),'cases':rows,'scope':'Actual ChatCompletionStreamState with fictional constructed chunks; not client SSE/provider proof. Zero totals are a constructed boundary control.'}))