kaxil commented on code in PR #69552: URL: https://github.com/apache/airflow/pull/69552#discussion_r3542711077
########## providers/common/ai/docs/quickstart.rst: ########## @@ -0,0 +1,94 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/quickstart: + +Quick start +=========== + +Go from zero to a running LLM task in three steps: install the provider, +configure a connection, and write a Dag. + +1. Install +---------- + +.. code-block:: bash + + pip install apache-airflow-providers-common-ai Review Comment: The base package pulls only `pydantic-ai-slim` (no model SDKs), so this install can't run the `openai:gpt-5.3` example from step 2. Verified on a clean install: after `pip install apache-airflow-providers-common-ai`, constructing the model raises `ImportError: Please install the openai package ... pip install "pydantic-ai-slim[openai]"`, and the `summarize` task fails at runtime with it; installing the extra clears it. So step 1 should install the matching extra: ```bash pip install "apache-airflow-providers-common-ai[openai]" ``` Worth one line noting the extra tracks the provider you configure (`[anthropic]`, `[google]`, `[bedrock]`, ...). ########## providers/common/ai/docs/quickstart.rst: ########## @@ -0,0 +1,94 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/quickstart: + +Quick start +=========== + +Go from zero to a running LLM task in three steps: install the provider, +configure a connection, and write a Dag. + +1. Install +---------- + +.. code-block:: bash + + pip install apache-airflow-providers-common-ai + +2. Configure the connection +---------------------------- + +Every LLM call goes through a Pydantic AI connection (``conn_type`` ``pydanticai``, +default connection id ``pydanticai_default``). The model is set in ``provider:model`` +format and the API key goes in the password field. See :ref:`howto/connection:pydanticai` +for the full reference, including providers that +don't need an API key (Bedrock, Vertex AI). + +The quickest way to set one up is an environment variable: + +.. code-block:: bash + + export AIRFLOW_CONN_PYDANTICAI_DEFAULT='{"conn_type": "pydanticai", "password": "sk-...", "extra": "{\"model\": \"openai:gpt-5.3\"}"}' + +Or add it through the Airflow UI (``Admin > Connections``) or the CLI (``airflow connections add``). + +3. Write your first Dag +------------------------ + +The ``@task.llm`` decorator turns a function that returns a prompt string into +a task that sends that prompt to the LLM and returns its response: + +.. code-block:: python Review Comment: This is a complete runnable DAG, but every other full DAG in the provider docs uses `.. exampleinclude::` from a tested `example_dags/` file; inline `code-block:: python` is reserved for fragments. As inline code it isn't covered by the example-import check, so it can silently rot when the decorator signature or `airflow.sdk` surface changes, and it's the one snippet a newcomer copies verbatim. It's also byte-for-byte the `howto_decorator_llm` slice of `example_dags/example_llm.py`, so it duplicates a DAG we already test. (The code itself is fine -- it runs on 3.4.0 via `airflow dags test` -- the concern is that it's uncovered and duplicated.) Suggest `exampleinclude`-ing it. One wrinkle: the existing example imports `from airflow.providers.common.compat.sdk import dag, task`, whereas here you (rightly) want the cleaner `from airflow.sdk import dag, task` for a 3.0+ reader, so a small dedicated `example_quickstart.py` on `airflow.sdk` is probably the cleanest source. While moving it: add `schedule=None` (siblings set it), and drop the doubled "summarize" (the `system_prompt` and the returned prompt both say it -- a first example reads cleaner with the instruction in one slot). ########## providers/common/ai/docs/quickstart.rst: ########## @@ -0,0 +1,94 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/quickstart: + +Quick start +=========== + +Go from zero to a running LLM task in three steps: install the provider, +configure a connection, and write a Dag. + +1. Install +---------- + +.. code-block:: bash + + pip install apache-airflow-providers-common-ai + +2. Configure the connection +---------------------------- + +Every LLM call goes through a Pydantic AI connection (``conn_type`` ``pydanticai``, +default connection id ``pydanticai_default``). The model is set in ``provider:model`` +format and the API key goes in the password field. See :ref:`howto/connection:pydanticai` +for the full reference, including providers that +don't need an API key (Bedrock, Vertex AI). + +The quickest way to set one up is an environment variable: + +.. code-block:: bash + + export AIRFLOW_CONN_PYDANTICAI_DEFAULT='{"conn_type": "pydanticai", "password": "sk-...", "extra": "{\"model\": \"openai:gpt-5.3\"}"}' Review Comment: Two small things. `openai:gpt-5.3` and `sk-...` are placeholders a reader pastes verbatim (the model constructs without complaint and only fails at call time), so add "replace `openai:gpt-5.3` with a model you have access to and `sk-...` with your API key." And the nested-JSON-as-a-string `extra` is the error-prone form; `Connection.from_json` accepts a nested object (`sdk/definitions/connection.py:349-353`), verified end-to-end that the DAG resolves the model from it, so this is cleaner and equally valid: ```bash export AIRFLOW_CONN_PYDANTICAI_DEFAULT='{"conn_type": "pydanticai", "password": "sk-...", "extra": {"model": "openai:gpt-5.3"}}' ``` ########## providers/common/ai/docs/quickstart.rst: ########## @@ -0,0 +1,94 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/quickstart: + +Quick start +=========== + +Go from zero to a running LLM task in three steps: install the provider, Review Comment: Two things for the opener. (1) It starts at installing the provider but assumes Airflow 3.0+ is already installed and initialized, and that step 3 makes a live, billed model call needing a real key -- verified: with the connection pointed at a fake key the `summarize` task runs and fails with a 401 from the OpenAI API, i.e. it does reach a real credentialed call. A short "before you start" line (assumes a working Airflow 3.0+ install, with a link to the core install; runs a real billed call; needs a provider API key) sets expectations. (2) "Go from zero to a running LLM task in three steps" reads like marketing; something plainer such as "This guide installs the provider, configures a connection, and runs a first LLM task" matches the rest of the docs. -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
