chore(py): re-organize file structure, api signatures, types by huangjeff5 · Pull Request #4879 · firebase/genkit

huangjeff5 · 2026-03-03T17:22:03Z

No description provided.

gemini-code-assist · 2026-03-03T17:28:05Z

Summary of Changes

Hello, 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 undertakes a substantial refactoring of the Python SDK, focusing on internal module consolidation and a more consistent, async-first public API. The changes aim to streamline development, improve clarity of core functionalities, and enhance the overall architectural design of the Genkit framework.

Highlights

Core Module Restructuring: The internal structure of the Python SDK has been significantly reorganized. Modules previously under genkit/blocks and genkit/aio have been consolidated into genkit/ai or genkit/core/_internal for a cleaner separation of concerns and improved maintainability.
API Signature Standardization: Key API methods within the Genkit class, such as generate, generate_stream, define_prompt, define_resource, dynamic_tool, and define_simple_retriever, have been updated to use direct keyword arguments for configuration and schema definitions, replacing previous object-based parameters like output and input.
Type and Class Renaming: Several core types and classes have been renamed for clarity and consistency across the SDK. Notable changes include GenerateResponseWrapper to ModelResponse, GenerateResponseChunkWrapper to ModelResponseChunk, GenerateStreamResponse to ModelStreamResponse, GenerationCommonConfig to ModelConfig, UserFacingError to PublicError, and ModelReference to ModelRef.
Asynchronous Handler Enforcement: Core action kinds (TOOL, MODEL, RETRIEVER, EMBEDDER, FLOW) now strictly require asynchronous functions as handlers, ensuring a consistent async-first approach throughout the framework and raising a TypeError if a synchronous function is provided.
Reflection Server Integration: The reflection server logic, crucial for the developer UI, has been integrated directly into the genkit.ai/_aio.py and genkit._web/_reflection.py modules, and now runs in a background daemon thread during development mode.

🧠 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/bin/sanitize_schema_typing.py
- Updated import path for StrEnum.
py/packages/genkit/src/genkit/init.py
- Updated docstring for clarity.
- Removed several re-exported symbols.
- Adjusted import paths for core types.
py/packages/genkit/src/genkit/_web/init.py
- Renamed from py/packages/genkit/src/genkit/web/__init__.py.
py/packages/genkit/src/genkit/_web/_reflection.py
- Renamed from py/packages/genkit/src/genkit/core/reflection.py.
- Added imports for threading and uvicorn.
- Updated import paths for internal modules.
- Changed action.arun_raw calls to action.run_raw.
- Introduced _ReflectionServer class and _make_reflection_server function for background reflection server management.
py/packages/genkit/src/genkit/_web/typing.py
- Renamed from py/packages/genkit/src/genkit/web/typing.py.
- Updated import path in example code.
- Added imports for Mapping and dataclass.
- Moved ServerSpec, is_streaming_requested, and is_query_flag_enabled definitions to this file.
py/packages/genkit/src/genkit/ai/init.py
- Updated docstring.
- Renamed GenerateResponseWrapper to ModelResponse and GenerateStreamResponse to ModelStreamResponse.
- Removed several re-exported symbols.
- Adjusted import paths.
py/packages/genkit/src/genkit/ai/_aio.py
- Removed inheritance from GenkitBase.
- Integrated reflection server logic directly into this file.
- Added imports for threading, socket, anyio, and uvicorn.
- Updated internal import paths.
- Replaced arun calls with run for action execution.
- Modified generate method signature to remove on_chunk parameter and accept direct output configuration arguments.
- Updated generate_stream to use ModelResponseChunk and ModelResponse.
- Introduced new define_* methods for various Genkit components (flow, helper, partial, schema, DAP, tool, retriever, indexer, reranker, evaluator, model, background model, embedder, format, prompt, resource).
- Added run_main method for managing the main coroutine execution.
py/packages/genkit/src/genkit/ai/_runtime.py
- Updated import paths for _constants, _logging, and ServerSpec.
py/packages/genkit/src/genkit/ai/document.py
- Renamed from py/packages/genkit/src/genkit/blocks/document.py.
- Updated import path for _typing.
py/packages/genkit/src/genkit/ai/embedding.py
- Renamed from py/packages/genkit/src/genkit/blocks/embedding.py.
- Updated import paths for internal modules.
- Changed _action.arun calls to _action.run.
- Added _get_func_description and define_embedder functions.
py/packages/genkit/src/genkit/ai/evaluator.py
- Added new file for evaluator definitions and related functions (define_evaluator, define_batch_evaluator).
py/packages/genkit/src/genkit/ai/formats/init.py
- Renamed from py/packages/genkit/src/genkit/blocks/formats/__init__.py.
- Updated package name string.
py/packages/genkit/src/genkit/ai/formats/array.py
- Renamed from py/packages/genkit/src/genkit/blocks/formats/array.py.
- Updated import paths.
- Changed GenerateResponseChunkWrapper to ModelResponseChunk.
py/packages/genkit/src/genkit/ai/formats/enum.py
- Renamed from py/packages/genkit/src/genkit/blocks/formats/enum.py.
- Updated import paths.
- Changed GenerateResponseChunkWrapper to ModelResponseChunk.
py/packages/genkit/src/genkit/ai/formats/json.py
- Renamed from py/packages/genkit/src/genkit/blocks/formats/json.py.
- Updated import paths.
- Changed GenerateResponseChunkWrapper to ModelResponseChunk.
py/packages/genkit/src/genkit/ai/formats/jsonl.py
- Renamed from py/packages/genkit/src/genkit/blocks/formats/jsonl.py.
- Updated import paths.
- Changed GenerateResponseChunkWrapper to ModelResponseChunk.
py/packages/genkit/src/genkit/ai/formats/text.py
- Renamed from py/packages/genkit/src/genkit/blocks/formats/text.py.
- Updated import paths.
- Changed GenerateResponseChunkWrapper to ModelResponseChunk.
py/packages/genkit/src/genkit/ai/formats/types.py
- Renamed from py/packages/genkit/src/genkit/blocks/formats/types.py.
- Updated import paths.
- Changed GenerateResponseChunkWrapper to ModelResponseChunk.
py/packages/genkit/src/genkit/ai/generate.py
- Renamed from py/packages/genkit/src/genkit/blocks/generate.py.
- Updated import paths for internal modules.
- Changed GenerateResponseWrapper to ModelResponse and GenerateResponseChunkWrapper to ModelResponseChunk.
- Replaced arun calls with run.
py/packages/genkit/src/genkit/ai/messages.py
- Renamed from py/packages/genkit/src/genkit/blocks/messages.py.
- Updated import path for _typing.
py/packages/genkit/src/genkit/ai/middleware.py
- Renamed from py/packages/genkit/src/genkit/blocks/middleware.py.
- Updated import paths.
py/packages/genkit/src/genkit/ai/model.py
- Renamed from py/packages/genkit/src/genkit/blocks/model.py.
- Updated import paths for internal modules.
- Renamed GenerateResponseWrapper to ModelResponse, GenerateResponseChunkWrapper to ModelResponseChunk, and ModelReference to ModelRef.
- Added get_func_description, define_model, ModelConfig, get_request_api_key, and get_effective_api_key functions.
py/packages/genkit/src/genkit/ai/prompt.py
- Renamed from py/packages/genkit/src/genkit/blocks/prompt.py.
- Updated import paths for internal modules.
- Changed GenerateStreamResponse to ModelStreamResponse and GenerateResponseWrapper to ModelResponse.
- Modified define_prompt signature to accept input_schema and output_schema directly.
py/packages/genkit/src/genkit/ai/reranker.py
- Renamed from py/packages/genkit/src/genkit/blocks/reranker.py.
- Updated import paths for internal modules.
- Changed action_response.arun to action_response.run.
py/packages/genkit/src/genkit/ai/resource.py
- Renamed from py/packages/genkit/src/genkit/blocks/resource.py.
- Updated import paths for internal modules.
- Changed ResourceFn to strictly require an async function.
- Added type checking for async functions in dynamic_resource.
py/packages/genkit/src/genkit/ai/retriever.py
- Renamed from py/packages/genkit/src/genkit/blocks/retriever.py.
- Updated import paths for internal modules.
- Added SimpleRetrieverOptions, _item_to_document, _item_to_metadata, _get_func_description, define_retriever_action, define_simple_retriever, and define_indexer_action functions.
py/packages/genkit/src/genkit/ai/tools.py
- Renamed from py/packages/genkit/src/genkit/blocks/tools.py.
- Updated import paths for internal modules.
- Added _get_func_description and define_tool functions.
py/packages/genkit/src/genkit/core/init.py
- Updated import paths for internal modules.
- Removed several re-exported symbols.
py/packages/genkit/src/genkit/core/_internal/init.py
- Renamed from py/packages/genkit/src/genkit/lang/__init__.py.
- Moved Channel, create_loop, ensure_async, iter_over_async, run_async, run_loop to this module.
py/packages/genkit/src/genkit/core/_internal/_aio.py
- Renamed from py/packages/genkit/src/genkit/aio/channel.py.
- Consolidated loop utilities and ensure_async into this module.
- Updated Channel generic types.
py/packages/genkit/src/genkit/core/_internal/_background.py
- Renamed from py/packages/genkit/src/genkit/blocks/background_model.py.
- Updated import paths for internal modules.
- Changed arun calls to run.
py/packages/genkit/src/genkit/core/_internal/_constants.py
- Renamed from py/packages/genkit/src/genkit/core/constants.py.
py/packages/genkit/src/genkit/core/_internal/_context.py
- Renamed from py/packages/genkit/src/genkit/core/context.py.
- Updated comment for PublicError.
py/packages/genkit/src/genkit/core/_internal/_dap.py
- Renamed from py/packages/genkit/src/genkit/blocks/dap.py.
- Updated import paths for internal modules.
- Changed action.arun calls to action.run.
py/packages/genkit/src/genkit/core/_internal/_deprecations.py
- Renamed from py/packages/genkit/src/genkit/lang/deprecations.py.
- Updated import path for _compat.
py/packages/genkit/src/genkit/core/_internal/_environment.py
- Renamed from py/packages/genkit/src/genkit/core/environment.py.
- Updated import path for _compat.
py/packages/genkit/src/genkit/core/_internal/_extract.py
- Renamed from py/packages/genkit/src/genkit/core/extract.py.
py/packages/genkit/src/genkit/core/_internal/_flow.py
- Added new file for flow wrapper and utilities.
py/packages/genkit/src/genkit/core/_internal/_http_client.py
- Renamed from py/packages/genkit/src/genkit/core/http_client.py.
- Updated import path for _logging.
py/packages/genkit/src/genkit/core/_internal/_logging.py
- Renamed from py/packages/genkit/src/genkit/core/logging.py.
- Updated example import path.
py/packages/genkit/src/genkit/core/_internal/_registry.py
- Renamed from py/packages/genkit/src/genkit/core/registry.py.
- Updated import paths for internal modules.
- Changed provider.arun calls to provider.run.
py/packages/genkit/src/genkit/core/_internal/_schema.py
- Renamed from py/packages/genkit/src/genkit/core/schema.py.
py/packages/genkit/src/genkit/core/_internal/_typing.py
- Renamed from py/packages/genkit/src/genkit/core/typing.py.
- Added DO NOT EDIT — auto-generated comment.
- Updated import path for _compat.
- Renamed GenerationCommonConfig to ModelConfig.
- Removed MiddlewareDesc and MiddlewareRef.
- Added metadata field to ToolResponse.
py/packages/genkit/src/genkit/core/action/init.py
- Consolidated ActionKind, ActionName, ActionResponse from types.py and create_action_key, parse_action_key from _key.py, parse_plugin_name_from_action_name from _util.py into _action.py and re-exported.
py/packages/genkit/src/genkit/core/action/_action.py
- Changed run method to be asynchronous.
- Removed arun method.
- Renamed arun_raw to run_raw.
- Added type enforcement for asynchronous handlers for core action kinds.
py/packages/genkit/src/genkit/core/action/_tracing.py
- Updated import path for _codec.
py/packages/genkit/src/genkit/core/error.py
- Updated error hierarchy diagram to reflect PublicError.
- Renamed UserFacingError to PublicError.
py/packages/genkit/src/genkit/core/plugin.py
- Updated import paths for ActionKind.
- Modified model and embedder methods to be asynchronous and return Action | None.
py/packages/genkit/src/genkit/core/trace/adjusting_exporter.py
- Updated import path for _compat.
py/packages/genkit/src/genkit/core/trace/default_exporter.py
- Updated import paths for _compat, _environment, _logging.
py/packages/genkit/src/genkit/core/trace/realtime_processor.py
- Updated import paths for _compat, _logging.
py/packages/genkit/src/genkit/core/trace/types.py
- Updated import path for _logging.
py/packages/genkit/src/genkit/core/tracing.py
- Updated import paths for _environment, _logging, _typing.
py/packages/genkit/src/genkit/testing.py
- Updated import paths for internal modules.
- Changed model_fn methods to be asynchronous.
- Updated ai.tool and ai.generate calls to reflect new API signatures.
py/plugins/amazon-bedrock/README.md
- Updated import path for genkit.types to genkit.
py/plugins/amazon-bedrock/src/genkit/plugins/amazon_bedrock/models/converters.py
- Updated import path for genkit.types to genkit.
py/plugins/amazon-bedrock/src/genkit/plugins/amazon_bedrock/models/model.py
- Updated import paths for _http_client, _logging, and genkit.types to genkit.
py/plugins/amazon-bedrock/src/genkit/plugins/amazon_bedrock/models/model_info.py
- Updated import path for genkit.types to genkit.
py/plugins/amazon-bedrock/src/genkit/plugins/amazon_bedrock/plugin.py
- Updated import paths for embedding, model, _logging, _registry, and genkit.types to genkit.
py/plugins/amazon-bedrock/src/genkit/plugins/amazon_bedrock/telemetry/tracing.py
- Updated import path for _environment.
py/plugins/amazon-bedrock/tests/amazon_bedrock_converters_test.py
- Updated import path for genkit.types to genkit.
py/plugins/amazon-bedrock/tests/amazon_bedrock_plugin_test.py
- Updated import path for genkit.types to genkit.
py/plugins/anthropic/src/genkit/plugins/anthropic/model_info.py
- Updated import path for genkit.types to genkit.
py/plugins/anthropic/src/genkit/plugins/anthropic/models.py
- Updated import paths for model, _logging, and genkit.types to genkit.
py/plugins/anthropic/src/genkit/plugins/anthropic/plugin.py
- Updated import paths for model, _registry, _schema, and genkit.types to genkit.
py/plugins/anthropic/src/genkit/plugins/anthropic/utils.py
- Updated import paths for _logging and genkit.types to genkit.
py/plugins/anthropic/tests/anthropic_models_test.py
- Updated import path for genkit.types to genkit.
py/plugins/anthropic/tests/anthropic_plugin_test.py
- Updated import path for _registry and genkit.types to genkit.
py/plugins/anthropic/tests/anthropic_utils_test.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/src/genkit/plugins/compat_oai/models/audio.py
- Updated import path for _typing and genkit.types to genkit.
py/plugins/compat-oai/src/genkit/plugins/compat_oai/models/handler.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/src/genkit/plugins/compat_oai/models/image.py
- Updated import path for _typing and genkit.types to genkit.
py/plugins/compat-oai/src/genkit/plugins/compat_oai/models/model.py
- Updated import paths for _logging, _typing, and genkit.types to genkit.
py/plugins/compat-oai/src/genkit/plugins/compat_oai/models/model_info.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/src/genkit/plugins/compat_oai/models/utils.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/src/genkit/plugins/compat_oai/openai_plugin.py
- Updated import paths for embedding, model, _registry, _schema, _typing, and genkit.types to genkit.
py/plugins/compat-oai/tests/audio_model_test.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/tests/compat_oai_model_test.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/tests/compat_oai_plugin_test.py
- Updated import path for _registry.
py/plugins/compat-oai/tests/compat_oai_utils_test.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/tests/conftest.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/tests/image_model_test.py
- Updated import path for genkit.types to genkit.
py/plugins/compat-oai/tests/tool_calling_test.py
- Updated import path for genkit.types to genkit.
py/plugins/dev-local-vectorstore/src/genkit/plugins/dev_local_vectorstore/constant.py
- Updated import path for genkit.types to genkit.
py/plugins/dev-local-vectorstore/src/genkit/plugins/dev_local_vectorstore/indexer.py
- Updated import paths for document, retriever, and genkit.types to genkit.
py/plugins/dev-local-vectorstore/src/genkit/plugins/dev_local_vectorstore/local_vector_store_api.py
- Updated import path for _codec.
py/plugins/dev-local-vectorstore/src/genkit/plugins/dev_local_vectorstore/plugin_api.py
- Updated import paths for retriever, _registry, and _schema.
py/plugins/dev-local-vectorstore/src/genkit/plugins/dev_local_vectorstore/retriever.py
- Updated import path for genkit.types to genkit.
py/plugins/dev-local-vectorstore/tests/dlvs_api_test.py
- Updated import path for genkit.types to genkit.
py/plugins/dev-local-vectorstore/tests/dlvs_indexer_test.py
- Updated import paths for document, retriever, and genkit.types to genkit.
py/plugins/fastapi/src/genkit/plugins/fastapi/handler.py
- Updated import paths for _codec and _context.
py/plugins/firebase/src/genkit/plugins/firebase/firestore.py
- Updated import paths for retriever, _registry, and _typing.
py/plugins/firebase/src/genkit/plugins/firebase/retriever.py
- Updated import paths for _typing and genkit.types to genkit.
py/plugins/firebase/src/genkit/plugins/firebase/telemetry.py
- Updated import path for _logging.
py/plugins/firebase/tests/firebase_retriever_test.py
- Updated import path for _typing.
py/plugins/flask/src/genkit/plugins/flask/handler.py
- Updated import paths for _internal, _codec, and _context.
py/plugins/flask/tests/flask_exports_test.py
- Updated import path for _context.
py/plugins/flask/tests/flask_test.py
- Updated import path for _context.
py/plugins/google-cloud/src/genkit/plugins/google_cloud/telemetry/config.py
- Updated import paths for _environment and _logging.
py/plugins/google-cloud/tests/tracing_test.py
- Updated import path for _environment.
py/plugins/google-genai/src/genkit/plugins/google_genai/evaluators/evaluation.py
- Updated import paths for evaluator, _http_client, and _typing.
py/plugins/google-genai/src/genkit/plugins/google_genai/google.py
- Updated import paths for _background, document, embedding, model, reranker, _registry, _schema, and _typing.
py/plugins/google-genai/src/genkit/plugins/google_genai/models/context_caching/utils.py
- Updated import path for _typing.
py/plugins/google-genai/src/genkit/plugins/google_genai/models/embedder.py
- Updated import path for genkit.types to genkit.
py/plugins/google-genai/src/genkit/plugins/google_genai/models/gemini.py
- Updated import paths for model, _codec, _typing, _deprecations, and genkit.types to genkit.
py/plugins/google-genai/src/genkit/plugins/google_genai/models/imagen.py
- Updated import paths for _codec and genkit.types to genkit.
py/plugins/google-genai/src/genkit/plugins/google_genai/models/lyria.py
- Updated import path for _typing.
py/plugins/google-genai/src/genkit/plugins/google_genai/models/utils.py
- Updated import paths for _http_client, _typing, and genkit.types to genkit.
py/plugins/google-genai/src/genkit/plugins/google_genai/models/veo.py
- Updated import paths for _typing and genkit.types to genkit.
py/plugins/google-genai/src/genkit/plugins/google_genai/rerankers/reranker.py
- Updated import paths for document, model, reranker, _http_client, and _typing.
py/plugins/google-genai/test/google_plugin_test.py
- Updated import path for _registry and genkit.types to genkit.
py/plugins/google-genai/test/models/googlegenai_embedder_test.py
- Updated import path for genkit.types to genkit.
py/plugins/google-genai/test/models/googlegenai_gemini_test.py
- Updated import path for _schema and genkit.types to genkit.
py/plugins/google-genai/test/models/googlegenai_imagen_test.py
- Updated import path for genkit.types to genkit.
py/plugins/google-genai/tests/google_genai_plugin_test.py
- Updated import path for _registry.
py/plugins/google-genai/tests/part_converter_test.py
- Updated import path for genkit.types to genkit.
py/plugins/google-genai/tests/rerankers_test.py
- Updated import paths for document and _typing.
py/plugins/ollama/src/genkit/plugins/ollama/converters.py
- Updated import path for genkit.types to genkit.
py/plugins/ollama/src/genkit/plugins/ollama/embedders.py
- Updated import paths for embedding and genkit.types to genkit.
py/plugins/ollama/src/genkit/plugins/ollama/models.py
- Updated import paths for model, _http_client, and genkit.types to genkit.
py/plugins/ollama/src/genkit/plugins/ollama/plugin_api.py
- Updated import paths for embedding, model, _registry, _schema, and genkit.types to genkit.
py/plugins/ollama/tests/integration_test.py
- Updated import path for genkit.types to genkit.
py/plugins/ollama/tests/models/embedders_test.py
- Updated import paths for _typing and genkit.types to genkit.
py/plugins/ollama/tests/models/ollama_models_test.py
- Updated import path for model and genkit.types to genkit.
py/plugins/ollama/tests/ollama_converters_test.py
- Updated import path for genkit.types to genkit.
py/plugins/vertex-ai/src/genkit/plugins/vertex_ai/model_garden/anthropic.py
- Updated import paths for _typing and genkit.types to genkit.
py/plugins/vertex-ai/src/genkit/plugins/vertex_ai/model_garden/model_garden.py
- Updated import path for genkit.types to genkit.
py/plugins/vertex-ai/src/genkit/plugins/vertex_ai/model_garden/modelgarden_plugin.py
- Updated import paths for model, _registry, and _schema.
py/plugins/vertex-ai/src/genkit/plugins/vertex_ai/vector_search.py
- Updated import paths for document, retriever, _registry, _schema, _typing, and genkit.types to genkit.
py/plugins/vertex-ai/tests/vector_search/retrievers_test.py
- Updated import paths for document, _typing, and genkit.types to genkit.
py/samples/dev-local-vectorstore-hello/src/main.py
- Updated import path for genkit.types to genkit.
py/samples/framework-context-demo/src/main.py
- Updated import path for _logging.
py/samples/framework-custom-evaluators/src/deliciousness_evaluator.py
- Updated import path for _typing.
py/samples/framework-custom-evaluators/src/funniness_evaluator.py
- Updated import path for _typing.
py/samples/framework-custom-evaluators/src/main.py
- Updated import path for _logging.
py/samples/framework-custom-evaluators/src/pii_evaluator.py
- Updated import path for _typing.
py/samples/framework-custom-evaluators/src/regex_evaluator.py
- Updated import path for _typing.
py/samples/framework-dynamic-tools-demo/src/main.py
- Updated import path for _logging.
- Modified ai.run and ai.dynamic_tool calls to reflect new API signatures.
py/samples/framework-format-demo/src/main.py
- Updated import paths for _logging and _typing.
py/samples/framework-middleware-demo/src/main.py
- Updated import paths for model, _logging, and genkit.types to genkit.
py/samples/framework-prompt-demo/src/main.py
- Updated import path for _logging.
py/samples/framework-realtime-tracing-demo/src/main.py
- Updated import path for _logging.
py/samples/framework-restaurant-demo/src/case_03/chats.py
- Updated import path for _typing.
py/samples/framework-restaurant-demo/src/case_03/flows.py
- Updated import path for _typing.
py/samples/framework-restaurant-demo/src/case_04/flows.py
- Updated import path for document.
py/samples/provider-amazon-bedrock-hello/src/main.py
- Updated import paths for _logging and genkit.types to genkit.
py/samples/provider-anthropic-hello/src/main.py
- Updated import paths for _logging and genkit.types to genkit.
py/samples/provider-compat-oai-hello/src/main.py
- Updated import paths for _logging and genkit.types to genkit.
py/samples/provider-firestore-retriever/src/main.py
- Updated import path for genkit.types to genkit.
py/samples/provider-google-genai-code-execution/src/main.py
- Updated import paths for model, _logging, and _typing.
py/samples/provider-google-genai-context-caching/src/main.py
- Updated import paths for _logging and genkit.types to genkit.
py/samples/provider-google-genai-hello/src/main.py
- Updated import paths for _logging and genkit.types to genkit.
py/samples/provider-google-genai-hello/src/main_vertexai.py
- Updated import path for genkit.types to genkit.
py/samples/provider-google-genai-media-models-demo/src/main.py
- Updated import paths for _background, model, _typing, and genkit.types to genkit.
py/samples/provider-google-genai-vertexai-hello/src/main.py
- Updated import paths for _logging and genkit.types to genkit.
py/samples/provider-google-genai-vertexai-image/src/main.py
- Updated import path for model.
py/samples/provider-ollama-hello/src/main.py
- Updated import paths for model, _logging, and _typing.
py/samples/provider-vertex-ai-model-garden/src/main.py
- Updated import paths for _logging and genkit.types to genkit.
py/samples/provider-vertex-ai-rerank-eval/src/main.py
- Updated import paths for document and _typing.
py/samples/provider-vertex-ai-vector-search-bigquery/src/main.py
- Updated import paths for document and _logging.
py/samples/provider-vertex-ai-vector-search-bigquery/src/setup_env.py
- Updated import paths for _typing and genkit.types to genkit.
py/samples/provider-vertex-ai-vector-search-firestore/src/main.py
- Updated import paths for document, _logging, and _typing.
py/samples/shared/flows.py
- Updated import paths for _logging and genkit.types to genkit.
- Modified ai.generate call to reflect new API signatures.
py/samples/web-fastapi-bugbot/src/main.py
- Removed Input and Output imports.
- Updated ai.prompt calls to reflect new API signatures.
py/samples/web-flask-hello/src/main.py
- Updated import paths for model and _context.
- Changed ai.generate call to ai.generate_stream and adjusted streaming logic.
py/tools/conform/src/conform/executors/conformance_native.py
- Updated import paths for _codec and _action.
- Updated import path for _typing.
py/tools/conform/src/conform/executors/in_process_runner.py
- Updated import paths for _codec, _typing, and _action.
py/tools/model-config-test/run_single_model_test.py
- Updated import path for _typing.
py/tools/sample-flows/review_sample_flows.py
- Updated import path for genkit.types to genkit.
- Updated import path for prompt.
py/tools/sample-flows/run_single_flow.py
- Updated import path for genkit.types to genkit.
- Updated import path for prompt.
- Changed flow_action.arun to flow_action.run.

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.

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 is a significant refactoring that reorganizes the file structure and simplifies several key API signatures. The changes, such as renaming arun() to run(), making core actions async-only, and replacing Input/Output wrappers with direct schema arguments, make the API more consistent and modern. The codebase, including samples and tests, has been updated thoroughly to reflect these changes. I've pointed out a few places where type hints for decorators and methods should be updated to match the new async requirements, which will improve static analysis and developer experience.

_{Note: Security Review did not run due to the size of the PR.}

py/packages/genkit/src/genkit/ai/_aio.py

py/packages/genkit/tests/genkit/ai/formats/enum_test.py

py/plugins/vertex-ai/tests/vector_search/retrievers_test.py

py/packages/genkit/src/genkit/core/codec.py

py/packages/genkit/src/genkit/_web/_reflection.py

py/packages/genkit/src/genkit/ai/model.py

py/bin/sanitize_schema_typing.py

py/packages/genkit/src/genkit/ai/__init__.py

py/samples/provider-google-genai-media-models-demo/src/main.py

py/samples/provider-google-genai-code-execution/src/main.py

py/plugins/google-genai/src/genkit/plugins/google_genai/models/utils.py

huangjeff5 · 2026-03-05T04:46:28Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a major refactoring of the Python SDK, reorganizing the file structure into _core and _ai modules and establishing a new public API surface. A significant change is making actions, flows, and tools async-only, which simplifies the concurrency model. The refactoring appears well-executed and consistent. I've identified a couple of minor code quality issues related to duplicate entries in a configuration set and the __all__ export list, which should be addressed for better maintainability.

_{Note: Security Review did not run due to the size of the PR.}

py/bin/sanitize_schema_typing.py

py/packages/genkit/src/genkit/__init__.py

huangjeff5 · 2026-03-11T16:19:31Z

py/packages/genkit/src/genkit/_ai/_model.py

+    config: dict[str, object] | None = None,
+) -> ModelRef:
+    """Create a ModelRef, optionally prefixing name with namespace."""
+    # Logic: if (options.namespace && !name.startsWith(options.namespace + '/'))


remove logic comment, outdated

huangjeff5 · 2026-03-11T16:20:47Z

py/packages/genkit/src/genkit/_ai/_model.py

+
+
+def get_request_api_key(config: Mapping[str, object] | ModelConfig | object | None) -> str | None:
+    """Extract API key from config (snake_case or camelCase)."""


This is too complicated. We shouldn't have fallbacks. We need a well defined contract.

huangjeff5 · 2026-03-11T16:37:45Z

py/packages/genkit/src/genkit/_ai/_prompt.py

+    ToolResponsePart,
+)
+
+ModelStreamingCallback = StreamingCallback


Don't need/want this alias

huangjeff5 · 2026-03-11T16:38:05Z

py/packages/genkit/src/genkit/_ai/_prompt.py

+OutputT = TypeVar('OutputT')
+
+
+class OutputOptions(TypedDict, total=False):


still used?

huangjeff5 · 2026-03-11T16:39:53Z

py/packages/genkit/src/genkit/_ai/_prompt.py

+    metadata: dict[str, Any] | None
+
+
+class ModelStreamResponse(Generic[OutputT]):


Double check if this class makes sense

huangjeff5 · 2026-03-11T16:40:15Z

py/packages/genkit/src/genkit/_ai/_prompt.py

+class PromptCache:
+    """Model for a prompt cache."""
+
+    user_prompt: PromptFunction[Any] | None = None


Better types

huangjeff5 · 2026-03-11T16:51:05Z

py/packages/genkit/src/genkit/_core/trace/_realtime_processor.py

-See Also:
-    - JavaScript RealtimeSpanProcessor: js/core/src/tracing/realtime-span-processor.ts
-"""
+"""Realtime span processor for live trace visualization."""


trace/ folder should be _trace/

huangjeff5 · 2026-03-11T16:53:34Z

py/packages/genkit/src/genkit/_core/_error.py

-    except Exception as e:
-        status_code = get_http_status(e)  # 404 for NOT_FOUND, 500 otherwise
-    ```
+# =============================================================================


remove this comment

huangjeff5 · 2026-03-11T16:54:40Z

py/packages/genkit/src/genkit/_core/_error.py


-from pydantic import BaseModel, ConfigDict
-from pydantic.alias_generators import to_camel
+class Status(BaseModel):


Does status belong in this file?

huangjeff5 · 2026-03-11T17:03:14Z

py/packages/genkit/src/genkit/_core/_extract.py

+# Copyright 2025 Google LLC
+#


file naming is a bit wierd

huangjeff5 · 2026-03-11T17:03:52Z

py/packages/genkit/src/genkit/_core/_extract.py

+    cursor: int
+
+
+def extract_items(text: str, cursor: int = 0) -> ExtractItemsResult:


beter naming? extract_json_array_from_text?

huangjeff5 · 2026-03-11T17:05:00Z

py/packages/genkit/src/genkit/_ai/_aio.py

+T = TypeVar('T')
+
+
+class _FlowDecorator:


does flow decorator belong here?

Is there the equivalent decorator for tools? Other primitives?

Decorators should probably live together.

huangjeff5 · 2026-03-11T17:11:24Z

py/packages/genkit/src/genkit/_core/_http_client.py

+_cache_lock = threading.Lock()
+
+
+def get_cached_client(


This seems to be solving the same fundamental problem as _loop_cache.py. See if we can unify.

huangjeff5 · 2026-03-11T17:14:01Z

py/packages/genkit/src/genkit/_core/_model.py

+                aggregated=chunk.aggregated,
+            )
+        else:
+            # Direct construction mode: role=..., content=... kwargs


Not understanding why this else block is "direct construction mode"
the conditional is "if chunk is not None"

huangjeff5 · 2026-03-11T17:15:43Z

py/packages/genkit/src/genkit/_core/_registry.py

        return await self.resolve_action(kind, name)

-    async def list_actions(self, allowed_kinds: list[ActionKind] | None = None) -> list[ActionMetadata]:
+    async def list_actions(self, allowed_kinds: list[str] | None = None) -> list[ActionMetadata]:


should still be ActionKind

huangjeff5 · 2026-03-11T17:18:36Z

py/packages/genkit/src/genkit/_core/_typing.py

    tool_choice: ToolChoice | None = Field(default=None)
-    output: OutputModel | None = None
-    docs: Docs | None = None
+    output: OutputConfig | None = None


If we extend this wire format we will expose output which is wrong

huangjeff5 · 2026-03-11T17:20:23Z

py/packages/genkit/src/genkit/__init__.py

+    ModelRequest,
+    ModelResponse,
+    ModelResponseChunk,
+    OutputConfig,


huangjeff5 · 2026-03-11T17:20:35Z

py/packages/genkit/src/genkit/__init__.py

    Media,
    MediaPart,
-    Message,
+    Metadata,


what's this one?

huangjeff5 · 2026-03-11T17:21:12Z

py/packages/genkit/src/genkit/__init__.py

+
+# Import embedder-related types from the embedder namespace
+from genkit.embedder import (
+    EmbedderOptions,


Is this the same as ModelConfig? EmbedderConfig?

huangjeff5 · 2026-03-11T17:22:02Z

py/packages/genkit/src/genkit/__init__.py

+    'Metadata',
+    'ReasoningPart',
+    'FinishReason',
+    'GenerationUsage',


Should this be ModelUsage maybe?

huangjeff5 · 2026-03-11T17:22:30Z

py/packages/genkit/tests/genkit/ai/formats/enum_test.py

@@ -21,41 +21,39 @@ def test_parses_simple_enum_value(self) -> None:
        enum_fmt = EnumFormat()
        fmt = enum_fmt.handle({'type': 'string', 'enum': ['VALUE1', 'VALUE2']})

-        result = fmt.parse_message(MessageWrapper(Message(role='model', content=[Part(root=TextPart(text='VALUE1'))])))
+        result = fmt.parse_message(Message(Message(role='model', content=[Part(root=TextPart(text='VALUE1'))])))


why is this double wrapped?

huangjeff5 · 2026-03-11T17:22:50Z

py/packages/genkit/tests/genkit/ai/formats/enum_test.py

-        chunk1 = GenerateResponseChunk(content=[Part(root=TextPart(text='"f'))])
-        chunk2 = GenerateResponseChunk(content=[Part(root=TextPart(text='oo"'))])
+        chunk1 = ModelResponseChunk(content=[Part(root=TextPart(text='"f'))])
+        chunk2 = ModelResponseChunk(content=[Part(root=TextPart(text='oo"'))])


stop using root=

huangjeff5 · 2026-03-11T17:23:01Z

py/packages/genkit/tests/genkit/ai/formats/json_test.py

@@ -18,8 +18,8 @@ def test_parses_complete_json_object(self) -> None:
        json_fmt = JsonFormat()
        fmt = json_fmt.handle({'type': 'object'})

-        chunk = GenerateResponseChunk(content=[Part(root=TextPart(text='{"id": 1, "name": "test"}'))])
-        result = fmt.parse_chunk(GenerateResponseChunkWrapper(chunk, index=0, previous_chunks=[]))
+        chunk = ModelResponseChunk(content=[Part(root=TextPart(text='{"id": 1, "name": "test"}'))])


stop using root= everywhere

huangjeff5 · 2026-03-11T17:23:38Z

py/packages/genkit/tests/genkit/ai/formats/jsonl_test.py

@@ -92,7 +90,7 @@ def test_handles_empty_response(self) -> None:
        jsonl_fmt = JsonlFormat()
        fmt = jsonl_fmt.handle({'type': 'array', 'items': {'type': 'object'}})

-        result = fmt.parse_message(MessageWrapper(Message(role='model', content=[Part(root=TextPart(text=''))])))
+        result = fmt.parse_message(Message(Message(role='model', content=[Part(root=TextPart(text=''))])))


why double message wrapper

huangjeff5 · 2026-03-11T17:25:10Z

py/packages/genkit/tests/genkit/ai/generate_test.py

@@ -112,7 +122,7 @@ async def test_simulates_doc_grounding(
                    content=[Part(root=TextPart(text='hi'))],
                ),
            ],
-            docs=[DocumentData(content=[DocumentPart(root=TextPart(text='doc content 1'))])],
+            docs=[Document(content=[DocumentPart(root=TextPart(text='doc content 1'))])],


don't use root=

huangjeff5 · 2026-03-11T17:26:19Z

py/packages/genkit/tests/genkit/ai/generate_test.py

        want = clean_schema(spec['expectResponse'])
        if got != want:
            raise AssertionError(
-                f'{dump_json(got, indent=2)}\n\nis not equal to expected:\n\n{dump_json(want, indent=2)}'
+                f'{_to_json(got, indent=2)}\n\nis not equal to expected:\n\n{_to_json(want, indent=2)}'


what is _to_json?

huangjeff5 · 2026-03-11T17:27:02Z

py/packages/genkit/tests/genkit/ai/genkit_api_test.py


-    res4 = await ai.run('multiply', 10, multiply)
-    assert res4 == 20
+    with pytest.raises(TypeError, match='fn must be a coroutine function'):


coroutine function = async function?

huangjeff5 · 2026-03-11T17:32:03Z

py/plugins/amazon-bedrock/src/genkit/plugins/amazon_bedrock/models/model.py

+    StreamingFenceStripper,
+    maybe_strip_fences,
+)
+from genkit.plugins.amazon_bedrock.typing import BedrockConfig


Double check this all actually makes sense... so many new concepts. also why is there a typing file

huangjeff5 · 2026-03-11T17:32:37Z

py/plugins/amazon-bedrock/src/genkit/plugins/amazon_bedrock/plugin.py

-from genkit.core.action import Action, ActionMetadata
-from genkit.core.logging import get_logger
-from genkit.core.registry import ActionKind
+from genkit import Embedding, EmbedRequest, EmbedResponse


import from embedder

huangjeff5 · 2026-03-11T17:33:16Z

py/plugins/amazon-bedrock/src/genkit/plugins/amazon_bedrock/typing.py

@@ -168,12 +168,12 @@ class CohereToolChoice(StrEnum):
 class GenkitCommonConfigMixin(BaseModel):
    """Genkit common configuration parameters mixin.

-    These parameters match the Genkit core GenerationCommonConfigSchema and are


?? It's duplicating core framework stuff

chore(py): re-organize file structure, api signatures, types

203a940

github-project-automation bot added this to Genkit Backlog Mar 3, 2026

github-actions bot added docs Improvements or additions to documentation python Python labels Mar 3, 2026

gemini-code-assist bot reviewed Mar 3, 2026

View reviewed changes

py/packages/genkit/src/genkit/ai/_aio.py Outdated Show resolved Hide resolved

Clean up init

e488bc4