Skip to content

chore(py): Clean up Python engdocs and samples folders#4908

Draft
huangjeff5 wants to merge 32 commits intomainfrom
samples-cleanup
Draft

chore(py): Clean up Python engdocs and samples folders#4908
huangjeff5 wants to merge 32 commits intomainfrom
samples-cleanup

Conversation

@huangjeff5
Copy link
Contributor

No description provided.

@huangjeff5 huangjeff5 changed the base branch from main to jh-redesign March 12, 2026 19:24
@github-actions github-actions bot added docs Improvements or additions to documentation python Python config labels Mar 12, 2026
@gemini-code-assist
Copy link
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! 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 represents a major internal architectural refactoring of the Genkit Python SDK. The primary goal was to enhance the clarity, maintainability, and type safety of the codebase by reorganizing modules, introducing a consistent base model for data structures, and streamlining the public API. These changes lay a stronger foundation for future development and improve the overall developer experience.

Highlights

  • Core Module Restructuring: The Python SDK underwent a significant internal reorganization, moving core functionalities from genkit.ai and genkit.blocks into new internal genkit._ai and genkit._core modules. This includes renaming numerous files and consolidating related logic.
  • New Base Model for Consistency: A new GenkitModel base class was introduced in genkit._core._base.py for all Pydantic models, ensuring consistent serialization behavior (camelCase, exclude_none) across the SDK.
  • Simplified Public API: The top-level genkit/__init__.py was refactored to expose key functionalities directly, simplifying imports for users (e.g., from genkit import Genkit instead of from genkit.ai import Genkit).
  • Enhanced Type Safety and Clarity: Changes in sanitize_schema_typing.py introduced EXCLUDED_CLASSES for veneer types and renamed Message to MessageData, clarifying the distinction between internal wire types and public API types. Flow decorators were also refined for better type inference.
  • Documentation Overhaul: Several documentation files were removed (py/CHANGELOG.md, py/docs/dev_ui_eventloop_model.md, py/docs/python_docs_roadmap.md) and existing ones (py/README.md, py/engdoc/) were updated to reflect the new module structure and simplify user guidance.
  • Improved Internal Utilities: New internal modules were added for async streaming channels, environment detection, dynamic action providers, enhanced error handling (PublicError replacing UserFacingError), JSON extraction, HTTP client caching, and comprehensive tracing utilities.

🧠 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/CHANGELOG.md
    • Removed the changelog file.
  • py/README.md
    • Simplified the README content, focusing on installation, quick start, and flows, removing detailed architectural and plugin information.
  • py/bin/check_consistency
    • Removed checks for py.typed markers in plugin directories.
  • py/bin/generate_schema_typing
    • Updated the target path for generated typing files to genkit/_core/_typing.py.
  • py/bin/sanitize_schema_typing.py
    • Introduced EXCLUDED_CLASSES for types with hand-written veneers, renamed Message to MessageData, and updated base class checks from BaseModel to GenkitModel.
  • py/docs/dev_ui_eventloop_model.md
    • Removed the Dev UI event loop model documentation.
  • py/docs/index.md
    • Updated module references from genkit.ai to genkit._ai and genkit.Flow.
  • py/docs/python_docs_roadmap.md
    • Removed the Python documentation roadmap.
  • py/docs/types.md
    • Updated module references from genkit.core.typing to genkit._core.typing and genkit._core._model.
  • py/engdoc/compute-engine.mdx
    • Updated sample reference from provider-google-genai-hello to context and simplified setup instructions.
  • py/engdoc/extending/api.md
    • Updated Genkit import statement.
  • py/engdoc/extending/index.md
    • Updated module references and removed amazon-bedrock and microsoft-foundry from plugin lists.
  • py/engdoc/extending/servers.md
    • Simplified signal handling documentation.
  • py/engdoc/index.md
    • Updated Genkit import statements and changed output=Output(schema=CharacterProfile) to output_schema=CharacterProfile.
  • py/engdoc/user_guide/python/getting_started.md
    • Updated module reference for ActionKind.
  • py/packages/genkit/README.md
    • Simplified quick start example to use output_schema directly and streamlined Genkit import.
  • py/packages/genkit/pyproject.toml
    • Removed genkit-plugin-dev-local-vectorstore from optional dependencies.
  • py/packages/genkit/src/genkit/init.py
    • Refactored imports to use new internal _ai and _core modules, exposing top-level types directly.
  • py/packages/genkit/src/genkit/_ai/init.py
    • Created and populated with new _ai module imports (renamed from py/samples/framework-restaurant-demo/src/case_01/__init__.py).
  • py/packages/genkit/src/genkit/_ai/_aio.py
    • Created, containing the main Genkit class and its asynchronous API methods.
  • py/packages/genkit/src/genkit/_ai/_decorators.py
    • Created, containing flow decorator classes for type-safe flow registration.
  • py/packages/genkit/src/genkit/_ai/_embedding.py
    • Created, containing embedding types and utilities.
  • py/packages/genkit/src/genkit/_ai/_evaluator.py
    • Created, containing evaluator type definitions.
  • py/packages/genkit/src/genkit/_ai/_formats/init.py
    • Created, containing built-in format definitions.
  • py/packages/genkit/src/genkit/_ai/_formats/_array.py
    • Renamed from py/packages/genkit/src/genkit/blocks/formats/array.py, updated imports and JSON extraction logic.
  • py/packages/genkit/src/genkit/_ai/_formats/_enum.py
    • Renamed from py/packages/genkit/src/genkit/blocks/formats/enum.py, updated imports.
  • py/packages/genkit/src/genkit/_ai/_formats/_json.py
    • Renamed from py/packages/genkit/src/genkit/blocks/formats/json.py, updated imports.
  • py/packages/genkit/src/genkit/_ai/_formats/_jsonl.py
    • Renamed from py/packages/genkit/src/genkit/blocks/formats/jsonl.py, updated imports.
  • py/packages/genkit/src/genkit/_ai/_formats/_text.py
    • Renamed from py/packages/genkit/src/genkit/blocks/formats/text.py, updated imports.
  • py/packages/genkit/src/genkit/_ai/_formats/_types.py
    • Renamed from py/packages/genkit/src/genkit/blocks/formats/types.py, updated imports.
  • py/packages/genkit/src/genkit/_ai/_generate.py
    • Renamed from py/packages/genkit/src/genkit/blocks/generate.py, updated imports, streaming callbacks, and request/response handling.
  • py/packages/genkit/src/genkit/_ai/_messages.py
    • Renamed from py/packages/genkit/src/genkit/blocks/messages.py, updated imports and docstrings.
  • py/packages/genkit/src/genkit/_ai/_middleware.py
    • Renamed from py/packages/genkit/src/genkit/blocks/middleware.py, updated imports and docstrings.
  • py/packages/genkit/src/genkit/_ai/_model.py
    • Created, containing model veneer types and utilities.
  • py/packages/genkit/src/genkit/_ai/_prompt.py
    • Created, containing prompt management and templating.
  • py/packages/genkit/src/genkit/_ai/_resource.py
    • Renamed from py/packages/genkit/src/genkit/blocks/resource.py, updated imports and docstrings.
  • py/packages/genkit/src/genkit/_ai/_runtime.py
    • Renamed from py/packages/genkit/src/genkit/ai/_runtime.py, updated imports.
  • py/packages/genkit/src/genkit/_ai/_testing.py
    • Created, containing internal testing utilities.
  • py/packages/genkit/src/genkit/_ai/_tools.py
    • Created, containing tool-specific types and utilities.
  • py/packages/genkit/src/genkit/_core/init.py
    • Created and populated with new _core module imports (renamed from py/samples/framework-restaurant-demo/src/case_02/__init__.py).
  • py/packages/genkit/src/genkit/_core/_action.py
    • Created, containing action module for defining and managing remotely callable functions.
  • py/packages/genkit/src/genkit/_core/_background.py
    • Renamed from py/packages/genkit/src/genkit/blocks/background_model.py, updated imports and docstrings.
  • py/packages/genkit/src/genkit/_core/_base.py
    • Created, containing a new GenkitModel base class for consistent serialization.
  • py/packages/genkit/src/genkit/_core/_channel.py
    • Created, containing async streaming channel utilities.
  • py/packages/genkit/src/genkit/_core/_compat.py
    • Renamed from py/packages/genkit/src/genkit/aio/_compat.py, updated imports.
  • py/packages/genkit/src/genkit/_core/_constants.py
    • Renamed from py/packages/genkit/src/genkit/core/constants.py, updated Genkit version.
  • py/packages/genkit/src/genkit/_core/_context.py
    • Renamed from py/packages/genkit/src/genkit/core/context.py, updated error class reference.
  • py/packages/genkit/src/genkit/_core/_dap.py
    • Created, containing Dynamic Action Provider support.
  • py/packages/genkit/src/genkit/_core/_environment.py
    • Created, containing environment detection.
  • py/packages/genkit/src/genkit/_core/_error.py
    • Renamed from py/packages/genkit/src/genkit/core/error.py, updated error classes and status code mapping.
  • py/packages/genkit/src/genkit/_core/_extract_json.py
    • Created, containing JSON extraction utilities.
  • py/packages/genkit/src/genkit/_core/_flow.py
    • Created, containing flow registration.
  • py/packages/genkit/src/genkit/_core/_http_client.py
    • Created, containing shared HTTP client utilities.
  • py/packages/genkit/src/genkit/_core/_logger.py
    • Created, containing internal logger.
  • py/packages/genkit/src/genkit/_core/_loop_cache.py
    • Renamed from py/packages/genkit/src/genkit/core/_loop_local.py, updated docstring.
  • py/packages/genkit/src/genkit/_core/_model.py
    • Created, containing model veneer types.
  • py/packages/genkit/src/genkit/_core/_plugin.py
    • Created, containing abstract base class for plugins.
  • py/packages/genkit/src/genkit/_core/_reflection.py
    • Created, containing reflection API server.
  • py/packages/genkit/src/genkit/_core/_registry.py
    • Renamed from py/packages/genkit/src/genkit/core/registry.py, updated imports and method signatures.
  • py/packages/genkit/src/genkit/_core/_schema.py
    • Renamed from py/plugins/dev-local-vectorstore/src/genkit/plugins/dev_local_vectorstore/constant.py, updated to provide JSON schema conversion.
  • py/packages/genkit/src/genkit/_core/_trace/_adjusting_exporter.py
    • Created, containing adjusting trace exporter for PII redaction and span enhancement.
  • py/packages/genkit/src/genkit/_core/_trace/_default_exporter.py
    • Created, containing telemetry and tracing default exporter.
  • py/packages/genkit/src/genkit/_core/_trace/_path.py
    • Created, containing path utilities for Genkit trace paths.
  • py/packages/genkit/src/genkit/_core/_trace/_realtime_processor.py
    • Created, containing realtime span processor for live trace visualization.
  • py/packages/genkit/src/genkit/_core/_tracing.py
    • Renamed from py/packages/genkit/src/genkit/core/tracing.py, updated imports and span handling.
  • py/packages/genkit/src/genkit/_core/_typing.py
    • Renamed from py/packages/genkit/src/genkit/core/typing.py, updated base classes to GenkitModel and added warnings filter.
  • py/packages/genkit/src/genkit/plugins/init.py
    • Renamed from py/samples/framework-restaurant-demo/src/__init__.py.
  • py/packages/genkit/tests/genkit/ai/dap_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/dap_test.py.
  • py/packages/genkit/tests/genkit/ai/document_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/document_test.py.
  • py/packages/genkit/tests/genkit/ai/embedding_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/embedding_test.py.
  • py/packages/genkit/tests/genkit/ai/formats/array_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/formats/array_test.py.
  • py/packages/genkit/tests/genkit/ai/formats/enum_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/formats/enum_test.py.
  • py/packages/genkit/tests/genkit/ai/formats/formats_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/formats/formats_test.py.
  • py/packages/genkit/tests/genkit/ai/formats/json_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/formats/json_test.py.
  • py/packages/genkit/tests/genkit/ai/formats/jsonl_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/formats/jsonl_test.py.
  • py/packages/genkit/tests/genkit/ai/formats/text_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/formats/text_test.py.
  • py/packages/genkit/tests/genkit/ai/generate_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/generate_test.py.
  • py/packages/genkit/tests/genkit/ai/message_utils_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/message_utils_test.py.
  • py/packages/genkit/tests/genkit/ai/middleware_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/middleware_test.py.
  • py/packages/genkit/tests/genkit/ai/prompt_test.py
    • Renamed from py/packages/genkit/tests/genkit/blocks/prompt_test.py.
  • py/packages/genkit/tests/genkit/core/channel_test.py
    • Renamed from py/packages/genkit/tests/genkit/aio/channel_test.py.
  • py/plugins/google-genai/src/genkit/plugins/google_genai/models/_deprecations.py
    • Renamed from py/packages/genkit/src/genkit/lang/deprecations.py.
Ignored Files
  • Ignored by pattern: .github/workflows/** (1)
    • .github/workflows/python-samples.yml
Activity
  • The pull request author, huangjeff5, initiated a substantial refactoring effort.
  • The changes involved extensive file renames, removals, and new file creations, indicating a deep restructuring of the Python SDK's internal architecture.
  • Documentation was updated and streamlined to align with the new code organization and simplify user understanding.
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.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a major and much-needed cleanup of the Python documentation and sample applications. The simplification of READMEs, reorganization of samples into feature-focused directories, and removal of boilerplate code like run.sh and _common.sh significantly improve the developer experience. The changes are consistent and well-executed. I've found one issue regarding missing imports in a newly added sample file, which should be a straightforward fix. Overall, this is an excellent refactoring that makes the project more maintainable and easier for newcomers to navigate.

from genkit import Genkit, Message
from genkit.plugins.google_genai import GeminiConfigSchema, GoogleAI

if 'GEMINI_API_KEY' not in os.environ:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The display_code_execution function uses CustomPart, TextPart, and PartConverter, but these are not imported in the file. This will cause a NameError when the function is called. Please add the required imports to make the helper function runnable.

Suggested change
if 'GEMINI_API_KEY' not in os.environ:
from genkit.plugins.google_genai import GeminiConfigSchema, GoogleAI
from genkit._core._typing import CustomPart, TextPart
from genkit.plugins.google_genai.models.utils import PartConverter

Base automatically changed from jh-redesign to main March 13, 2026 20:34
An error occurred while trying to automatically change base from jh-redesign to main March 13, 2026 20:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

config docs Improvements or additions to documentation python Python

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant