Python SDK beta proposal

[huangjeff5]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello @huangjeff5, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive proposal for the Genkit Python SDK's public API surface, aiming to enhance its Pythonic nature, consistency, and developer experience for the beta release. It addresses existing friction points by clearly segmenting the API for app developers and plugin authors, standardizing conventions, and streamlining configuration and streaming mechanisms. The changes are designed to improve usability, type safety, and maintainability across the SDK.

Highlights

• Formalized Public API Entry Points: The Python SDK's public API is now clearly defined with three distinct entry points: genkit for app developers (core framework), genkit.types for app developers (data types), and genkit.plugin for plugin authors (contract types and metadata builders). This separation clarifies audience-specific imports and improves discoverability.
• Adopted Pythonic API Conventions: The SDK now enforces keyword-only arguments for public methods, uses keyword arguments over options dictionaries, and aims for a single, obvious way to configure behaviors. This enhances code readability, type checking, and IDE autocomplete.
• Streamlined Output Configuration: The generate() method's output configuration has been simplified to use flat keyword arguments like output_schema, output_format, and output_constrained, removing redundant OutputConfig, OutputConfigDict, and Output[T] types from the app developer's surface. This provides a clearer and more Pythonic approach to typed responses.
• Proposed Dual Sync/Async Clients: A proposal is made to introduce both Genkit (sync) and AsyncGenkit (async) clients, aligning with industry standards from other major Python LLM SDKs. This addresses friction points for developers in various execution environments like Flask, Jupyter notebooks, and CLI scripts.
• Refined Streaming API: The streaming API for generate_stream() and prompt.stream() is updated to return a directly iterable object with a .response property for the final assembled response, standardizing the streaming pattern across the SDK and removing the tuple return.
• Cleaned Up Method Signatures: Method signatures for generate(), prompt.__call__(), generate_stream(), retrieve(), and embed() have been refined to enforce keyword-only arguments, remove unnecessary parameters (e.g., on_chunk), and consolidate options, improving clarity and maintainability.
• Veneer Naming Aliasing: Internal 'Wrapper' suffixes for veneer types (e.g., GenerateResponseWrapper) are now aliased to cleaner names (e.g., GenerateResponse) at the public surface, preventing implementation details from leaking into the public API.
• RetrieverResponse Iterability: RetrieverResponse now implements Python's sequence protocol (__iter__, __len__, __getitem__), allowing direct iteration over documents and behaving more like a collection-like object.
• Internal Module Underscoring: Internal modules like genkit.core, genkit.blocks, and genkit.ai are proposed to be renamed with an underscore prefix (e.g., genkit._core) to clearly signal their private nature and lack of stability guarantees, preventing accidental external dependencies.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• py/docs/python_beta_api_proposal.md
  • Added a new document outlining the proposed public API surface for the Genkit Python SDK, detailing entry points, type architecture, and symbol lists for app developers and plugin authors.
• py/docs/python_beta_sdk_audit.md
  • Added a new document summarizing resolved API issues and decisions based on an audit of the Python SDK, covering topics like keyword-only arguments, decorator shorthands, Part constructor, RetrieverResponse iterability, response.media property, veneer naming, type consolidation, and public API cleanup.
• py/docs/python_beta_sdk_design.md
  • Added a new document detailing the API design review for the Genkit Python SDK, establishing guiding principles, discussing open questions related to output configuration, streaming API, sync/async support, and method signatures.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive and well-thought-out proposal for a new Python SDK API design. The changes, presented in several detailed markdown documents, aim to create a more Pythonic, consistent, and user-friendly interface. The proposals for keyword-only arguments, distinct entry points for different user personas, a simplified streaming API, and dual sync/async clients are excellent improvements. My review focuses on ensuring the documentation is consistent and accurate, and I've identified a few minor areas for clarification and correction within the proposal documents.

[gemini-code-assist]

The description of MessageWrapper appears to be inconsistent. The document states that it uses composition and "doesn't extend" Message. However, the provided source code in py/packages/genkit/src/genkit/blocks/model.py shows class MessageWrapper(Message):, which is inheritance. This is a key detail for developers, as it affects type hinting and usage. Please update the documentation to accurately reflect that MessageWrapper extends Message.

[huangjeff5]

already decided; doing inline kwargs, we can still parametrize types

[huangjeff5]

remove Layer 3 stuff, noisy