Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions providers/common/ai/docs/decision_models.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,9 @@ Decision models

.. note::

Experimental: this can change or be removed in a minor release of this provider.
See :ref:`howto/stability`.
Experimental: the ``typesafe`` extra can change or be removed in a minor release of this
provider, because the ``typesafe-sdk`` it installs is before its 1.0 release. See
:ref:`howto/stability`.

Every other model in this provider writes text. A decision model does not: you give it
some text and a typed question, and it answers with a value from a set you named in
Expand Down
5 changes: 0 additions & 5 deletions providers/common/ai/docs/retry_policies.rst
Original file line number Diff line number Diff line change
Expand Up @@ -162,11 +162,6 @@ an attempt is a separate mechanism on the connection; see
ClassifierRetryPolicy
---------------------

.. note::

Experimental: this can change or be removed in a minor release of this provider.
See :ref:`howto/stability`.

``ClassifierRetryPolicy`` takes the retry decision away from the model. Its
``categories`` maps a category name to an
:class:`~airflow.providers.common.ai.policies.retry.ErrorCategory`: what
Expand Down
16 changes: 13 additions & 3 deletions providers/common/ai/docs/stability.rst
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,17 @@ Pydantic AI toolsets, but the Pydantic AI class they inherit from can change.
``redact_exception=False`` or a custom ``redactor`` replaces the masking. If the
model call fails, it falls back to ``fallback_rules`` and then to the task's own
retry settings; it never fails the task itself.
* - :class:`~airflow.providers.common.ai.policies.retry.ClassifierRetryPolicy` and
:class:`~airflow.providers.common.ai.policies.retry.ErrorCategory`
- The model can only answer with one of the names in ``categories``, and that name's
``ErrorCategory`` decides whether the task retries and after what ``delay``.
Without ``categories`` the policy uses
:data:`~airflow.providers.common.ai.policies.retry.DEFAULT_CATEGORIES`, whose seven
names and their retry or fail split stay the same. When the model call fails, or
``min_confidence`` is set and the answer is under it or carries no confidence, the
policy uses the RETRY or FAIL of ``fallback_policy``, then ``fallback_rules``, then
the task's own retry settings. Secrets are masked in the exception text as for
``LLMRetryPolicy``.
* - Output review: ``require_approval``, ``enable_hitl_review`` and the review plugin
- With ``require_approval=True``, the task defers after generating output and returns
it only once a person approves it on the Required Actions page. A rejection, or a
Expand All @@ -191,9 +202,8 @@ Everything this provider ships that is not in the table above is experimental.

* - Feature
- Why it is experimental
* - :class:`~airflow.providers.common.ai.policies.retry.ClassifierRetryPolicy`
(:doc:`decision_models`)
- What it does when the classifier is unsure or unavailable is changing.
* - The ``typesafe`` extra (:doc:`decision_models`)
- It installs ``typesafe-sdk``, which is before its 1.0 release.
* - :class:`~airflow.providers.common.ai.policies.decision.DecisionPolicy`, and
``min_confidence`` on
:class:`~airflow.providers.common.ai.policies.decision.BranchOption`
Expand Down
25 changes: 11 additions & 14 deletions providers/common/ai/docs/why_common_ai.rst
Original file line number Diff line number Diff line change
Expand Up @@ -85,10 +85,9 @@ and a bucket of report files. What differs:
- **The tools.** The hand-written ``query`` runs any SQL the model writes, including
``DELETE``, on any table the connection can reach, and returns every row it gets.
``SQLToolset`` allows only the ``orders`` table, rejects statements that write, and caps
the rows and bytes it returns. ``ObjectStorageToolset`` (experimental) keeps reads under
the prefix you gave it. Both run Airflow's secrets masker over results, which hides
values Airflow knows are secret, such as connection passwords, not personal data in your
tables.
the rows and bytes it returns. ``ObjectStorageToolset`` keeps reads under the prefix you
gave it. Both run Airflow's secrets masker over results, which hides values Airflow knows
are secret, such as connection passwords, not personal data in your tables.
- **The model.** The plain task names a vendor in code and reads its key from the
environment. ``AgentOperator`` takes both from a connection, so moving to another vendor
or adding a fallback is a connection change. See :doc:`model_providers`.
Expand Down Expand Up @@ -137,7 +136,7 @@ What a plain task leaves to you
* - A person has to approve a tool call before it runs, such as a refund or a write
to a production table.
- A tool marked with Pydantic AI's approval API pauses ``AgentOperator`` before the
call, without holding a worker slot. Airflow 3.3 and later. Experimental. Not with
call, without holding a worker slot. Airflow 3.3 and later. Not with
``durable=True`` or ``enable_hitl_review=True``; with either, a tool marked for
approval fails the task.
- :doc:`tool_approval`
Expand All @@ -150,10 +149,10 @@ What a plain task leaves to you
- :doc:`hitl_review`
* - The agent needs your databases, object storage or an API you already have a
hook for.
- ``SQLToolset``, ``HookToolset`` and ``ObjectStorageToolset`` (experimental) build
tools from an Airflow connection, with table allow-lists, read-only SQL and size
limits. Results pass through Airflow's secrets masker before the model sees
them. They work in an agent you run yourself too.
- ``SQLToolset``, ``HookToolset`` and ``ObjectStorageToolset`` build tools from an
Airflow connection, with table allow-lists, read-only SQL and size limits. Results
pass through Airflow's secrets masker before the model sees them. They work in an
agent you run yourself too.
- :doc:`toolsets/index`
* - A model vendor is down.
- ``fallback_conn_ids`` fails over to other connections in order.
Expand All @@ -162,11 +161,10 @@ What a plain task leaves to you
- The batch operator sends them through the OpenAI or Anthropic batch API at
roughly half the per-token cost. A retry re-attaches to the batch already
submitted if the prompts, model, output schema and connection are unchanged.
With ``deferrable=True`` the wait does not hold a worker slot. Experimental.
With ``deferrable=True`` the wait does not hold a worker slot.
- :doc:`operators/llm_batch`

The provider runs on Airflow 2.11 and later; a row that needs a newer Airflow says so.
Experimental features can change in a minor release; see :doc:`stability`.

Decide whether a failed task retries
------------------------------------
Expand All @@ -187,9 +185,8 @@ When the task fails, the model reads the exception and decides whether to retry
long to wait, so it can decide to wait out a rate limit and to fail a revoked credential
at once. The exception text goes through the secrets masker before the model sees it,
and ``fallback_rules`` decide when the model cannot be reached. ``ClassifierRetryPolicy``
(experimental) has a cheaper model pick from categories you define, and can hand the
cases it is unsure of to an ``LLMRetryPolicy``. Both need Airflow 3.3 or later. See
:doc:`retry_policies`.
has a cheaper model pick from categories you define, and can hand the cases it is unsure
of to an ``LLMRetryPolicy``. Both need Airflow 3.3 or later. See :doc:`retry_policies`.

When a plain task is enough
---------------------------
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -129,11 +129,6 @@ class ErrorCategory:
"""
One kind of failure a :class:`ClassifierRetryPolicy` may name, and what it does when it does.

.. note::

Experimental: this can change or be removed in a minor release of this provider.
See :ref:`howto/stability`.

The value of the policy's ``categories`` mapping, keyed by the category name the model
answers with.

Expand Down Expand Up @@ -459,11 +454,6 @@ class ClassifierRetryPolicy(_ModelRetryPolicy):
"""
Retry policy where the model names the kind of failure and the author's table decides.

.. note::

Experimental: this can change or be removed in a minor release of this provider.
See :ref:`howto/stability`.

The model's only job is to pick one of ``categories``; it reads each one's description
from the output schema. Whether that category is retried, after how long, and how sure
the model has to be all come from the :class:`ErrorCategory` in the worker process.
Expand Down