gt

package module
v0.5.14 Latest Latest
Warning

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

 Go to latest Published: Feb 12, 2026 License: MIT Imports: 28 Imported by: 5

README

gemini-things-go

A helper library for generating things with Gemini API.

Go Reference

Usage

See the code examples in the generation_test.go file.

package main

import (
	"context"
	"fmt"
	"time"

	gt "github.com/meinside/gemini-things-go"
)

const (
	apiKey = `AIabcdefghijklmnopqrstuvwxyz_ABCDEFG-00000000-00` // Your API key here
	model  = "gemini-2.5-flash"

	contentsBuildupTimeoutSeconds = 60
	generationTimeoutSeconds      = 30
)

func main() {
	if client, err := gt.NewClient(
		apiKey,
		gt.WithModel(model),     // Specify the model
		gt.WithMaxRetryCount(5), // Configure a maximum of 5 retries on 5xx server errors
	); err == nil {
		ctxContents, cancelContents := context.WithTimeout(context.TODO(), contentsBuildupTimeoutSeconds*time.Second)
		defer cancelContents()

		// convert prompts and histories to contents for generation
		if contents, err := client.PromptsToContents(
			ctxContents,
			[]gt.Prompt{
				gt.PromptFromText(`What is the answer to life, the universe, and everything?`),
			},
			nil,
		); err == nil {
			ctxGenerate, cancelGenerate := context.WithTimeout(context.TODO(), generationTimeoutSeconds*time.Second)
			defer cancelGenerate()

			// generate with contents
			if res, err := client.Generate(
				ctxGenerate,
				contents,
			); err == nil {
				// do something with the generated response
				fmt.Printf("response: %+v\n", res)
			} else {
				panic(fmt.Errorf("failed to generate: %w", err))
			}
		} else {
			panic(fmt.Errorf("failed to convert prompts: %w", err))
		}
	} else {
		panic(fmt.Errorf("failed to create client: %w", err))
	}
}

Test

Test with Gemini API key:

$ GEMINI_API_KEY="AIabcdefghijklmnopqrstuvwxyz_ABCDEFG-00000000-00" go test -timeout 0

# for verbose output:
$ GEMINI_API_KEY="AIabcdefghijklmnopqrstuvwxyz_ABCDEFG-00000000-00" VERBOSE=true go test -timeout 0

# for testing free APIs only
$ GEMINI_API_KEY="AIabcdefghijklmnopqrstuvwxyz_ABCDEFG-00000000-00" go test -run="Free"

# for testing paid APIs only
$ GEMINI_API_KEY="AIabcdefghijklmnopqrstuvwxyz_ABCDEFG-00000000-00" go test -run="Paid"

or with Google Cloud credential file (for Vertex AI):

$ CREDENTIALS_FILEPATH="/path/to/credentials.json" go test -timeout 0

Documentation

Overview

Package gt provides a client for interacting with the Google Generative AI API. It encapsulates a genai.Client and adds higher-level functionalities.

Index

Constants

View Source 
const (
	RoleUser  genai.Role = genai.RoleUser
	RoleModel genai.Role = genai.RoleModel
)

role constants for convenience

View Source 
const (
	PrefixAPIError = "genai API error"
)

Variables

This section is empty.

Functions

func APIError added in v0.3.4 

func APIError(err error) (ae genai.APIError, isAPIError bool)

APIError checks if the provided error is a `*genai.APIError` and returns it if it is.

func ErrDetails added in v0.3.2 

func ErrDetails(err error) []map[string]any

ErrDetails returns the `Details` of given `genai.APIError`. Returns nil if it is not a `genai.APIError`, or something goes wrong with it.

func ErrToStr added in v0.1.2 

func ErrToStr(err error) (str string)

ErrToStr converts an error into a string. If the error is a `*genai.APIError`, it formats it with a prefix "genai API error: ". Otherwise, it calls the error's `Error()` method.

func FuncArg 

func FuncArg[T any](from map[string]any, key string) (*T, error)

FuncArg is a generic helper function to safely extract and type-assert a value from a map[string]any, which is commonly used for function call arguments in `genai.FunctionCall.Args`.

Parameters:

  • from: The map (typically `FunctionCall.Args`) to extract the value from.
  • key: The key of the desired argument.

Type Parameter:

  • T: The expected type of the argument.

Returns:

  • *T: A pointer to the extracted value of type T if found and type assertion is successful. Returns nil if the key is not found.
  • error: An error if the key is found but the value cannot be cast to type T. Returns nil if the key is not found or if extraction and casting are successful.

func GenerateSafetySettings added in v0.5.0 

func GenerateSafetySettings(threshold *genai.HarmBlockThreshold) (settings []*genai.SafetySetting)

GenerateSafetySettings creates a slice of *genai.SafetySetting for all supported harm categories, applying the given threshold. If threshold is nil, it defaults to HarmBlockThresholdOff. This function is an internal helper.

func IsModelOverloaded added in v0.1.33 

func IsModelOverloaded(err error) bool

IsModelOverloaded checks if the provided error is a `*genai.APIError` with a status code 503 and a message indicating that the model is currently overloaded.

func IsQuotaExceeded added in v0.1.32 

func IsQuotaExceeded(err error) bool

IsQuotaExceeded checks if the provided error is a `*genai.APIError` with a status code 429 indicating that a quota limit has been exceeded.

func MCPToGeminiTools added in v0.3.12 

func MCPToGeminiTools(
	from []*mcp.Tool,
) (to []*genai.FunctionDeclaration, err error)

MCPToGeminiTools converts given []mcp.Tool to []genai.FunctionDeclaration.

InputSchema value of each mcp.Tool should be in type: `jsonschema.Schema` or `map[string]any`.

func SupportedMimeType added in v0.0.14 

func SupportedMimeType(data []byte) (matchedMimeType string, supported bool, err error)

SupportedMimeType detects the MIME type of the given byte data and checks if it's a supported format for the Gemini API (as defined in `checkMimeType`).

Parameters:

  • data: A byte slice containing the file data.

Returns:

  • matchedMimeType: The string representation of the detected MIME type if successful, or the result of `http.DetectContentType` if `mimetype.DetectReader` fails.
  • supported: A boolean indicating true if the MIME type is supported, false otherwise.
  • err: An error if MIME type detection fails significantly (e.g., reader error, though less likely with bytes.Reader).

func SupportedMimeTypePath added in v0.1.9 

func SupportedMimeTypePath(filepath string) (matchedMimeType string, supported bool, err error)

SupportedMimeTypePath opens a file at the given path, detects its MIME type, and checks if it's a supported format for the Gemini API (as defined in `checkMimeType`).

Parameters:

  • filepath: The path to the file.

Returns:

  • matchedMimeType: The string representation of the detected MIME type if successful.
  • supported: A boolean indicating true if the MIME type is supported, false otherwise.
  • err: An error if opening the file or detecting the MIME type fails.

Types

type BytesPrompt added in v0.2.1 

type BytesPrompt struct {
	Filename string // Optional display name for the byte data, used if uploaded.
	Bytes    []byte // The raw byte data of the file.

	// The MIME type of the byte data (e.g., "image/png"), typically auto-detected.
	MIMEType string

	// When this data needs to be handled as a specific MIME type,
	// set this value then it will be forced to that type.
	ForcedMIMEType string
}

BytesPrompt represents a prompt where the file data is provided directly as a byte slice. This is typically used for smaller files that can be inlined in the request if not uploaded, or uploaded if they exceed size limits for inline data or if a file URI is preferred. The `filename` field can be used to provide a display name if the bytes are uploaded.

func (BytesPrompt) String added in v0.2.1 

func (p BytesPrompt) String() string

String returns a string representation of the BytesPrompt, including its filename (if any), length, and MIME type.

func (BytesPrompt) ToPart added in v0.2.1 

func (p BytesPrompt) ToPart() genai.Part

ToPart converts the BytesPrompt into a `genai.Part`. If the BytesPrompt was processed by `client.processPromptToPartAndInfo` and uploaded, it would have been converted to a FilePrompt, and that FilePrompt's ToPart would be used. This ToPart method is for when BytesPrompt is used directly to form an InlineData part.

type ChunkedText added in v0.1.35 

type ChunkedText struct {
	Original string   // Original is the input text that was chunked.
	Chunks   []string // Chunks is a slice of strings, where each string is a chunk of the original text.
}

ChunkedText holds the original text and the generated chunks.

func ChunkText added in v0.1.35 

func ChunkText(text string, opts ...TextChunkOption) (ChunkedText, error)

ChunkText splits a given text into smaller chunks based on the provided options. This can be useful for processing large texts that might exceed model input limits. It supports overlapping chunks and handling of UTF-8 characters at boundaries.

Parameters:

  • text: The string to be chunked.
  • opts: Optional TextChunkOption to customize chunking behavior. If not provided, default chunk size, overlap size, and UTF-8 handling will be used.

Returns:

  • ChunkedText: A struct containing the original text and a slice of its chunks.
  • error: An error if the configuration is invalid (e.g., overlappedSize >= chunkSize).

type Client 

type Client struct {
	Type genai.Backend

	DeleteFilesOnClose  bool // If true, automatically deletes all uploaded files when Close is called.
	DeleteCachesOnClose bool // If true, automatically deletes all cached contexts when Close is called.
	Verbose             bool // If true, enables verbose logging for debugging.
	// contains filtered or unexported fields
}

Client provides methods for interacting with the Google Generative AI API. It encapsulates a genai.Client and adds higher-level functionalities.

func NewClient 

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

NewClient creates and returns a new Client instance which uses Gemini API.

It requires an API key and accepts optional ClientOption functions to customize the client.

Example: 

client, err := gt.NewClient(
	"YOUR_API_KEY",
	gt.WithModel("gemini-2.5-flash"),
	gt.WithMaxRetryCount(3),
)
if err != nil {
	log.Fatal(err)
}
defer client.Close()

func NewVertexClient added in v0.4.10 

func NewVertexClient(
	ctx context.Context,
	credentialsJSON []byte,
	location string,
	bucketName string,
	opts ...ClientOption,
) (*Client, error)

NewVertexClient creates and returns a new Client instance which uses Vertex AI API.

It requires a project ID, location, and credentials and accepts optional ClientOption functions to customize the client.

func (*Client) Batch added in v0.3.18 

func (c *Client) Batch(
	ctx context.Context,
	name string,
) (batch *genai.BatchJob, err error)

Batch returns the batch job with the given name.

func (*Client) CacheContext added in v0.1.0 

func (c *Client) CacheContext(
	ctx context.Context,
	systemInstruction *string,
	prompts []Prompt,
	tools []*genai.Tool,
	toolConfig *genai.ToolConfig,
	cachedContextDisplayName *string,
) (cachedContextName string, err error)

CacheContext creates a cached content entry on the server. This can be used to reduce latency and token count for frequently used context.

A `model` must be set in the Client before calling. The `systemInstruction`, `prompts`, `tools`, `toolConfig`, and `cachedContextDisplayName` are used to configure the cached content.

Returns the server-assigned name of the cached content and any error encountered.

func (*Client) CancelBatch added in v0.3.18 

func (c *Client) CancelBatch(ctx context.Context, name string) (err error)

CancelBatch cancels the batch job with the given name.

func (*Client) Close added in v0.1.0 

func (c *Client) Close(ctx ...context.Context) error

Close releases resources associated with the client. It handles the deletion of uploaded files and cached contexts if configured to do so via `deleteFilesOnClose` and `deleteCachesOnClose` respectively. Any errors encountered during cleanup are collected and returned as a single joined error. An optional context can be provided for the cleanup operations.

func (*Client) CountTokens added in v0.2.9 

func (c *Client) CountTokens(
	ctx context.Context,
	contents []*genai.Content,
	config ...*genai.CountTokensConfig,
) (res *genai.CountTokensResponse, err error)

CountTokens calculates the number of tokens that the provided content would consume. This is useful for understanding and managing token usage.

A `model` must be set in the Client.

See https://ai.google.dev/gemini-api/docs/tokens?lang=go for more information.

func (*Client) CreateBucketForFileUploads added in v0.4.9 

func (c *Client) CreateBucketForFileUploads(ctx context.Context) error

CreateBucketForFileUploads creates a Google Cloud Storage bucket for file uploads.

func (*Client) CreateFileSearchStore added in v0.3.52 

func (c *Client) CreateFileSearchStore(
	ctx context.Context,
	displayName string,
) (store *genai.FileSearchStore, err error)

CreateFileSearchStore creates a new file search store.

func (*Client) DeleteAllCachedContexts added in v0.1.0 

func (c *Client) DeleteAllCachedContexts(ctx context.Context) (err error)

DeleteAllCachedContexts iterates through all available cached content and deletes each one. The `model` does not need to be set in the client for this operation. Errors encountered during deletion of individual caches are aggregated. Consider the rate limits if deleting a very large number of caches.

func (*Client) DeleteAllFiles added in v0.1.0 

func (c *Client) DeleteAllFiles(ctx context.Context) (err error)

DeleteAllFiles iterates through all uploaded files associated with the API key and deletes them. The `model` does not need to be set in the client for this operation. Errors during deletion of individual files are aggregated. Consider rate limits if deleting a large number of files.

func (*Client) DeleteBatch added in v0.3.18 

func (c *Client) DeleteBatch(ctx context.Context, name string) (err error)

DeleteBatch deletes the batch job with the given name.

func (*Client) DeleteBucketForFileUploads added in v0.4.9 

func (c *Client) DeleteBucketForFileUploads(ctx context.Context) error

DeleteBucketForFileUploads deletes a Google Cloud Storage bucket which was created for file uploads.

func (*Client) DeleteCachedContext added in v0.1.4 

func (c *Client) DeleteCachedContext(
	ctx context.Context,
	cachedContextName string,
) (err error)

DeleteCachedContext deletes a specific cached content entry by its name. The `model` does not need to be set in the client for this operation.

func (*Client) DeleteFileInFileSearchStore added in v0.3.54 

func (c *Client) DeleteFileInFileSearchStore(
	ctx context.Context,
	fileName string,
) error

DeleteFileInFileSearchStore deletes a file in a file search store.

func (*Client) DeleteFileSearchStore added in v0.3.52 

func (c *Client) DeleteFileSearchStore(
	ctx context.Context,
	fileSearchStoreName string,
) (err error)

DeleteFileSearchStore deletes a file search store.

func (*Client) Generate 

func (c *Client) Generate(
	ctx context.Context,
	contents []*genai.Content,
	options ...*genai.GenerateContentConfig,
) (res *genai.GenerateContentResponse, err error)

Generate performs a synchronous content generation request. It builds the prompt from the provided `prompts`, sends it to the API, and returns the full response.

A `model` must be set in the Client before calling.

It also implements a retry mechanism for 5xx server errors, configured by `c.maxRetryCount` (configurable via `WithMaxRetryCount` or `SetMaxRetryCount`).

func (*Client) GenerateEmbeddings added in v0.1.24 

func (c *Client) GenerateEmbeddings(
	ctx context.Context,
	title string,
	contents []*genai.Content,
	taskType *EmbeddingTaskType,
) (vectors [][]float32, err error)

GenerateEmbeddings creates vector embeddings for the given content.

A `model` (specifically an embedding model) must be set in the Client. The `title` is optional but recommended if `taskType` is `EmbeddingTaskRetrievalDocument`. `contents` are the actual pieces of text/data to embed. `taskType` specifies the intended use of the embeddings, allowing the model to optimize them.

Refer to https://ai.google.dev/gemini-api/docs/embeddings for more details.

func (*Client) GenerateImages added in v0.2.3 

func (c *Client) GenerateImages(
	ctx context.Context,
	prompt string,
	options ...*genai.GenerateImagesConfig,
) (res *genai.GenerateImagesResponse, err error)

GenerateImages generates images based on the provided text prompt and options.

A `model` (specifically an image generation model) must be set in the Client before calling.

func (*Client) GenerateStreamIterated added in v0.0.11 

func (c *Client) GenerateStreamIterated(
	ctx context.Context,
	contents []*genai.Content,
	options ...*genai.GenerateContentConfig,
) iter.Seq2[*genai.GenerateContentResponse, error]

GenerateStreamIterated returns an iterator (iter.Seq2) for streaming generated content. This method allows for processing parts of the response as they arrive.

A `model` must be set in the Client (e.g., via WithModel or by setting c.model directly) before calling this function, otherwise an error will be yielded by the iterator.

Example: 

ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()

if contents, err := client.PromptsToContents(ctx, []gt.Prompt{gt.PromptFromText("Tell me a story.")}, nil); err == nil {
	iter := client.GenerateStreamIterated(ctx, []gt.Prompt{gt.PromptFromText("Tell me a story.")})
	for resp, err := range iter {
		if err != nil { /* handle error */
		}
		// process response part
	}
}

func (*Client) GenerateVideos added in v0.5.0 

func (c *Client) GenerateVideos(
	ctx context.Context,
	prompt *string,
	image *genai.Image,
	video *genai.Video,
	options ...*genai.GenerateVideosConfig,
) (res *genai.GenerateVideosResponse, err error)

GenerateVideos generates videos based on the provided text prompt and options. It will wait for the operation to complete before returning the result.

A `model` (specifically a video generation model) must be set in the Client before calling.

func (*Client) GenerateWithRecursiveToolCalls added in v0.3.11 

func (c *Client) GenerateWithRecursiveToolCalls(
	ctx context.Context,
	fnCallHandlers map[string]FunctionCallHandler,
	contents []*genai.Content,
	options ...*genai.GenerateContentConfig,
) (res *genai.GenerateContentResponse, err error)

GenerateWithRecursiveToolCalls generates recursively with resulting tool calls.

func (*Client) GetBucketName added in v0.5.1 

func (c *Client) GetBucketName() string

GetBucketName returns the name of the Google Cloud Storage bucket to use for (temporary) file uploads.

func (*Client) GetFileSearchStore added in v0.3.52 

func (c *Client) GetFileSearchStore(
	ctx context.Context,
	fileSearchStoreName string,
) (store *genai.FileSearchStore, err error)

GetFileSearchStore gets a file search store.

func (*Client) ImportFileForSearch added in v0.3.52 

func (c *Client) ImportFileForSearch(
	ctx context.Context,
	fileSearchStoreName string,
	fileName string,
	metadata []*genai.CustomMetadata,
	chunkConfig *genai.ChunkingConfig,
) (operation *genai.ImportFileOperation, err error)

ImportFileForSearch imports an alread-uploaded file into a file search store.

Supported file formats are: https://ai.google.dev/gemini-api/docs/file-search#supported-files

func (*Client) ListAllCachedContexts added in v0.1.3 

func (c *Client) ListAllCachedContexts(ctx context.Context) (listed map[string]*genai.CachedContent, err error)

ListAllCachedContexts retrieves a list of all cached content entries available. The `model` does not need to be set in the client for this operation. It returns a map where keys are cached content names and values are the corresponding `*genai.CachedContent` objects.

func (*Client) ListBatches added in v0.3.18 

func (c *Client) ListBatches(ctx context.Context) iter.Seq2[*genai.BatchJob, error]

ListBatches returns a list of all batch jobs available to the authenticated API key.

func (*Client) ListFileSearchStores added in v0.3.52 

func (c *Client) ListFileSearchStores(
	ctx context.Context,
) (stores iter.Seq2[*genai.FileSearchStore, error])

ListFileSearchStores lists all file search stores.

func (*Client) ListFilesInFileSearchStore added in v0.3.54 

func (c *Client) ListFilesInFileSearchStore(
	ctx context.Context,
	fileSearchStoreName string,
) iter.Seq2[*genai.Document, error]

ListFilesInFileSearchStore lists all files in a file search store.

func (*Client) ListModels added in v0.2.14 

func (c *Client) ListModels(ctx context.Context) (models []*genai.Model, err error)

ListModels retrieves a list of all generative models available to the authenticated API key. The `model` field in the Client does not need to be set for this operation. The function handles pagination automatically and returns a consolidated list of models.

func (*Client) PromptsToContents added in v0.4.0 

func (c *Client) PromptsToContents(
	ctx context.Context,
	prompts []Prompt, histories []genai.Content,
) (contents []*genai.Content, err error)

PromptsToContents constructs a `[]*genai.Content` slice with given `prompts` and `histories`.

func (*Client) RequestBatch added in v0.3.18 

func (c *Client) RequestBatch(
	ctx context.Context,
	job *genai.BatchJobSource,
	displayName string,
) (batch *genai.BatchJob, err error)

RequestBatch creates a batch job for the given job source.

A `model` (specifically a batch model) must be set in the Client. `displayName` is an optional name to give the batch job.

func (*Client) RequestBatchEmbeddings added in v0.3.46 

func (c *Client) RequestBatchEmbeddings(
	ctx context.Context,
	job *genai.EmbeddingsBatchJobSource,
	displayName string,
) (batch *genai.BatchJob, err error)

RequestBatchEmbeddings creates a batch job for the given embeddings job source.

A `model` (specifically a batch model) must be set in the Client. `displayName` is an optional name to give the batch job.

func (*Client) SetCachedContextExpireTime added in v0.1.0 

func (c *Client) SetCachedContextExpireTime(
	ctx context.Context,
	cachedContextName string,
	expireTime time.Time,
) (err error)

SetCachedContextExpireTime updates the expiration time of an existing cached content. The `model` does not need to be set in the client for this operation, as it uses the `cachedContextName`. The `expireTime` specifies the new absolute time at which the cache should expire.

func (*Client) SetCachedContextTTL added in v0.1.0 

func (c *Client) SetCachedContextTTL(
	ctx context.Context,
	cachedContextName string,
	ttl time.Duration,
) (err error)

SetCachedContextTTL updates the Time-To-Live (TTL) of an existing cached content. The `model` does not need to be set in the client for this operation. The `ttl` specifies the new duration for which the cache should live from the time of the update. A common default TTL (e.g., 1 hour) is often applied by the server if not specified.

func (*Client) SetFileConverter added in v0.2.3 

func (c *Client) SetFileConverter(mimeType string, fn FnConvertBytes)

SetFileConverter registers a custom function to convert files of a specific MIME type before they are uploaded. This is useful for unsupported MIME types or for pre-processing. The provided function `fn` will be called if the MIME type matches `mimeType` and is not natively supported (see `SupportedMimeType`).

func (*Client) SetMaxRetryCount added in v0.3.0 

func (c *Client) SetMaxRetryCount(count uint)

SetMaxRetryCount sets the default maximum number of retries for retriable API errors (typically 5xx server errors) encountered during operations like Generate.

func (*Client) SetNumDaysUploadedFilesTTL added in v0.4.9 

func (c *Client) SetNumDaysUploadedFilesTTL(days int64)

SetNumDaysUploadedFilesTTL sets the number of days for which uploaded files should be retained in the Google Cloud Storage bucket.

func (*Client) SetSystemInstructionFunc 

func (c *Client) SetSystemInstructionFunc(fn FnSystemInstruction)

SetSystemInstructionFunc sets a custom function that provides the system instruction string. This instruction is used by the model to guide its behavior. If a model or specific generation task does not support system instructions, or to remove a previously set instruction, pass `nil`.

func (*Client) Storage added in v0.4.9 

func (c *Client) Storage() *storage.Client

Storage returns the Google Cloud Storage client used by the client.

func (*Client) UploadFile added in v0.3.52 

func (c *Client) UploadFile(
	ctx context.Context,
	file io.Reader,
	fileDisplayName string,
	overrideMimeType ...string,
) (uploaded *genai.File, err error)

UploadFile uploads a file to the Gemini API.

If `overrideMimeType` is not given, it will be inferred from the file bytes.

func (*Client) UploadFileForSearch added in v0.3.52 

func (c *Client) UploadFileForSearch(
	ctx context.Context,
	fileSearchStoreName string,
	file io.Reader,
	fileDisplayName string,
	metadata []*genai.CustomMetadata,
	chunkConfig *genai.ChunkingConfig,
	overrideMimeType ...string,
) (operation *genai.UploadToFileSearchStoreOperation, err error)

UploadFileForSearch creates a new file in a file search store.

If `overrideMimeType` is not given, it will be inferred from the file bytes.

Supported file formats are: https://ai.google.dev/gemini-api/docs/file-search#supported-files

func (*Client) UploadFilesAndWait added in v0.0.10 

func (c *Client) UploadFilesAndWait(
	ctx context.Context,
	prompts []Prompt,
	ignoreMimeType ...bool,
) (processedPrompts []Prompt, err error)

UploadFilesAndWait processes a slice of Prompts, handling file uploads for FilePrompt and BytesPrompt types. It waits for all uploaded files to become "ACTIVE".

For FilePrompt and BytesPrompt instances that require uploading:

  • FilePrompt instances will have their `data` field populated with the `*genai.FileData` (URI and MIME type) returned by the server after successful upload. Their `filename` field will be updated to the server-assigned unique name.
  • BytesPrompt instances are converted into FilePrompt instances after their content is uploaded as a file. The new FilePrompt will have its `filename` and `data` fields populated accordingly.

TextPrompt and URIPrompt instances are returned as is.

Parameters:

  • ctx: The context for the operation.
  • prompts: A slice of Prompt interfaces to process.

Returns:

  • processedPrompts: A new slice of Prompt interfaces. For uploaded files, FilePrompt instances are updated with server data, and BytesPrompt instances are converted to FilePrompt instances. Other prompt types remain unchanged.
  • err: An error if any part of the processing (like file upload or waiting) fails.

type ClientOption added in v0.3.0 

type ClientOption func(*Client)

ClientOption is a function type used to configure a new Client. It follows the functional options pattern.

func WithMaxRetryCount added in v0.3.0 

func WithMaxRetryCount(count uint) ClientOption

WithMaxRetryCount is a ClientOption that sets the default maximum retry count for retriable API errors (typically 5xx server errors).

func WithModel added in v0.3.0 

func WithModel(model string) ClientOption

WithModel is a ClientOption that sets the default model for the client. This model will be used for generation tasks unless overridden in specific function calls.

type EmbeddingTaskType added in v0.2.30 

type EmbeddingTaskType string

EmbeddingTaskType defines the specific task for which embeddings are being generated. This helps the model produce more relevant embeddings. See https://ai.google.dev/api/embeddings#v1beta.TaskType for details. 

const (
	EmbeddingTaskUnspecified        EmbeddingTaskType = "TASK_TYPE_UNSPECIFIED" // Default, unspecified task type.
	EmbeddingTaskRetrievalQuery     EmbeddingTaskType = "RETRIEVAL_QUERY"       // Embeddings for a query to be used in retrieval.
	EmbeddingTaskRetrievalDocument  EmbeddingTaskType = "RETRIEVAL_DOCUMENT"    // Embeddings for a document to be indexed for retrieval.
	EmbeddingTaskSemanticSimilarity EmbeddingTaskType = "SEMANTIC_SIMILARITY"   // Embeddings for semantic similarity tasks.
	EmbeddingTaskClassification     EmbeddingTaskType = "CLASSIFICATION"        // Embeddings for classification tasks.
	EmbeddingTaskClustering         EmbeddingTaskType = "CLUSTERING"            // Embeddings for clustering tasks.
	EmbeddingTaskQuestionAnswering  EmbeddingTaskType = "QUESTION_ANSWERING"    // Embeddings for question answering.
	EmbeddingTaskFactVerification   EmbeddingTaskType = "FACT_VERIFICATION"     // Embeddings for fact verification.
	EmbeddingTaskCodeRetrievalQuery EmbeddingTaskType = "CODE_RETRIEVAL_QUERY"  // Embeddings for code retrieval query.
)

EmbeddingTaskType constants represent the various tasks for which embeddings can be optimized.

type FilePrompt added in v0.2.0 

type FilePrompt struct {
	Filename string    // filename is the display name for the file, used during upload.
	Reader   io.Reader // reader provides the content of the file.

	// Data holds the URI and MIME type of the file after it has been uploaded
	// and the server has responded with the file's metadata.
	// This field is populated by processing functions like `client.processPromptToPartAndInfo`.
	// It is nil until the file is successfully processed and its URI obtained.
	Data *genai.FileData

	// When this data needs to be handled as a specific MIME type,
	// set this value then it will be forced to that type.
	ForcedMIMEType string
}

FilePrompt represents a prompt that involves a file to be uploaded. The file content is provided via an io.Reader. After processing (e.g., uploading via client.processPromptToPartAndInfo), the `data` field will be populated with the URI and MIME type of the uploaded file from the server.

func (FilePrompt) String added in v0.2.0 

func (p FilePrompt) String() string

String returns a string representation of the FilePrompt. If the file has been uploaded and `data` is populated, it includes the URI and MIME type.

func (FilePrompt) ToPart added in v0.2.0 

func (p FilePrompt) ToPart() genai.Part

ToPart converts the FilePrompt into a `genai.Part` using the FileData (URI and MIME type). This method relies on the `data` field being populated by a prior file upload step (e.g., within `client.processPromptToPartAndInfo`). If `p.data` is nil, it will result in a `genai.Part` with empty FileData, which may be invalid for API requests.

type FnConvertBytes added in v0.2.3 

type FnConvertBytes func(bytes []byte) ([]byte, string, error)

FnConvertBytes is a function type for converting file bytes. It takes a byte slice (original file content) and should return the converted byte slice, the new MIME type string, and an error if conversion fails. This is used by the Client's SetFileConverter method to handle custom file type conversions.

type FnSystemInstruction 

type FnSystemInstruction func() string

FnSystemInstruction is a function type that returns a string to be used as the system instruction. This allows for dynamic generation of system instructions if needed.

type FunctionCallHandler added in v0.3.11 

type FunctionCallHandler func(args map[string]any) (string, error)

FunctionCallHandler is a function type for handling function calls

type NumTokens 

type NumTokens struct {
	Cached   int32 // Number of tokens from cached content.
	Output   int32 // Number of tokens in the generated output (candidates).
	Input    int32 // Number of tokens in the input prompt.
	Thoughts int32 // Number of tokens used for model's internal "thoughts" (if applicable and requested).
	ToolUse  int32 // Number of tokens used for tool interactions (function calls, etc.).
	Total    int32 // Total number of tokens processed for the request.
}

NumTokens represents the breakdown of token usage for a generation request.

type Prompt added in v0.2.0 

type Prompt interface {
	// String returns a string representation of the prompt, useful for logging or debugging.
	String() string
	// ToPart converts the prompt into a `genai.Part`.
	// The implementation determines how the specific prompt type is transformed
	// (e.g., text to TextPart, file URI to FileDataPart).
	ToPart() genai.Part
}

Prompt is an interface representing different types of input that can be converted into a `genai.Part` for use in generative AI model requests. It standardizes how various input forms (text, file, URI, bytes) are processed.

func MCPCallToolResultToGeminiPrompts added in v0.3.12 

func MCPCallToolResultToGeminiPrompts(
	from *mcp.CallToolResult,
) (to []Prompt, err error)

MCPCallToolResultToGeminiPrompts converts given *mcp.CallToolResult to []Prompt.

func PromptFromBytes added in v0.2.1 

func PromptFromBytes(
	bytes []byte,
	forceMimeType ...string,
) Prompt

PromptFromBytes creates a new BytesPrompt from a byte slice. The MIME type is automatically detected from the byte content. It implements the Prompt interface. This version does not include a filename.

func PromptFromBytesWithName added in v0.3.0 

func PromptFromBytesWithName(
	bytes []byte,
	filename string,
	forceMimeType ...string,
) Prompt

PromptFromBytesWithName creates a new BytesPrompt from a byte slice with an associated filename. The MIME type is automatically detected from the byte content. It implements the Prompt interface.

func PromptFromFile added in v0.2.1 

func PromptFromFile(
	filename string,
	reader io.Reader,
	forceMimeType ...string,
) Prompt

PromptFromFile creates a new FilePrompt with the given display filename and an io.Reader for its content. It implements the Prompt interface.

func PromptFromText added in v0.2.1 

func PromptFromText(text string) Prompt

PromptFromText creates a new TextPrompt from the given text string. It implements the Prompt interface.

func PromptFromURI added in v0.2.6 

func PromptFromURI(uri, mimeType string) Prompt

PromptFromURI creates a new URIPrompt from the given URI string. It implements the Prompt interface.

type TextChunkOption added in v0.1.35 

type TextChunkOption struct {
	ChunkSize                uint   // ChunkSize is the desired maximum size of each text chunk in bytes.
	OverlappedSize           uint   // OverlappedSize specifies how many bytes from the end of the previous chunk should be included at the beginning of the next chunk.
	KeepBrokenUTF8Characters bool   // KeepBrokenUTF8Characters, if true, preserves potentially broken UTF-8 characters at chunk boundaries. If false (default), ToValidUTF8 is used to replace them.
	EllipsesText             string // EllipsesText is a string (e.g., "...") to append to the beginning of subsequent chunks and the end of chunks that are not the final part of the text.
}

TextChunkOption provides configuration for the ChunkText function.

type TextPrompt added in v0.2.0 

type TextPrompt struct {
	Text string // The actual text content of the prompt.
}

TextPrompt represents a simple text-based prompt.

func (TextPrompt) String added in v0.2.0 

func (p TextPrompt) String() string

String returns a string representation of the TextPrompt, showing the text content.

func (TextPrompt) ToPart added in v0.2.0 

func (p TextPrompt) ToPart() genai.Part

ToPart converts the TextPrompt into a `genai.Part` containing the text.

type URIPrompt added in v0.2.6 

type URIPrompt struct {
	URI      string // The URI of the file.
	MIMEType string
}

URIPrompt represents a prompt that uses a URI to point to file data (e.g., a gs:// URI for a file in Google Cloud Storage, or a publicly accessible HTTPS URI).

func (URIPrompt) String added in v0.2.6 

func (p URIPrompt) String() string

String returns a string representation of the URIPrompt.

func (URIPrompt) ToPart added in v0.2.6 

func (p URIPrompt) ToPart() genai.Part

ToPart converts the URIPrompt into a `genai.Part` using the FileData URI.

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.