@spec chat(
  client(),
  keyword()
) :: response()

Chat with a Mistral model. Send messages and get a completion from the model.

Options

• :model (String.t/0) - Required. The model to use for generating the response.
• :messages (list of map/0) - Required. List of messages in the conversation.
• :temperature (float/0) - Controls randomness. Lower values are more deterministic (0.0 to 1.5).
• :top_p (float/0) - Controls diversity via nucleus sampling. Considers only tokens with the top_p probability mass. The default value is 1.0.
• :max_tokens (non_neg_integer/0) - Maximum number of tokens to generate.
• :stream - When true, returns a stream of partial response chunks. The default value is false.
• :random_seed (non_neg_integer/0) - Seed for deterministic results.
• :tools (list of map/0) - List of tools available to the model.
• :tool_choice - Controls tool selection. Options: 'auto', 'any', 'none', or a specific tool.
• :presence_penalty (float/0) - Penalizes repetition of tokens. Higher values reduce repetition. The default value is 0.0.
• :frequency_penalty (float/0) - Penalizes tokens based on their frequency. Higher values reduce repetition. The default value is 0.0.
• :safe_prompt (boolean/0) - Whether to inject a safety prompt before all conversations. The default value is false.

Message structure

Each message is a map with the following fields:

• :role - Required. The role of the message, either system, user, assistant or tool.
• :content - The content of the message.
• :tool_calls - (optional) Tool calls from the assistant that the model wants to use.
• :tool_call_id (String.t/0) - (optional) Required when role is 'tool'. ID of the tool call this message is responding to.

Tool structure

Each tool is a map with the following fields:

• :type - Required. The type of tool. Currently only 'function' is supported.
• :function (map/0) - Required. The function definition.
  • :name (String.t/0) - Required. The name of the function to be called.
  • :description (String.t/0) - (optional) A description of what the function does.
  • :parameters - Required. The parameters the function accepts, described as a JSON Schema object.

Examples

iex> Mistral.chat(client, [
...>   model: "mistral-small-latest",
...>   messages: [
...>     %{role: "user", content: "Write a haiku."}
...>   ]
...> ])
{:ok, %{"choices" => [%{"message" => %{"content" => "Nature's whisper soft..."}}], ...}}

# Stream the response
iex> {:ok, stream} = Mistral.chat(client, [
...>   model: "mistral-small-latest",
...>   messages: [%{role: "user", content: "Write a haiku."}],
...>   stream: true
...> ])
iex> Enum.to_list(stream)
[%{"choices" => [%{"delta" => ...}]}, ...]

## Tool Example

iex> Mistral.chat(client, [
...>   model: "mistral-large-latest",
...>   messages: [%{role: "user", content: "What is the weather?"}],
...>   tools: [
...>     %{
...>       type: "function",
...>       function: %{
...>         name: "get_weather",
...>         description: "Fetches current weather",
...>         parameters: %{type: "object", properties: %{}}
...>       }
...>     }
...>   ],
...>   tool_choice: "auto"
...> ])

@spec embed(
  client(),
  keyword()
) :: response()

Generate embeddings for the given input using a specified model.

Options

• :model (String.t/0) - The model to use for generating embeddings. The default value is "mistral-embed".
• :input - Required. Text or list of texts to generate embeddings for.

Examples

iex> Mistral.embed(client, input: "Hello, world!")
{:ok, %{"data" => [%{"embedding" => [...]}]}}

iex> Mistral.embed(client, input: ["First text", "Second text"])
{:ok, %{"data" => [%{"embedding" => [...]}, %{"embedding" => [...]}]}}

@spec get_file(client(), String.t()) :: response()

Retrieves information about a specific file by its ID.

Parameters

• client: A Mistral.client() struct.
• file_id: The ID of the file to retrieve.

Examples

iex> Mistral.get_file(client, "00edaf84-95b0-45db-8f83-f71138491f23")
{:ok, %{
  "id" => "00edaf84-95b0-45db-8f83-f71138491f23",
  "object" => "file",
  "bytes" => 3749788,
  "created_at" => 1741023462,
  "filename" => "test_document.pdf",
  "purpose" => "ocr",
  "sample_type" => "ocr_input",
  "source" => "upload",
  "deleted" => false
}}

@spec get_file_url(client(), String.t(), keyword()) :: response()

Retrieves a signed URL for the specified file.

Parameters

• client: A Mistral.client() struct.
• file_id: The ID of the file.
• opts: An optional keyword list for additional query parameters (e.g., expiry).

Examples

iex> Mistral.get_file_url(client, "00edaf84-95b0-45db-8f83-f71138491f23")
{:ok, %{"url" => "https://storage.googleapis.com/mistral-file-uploads/signed-url-example"}}

iex> Mistral.get_file_url(client, "00edaf84-95b0-45db-8f83-f71138491f23", expiry: 48)
{:ok, %{"url" => "https://storage.googleapis.com/mistral-file-uploads/signed-url-example"}}

@spec get_model(client(), String.t()) :: response()

Retrieves information about a specific model by its ID.

Parameters

• client: A Mistral.client() struct.
• model_id: The ID of the model to retrieve (e.g. "mistral-small-latest").

Examples

iex> Mistral.get_model(client, "mistral-small-latest")
{:ok, %{
  "id" => "mistral-small-latest",
  "object" => "model",
  "created" => 1711430400,
  "owned_by" => "mistralai",
  "capabilities" => %{
    "completion_chat" => true,
    "function_calling" => true,
    "vision" => false
  },
  "name" => "Mistral Small"
}}

@spec init() :: client()

Creates a new Mistral API client using the API key set in your application's config.

config :mistral, :api_key, "your-api-key"

If given, a keyword list of options will be passed to Req.new/1.

Examples

iex> client = Mistral.init()
%Mistral{}

iex> client = Mistral.init(headers: [{"X-Custom-Header", "value"}])
%Mistral{}

@spec init(
  String.t(),
  keyword()
) :: client()

Creates a new Mistral API client with the given API key.

Optionally, a keyword list of options can be passed through to Req.new/1.

Examples

iex> client = Mistral.init("YOUR_API_KEY")
%Mistral{}

iex> client = Mistral.init("YOUR_API_KEY", receive_timeout: :infinity)
%Mistral{}

@spec list_models(client()) :: response()

Lists all available models.

Examples

iex> Mistral.list_models(client)
{:ok, %{
  "object" => "list",
  "data" => [
    %{
      "id" => "mistral-small-latest",
      "object" => "model",
      "created" => 1711430400,
      "owned_by" => "mistralai",
      "capabilities" => %{
        "completion_chat" => true,
        "function_calling" => true
      }
    }
  ]
}}

@spec ocr(
  client(),
  keyword()
) :: response()

Perform OCR on a document or image.

Options

• :model - Required. Model to use for OCR processing.
• :id (String.t/0) - Unique identifier for the OCR request.
• :document - Required. Document object containing the URL or image URL.
• :pages - List of page indices to process (starting from 0).
• :include_image_base64 - Include base64 images in the response.
• :image_limit - Maximum number of images to extract.
• :image_min_size - Minimum image dimensions to extract.

Examples

iex> Mistral.ocr(client, model: "mistral-ocr-latest", document: %{type: "document_url", document_url: "https://example.com/sample.pdf"})
{:ok, %{"pages" => [...]}}

iex> Mistral.ocr(client, model: "mistral-ocr-latest", document: %{type: "image_url", image_url: "https://example.com/sample.png"})
{:ok, %{"pages" => [...]}}

@spec upload_file(client(), Path.t(), keyword()) :: response()

Uploads a file to the Mistral API.

Options

• :purpose - Required. The purpose of the file. Currently supports 'ocr', 'fine-tune', and 'batch'.

Examples

iex> Mistral.upload_file(client, "path/to/file.pdf", purpose: "ocr")
{:ok, %{"id" => "file-abc123", "object" => "file", ...}}