# 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/google` on `google.golang.org/genai` **v1.59.0**,
  `BackendGeminiAPI`, API key from `GOOGLE_API_KEY` then `GEMINI_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 → `FunctionResponse` parts in a user content
  (`{"output": ...}` / `{"error": ...}` payloads); tool schemas via
  `FunctionDeclaration.ParametersJsonSchema` (raw JSON schema — no lossy
  conversion to genai.Schema); structured output via `ResponseJsonSchema`
  + `application/json` MIME; `ToolChoice` → `FunctionCallingConfig` modes
  (`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.Seq2` to majordomo's pull-based
  `Stream` with `iter.Pull2`; `Close` releases 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` + `HTTPClient` pointed at `httptest` servers (the
  same technique as the SDK's own test suite); streaming fixtures are SSE.
- Errors: `genai.APIError` (value type; `Code` = HTTP status) maps to
  `llm.APIError{Status: Code, Code: Status}` so the standard classifier
  applies.

## Consequences

- `go.mod` gains 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.