This is an automated email from the ASF dual-hosted git repository. kaxil pushed a commit to branch commonai-stability-graduation in repository https://gitbox.apache.org/repos/asf/airflow.git
commit b58ee8c37155e24cab8cba5098634abd5b5226f0 Author: Kaxil Naik <[email protected]> AuthorDate: Wed Oct 14 02:12:24 2026 +0100 Graduate Common AI features to stable ahead of 1.0 Move @task.llm_sql, @task.llm_file_analysis, @task.llm_schema_compare, @task.llm_batch, ObjectStorageToolset, HookToolset.pinned_arguments and the framework-neutral tool interface into the stable table, and drop their "Experimental" notes. Every remaining experimental row now names a concrete reason: an outside dependency before its 1.0, a framework that changes often, or a change that is planned. Per-tool approval stays experimental because a task instance can pause for approval only once per Dag run. Two stated reasons were out of date: amazon and google implement the managed-agent contract, and CI runs the Strands and ADK adapter tests. --- providers/common/ai/docs/frameworks/adk.rst | 4 +- providers/common/ai/docs/frameworks/index.rst | 6 +- providers/common/ai/docs/frameworks/strands.rst | 4 +- providers/common/ai/docs/operators/llm_batch.rst | 11 +- .../common/ai/docs/operators/llm_file_analysis.rst | 5 - .../ai/docs/operators/llm_schema_compare.rst | 5 - providers/common/ai/docs/operators/llm_sql.rst | 5 - providers/common/ai/docs/stability.rst | 124 ++++++++++++++------- providers/common/ai/docs/toolsets/hook.rst | 6 - .../common/ai/docs/toolsets/object_storage.rst | 5 - providers/common/ai/docs/toolsets/skills.rst | 7 +- .../providers/common/ai/decorators/llm_batch.py | 5 - .../common/ai/decorators/llm_file_analysis.py | 5 - .../common/ai/decorators/llm_schema_compare.py | 5 - .../providers/common/ai/decorators/llm_sql.py | 5 - .../providers/common/ai/operators/llm_batch.py | 5 - .../common/ai/operators/llm_file_analysis.py | 5 - .../common/ai/operators/llm_schema_compare.py | 5 - .../providers/common/ai/operators/llm_sql.py | 5 - .../airflow/providers/common/ai/tools/__init__.py | 6 - .../src/airflow/providers/common/ai/tools/adk.py | 2 +- .../airflow/providers/common/ai/tools/strands.py | 2 +- .../airflow/providers/common/ai/tools/tracing.py | 2 +- .../airflow/providers/common/ai/toolsets/hook.py | 2 +- .../providers/common/ai/toolsets/object_storage.py | 5 - .../providers/common/ai/triggers/llm_batch.py | 5 - 26 files changed, 105 insertions(+), 141 deletions(-) diff --git a/providers/common/ai/docs/frameworks/adk.rst b/providers/common/ai/docs/frameworks/adk.rst index a4583bbb344..58221e93869 100644 --- a/providers/common/ai/docs/frameworks/adk.rst +++ b/providers/common/ai/docs/frameworks/adk.rst @@ -28,8 +28,8 @@ it is, and add Airflow's toolsets to its tools with the .. note:: - ``AirflowTools`` and the framework-neutral tool interface it builds on are - experimental. They may change in a minor release of this provider. + ``AirflowTools`` is experimental: it may change in a minor release of this provider. + The framework-neutral tool interface it builds on is stable. See :ref:`howto/stability`. Run an ADK agent in a task diff --git a/providers/common/ai/docs/frameworks/index.rst b/providers/common/ai/docs/frameworks/index.rst index e99537b90a7..a58d80c1da9 100644 --- a/providers/common/ai/docs/frameworks/index.rst +++ b/providers/common/ai/docs/frameworks/index.rst @@ -80,9 +80,9 @@ is Airflow's and which part stays yours. - No agent - ``[llamaindex]`` extra -The Strands and ADK integrations, the framework-neutral tool interface under them, and -the tracing helper are experimental: they can change or be removed in a minor release of -this provider. See :ref:`howto/stability`. +The Strands and ADK integrations and the tracing helper are experimental: they can change +or be removed in a minor release of this provider. The framework-neutral tool interface +under them is stable. See :ref:`howto/stability`. Tested versions --------------- diff --git a/providers/common/ai/docs/frameworks/strands.rst b/providers/common/ai/docs/frameworks/strands.rst index 75401a9a2e1..50cc26dfe40 100644 --- a/providers/common/ai/docs/frameworks/strands.rst +++ b/providers/common/ai/docs/frameworks/strands.rst @@ -29,8 +29,8 @@ give it Airflow's toolsets with the .. note:: - ``AirflowTools`` and the framework-neutral tool interface it builds on are - experimental. They may change in a minor release of this provider. + ``AirflowTools`` is experimental: it may change in a minor release of this provider. + The framework-neutral tool interface it builds on is stable. See :ref:`howto/stability`. Run a Strands agent in a task diff --git a/providers/common/ai/docs/operators/llm_batch.rst b/providers/common/ai/docs/operators/llm_batch.rst index c9030bf7297..18c1b7ac395 100644 --- a/providers/common/ai/docs/operators/llm_batch.rst +++ b/providers/common/ai/docs/operators/llm_batch.rst @@ -20,11 +20,6 @@ Batch processing: ``LLMBatchOperator`` ====================================== -.. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Use :class:`~airflow.providers.common.ai.operators.llm_batch.LLMBatchOperator` to run many prompts through a provider's **batch API** instead of one synchronous call per prompt: roughly half the per-token cost of :class:`~airflow.providers.common.ai.operators.llm.LLMOperator`, @@ -315,6 +310,12 @@ storage with a reconciled manifest. Adding an adapter ------------------ +.. note:: + + Experimental: the adapter contract can change or be removed in a minor release of this + provider. + See :ref:`howto/stability`. + Another provider package can add a batch engine without changes here: subclass :class:`~airflow.providers.common.ai.batch.base.BatchAdapter`, set its ``name`` to the model prefix it serves and ``conn_types`` to the connection types it can authenticate from, and either diff --git a/providers/common/ai/docs/operators/llm_file_analysis.rst b/providers/common/ai/docs/operators/llm_file_analysis.rst index eed8c866281..0f9cdbc6279 100644 --- a/providers/common/ai/docs/operators/llm_file_analysis.rst +++ b/providers/common/ai/docs/operators/llm_file_analysis.rst @@ -20,11 +20,6 @@ Analyze files and images: ``LLMFileAnalysisOperator`` and ``@task.llm_file_analysis`` ===================================================================================== -.. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Use :class:`~airflow.providers.common.ai.operators.llm_file_analysis.LLMFileAnalysisOperator` or the ``@task.llm_file_analysis`` decorator to analyze files from object storage or local storage with a single prompt. diff --git a/providers/common/ai/docs/operators/llm_schema_compare.rst b/providers/common/ai/docs/operators/llm_schema_compare.rst index 47b06cf2225..39be5fefa9d 100644 --- a/providers/common/ai/docs/operators/llm_schema_compare.rst +++ b/providers/common/ai/docs/operators/llm_schema_compare.rst @@ -20,11 +20,6 @@ Detect schema drift: ``LLMSchemaCompareOperator`` and ``@task.llm_schema_compare`` ================================================================================== -.. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Use :class:`~airflow.providers.common.ai.operators.llm_schema_compare.LLMSchemaCompareOperator` to compare schemas across different database systems and detect drift using LLM reasoning. diff --git a/providers/common/ai/docs/operators/llm_sql.rst b/providers/common/ai/docs/operators/llm_sql.rst index 42e51de7955..c843d0a62da 100644 --- a/providers/common/ai/docs/operators/llm_sql.rst +++ b/providers/common/ai/docs/operators/llm_sql.rst @@ -20,11 +20,6 @@ Natural language to SQL: ``LLMSQLQueryOperator`` and ``@task.llm_sql`` ====================================================================== -.. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Use :class:`~airflow.providers.common.ai.operators.llm_sql.LLMSQLQueryOperator` to generate SQL queries from natural language using an LLM. diff --git a/providers/common/ai/docs/stability.rst b/providers/common/ai/docs/stability.rst index 15d352b9a15..79ec4e8fe50 100644 --- a/providers/common/ai/docs/stability.rst +++ b/providers/common/ai/docs/stability.rst @@ -63,6 +63,44 @@ Pydantic AI toolsets, but the Pydantic AI class they inherit from can change. descriptions in ``branches``, as strings or as ``BranchOption(description=...)``, are sent to the model with the options. ``decision_policy`` and ``BranchOption.min_confidence`` are experimental; see below. + * - ``@task.llm_sql`` and + :class:`~airflow.providers.common.ai.operators.llm_sql.LLMSQLQueryOperator` + - Generates SQL from the prompt and returns it without running it. With + ``validate_sql=True``, the default, the task fails unless the output is a single + statement that parses for ``dialect`` and is one of ``allowed_sql_types`` + (``SELECT``, ``UNION``, ``INTERSECT`` and ``EXCEPT`` by default); with the default + types, a write nested inside the statement fails it too. A reviewer's edit under + ``allow_modifications=True`` is checked the same way. ``db_conn_id`` with + ``table_names``, ``schema_context`` or ``datasource_config`` give the model the + schema. + * - ``@task.llm_file_analysis`` and + :class:`~airflow.providers.common.ai.operators.llm_file_analysis.LLMFileAnalysisOperator` + - Reads the file at ``file_path``, or up to ``max_files`` files under a prefix, + without changing them, and sends their content to the model with the prompt in one + request: CSV, Parquet and Avro sampled to ``sample_rows`` rows, and all text cut to + ``max_text_chars``. Input over ``max_file_size_bytes`` or ``max_total_size_bytes`` + fails the task before the model is called, and so does an image or PDF unless + ``multi_modal=True``, which attaches it. + * - ``@task.llm_schema_compare`` and + :class:`~airflow.providers.common.ai.operators.llm_schema_compare.LLMSchemaCompareOperator` + - Introspects the schemas of ``data_sources`` and of ``table_names`` on each of + ``db_conn_ids``, either or both, and returns a + :class:`~airflow.providers.common.ai.operators.llm_schema_compare.SchemaCompareResult` + as a dict: ``compatible``, ``summary`` and the ``mismatches``, each with a + ``severity`` of ``critical``, ``warning`` or ``info``. ``context_strategy="basic"`` + sends columns only; ``"full"``, the default, adds keys and indexes for database + sources. + * - ``@task.llm_batch`` and + :class:`~airflow.providers.common.ai.operators.llm_batch.LLMBatchOperator` + - Submits ``requests`` to the batch API that the ``model_id`` prefix selects, writes + one JSONL row per request under ``result_path`` and returns the manifest + (``schema_version: 1``) described in :doc:`operators/llm_batch`, never the results + themselves. A retry or clear that renders the same ``result_path`` re-attaches to + the batch already submitted while the requests, model, connection, system prompt, + ``max_tokens``, ``request_params`` and output schema are unchanged, unless that + batch was cancelled or failed. On Airflow 3.3 and later, clearing a deferred task + cancels its batch while ``cancel_on_kill=True``, the default. Adding a batch engine + through ``BatchAdapter`` is experimental; see below. * - :class:`~airflow.providers.common.ai.hooks.pydantic_ai.PydanticAIHook` and its connection types - The connection fields documented for each type in :doc:`connections/pydantic_ai`, @@ -80,13 +118,29 @@ Pydantic AI toolsets, but the Pydantic AI class they inherit from can change. - Exposes exactly the hook methods in ``allowed_methods``, each named ``<tool_prefix>_<method>`` when ``tool_prefix`` is set, which must be a valid Python identifier, and raises an error when the toolset is created - if a listed method does not exist on the hook. ``pinned_arguments`` is - experimental; see below. + if a listed method does not exist on the hook. Arguments in ``pinned_arguments`` + are left out of the schema the model sees and passed to every allowed method; a + call that supplies one is refused, and the toolset raises an error when it is + created if an allowed method does not take a pinned argument by that name. + * - :class:`~airflow.providers.common.ai.toolsets.object_storage.ObjectStorageToolset` + - Exposes ``list_files``, ``get_file_info`` and ``read_file`` for the files under the + root path, read-only. Paths from the model are relative to the root: absolute + paths, paths with a scheme and paths that climb out of the root are refused. A file + the model cannot read, such as a binary file or one larger than ``max_read_bytes``, + comes back to it as a message instead of failing the task. * - :class:`~airflow.providers.common.ai.toolsets.mcp.MCPToolset` and :class:`~airflow.providers.common.ai.hooks.mcp.MCPHook` - Exposes the tools of the MCP server configured by ``mcp_conn_id``, each named ``<tool_prefix>_<name>`` when ``tool_prefix`` is set. The connection fields for each transport keep their meaning. + * - The framework-neutral tool interface (:mod:`airflow.providers.common.ai.tools`): + ``AirflowTool``, ``ToolResult``, ``ToolCallError``, ``ToolProvider``, + ``collect_tools`` and the ``airflow_tools()`` method of the toolsets + - An ``AirflowTool`` keeps its ``name``, ``description``, JSON Schema ``parameters`` + and async ``function``, and ``call()`` masks secrets in what it returns. A + ``ToolResult`` with ``is_error=True`` is a failure the model can correct; + ``ToolCallError`` fails the run. ``collect_tools`` raises ``ValueError`` when two + tools share a name. An adapter for another agent framework can build on this. * - :class:`~airflow.providers.common.ai.policies.retry.LLMRetryPolicy` - Returns a retry decision from a model's reading of the exception. Values registered as secrets are masked in the exception text before it reaches the model, unless @@ -113,48 +167,53 @@ Everything this provider ships that is not in the table above is experimental. - Why it is experimental * - :class:`~airflow.providers.common.ai.policies.retry.ClassifierRetryPolicy` (:doc:`decision_models`) - - The confidence threshold, the fallback order and the behaviour when the classifier - is unavailable are still settling. + - What it does when the classifier is unsure or unavailable is changing. * - :class:`~airflow.providers.common.ai.policies.decision.DecisionPolicy`, and ``min_confidence`` on :class:`~airflow.providers.common.ai.policies.decision.BranchOption` (:doc:`approval_gates`) - - New. The threshold semantics and the recorded decision may change as they are - used. - * - ``@task.llm_batch`` and batch adapters (:doc:`operators/llm_batch`) - - Submission, re-attachment on retry, cancellation and handling of partial results - are still settling, and ``BatchAdapter`` has no implementation outside this - provider yet. + - Whether the confidence gate keeps this shape or becomes part of a wider decision + policy is still open. + * - Batch engines from other packages: ``BatchAdapter``, ``register_adapter()`` and the + ``airflow.providers.common.ai.batch_adapters`` entry point + (:doc:`operators/llm_batch`) + - No package outside this provider implements the contract yet, so it has not been + tested by a second implementation. * - ``durable=True`` on ``AgentOperator`` (:doc:`durable_execution`) - Which tool results are replayed on retry will change, so that a tool can declare whether its result may be reused. * - Per-tool approval on ``AgentOperator`` (``tool_approval_timeout``, ``on_tool_approval_timeout`` and ``tool_approval_assigned_users``; :doc:`tool_approval`) - - New, and needs Airflow 3.3. How a paused run resumes may change. - * - Code mode (:doc:`code_mode`), the Agent Skills toolset - (:doc:`toolsets/skills`) and the ``shields`` extra (used in :doc:`capabilities`) - - Thin integrations of packages outside this provider whose APIs are still - changing: ``pydantic-ai-harness``, ``pydantic-ai-skills`` and - ``pydantic-ai-shields``. + - A task instance can pause for approval only once per Dag run, so an agent that + needs a second approval later in the run fails. Lifting that limit is planned. + * - Code mode (:doc:`code_mode`) and the ``shields`` extra (used in + :doc:`capabilities`) + - Thin integrations of ``pydantic-ai-harness`` and ``pydantic-ai-shields``, which are + before their 1.0 releases. + * - The Agent Skills toolset (:doc:`toolsets/skills`) + - It may move from ``pydantic-ai-skills`` to the on-demand loading Pydantic AI now has + itself (`pydantic/pydantic-ai#5230 <https://github.com/pydantic/pydantic-ai/pull/5230>`__). * - :class:`~airflow.providers.common.ai.toolsets.sandbox.SandboxToolset` and its backends (:doc:`sandbox/index`) - - The sandbox runtime belongs to the backend; ownership and cleanup across worker - failures are still being designed. + - ``durable=True`` cannot be used with it yet, the ``sbx`` backend leaves its sandbox + behind when the worker is killed, and the backend contract is still gaining + capabilities, such as attaching to a sandbox another task owns. * - LangChain and LlamaIndex hooks and the LangChain tool bridge (:doc:`hooks/langchain`, :doc:`toolsets/langchain`, :doc:`hooks/llamaindex`) - Each follows the API of a framework that changes often. * - The retrieval operators: ``DocumentLoaderOperator``, ``LlamaIndexEmbeddingOperator`` and ``LlamaIndexRetrievalOperator`` (:doc:`rag_pipelines`) - - New. The shape of the pipeline, from loading documents through embedding to - retrieval, has not settled. + - Whether retrieval pipelines belong in this provider, which bridges Airflow to agent + frameworks rather than replacing them, is still open. * - :class:`~airflow.providers.common.ai.toolsets.datafusion.DataFusionToolset` (:doc:`toolsets/datafusion`) - Runs on the DataFusion engine of ``common.sql``, which pins ``datafusion`` below 52 and follows its API. * - Managed agent toolsets (:doc:`toolsets/managed_agent`) - - A contract for vendor providers that no vendor implements yet. + - The amazon and google providers implement the contract. The managed-agent operators + of the other vendor providers are still being brought onto it, which can change it. * - OpenTelemetry spans (``[common.ai] otel_export_enabled`` and ``capture_content``; :doc:`observability`) - Span names and attributes come from Pydantic AI's instrumentation and the @@ -163,25 +222,10 @@ Everything this provider ships that is not in the table above is experimental. (:doc:`toolsets/logging`) - The wrapper ``AgentOperator`` applies for ``enable_tool_logging``; its constructor may change. - * - ``@task.llm_schema_compare``, ``@task.llm_file_analysis`` and ``@task.llm_sql`` - (:doc:`operators/llm_schema_compare`, :doc:`operators/llm_file_analysis`, - :doc:`operators/llm_sql`) - - Each adds its own input handling to ``@task.llm``: schema introspection, file - sampling, or SQL validation. Their options are still settling. - * - The framework-neutral tools (:mod:`airflow.providers.common.ai.tools`), including - the ``airflow_tools()`` method of the toolsets, the Strands plugin and the ADK - toolset (:doc:`frameworks/index`) - - Written against Strands 1.56 and ADK 2.9.1. CI does not run the tests of the two - adapters, because both frameworks exclude dependency versions that Airflow's - development environment uses. - * - :class:`~airflow.providers.common.ai.toolsets.object_storage.ObjectStorageToolset` - (:doc:`toolsets/object_storage`) - - New; its tools and read limits may change after first use. - * - ``pinned_arguments`` on - :class:`~airflow.providers.common.ai.toolsets.hook.HookToolset` - (:doc:`toolsets/hook`) - - New; how a pinned argument is matched to each method's parameters may change after - first use. + * - The Strands plugin, the ADK toolset and Strands checkpoint resume + (:doc:`frameworks/index`) + - Written against Strands 1.56 and ADK 2.9.1, which change often. Strands marks its + own checkpointing experimental. * - The ``common_ai.tool_calls`` metric and :func:`~airflow.providers.common.ai.tools.tracing.agent_framework_tracing` (:doc:`observability`) diff --git a/providers/common/ai/docs/toolsets/hook.rst b/providers/common/ai/docs/toolsets/hook.rst index 4ef43cc701a..6ad8b8d2e26 100644 --- a/providers/common/ai/docs/toolsets/hook.rst +++ b/providers/common/ai/docs/toolsets/hook.rst @@ -85,12 +85,6 @@ the ID from values the Dag controls, not from ``params`` or ``dag_run.conf`` (se Fix arguments the model must not choose --------------------------------------- -.. note:: - - Experimental: ``pinned_arguments`` can change or be removed in a minor release of this - provider. - See :ref:`howto/stability`. - Exposing a method lets the model pick every argument it takes. When some of them are the Dag author's decision, such as which bucket a storage hook reads, pin them: diff --git a/providers/common/ai/docs/toolsets/object_storage.rst b/providers/common/ai/docs/toolsets/object_storage.rst index 6a7a0b8c5f6..8a2a0b251a6 100644 --- a/providers/common/ai/docs/toolsets/object_storage.rst +++ b/providers/common/ai/docs/toolsets/object_storage.rst @@ -20,11 +20,6 @@ Files on object storage: ``ObjectStorageToolset`` ================================================= -.. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Give an agent the files under one location in S3, GCS, Azure Blob Storage or any other store Airflow's :class:`~airflow.sdk.ObjectStoragePath` can open, and let it find and read what it needs: a month's reports, the config files of a failing job, the first diff --git a/providers/common/ai/docs/toolsets/skills.rst b/providers/common/ai/docs/toolsets/skills.rst index 0b0bc9d42f8..52398c8a064 100644 --- a/providers/common/ai/docs/toolsets/skills.rst +++ b/providers/common/ai/docs/toolsets/skills.rst @@ -33,9 +33,10 @@ prompt until the model decides it needs one, so a large skill library costs few tokens until used (progressive disclosure). It is backed by the community `pydantic-ai-skills -<https://github.com/DougTrajano/pydantic-ai-skills>`__ package (MIT); native -progressive disclosure is in flight upstream in `pydantic/pydantic-ai#5230 -<https://github.com/pydantic/pydantic-ai/pull/5230>`__. Install the optional +<https://github.com/DougTrajano/pydantic-ai-skills>`__ package (MIT). Pydantic AI now +has on-demand loading of its own (`pydantic/pydantic-ai#5230 +<https://github.com/pydantic/pydantic-ai/pull/5230>`__), and this toolset may move to it. +Install the optional extra to use it: .. code-block:: bash diff --git a/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_batch.py b/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_batch.py index d1bc139a1b4..1676c679ae2 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_batch.py +++ b/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_batch.py @@ -110,11 +110,6 @@ def llm_batch_task( """ Wrap a function that returns a batch's inputs into an ``@task.llm_batch`` task. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - The function body constructs the list of inputs (it can use Airflow context, XCom, etc.). Results are written to ``result_path`` as JSONL; the XCom value is a manifest describing where to find them (see diff --git a/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_file_analysis.py b/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_file_analysis.py index 83447e92322..1e3f6974826 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_file_analysis.py +++ b/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_file_analysis.py @@ -101,11 +101,6 @@ def llm_file_analysis_task( """ Wrap a callable that returns a prompt into an LLM-backed file-analysis task. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Any file-analysis keyword arguments accepted by :class:`~airflow.providers.common.ai.operators.llm_file_analysis.LLMFileAnalysisOperator`, including ``sample_rows``, can be passed through this decorator. diff --git a/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_schema_compare.py b/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_schema_compare.py index a4f22bfa486..abacb2dbbbf 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_schema_compare.py +++ b/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_schema_compare.py @@ -110,11 +110,6 @@ def llm_schema_compare_task( """ Wrap a function that returns a prompt into an LLM schema comparison task. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - The function body constructs the prompt (can use Airflow context, XCom, etc.). The decorator handles: schema introspection from multiple data sources, LLM-powered cross-system type comparison, and structured mismatch output. diff --git a/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_sql.py b/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_sql.py index e06a46183b8..66bf1326bae 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_sql.py +++ b/providers/common/ai/src/airflow/providers/common/ai/decorators/llm_sql.py @@ -112,11 +112,6 @@ def llm_sql_task( """ Wrap a function that returns a natural language prompt into an LLM SQL task. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - The function body constructs the prompt (can use Airflow context, XCom, etc.). The decorator handles: LLM connection, schema introspection, SQL generation, and safety validation. diff --git a/providers/common/ai/src/airflow/providers/common/ai/operators/llm_batch.py b/providers/common/ai/src/airflow/providers/common/ai/operators/llm_batch.py index 44b504b6361..9b49d714a1d 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/operators/llm_batch.py +++ b/providers/common/ai/src/airflow/providers/common/ai/operators/llm_batch.py @@ -61,11 +61,6 @@ class LLMBatchOperator(BaseOperator): """ Submit prompts as a provider batch job and land results on object storage. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Routes to the OpenAI or Anthropic batch API based on ``model_id``'s ``"<provider>:<model>"`` prefix (see :mod:`~airflow.providers.common.ai.batch.dispatch`). Unlike diff --git a/providers/common/ai/src/airflow/providers/common/ai/operators/llm_file_analysis.py b/providers/common/ai/src/airflow/providers/common/ai/operators/llm_file_analysis.py index bb88c357386..cf176992eeb 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/operators/llm_file_analysis.py +++ b/providers/common/ai/src/airflow/providers/common/ai/operators/llm_file_analysis.py @@ -37,11 +37,6 @@ class LLMFileAnalysisOperator(LLMOperator): """ Analyze files from object storage or local storage using a single LLM call. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - The operator resolves ``file_path`` via :class:`~airflow.providers.common.compat.sdk.ObjectStoragePath`, normalizes supported formats into text context, and optionally attaches images/PDFs as diff --git a/providers/common/ai/src/airflow/providers/common/ai/operators/llm_schema_compare.py b/providers/common/ai/src/airflow/providers/common/ai/operators/llm_schema_compare.py index 6b7f0822698..91723596627 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/operators/llm_schema_compare.py +++ b/providers/common/ai/src/airflow/providers/common/ai/operators/llm_schema_compare.py @@ -80,11 +80,6 @@ class LLMSchemaCompareOperator(LLMOperator): """ Compare schemas across different database systems and detect drift using LLM reasoning. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - The LLM handles complex cross-system type mapping that simple equality checks miss (e.g., ``varchar(255)`` vs ``string``, ``timestamp`` vs ``timestamptz``). diff --git a/providers/common/ai/src/airflow/providers/common/ai/operators/llm_sql.py b/providers/common/ai/src/airflow/providers/common/ai/operators/llm_sql.py index 6b88a1b3195..28247e3eae4 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/operators/llm_sql.py +++ b/providers/common/ai/src/airflow/providers/common/ai/operators/llm_sql.py @@ -49,11 +49,6 @@ class LLMSQLQueryOperator(LLMOperator): """ Generate SQL queries from natural language using an LLM. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Inherits from :class:`~airflow.providers.common.ai.operators.llm.LLMOperator` for LLM access and optionally uses a :class:`~airflow.providers.common.sql.hooks.sql.DbApiHook` diff --git a/providers/common/ai/src/airflow/providers/common/ai/tools/__init__.py b/providers/common/ai/src/airflow/providers/common/ai/tools/__init__.py index dc7673e88f6..8f82ec26f1e 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/tools/__init__.py +++ b/providers/common/ai/src/airflow/providers/common/ai/tools/__init__.py @@ -28,12 +28,6 @@ The toolsets this provider ships, such as :class:`~airflow.providers.common.ai.toolsets.hook.HookToolset`, implement :class:`ToolProvider` and expose their tools through :meth:`ToolProvider.airflow_tools`. - -.. note:: - - Experimental: this interface can change or be removed in a minor release of this - provider. - See :ref:`howto/stability`. """ from __future__ import annotations diff --git a/providers/common/ai/src/airflow/providers/common/ai/tools/adk.py b/providers/common/ai/src/airflow/providers/common/ai/tools/adk.py index cef3731be98..5520dd7b060 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/tools/adk.py +++ b/providers/common/ai/src/airflow/providers/common/ai/tools/adk.py @@ -17,7 +17,7 @@ """ Give Airflow tools to a `Google ADK <https://google.github.io/adk-docs/>`__ agent. -.. note:: Experimental; see :mod:`airflow.providers.common.ai.tools`. +.. note:: Experimental; see :ref:`howto/stability`. """ from __future__ import annotations diff --git a/providers/common/ai/src/airflow/providers/common/ai/tools/strands.py b/providers/common/ai/src/airflow/providers/common/ai/tools/strands.py index d9e80cf91c6..5bdeccadeba 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/tools/strands.py +++ b/providers/common/ai/src/airflow/providers/common/ai/tools/strands.py @@ -17,7 +17,7 @@ """ Give Airflow tools to a `Strands Agents <https://strandsagents.com/>`__ agent. -.. note:: Experimental; see :mod:`airflow.providers.common.ai.tools`. +.. note:: Experimental; see :ref:`howto/stability`. """ from __future__ import annotations diff --git a/providers/common/ai/src/airflow/providers/common/ai/tools/tracing.py b/providers/common/ai/src/airflow/providers/common/ai/tools/tracing.py index 4b4a59524e0..9cc8a4365a6 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/tools/tracing.py +++ b/providers/common/ai/src/airflow/providers/common/ai/tools/tracing.py @@ -17,7 +17,7 @@ """ Make the OpenTelemetry spans of an agent framework other than Pydantic AI part of the task. -.. note:: Experimental; see :mod:`airflow.providers.common.ai.tools`. +.. note:: Experimental; see :ref:`howto/stability`. """ from __future__ import annotations diff --git a/providers/common/ai/src/airflow/providers/common/ai/toolsets/hook.py b/providers/common/ai/src/airflow/providers/common/ai/toolsets/hook.py index b6402796658..331f4c1af3a 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/toolsets/hook.py +++ b/providers/common/ai/src/airflow/providers/common/ai/toolsets/hook.py @@ -78,7 +78,7 @@ class HookToolset(AirflowToolset): (``"s3_"`` → ``"s3_list_keys"``, ``"s3"`` → ``"s3list_keys"``) and not validated. Passing it with ``tool_prefix`` raises ``ValueError`` unless it equals ``"<tool_prefix>_"``. - :param pinned_arguments: Experimental. Arguments the Dag author fixes, such as the bucket a + :param pinned_arguments: Arguments the Dag author fixes, such as the bucket a storage hook may use: ``{"bucket_name": "reports"}``. Each is left out of the arguments the model sees, refused if the model supplies it anyway, and passed to every allowed method as it is written here, not rendered as a template. Every allowed diff --git a/providers/common/ai/src/airflow/providers/common/ai/toolsets/object_storage.py b/providers/common/ai/src/airflow/providers/common/ai/toolsets/object_storage.py index c8a971efd10..53e2217485d 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/toolsets/object_storage.py +++ b/providers/common/ai/src/airflow/providers/common/ai/toolsets/object_storage.py @@ -113,11 +113,6 @@ class ObjectStorageToolset(AirflowToolset): """ Give an agent read-only access to the files under one object-storage path. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Exposes three tools, ``list_files``, ``get_file_info`` and ``read_file``, rooted at ``path``, which is any location Airflow's :class:`~airflow.sdk.ObjectStoragePath` can open: ``s3://``, ``gs://``, ``abfs://``, diff --git a/providers/common/ai/src/airflow/providers/common/ai/triggers/llm_batch.py b/providers/common/ai/src/airflow/providers/common/ai/triggers/llm_batch.py index ee989cfbaa5..8e019686355 100644 --- a/providers/common/ai/src/airflow/providers/common/ai/triggers/llm_batch.py +++ b/providers/common/ai/src/airflow/providers/common/ai/triggers/llm_batch.py @@ -34,11 +34,6 @@ class LLMBatchTrigger(BaseTrigger): """ Poll a batch adapter until the batch reaches a terminal state. - .. note:: - - Experimental: this can change or be removed in a minor release of this provider. - See :ref:`howto/stability`. - Deliberately thin: this trigger only polls and, on kill or timeout, cancels. It never downloads or validates results; that is :meth:`~airflow.providers.common.ai.operators.llm_batch.LLMBatchOperator.execute_complete`'s
