Google Gemini LLM provider

Gemini provider for Piko's LLM service. It covers chat completions, streaming, tool/function calling, structured output, and embeddings against Google's Generative Language API.

Overview

This provider implements llm.ProviderPort and llm.EmbeddingProviderPort against Google's Gemini API. The single registration serves both completions and embeddings. Image inputs are first-class alongside text. The provider converts text content parts and image content parts (by URL or inline bytes) into Gemini request parts. It does not pass video or audio through to the model. Gemini Flash is a low-cost model for high-volume, low-stakes generation. It suits subject lines, summaries of small inputs, classification, and routing.

The default model is gemini-2.5-flash. Set DefaultModel to one of the gemini-2.5-pro or gemini-2.5-flash-lite variants for the price and quality point you want. Embeddings default to text-embedding-004 (768 dimensions). The provider does not expose a BaseURL override. It targets the official Google endpoint (genai.BackendGeminiAPI) and accepts an API key only.

The provider declares its capabilities to the LLM service. It reports support for streaming, tool calling, structured output, deterministic seed, and frequency and presence penalties. It reports no support for parallel tool calls or per-message names. The service reads these signals before it dispatches a request, so it rejects an unsupported feature at the boundary instead of at the API.

The provider wraps 4xx errors (authentication, permission, invalid argument) in a safe error at the piko boundary. End users receive a generic message instead of the upstream detail. Other errors pass through unchanged for retry classification.

Requirements

  • A Google AI Studio API key for the Generative Language API. This provider has no Vertex backend or service-account path.
  • Network egress to generativelanguage.googleapis.com.

The provider is pure Go and needs no build tags or CGO. It runs unchanged in interpreted dev mode and in compiled builds.

Configuration

import (
    "os"

    "piko.sh/piko/wdk/llm/llm_provider_gemini"
)

provider, err := llm_provider_gemini.NewGeminiProvider(llm_provider_gemini.Config{
    APIKey:                os.Getenv("GEMINI_API_KEY"), // required
    DefaultModel:          "gemini-2.5-flash",          // optional; package default if empty
    DefaultEmbeddingModel: "text-embedding-004",        // optional; package default if empty
    EmbeddingDimensions:   0,                           // 0 = use the model's default (768)
})
if err != nil {
    return err
}

Config.Validate() rejects missing API keys at construction time. Config.WithDefaults() fills DefaultModel, DefaultEmbeddingModel, and EmbeddingDimensions when those fields are zero.

Bootstrap

ssr := piko.New(
    piko.WithLLMProvider("gemini", provider),
    piko.WithDefaultLLMProvider("gemini"),
)

Because the Gemini provider implements llm.EmbeddingProviderPort as well as llm.ProviderPort, this one registration also makes embeddings available. The container auto-detects embedding support from the LLM provider, so a separate piko.WithEmbeddingProvider call is redundant. Call piko.WithDefaultEmbeddingProvider("gemini") only when you run more than one provider and want Gemini to serve the default embeddings.

On shutdown, the provider cancels its background context and waits for in-flight streaming goroutines to drain within a bounded 30-second window, then releases idle connections. It cooperates with the piko lifecycle instead of leaking work.

See also

Other LLM providers:

  • Anthropic Claude, long-context, strong tool use.
  • OpenAI, widest model selection, native structured-output API.
  • Mistral, open-weight European provider.
  • Grok, xAI provider.
  • Ollama, local inference for offline or privacy-sensitive workloads.
  • Voyage, embeddings-only specialist.

Framework docs:

External: