kaxil commented on code in PR #72049:
URL: https://github.com/apache/airflow/pull/72049#discussion_r3993025136
##########
providers/openai/docs/operators/openai.rst:
##########
@@ -58,6 +58,54 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See the `Responses API reference
+<https://platform.openai.com/docs/api-reference/responses/create>`__ for the
authoritative list
+of parameters. ``response_kwargs`` passes straight through to the underlying
``create_response``
+call, so most keyword arguments the Responses API accepts can be set there,
with the exceptions
+noted below. Options worth knowing about:
+
+- ``background``: run the response asynchronously on OpenAI's side. See the
note below before
+ using this with ``OpenAIResponseOperator``.
+- ``stream``: return a stream of response events instead of a single completed
response. Do not
+ set this on ``OpenAIResponseOperator``: ``execute`` reads
``response.status`` and
+ ``response.output_text``, neither of which exists on the streamed response
object, so the task
+ raises ``AttributeError``. Stream responses from a ``@task`` using
+ :class:`~airflow.providers.openai.hooks.openai.OpenAIHook` instead.
+- ``store``: whether the response is retained on OpenAI's side, for example so
it can later be
+ used as a ``previous_response_id``.
+- ``reasoning``: reasoning configuration for reasoning models.
+- ``service_tier``: currently one of ``'auto'``, ``'default'``, ``'flex'``,
``'scale'`` or
Review Comment:
This enumeration is already wrong for anyone installing the provider today,
so I'd fix it before merge. I read the `service_tier` Literal in
`response_create_params.py` at three versions: `auto, default, flex, scale,
priority` at the 2.37.0 floor, plus `fast` at 2.54.0, plus `ultrafast` at
3.13.0. The pin is `openai>=2.37.0` with no upper bound
(`providers/openai/pyproject.toml:70`), so a fresh install resolves 3.13.0 and
this bullet tells the reader two valid tiers don't exist. Now that the section
links the API reference at the top, dropping the values and keeping "selecting
the processing tier the request is served from" stays correct on its own.
`truncation` doesn't need the same treatment: its Literal is identical at
2.37.0 and 3.13.0.
##########
providers/openai/docs/operators/openai.rst:
##########
@@ -58,6 +58,54 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See the `Responses API reference
+<https://platform.openai.com/docs/api-reference/responses/create>`__ for the
authoritative list
+of parameters. ``response_kwargs`` passes straight through to the underlying
``create_response``
+call, so most keyword arguments the Responses API accepts can be set there,
with the exceptions
+noted below. Options worth knowing about:
+
+- ``background``: run the response asynchronously on OpenAI's side. See the
note below before
+ using this with ``OpenAIResponseOperator``.
+- ``stream``: return a stream of response events instead of a single completed
response. Do not
+ set this on ``OpenAIResponseOperator``: ``execute`` reads
``response.status`` and
+ ``response.output_text``, neither of which exists on the streamed response
object, so the task
+ raises ``AttributeError``. Stream responses from a ``@task`` using
+ :class:`~airflow.providers.openai.hooks.openai.OpenAIHook` instead.
+- ``store``: whether the response is retained on OpenAI's side, for example so
it can later be
+ used as a ``previous_response_id``.
+- ``reasoning``: reasoning configuration for reasoning models.
+- ``service_tier``: currently one of ``'auto'``, ``'default'``, ``'flex'``,
``'scale'`` or
+ ``'priority'``, selecting the processing tier the request is served from.
+- ``prompt_cache_key``: an identifier used to route requests to the same
prompt cache.
+- ``safety_identifier``: a stable identifier for the end user, used for safety
and abuse
+ detection.
+- ``truncation``: one of ``'auto'`` or ``'disabled'``, controlling whether the
model truncates
+ context that exceeds its window.
+- ``include``: additional output fields to include in the response, such as
encrypted reasoning
Review Comment:
`include` has no observable effect through this operator, and `store`'s
stated reason (line 77) doesn't hold either, so both bullets send readers down
dead ends. `execute` returns `response.output_text` and nothing else, and
`response.id` only reaches `self.log` (`operators/openai.py:133`, `:136`), so
the extra output fields `include` asks for are fetched and discarded, and no id
reaches a downstream task to use as a `previous_response_id`. The class
docstring already says this at `operators/openai.py:87-88` (use the hook for
`previous_response_id` chaining or the full structured response), so marking
both bullets hook-only, the way `stream` and `background` now are, would make
the page agree with itself. This is the same dead end as my round-1 note on the
background admonition, one bullet higher up.
##########
providers/openai/docs/operators/openai.rst:
##########
@@ -58,6 +58,54 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See the `Responses API reference
+<https://platform.openai.com/docs/api-reference/responses/create>`__ for the
authoritative list
+of parameters. ``response_kwargs`` passes straight through to the underlying
``create_response``
+call, so most keyword arguments the Responses API accepts can be set there,
with the exceptions
+noted below. Options worth knowing about:
+
+- ``background``: run the response asynchronously on OpenAI's side. See the
note below before
+ using this with ``OpenAIResponseOperator``.
+- ``stream``: return a stream of response events instead of a single completed
response. Do not
+ set this on ``OpenAIResponseOperator``: ``execute`` reads
``response.status`` and
+ ``response.output_text``, neither of which exists on the streamed response
object, so the task
+ raises ``AttributeError``. Stream responses from a ``@task`` using
+ :class:`~airflow.providers.openai.hooks.openai.OpenAIHook` instead.
+- ``store``: whether the response is retained on OpenAI's side, for example so
it can later be
+ used as a ``previous_response_id``.
+- ``reasoning``: reasoning configuration for reasoning models.
Review Comment:
Collecting the smaller things here so they're all in one pass, none of them
merge-gating.
This bullet defines the option with its own name and drops the SDK's first
line, "**gpt-5 and o-series models only**". That matters because the operator
defaults to `gpt-4o-mini` and the example DAG keeps the default, so the reader
most likely to try `reasoning` is the one it won't work for. Naming `{"effort":
...}` would also make the bullet actionable.
`prompt_cache_retention` (`Literal["in_memory", "24h"]`) exists at the floor
version and is missing next to `prompt_cache_key` on line 82; it's the half
that decides whether a scheduled DAG's next run still hits the cache.
`previous_response_id` and `conversation` cannot be combined, verbatim from
the SDK: "Cannot be used in conjunction with `conversation`." The page offers
both as example `response_kwargs` (line 53 and `operators/openai.py:95`), and
combining them is the likeliest route to a 400.
On line 70, "See the note below" has two candidates under it, the spend note
at line 93 and the background note at line 99, and the nearer one is the
unrelated one.
##########
providers/openai/docs/operators/openai.rst:
##########
@@ -58,6 +58,54 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See the `Responses API reference
+<https://platform.openai.com/docs/api-reference/responses/create>`__ for the
authoritative list
+of parameters. ``response_kwargs`` passes straight through to the underlying
``create_response``
+call, so most keyword arguments the Responses API accepts can be set there,
with the exceptions
Review Comment:
One caveat worth adding here: what you can pass is gated by the installed
`openai` version, not by the API reference. `Responses.create` takes no
`**kwargs` at any version I checked (2.37.0, 2.54.0, 3.13.0), so a parameter
that exists on the reference page but not in the installed SDK fails before the
request is made, with `TypeError: Responses.create() got an unexpected keyword
argument '...'`. `extra_body` is the escape hatch that does reach the API. A
sentence to that effect saves a confusing traceback for anyone who copies a
newly announced parameter off that page.
##########
providers/openai/src/airflow/providers/openai/operators/openai.py:
##########
@@ -93,6 +93,9 @@ class OpenAIResponseOperator(BaseOperator):
:param model: The OpenAI model to use.
:param response_kwargs: Additional keyword arguments to pass to the OpenAI
``create_response``
method (for example ``instructions``, ``tools``, ``conversation`` or
``previous_response_id``).
+ See :ref:`howto/operator:OpenAIResponseOperator` for the additional
options this operator
Review Comment:
This docstring ends up softer than the guide it points at, which I'd rather
not ship in the same PR that tightened the guide. The guide now says "Do not
set `background=True` on `OpenAIResponseOperator`" (`openai.rst:105`), while
this reads "a note on why `background=True` needs care", so a reader who stops
here takes it for a caveat. The line also names `background` but not `stream`,
which is the harder of the two: `background=True` returns empty output plus a
log warning, `stream=True` raises `AttributeError` and fails the task.
##########
providers/openai/docs/operators/openai.rst:
##########
@@ -58,6 +58,54 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See the `Responses API reference
+<https://platform.openai.com/docs/api-reference/responses/create>`__ for the
authoritative list
+of parameters. ``response_kwargs`` passes straight through to the underlying
``create_response``
+call, so most keyword arguments the Responses API accepts can be set there,
with the exceptions
+noted below. Options worth knowing about:
+
+- ``background``: run the response asynchronously on OpenAI's side. See the
note below before
+ using this with ``OpenAIResponseOperator``.
+- ``stream``: return a stream of response events instead of a single completed
response. Do not
+ set this on ``OpenAIResponseOperator``: ``execute`` reads
``response.status`` and
+ ``response.output_text``, neither of which exists on the streamed response
object, so the task
+ raises ``AttributeError``. Stream responses from a ``@task`` using
+ :class:`~airflow.providers.openai.hooks.openai.OpenAIHook` instead.
+- ``store``: whether the response is retained on OpenAI's side, for example so
it can later be
+ used as a ``previous_response_id``.
+- ``reasoning``: reasoning configuration for reasoning models.
+- ``service_tier``: currently one of ``'auto'``, ``'default'``, ``'flex'``,
``'scale'`` or
+ ``'priority'``, selecting the processing tier the request is served from.
+- ``prompt_cache_key``: an identifier used to route requests to the same
prompt cache.
+- ``safety_identifier``: a stable identifier for the end user, used for safety
and abuse
+ detection.
+- ``truncation``: one of ``'auto'`` or ``'disabled'``, controlling whether the
model truncates
Review Comment:
These two bullets drop the half of the SDK docstring that decides the
outcome. For `truncation`, `disabled` is the default, and the docstring says
that with it "the request will fail with a 400 error" once input exceeds the
context window; `auto` is the opt-in that truncates. As written it reads as a
choice between two ways of truncating, so someone debugging context-window 400s
would not learn the default is the failing one. For `max_output_tokens` (line
90), the SDK adds "including visible output tokens and reasoning tokens", which
bears on the spend note below since the invisible half is billed too.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
