gemini

package
v0.15.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package gemini is core-models' Gemini adapter: the Gemini Developer API (API key) and Gemini on Vertex AI (Application Default Credentials), over genai, as llm.LLM.

It is the extraction both products' copies were waiting on (docs/design.md §7.3, phase L5). The shape is mast's — an option struct, no registry, the usage.Detail sidecar — and the behaviour merges both:

  • from mast: built-ins off unless asked for (#324, #340); the one eviction verdict both the wrapper and the cache manager ask (#325, vertexcache.Gone); skipping built-ins on a pre-3.0 model carrying function tools;
  • from core-agent: IncludeServerSideToolInvocations set from the backend rather than by the caller, so the Developer API path can no longer forget it (mast #505); per-request opt-outs through callctx; the retry on a bare 400 after the session was served (#898, #1247); the below-minimum cache verdict (#1067);
  • from neither: a genai-native base model in place of ADK's model/gemini, which the core module cannot import (model.go).

Retries happen at the HTTP layer through package retry, like every core-models dialect: 408, 429 and 5xx, honoring Retry-After, plus the bare-400 rule as Policy.AfterSuccess. That replaces core-agent's model-level 429/503 predicate; a product's own outer policy, if it keeps one, now sees only what this layer gave up on.

Index

Constants

View Source
const (
	WebSearch     = "web_search"
	URLContext    = "url_context"
	CodeExecution = "code_execution"
)

Built-in names shared across providers, so a product's config reads the same whichever vendor it resolves to.

View Source
const AuthorGoogleSearch = "gemini/google_search"

AuthorGoogleSearch is the author both products give the synthetic session events that surface Google Search evidence. Stable, so event log consumers can filter on it.

Variables

View Source
var ErrEmptyResponse = fmt.Errorf(
	"gemini: model returned no usable content with no finish reason and no error — likely a silent safety filter, streaming truncation, or transient Vertex fault; retrying often succeeds (%w)",
	llm.ErrEmptyResponse)

ErrEmptyResponse is returned when the model answered with no usable content, no finish reason other than STOP and no error, twice in a row — the silent turn mast #220 was filed for. It wraps llm.ErrEmptyResponse.

Functions

func GroundingEvidence

func GroundingEvidence(gm *genai.GroundingMetadata) []string

GroundingEvidence renders what Google Search grounding did as lines for an audit trail: one "query: …" per search the model issued, then one per grounded web source ("Title — URI", or the URI alone). Duplicates are dropped — Vertex repeats a query or source across search rounds — and a source with no URI, which names nothing anyone can follow, is skipped. Nil when there is no evidence, the common case.

This is the ADK-free half of the grounding projection. The other half, adkv2.GroundingProjection, wraps an ADK session.Service and appends one event per line under AuthorGoogleSearch; it lives in the adapter module because session events are ADK's.

func IsBareInvalidArgument

func IsBareInvalidArgument(err error) bool

IsBareInvalidArgument is IsBareInvalidArgumentBody for an error that has already become a genai.APIError, for a product policy above the adapter that judges errors rather than responses.

func IsBareInvalidArgumentBody

func IsBareInvalidArgumentBody(status int, body []byte) bool

IsBareInvalidArgumentBody reports whether an HTTP response is Vertex's 400 INVALID_ARGUMENT that names nothing — the generic message and no details. It is the retry.Policy.AfterSuccess New installs: twice now it arrived on a session whose previous call under the same config had succeeded, and the session worked afterwards. On its own it is indistinguishable from a request malformed from the start, which is why the transport consults it only for a session that has been served (callctx.PriorCallSucceeded), and only once.

All three must hold, each a narrowing: status 400 with INVALID_ARGUMENT; no details, since a 400 with field violations has said what is wrong; the generic message exactly, since one naming a parameter is saying what is wrong too, and an expired cache ("Cache content <id> is expired.") is vertexcache.Gone's. Google sends the error object bare or, on some Vertex paths, inside a one-element array; both are read.

func IsTransient

func IsTransient(err error) bool

IsTransient reports whether err is Gemini declining to serve this request right now — 429 RESOURCE_EXHAUSTED or 503 UNAVAILABLE — as opposed to declining it at all. The adapter does not need it: package retry already retries those at the HTTP layer, with Retry-After visible. It is exported for a product's own model-level policy, which sees what the transport gave up on (core-agent's RetryPolicy).

The typed genai.APIError check is exact and tried first; a typed error that is neither code is a definite no. The text fallback pairs the code with its status word, so a 429 in the model's own prose or a pod named "unavailable" cannot match.

Types

type BuiltinTools

type BuiltinTools struct {
	GoogleSearch  bool // web search grounding
	URLContext    bool // fetch and ground on URLs the model picks
	CodeExecution bool // sandboxed Python on Google's servers
}

BuiltinTools toggles Gemini's server-side tools. Each enabled flag becomes its own genai.Tool appended to a request's tools, alongside its function declarations.

Other genai built-ins (FileSearch, GoogleMaps, ComputerUse, EnterpriseWebSearch, Retrieval) are not surfaced: they need an upstream resource configured first, so turning one on without it yields an API error rather than a tool.

func BuiltinToolsFromNames

func BuiltinToolsFromNames(names []string) (BuiltinTools, error)

BuiltinToolsFromNames maps provider-neutral names onto the toggles. An unknown name is an error, not a silently absent tool.

func (BuiltinTools) Names

func (b BuiltinTools) Names() []string

Names reports the enabled built-ins under the neutral names, in a fixed order.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a configured Gemini endpoint. Model returns an llm.LLM for one model id on it. Safe for concurrent use.

func New

func New(ctx context.Context, opts Options) (*Client, error)

New builds a Client. On Vertex AI with no Credential it detects Application Default Credentials, and fails if there are none.

func (*Client) Caches

func (c *Client) Caches() *genai.Caches

Caches returns the genai caches service on the Client's endpoint and credentials, for building a vertexcache.Manager without a second client configuration.

func (*Client) Model

func (c *Client) Model(id string) llm.LLM

Model returns the model id as an llm.LLM carrying the Client's behaviour (see wrap.go).

func (*Client) SetContextCache added in v0.8.0

func (c *Client) SetContextCache(cc ContextCache) error

SetContextCache installs context-cache hooks on the Client, replacing any set before, and they apply from each model's next call, including models built before this call. It is how a host builds one Client, creates a vertexcache.Manager from Caches(), and then hooks the manager in, without a second Client (core-models #31). The zero ContextCache removes the hooks. Ignored on the Developer API, like the Options fields.

type ContextCache added in v0.8.0

type ContextCache struct {
	Model      string
	Init       ContextCacheInitFn
	Name       ContextCacheNameFn
	Invalidate ContextCacheInvalidateFn
}

ContextCache is a set of Vertex context-cache hooks, the same four the Options fields carry, for installing on a Client after it is built (SetContextCache). Model is required when any hook is set.

type ContextCacheInitFn

type ContextCacheInitFn func(ctx context.Context, systemInstruction *genai.Content, tools []*genai.Tool)

ContextCacheInitFn is called with the fully assembled system instruction and tools of a request about to run uncached, so the cache can be seeded from exactly what the model is sent. It must not block; vertexcache.Manager.Init creates the cache in the background.

type ContextCacheInvalidateFn

type ContextCacheInvalidateFn func(name, reason string)

ContextCacheInvalidateFn is told that Vertex rejected the stamped cache reference name because the cache is gone (vertexcache.Gone), so later calls run uncached until a fresh cache exists. It should forget name only if name is still current — vertexcache.Manager's MarkEvictedName does exactly that. The reason quotes the error.

type ContextCacheNameFn

type ContextCacheNameFn func(ctx context.Context) string

ContextCacheNameFn returns the cache to stamp on a request, or "" to run it uncached — always safe.

type Options

type Options struct {
	// Backend is genai.BackendGeminiAPI or genai.BackendVertexAI.
	Backend genai.Backend

	// APIKey authenticates the Gemini Developer API. On Vertex AI it
	// selects express mode: the key alone, with no Project, Location or
	// Credential (Google routes the key to its project).
	APIKey string

	// Project and Location address Vertex AI. "global" is a valid
	// location for current Gemini models.
	Project  string
	Location string
	// Credential authenticates Vertex AI requests as a bearer token. Nil
	// means Application Default Credentials, detected here.
	Credential *auth.Credential

	// BaseURL overrides the service endpoint, for a proxy, a private
	// endpoint or a test server. Empty means Google's.
	BaseURL string

	// HTTPClient supplies the base transport, for tracing or a proxy;
	// the retry and auth layers wrap it. Nil means
	// http.DefaultTransport. coremodels.Open puts a profile's headers in
	// it (profile.Resolved.HeaderTransport); a host building the Client
	// itself, to share it with a context cache, does the same.
	HTTPClient *http.Client
	// Retry is the HTTP-layer retry policy. Nil means retry.Default().
	// Either way, a nil AfterSuccess gets the bare-400 rule
	// (IsBareInvalidArgumentBody); to turn it off, supply an
	// AfterSuccess that returns false.
	Retry *retry.Policy

	// BackendName labels usage.Detail.Backend, the key products price
	// by. Empty means "gemini" for the Developer API and "vertex" for
	// Vertex AI, matching mast's and core-agent's pricing catalogs.
	BackendName string

	// BuiltinTools turns on Gemini's server-side tools. The zero value
	// is none, which is what both products start from: an unattended
	// workload's internet reachability should not depend on which
	// vendor it resolved to (mast #324).
	BuiltinTools BuiltinTools

	// ContextCacheModel, ContextCacheInit, ContextCacheName and
	// ContextCacheInvalidate wire Vertex explicit context caching — see
	// vertexcache.Manager, whose Model, Init, Name and MarkEvictedName
	// they usually are. A cache serves the one model it was created
	// for, so the hooks apply only to requests for ContextCacheModel,
	// which is required when any hook is set. They are skipped, too,
	// for a side call, a request that opted out of built-ins or prompt
	// caching, and one carrying a tool config (see cacheable). Ignored
	// on the Developer API, which rejects the cache reference on some
	// model families.
	ContextCacheModel      string
	ContextCacheInit       ContextCacheInitFn
	ContextCacheName       ContextCacheNameFn
	ContextCacheInvalidate ContextCacheInvalidateFn

	// Logf receives the adapter's operator-facing notices: an empty
	// response retried, a cache found evicted, built-ins skipped for an
	// old model. Nil discards them.
	Logf func(format string, args ...any)
}

Options configures a Client. Backend picks the service; the fields after it apply to one backend or the other.

Directories

Path Synopsis
Package vertexcache owns the lifecycle of a single Vertex explicit context cache — Create at agent startup, Refresh on TTL pressure, Delete on session unregister.
Package vertexcache owns the lifecycle of a single Vertex explicit context cache — Create at agent startup, Refresh on TTL pressure, Delete on session unregister.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL