vxai

vxai is a V module that provides support for xAI API

Features

• Simple interface for interacting with xAI API
• Basics tests that can be ran by providing your own API key

Installation

To use vxai in your V project, you can install it via VPM:

v install ismyhc.vxai

Or clone the repository:

git clone https://github.com/ismyhc/vxai.git
cd vxai
v install

Usage

Take a look at the tests and the docs for more information on how to use vxai.

Todo

• Add more tests
• Add more documentation
• Add more examples
• Add streaming support.

License

This project is licensed under the MIT License

Contact

If you have any questions or feedback, please open an issue on this GitHub repository.

fn get_api_key_from_env(env string) !string

get_api_key_from_env retrieves an API key from the specified environment variable.

Parameters:- env: The name of the environment variable containing the API key.

Returns:- The API key as a string if the environment variable is set.

• An error if the environment variable is not set or is empty.

fn ChatCompletionInput.new(messages []ChatCompletionMessage, model string) ChatCompletionInput

ChatCompletionInput.new creates a new ChatCompletionInput with the given messages and model.

Parameters:- messages: A list of input messages defining the conversation context.

• model: The name of the model to use for the completion.

Returns:- A ChatCompletionInput instance with the specified parameters.

fn CompletionInput.new(prompt string, model string) CompletionInput

CompletionInput.new creates a new CompletionInput instance with the given prompt and model.

Parameters:- prompt: The input text to generate a completion for.

• model: The name of the model to use for generating the completion.

Returns:- A new CompletionInput instance.

fn XAIClient.new(p XAIClientParams) XAIClient

new creates a new instance of the XAIClient using the provided parameters.

struct APIKeyInfo {
pub:
	// acls is a list of access control rules associated with the API key.
	// Examples include "api-key:model:*" or "api-key:endpoint:*".
	acls []string

	// api_key_blocked indicates whether the API key is currently blocked.
	api_key_blocked bool

	// api_key_disabled indicates whether the API key is currently disabled.
	api_key_disabled bool

	// api_key_id is the unique identifier for the API key.
	api_key_id string

	// create_time is the ISO 8601 timestamp indicating when the API key was created.
	create_time string

	// modified_by is the unique identifier of the user who last modified the API key.
	modified_by string

	// modify_time is the ISO 8601 timestamp indicating when the API key was last modified.
	modify_time string

	// name is the user-defined name of the API key.
	name string

	// redacted_api_key is a partially hidden representation of the API key for display purposes.
	redacted_api_key string

	// team_blocked indicates whether the team associated with the API key is blocked.
	team_blocked bool

	// team_id is the unique identifier for the team associated with the API key.
	team_id string

	// user_id is the unique identifier for the user associated with the API key.
	user_id string
}

APIKeyInfo represents detailed information about an API key, including its status, associated user, and access controls.

struct ChatCompletionChoice {
pub:
	// finish_reason explains why the completion stopped (e.g., "length", "stop").
	finish_reason string

	// index is the position of this choice in the list of returned choices.
	index int

	// message contains the content of the generated message.
	message ChatCompletionMessage
}

ChatCompletionChoice represents a single completion choice returned by the API.

struct ChatCompletionInput {
pub:
	// Number between -2.0 and 2.0. Positive values penalize new tokens based on
	// their existing frequency in the text so far, decreasing the model's
	// likelihood to repeat the same line verbatim.
	frequency_penalty ?f32

	// A JSON object that maps tokens (specified by their token ID in the tokenizer)
	// to an associated bias value from -100 to 100. Mathematically, the bias is added
	// to the logits generated by the model prior to sampling. The exact effect will
	// vary per model, but values between -1 and 1 should decrease or increase likelihood
	// of selection; values like -100 or 100 should result in a ban or exclusive selection
	//  of the relevant token.
	logit_bias ?map[string]f32

	// Whether to return log probabilities of the output tokens or not. If true, returns
	// the log probabilities of each output token returned in the content of message.
	logprobs ?bool

	// The maximum number of tokens that can be generated in the chat completion. This
	// value can be used to control costs for text generated via API.
	max_tokens ?int

	// A list of messages that make up the the chat conversation. Different models
	// support different message types, such as image and text.
	messages []ChatCompletionMessage

	// Model name for the model to use.
	model string

	// How many chat completion choices to generate for each input message. Note that
	// you will be charged based on the number of generated tokens across all of the
	// choices. Keep n as 1 to minimize costs.
	n ?int

	// Number between -2.0 and 2.0. Positive values penalize new tokens based on whether
	// they appear in the text so far, increasing the model's likelihood to talk about new topics.
	presence_penalty ?f32

	// response_format specifies the format of the response, such as plain text or JSON.
	// When null, the default format is used.
	response_format ?string

	// If specified, our system will make a best effort to sample deterministically, such that
	// repeated requests with the same `seed` and parameters should return the same result.
	// Determinism is not guaranteed, and you should refer to the `system_fingerprint` response
	// parameter to monitor changes in the backend.
	seed ?int

	// Up to 4 sequences where the API will stop generating further tokens.
	stop ?[]string
pub mut:
	// If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent
	// events as they become available, with the stream terminated by a `data: [DONE]` message.
	stream bool

	// What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the
	// output more random, while lower values like 0.2 will make it more focused and deterministic.
	temperature ?f32

	// A list of tools the model may call. Currently, only functions are supported as a tool. Use
	// this to provide a list of functions the model may generate JSON inputs for. A max of 128
	// functions are supported.
	tool_choice ?string
	tools       ?[]string

	// An integer between 0 and 20 specifying the number of most likely tokens to return at each
	// token position, each with an associated log probability. logprobs must be set to true if
	// this parameter is used.
	top_logprobs ?int

	// An alternative to sampling with temperature, called nucleus sampling, where the model
	// considers the results of the tokens with top_p probability mass. So 0.1 means only the
	// tokens comprising the top 10% probability mass are considered. It is generally recommended
	// to alter this or `temperature` but not both.
	top_p ?f32

	// A unique identifier representing your end-user, which can help xAI to monitor and detect abuse
	user ?string
}

ChatCompletionInput represents the input parameters for a chat completion request. It includes options for customizing the behavior and output of the model.

struct ChatCompletionMessage {
pub:
	// role is the role of the message sender (e.g., "user", "assistant", "system").
	role string

	// content is the text content of the message.
	content string
}

ChatCompletionMessage represents a single message in the chat conversation.

struct ChatCompletionResponse {
pub:
	// choices contains the list of generated messages.
	choices []ChatCompletionChoice

	// created is the Unix timestamp when the response was generated.
	created i64

	// id is the unique identifier for this API response.
	id string

	// model specifies the model used for this completion.
	model string

	// object specifies the type of object returned (e.g., "text_completion").
	object string

	// system_fingerprint provides a system-level tracking identifier.
	system_fingerprint string

	// usage provides details about token usage in the request and response.
	usage ChatCompletionUsage
}

ChatCompletionResponse represents the full response from the chat completion API.

struct ChatCompletionUsage {
pub:
	// completion_tokens is the number of tokens in the generated response.
	completion_tokens int

	// prompt_tokens is the number of tokens in the input prompt.
	prompt_tokens int

	// total_tokens is the total number of tokens used (prompt + completion).
	total_tokens int
}

ChatCompletionUsage provides details about token usage for a request and response.

struct CompletionChoice {
pub:
	// finish_reason indicates why the generation stopped (e.g., "length", "stop").
	finish_reason string

	// index is the position of this choice in the list of returned choices.
	index int

	// text contains the generated text for this completion.
	text string
}

CompletionChoice represents an individual generated completion within the response.

struct CompletionInput {
pub:
	// The prompt to generate completions for.
	prompt string

	// Number between -2.0 and 2.0. Positive values penalize new tokens based on
	// their existing frequency in the text so far, decreasing the model's
	// likelihood to repeat the same line verbatim.
	frequency_penalty ?f32

	// A JSON object that maps tokens (specified by their token ID in the tokenizer)
	// to an associated bias value from -100 to 100. Mathematically, the bias is added
	// to the logits generated by the model prior to sampling. The exact effect will
	// vary per model, but values between -1 and 1 should decrease or increase likelihood
	// of selection; values like -100 or 100 should result in a ban or exclusive selection
	//  of the relevant token.
	logit_bias ?map[string]f32

	// Whether to return log probabilities of the output tokens or not. If true, returns
	// the log probabilities of each output token returned in the content of message.
	logprobs ?bool

	// The maximum number of tokens that can be generated in the chat completion. This
	// value can be used to control costs for text generated via API.
	max_tokens ?int

	// Specifies the model to be used for the request.
	model string

	// How many chat completion choices to generate for each input message. Note that
	// you will be charged based on the number of generated tokens across all of the
	// choices. Keep n as 1 to minimize costs.
	n ?int

	// Number between -2.0 and 2.0. Positive values penalize new tokens based on whether
	// they appear in the text so far, increasing the model's likelihood to talk about new topics.
	presence_penalty ?f32

	// response_format specifies the format of the response, such as plain text or JSON.
	// When null, the default format is used.
	response_format ?string

	// If specified, our system will make a best effort to sample deterministically, such that
	// repeated requests with the same `seed` and parameters should return the same result.
	// Determinism is not guaranteed, and you should refer to the `system_fingerprint` response
	// parameter to monitor changes in the backend.
	seed ?int

	// Up to 4 sequences where the API will stop generating further tokens.
	stop ?[]string
pub mut:
	// If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent
	// events as they become available, with the stream terminated by a `data: [DONE]` message.
	stream bool

	// What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the
	// output more random, while lower values like 0.2 will make it more focused and deterministic.
	temperature ?f32

	// An alternative to sampling with temperature, called nucleus sampling, where the model
	// considers the results of the tokens with top_p probability mass. So 0.1 means only the
	// tokens comprising the top 10% probability mass are considered. It is generally recommended
	// to alter this or `temperature` but not both.
	top_p ?f32

	// A unique identifier representing your end-user, which can help xAI to monitor and detect abuse
	user ?string
}

CompletionInput represents the input parameters for a completion request. It includes options for customizing the behavior and output of the model.

struct CompletionResponse {
pub:
	// choices contains the list of generated completions.
	choices []CompletionChoice

	// created is the Unix timestamp indicating when the response was generated.
	created i64

	// id is a unique identifier for this completion response.
	id string

	// model specifies the model used to generate the completion.
	model string

	// object specifies the type of object returned, typically "text_completion".
	object string

	// system_fingerprint is a server-generated identifier for debugging or tracking.
	system_fingerprint string

	// usage provides token usage details, including prompt and completion token counts.
	usage CompletionUsage
}

CompletionResponse represents the response from a text completion API call. It includes the generated choices, metadata about the request, and token usage details.

struct CompletionUsage {
pub:
	// completion_tokens is the number of tokens in the generated completion.
	completion_tokens int

	// prompt_tokens is the number of tokens in the input prompt.
	prompt_tokens int

	// total_tokens is the total number of tokens processed (prompt + completion).
	total_tokens int
}

CompletionUsage provides statistics on token usage for a completion request.

struct EmbeddingModel {
	// created is the Unix timestamp indicating when the model was created.
	created i64

	// id is the unique identifier for the embedding model.
	id string

	// input_modalities is a list of supported input types for the model, such as "text" or "image".
	input_modalities []string

	// object specifies the type of object represented, typically "model".
	object string

	// owned_by indicates the owner of the model, usually the organization or team responsible for it.
	owned_by string

	// prompt_image_token_price specifies the token price for image-based inputs.
	prompt_image_token_price i64

	// prompt_text_token_price specifies the token price for text-based inputs.
	prompt_text_token_price i64

	// version specifies the version of the embedding model, such as "1.0.0".
	version string
}

EmbeddingModel represents a specific embedding model available in the X.AI API. It includes details about the model's ID, creation time, input capabilities, and pricing.

struct EmbeddingModelsResponse {
pub:
	// models is the list of embedding models available in the API.
	models []EmbeddingModel
}

EmbeddingModelsResponse represents the response from the API when querying for all available embedding models. It contains a list of EmbeddingModel objects.

struct LanguageModel {
pub:
	// completion_text_token_price specifies the token price for text completions generated by the model.
	completion_text_token_price i64

	// created is the Unix timestamp indicating when the model was created.
	created i64

	// id is the unique identifier for the language model.
	id string

	// input_modalities lists the types of input supported by the model, such as "text" or "image".
	input_modalities []string

	// object specifies the type of object represented, typically "model".
	object string

	// output_modalities lists the types of output that the model can generate, such as "text".
	output_modalities []string

	// owned_by indicates the owner of the model, usually the organization or team responsible for it.
	owned_by string

	// prompt_image_token_price specifies the token price for image-based inputs.
	prompt_image_token_price i64

	// prompt_text_token_price specifies the token price for text-based inputs.
	prompt_text_token_price i64
}

LanguageModel represents a specific language model available in the X.AI API. It includes details about the model's ID, creation time, input/output capabilities, and pricing.

struct LanguageModelsResponse {
pub:
	// models is the list of language models available in the API.
	models []LanguageModel
}

LanguageModelsResponse represents the response from the API when querying for all available language models. It contains a list of LanguageModel objects.

struct Model {
pub:
	// created is the Unix timestamp indicating when the model was created.
	created i64

	// id is the unique identifier for the model.
	id string

	// object specifies the type of object represented, typically "model".
	object string

	// owned_by indicates the owner of the model, usually the organization or team responsible for it.
	owned_by string
}

Model represents a model in the X.AI API. It includes details such as the creation time, ID, ownership, and object type.

struct ModelsResponse {
pub:
	// models is the list of models available in the API.
	models []Model @[json: data]
}

ModelsResponse represents the response from the API when querying for all models. It contains a list of Model objects.

The @json: data attribute maps the "data" key in the JSON response to the models field.

struct StreamChatCompletionChoice {
pub:
	// index is the position of this choice in the list of streamed choices.
	index int

	// delta contains the incremental message content for this choice.
	delta StreamChatCompletionDelta

	// finish_reason explains why this choice's generation stopped (if applicable).
	finish_reason ?string
}

StreamChatCompletionChoice represents a single partial completion returned during streaming.

struct StreamChatCompletionChunk {
pub:
	// id is the unique identifier for this chunk.
	id string

	// object specifies the type of object returned.
	object string

	// created is the Unix timestamp when this chunk was generated.
	created i64

	// choices contains the partial completion choices in this chunk.
	choices []StreamChatCompletionChoice

	// usage provides token usage information for this chunk.
	usage StreamChatCompletionUsage

	// system_fingerprint provides a system-level tracking identifier for this chunk.
	system_fingerprint string
}

StreamChatCompletionChunk represents a single chunk of a streamed response.

struct StreamChatCompletionDelta {
pub:
	// content is the partial message content for this update.
	content ?string

	// role is the role of the message sender for this update.
	role string
}

StreamChatCompletionDelta represents an incremental update to a message during streaming.

struct StreamChatCompletionPromptTokenDetails {
pub:
	// text_tokens is the number of tokens from text inputs.
	text_tokens int

	// audio_tokens is the number of tokens from audio inputs.
	audio_tokens int

	// image_tokens is the number of tokens from image inputs.
	image_tokens int

	// cached_tokens is the number of tokens retrieved from cache.
	cached_tokens int
}

StreamChatCompletionPromptTokenDetails provides a breakdown of tokens in the input prompt.

struct StreamChatCompletionUsage {
pub:
	// prompt_tokens is the number of tokens in the input prompt.
	prompt_tokens int

	// completion_tokens is the number of tokens generated so far.
	completion_tokens int

	// total_tokens is the total number of tokens used (prompt + completion).
	total_tokens int

	// prompt_tokens_details provides a detailed breakdown of the input tokens.
	prompt_tokens_details StreamChatCompletionPromptTokenDetails
}

StreamChatCompletionUsage provides token usage details for a streaming request.

struct StreamCompletionChoice {
pub:
	// index is the position of this choice in the list of returned choices.
	index int

	// delta contains newly streamed content or role information for this choice.
	delta StreamCompletionDelta

	// finish_reason is an optional reason indicating why this choice concluded (e.g., "stop").
	finish_reason ?string
}

StreamCompletionChoice represents an individual choice within a streamed chunk.

struct StreamCompletionChunk {
pub:
	// id is a unique identifier for this specific chunk of the completion.
	id string

	// object specifies the type of the returned object, typically "completion.chunk".
	object string

	// created is the Unix timestamp (in seconds) indicating when this chunk was generated.
	created i64

	// choices is an array of StreamCompletionChoice objects, each representing a portion of the streamed completion.
	choices []StreamCompletionChoice

	// usage contains token usage statistics for this chunk, including prompt and completion tokens.
	usage StreamCompletionUsage

	// system_fingerprint is a server-generated identifier for debugging or reference.
	system_fingerprint string
}

StreamCompletionChunk represents a single streamed chunk of a completion response.

struct StreamCompletionDelta {
pub:
	// content is the newly generated text or partial completion content, if any.
	content ?string

	// role is the role associated with this content, such as "assistant" or "system".
	role string
}

StreamCompletionDelta represents incremental updates to the streamed completion.

struct StreamCompletionPromptTokenDetails {
pub:
	// text_tokens is the number of tokens derived from textual input.
	text_tokens int

	// audio_tokens is the number of tokens derived from audio input.
	audio_tokens int

	// image_tokens is the number of tokens derived from image input.
	image_tokens int

	// cached_tokens is the number of tokens retrieved from cache.
	cached_tokens int
}

StreamCompletionPromptTokenDetails provides a breakdown of the prompt tokens by type.

struct StreamCompletionUsage {
pub:
	// prompt_tokens is the number of tokens used in the input prompt.
	prompt_tokens int

	// completion_tokens is the number of tokens generated in this streamed response.
	completion_tokens int

	// total_tokens is the total number of tokens processed so far (prompt + completion).
	total_tokens int

	// prompt_tokens_details provides a detailed breakdown of the input tokens by type (e.g., text, audio).
	prompt_tokens_details StreamCompletionPromptTokenDetails
}

StreamCompletionUsage contains token usage details for a streamed completion segment.

struct XAIClient {
pub:
	// api_key is the API key used for authentication.
	api_key string

	// base_url is the base URL for API requests.
	// Defaults to `https://api.x.ai/v1/` but can be customized.
	base_url string
}

XAIClient is a client for interacting with the X.AI API. It provides methods for making authenticated GET and POST requests.

fn (c XAIClient) get_api_key_info() !APIKeyInfo

get_api_key_info retrieves information about the current API key being used by the client. It sends a GET request to the "api-key" endpoint and parses the response into an APIKeyInfo struct.

Returns:- An APIKeyInfo struct containing detailed API key information if successful.

• An error if the request or JSON decoding fails.

fn (c XAIClient) get_chat_completion(input ChatCompletionInput) !ChatCompletionResponse

get_chat_completion sends a chat completion request to the API.

Parameters:- input: A ChatCompletionInput instance containing the request parameters.

Returns:- A ChatCompletionResponse containing the generated completions.

• An error if the request fails or if the response cannot be decoded.

fn (c XAIClient) get_completion(input CompletionInput) !CompletionResponse

get_completion sends a completion request to the API.

Parameters:- input: A CompletionInput instance containing the request parameters.

Returns:- A CompletionResponse containing the generated completions.

• An error if the request fails or if the response cannot be decoded.

fn (c XAIClient) get_embedding_model(id string) !EmbeddingModel

get_embedding_model retrieves details about a specific embedding model by its ID.

Parameters:- id: The unique identifier of the embedding model to retrieve.

Returns:- An EmbeddingModel struct containing details about the requested model.

• An error if the request fails or if the response cannot be decoded.

fn (c XAIClient) get_embedding_models() !EmbeddingModelsResponse

get_embedding_models retrieves all available embedding models from the X.AI API.

Returns:- An EmbeddingModelsResponse struct containing a list of all available embedding models.

• An error if the request fails or if the response cannot be decoded.

fn (c XAIClient) get_language_model(id string) !LanguageModel

get_language_model retrieves details about a specific language model by its ID.

Parameters:- id: The unique identifier of the language model to retrieve.

Returns:- A LanguageModel struct containing details about the requested model.

• An error if the request fails or if the response cannot be decoded.

fn (c XAIClient) get_language_models() !LanguageModelsResponse

get_language_models retrieves all available language models from the X.AI API.

Returns:- A LanguageModelsResponse struct containing a list of all available language models.

• An error if the request fails or if the response cannot be decoded.

fn (c XAIClient) get_model(id string) !Model

get_model retrieves details about a specific model by its ID.

Parameters:- id: The unique identifier of the model to retrieve.

Returns:- A Model struct containing details about the requested model.

• An error if the request fails or if the response cannot be decoded.

fn (c XAIClient) get_models() !ModelsResponse

get_models retrieves all available models from the X.AI API.

Returns:- A ModelsResponse struct containing a list of all available models.

• An error if the request fails or if the response cannot be decoded.

fn (c XAIClient) stream_chat_completion(mut input ChatCompletionInput, on_message fn (StreamOnMessageFn), on_finish fn ()) !http.Response

stream_chat_completion sends a streaming chat completion request to the API.

Parameters:- input: A mutable ChatCompletionInput instance containing the request parameters.

• on_message: A callback function invoked for each streamed chunk.
• on_finish: A callback function invoked when streaming finishes.

Returns:- The HTTP response object for the streaming request.

• An error if the request fails.

fn (c XAIClient) stream_completion(mut input CompletionInput, on_message fn (StreamOnMessageFn), on_finish fn ()) !http.Response

stream_completion sends a streaming completion request to the API.

Parameters:- input: A mutable CompletionInput instance containing the request parameters.

• on_message: A callback function invoked for each streamed chunk of the completion.
• on_finish: A callback function invoked when streaming finishes.

Returns:- An HTTP response object for the streaming request.

• An error if the request fails.

struct XAIClientParams {
pub:
	// api_key is the API key required for authentication.
	api_key string

	// base_url is the base URL for API requests.
	// If not provided, it defaults to `https://api.x.ai/v1/`.
	base_url string = vxai.base_url
}

XAIClientParams is used to initialize an XAIClient instance. It supports optional customization of the base URL.