Mistral (Mistral v0.5.0)
Client for the Mistral AI API.
This library provides a simple and convenient way to integrate with Mistral's API, allowing you to use their powerful language models in your Elixir applications.
Installation
Add mistral to your list of dependencies in mix.exs:
def deps do
[
{:mistral, "~> 0.5.0"}
]
endConfiguration
Set your Mistral API key in your config:
config :mistral, :api_key, "your_mistral_api_key"Usage Examples
Chat Completion
{:ok, client} = Mistral.init("your_api_key")
{:ok, response} = Mistral.chat(client,
model: "mistral-small-latest",
messages: [
%{role: "user", content: "Write a haiku about elixir"}
]
)Summary
Functions
Send a completion request to an agent.
Append entries to an existing conversation.
Archive a fine-tuned model.
Cancel a batch job by its ID.
Cancel a fine-tuning job by its ID.
Chat with a Mistral model. Send messages and get a completion from the model.
Classify text using a Mistral moderation model.
Classify chat conversations using a Mistral moderation model.
Create an agent.
Create a batch job for asynchronous batch inference.
Create a new conversation.
Create a fine-tuning job.
Create or update a version alias for an agent.
Delete an agent by its ID.
Delete a conversation by its ID.
Deletes a file by its ID.
Delete a model by its ID.
Downloads the content of a file by its ID.
Generate embeddings for the given input using a specified model.
Fill-in-the-middle completion for code. Given a code prompt (and optional suffix),
the model generates the code that fits between them.
Retrieve an agent by its ID.
Get a specific version of an agent.
Retrieve a batch job by its ID.
Retrieve a conversation by its ID.
Get the history of a conversation.
Get the messages of a conversation.
Retrieves information about a specific file by its ID.
Retrieves a signed URL for the specified file.
Retrieve a fine-tuning job by its ID.
Retrieves information about a specific model by its ID.
Creates a new Mistral API client using the API key set in your application's config.
Creates a new Mistral API client with the given API key.
List all version aliases for an agent.
List all versions of an agent.
List agents with optional filtering and pagination.
List batch jobs with optional filtering and pagination.
List conversations with optional pagination.
Lists all uploaded files.
List fine-tuning jobs with optional filtering and pagination.
Lists all available models.
Moderate text using a Mistral moderation model.
Moderate chat conversations using a Mistral moderation model.
Perform OCR on a document or image.
Restart a conversation from a specific entry.
Start a fine-tuning job by its ID.
Unarchive a fine-tuned model.
Update an agent. Creates a new version of the agent.
Switch an agent to a specific version.
Update a fine-tuned model's name and/or description.
Uploads a file to the Mistral API.
Types
@type client() :: %Mistral{req: Req.Request.t()}
Client struct
@type response() :: {:ok, map() | binary() | Enumerable.t() | Task.t()} | {:error, term()}
Client response
Functions
Send a completion request to an agent.
Options
:agent_id(String.t/0) - Required. ID of the agent.:messages(list ofmap/0) - Required. Messages.:max_tokens(non_neg_integer/0) - Maximum tokens.:stream- Stream response. The default value isfalse.:stream_timeout(non_neg_integer/0) - Timeout in milliseconds for receiving stream chunks. Defaults to 30000 (30 seconds). The default value is30000.:stop- Stop token(s).:random_seed(non_neg_integer/0) - Random seed.:response_format- Response format.:tools(list ofmap/0) - Available tools.:tool_choice- Tool choice.:presence_penalty(float/0) - Presence penalty. The default value is0.0.:frequency_penalty(float/0) - Frequency penalty. The default value is0.0.:n(pos_integer/0) - Number of completions.:metadata- Custom metadata.
Examples
iex> Mistral.agent_completion(client,
...> agent_id: "ag_abc123",
...> messages: [%{role: "user", content: "Hello!"}]
...> )
{:ok, %{"choices" => [%{"message" => %{"content" => "..."}}], ...}}
# Stream the response
iex> {:ok, stream} = Mistral.agent_completion(client,
...> agent_id: "ag_abc123",
...> messages: [%{role: "user", content: "Hello!"}],
...> stream: true
...> )
iex> Enum.to_list(stream)
[%{"choices" => [%{"delta" => ...}]}, ...]Append entries to an existing conversation.
Options
:inputs- Required. The input string or list of entry objects.:stream- When true, returns a stream of response events. The default value isfalse.:stream_timeout(non_neg_integer/0) - Timeout in milliseconds for receiving stream chunks. Defaults to 30000 (30 seconds). The default value is30000.:store(boolean/0) - Whether to store the entries. The default value istrue.:handoff_execution- Handoff execution mode. The default value is"server".:completion_args- (optional) Completion arguments.
Examples
iex> Mistral.append_conversation(client, "conv_abc123", inputs: "Follow up question")
{:ok, %{"object" => "conversation.response", ...}}
# Stream the response
iex> {:ok, stream} = Mistral.append_conversation(client, "conv_abc123", inputs: "Follow up", stream: true)
iex> Enum.to_list(stream)
[%{"object" => "conversation.response.started", ...}, ...]Archive a fine-tuned model.
Examples
iex> Mistral.archive_fine_tuned_model(client, "ft:open-mistral-7b:abc123")
{:ok, %{"id" => "ft:open-mistral-7b:abc123", "archived" => true, ...}}Cancel a batch job by its ID.
Examples
iex> Mistral.cancel_batch_job(client, "b_abc123")
{:ok, %{"id" => "b_abc123", "status" => "CANCELLATION_REQUESTED", ...}}Cancel a fine-tuning job by its ID.
Examples
iex> Mistral.cancel_fine_tuning_job(client, "ft-abc123")
{:ok, %{"id" => "ft-abc123", "status" => "CANCELLATION_REQUESTED", ...}}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 ofmap/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 is1.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 isfalse.:stream_timeout(non_neg_integer/0) - Timeout in milliseconds for receiving stream chunks. Defaults to 30000 (30 seconds). The default value is30000.:random_seed(non_neg_integer/0) - Seed for deterministic results.:tools(list ofmap/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 is0.0.:frequency_penalty(float/0) - Penalizes tokens based on their frequency. Higher values reduce repetition. The default value is0.0.:safe_prompt(boolean/0) - Whether to inject a safety prompt before all conversations. The default value isfalse.:response_format- (optional) Controls the output format. Use for JSON mode or structured output with schema validation.
Message structure
Each message is a map with the following fields:
:role- Required. The role of the message, eithersystem,user,assistantortool.: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 whenroleis '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"
...> ])
## Response Format Control
You can control the output format using the `response_format` parameter:
iex> # JSON mode - ensures response is valid JSON
iex> Mistral.chat(client, [
...> model: "mistral-small-latest",
...> messages: [%{role: "user", content: "Generate user data in JSON format"}],
...> response_format: %{type: "json_object"}
...> ])
iex> # JSON Schema mode - validates response against schema
iex> user_schema = %{
...> type: "object",
...> title: "UserProfile",
...> properties: %{
...> name: %{type: "string", title: "Name"},
...> age: %{type: "integer", title: "Age", minimum: 0},
...> email: %{type: "string", title: "Email"}
...> },
...> required: ["name", "age"],
...> additionalProperties: false
...> }
iex> Mistral.chat(client, [
...> model: "mistral-small-latest",
...> messages: [%{role: "user", content: "Generate a user profile"}],
...> response_format: %{
...> type: "json_schema",
...> json_schema: %{
...> name: "user_profile",
...> schema: user_schema,
...> strict: true
...> }
...> }
...> ])Classify text using a Mistral moderation model.
Options
:model(String.t/0) - Required. ID of the model to use.:input- Required. Text or list of texts to classify.
Examples
iex> Mistral.classify(client, model: "mistral-moderation-latest", input: "Hello, world!")
{:ok, %{"id" => "...", "model" => "mistral-moderation-latest", "results" => [...]}}
iex> Mistral.classify(client, model: "mistral-moderation-latest", input: ["First text", "Second text"])
{:ok, %{"id" => "...", "model" => "mistral-moderation-latest", "results" => [...]}}Classify chat conversations using a Mistral moderation model.
Options
:model(String.t/0) - Required. ID of the model to use.:input- Required. A single conversation or list of conversations to classify.
Examples
iex> Mistral.classify_chat(client,
...> model: "mistral-moderation-latest",
...> input: %{messages: [%{role: "user", content: "Hello"}]}
...> )
{:ok, %{"id" => "...", "model" => "mistral-moderation-latest", "results" => [...]}}Create an agent.
Options
:model(String.t/0) - Required. Model ID to use.:name(String.t/0) - Required. Agent name.:instructions- System instructions.:tools(list ofmap/0) - Available tools.:completion_args(map/0) - Default completion arguments.:stop- Stop token(s).:presence_penalty(float/0) - Presence penalty (-2 to 2).:frequency_penalty(float/0) - Frequency penalty (-2 to 2).:temperature(float/0) - Temperature (0 to 1).:top_p(float/0) - Top-p sampling (0 to 1).:max_tokens(non_neg_integer/0) - Maximum tokens.:random_seed(non_neg_integer/0) - Random seed.:response_format- Response format.:tool_choice- Tool choice strategy. The default value is"auto".
:description- Agent description.:handoffs(list ofString.t/0) - Agent IDs for handoff.:metadata- Custom metadata.
Agent tool structure
:type- Required. The type of tool.:function(map/0) - (required when type is 'function') 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.
:library_ids(list ofString.t/0) - (required when type is 'document_library') IDs of the libraries to search.
Completion arguments structure
:stop- Stop token(s).:presence_penalty(float/0) - Presence penalty (-2 to 2).:frequency_penalty(float/0) - Frequency penalty (-2 to 2).:temperature(float/0) - Temperature (0 to 1).:top_p(float/0) - Top-p sampling (0 to 1).:max_tokens(non_neg_integer/0) - Maximum tokens.:random_seed(non_neg_integer/0) - Random seed.:response_format- Response format.:tool_choice- Tool choice strategy. The default value is"auto".
Examples
iex> Mistral.create_agent(client,
...> model: "mistral-large-latest",
...> name: "My Agent",
...> instructions: "You are a helpful assistant."
...> )
{:ok, %{"id" => "ag_abc123", "name" => "My Agent", ...}}Create a batch job for asynchronous batch inference.
Provide either input_files (list of uploaded JSONL file IDs) or requests
(inline list of batch request objects). The endpoint parameter specifies which
API endpoint to use for processing.
Options
:input_files(list ofString.t/0) - (optional) List of file IDs (UUIDs) to use as input. Files must be JSONL format.:requests(list ofmap/0) - (optional) Inline list of batch requests (max 10,000).:endpoint- Required. The API endpoint to use for batch inference.:model(String.t/0) - (optional) The model to use for batch inference.:metadata- (optional) Metadata to associate with the batch job.:timeout_hours(integer/0) - Timeout in hours for the batch job. The default value is24.
Batch request structure
:custom_id(String.t/0) - (optional) Custom identifier for this request.:body- Required. The request body for the batch inference.
Examples
iex> Mistral.create_batch_job(client,
...> endpoint: "/v1/chat/completions",
...> input_files: ["file-abc123"]
...> )
{:ok, %{"id" => "b_abc123", "status" => "QUEUED", ...}}
iex> Mistral.create_batch_job(client,
...> endpoint: "/v1/chat/completions",
...> model: "mistral-small-latest",
...> requests: [
...> %{custom_id: "req-1", body: %{messages: [%{role: "user", content: "Hello"}]}}
...> ]
...> )
{:ok, %{"id" => "b_abc123", "status" => "QUEUED", ...}}Create a new conversation.
Options
:inputs- Required. The input string or list of entry objects.:stream- When true, returns a stream of response events. The default value isfalse.:stream_timeout(non_neg_integer/0) - Timeout in milliseconds for receiving stream chunks. Defaults to 30000 (30 seconds). The default value is30000.:store- (optional) Whether to store the conversation.:handoff_execution- (optional) Handoff execution mode ('client' or 'server').:instructions- (optional) System instructions for the conversation.:tools- (optional) Available tools (function, web_search, code_interpreter, etc.).:completion_args- (optional) Completion arguments.:name- (optional) Name of the conversation.:description- (optional) Description of the conversation.:metadata- (optional) Custom metadata.:agent_id- (optional) Agent ID to use.:agent_version- (optional) Agent version.:model- (optional) Model ID to use.
Examples
iex> Mistral.create_conversation(client, inputs: "Hello!")
{:ok, %{"object" => "conversation.response", "conversation_id" => "conv_abc123", ...}}
# Stream the response
iex> {:ok, stream} = Mistral.create_conversation(client, inputs: "Hello!", stream: true)
iex> Enum.to_list(stream)
[%{"object" => "conversation.response.started", ...}, ...]Create a fine-tuning job.
Options
:model- Required. The model to fine-tune.:training_files(list ofmap/0) - (optional) List of training file objects.:validation_files(list ofString.t/0) - (optional) List of validation file IDs (UUIDs).:suffix(String.t/0) - (optional) A suffix to append to the fine-tuned model name.:integrations(list ofmap/0) - (optional) List of W&B integrations.:auto_start(boolean/0) - (optional) Whether to start the job automatically after validation.:hyperparameters- Required. Hyperparameters for fine-tuning (e.g. training_steps, learning_rate, etc.).:repositories(list ofmap/0) - (optional) List of GitHub repositories to use as training data.:classifier_targets(list ofmap/0) - (optional) List of classifier targets (for classifier job type).:job_type- (optional) The type of fine-tuning job.:invalid_sample_skip_percentage(float/0) - (optional) Percentage of invalid samples to skip during training. The default value is0.0.:dry_run(boolean/0) - (optional) If true, returns estimated cost and duration without creating the job.
Training file structure
:file_id(String.t/0) - Required. The ID (UUID) of an uploaded training file.:weight(float/0) - (optional) Weight of the training file. The default value is1.0.
W&B integration structure
:type- Integration type. The default value is"wandb".:project(String.t/0) - Required. The W&B project name.:name(String.t/0) - (optional) Display name for the run.:api_key(String.t/0) - Required. The W&B API key (40 characters).:run_name(String.t/0) - (optional) The W&B run name.
Examples
iex> Mistral.create_fine_tuning_job(client,
...> model: "open-mistral-7b",
...> hyperparameters: %{training_steps: 10},
...> training_files: [%{file_id: "file-abc123"}]
...> )
{:ok, %{"id" => "ft-abc123", "status" => "QUEUED", ...}}
iex> Mistral.create_fine_tuning_job(client,
...> model: "open-mistral-7b",
...> hyperparameters: %{training_steps: 10},
...> dry_run: true
...> )
{:ok, %{"expected_duration_seconds" => 300, ...}}Create or update a version alias for an agent.
Examples
iex> Mistral.create_or_update_agent_alias(client, "ag_abc123", "production", 2)
{:ok, %{"alias" => "production", "version" => 2, ...}}Delete an agent by its ID.
Examples
iex> Mistral.delete_agent(client, "ag_abc123")
{:ok, %{}}Delete a conversation by its ID.
Examples
iex> Mistral.delete_conversation(client, "conv_abc123")
{:ok, %{}}Deletes a file by its ID.
Parameters
client: AMistral.client()struct.file_id: The ID of the file to delete.
Examples
iex> Mistral.delete_file(client, "file-abc123")
{:ok, %{"id" => "file-abc123", "object" => "file", "deleted" => true}}Delete a model by its ID.
Examples
iex> Mistral.delete_model(client, "ft:open-mistral-7b:abc123")
{:ok, %{"id" => "ft:open-mistral-7b:abc123", "deleted" => true, ...}}Downloads the content of a file by its ID.
Returns the raw binary content of the file.
Parameters
client: AMistral.client()struct.file_id: The ID of the file to download.
Examples
iex> Mistral.download_file(client, "file-abc123")
{:ok, <<...>>}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" => [...]}]}}Fill-in-the-middle completion for code. Given a code prompt (and optional suffix),
the model generates the code that fits between them.
Options
:model(String.t/0) - Required. ID of the model to use for FIM completion (e.g.codestral-latest).:prompt(String.t/0) - Required. The text/code to complete.:suffix(String.t/0) - (optional) Text/code that adds more context. When given apromptand asuffix, the model fills what is between them.:temperature(float/0) - Controls randomness (0.0 to 1.5).:top_p(float/0) - Controls diversity via nucleus sampling. The default value is1.0.:max_tokens(non_neg_integer/0) - Maximum number of tokens to generate.:min_tokens(non_neg_integer/0) - Minimum number of tokens to generate.:stream- When true, returns a stream of partial response chunks. The default value isfalse.:stream_timeout(non_neg_integer/0) - Timeout in milliseconds for receiving stream chunks. Defaults to 30000 (30 seconds). The default value is30000.:stop- Stop generation if this token is detected.:random_seed(non_neg_integer/0) - Seed for deterministic results.
Examples
iex> Mistral.fim(client, model: "codestral-latest", prompt: "def add(a, b):\n ")
{:ok, %{"choices" => [%{"message" => %{"content" => "return a + b"}}], ...}}
# With suffix for fill-in-the-middle
iex> Mistral.fim(client, model: "codestral-latest", prompt: "def ", suffix: "return a + b")
{:ok, %{"choices" => [%{"message" => %{"content" => "add(a, b):\n "}}], ...}}
# Stream the response
iex> {:ok, stream} = Mistral.fim(client, model: "codestral-latest", prompt: "def ", stream: true)
iex> Enum.to_list(stream)
[%{"choices" => [%{"delta" => ...}]}, ...]Retrieve an agent by its ID.
Options
:agent_version- Version number or alias.
Examples
iex> Mistral.get_agent(client, "ag_abc123")
{:ok, %{"id" => "ag_abc123", "name" => "My Agent", ...}}
iex> Mistral.get_agent(client, "ag_abc123", agent_version: 2)
{:ok, %{"id" => "ag_abc123", "version" => 2, ...}}Get a specific version of an agent.
Examples
iex> Mistral.get_agent_version(client, "ag_abc123", 2)
{:ok, %{"id" => "ag_abc123", "version" => 2, ...}}Retrieve a batch job by its ID.
Options
:inline(boolean/0) - (optional) If true, return results inline in the response.
Examples
iex> Mistral.get_batch_job(client, "b_abc123")
{:ok, %{"id" => "b_abc123", "status" => "QUEUED", ...}}
iex> Mistral.get_batch_job(client, "b_abc123", inline: true)
{:ok, %{"id" => "b_abc123", "status" => "SUCCESS", "results" => [...], ...}}Retrieve a conversation by its ID.
Examples
iex> Mistral.get_conversation(client, "conv_abc123")
{:ok, %{"object" => "conversation", "conversation_id" => "conv_abc123", ...}}Get the history of a conversation.
Examples
iex> Mistral.get_conversation_history(client, "conv_abc123")
{:ok, %{"entries" => [...]}}Get the messages of a conversation.
Examples
iex> Mistral.get_conversation_messages(client, "conv_abc123")
{:ok, %{"messages" => [...]}}Retrieves information about a specific file by its ID.
Parameters
client: AMistral.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
}}Retrieves a signed URL for the specified file.
Parameters
client: AMistral.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"}}Retrieve a fine-tuning job by its ID.
Examples
iex> Mistral.get_fine_tuning_job(client, "ft-abc123")
{:ok, %{"id" => "ft-abc123", "status" => "QUEUED", ...}}Retrieves information about a specific model by its ID.
Parameters
client: AMistral.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{}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.
Retry options
The client automatically retries transient errors (HTTP 408, 429, 5xx, and socket/connection errors) using exponential backoff with full jitter. The following retry-related options can be overridden:
:retry- Retry mode. Defaults to:transient. Set tofalseto disable retries entirely.:max_retries- Maximum number of retry attempts. Defaults to3.:retry_delay- A function that receives the retry count (0-indexed) and returns the delay in milliseconds. Defaults to&Mistral.Retry.delay/1(exponential backoff with full jitter, capped at 60 seconds).:retry_log_level- Log level for retry warnings. Defaults to:warning. Set tofalseto disable retry logging.
Streaming requests automatically disable retries since SSE streams cannot be safely replayed.
Cache options
Optional response caching can be enabled to reduce redundant API calls.
Only deterministic, non-streaming endpoints are cached. See Mistral.Cache
for details.
:cache- Set totrueto enable response caching. Defaults tofalse.:cache_ttl- Cache time-to-live in milliseconds. Defaults to300_000(5 minutes).:cache_table- ETS table name for the cache. Defaults to:mistral_cache.
Examples
iex> client = Mistral.init("YOUR_API_KEY")
%Mistral{}
iex> client = Mistral.init("YOUR_API_KEY", receive_timeout: :infinity)
%Mistral{}
iex> client = Mistral.init("YOUR_API_KEY", retry: false)
%Mistral{}
iex> client = Mistral.init("YOUR_API_KEY", max_retries: 5)
%Mistral{}
iex> client = Mistral.init("YOUR_API_KEY", cache: true)
%Mistral{}
iex> client = Mistral.init("YOUR_API_KEY", cache: true, cache_ttl: 600_000)
%Mistral{}List all version aliases for an agent.
Examples
iex> Mistral.list_agent_aliases(client, "ag_abc123")
{:ok, %{"object" => "list", "data" => [...], "total" => 2}}List all versions of an agent.
Options
Examples
iex> Mistral.list_agent_versions(client, "ag_abc123")
{:ok, %{"object" => "list", "data" => [...], "total" => 3}}List agents with optional filtering and pagination.
Options
:page(integer/0) - Page number (0-indexed).:page_size(integer/0) - Items per page (1-1000).:deployment_chat(boolean/0) - Filter by deployment chat.:sources- Filter by sources.:name(String.t/0) - Filter by name.:id(String.t/0) - Filter by ID.
Examples
iex> Mistral.list_agents(client)
{:ok, %{"object" => "list", "data" => [...], "total" => 2}}
iex> Mistral.list_agents(client, page: 0, page_size: 10)
{:ok, %{"object" => "list", "data" => [...], "total" => 2}}List batch jobs with optional filtering and pagination.
Options
:page(integer/0) - (optional) Page number (0-indexed).:page_size(integer/0) - (optional) Number of items per page.:model(String.t/0) - (optional) Filter by model.:created_after(String.t/0) - (optional) Filter jobs created after this datetime (ISO 8601).:created_by_me(boolean/0) - (optional) Only return jobs created by the current user. The default value isfalse.:status- (optional) Filter by job status.
Examples
iex> Mistral.list_batch_jobs(client)
{:ok, %{"object" => "list", "data" => [...], "total" => 2}}
iex> Mistral.list_batch_jobs(client, status: ["QUEUED", "RUNNING"], model: "mistral-small-latest")
{:ok, %{"object" => "list", "data" => [...], "total" => 1}}List conversations with optional pagination.
Options
Examples
iex> Mistral.list_conversations(client)
{:ok, [%{"object" => "conversation", ...}]}
iex> Mistral.list_conversations(client, page: 0, page_size: 10)
{:ok, [%{"object" => "conversation", ...}]}Lists all uploaded files.
Options
:page(integer/0) - (optional) Pagination page number.:page_size(integer/0) - (optional) Number of items per page.:sample_type(list ofString.t/0) - (optional) Filter by sample type.:source(list ofString.t/0) - (optional) Filter by source.:search(String.t/0) - (optional) Search query.:purpose- (optional) Filter by purpose. Supports 'ocr', 'fine-tune', and 'batch'.
Examples
iex> Mistral.list_files(client)
{:ok, %{"object" => "list", "data" => [%{"id" => "file-abc123", ...}]}}
iex> Mistral.list_files(client, purpose: "ocr", page_size: 10)
{:ok, %{"object" => "list", "data" => [...]}}List fine-tuning jobs with optional filtering and pagination.
Options
:page(integer/0) - (optional) Page number (0-indexed).:page_size(integer/0) - (optional) Number of items per page.:model(String.t/0) - (optional) Filter by model.:created_after(String.t/0) - (optional) Filter jobs created after this datetime (ISO 8601).:created_before(String.t/0) - (optional) Filter jobs created before this datetime (ISO 8601).:wandb_project(String.t/0) - (optional) Filter by W&B project name.:wandb_name(String.t/0) - (optional) Filter by W&B run name.:suffix(String.t/0) - (optional) Filter by model suffix.:created_by_me(boolean/0) - (optional) Only return jobs created by the current user. The default value isfalse.:status- (optional) Filter by job status.
Examples
iex> Mistral.list_fine_tuning_jobs(client)
{:ok, %{"object" => "list", "data" => [...], "total" => 2}}
iex> Mistral.list_fine_tuning_jobs(client, status: "RUNNING", model: "open-mistral-7b")
{:ok, %{"object" => "list", "data" => [...], "total" => 1}}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
}
}
]
}}Moderate text using a Mistral moderation model.
Options
:model(String.t/0) - Required. ID of the model to use.:input- Required. Text or list of texts to classify.
Examples
iex> Mistral.moderate(client, model: "mistral-moderation-latest", input: "Hello, world!")
{:ok, %{"id" => "...", "model" => "mistral-moderation-latest", "results" => [...]}}
iex> Mistral.moderate(client, model: "mistral-moderation-latest", input: ["First text", "Second text"])
{:ok, %{"id" => "...", "model" => "mistral-moderation-latest", "results" => [...]}}Moderate chat conversations using a Mistral moderation model.
Options
:model(String.t/0) - Required. ID of the model to use.:input- Required. A single conversation (list of messages) or multiple conversations (list of lists of messages) to moderate.
Examples
iex> Mistral.moderate_chat(client,
...> model: "mistral-moderation-latest",
...> input: [%{role: "user", content: "Hello"}]
...> )
{:ok, %{"id" => "...", "model" => "mistral-moderation-latest", "results" => [...]}}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.:bbox_annotation_format- (optional) Structured output for extracting information from each bounding box/image. Only json_schema type is valid.:document_annotation_format- (optional) Structured output for extracting information from the entire document. Only json_schema type is valid.
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" => [...]}}
## Structured Output for OCR
You can extract structured information from documents using annotation formats:
iex> # Extract structured data from bounding boxes
iex> bbox_schema = %{
...> type: "object",
...> title: "BoundingBoxData",
...> properties: %{
...> text: %{type: "string", title: "Text"},
...> confidence: %{type: "number", title: "Confidence", minimum: 0, maximum: 1}
...> },
...> additionalProperties: false
...> }
iex> Mistral.ocr(client,
...> model: "mistral-ocr-latest",
...> document: %{type: "document_url", document_url: "https://example.com/invoice.pdf"},
...> bbox_annotation_format: %{
...> type: "json_schema",
...> json_schema: %{name: "bbox_data", schema: bbox_schema}
...> }
...> )
iex> # Extract document-level structured information
iex> doc_schema = %{
...> type: "object",
...> title: "DocumentInfo",
...> properties: %{
...> title: %{type: "string", title: "Title"},
...> summary: %{type: "string", title: "Summary"},
...> total_pages: %{type: "integer", title: "TotalPages"}
...> },
...> additionalProperties: false
...> }
iex> Mistral.ocr(client,
...> model: "mistral-ocr-latest",
...> document: %{type: "document_url", document_url: "https://example.com/report.pdf"},
...> document_annotation_format: %{
...> type: "json_schema",
...> json_schema: %{name: "document_info", schema: doc_schema}
...> }
...> )@spec res(req_response()) :: response()
Restart a conversation from a specific entry.
Options
:inputs- Required. The input string or list of entry objects.:from_entry_id(String.t/0) - Required. The entry ID to restart from.:stream- When true, returns a stream of response events. The default value isfalse.:stream_timeout(non_neg_integer/0) - Timeout in milliseconds for receiving stream chunks. Defaults to 30000 (30 seconds). The default value is30000.:store(boolean/0) - Whether to store the entries. The default value istrue.:handoff_execution- Handoff execution mode. The default value is"server".:completion_args- (optional) Completion arguments.
Examples
iex> Mistral.restart_conversation(client, "conv_abc123",
...> inputs: "Try again",
...> from_entry_id: "entry_xyz789"
...> )
{:ok, %{"object" => "conversation.response", ...}}
# Stream the response
iex> {:ok, stream} = Mistral.restart_conversation(client, "conv_abc123",
...> inputs: "Try again",
...> from_entry_id: "entry_xyz789",
...> stream: true
...> )
iex> Enum.to_list(stream)
[%{"object" => "conversation.response.started", ...}, ...]Start a fine-tuning job by its ID.
Examples
iex> Mistral.start_fine_tuning_job(client, "ft-abc123")
{:ok, %{"id" => "ft-abc123", "status" => "STARTED", ...}}Unarchive a fine-tuned model.
Examples
iex> Mistral.unarchive_fine_tuned_model(client, "ft:open-mistral-7b:abc123")
{:ok, %{"id" => "ft:open-mistral-7b:abc123", "archived" => false, ...}}Update an agent. Creates a new version of the agent.
Options
:model- Model ID.:name- Agent name.:instructions- System instructions.:tools(list ofmap/0) - Available tools.:completion_args(map/0) - Default completion arguments.:stop- Stop token(s).:presence_penalty(float/0) - Presence penalty (-2 to 2).:frequency_penalty(float/0) - Frequency penalty (-2 to 2).:temperature(float/0) - Temperature (0 to 1).:top_p(float/0) - Top-p sampling (0 to 1).:max_tokens(non_neg_integer/0) - Maximum tokens.:random_seed(non_neg_integer/0) - Random seed.:response_format- Response format.:tool_choice- Tool choice strategy. The default value is"auto".
:description- Agent description.:handoffs- Agent IDs for handoff.:deployment_chat- Deployment chat flag.:metadata- Custom metadata.
Examples
iex> Mistral.update_agent(client, "ag_abc123",
...> name: "Updated Agent",
...> instructions: "New instructions."
...> )
{:ok, %{"id" => "ag_abc123", "name" => "Updated Agent", ...}}Switch an agent to a specific version.
Examples
iex> Mistral.update_agent_version(client, "ag_abc123", 2)
{:ok, %{"id" => "ag_abc123", "version" => 2, ...}}Update a fine-tuned model's name and/or description.
Options
:name(String.t/0) - (optional) New name for the fine-tuned model.:description(String.t/0) - (optional) New description for the fine-tuned model.
Examples
iex> Mistral.update_fine_tuned_model(client, "ft:open-mistral-7b:abc123",
...> name: "My Model",
...> description: "A fine-tuned model"
...> )
{:ok, %{"id" => "ft:open-mistral-7b:abc123", ...}}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", ...}}