Skip to content

Fix stale and duplicated content in the common.ai provider docs - #73567

Merged
kaxil merged 2 commits into
apache:mainfrom
astronomer:commonai-docs-content
Sep 23, 2026
Merged

kaxil merged 2 commits into
apache:mainfrom
astronomer:commonai-docs-content

Conversation

@kaxil

@kaxil kaxil commented Sep 22, 2026

Copy link
Copy Markdown
Member

The common.ai docs were reorganized recently without rewriting the pages, and a read of every page afterwards found problems in the words rather than the structure. This PR fixes them. No page moves; the sidebar is unchanged.

Correctness. The schema-compare page told readers to set context_strategy="full" to get keys and indexes, but that is the default; the section now shows opting down to "basic" and the parameter bullet, which was garbled, is rewritten. The LangChain connection page called Anthropic OpenAI-compatible; the real criterion is a LangChain model class that accepts api_key and base_url, and the page, the hook page and the hook docstring now say so. The two TypeSafe pages gave different install commands and now agree on the provider's typesafe extra. The LLM operator page lists fallback_conn_ids, which the operator accepts. The document loader example passes a llamaindex connection to the LlamaIndex embedding operator instead of an OpenAI one.

Duplication. Each explanation now has one home and the other pages link to it: the connection-type rename note (troubleshooting), the MCP token_provider and env_provider callables (the toolset page, with the connection page keeping the fields), the LlamaIndex OpenAI-only model check (the hook page), the model resolution order (the connection page, now including the spec-file case that only the hook page mentioned) and the HITL review parameters (the review page).

Stale text. Review-process language ("pre-PR behavior", "tracked as a follow-up", "left out of this change", a "roadmap" section) is gone, as are version-pinned claims ("2.46+", "verified against 2.23.0 and 2.31.1", "legacy flag from 1.x") and a paragraph quoting calibration scores from one classifier release. The one version that stays is the pydantic-ai-slim release that ships the TypeSafe adapter, on the classifier page, because the provider's extra does not pin it (raising that floor is a dependency change, not a docs one).

Model ids. The tree used four OpenAI ids, one of them invented (gpt-5.6-sol, in the quick start and the connection form placeholder). Docs, docstrings, provider.yaml and the example Dags now use gpt-5 with gpt-5-mini as the cheap variant, and claude-sonnet-5 with claude-haiku-4-5-20251001 for Anthropic. Bedrock ids are untouched because they are a different namespace. The per-request batch example keeps gpt-4.1-mini, since it demonstrates a temperature override that the reasoning models reject.

Style. Em dashes are replaced with commas, colons or sentence breaks, tilde H3 underlines match the rest of the tree, extras installs are quoted so the brackets survive zsh, and "PydanticAI" is spelled pydantic-ai when it means the library.


  • 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.

@kaxil
kaxil marked this pull request as ready for review September 22, 2026 17:58
The navigation reorg moved pages without rewriting them. This pass fixes
what the words say.

Correctness: the schema-compare page described the default context
strategy as an opt-in and its parameter bullet was garbled; the LangChain
connection page called Anthropic OpenAI-compatible when the real criterion
is a model class that accepts api_key and base_url; the two TypeSafe pages
gave different install commands; the LLM operator page omitted
fallback_conn_ids; the document loader example passed an OpenAI connection
to an operator that needs a llamaindex one.

Duplication: the connection-type rename note lives once in troubleshooting,
the MCP token_provider and env_provider explanation lives on the toolset
page, the LlamaIndex OpenAI-only story lives on the hook page, the model
resolution order is one list on the connection page, and the HITL review
parameters are documented once.

Removed review-process language, version-pinned claims and one set of
measured calibration numbers that would rot. One OpenAI id and one
Anthropic id are used across the tree, plus a cheap variant of each; the
invented gpt-5.6-sol is gone from the quick start and the connection form.
Em dashes, tilde underlines, unquoted extras and the PydanticAI spelling
are normalized.
@kaxil
kaxil force-pushed the commonai-docs-content branch from 96ed370 to a087fc9 Compare September 23, 2026 09:30
@kaxil
kaxil merged commit 88c53ed into apache:main Sep 23, 2026
7 checks passed
@kaxil
kaxil deleted the commonai-docs-content branch September 23, 2026 09:31
zozo123 added a commit to zozo123/airflow that referenced this pull request Sep 24, 2026
Resolve conflicts with the common.ai docs rewrite on main (apache#73567,
apache#73589): keep main's wording and style, and add OpenSandbox where
main lists the shipped backends.

- installation.rst: take main's parenthesized extras list, keep
  ``opensandbox`` in the agent-tooling group.
- sandbox/index.rst: "Three backends ship"; add an OpenSandboxBackend
  row to the new "What enforces the boundary" table and cover it in
  the teardown paragraph that follows.
- sandbox/backends.rst: take main's Modal CPU default, keep the
  OpenSandbox CPU note; stop calling Modal the only backend that runs
  on Kubernetes, which the OpenSandbox section contradicts.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants