Documentation
¶
Overview ¶
Package google is the weft adapter for the Gemini API via the official google.golang.org/genai SDK. weft never owns the HTTP: every request goes through the SDK's client, and the SDK's stream iterator is the contract.
Mapping highlights (ADR 0013 has the full tables):
- Tool definitions become function declarations from Schema. Thought signatures round-trip as reasoning: surfaced from whichever part carries them, sent back on the first function call of a tool turn (where the API validates them) or on a thought part otherwise; unsigned reasoning is dropped.
- FilePart becomes inline data (base64) or a file URI.
- Function calls arrive whole; the adapter prefers the call id the API populates and synthesises call_<i> per step when absent, matching responses by position (the API matches by name and order).
- SequentialTools has no Gemini switch: function-calling config stays AUTO and the adapter's conformance run declares the sequential cap false — a documented gap, not a silent one.
- ModelRequest.Thinking maps onto thinkingConfig: Off zeroes the budget (Gemini's off switch), a Budget pins it, a bare level maps to thinkingLevel — and asks for thought summaries back so reasoning streams (ADR 0013 amendment 9).
Retry stance: transport retries (429, 5xx, connection errors) belong to the SDK via MaxRetries (off unless asked); the weft loop never retries a model call, and logic retries are model-seam middleware.
Vertex AI and Bedrock-style setups compose through Client(c) with their own genai.Client. Grounding, search, and code-execution tools are not wrapped here.
Index ¶
- func Model(name string, opts ...Option) core.Model
- type Option
- func APIKey(k string) Option
- func BaseURL(u string) Option
- func Client(c *genai.Client) Option
- func ExtraBody(fields map[string]any) Option
- func ExtraHeaders(h http.Header) Option
- func IdleTimeout(d time.Duration) Option
- func MaxRetries(n int) Option
- func MaxTokens(n int) Option
- func Seed(s int64) Option
- func Stop(seqs ...string) Option
- func Temperature(t float64) Option
- func TopP(p float64) Option
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Model ¶
Model returns a core.Model backed by the Gemini API. The SDK client is created lazily on the first run (its constructor wants a context for credential discovery), so constructing a Model performs no I/O. A Model is immutable and safe for concurrent runs.
Example ¶
Constructing a model performs no I/O; credentials ($GEMINI_API_KEY / $GOOGLE_API_KEY, then application default) are read on the first run. Swap providers by swapping this one line.
package main
import (
"context"
"github.com/weftgo/weft"
"github.com/weftgo/weft/google"
)
func main() {
m := google.Model("gemini-2.5-flash")
echo := weft.Tool("echo", "Echo a message.", func(ctx context.Context, in struct {
Message string `json:"message" jsonschema:"the text to repeat"`
}) (string, error) {
return in.Message, nil
})
agt := weft.New(m, echo)
_ = agt // a run is agt.Generate(ctx, weft.Prompt("Echo: hello"))
}
Output:
Types ¶
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option configures the adapter at construction, the same functional style as the core. The zero configuration discovers credentials the SDK's way ($GOOGLE_API_KEY / $GEMINI_API_KEY, then application default) and does not set a base URL.
func APIKey ¶
APIKey sets the API key. Default: the SDK's own discovery ($GOOGLE_API_KEY / $GEMINI_API_KEY, then application default credentials).
func BaseURL ¶
BaseURL points the adapter at a custom endpoint (a gateway, a proxy). When the option is not given the SDK applies its own $GOOGLE_GEMINI_BASE_URL.
func Client ¶
Client uses an already-configured SDK client (Vertex AI projects and regions, test doubles); it overrides BaseURL, APIKey, and MaxRetries. The WEFT_MODEL_REQUESTS kill switch guards egress from clients the adapter builds from credentials; an injected client's destinations are the caller's responsibility — which is why it stays reachable under deny (ADR 0013's kill-switch clause).
func ExtraBody ¶
ExtraBody adds fields to every request's JSON body — the generic valve for vendor knobs weft has no option for. Merged by the SDK into the body weft built (recursiveMapMerge): nested maps merge recursively, every other value replaces, and **your key wins on conflict** — the escape hatch is you taking responsibility for bytes weft did not choose, and the default-bytes tests do not cover what it sends. Construction-time only, and a snapshot: the values are deep-copied when the option applies, so mutating the map you passed afterwards never reaches the Model (safe for concurrent runs). It applies to the requests the adapter makes, including through an injected Client(c).
func ExtraHeaders ¶
ExtraHeaders adds HTTP headers to every request, verbatim. A header the SDK itself sets (Authorization, Content-Type) is yours not to clobber — the option does not check. Construction-time only, and a snapshot: the slices are copied when the option applies, so mutating the header values you passed afterwards never reaches the Model.
func IdleTimeout ¶
IdleTimeout is the maximum gap between two stream chunks before the call fails wrapping core.ErrStreamIdle (default 60s; zero disables it). The wait for response headers is the first gap — it covers the SDK's transport retries when MaxRetries asked for any. The ctx deadline stays the hard limit on the whole call — a slow but actively streaming response is never killed.
func MaxRetries ¶
MaxRetries forwards to the SDK's transport retry configuration (429/5xx/connection errors only; the SDK retries nothing unless asked). The weft loop never retries a model call; logic retries are model-seam middleware (TODO §4.1).
func MaxTokens ¶
MaxTokens caps a step's output tokens (maxOutputTokens). Zero keeps the provider default. The API's limit is an int32: a value above math.MaxInt32 fails the call wrapping core.ErrUnsupported rather than wrapping around on the wire. Options carry no error channel, so the check lands at convert time — the first place that can refuse — not at construction.
func Seed ¶
Seed sets the sampling seed — a best-effort determinism hint, not a contract. Not sent unless the option is given; a per-request core.RequestParams.Seed overrides it for one call. The wire field is an int32: a value outside that range fails the call wrapping core.ErrUnsupported at convert time (options carry no error channel — the MaxTokens rule).
func Stop ¶
Stop sets stop sequences; not sent unless the option is given. A per-request core.RequestParams.Stop overrides it for one call.
func Temperature ¶
Temperature sets the sampling temperature; it is not sent unless the option is given. A per-request core.RequestParams.Temperature overrides it for one call.
Source Files
Directories