steve
1ca607906d
Phase 4: provider/google on google.golang.org/genai v1.59.0 — lazy cached client, FunctionResponse tool loop, raw-JSON-schema tools and structured output, ThinkingLevel reasoning mapping, iter.Pull2 streaming, hermetic httptest suite via HTTPOptions.BaseURL. Registry wires google + gemini schemes to the real client; stub machinery deleted (all built-ins real). ADR-0011; README matrix + CLAUDE.md synced. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2.2 KiB
2.2 KiB
ADR-0011: Google provider on the official Gen AI SDK
Status: Accepted — 2026-06-10
Context
ADR-0007 approves exactly one third-party dependency: Google's surface
(auth modes, API versions, endpoint shapes) moves too much to hand-roll
profitably. The deprecated github.com/google/generative-ai-go is not an
option; google.golang.org/genai is the current official SDK.
Decision
- Build
provider/googleongoogle.golang.org/genaiv1.59.0,BackendGeminiAPI, API key fromGOOGLE_API_KEYthenGEMINI_API_KEY(the SDK's own precedence). - The SDK client is created lazily on first request and cached;
construction of the Provider never fails (per ADR-0005). A missing key
is a synthetic 401
APIError, so chains fail over past it. - Mappings (recorded in the package doc): assistant role →
model; tool results →FunctionResponseparts in a user content ({"output": ...}/{"error": ...}payloads); tool schemas viaFunctionDeclaration.ParametersJsonSchema(raw JSON schema — no lossy conversion to genai.Schema); structured output viaResponseJsonSchemaapplication/jsonMIME;ToolChoice→FunctionCallingConfigmodes (required→ ANY, named → ANY + AllowedFunctionNames,none→ tools omitted);ReasoningEffort→ThinkingConfig.ThinkingLevel(LOW/MEDIUM/HIGH); usage output = candidates + thoughts tokens; thought parts are skipped in content.
- Streaming adapts the SDK's
iter.Seq2to majordomo's pull-basedStreamwithiter.Pull2;Closereleases the iterator via its stop function. Function calls arrive whole per chunk (no partial-args assembly needed). - Hermetic tests use the SDK's documented hooks:
HTTPOptions.BaseURL+HTTPClientpointed athttptestservers (the same technique as the SDK's own test suite); streaming fixtures are SSE. - Errors:
genai.APIError(value type;Code= HTTP status) maps tollm.APIError{Status: Code, Code: Status}so the standard classifier applies.
Consequences
go.modgains genai and its transitive tree (auth, grpc, protobuf) — the one sanctioned dependency cost.- Vertex AI backend is NOT wired (API-key Gemini only); adding it later is an options-level change, not a redesign.