RFC: [Go] V2

[apascal07]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello @apascal07, 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 the Genkit Go v2 API, representing a significant overhaul focused on improving idiomatic Go usage, simplifying type structures, and enhancing overall API consistency and type safety. Key changes include transitioning to channels for streaming, replacing custom contexts with standard Go contexts and helpers, and moving from interfaces to concrete types for core components. The update also standardizes function signatures and streamlines output and format handling, aiming to provide a more robust and developer-friendly experience.

Highlights

• Streaming API Transition: Migrated streaming functions from callbacks to Go channels for more idiomatic usage and improved data flow.
• Context Simplification: Replaced the custom ToolContext with the standard context.Context augmented by dedicated helper functions for handling interrupt and resume data.
• API Registry Sealing: Sealed the api.Registry interface with an unexported method to prevent external implementations, ensuring API stability and allowing for future method additions without breaking changes.
• Interface to Concrete Type Conversion: Replaced numerous interfaces (e.g., Model, Tool, Embedder) with concrete structs, simplifying type usage and eliminating the need for companion *Ref and *Arg types.
• Unified Reference Handling: Introduced the Named interface and ActionRef struct to provide a unified mechanism for lazy references, replacing disparate ModelRef, EmbedderRef, and RetrieverRef types.
• Standardized Function Signatures: Standardized the argument order for all Define* and New* functions to name, fn, opts, improving consistency and readability across the API.
• Enhanced Type Safety: Implemented a strongly typed interrupt API and ensured GenerateData returns values instead of pointers, significantly reducing potential nil pointer dereference issues.
• Streamlined Output Handling: Removed WithOutputType and WithOutputSchema options, centralizing structured output handling through GenerateData[Out] and DataPrompt[In, Out].
• Consolidated Format Handlers: Merged FormatHandler and StreamingFormatHandler into a single, unified FormatHandler interface, simplifying the implementation of custom formatters.
• Consistent Telemetry Reporting: Ensured that Action.RunJSON always returns telemetry data by removing the variant that previously discarded it, providing consistent operational insights.

🧠 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

• docs/go-v2.md
  • Added comprehensive documentation detailing the Genkit Go v2 API changes, including new API surfaces, motivations for changes, and lists of removed and new types.

Activity

• No human activity has been recorded on this pull request yet.

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 RFC document for Genkit Go v2 presents a well-thought-out set of API changes that improve consistency, simplicity, and idiomatic Go usage. The move to concrete types, channel-based streaming, and unified reference types are all excellent improvements. I've added a few comments to point out some minor inconsistencies in the documentation to ensure the final API is as clear and robust as possible.

[gemini-code-assist]

The comment for ToolNamed says it "returns a ToolArg", which is a bit confusing since ToolNamed is a type, not a function. To improve clarity, I suggest rephrasing it to describe what the type represents.

Suggested change

	// ToolNamed returns a ToolArg that matches registered tools by exact name
	// ToolNamed is a ToolArg that matches registered tools by exact name

[gemini-code-assist]

The function WithResumedMetadata is marked as // unchanged, but its signature appears to have changed from func WithResumedMetadata[In any](meta map[string]any) RestartWithOption[In] in v1 to func WithResumedMetadata[In any](meta any) RestartWithOption[In] here.

Additionally, the motivation section states "Resume metadata is always strongly typed — no map[string]any", but this function still accepts meta any. This seems to contradict the goal of strong typing for resume metadata.

To align with the design goal of strong typing, perhaps this function should be generic over the metadata type as well, similar to how RestartOptions is now RestartOptions[In, Meta any]. For example: func WithResumedMetadata[In any, Meta any](meta Meta) RestartWithOption[In].

[gemini-code-assist]

The table indicates that RunRawMultipart is consolidated into RunRaw, and that RunRaw now "always returns *MultipartToolResponse". However, the Tool API surface defined earlier shows RunRaw's signature as func (t *Tool[In, Out]) RunRaw(ctx context.Context, input any) (any, error). This seems to be a contradiction. Please clarify the new behavior of RunRaw and update the documentation accordingly.