fix(openai): preserve refusal text in traces

[ch-z-hc]

What does this PR do?

Preserves OpenAI Chat Completions refusal text in generation output, including streamed responses.

When OpenAI returns content=None and a refusal, the SDK consumer receives the refusal but the Langfuse trace loses it. Non-streaming output only contains role and content; refusal-only streams have no recorded output. This makes refused requests indistinguishable from empty responses when inspecting traces or evaluating model behavior.

The patch copies non-null refusal into chat output and accumulates streamed refusal deltas. Existing output shapes for responses without a refusal are unchanged. The field is part of the OpenAI Chat Completions streaming contract.

The regression test exercises the actual OpenAI SDK with HTTPX MockTransport and the in-memory exporter, covering sync/async clients and streaming/non-streaming responses. It verifies both the application-visible response and recorded output/usage. Before the fix, all four new cases fail; the other 37 tests in test_openai.py pass.

Type of change

• Bug fix
• New feature
• Breaking change
• Refactor
• Documentation update
• Tooling, CI, or repo maintenance

Verification

Python 3.12, locked dependencies:

uv sync --locked --python 3.12
# Windows, using the locked virtual environment:
.venv/Scripts/python.exe -m pytest tests/unit/test_openai.py tests/unit/test_openai_prompt_extraction.py -q
# Native Linux, with CI's dummy credentials and PYTEST_XDIST_AUTO_NUM_WORKERS=4:
uv run --frozen pytest -n auto --dist worksteal tests/unit -q
uv run --frozen ruff check .
uv run --frozen mypy langfuse --no-error-summary
uv run --frozen ruff format --check langfuse/openai.py tests/unit/test_openai.py
uv run --frozen pre-commit run --files langfuse/openai.py tests/unit/test_openai.py
git diff --check

• Affected unit suites: 64 passed on Windows.
• Full unit suite: 889 passed, 2 skipped on native Linux, using CI's dummy Langfuse/OpenAI credentials and four workers. Both skips are existing explicit skips (test_shutdown_and_flush, test_span_metadata_updates_in_async_context). No test was disabled or weakened for this patch.
• Ruff, mypy, changed-file formatting and applicable pre-commit hooks pass. The lock hook has no applicable files.
• Repository-wide ruff format --check . reports an existing formatting issue in unchanged tests/unit/test_media.py; left outside this patch.
• The first Windows full-suite run had missing-credential errors plus bare-python subprocess and POSIX-path failures. The relevant failures also reproduce on the unmodified base. The Linux run above passes the complete unit suite.
• E2E/live-provider suites were not run: the SDK parsing and exporter behavior are covered offline, without a running Langfuse server or paid provider calls. Other Python versions remain for CI.

Checklist

• I self-reviewed the diff using code_review.md.
• I added or updated tests for behavior changes.
• I updated docs, examples, or .env.template if needed. (Not needed: no examples or configuration become stale.)
• I did not hand-edit generated files; if generated files changed, I used the upstream regeneration path.
• I did not commit secrets or credentials.

AI assistance: Codex assisted with investigation, implementation, tests and diff self-review. This is not a claim of independent human review.

Confidence Score: 4/5

The refusal fix looks sound, but the new test must satisfy the repository’s import rule before merging.

Summary

Preserves OpenAI refusal text in completed and streamed chat traces.

• Adds offline coverage for synchronous and asynchronous clients, with and without streaming.
• Existing output paths remain unchanged when refusal is absent.
• Move the test’s httpx import to the module’s import block to satisfy the repository rule.

_{Reviews (1) · Last reviewed commit: "fix(openai): preserve refusal text in tr..." · Reviewed by Greptile}

[CLAassistant]

All committers have signed the CLA.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[chrikrah]

@ch-z-hc refusal text now lands on the generation in all four sync/async and stream/no-stream cases, and 6579cf1 is ready to go in as it stands. Your four new cases fail against main's openai.py.

$ pytest -q tests/unit/test_openai.py tests/unit/test_openai_prompt_extraction.py   # uv sync --locked, Python 3.12, openai 2.29.0
64 passed                  # head 6579cf1
4 failed, 60 passed        # langfuse/openai.py from bf11ec1, your tests kept
FAILED tests/unit/test_openai.py::test_chat_completion_captures_refusal[False-False]
FAILED tests/unit/test_openai.py::test_chat_completion_captures_refusal[True-True]
$ pytest -q tests/unit/test_openai.py   # prepare-v5-release edf44eb + this diff, Python 3.14.7, openai 2.29.0
41 passed                  # with the change
4 failed (-k refusal)      # v5's own openai.py
# not run: the e2e suites against a Langfuse server, a live OpenAI call

non-blocking: a streamed refusal now logs a {role, refusal, content} dict. Other text streams log a bare string. I'd keep the dict. The non-streamed path records the same dict, so a filter on output.refusal finds both.

@hassiebp the diff also applies onto prepare-v5-release with no conflict in openai.py, and the refusal cases pass there too. Should it land on main now, or ride along with v5?