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
- Variables
- func GroundingEvidence(gm *genai.GroundingMetadata) []string
- func IsBareInvalidArgument(err error) bool
- func IsBareInvalidArgumentBody(status int, body []byte) bool
- func IsTransient(err error) bool
- type BuiltinTools
- type Client
- type ContextCache
- type ContextCacheInitFn
- type ContextCacheInvalidateFn
- type ContextCacheNameFn
- type Options
Constants ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
New builds a Client. On Vertex AI with no Credential it detects Application Default Credentials, and fails if there are none.
func (*Client) 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 ¶
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 ¶
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. |