From b58ee8c37155e24cab8cba5098634abd5b5226f0 Mon Sep 17 00:00:00 2001 From: Kaxil Naik Date: Wed, 14 Oct 2026 02:12:24 +0100 Subject: [PATCH] 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 +- .../common/ai/docs/frameworks/strands.rst | 4 +- .../common/ai/docs/operators/llm_batch.rst | 11 +- .../ai/docs/operators/llm_file_analysis.rst | 5 - .../ai/docs/operators/llm_schema_compare.rst | 5 - .../common/ai/docs/operators/llm_sql.rst | 5 - providers/common/ai/docs/stability.rst | 124 ++++++++++++------ providers/common/ai/docs/toolsets/hook.rst | 6 - .../ai/docs/toolsets/object_storage.rst | 5 - providers/common/ai/docs/toolsets/skills.rst | 7 +- .../common/ai/decorators/llm_batch.py | 5 - .../common/ai/decorators/llm_file_analysis.py | 5 - .../ai/decorators/llm_schema_compare.py | 5 - .../providers/common/ai/decorators/llm_sql.py | 5 - .../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 - .../providers/common/ai/tools/__init__.py | 6 - .../airflow/providers/common/ai/tools/adk.py | 2 +- .../providers/common/ai/tools/strands.py | 2 +- .../providers/common/ai/tools/tracing.py | 2 +- .../providers/common/ai/toolsets/hook.py | 2 +- .../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 a4583bbb344be..58221e938697b 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 e99537b90a712..a58d80c1da970 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 75401a9a2e187..50cc26dfe4034 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 c9030bf729711..18c1b7ac3957f 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 eed8c86628189..0f9cdbc6279ec 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 47b06cf22255f..39be5fefa9dec 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 42e51de795582..c843d0a62da39 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 15d352b9a158c..79ec4e8fe5050 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 ``_`` 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 ``_`` 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 `__). * - :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 4ef43cc701aeb..6ad8b8d2e265c 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 6a7a0b8c5f61d..8a2a0b251a6ef 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 0b0bc9d42f815..52398c8a0649b 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 -`__ package (MIT); native -progressive disclosure is in flight upstream in `pydantic/pydantic-ai#5230 -`__. Install the optional +`__ package (MIT). Pydantic AI now +has on-demand loading of its own (`pydantic/pydantic-ai#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 d1bc139a1b498..1676c679ae2c3 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 83447e9232266..1e3f6974826a2 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 a4f22bfa48674..abacb2dbbbfe6 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 e06a46183b8c7..66bf1326baed0 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 44b504b6361eb..9b49d714a1d0c 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 ``":"`` 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 bb88c35738655..cf176992eeba4 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 6b7f0822698e5..9172359662792 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 6b88a1b319598..28247e3eae46c 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 dc7673e88f6da..8f82ec26f1e3e 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 @@ :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 cef3731be98bb..5520dd7b0607f 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 `__ 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 d9e80cf91c67e..5bdeccadebab2 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 `__ 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 4b4a59524e0e1..9cc8a4365a6a8 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 b6402796658e7..331f4c1af3a99 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 ``"_"``. - :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 c8a971efd10ca..53e2217485d35 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 ee989cfbaa56b..8e019686355db 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