Documentation
¶
Overview ¶
Package gemini implements models.Provider for the Gemini family, covering both the public Gemini API (API-key auth) and Vertex AI (Application Default Credentials + GCP project).
The two are exposed as distinct provider names ("gemini" and "vertex") so users and automation can pin to a backend explicitly. Both delegate to google.golang.org/adk/model/gemini under the hood.
Index ¶
- Constants
- Variables
- func GroundingProjection(inner session.Service) session.Service
- type BuiltinTools
- type ContextCacheInitFn
- type ContextCacheInvalidateFn
- type ContextCacheNameFn
- type Option
- type Provider
- func (p *Provider) ClientConfig() *genai.ClientConfig
- 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(init ContextCacheInitFn, name ContextCacheNameFn)
- func (p *Provider) SetContextCacheInvalidate(invalidate ContextCacheInvalidateFn)
Constants ¶
const AuthorGoogleSearch = "gemini/google_search"
AuthorGoogleSearch is the synthetic event Author used for both "model issued a search query" and "model grounded on this web source" projected events. Stable across releases so eventlog consumers can filter on it.
const DefaultSmallModelID = "gemini-2.5-flash"
DefaultSmallModelID is the Gemini cheap-tier model used by default for agentic subtasks when the operator hasn't pinned one with --agentic-small-model.
Variables ¶
var ErrEmptyResponse = errors.New("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")
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.
Functions ¶
func GroundingProjection ¶
GroundingProjection wraps a session.Service so that every event carrying Gemini server-side built-in evidence (today: GoogleSearch grounding) is followed by one or more synthetic events surfacing that evidence under a stable Author namespace:
- "gemini/google_search" — one event per web search query the model issued, then one per grounded web source (title + URI)
Synthetic events share the parent event's InvocationID and Branch so they participate in eventlog queries (WithAuthor, WithBranchPrefix, WithSessionTree). Their Content.Role is left empty so ADK's content processor skips them when assembling the LLM's conversation history — they're for audit + display, not conversation context.
Wiring:
svc, _ := eventlog.Open(ctx, dialector) svc.Service = gemini.GroundingProjection(svc.Service) // wrap before WithSessionService agent.New(model, agent.WithSessionService(svc.Service))
URLContext evidence is not projected today: ADK's gemini wrapper drops URLContextMetadata at conversion (only GroundingMetadata is lifted onto model.LLMResponse). Capturing it would require intercepting raw genai responses below the ADK boundary; deferred until a consumer needs it.
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.
type ContextCacheInitFn ¶
type ContextCacheInitFn func(ctx context.Context, systemInstruction *genai.Content, tools []*genai.Tool)
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 func(reason string)
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.
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 ¶
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(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) — nothing special about their interaction.
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) ClientConfig ¶
func (p *Provider) ClientConfig() *genai.ClientConfig
ClientConfig returns a copy of the Provider's underlying genai client config so callers (chiefly cmd/core-agent) can construct a sibling *genai.Client for the vertexcache.Manager without duplicating auth/backend/project detection. Returns nil if the Provider was constructed without one (shouldn't happen via the public constructors, but defensive against tests).
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. When the Provider has any built-in tools enabled, the returned LLM is wrapped to inject them into Config.Tools on every request.
func (*Provider) SetContextCache ¶
func (p *Provider) SetContextCache(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 bound to the same ClientConfig the Provider already owns.
Not safe to call concurrently with a Model() invocation on the same Provider — treat as construction-time-only, invoked before the first Model() call.
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 concurrency contract as SetContextCache — treat as construction-time-only.
Source Files