Documentation
¶
Overview ¶
Package gemini implements models.Provider for Gemini, on the Gemini Developer API ("gemini") and on Vertex AI ("vertex").
The adapter lives in core-models (dialect/gemini, docs/model-support-design.md): the genai-native model, the stream aggregation, built-in injection and its pre-3.0 skip, the IncludeServerSideToolInvocations flag set from the backend, the empty-response retry and the Vertex context-cache stamping with its eviction recovery. This package is core-agent's facade over it: it maps config.Config onto the library's options, keeps core-agent's defaults (built-ins web search and URL context on) and exported API, keeps core-agent's own transient retry and its process-wide budget (pkg/models.RetryPolicy) as the one retry layer, and adapts each model to ADK v2 through models.Adapt.
Index ¶
- Constants
- Variables
- func GroundingProjection(inner session.Service) session.Servicedeprecated
- func IsBareInvalidArgument(err error) bool
- func IsTransient(err error) bool
- type BuiltinTools
- type ContextCacheInitFn
- type ContextCacheInvalidateFn
- type ContextCacheNameFn
- type Option
- type Provider
- func (p *Provider) BuiltinToolNames() []string
- func (p *Provider) Caches(ctx context.Context) (*genai.Caches, error)
- func (p *Provider) DefaultSmallModel() string
- func (p *Provider) Model(ctx context.Context, modelID string) (adkmodel.LLM, error)
- func (p *Provider) Name() string
- func (p *Provider) SetContextCache(model string, init ContextCacheInitFn, name ContextCacheNameFn)
- func (p *Provider) SetContextCacheInvalidate(invalidate ContextCacheInvalidateFn)
Constants ¶
const AuthorGoogleSearch = cmgemini.AuthorGoogleSearch
AuthorGoogleSearch is the synthetic event Author the grounding projection uses for both "model issued a search query" and "model grounded on this web source" events. Stable across releases so eventlog consumers can filter on it.
const DefaultSmallModelID = "gemini-3.5-flash-lite"
DefaultSmallModelID is the Gemini cheap-tier model used by default for agentic subtasks when the operator hasn't pinned one with --agentic-small-model. Moves in lockstep with taskclass's gemini small tier (TestModelForTier_ConsistentWithSmallModelDefaulters).
Variables ¶
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)", models.ErrEmptyResponse)
ErrEmptyResponse is surfaced by the Gemini adapter when the model returns no usable content AND no explicit finish reason AND no error — the "silent hang" pattern #220 documents. The error text names the likely upstream causes so operators reading the daemon log get an actionable next step rather than a mystery.
Callers (typically the agent loop) may treat this as retryable — empty responses from Vertex are usually transient (safety filter race, streaming truncation, provisional-throughput mismatch). A second attempt often succeeds; a persistent pattern signals a deeper Vertex-side issue worth escalating.
It wraps models.ErrEmptyResponse so a caller can recognize "the model said nothing" without importing this adapter. One-shot callers need that: for /btw the empty answer IS the result, and rendering this sentence at an operator who asked a question would be the infra-error-instead-of-an-answer bug all over again.
Functions ¶
func GroundingProjection
deprecated
GroundingProjection wraps a session.Service so that every event carrying Gemini Google Search grounding is followed by synthetic events surfacing that evidence under AuthorGoogleSearch: one per web search query the model issued, then one per grounded web source (title + URI). They share the parent event's InvocationID and Branch and have an empty Content.Role, so ADK leaves them out of the conversation it sends the model.
Deprecated: the projection lives in core-models now; call adkv2.GroundingProjection (github.com/go-steer/core-models/adkv2) directly. This wrapper delegates to it and stays for embedders who wired the core-agent name. Removed in v4.0.
func IsBareInvalidArgument ¶
IsBareInvalidArgument reports whether err is Vertex's detail-less 400 INVALID_ARGUMENT. It is the library's classification.
func IsTransient ¶
IsTransient reports whether err is a Gemini rate limit or overload worth retrying. It is the library's classification.
Types ¶
type BuiltinTools ¶
type BuiltinTools struct {
GoogleSearch bool // Public web search grounding (default: on)
URLContext bool // Fetch + ground on URLs the model decides to visit (default: on)
CodeExecution bool // Sandboxed Python execution on Google's servers (default: off)
}
BuiltinTools toggles Gemini's server-side built-in tools surfaced by core-agent. Each enabled flag becomes its own *genai.Tool entry injected into the request's Config.Tools alongside any user-defined function declarations.
Defaults:
- GoogleSearch + URLContext are on (universally useful, no setup)
- CodeExecution is off (useful but a real action surface — opt in when you've decided sandboxed Python on Google's servers is acceptable for your security and cost posture)
To turn one off:
provider, _ := gemini.NewAPIKey(key, gemini.WithURLContext(false))
To turn CodeExecution on:
provider, _ := gemini.NewAPIKey(key, gemini.WithCodeExecution(true))
To replace the whole set:
provider, _ := gemini.NewAPIKey(key, gemini.WithBuiltinTools(gemini.BuiltinTools{
GoogleSearch: true, // URL context + CodeExecution off
}))
Other genai built-ins (FileSearch, GoogleMaps, ComputerUse, EnterpriseWebSearch, GoogleSearchRetrieval, Retrieval) aren't surfaced here. They require upstream setup (a corpus, a Maps API key, a hosted environment) or are Vertex-only — flipping them on without configuring the upstream resource yields an API error, not a working tool. Add them when an actual consumer needs them.
func DefaultBuiltinTools ¶
func DefaultBuiltinTools() BuiltinTools
DefaultBuiltinTools returns the on-by-default baseline applied to every Provider unless overridden via WithBuiltinTools or one of the per-tool helpers.
func (BuiltinTools) Names ¶
func (b BuiltinTools) Names() []string
Names reports the enabled built-ins under the provider-neutral names the config block uses (see config.BuiltinToolsConfig), so the startup summary reads the same whichever provider is resolved and an operator can match the line against the keys they typed.
type ContextCacheInitFn ¶
type ContextCacheInitFn = cmgemini.ContextCacheInitFn
ContextCacheInitFn is called on the first GenerateContent request with the fully-assembled system instruction + tools ADK is about to send. Implementations typically snapshot these into a Vertex explicit-cache Create call (async — must not block the request).
type ContextCacheInvalidateFn ¶
type ContextCacheInvalidateFn = cmgemini.ContextCacheInvalidateFn
ContextCacheInvalidateFn is called when a GenerateContent response carries a NOT_FOUND for the stamped cache reference — the signal that Vertex has reaped our cache server-side (TTL elapsed while the daemon held a valid-looking Manager handle). Implementations flip their manager back to a pre-Init state so:
- The follow-up retry (issued by GenerateContent itself) runs uncached.
- The next turn's Init call fires a fresh Create instead of the daemon staying uncached for the rest of its lifetime.
name is the cache reference the failed request carried, so a manager can ignore a report about a cache it has already replaced (vertexcache.Manager.MarkEvictedName). The reason string is opaque; wired into the operator-facing log line so grep-triage can distinguish TTL eviction from other 404 shapes as the deployment matures.
type ContextCacheNameFn ¶
type ContextCacheNameFn = cmgemini.ContextCacheNameFn
ContextCacheNameFn returns the currently-resolved cache name to stamp onto GenerateContentConfig.CachedContent, or "" if no cache is available yet (async Init still in flight, failed, or explicitly disabled). Empty return = request runs uncached, which is always safe — the caller degrades gracefully.
type Option ¶
type Option func(*Provider)
Option configures a Gemini Provider at construction time.
func WithBuiltinTools ¶
func WithBuiltinTools(b BuiltinTools) Option
WithBuiltinTools replaces the Provider's whole BuiltinTools set.
func WithCodeExecution ¶
WithCodeExecution toggles the CodeExecution built-in (sandboxed Python on Google's servers). Off by default.
func WithContextCache ¶
func WithContextCache(model string, init ContextCacheInitFn, name ContextCacheNameFn) Option
WithContextCache wires Vertex explicit-cache hooks into every GenerateContent call this Provider issues. Only meaningful on the Vertex backend — the direct Gemini API rejects the cache-reference parameter on some model families and the wrap silently no-ops on GeminiAPI even when set (the caller is expected to gate this on backend). Passing nil for either hook disables caching.
The hooks compose with builtins (google_search / url_context / code_execution): the cache is seeded from the request AFTER the builtins-append, so it contains the built-ins exactly when the model supports injecting them (see builtinsCompatible, #535) — cached and uncached turns always agree on the tool set.
model is the model the cache was created for (vertexcache.Manager's Model()): a cache serves one model, so the hooks apply only to requests for it.
func WithGoogleSearch ¶
WithGoogleSearch toggles the Google Search built-in.
func WithURLContext ¶
WithURLContext toggles the URL Context built-in.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is the Gemini-family implementation of models.Provider.
func NewAPIKey ¶
NewAPIKey returns a Provider authenticated against the public Gemini API using key. Empty key is rejected so the failure mode is clear at startup.
Built-in tools (Google Search + URL Context) are enabled by default; pass WithBuiltinTools / WithGoogleSearch / WithURLContext to override.
func NewVertex ¶
NewVertex returns a Provider authenticated against Vertex AI for the given GCP project and location, using Application Default Credentials.
Built-in tools (Google Search + URL Context) are enabled by default; pass WithBuiltinTools / WithGoogleSearch / WithURLContext to override.
func (*Provider) BuiltinToolNames ¶
BuiltinToolNames satisfies models.BuiltinToolsReporter — the effective server-side built-in set this Provider will inject, after config and options. Reported from what the Provider actually carries rather than re-derived from config, so the startup line cannot drift from the requests.
Provider-level, so it is an upper bound rather than a per-request promise: two paths drop these tools from an individual request afterwards — a pre-3.0 model carrying function declarations (the library logs its own line when it skips) and an explicitly suppressed one-shot (models.BuiltinsSuppressed). Both subtract, never add, so a name absent here is a tool that cannot be reached at all, which is the direction that matters for the operator reading this to confirm a `builtin_tools` disable took.
func (*Provider) Caches ¶
Caches returns the genai caches service on this Provider's endpoint and credentials, for building a vertexcache.Manager (see pkg/compose.MaybeWireContextCache) without a second copy of the backend, project and auth detection. It is the shared client's, and installing hooks afterwards keeps that client.
func (*Provider) DefaultSmallModel ¶
DefaultSmallModel satisfies models.SmallModelDefaulter so core-agent can route subtask digesting to a cheap-tier Gemini model without requiring the operator to set --agentic-small-model.
func (*Provider) Model ¶
Model constructs a model.LLM for the given model ID. The client is built here, so a missing credential fails at startup rather than on the first turn.
func (*Provider) SetContextCache ¶
func (p *Provider) SetContextCache(model string, init ContextCacheInitFn, name ContextCacheNameFn)
SetContextCache installs Vertex explicit-cache hooks on an already-constructed Provider. Same effect as WithContextCache but usable when the Provider comes from a registry (models.Resolve) that doesn't thread arbitrary options through — the daemon's wiring in cmd/core-agent constructs the vertexcache.Manager AFTER Resolve() returns because Manager needs cfg.Model.Name + a *genai.Caches client on the same endpoint and credentials (Caches).
Safe at any time: the hooks go onto the Provider's shared client, and every model — including one Model() returned earlier — uses them from its next call on. No second client is built.
func (*Provider) SetContextCacheInvalidate ¶
func (p *Provider) SetContextCacheInvalidate(invalidate ContextCacheInvalidateFn)
SetContextCacheInvalidate installs the eviction-recovery hook — called when GenerateContent detects that Vertex has reaped our cache server-side. See ContextCacheInvalidateFn. Optional: without it, cache-not-found responses surface as hard turn errors instead of transparent retry, and the daemon needs a restart to recover.
Same contract as SetContextCache: safe at any time, effective from each model's next call.