xai

package module
v0.0.0-...-f97c3c1 Latest Latest
Warning

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

 Go to latest Published: Dec 29, 2025 License: Apache-2.0 Imports: 48 Imported by: 0

README

xAI Go Client

Overview

This package is a Go language port of the xai-org/xai-sdk-python. It provides a Go SDK for interacting with xAI's services using gRPC.

Project Structure

  • api/: Generated gRPC code from protocol buffers.
  • client.go: Main Client implementation.
  • chat.go: Chat API client.
  • models.go: Models API client.
  • files.go: Files API client (upload/download/list/delete, signed URLs, progress, batch).
  • image.go: Image API client.
  • tokenizer.go: Tokenizer API client.
  • collections.go: Collections/document management (management gRPC + data-plane search).
  • tools.go: Helpers for model/tool calling and search sources.

Usage

Installation
go get github.com/zchee/tumix/gollm/xai
Authentication

The SDK reads XAI_API_KEY by default. The management endpoints (collections) use XAI_MANAGEMENT_KEY when present.

You can override hosts, metadata, and timeouts via functional options such as WithAPIHost, WithManagementAPIHost, WithTimeout, and WithMetadata.

Example: Chat
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/zchee/tumix/gollm/xai"
)

func main() {
    ctx := context.Background()
    client, err := xai.NewClient(ctx, "") // uses XAI_API_KEY from the environment
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
    defer client.Close()

    chat := client.Chat.Create("grok-4-1-fast-reasoning", xai.WithMessages(xai.System("You are a helpful assistant.")))
    chat.Append(xai.User("Hello!"))

    resp, err := chat.Sample(ctx)
    if err != nil {
        log.Fatalf("Failed to get response: %v", err)
    }

    fmt.Printf("Response: %s\n", resp.Content())
}
Additional examples:
  • Files: client.Files.Upload(ctx, "./doc.pdf") uploads with chunked streaming; client.Files.Content streams bytes back.
  • Images: client.Image.Sample(ctx, "a cat in space", "grok-2-image-1212", xai.WithImageFormat(xai.ImageFormatBase64)).
  • Collections (requires management key): create/list/update collections and documents via client.Collections APIs.
  • Tools/Search: build server-side tools with WebSearchTool, XSearchTool, CodeExecutionTool, and search sources via helpers in search.go.

Development

Generating Protos
  • Public protos (the ones that exist in xai-proto): buf generate (uses buf.gen.yaml to pull https://github.com/xai-org/xai-proto.git).
  • Descriptor-only protos that ship inside the Python SDK (xai/api/v1/{collections,shared,types}.proto):
    • Install uv.
    • Run ./hack/gen-python-protos.py (uv shebang declares protobuf dependency).
      Requirements: git, protoc, protoc-gen-go, protoc-gen-go-grpc, protoc-gen-go-vtproto.
      The script clones xai-org/xai-sdk-python (default tag main, override with XAI_SDK_PYTHON_REF), extracts the descriptor set, and regenerates Go bindings with the same module/import layout used in this repo.
Building
go build ./...
Testing
go test ./...
Structured Outputs

Use WithJSONStruct[T] or WithJSONSchema to request JSON-formatted replies and ParseInto[T] / Response.DecodeJSON to decode them.

Telemetry

Configure OTLP exporting with InitOTLP(ctx, OTLPConfig{Endpoint: "collector:4318", Transport: xai.OTLPHTTP, Insecure: true}); default resource attrs include service.name=xai-sdk-go and your build version.

Tool calling caveat

The current chat proto does not include a tool_call_id on ROLE_TOOL messages, so tool results cannot be automatically threaded to a specific call. Until the proto is updated, include the tool call id in your own payload (e.g., JSON content {"tool_call_id":..., ...}) and handle correlation client-side. Helpers such as ToolCallArguments remain safe for parsing call inputs.

Documentation

Overview

Package xai is a Go language port of the xai-org/xai-sdk-python.

It provides a Go SDK for interacting with xAI services using gRPC.

Index

Examples

Constants

View Source 
const (
	// APIHost is the default host for the data plane API.
	APIHost = "api.x.ai:443"
	// ManagementAPIHost is the default host for the management API.
	ManagementAPIHost = "management-api.x.ai:443"
)

Variables

This section is empty.

Functions

func Assistant 

func Assistant(parts ...any) *xaipb.Message

Assistant creates an assistant message.

func AttachmentSearchTool 

func AttachmentSearchTool(limit int32) *xaipb.Tool

AttachmentSearchTool enables server-side attachment search.

func AuthStreamInterceptor 

func AuthStreamInterceptor(token string, md map[string]string) grpc.StreamClientInterceptor

func AuthUnaryInterceptor 

func AuthUnaryInterceptor(token string, md map[string]string) grpc.UnaryClientInterceptor

func BuildDialOptions 

func BuildDialOptions(opts *clientOptions, token string) []grpc.DialOption

BuildDialOptions builds gRPC dial options based on the provided client options and token.

func ChunkConfigChars 

func ChunkConfigChars(maxSize, overlap int32, stripWhitespace, injectName bool) *ragpb.ChunkConfiguration

ChunkConfigChars builds a character-based chunk configuration.

func ChunkConfigTokens 

func ChunkConfigTokens(maxTokens, overlapTokens int32, encoding string, stripWhitespace, injectName bool) *ragpb.ChunkConfiguration

ChunkConfigTokens builds a token-based chunk configuration.

func CodeExecutionTool 

func CodeExecutionTool() *xaipb.Tool

CodeExecutionTool enables server-side code execution.

func CollectionsSearchTool 

func CollectionsSearchTool(collectionIDs []string, limit int32) *xaipb.Tool

CollectionsSearchTool allows querying collections from agentic responses.

func CollectionsSearchToolIDs 

func CollectionsSearchToolIDs(limit int32, collectionIDs ...string) *xaipb.Tool

CollectionsSearchToolIDs is a convenience wrapper that accepts variadic IDs.

func DefaultClientOptions 

func DefaultClientOptions() *clientOptions

DefaultClientOptions returns the default client configuration.

func DocumentsSource 

func DocumentsSource(collectionIDs []string) *xaipb.DocumentsSource

DocumentsSource builds a documents source for semantic search over collections.

func FileContent 

func FileContent(fileID string) *xaipb.Content

FileContent references an uploaded file (id only).

func FileContentWithName 

func FileContentWithName(fileID, name string) *xaipb.Content

FileContentWithName references an uploaded file and provides a display name.

func GenAIContentsToMessages 

func GenAIContentsToMessages(system *genai.Content, contents []*genai.Content) ([]*xaipb.Message, error)

GenAIContentsToMessages converts a GenerateContent request payload into xAI chat messages. It maps system instruction (when present) and each content entry into the closest xAI shape, preserving roles and tool calling information. Unsupported parts return an error so callers can fail fast instead of silently dropping context.

func ImageContent 

func ImageContent(url string, detail xaipb.ImageDetail) *xaipb.Content

ImageContent creates an image content entry with optional detail.

func IndexConfig 

func IndexConfig(modelName string) *ragpb.IndexConfiguration

IndexConfig builds an IndexConfiguration with the provided model name.

func InitOTLP 

func InitOTLP(ctx context.Context, cfg OTLPConfig) (*trace.TracerProvider, error)

InitOTLP configures a global OTLP trace exporter using the provided config. Defaults: transport http, secure by default.

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable reports whether an error is retryable (currently [codes.Unavailable] or [codes.DeadlineExceeded]).

This mirrors the retryable set used in the client service config.

func MCPTool 

func MCPTool(serverURL, serverLabel, serverDescription string, allowedToolNames []string, authorization string, extraHeaders map[string]string) *xaipb.Tool

MCPTool connects to a remote MCP server.

func MustTool 

func MustTool(name, description string, parameters any) *xaipb.Tool

MustTool is a convenience that panics on error; useful in init paths.

func NewsSource 

func NewsSource(country string, excludedWebsites []string, safeSearch bool) *xaipb.Source

NewsSource builds a news search source.

func RSSSource 

func RSSSource(links []string) *xaipb.Source

RSSSource builds an RSS feed search source.

func RequiredTool 

func RequiredTool(name string) *xaipb.ToolChoice

RequiredTool creates a tool choice that forces invocation of the given tool name.

func SDKVersion 

func SDKVersion() string

SDKVersion returns the detected SDK version string (without the go/ prefix).

func System 

func System(parts ...any) *xaipb.Message

System creates a system message.

func TextContent 

func TextContent(text string) *xaipb.Content

TextContent wraps plain text into a Content message.

func TimeoutStreamInterceptor 

func TimeoutStreamInterceptor(timeout time.Duration) grpc.StreamClientInterceptor

func TimeoutUnaryInterceptor 

func TimeoutUnaryInterceptor(timeout time.Duration) grpc.UnaryClientInterceptor

func Tool 

func Tool(name, description string, parameters any) (*xaipb.Tool, error)

Tool builds a function-calling tool definition.

func ToolCallArguments 

func ToolCallArguments(tc *xaipb.ToolCall, out any) error

ToolCallArguments unmarshals a tool call's arguments into the provided destination. Returns an error if the tool call has no function payload or JSON is invalid.

Example

ExampleToolCallArguments demonstrates decoding tool call arguments locally. 

tc := &xaipb.ToolCall{
	Tool: &xaipb.ToolCall_Function{
		Function: &xaipb.FunctionCall{
			Name:      "sum",
			Arguments: `{"a":1,"b":2}`,
		},
	},
}
var args struct {
	A int `json:"a"`
	B int `json:"b"`
}
if err := ToolCallArguments(tc, &args); err != nil {
	log.Fatal(err)
}
fmt.Printf("%d %d\n", args.A, args.B)

Output:

1 2

func ToolCallJSON 

func ToolCallJSON(tc *xaipb.ToolCall) string

ToolCallJSON returns the raw JSON arguments string (empty if absent).

func ToolResult 

func ToolResult(result string) *xaipb.Message

ToolResult creates a tool result message.

func User 

func User(parts ...any) *xaipb.Message

User creates a user message with text or content parts.

func ValidateOrder 

func ValidateOrder(order Order) error

ValidateOrder ensures incoming order strings match expected values.

func WebSearchTool 

func WebSearchTool(excludedDomains, allowedDomains []string, enableImageUnderstanding bool) *xaipb.Tool

WebSearchTool defines a server-side web search tool.

func WebSource 

func WebSource(country string, excludedWebsites, allowedWebsites []string, safeSearch bool) *xaipb.Source

WebSource builds a web search source.

func WithTeamID 

func WithTeamID(teamID string) collectionsOption

WithTeamID sets an explicit team id on management requests.

func WrapError 

func WrapError(err error) error

WrapError returns an Error if err is a gRPC status error; otherwise returns err unchanged.

func XSearchTool 

func XSearchTool(fromDate, toDate *time.Time, allowedHandles, excludedHandles []string, enableImageUnderstanding, enableVideoUnderstanding bool) *xaipb.Tool

XSearchTool defines a server-side X (Twitter) search tool.

func XSource 

func XSource(includedHandles, excludedHandles []string, favoriteCount, viewCount int32) *xaipb.Source

XSource builds an X (Twitter) search source.

Types

type AuthClient 

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

AuthClient provides access to Auth RPCs.

func (*AuthClient) GetAPIKeyInfo 

func (c *AuthClient) GetAPIKeyInfo(ctx context.Context, opts ...grpc.CallOption) (*xaipb.ApiKey, error)

GetAPIKeyInfo returns metadata for the current API key.

type BillingClient 

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

BillingClient handles billing operations.

func (*BillingClient) AnalyzeBillingItems 

func (c *BillingClient) AnalyzeBillingItems(ctx context.Context, teamID string, analyticsReq *analyticspb.AnalyticsRequest) (*analyticspb.AnalyticsResponse, error)

AnalyzeBillingItems gets historical usage of the API over a time period, aggregated by fields.

func (*BillingClient) GetAmountToPay 

func (c *BillingClient) GetAmountToPay(ctx context.Context, teamID string) (*managementpb.GetAmountToPayResp, error)

GetAmountToPay previews the amount to pay for postpaid usage in the current billing period.

func (*BillingClient) GetBillingInfo 

func (c *BillingClient) GetBillingInfo(ctx context.Context, teamID string) (*billingpb.BillingInfo, error)

GetBillingInfo gets billing information of the team with given team ID.

func (*BillingClient) GetSpendingLimits 

func (c *BillingClient) GetSpendingLimits(ctx context.Context, teamID string) (*managementpb.GetSpendingLimitsResp, error)

GetSpendingLimits gets the postpaid monthly spending limits.

func (*BillingClient) ListInvoices 

func (c *BillingClient) ListInvoices(ctx context.Context, req *managementpb.ListInvoicesReq) (*managementpb.ListInvoicesResp, error)

ListInvoices lists invoices that belong to a team.

func (*BillingClient) ListPaymentMethods 

func (c *BillingClient) ListPaymentMethods(ctx context.Context, teamID string) (*managementpb.ListPaymentMethodsResp, error)

ListPaymentMethods lists payment methods of a team.

func (*BillingClient) ListPrepaidBalanceChanges 

func (c *BillingClient) ListPrepaidBalanceChanges(ctx context.Context, teamID string) (*managementpb.ListPrepaidBalanceChangesResp, error)

ListPrepaidBalanceChanges lists the prepaid credit balance and balance changes of a team.

func (*BillingClient) SetBillingInfo 

func (c *BillingClient) SetBillingInfo(ctx context.Context, teamID string, info *billingpb.BillingInfo) (*managementpb.SetBillingInfoResp, error)

SetBillingInfo sets billing information of a team.

func (*BillingClient) SetDefaultPaymentMethod 

func (c *BillingClient) SetDefaultPaymentMethod(ctx context.Context, teamID, paymentMethodID string) (*managementpb.SetDefaultPaymentMethodResp, error)

SetDefaultPaymentMethod sets default payment method to an existing payment method on file.

func (*BillingClient) SetSoftSpendingLimit 

func (c *BillingClient) SetSoftSpendingLimit(ctx context.Context, teamID string, limit *billingpb.Cent) (*managementpb.SetSoftSpendingLimitResp, error)

SetSoftSpendingLimit sets the postpaid monthly spending limit of a team.

func (*BillingClient) TopUpOrGetExistingPendingChange 

func (c *BillingClient) TopUpOrGetExistingPendingChange(ctx context.Context, teamID string, amount *billingpb.Cent) (*managementpb.TopUpOrGetExistingPendingChangeResp, error)

TopUpOrGetExistingPendingChange tops up prepaid credit using the default payment method.

type ChatClient 

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

ChatClient handles chat operations.

func (*ChatClient) Create 

func (c *ChatClient) Create(model string, opts ...ChatOption) *ChatSession

Create initializes a new chat session for the specified model.

func (*ChatClient) DeleteStoredCompletion 

func (c *ChatClient) DeleteStoredCompletion(ctx context.Context, responseID string) error

DeleteStoredCompletion deletes a stored response using the response ID.

func (*ChatClient) GetDeferredCompletion 

func (c *ChatClient) GetDeferredCompletion(ctx context.Context, requestID string) (*xaipb.GetDeferredCompletionResponse, error)

GetDeferredCompletion gets the result of a deferred completion.

func (*ChatClient) GetStoredCompletion 

func (c *ChatClient) GetStoredCompletion(ctx context.Context, responseID string) (*xaipb.GetChatCompletionResponse, error)

GetStoredCompletion retrieves a stored response using the response ID.

func (*ChatClient) StartDeferredCompletion 

func (c *ChatClient) StartDeferredCompletion(ctx context.Context, req *xaipb.GetCompletionsRequest) (*xaipb.StartDeferredResponse, error)

StartDeferredCompletion starts sampling of the model and immediately returns a response containing a request id.

type ChatOption 

type ChatOption func(*xaipb.GetCompletionsRequest, *ChatSession)

ChatOption customizes a chat request before execution.

func WithConversationID 

func WithConversationID(id string) ChatOption

WithConversationID stores an optional conversation identifier (client-side only).

func WithEncryptedContent 

func WithEncryptedContent(enabled bool) ChatOption

WithEncryptedContent enables encrypted content in the response.

func WithFrequencyPenalty 

func WithFrequencyPenalty(v float32) ChatOption

WithFrequencyPenalty sets the frequency penalty.

func WithJSONSchema 

func WithJSONSchema(schema string) ChatOption

WithJSONSchema sets a JSON schema string for structured outputs.

func WithJSONStruct 

func WithJSONStruct[T any]() ChatOption

WithJSONStruct derives a JSON Schema from the generic type T (pointer recommended) for structured outputs.

Example

ExampleWithJSONStruct shows how to request structured output without hitting the network. 

req := &xaipb.GetCompletionsRequest{
	Model: "grok-4",
}
WithJSONStruct[struct {
	Name string `json:"name"`
}]()(req, nil)

if req.GetResponseFormat() != nil && req.ResponseFormat.Schema != nil {
	fmt.Println("schema set")
}

Output:

schema set

func WithLogprobs 

func WithLogprobs(enabled bool) ChatOption

WithLogprobs enables log probabilities return.

func WithMaxTokens 

func WithMaxTokens(maxToken int32) ChatOption

WithMaxTokens sets the maximum number of tokens to generate.

func WithMaxTurns 

func WithMaxTurns(maxTurns int32) ChatOption

WithMaxTurns sets the maximum number of turns for the conversation.

func WithMessages 

func WithMessages(msgs ...*xaipb.Message) ChatOption

WithMessages sets initial messages.

func WithParallelToolCalls 

func WithParallelToolCalls(enabled bool) ChatOption

WithParallelToolCalls enables or disables parallel tool calls.

func WithPresencePenalty 

func WithPresencePenalty(v float32) ChatOption

WithPresencePenalty sets the presence penalty.

func WithPreviousResponse 

func WithPreviousResponse(id string) ChatOption

WithPreviousResponse sets the previous response ID for context.

func WithReasoningEffort 

func WithReasoningEffort(effort xaipb.ReasoningEffort) ChatOption

WithReasoningEffort sets the reasoning effort level.

func WithResponseFormat 

func WithResponseFormat(format *xaipb.ResponseFormat) ChatOption

WithResponseFormat sets the desired response format (e.g. JSON).

func WithSearch 

func WithSearch(params SearchParameters) ChatOption

WithSearch configures search using the helper struct.

func WithSearchParameters 

func WithSearchParameters(params *xaipb.SearchParameters) ChatOption

WithSearchParameters sets the search parameters for the request.

func WithSeed 

func WithSeed(seed int32) ChatOption

WithSeed sets the random seed for deterministic generation.

func WithStop 

func WithStop(stop ...string) ChatOption

WithStop sets the stop sequences.

func WithStoreMessages 

func WithStoreMessages(store bool) ChatOption

WithStoreMessages enables message storage.

func WithTemperature 

func WithTemperature(t float32) ChatOption

WithTemperature sets the sampling temperature.

func WithToolChoice 

func WithToolChoice(choice *xaipb.ToolChoice) ChatOption

WithToolChoice sets the tool choice strategy.

func WithTools 

func WithTools(tools ...*xaipb.Tool) ChatOption

WithTools sets the tools available to the model.

func WithTopLogprobs 

func WithTopLogprobs(v int32) ChatOption

WithTopLogprobs sets the number of top log probabilities to return.

func WithTopP 

func WithTopP(p float32) ChatOption

WithTopP sets the nucleus sampling probability.

func WithUser 

func WithUser(user string) ChatOption

WithUser sets the user identifier for the request.

type ChatSession 

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

ChatSession represents an active chat session.

func (*ChatSession) Append 

func (s *ChatSession) Append(message any) *ChatSession

Append adds a message or response to the chat session.

func (*ChatSession) AppendToolResultJSON 

func (s *ChatSession) AppendToolResultJSON(toolCallID string, result any) *ChatSession

AppendToolResultJSON appends a tool result message with JSON payload (string or marshaled value). toolCallID is optional; if empty, it is omitted because the proto does not carry it.

func (*ChatSession) Completion 

func (s *ChatSession) Completion(ctx context.Context) (*Response, error)

Completion sends the chat request and returns the first response.

func (*ChatSession) CompletionBatch 

func (s *ChatSession) CompletionBatch(ctx context.Context, n int32) ([]*Response, error)

CompletionBatch requests n responses in a single call.

func (*ChatSession) Defer 

func (s *ChatSession) Defer(ctx context.Context, timeout, interval time.Duration) (*Response, error)

Defer executes the request using deferred polling.

func (*ChatSession) DeferBatch 

func (s *ChatSession) DeferBatch(ctx context.Context, n int32, timeout, interval time.Duration) ([]*Response, error)

DeferBatch executes the request using deferred polling and returns n responses.

func (*ChatSession) Messages 

func (s *ChatSession) Messages() []*xaipb.Message

Messages returns the current conversation history.

func (*ChatSession) Parse 

func (s *ChatSession) Parse(ctx context.Context, out any) (*Response, error)

Parse sets response_format to a JSON schema derived from the provided sample value and decodes into it. Pass a pointer to a struct value to populate it.

func (*ChatSession) Stream 

func (s *ChatSession) Stream(ctx context.Context) (*ChatStream, error)

Stream returns a streaming iterator for a single response.

func (*ChatSession) StreamBatch 

func (s *ChatSession) StreamBatch(ctx context.Context, n int32) (*ChatStream, error)

StreamBatch returns a streaming iterator for multiple responses.

type ChatStream 

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

ChatStream wraps the streaming completion response.

func (*ChatStream) Close 

func (s *ChatStream) Close() error

Close closes the underlying stream and ends the span if present. It is safe to call multiple times.

func (*ChatStream) Recv 

func (s *ChatStream) Recv() iter.Seq2[*Response, error]

Recv returns an iterator over the aggregated response as it streams in. Iterate with: 

for resp, err := range stream.Recv() { ... }

func (*ChatStream) Response 

func (s *ChatStream) Response() *Response

Response returns the aggregated response built from streamed chunks.

type Chunk 

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

Chunk wraps GetChatCompletionChunk with helpers.

func (*Chunk) Content 

func (c *Chunk) Content() string

Content concatenates chunk content for the tracked index (or all when multi-output).

func (*Chunk) ReasoningContent 

func (c *Chunk) ReasoningContent() string

ReasoningContent concatenates reasoning content for tracked outputs.

func (*Chunk) ToolCalls 

func (c *Chunk) ToolCalls() []*xaipb.ToolCall

ToolCalls returns tool calls for this chunk.

type Client 

type Client struct {
	Auth        *AuthClient
	Billing     *BillingClient
	Chat        *ChatClient
	Collections *CollectionsClient
	Files       *FilesClient
	Embed       *EmbedClient
	Image       *ImageClient
	Models      *ModelsClient
	Sampler     *SamplerClient
	Tokenizer   *TokenizerClient
	// contains filtered or unexported fields
}

Client aggregates all xAI service clients.

func NewClient 

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

NewClient creates a new xAI API client with optional configuration.

func (*Client) Close 

func (c *Client) Close() error

Close closes all underlying connections.

type ClientOption 

type ClientOption func(*clientOptions)

ClientOption configures the xAI client.

func WithAPIConn 

func WithAPIConn(conn *grpc.ClientConn) ClientOption

WithAPIConn injects a pre-built gRPC connection for the data plane.

func WithAPIHost 

func WithAPIHost(host string) ClientOption

WithAPIHost overrides the default API host.

func WithAPIKey 

func WithAPIKey(key string) ClientOption

WithAPIKey sets the API key used for the data plane.

func WithDialOptions 

func WithDialOptions(opts ...grpc.DialOption) ClientOption

WithDialOptions appends grpc.DialOptions to the client configuration.

func WithInsecure 

func WithInsecure() ClientOption

WithInsecure enables plaintext transport (useful for local development).

func WithManagementAPIHost 

func WithManagementAPIHost(host string) ClientOption

WithManagementAPIHost overrides the default management API host.

func WithManagementAPIKey 

func WithManagementAPIKey(key string) ClientOption

WithManagementAPIKey sets the management API key used for collection administration.

func WithManagementConn 

func WithManagementConn(conn *grpc.ClientConn) ClientOption

WithManagementConn injects a pre-built gRPC connection for the management plane.

func WithMetadata 

func WithMetadata(md map[string]string) ClientOption

WithMetadata attaches static metadata to every RPC.

func WithSDKVersion 

func WithSDKVersion(version string) ClientOption

WithSDKVersion overrides the reported SDK version (xai-sdk-version metadata value). Useful for integration tests or custom builds.

func WithTimeout 

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets the default RPC timeout applied when no deadline is present on the context.

type CollectionSortBy 

type CollectionSortBy string

CollectionSortBy defines collection sort fields. 

const (
	CollectionSortByName CollectionSortBy = "name"
	CollectionSortByAge  CollectionSortBy = "age"
)

type CollectionsClient 

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

CollectionsClient provides gRPC access to collections/documents.

func NewCollectionsClient 

func NewCollectionsClient(apiConn, managementConn *grpc.ClientConn) *CollectionsClient

NewCollectionsClient builds a client. managementConn is required for collection mutations.

func (*CollectionsClient) AddExistingDocument 

func (c *CollectionsClient) AddExistingDocument(ctx context.Context, collectionID, fileID string, fields map[string]string, opts ...collectionsOption) error

AddExistingDocument attaches an existing file to a collection.

func (*CollectionsClient) BatchGetDocuments 

func (c *CollectionsClient) BatchGetDocuments(ctx context.Context, collectionID string, fileIDs []string, opts ...collectionsOption) (*collectionspb.BatchGetDocumentsResponse, error)

BatchGetDocuments fetches metadata for multiple documents.

func (*CollectionsClient) CollectionsSearchTool 

func (c *CollectionsClient) CollectionsSearchTool(collectionIDs []string, limit int32) *xaipb.Tool

CollectionsSearchTool builds a server-side collections search tool definition for chat requests. This mirrors the helper in tools.go but keeps the collections surface discoverable in one place.

func (*CollectionsClient) Create 

func (c *CollectionsClient) Create(ctx context.Context, name, modelName string, chunkCfg *ragpb.ChunkConfiguration, opts ...collectionsOption) (*collectionspb.CollectionMetadata, error)

Create makes a new collection.

func (*CollectionsClient) Delete 

func (c *CollectionsClient) Delete(ctx context.Context, collectionID string, opts ...collectionsOption) error

Delete removes a collection.

func (*CollectionsClient) Get 

func (c *CollectionsClient) Get(ctx context.Context, collectionID string, opts ...collectionsOption) (*collectionspb.CollectionMetadata, error)

Get returns collection metadata.

func (*CollectionsClient) GetDocument 

func (c *CollectionsClient) GetDocument(ctx context.Context, collectionID, fileID string, opts ...collectionsOption) (*collectionspb.DocumentMetadata, error)

GetDocument returns metadata for a file within a collection.

func (*CollectionsClient) List 

func (c *CollectionsClient) List(ctx context.Context, limit int32, order Order, sortBy CollectionSortBy, paginationToken string, opts ...collectionsOption) (*collectionspb.ListCollectionsResponse, error)

List collections with optional ordering and pagination.

func (*CollectionsClient) ListDocuments 

func (c *CollectionsClient) ListDocuments(ctx context.Context, collectionID string, limit int32, order Order, sortBy DocumentSortBy, paginationToken string, opts ...collectionsOption) (*collectionspb.ListDocumentsResponse, error)

ListDocuments returns documents within a collection.

func (*CollectionsClient) ReindexDocument 

func (c *CollectionsClient) ReindexDocument(ctx context.Context, collectionID, fileID string, opts ...collectionsOption) error

ReindexDocument reprocesses a document after config changes.

func (*CollectionsClient) RemoveDocument 

func (c *CollectionsClient) RemoveDocument(ctx context.Context, collectionID, fileID string, opts ...collectionsOption) error

RemoveDocument detaches a document from a collection.

func (*CollectionsClient) Search 

func (c *CollectionsClient) Search(ctx context.Context, query string, collectionIDs []string, opts ...DocumentSearchOption) (*xaipb.SearchResponse, error)

Search performs semantic search over collections via the Documents service (data plane).

func (*CollectionsClient) Update 

func (c *CollectionsClient) Update(ctx context.Context, collectionID, name string, chunkCfg *ragpb.ChunkConfiguration, opts ...collectionsOption) (*collectionspb.CollectionMetadata, error)

Update changes name and/or chunk configuration.

func (*CollectionsClient) UpdateDocument 

func (c *CollectionsClient) UpdateDocument(ctx context.Context, collectionID, fileID, name string, data []byte, contentType string, fields map[string]string, opts ...collectionsOption) (*collectionspb.DocumentMetadata, error)

UpdateDocument updates a document's data/metadata.

func (*CollectionsClient) UploadDocument 

func (c *CollectionsClient) UploadDocument(ctx context.Context, collectionID, name string, data []byte, contentType string, fields map[string]string, opts ...collectionsOption) (*collectionspb.DocumentMetadata, error)

UploadDocument uploads raw bytes into a collection.

type DocumentSearchOption 

type DocumentSearchOption func(*documentSearchRequest)

DocumentSearchOption customizes document search requests.

func WithRankingMetric 

func WithRankingMetric(metric xaipb.RankingMetric) DocumentSearchOption

WithRankingMetric sets the ranking metric for document search.

func WithSearchLimit 

func WithSearchLimit(limit int32) DocumentSearchOption

WithSearchLimit sets the maximum number of results returned.

type DocumentSortBy 

type DocumentSortBy string

DocumentSortBy defines document sort fields. 

const (
	DocumentSortByName DocumentSortBy = "name"
	DocumentSortByAge  DocumentSortBy = "age"
	DocumentSortBySize DocumentSortBy = "size"
)

type EmbedClient 

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

EmbedClient provides access to the Embeddings service.

func (*EmbedClient) Create 

func (c *EmbedClient) Create(ctx context.Context, req *xaipb.EmbedRequest) (*xaipb.EmbedResponse, error)

Create generates embeddings for the provided inputs.

func (*EmbedClient) CreateStrings 

func (c *EmbedClient) CreateStrings(ctx context.Context, model string, texts []string) (*xaipb.EmbedResponse, error)

CreateStrings generates embeddings for a list of text strings.

type Error 

type Error struct {
	Code    codes.Code
	Message string
	Details []any
}

Error provides structured access to gRPC status errors returned by xAI services.

func AsError 

func AsError(err error) (*Error, bool)

AsError is a helper for errors.As.

func ParseError 

func ParseError(err error) (*Error, bool)

ParseError converts a gRPC status error into Error if possible.

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface.

func (*Error) GRPCStatus 

func (e *Error) GRPCStatus() *status.Status

GRPCStatus builds a status.Status from the structured error for interoperability.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap enables errors.Is and errors.As to reach the underlying status.

type FileOption 

type FileOption func(*fileUploadConfig)

FileOption customizes upload behavior.

func WithFilename 

func WithFilename(name string) FileOption

WithFilename overrides the filename used for non-path uploads (e.g. bytes, readers).

func WithProgress 

func WithProgress(fn ProgressFunc) FileOption

WithProgress registers a progress callback invoked after each chunk is sent.

type FileSortBy 

type FileSortBy string

FileSortBy controls sorting in List. 

const (
	FileSortByCreatedAt FileSortBy = "created_at"
	FileSortByFilename  FileSortBy = "filename"
	FileSortBySize      FileSortBy = "size"
)

type FilesClient 

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

FilesClient wraps the Files service.

func (*FilesClient) BatchUpload 

func (c *FilesClient) BatchUpload(ctx context.Context, paths []string, concurrency int, progress ProgressFunc) ([]*xaipb.File, []error)

BatchUpload uploads multiple files concurrently. Sources must be paths. Results are returned in index order; errors are stored per entry.

func (*FilesClient) Content 

func (c *FilesClient) Content(ctx context.Context, fileID string) ([]byte, error)

Content downloads the full file content.

func (*FilesClient) Delete 

func (c *FilesClient) Delete(ctx context.Context, fileID string) (*xaipb.DeleteFileResponse, error)

Delete removes a file by ID.

func (*FilesClient) Get 

func (c *FilesClient) Get(ctx context.Context, fileID string) (*xaipb.File, error)

Get retrieves metadata for a file.

func (*FilesClient) List 

func (c *FilesClient) List(ctx context.Context, limit int32, order Order, sortBy FileSortBy, paginationToken string) (*xaipb.ListFilesResponse, error)

List returns file metadata.

func (*FilesClient) URL 

func (c *FilesClient) URL(ctx context.Context, fileID string) (string, error)

URL retrieves a signed URL for file download when available.

func (*FilesClient) Upload 

func (c *FilesClient) Upload(ctx context.Context, src any, opts ...FileOption) (*xaipb.File, error)

Upload sends a file using the client-streaming UploadFile RPC.

Supported `src`:

  • string: path on disk
  • []byte: raw data (requires WithFilename)
  • io.Reader: streaming reader (requires WithFilename; total size optional)

type ImageClient 

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

ImageClient wraps the Image service.

func (*ImageClient) Sample 

func (c *ImageClient) Sample(ctx context.Context, prompt, model string, opts ...ImageOption) (*ImageResponse, error)

Sample generates a single image.

func (*ImageClient) SampleBatch 

func (c *ImageClient) SampleBatch(ctx context.Context, prompt, model string, n int32, opts ...ImageOption) ([]*ImageResponse, error)

SampleBatch generates n images.

type ImageFormat 

type ImageFormat string

ImageFormat selects the image response format. 

const (
	// ImageFormatURL returns the image as a URL.
	ImageFormatURL ImageFormat = "url"
	// ImageFormatBase64 returns the image as a base64-encoded string.
	ImageFormatBase64 ImageFormat = "base64"
)

type ImageOption 

type ImageOption func(*xaipb.GenerateImageRequest)

ImageOption customizes image generation requests.

func WithImageFormat 

func WithImageFormat(format ImageFormat) ImageOption

WithImageFormat sets the desired return format.

func WithImageUser 

func WithImageUser(user string) ImageOption

WithImageUser sets the end-user id.

type ImageResponse 

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

ImageResponse provides helpers around GenerateImageResponse.

func (*ImageResponse) Base64 

func (r *ImageResponse) Base64() (string, error)

Base64 returns the base64 representation if present.

func (*ImageResponse) Data 

func (r *ImageResponse) Data(ctx context.Context) ([]byte, error)

Data returns the raw bytes of the image, downloading if needed.

func (*ImageResponse) Prompt 

func (r *ImageResponse) Prompt() string

Prompt returns the prompt actually used to generate the image.

func (*ImageResponse) URL 

func (r *ImageResponse) URL() (string, error)

URL returns the image URL if present.

type ModelsClient 

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

ModelsClient provides access to the Models service.

func (*ModelsClient) GetEmbeddingModel 

func (c *ModelsClient) GetEmbeddingModel(ctx context.Context, name string) (*xaipb.EmbeddingModel, error)

GetEmbeddingModel retrieves information about a specific embedding model.

func (*ModelsClient) GetImageGenerationModel 

func (c *ModelsClient) GetImageGenerationModel(ctx context.Context, name string) (*xaipb.ImageGenerationModel, error)

GetImageGenerationModel retrieves information about a specific image generation model.

func (*ModelsClient) GetLanguageModel 

func (c *ModelsClient) GetLanguageModel(ctx context.Context, name string) (*xaipb.LanguageModel, error)

GetLanguageModel retrieves information about a specific language model.

func (*ModelsClient) ListEmbeddingModels 

func (c *ModelsClient) ListEmbeddingModels(ctx context.Context) (*xaipb.ListEmbeddingModelsResponse, error)

ListEmbeddingModels lists available embedding models.

func (*ModelsClient) ListImageGenerationModels 

func (c *ModelsClient) ListImageGenerationModels(ctx context.Context) (*xaipb.ListImageGenerationModelsResponse, error)

ListImageGenerationModels lists available image generation models.

func (*ModelsClient) ListLanguageModels 

func (c *ModelsClient) ListLanguageModels(ctx context.Context) (*xaipb.ListLanguageModelsResponse, error)

ListLanguageModels lists available language models.

type OTLPConfig 

type OTLPConfig struct {
	Endpoint    string
	Headers     map[string]string
	Insecure    bool // default secure (false)
	Transport   OTLPTransport
	Resource    map[string]string
	Compression string
}

OTLPConfig mirrors the Python telemetry setup knobs.

type OTLPTransport 

type OTLPTransport string

OTLPTransport selects HTTP or gRPC exporter. 

const (
	OTLPHTTP OTLPTransport = "http"
	OTLPGRPC OTLPTransport = "grpc"
)

type Order 

type Order string

Order defines sort order for collections/documents/files. 

const (
	OrderAscending  Order = "asc"
	OrderDescending Order = "desc"
)

type ProgressFunc 

type ProgressFunc func(uploaded, total int64)

ProgressFunc mirrors the Python progress callback signature (uploaded, total).

type Response 

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

Response wraps GetChatCompletionResponse with convenience accessors.

func ParseInto 

func ParseInto[T any](ctx context.Context, s *ChatSession) (*Response, *T, error)

ParseInto is a generic convenience for structured outputs into type T.

func (*Response) Citations 

func (r *Response) Citations() []string

Citations returns any citations returned by the model.

func (*Response) Content 

func (r *Response) Content() string

Content returns the content string for the selected output(s).

func (*Response) DecodeJSON 

func (r *Response) DecodeJSON(out any) error

DecodeJSON unmarshals the response content into the provided destination. Useful when using structured outputs or JSON response_format.

func (*Response) EncryptedContent 

func (r *Response) EncryptedContent() string

EncryptedContent returns encrypted reasoning content when present.

func (*Response) FinishReason 

func (r *Response) FinishReason() string

FinishReason returns the finish reason string.

func (*Response) Proto 

func (r *Response) Proto() *xaipb.GetChatCompletionResponse

Proto returns the underlying protobuf message (materializing buffered chunks).

func (*Response) ReasoningContent 

func (r *Response) ReasoningContent() string

ReasoningContent returns any reasoning trace text.

func (*Response) Role 

func (r *Response) Role() string

Role returns the assistant role string.

func (*Response) SystemFingerprint 

func (r *Response) SystemFingerprint() string

SystemFingerprint returns system fingerprint.

func (*Response) ToolCalls 

func (r *Response) ToolCalls() []*xaipb.ToolCall

ToolCalls returns tool calls from all assistant outputs.

func (*Response) Usage 

func (r *Response) Usage() *xaipb.SamplingUsage

Usage returns token usage.

type SamplerClient 

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

SamplerClient exposes the Sample service for low-level text sampling.

func (*SamplerClient) SampleText 

func (c *SamplerClient) SampleText(ctx context.Context, req *xaipb.SampleTextRequest) (*xaipb.SampleTextResponse, error)

SampleText performs a unary sampling request.

func (*SamplerClient) SampleTextStreaming 

func (c *SamplerClient) SampleTextStreaming(ctx context.Context, req *xaipb.SampleTextRequest) (xaipb.Sample_SampleTextStreamingClient, error)

SampleTextStreaming opens a server-streaming sampling request.

type SearchMode 

type SearchMode string

SearchMode controls when the model should perform search. 

const (
	// SearchModeAuto lets the model decide whether to search.
	SearchModeAuto SearchMode = "auto"
	// SearchModeOn forces the model to search.
	SearchModeOn SearchMode = "on"
	// SearchModeOff disables search.
	SearchModeOff SearchMode = "off"
)

type SearchParameters 

type SearchParameters struct {
	Sources          []*xaipb.Source
	Mode             SearchMode
	FromDate         *time.Time
	ToDate           *time.Time
	ReturnCitations  bool
	MaxSearchResults int32
}

SearchParameters mirrors the Python SDK configuration for search.

func (SearchParameters) Proto 

func (p SearchParameters) Proto() *xaipb.SearchParameters

Proto converts the struct into the protobuf message.

type TokenizerClient 

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

TokenizerClient provides access to the Tokenizer service.

func (*TokenizerClient) Tokenize 

func (c *TokenizerClient) Tokenize(ctx context.Context, text, model string) (*xaipb.TokenizeTextResponse, error)

Tokenize converts text into tokens using the specified model.

func (*TokenizerClient) TokenizeText 

func (c *TokenizerClient) TokenizeText(ctx context.Context, text, model string) (*xaipb.TokenizeTextResponse, error)

TokenizeText is an alias for Tokenize for parity with the Python SDK.

Source Files

View all Source files

Directories

Path Synopsis
api
v1
v1/collectionspb
v1/ragpb
v1/sharedpb
internal
grpccodec
Package grpccodec provides a gRPC codec that uses vtproto for serialization.
 Package grpccodec provides a gRPC codec that uses vtproto for serialization.
management_api
v1
shared
analytics
billing

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.