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]

Reply via email to