mistral

README

mistral

mistral is a Go client for the Mistral API. It implements the github.com/goloop/ai interface, so it looks and works like every other goloop AI provider, and exposes Mistral's native endpoints with their full options on top.

Features

• Chat completions: Generate for a single response, Stream for token-by-token output through iter.Seq2.
• Tool use (function calling), multimodal image input and system prompts.
• Native ChatCompletion and ChatCompletionStream with the full option set.
• Embeddings, fill-in-the-middle completions and model listing.
• Retries on 429 and 5xx with backoff; normalized, typed API errors.
• Depends only on github.com/goloop/ai and the standard library.
• Structured output: ai.Format maps onto the provider's response_format (JSON mode or a JSON Schema); read the reply with resp.JSON(&v).
• Hosted capabilities: ai.Request.Hosted is refused with ai.ErrNoHosted, because this provider's search lives on another endpoint.

Installation

go get github.com/goloop/mistral

Quick start

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/goloop/ai"
	"github.com/goloop/mistral"
)

func main() {
	c := mistral.New(os.Getenv("MISTRAL_API_KEY"))

	resp, err := c.Generate(context.Background(), &ai.Request{
		Model:    mistral.ModelLargeLatest,
		Messages: []ai.Message{ai.UserText("Say hello in one word.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Text())
}

Streaming

for chunk, err := range c.Stream(ctx, req) {
	if err != nil {
		break
	}
	fmt.Print(chunk.Text)
}

Embeddings

vecs, err := c.Embed(ctx, mistral.ModelEmbed, "hello", "world")

Fill-in-the-middle

Codestral models can complete the gap between a prefix and a suffix. Read the inserted code from the first choice's message content.

resp, err := c.FIM(ctx, &mistral.FIMRequest{
	Model:  mistral.ModelCodestral,
	Prompt: "def add(a, b):\n    ",
	Suffix: "\n    return result",
})

Documentation

Full reference: DOC.md (Ukrainian: DOC.UK.md).

Contributing

See CONTRIBUTING.md.

License

MIT - see LICENSE.

Documentation

Overview

Package mistral is a client for the Mistral API, built on the goloop/ai interface.

The Client implements ai.Client, so Generate and Stream work the same as with any other goloop AI provider. On top of that it exposes the native chat completions endpoint with its full options, embeddings, fill-in-the- middle completions (FIM, for Codestral models) and model listing. The wire format is chat-completions compatible.

c := mistral.New(os.Getenv("MISTRAL_API_KEY"))
resp, err := c.Generate(ctx, &ai.Request{
    Model:    mistral.ModelLargeLatest,
    Messages: []ai.Message{ai.UserText("Say hello in one word.")},
})

Structured output

ai.Request.Format maps onto the provider's response_format, so a request for JSON is enforced rather than merely asked for, and ai.Response.JSON decodes the reply. Plain JSON mode also puts ai.Format.Instruction into the system prompt, because this wire format rejects json_object unless the word "json" appears in the messages.

Hosted capabilities

This provider's hosted search belongs to its conversations and agents endpoints, not to the chat endpoint this package speaks: a chat reply carries no references, and references are what make a searched answer checkable. ai.Hosted is refused with ai.ErrNoHosted.

The refusal is the documented behavior, not a gap waiting to be filled in silence: an answer produced without the search that was asked for looks exactly like one produced with it. A caller who would rather have the answer anyway asks again without ai.Request.Hosted.

Asking what this driver can do

Capabilities describes this driver for the decision taken before a call: whether to offer a feature at all, and whether it needs one request or two.

if ai.SupportsHosted(c, ai.Hosted{Kind: ai.HostedWebSearch}) { ... }

It is a hint and not a permission - support also depends on the model, the account and the region - so ai.ErrNoHosted and ai.ErrNoFormat remain the source of truth and a caller still handles them. What changes is that a refusal the provider only reports as a 400 now arrives as those same sentinels, wrapped around the original ai.APIError, so one errors.Is covers a limitation this driver knew in advance and one it learned over the wire.

It depends only on goloop/ai and the standard library.

Index

• Constants
• type ChatChoice
• type ChatFunctionCall
• type ChatFunctionDef
• type ChatMessage
• type ChatRequest
• type ChatResponse
• type ChatStreamChunk
• type ChatTool
• type ChatToolCall
• type ChatUsage
• type Client
  • func New(apiKey string, opts ...Option) *Client
  • func (c *Client) Capabilities() ai.Capabilities
  • func (c *Client) ChatCompletion(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
  • func (c *Client) ChatCompletionStream(ctx context.Context, req *ChatRequest) iter.Seq2[ChatStreamChunk, error]
  • func (c *Client) Embed(ctx context.Context, model string, input ...string) ([][]float64, error)
  • func (c *Client) Embeddings(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error)
  • func (c *Client) FIM(ctx context.Context, req *FIMRequest) (*ChatResponse, error)
  • func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)
  • func (c *Client) GetModel(ctx context.Context, id string) (*Model, error)
  • func (c *Client) Models(ctx context.Context) ([]Model, error)
  • func (c *Client) Stream(ctx context.Context, req *ai.Request) iter.Seq2[ai.Chunk, error]
• type Embedding
• type EmbeddingRequest
• type EmbeddingResponse
• type FIMRequest
• type Model
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithHeader(key, value string) Option
  • func WithMaxRetries(n int) Option
  • func WithTimeout(d time.Duration) Option

Examples

• Client.FIM
• Client.Generate
• New

Constants

const (
	ModelLargeLatest = "mistral-large-latest"
	ModelSmallLatest = "mistral-small-latest"
	ModelPixtral     = "pixtral-12b-2409"
	ModelEmbed       = "mistral-embed"
	ModelCodestral   = "codestral-latest"
)

Convenience model identifiers. Any model string is accepted; use Models to discover what the account can call.

const DefaultBaseURL = "https://api.mistral.ai/v1"

DefaultBaseURL is the Mistral API base URL, including the version segment.

Types

type ChatChoice

type ChatChoice struct {
	Index        int         `json:"index"`
	Message      ChatMessage `json:"message"`
	FinishReason string      `json:"finish_reason"`
}

ChatChoice is one completion choice.

type ChatFunctionCall

type ChatFunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

ChatFunctionCall is the function name and JSON-encoded arguments of a call.

type ChatFunctionDef

type ChatFunctionDef struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`
}

ChatFunctionDef is a function's name, description and JSON Schema parameters.

type ChatMessage

type ChatMessage struct {
	Role       string         `json:"role"`
	Content    any            `json:"content,omitempty"`
	Name       string         `json:"name,omitempty"`
	ToolCalls  []ChatToolCall `json:"tool_calls,omitempty"`
	ToolCallID string         `json:"tool_call_id,omitempty"`
}

ChatMessage is one message in a chat request or response. Content is a string or a slice of content parts (for images).

type ChatRequest

type ChatRequest struct {
	Model          string          `json:"model"`
	Messages       []ChatMessage   `json:"messages"`
	Tools          []ChatTool      `json:"tools,omitempty"`
	ToolChoice     any             `json:"tool_choice,omitempty"`
	Temperature    *float64        `json:"temperature,omitempty"`
	TopP           *float64        `json:"top_p,omitempty"`
	MaxTokens      int             `json:"max_tokens,omitempty"`
	Stop           []string        `json:"stop,omitempty"`
	N              int             `json:"n,omitempty"`
	Seed           *int            `json:"seed,omitempty"`
	ResponseFormat json.RawMessage `json:"response_format,omitempty"`
	User           string          `json:"user,omitempty"`
	Stream         bool            `json:"stream,omitempty"`
	StreamOptions  *streamOptions  `json:"stream_options,omitempty"`
}

ChatRequest is the native chat completions request, exposing the full option set (response_format, seed, n and so on). Build one directly for features the shared ai.Request does not model, or let Generate build it.

type ChatResponse

type ChatResponse struct {
	ID      string       `json:"id"`
	Object  string       `json:"object"`
	Model   string       `json:"model"`
	Choices []ChatChoice `json:"choices"`
	Usage   ChatUsage    `json:"usage"`
}

ChatResponse is the native chat completions response.

type ChatStreamChunk

type ChatStreamChunk struct {
	ID      string `json:"id"`
	Model   string `json:"model"`
	Choices []struct {
		Index int `json:"index"`
		Delta struct {
			Content   string `json:"content"`
			ToolCalls []struct {
				Index    int    `json:"index"`
				ID       string `json:"id"`
				Function struct {
					Name      string `json:"name"`
					Arguments string `json:"arguments"`
				} `json:"function"`
			} `json:"tool_calls"`
		} `json:"delta"`
		FinishReason string `json:"finish_reason"`
	} `json:"choices"`
	Usage *ChatUsage `json:"usage"`
}

ChatStreamChunk is one streamed chat completions event.

type ChatTool

type ChatTool struct {
	Type     string          `json:"type"`
	Function ChatFunctionDef `json:"function"`
}

ChatTool declares a callable function.

type ChatToolCall

type ChatToolCall struct {
	ID       string           `json:"id"`
	Type     string           `json:"type"`
	Function ChatFunctionCall `json:"function"`
}

ChatToolCall is a tool call the model produced.

type ChatUsage

type ChatUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

ChatUsage reports token usage for a chat completion.

type Client

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

Client is a Mistral API client. It implements ai.Client and adds the provider's native endpoints. The wire format is chat-completions compatible.

func New

func New(apiKey string, opts ...Option) *Client

New returns a Client for the given API key. Shared options (WithBaseURL, WithHTTPClient, WithTimeout, WithMaxRetries, WithHeader) configure it.

Example

package main

import (
	"fmt"

	"github.com/goloop/mistral"
)

func main() {
	c := mistral.New("...")
	_ = c // use c.Generate, c.Stream, c.ChatCompletion, ...
	fmt.Println(mistral.ModelLargeLatest)
}

Output:
mistral-large-latest

func (*Client) Capabilities

func (c *Client) Capabilities() ai.Capabilities

Capabilities describes what this driver can be asked for. It is a hint for the decision taken before a call - whether to offer a feature, and whether it needs one request or two - and never a substitute for handling ai.ErrNoHosted, ai.ErrNoFormat or ai.ErrFormatWithHosted, because support also depends on the model, the account and the region.

func (*Client) ChatCompletion

func (c *Client) ChatCompletion(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

ChatCompletion sends a native chat completions request and returns the whole response. Use it for provider-specific options; use Generate for the shared, provider-agnostic path.

func (*Client) ChatCompletionStream

func (c *Client) ChatCompletionStream(ctx context.Context, req *ChatRequest) iter.Seq2[ChatStreamChunk, error]

ChatCompletionStream sends a native streaming chat request and returns an iterator over the raw chunks.

func (*Client) Embed

func (c *Client) Embed(
	ctx context.Context,
	model string,
	input ...string,
) ([][]float64, error)

Embed embeds one or more inputs and returns their vectors in order.

func (*Client) Embeddings

func (c *Client) Embeddings(
	ctx context.Context,
	req *EmbeddingRequest,
) (*EmbeddingResponse, error)

Embeddings sends a native embeddings request.

func (*Client) FIM

func (c *Client) FIM(ctx context.Context, req *FIMRequest) (*ChatResponse, error)

FIM sends a fill-in-the-middle completion request. The response reuses the chat completions shape; read the inserted text from the first choice's message content.

Example

ExampleClient_FIM shows a fill-in-the-middle request. The model completes the gap between Prompt and Suffix; read the inserted text from the first choice.

package main

import (
	"fmt"

	"github.com/goloop/mistral"
)

func main() {
	req := &mistral.FIMRequest{
		Model:  mistral.ModelCodestral,
		Prompt: "def add(a, b):\n    ",
		Suffix: "\n    return result",
	}
	fmt.Println(req.Model)
}

Output:
codestral-latest

func (*Client) Generate

func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)

Generate implements ai.Client over chat completions.

Example

ExampleClient_Generate builds a request. Sending it needs a real API key, so this example only shows the shape.

package main

import (
	"fmt"

	"github.com/goloop/ai"
	"github.com/goloop/mistral"
)

func main() {
	req := &ai.Request{
		Model: mistral.ModelLargeLatest,
		Messages: []ai.Message{
			ai.UserText("Name the capital of France."),
		},
	}
	fmt.Println(req.Model, len(req.Messages))
}

Output:
mistral-large-latest 1

func (*Client) GetModel

func (c *Client) GetModel(ctx context.Context, id string) (*Model, error)

GetModel returns a single model by ID.

func (*Client) Models

func (c *Client) Models(ctx context.Context) ([]Model, error)

Models lists the models available to the account.

func (*Client) Stream

func (c *Client) Stream(ctx context.Context, req *ai.Request) iter.Seq2[ai.Chunk, error]

Stream implements ai.Client over streaming chat completions.

type Embedding

type Embedding struct {
	Index     int       `json:"index"`
	Embedding []float64 `json:"embedding"`
}

Embedding is one embedding vector with its position in the input.

type EmbeddingRequest

type EmbeddingRequest struct {
	Model string   `json:"model"`
	Input []string `json:"input"`
}

EmbeddingRequest is the native embeddings request.

type EmbeddingResponse

type EmbeddingResponse struct {
	Model string      `json:"model"`
	Data  []Embedding `json:"data"`
	Usage ChatUsage   `json:"usage"`
}

EmbeddingResponse is the native embeddings response.

type FIMRequest

type FIMRequest struct {
	Model       string   `json:"model"`
	Prompt      string   `json:"prompt"`
	Suffix      string   `json:"suffix,omitempty"`
	MaxTokens   int      `json:"max_tokens,omitempty"`
	Temperature *float64 `json:"temperature,omitempty"`
	TopP        *float64 `json:"top_p,omitempty"`
	Stop        []string `json:"stop,omitempty"`
}

FIMRequest is a fill-in-the-middle completion request. The model (a Codestral model) completes the gap between Prompt and Suffix; leave Suffix empty for a plain prefix completion.

type Model

type Model struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	Created int64  `json:"created"`
	OwnedBy string `json:"owned_by"`
}

Model describes a model returned by the models endpoint.

type Option

type Option func(*settings)

Option configures a Client in New.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (proxies, gateways, mock servers).

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets the HTTP client used for requests.

func WithHeader

func WithHeader(key, value string) Option

WithHeader adds a header sent with every request.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets how many times a request is retried on 429 and 5xx.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-request timeout when no custom HTTP client is set.