[PR] Add use-case pages to the `common.ai` provider docs [airflow]

["kaxil (via GitHub)" <gi...@apache.org>]

kaxil opened a new pull request, #73542:
URL: https://github.com/apache/airflow/pull/73542

   The `common.ai` docs answer "how do I call this operator" well and "what could I build with this" not at all. The nav is organized by mechanism, the only scenario-shaped material sat under an "Examples" caption near the bottom of the sidebar, and six of the richest example Dags (RAG over PDFs, the LangChain 10-K variant, both survey-analysis Dags, the research agent, the classifier example) were linked to GitHub without a single `exampleinclude`. A data engineer who has heard of the provider and wants inspiration never sees a page titled after an outcome they recognize.
   
   This adds a **What you can build** section directly after Getting started: an overview page and ten scenario pages, each starting from a job a data team already has (triage support tickets, route a failed task to a fix or a person, block a load on schema drift, explain a revenue anomaly, monthly report from a CSV, compare 10-K filings, ask questions over PDFs, weekly status report with a hallucination check, classify reviews in bulk, research agent with human review). Every page follows the same shape: the problem, what this demonstrates with links to the operator pages, how to run it, the Dag embedded via `exampleinclude`, and how to adapt it. The overview closes with eight more scenarios described in a sentence each, for ideas without a Dag yet. The end-to-end pipelines page is folded into the new pages with a redirect, and the examples page becomes an operator-indexed list under References.
   
   ## Design rationale
   
   **The use-case pages embed the same Dags the operator pages embed, and that is deliberate.** The alternative is to link across and keep one copy of each snippet. It loses because a use-case page is read top to bottom by someone deciding whether to try the provider; sending them to a second page for the code breaks that. The operator pages stay the reference for parameters and edge cases; the use-case pages carry the scenario and the embedded code. The `exampleinclude` markers mean both render from one source file, so nothing drifts.
   
   The pages install-and-connection boilerplate once, on the overview. Each page's "Run it" lists only what that Dag adds: extra connections, env vars, the trigger command.
   
   Three source fixes came out of checking every claim against the Dags: the triage example's `[START]` marker now sits above the `TicketAnalysis` class so the embedded snippet shows the output type it uses; a comment on the survey example said the schema check "raises if critical columns are missing", which `LLMSchemaCompareOperator` does not do (it reports a `compatible` flag); and the 10-K module docstrings named the HITL task `analyst_question` when its id is `analyst_input`.
   
   ## Gotchas
   
   * No screenshots. None exist for these Dags yet, and the "Run it" step on each page tells the reader what to look at instead. The two pages that would gain most from a Grid screenshot are the triage page (mapped tasks) and the 10-K page (a parked HITL task).
   * Four of the Dags pause on `HITLEntryOperator` or `ApprovalOperator`. Under `airflow dags test` the run waits until someone answers from Required Actions in the UI of an api-server on the same metadata database. The overview says this once and the four pages point at it, because a reader who does not know it concludes the command hung.
   
   <img width="1099" height="718" alt="image" src="https://github.com/user-attachments/assets/4f8eb810-159c-4e79-8db2-d616cafa5e91" />
   <img width="1107" height="750" alt="image" src="https://github.com/user-attachments/assets/a7096b3c-35a5-48af-8432-0faad4efd03a" />
   
   
   
   
   ---
   
   * Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#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](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals)) is needed.
   * When adding dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
   * For significant user-facing changes create newsfragment: `{pr_number}.significant.rst`, in [airflow-core/newsfragments](https://github.com/apache/airflow/tree/main/airflow-core/newsfragments). You can add this file in a follow-up commit after the PR is created so you know the PR number.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Add use-case pages to the `common.ai` provider docs [airflow]

["kaxil (via GitHub)" <gi...@apache.org>]

kaxil merged PR #73542:
URL: https://github.com/apache/airflow/pull/73542


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org