Skip to content

Mark experimental common.ai features ahead of 1.0 - #73896

Merged
kaxil merged 1 commit into
mainfrom
commonai-stability-page
Sep 29, 2026
Merged

kaxil merged 1 commit into
mainfrom
commonai-stability-page

Conversation

@kaxil

@kaxil kaxil commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

Before common.ai reaches 1.0, someone building a production Dag needs to know which features keep their behaviour across minor releases. This adds a Stable and experimental features page. It lists each stable feature with what stays the same about it, and names every experimental feature with the reason it is experimental. The guarantees start at 1.0.0. Experimental features follow Airflow's experimental feature policy: they can change or be removed in a minor release, and the changelog says so.

The pages of experimental features, and their main classes and functions, carry a note that links to the page. Parameters of stable operators that take an experimental value are marked one by one: durable, code_mode and the per-tool approval parameters on AgentOperator, and decision_policy on LLMOperator and LLMBranchOperator.

Stability covers behaviour, not wording. Log lines, error messages, tool descriptions and the prompt text sent to a model can change in any release, and so can the Pydantic AI class the toolsets inherit from. Freezing those would block routine fixes without protecting anyone's Dag.

The line is drawn at the parameter where a stable operator takes an experimental type. LLMBranchOperator turns every plain-string branch description into a BranchOption, so the descriptions stay stable while BranchOption.min_confidence and decision_policy are experimental.

This is the bottom of a stack for the native agent framework work. Each PR above it adds its own row to this page.

The stability page as rendered:

Stable and experimental features page


  • Read the Pull Request Guidelines for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
  • For fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
  • When adding dependency, check compliance with the ASF 3rd Party License Policy.
  • For significant user-facing changes create newsfragment: {pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.

Add a stability page listing what stays the same for each stable feature
and why the rest is experimental, and note the experimental status on
each experimental feature's page and in its class docstring.
@kaxil
kaxil added this pull request to stack #73905 September 29, 2026 12:49
@kaxil
kaxil marked this pull request as ready for review September 29, 2026 13:17
@kaxil
kaxil merged commit 647add7 into main Sep 29, 2026
90 of 95 checks passed
@kaxil
kaxil deleted the commonai-stability-page branch September 29, 2026 14:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants