gemini

Documentation

Overview

Package gemini provides a Google Gemini API client implementing the ai.Provider interface. It supports both AI Studio (API key) and Vertex AI (ADC) authentication.

Index

• type AuthType
• type Client
  • func NewClient(apiKey string, opts ...ClientOption) *Client
  • func NewVertexAIClient(projectID string, opts ...ClientOption) (*Client, error)
  • func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)
  • func (c *Client) Name() string
  • func (c *Client) NewHandler(model string, opts ...ai.HandlerOption) *ai.Handler
  • func (c *Client) Step(ctx context.Context, req *ai.Request) (*ai.Response, error)
  • func (c *Client) StreamStep(ctx context.Context, req *ai.Request, onChunk func(ai.StreamChunk)) (*ai.Response, error)
• type ClientOption
  • func WithBaseURL(url string) ClientOption
  • func WithHTTPClient(client *http.Client) ClientOption
  • func WithLocation(location string) ClientOption

Types

type AuthType

type AuthType string

AuthType indicates the authentication method.

const (
	// AuthAPIKey uses API key authentication (AI Studio).
	AuthAPIKey AuthType = "apikey"

	// AuthADC uses Application Default Credentials (Vertex AI).
	AuthADC AuthType = "adc"
)

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client implements ai.Provider for Google's Gemini API. It supports both AI Studio and Vertex AI endpoints.

func NewClient

func NewClient(apiKey string, opts ...ClientOption) *Client

NewClient creates a new Gemini client using API key (AI Studio).

func NewVertexAIClient

func NewVertexAIClient(projectID string, opts ...ClientOption) (*Client, error)

NewVertexAIClient creates a new Gemini client using ADC (Vertex AI). If projectID is empty, it will be fetched from gcloud config.

func (*Client) Generate

func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)

Generate implements ai.Provider.

func (*Client) Name

func (c *Client) Name() string

Name implements ai.Provider.

func (*Client) NewHandler

func (c *Client) NewHandler(model string, opts ...ai.HandlerOption) *ai.Handler

NewHandler creates an ai.Handler wrapping this client.

func (*Client) Step

func (c *Client) Step(ctx context.Context, req *ai.Request) (*ai.Response, error)

Step is the multi-turn / tool-aware completion entry point introduced by M-AI-TOOL-LOOP (v0.17.0). It translates req.Messages + req.Tools into the Gemini generateContent API's function-calling shape (functionCall / functionResponse parts on contents[].parts[]) and parses functionCall parts in the response into resp.ToolCalls.

Tool-call ID generation: Gemini does NOT assign tool-call IDs natively (unlike Anthropic and OpenAI). To keep the round-trip stable across loop turns, this adapter generates deterministic IDs of the form "<turn_index>_<call_index>" where turn_index is the count of assistant messages already present in req.Messages (so the first turn's calls get "0_0", "0_1", ...; the third turn's calls get "2_0", "2_1", ...) and call_index is the position of the functionCall part within the response parts. Loop drivers should treat the ID as opaque; only this adapter produces or consumes it.

Errors returned are always *ai.AIError (typed) so the AILANG-side _ai_call_result / _ai_step builtins can assert on Code/Retryable.

func (*Client) StreamStep

func (c *Client) StreamStep(ctx context.Context, req *ai.Request, onChunk func(ai.StreamChunk)) (*ai.Response, error)

StreamStep is the streaming variant of Step, introduced by M-AI-STEP-STREAMING (v0.18.7). It targets Gemini's streamGenerateContent endpoint with alt=sse — the response is SSE-framed (one JSON object per "data: " line, no event-type prefix), each object having the same shape as a single generateContent response chunk.

Per-chunk callback semantics:

• ai.StreamContentDelta is fired once per non-empty text part in any candidate chunk.
• ai.StreamUsage is fired exactly once after the stream closes, carrying the FINAL usageMetadata (Gemini emits a running usage block on every chunk; we only surface the last one to match the Anthropic/OpenAI semantics where Usage means "this is what the call consumed").
• functionCall parts are accumulated into resp.ToolCalls (turn-index based deterministic IDs, mirroring the non-streaming Step path). Tool calls are NOT streamed individually as ToolCallDelta — that's deferred to Phase 2.

Implements ai.StreamingProvider so ai.Handler.StepWithStream type-asserts successfully and dispatches natively rather than NO-OP-falling-back.

type ClientOption

type ClientOption func(*Client)

ClientOption configures a Client.

func WithBaseURL

func WithBaseURL(url string) ClientOption

WithBaseURL sets a custom base URL (useful for testing).

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client.

func WithLocation

func WithLocation(location string) ClientOption

WithLocation sets the GCP location for Vertex AI.