protocol

package
v0.61.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 10, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package protocol implements the Google Gen AI wire protocol reused by Gemini and Vertex AI provider endpoints inside the models module.

Constructors:

  • NewChat — native genai chat: thinking budget, response modalities, system instructions, safety settings, structured output, tool calling, grounding with Google Search. Code execution is rejected because its output and replay state cannot be represented losslessly;
  • NewEmbeddingModel — text embeddings with outputDimensionality truncation; the selected model determines its supported dimensions;
  • NewStreamingSpeechModel — Gemini 3.1 TTS; Call consumes Stream;
  • NewSpeechModel — unary-only Gemini 2.5 TTS via generate_content with audio response modality;
  • NewTranscriptionModel — audio-input → text via generate_content (Gemini transcribes any audio attachment).

Token estimation: NewTextCounter wraps CountTokens for model-specific tokenizer-based counts.

Complete GenerateContent requests are prepared through the public SDK with a local capture transport because the SDK has no supported request-only API. Scope performs the real HTTP operation and strict response decoding separately; unsupported backend fields fail before the borrowed transport is called. Original opaque JSON payloads replace only their already-admitted SDK slots to avoid the SDK's float64 intermediate representation losing numeric precision.

Gemini's Context Caching API (cheaper repeated prompts) doesn't fit core/chat's request model and is not exposed.

genai supports two backends: Generative Language (api key) and Vertex AI has its own facade package and construction config.

Index

Constants

View Source 
const (
	RequestExtensionSuffix               = "/request"
	ResponseExtensionSuffix              = "/response"
	SpeechRequestExtensionSuffix         = "/speech_request"
	SpeechResponseExtensionSuffix        = "/speech_response"
	TranscriptionRequestExtensionSuffix  = "/transcription_request"
	TranscriptionResponseExtensionSuffix = "/transcription_response"
	EmbeddingRequestExtensionSuffix      = "/embedding_request"
	EmbeddingResponseExtensionSuffix     = "/embedding_response"
	ImageRequestExtensionSuffix          = "/image_request"
	ImageResponseExtensionSuffix         = "/image_response"
)
View Source 
const (
	SpeechRequestExtensionKey         = GoogleProviderID + SpeechRequestExtensionSuffix
	SpeechResponseExtensionKey        = GoogleProviderID + SpeechResponseExtensionSuffix
	TranscriptionRequestExtensionKey  = GoogleProviderID + TranscriptionRequestExtensionSuffix
	TranscriptionResponseExtensionKey = GoogleProviderID + TranscriptionResponseExtensionSuffix
	EmbeddingRequestExtensionKey      = GoogleProviderID + EmbeddingRequestExtensionSuffix
	EmbeddingResponseExtensionKey     = GoogleProviderID + EmbeddingResponseExtensionSuffix
)
View Source 
const (
	ModelGemini36Flash      = "gemini-3.6-flash"
	ModelGemini35Flash      = "gemini-3.5-flash"
	ModelGemini35FlashLite  = "gemini-3.5-flash-lite"
	ModelGemini31ProPreview = "gemini-3.1-pro-preview"

	ModelGemini25FlashPreviewTTS = "gemini-2.5-flash-preview-tts"
	ModelGemini25ProPreviewTTS   = "gemini-2.5-pro-preview-tts"
	ModelGemini31FlashTTSPreview = "gemini-3.1-flash-tts-preview"

	ModelGemini25FlashImage     = "gemini-2.5-flash-image"
	ModelGemini3ProImage        = "gemini-3-pro-image"
	ModelGemini31FlashImage     = "gemini-3.1-flash-image"
	ModelGemini31FlashLiteImage = "gemini-3.1-flash-lite-image"

	ModelGeminiEmbedding2 = "gemini-embedding-2"
)
View Source 
const DefaultBaseURL = "https://generativelanguage.googleapis.com"
View Source 
const GoogleProviderID = "google"
View Source 
const (
	// RequestExtensionKey stores provider-specific [genai.GenerateContentConfig]
	// fields using the SDK's JSON names. Fields owned by Core are rejected, as is
	// codeExecution because its output and replay cannot be represented losslessly.
	RequestExtensionKey = GoogleProviderID + RequestExtensionSuffix
)
View Source 
const (
	// ResponseExtensionKey preserves the complete official GenerateContent
	// response (or the current official stream chunk).
	ResponseExtensionKey = GoogleProviderID + ResponseExtensionSuffix
)

Variables

View Source 
var ErrInvalidGenerationResponse = errors.New("google: invalid generation response")

Functions

func ValidateGenerationCompletion added in v0.54.0 

func ValidateGenerationCompletion(response *genai.GenerateContentResponse) error

ValidateGenerationCompletion requires native success for every returned candidate. Image generation may produce multiple candidates; unary speech narrows that cardinality separately.

Types

type Chat 

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

Chat implements the minimal Core Model and optional Streamer capabilities.

func NewChat 

func NewChat(ctx context.Context, config ChatConfig) (*Chat, error)

func (*Chat) Call 

func (c *Chat) Call(ctx context.Context, req *corechat.Request) (*corechat.Response, error)

func (*Chat) Stream 

func (c *Chat) Stream(ctx context.Context, req *corechat.Request) iter.Seq2[*corechat.ResponseDelta, error]

Stream performs one streaming GenerateContent request. Candidate and logical part offsets are retained only for the lifetime of this stream. A native finish reason ends generation; subsequent content returns corechat.ErrInvalidResponse. Metadata may follow, and completion is published only after the stream ends.

type ChatConfig 

type ChatConfig struct {
	Provider       string
	Client         ClientConfig
	DefaultOptions corechat.Options
}

func (ChatConfig) Validate 

func (c ChatConfig) Validate() error

type ClientConfig 

type ClientConfig struct {
	APIKey string

	// Backend selects the genai backend. Zero value falls back to
	// [genai.BackendGeminiAPI] — the public Gemini API. Set to
	// [genai.BackendVertexAI] for GCP-hosted enterprise deployments;
	// Project and Location become required in that mode and APIKey
	// is ignored in favor of the supplied [genai.ClientConfig.Credentials]
	// (or ADC).
	Backend genai.Backend

	// Project is the GCP project id, required when Backend ==
	// BackendVertexAI. Ignored otherwise.
	Project string

	// Location is the GCP region (e.g. "us-central1"), required when
	// Backend == BackendVertexAI. Ignored otherwise.
	Location string

	// BaseURL overrides the genai client endpoint. Optional —
	// production users should leave it empty (the SDK picks the right
	// host per Backend). Useful for mock servers / corporate proxies.
	BaseURL    string
	APIVersion string

	// HTTPClient remains owned by the caller; the SDK borrows a shallow copy.
	HTTPClient *http.Client
}

func (ClientConfig) Validate 

func (c ClientConfig) Validate() error

type EmbeddingModel 

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

EmbeddingModel admits the SDK's dimensionality representation; the selected model owns its supported dimensions. Core's text-only request cannot carry multimodal embedding inputs through a hidden native extension.

func NewEmbeddingModel 

func NewEmbeddingModel(ctx context.Context, config EmbeddingModelConfig) (*EmbeddingModel, error)

func (*EmbeddingModel) Call 

func (e *EmbeddingModel) Call(ctx context.Context, req *embedding.Request) (*embedding.Response, error)

type EmbeddingModelConfig 

type EmbeddingModelConfig struct {
	Provider       string
	Client         ClientConfig
	DefaultOptions embedding.Options
}

func (EmbeddingModelConfig) Validate 

func (e EmbeddingModelConfig) Validate() error

type GenerationClient added in v0.54.0 

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

GenerationClient owns GenerateContent's native request and response boundary. The SDK owns authentication and complete request projection. Scope owns strict response decoding and the lifetime of the single real HTTP request.

func NewGenerationClient added in v0.54.0 

func NewGenerationClient(ctx context.Context, config ClientConfig) (*GenerationClient, error)

func (*GenerationClient) GenerateContent added in v0.54.0 

func (g *GenerationClient) GenerateContent(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) (*genai.GenerateContentResponse, error)

func (*GenerationClient) GenerateContentStream added in v0.54.0 

func (g *GenerationClient) GenerateContentStream(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) iter.Seq2[*genai.GenerateContentResponse, error]

type SpeechModel added in v0.41.0 

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

SpeechModel owns Gemini 2.5's unary-only synthesis protocol. Gemini 3.1 uses StreamingSpeechModel for both aggregate and streaming output.

Speed and OutputFormat are not honored: Gemini's TTS has no playback-rate knob. GenerateContent returns 24 kHz signed 16-bit little-endian PCM; callers choose their own container at the application boundary.

func NewSpeechModel added in v0.41.0 

func NewSpeechModel(ctx context.Context, config SpeechModelConfig) (*SpeechModel, error)

func (*SpeechModel) Call added in v0.41.0 

func (s *SpeechModel) Call(ctx context.Context, req *speech.Request) (*speech.Response, error)

type SpeechModelConfig added in v0.41.0 

type SpeechModelConfig struct {
	Provider       string
	Client         ClientConfig
	DefaultOptions speech.Options
	// Call must fit in memory; Stream retains incremental delivery. Zero uses
	// speech.DefaultMaxAudioBytes, and a negative limit is invalid.
	MaxResponseBytes int64
}

func (SpeechModelConfig) Validate added in v0.41.0 

func (s SpeechModelConfig) Validate() error

type StreamingSpeechModel added in v0.41.0 

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

func NewStreamingSpeechModel added in v0.41.0 

func NewStreamingSpeechModel(ctx context.Context, config SpeechModelConfig) (*StreamingSpeechModel, error)

func (*StreamingSpeechModel) Call added in v0.41.0 

func (s *StreamingSpeechModel) Call(ctx context.Context, req *speech.Request) (*speech.Response, error)

Call consumes the same stream to completion. Failed or interrupted synthesis never returns partial audio as a complete response.

func (*StreamingSpeechModel) Stream added in v0.41.0 

func (s *StreamingSpeechModel) Stream(ctx context.Context, req *speech.Request) iter.Seq2[*speech.Response, error]

type TextCounter added in v0.21.0 

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

TextCounter reports input-token counts via Gemini's count_tokens endpoint. Implements tokenizer.TextCounter so it drops into code paths gating on token budgets (RAG chunking, prompt-window checks).

func NewTextCounter added in v0.21.0 

func NewTextCounter(ctx context.Context, config TextCounterConfig) (*TextCounter, error)

func (*TextCounter) CountText added in v0.21.0 

func (t *TextCounter) CountText(ctx context.Context, text string) (int, error)

CountText returns the prompt-token count Gemini would charge if text were sent as a single user message under the configured model.

type TextCounterConfig added in v0.21.0 

type TextCounterConfig struct {
	Client ClientConfig
	Model  string
}

Token counts vary across model families — supply the same Model name you intend to send chat requests under so the count matches the real billing.

func (TextCounterConfig) Validate added in v0.21.0 

func (t TextCounterConfig) Validate() error

type TranscriptionModel added in v0.41.0 

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

TranscriptionModel exposes Gemini's multimodal chat through the transcription interface. Gemini has no /transcribe endpoint — any audio-accepting model returns a transcript when prompted. This adapter uses the stable instruction "Transcribe this audio.".

func NewTranscriptionModel added in v0.41.0 

func NewTranscriptionModel(ctx context.Context, config TranscriptionModelConfig) (*TranscriptionModel, error)

func (*TranscriptionModel) Call added in v0.41.0 

func (t *TranscriptionModel) Call(ctx context.Context, req *transcription.Request) (*transcription.Response, error)

type TranscriptionModelConfig added in v0.41.0 

type TranscriptionModelConfig struct {
	Provider       string
	Client         ClientConfig
	DefaultOptions transcription.Options
}

func (TranscriptionModelConfig) Validate added in v0.41.0 

func (t TranscriptionModelConfig) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.