uranusjr commented on code in PR #74695: URL: https://github.com/apache/airflow/pull/74695#discussion_r4534405075
########## providers/common/ai/src/airflow/providers/common/ai/utils/tool_prefix.py: ########## @@ -0,0 +1,54 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +"""The ``tool_prefix`` handling shared by the toolsets that namespace their tool names.""" + +from __future__ import annotations + + +def validate_tool_prefix(tool_prefix: str) -> None: + """Raise ``ValueError`` if a non-empty ``tool_prefix`` is not a valid Python identifier.""" + if tool_prefix and not tool_prefix.isidentifier(): + # The prefixed names are rendered as Python function signatures under + # code mode, so a name that is not an identifier breaks there. + raise ValueError(f"tool_prefix must be a valid Python identifier, got {tool_prefix!r}.") + + +class ToolPrefixMixin: + """Build, and map back from, the tool names and the toolset id that a ``tool_prefix`` produces.""" + + _tool_prefix: str = "" + + def _set_tool_prefix(self, tool_prefix: str) -> None: + validate_tool_prefix(tool_prefix) + self._tool_prefix = tool_prefix + + def _build_tool_name(self, base: str) -> str: + return f"{self._tool_prefix}_{base}" if self._tool_prefix else base + + def _strip_tool_prefix(self, name: str) -> str: + """Return ``name`` without the prefix; a name that does not carry it is returned unchanged.""" + return name.removeprefix(f"{self._tool_prefix}_") if self._tool_prefix else name + + def _find_base_tool_name(self, name: str) -> str | None: + """Return ``name`` without the prefix, or ``None`` when a prefix is set and ``name`` does not carry it.""" + if not self._tool_prefix: + return name + prefix = f"{self._tool_prefix}_" + return name.removeprefix(prefix) if name.startswith(prefix) else None Review Comment: These are essentially the same; callers of `_strip_tool_prefix` simply use `"Unknown tool"` instead of None. Keep one. ########## providers/common/ai/src/airflow/providers/common/ai/operators/llm.py: ########## @@ -263,7 +274,7 @@ def __init__( model_id: str | None = None, fallback_conn_ids: list[str] | None = None, system_prompt: str = "", - output_type: type | UnionType = str, + output_type: type | UnionType | Sequence[type] = str, Review Comment: Output markers (`ToolOutput(...)`, `NativeOutput(...)`) and output functions are documented as supported, but not a part of the annotation. Use pydantic-ai's `OutputSpec[Any]`? ########## providers/common/ai/docs/structured_output.rst: ########## @@ -109,5 +113,45 @@ class is not auto-registered. Add the class qualified name to that pattern work. If a downstream consumer needs the dict shape (e.g. forwarding to an external -system that expects JSON-style payloads), pass ``serialize_output=True`` and the -operator calls ``model_dump()`` before pushing to XCom. +system that expects JSON-style payloads), the operator can push the model dumped +instead of as an instance. Whether it does depends on ``serialize_output``: + +* With ``serialize_output=True``, an output that is itself a model is dumped with ``model_dump()``, so + field types such as ``date`` and ``Decimal`` are kept. +* A model inside a list, tuple, set or dict is not dumped when the worker registers its class + (``output_type=list[MyModel]`` on Airflow 3.3 and later). The XCom serializer pushes it as an + instance, with or without ``serialize_output``. +* A model whose class the worker cannot register is dumped to JSON values, whatever ``serialize_output`` + says. The one exception is a model that is itself the output when ``serialize_output=True``: it is + still dumped, but in Python mode as the first bullet describes. The worker registers the classes it + finds by reading ``output_type``, and finds none in a list of types such as + ``output_type=[MyModel, int]``, so a ``MyModel`` output of that shape is dumped. +* ``LLMOperator``, ``@task.llm``, ``LLMFileAnalysisOperator``, ``AgentOperator`` and ``@task.agent`` dump the + whole output with ``to_jsonable_python``, using field names rather than aliases (also for a model that + sets ``serialize_by_alias=True``), as soon as it holds such a model in a list, tuple, set or dict, as a + set member or as a dict key. A ``date`` or ``Decimal`` next to the model becomes a string. + +In a dump to JSON values, ``HttpUrl``, ``Path`` and ``Enum`` fields become plain JSON values. A model +that is itself the output with ``serialize_output=True`` keeps its Python field values instead, so an +``HttpUrl``, a ``Path`` or a plain ``Enum`` member in it stays an object that the default XCom backend +cannot serialize. + +Behaviour of the LLM operators after 1.1.0 +------------------------------------------- + +The changelog note above 1.1.0 describes changes made after that release. ``LLMOperator``, +``@task.llm``, ``LLMFileAnalysisOperator``, ``AgentOperator`` and ``@task.agent`` share one +helper, ``dump_output_for_xcom``, and behave as follows: + +* A model whose class the worker registers is left for the XCom serializer, in a container or not. + A top-level model is dumped with ``model_dump()`` (Python field values kept) when + ``serialize_output=True`` is set. +* A model whose class the worker cannot register is dumped to JSON values, also inside a list, + tuple, set or dict. +* Before Airflow 3.3, or with a task-sdk that has no deserialization walker, the worker registers no + class, so every model is dumped, a top-level one included. A top-level model is dumped with + ``model_dump()`` when ``serialize_output=True`` is set, and otherwise to JSON values with field + names rather than aliases, like a model inside a list, tuple, set or dict. ``LLMOperator``, + ``@task.llm`` and ``LLMFileAnalysisOperator`` pushed ``list[MyModel]``, and a top-level model + without ``serialize_output=True``, as instances there in 1.1.0 and now push dicts; Review Comment: These lines say that before 3.3, a top-level model without `serialize_output=True` is now dumped to JSON values, and that the LLM operators pushed it as an instance in 1.1.0. But the implementation still sets `self._serialize_model_output = serialize_output or not _CORE_WALKER`. Without the walker, the operators always pass `serialize_output=True`, so a top-level model gets `model_dump()`, as it did in 1.1.0. ########## providers/common/ai/docs/changelog.rst: ########## @@ -34,6 +34,39 @@ Changelog argument the task is called with, positional ones included, can be referenced in it by name; see the ``@task.llm`` documentation for how to include text from function arguments in it. +.. note:: + **Significant change: output serialization of the LLM operators** + + ``LLMOperator``, ``@task.llm``, ``LLMFileAnalysisOperator``, ``AgentOperator`` and ``@task.agent`` + now share one helper, ``dump_output_for_xcom``, to decide which models they push to XCom as Review Comment: Sharing a helper sounds more like implementation detail to me, not a part of using-facing documentation. ########## providers/common/ai/docs/structured_output.rst: ########## @@ -109,5 +113,45 @@ class is not auto-registered. Add the class qualified name to that pattern work. If a downstream consumer needs the dict shape (e.g. forwarding to an external -system that expects JSON-style payloads), pass ``serialize_output=True`` and the -operator calls ``model_dump()`` before pushing to XCom. +system that expects JSON-style payloads), the operator can push the model dumped +instead of as an instance. Whether it does depends on ``serialize_output``: + +* With ``serialize_output=True``, an output that is itself a model is dumped with ``model_dump()``, so + field types such as ``date`` and ``Decimal`` are kept. +* A model inside a list, tuple, set or dict is not dumped when the worker registers its class + (``output_type=list[MyModel]`` on Airflow 3.3 and later). The XCom serializer pushes it as an + instance, with or without ``serialize_output``. +* A model whose class the worker cannot register is dumped to JSON values, whatever ``serialize_output`` + says. The one exception is a model that is itself the output when ``serialize_output=True``: it is + still dumped, but in Python mode as the first bullet describes. The worker registers the classes it + finds by reading ``output_type``, and finds none in a list of types such as + ``output_type=[MyModel, int]``, so a ``MyModel`` output of that shape is dumped. +* ``LLMOperator``, ``@task.llm``, ``LLMFileAnalysisOperator``, ``AgentOperator`` and ``@task.agent`` dump the + whole output with ``to_jsonable_python``, using field names rather than aliases (also for a model that + sets ``serialize_by_alias=True``), as soon as it holds such a model in a list, tuple, set or dict, as a + set member or as a dict key. A ``date`` or ``Decimal`` next to the model becomes a string. + +In a dump to JSON values, ``HttpUrl``, ``Path`` and ``Enum`` fields become plain JSON values. A model +that is itself the output with ``serialize_output=True`` keeps its Python field values instead, so an +``HttpUrl``, a ``Path`` or a plain ``Enum`` member in it stays an object that the default XCom backend +cannot serialize. + +Behaviour of the LLM operators after 1.1.0 +------------------------------------------- Review Comment: This section repeats the bullet list right above. The same rules also appear in both `serialize_output` docstrings, `stability.rst`, and the changelog. Use references instead? ########## providers/common/ai/src/airflow/providers/common/ai/utils/output_type.py: ########## @@ -82,12 +142,16 @@ def rehydrate_pydantic_output( """ if output_type is str: return raw + declared_type = output_type try: + if isinstance(output_type, (list, tuple)): + # pydantic-ai treats a list of output types as "any of these". + output_type = reduce(operator.or_, output_type) adapter: TypeAdapter[Any] = TypeAdapter(output_type) is_output_function = _is_output_function(adapter.core_schema) # A pydantic-ai output marker (``ToolOutput``, ``NativeOutput``, ...) is not a type, and - # ``TypeAdapter`` fails on it with an ``AttributeError``. - except (PydanticUserError, AttributeError): + # ``TypeAdapter`` fails on it with an ``AttributeError``. Unioning an empty list or markers is a ``TypeError``. + except (PydanticUserError, AttributeError, TypeError): Review Comment: Limit the `TypeError` catch to the `reduce` (or use `Union[tuple(output_type)]`), so a real `TypeError` from `TypeAdapter(...)` doesn't silently fall back to returning `raw`. ########## providers/common/ai/src/airflow/providers/common/ai/utils/output_type.py: ########## @@ -38,6 +46,58 @@ _CONVERSION_ERRORS = (ValidationError, ValueError, TypeError, AttributeError, KeyError, IndexError) +def is_model_dump_required(output: Any, output_type: Any) -> bool: Review Comment: This is only called within the module and can be made private instead. Also the docstring has a very long line. ########## providers/common/ai/src/airflow/providers/common/ai/toolsets/sql.py: ########## @@ -275,6 +280,12 @@ class SQLToolset(AirflowToolset): # Airflow's templater would render in place wherever the toolset is nested. agent_template_fields: Sequence[str] = ("_db_conn_id",) + tool_name_conflict_hint: str = ( + "Pass a distinct `tool_prefix=...` to this toolset so its tool names and " + "model-facing hints are renamed together; wrapping it in `PrefixedToolset` " + "renames only the tools." + ) Review Comment: This is repeated in DataFusion. ObjectStorage and Sandbox, which also use the mixin, don't get it. Move it to `ToolPrefixMixin`? -- 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]
