docs(py): upgrade plugin docstrings to landing-page hero style with inline return shapes

[huangjeff5]

Description

As part of PR stack #3 (branched off PR #2 reorg/py-plugins), this pull request audits all Genkit Python plugin and core packages to replace verbose ELI5 explanations and ASCII data-flow diagrams with professional, product-oriented landing-page hero snippets.

Key highlights:

• Calibrated Style Guide: Introduced genkit-docstring-style skill defining required code block formatting.
• Numbered Action Steps: Code snippets use # 1. ..., # 2. ..., # 3. ... comments guiding developers through initialization and execution.
• Inline Return Shapes (# =>): Illustrates expected response shapes directly inline without requiring execution.
• Clean Multi-Line Formatting: Formatted multi-line outputs cleanly across indented # lines without escape codes like \n.
• Strict Scope: Code examples are kept strictly on modules, classes, or functions that originally contained code examples.
• Model Standard: Recommends googleai/gemini-flash-latest, googleai/gemini-pro-latest, or vertexai/... equivalents across generation snippets.

Base Branch

Branches off of and targets reorg/py-plugins (#5644).

[gemini-code-assist]

Code Review

This pull request introduces a new docstring style guide (SKILL.md) for Genkit Python packages, mandating the "Landing Page Hero Snippet" pattern. This pattern focuses on clean, product-oriented code examples with numbered steps and inline return shape annotations (# =>), while removing verbose ELI5 explanations and ASCII diagrams. Accordingly, docstrings across multiple packages (including genkit-anthropic, genkit-django, genkit-fastapi, genkit-flask, genkit-googleai, genkit-googlecloud, genkit-middleware, genkit-ollama, genkit-openai, and genkit-vertexai) have been refactored to align with this style. The review feedback correctly identifies several bugs in the newly introduced code examples, such as incorrect attribute access on evaluation results, long-running operations, and media parts, which would lead to AttributeErrors at runtime.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[huangjeff5]

/gemini review

[gemini-code-assist]

Code Review

This pull request streamlines and simplifies the module-level docstrings across multiple Genkit Python packages by removing large ASCII diagrams, ELI5 explanations, and complex architecture overviews. These are replaced with concise descriptions, updated requirements, and cleaner, more practical code examples. The feedback points out a missing asyncio import in the veo.py example code block, which is necessary to make the snippet fully functional and copy-pasteable.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[hilariie]

The snippets read well, but some snippets still require implementation support. For example

1. Flask: genkit_flask_handler(ai) returns a decorator; the current form passes the flow as context_provider and returns the decorator as the response. Real usage is the stacked @app.post(...) / @genkit_flask_handler(ai) / @ai.flow() form.

2. Ollama does not accept string model definitions: models= is list[ModelDefinition]; strings hit AttributeError on .name. Either wrap in ModelDefinition(name=...) or (preferably) teach the plugin to accept strings so the snippet stays clean.

3. Model Garden: models register under modelgarden/, not vertexai/, and only when passed via models=[...]. modelgarden/claude-3-5-sonnet-v2 with an explicit models list resolves; vertexai/... never will.

4. Veo/Lyria route through the wrong path: Veo is a background model (start/check action pair), so ai.generate(...) isn't the invocation path. Lyria is Vertex-only predict-based audio with the same concern.

Since these are presented as runnable examples, could we either land the supporting changes first in an implementation PR, tracked by an issue, and rebase this PR onto it, or include the fixes here to avoid publishing these snippets before the behavior exists. If this is intended as follow-up work, could we link the tracking issue here and make the release ordering explicit?

[huangjeff5]

Thanks for the review @hilariie! We've updated the docstring examples across this PR so that every snippet reflects APIs that run on this branch today, without relying on unmerged follow-up PRs:

1. Flask (genkit-flask):

   • Switched the snippet to the stacked decorator pattern (@app.post(...) / @genkit_flask_handler(ai) / @ai.flow()) on a single async flow handler function.

2. Ollama (genkit-ollama):

   • Updated the init snippet to plugins=[Ollama()] and pass model='ollama/llama3.2' directly in ai.generate(...). Lazy model resolution works on this branch today without passing string model lists at plugin initialization.

3. Model Garden (genkit-vertexai):

   • Corrected the namespace and model reference to model='modelgarden/anthropic/claude-3-5-sonnet-v2@20241022', matching the modelgarden/ plugin registration and publisher qualification.

4. Veo & Lyria (genkit-google-genai):

   • Removed the runnable ai.generate(...) code examples for now, leaving concise module description blurbs. We will re-add the full generate & polling operation snippets once background operations support (feat(py): support Google AI Interactions and background models (Veo, Deep Research, Antigravity, Lyria) #5806) lands.

The fixes have been pushed to reorg/py-plugins-docstrings. Ready for another look!

[hilariie]

LGTM