Undesirable API inconsistencies Google AI vs. Vertex AI

[fredsa]

Human authored Google AI and Vertex AI packages should use identical APIs for the same functionality.

Where the two APIs currently different, we should:

1. Agree on the preferred API
2. Apply changes to make the APIs consistent
   • Where possible, add a new API & deprecate the old API (to be deleted at a later date in a newer version)
   • If not possible, do consider a breaking changes in order to get both packages into a good state for the long-term, to the benefit of all future developers that be exposed to both

Context

Compare these two human-authored packages:

• Google AI: https://pkg.go.dev/github.com/google/generative-ai-go/genai
• Vertex AI: https://pkg.go.dev/cloud.google.com/go/vertexai/genai

EXEPCTED

• Google AI and Vertex AI packages share identical API signatures for the same functionality. This ensures developer can easily convert or migrate between the two offerings without unnecessary friction.
• Differences that exist in minor underlying API differences between auto-generated "Generative Language API"(generativelanguage.googleapis.com) and "Vertex AI API" (aiplatform.googleapis.com) implementations should not result unnecessary differences in the human-authored packages.

ACTUAL

Two package are different:

1. BlockReason vs. BlockedReason

   https://pkg.go.dev/github.com/google/generative-ai-go/genai

   type BlockReason
       func (v BlockReason) String() string
   type BlockedError
       func (e *BlockedError) Error() string
   

   https://pkg.go.dev/cloud.google.com/go/vertexai/genai

   type BlockedError
       func (e *BlockedError) Error() string
   type BlockedReason
       func (v BlockedReason) String() string
   

2. SetTopK inconsistent type: int32 vs. float32

   https://pkg.go.dev/github.com/google/generative-ai-go/genai

   func (c *GenerationConfig) SetTopK(x int32)
   

   https://pkg.go.dev/cloud.google.com/go/vertexai/genai

   func (c *GenerationConfig) SetTopK(x float32)
   

3. CitationSource vs. Citation, with field and field type differences

   type CitationSource struct {
       StartIndex *[int32](https://pkg.go.dev/builtin#int32)
       EndIndex *[int32](https://pkg.go.dev/builtin#int32)
       URI *[string](https://pkg.go.dev/builtin#string)
       License [string](https://pkg.go.dev/builtin#string)
   }
   

   type Citation struct {
       StartIndex [int32](https://pkg.go.dev/builtin#int32)
       EndIndex [int32](https://pkg.go.dev/builtin#int32)
       URI [string](https://pkg.go.dev/builtin#string)
       Title [string](https://pkg.go.dev/builtin#string)
       License [string](https://pkg.go.dev/builtin#string)
       PublicationDate [civil](https://pkg.go.dev/cloud.google.com/go/civil).[Date](https://pkg.go.dev/cloud.google.com/go/civil#Date)
   }
   

4. …

[eliben]

It seems like these come from the underlying RPC/GAPIC surfaces and we copy them with protoveneer. @jba we could configure protoveneer to modify the output to have consistency, since the underlying protos are unlikely to change at this point. We're still in version 0.x and these are all relatively minor, so we could just change them, perhaps also keeping an alias around for a release or two in deprecated mode. WDYT?

[jba]

Thanks for identifying these. I'll look at this tomorrow and see what I can do.

On Wed, Feb 21, 2024 at 3:56 PM Eli Bendersky @.***> wrote:

It seems like these come from the underlying RPC/GAPIC surfaces and we copy them with protoveneer. @jba https://github.com/jba we could configure protoveneer to modify the output to have consistency, since the underlying protos are unlikely to change at this point. We're still in version 0.x and these are all relatively minor, so we could just change them, perhaps also keeping an alias around for a release or two in deprecated mode. WDYT?

— Reply to this email directly, view it on GitHub https://github.com/google/generative-ai-go/issues/50#issuecomment-1957902674, or unsubscribe https://github.com/notifications/unsubscribe-auth/AENAOZNXLC65S53YED5SQU3YUZNOZAVCNFSM6AAAAABDTWB3KCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNJXHEYDENRXGQ . You are receiving this because you were mentioned.Message ID: @.***>

[jba]

1. Fixed by https://github.com/google/generative-ai-go/pull/53
2. Underlying inconsistency. Although logically this is an int, I'm hesitant to change the cloud client to use an int because I don't know if they interpret fractional values in some way. I asked for more details.
3. Underlying inconsistency. We could use the same name, but which one? And I'm not sure whether int or *int makes more sense for those fields.

On Wed, Feb 21, 2024 at 4:52 PM Jonathan Amsterdam @.***> wrote:

Thanks for identifying these. I'll look at this tomorrow and see what I can do.

On Wed, Feb 21, 2024 at 3:56 PM Eli Bendersky @.***> wrote:

It seems like these come from the underlying RPC/GAPIC surfaces and we copy them with protoveneer. @jba https://github.com/jba we could configure protoveneer to modify the output to have consistency, since the underlying protos are unlikely to change at this point. We're still in version 0.x and these are all relatively minor, so we could just change them, perhaps also keeping an alias around for a release or two in deprecated mode. WDYT?

— Reply to this email directly, view it on GitHub https://github.com/google/generative-ai-go/issues/50#issuecomment-1957902674, or unsubscribe https://github.com/notifications/unsubscribe-auth/AENAOZNXLC65S53YED5SQU3YUZNOZAVCNFSM6AAAAABDTWB3KCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNJXHEYDENRXGQ . You are receiving this because you were mentioned.Message ID: @.***>

[wjkoh]

Sorry for piggybacking on this thread. I was wondering what the difference is between generative-ai-go and vertexai. Are there any guidelines for when to use each one?

[eliben]

@wjkoh see https://ai.google.dev/gemini-api/docs/migrate-to-cloud