board3r/mistral-sdk

PHP SDK for Mistral.ai API

V1.0.1 2025-02-28 08:32 UTC

Requires

• php: ^8.2
• jasny/phpdoc-parser: ^1.0
• saloonphp/saloon: ^3.10
• stolt/json-lines: ^4.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.69
• pestphp/pest: ^3.7
• phpstan/phpstan: ^2.1
• symfony/var-dumper: ^7.2

MIT

• Maxime DANJOU

• php
• sdk
• ai
• mistral

README

PHP Client for Mistral AI

Introduction

This PHP library provides a straightforward wrapper for the Mistral API, enabling seamless integration of the Mistral API into your PHP projects.

Coming soon :

• Fine tuning API
• Models API
• Batch API

Features

• Easy integration with the Mistral API
• Chat session management
• Support for various Mistral models
• Flexible configuration
• Full Data To Object approach (request and response)
• Trick integration for message functions
• Built-in testing to ensure reliability

Requirements

• PHP 8.2 or higher
• Mistral.ai API key

Installation

You can install the package via Composer:

composer require board3r/mistral-sdk

Usage

To create an instance of the Mistral client and start interacting with the API, you'll need to initialize the client with your API key or any required credentials. This instance will serve as your primary interface for sending requests to Mistral.AI.

Client Instantiation & Simple request

require 'vendor/autoload.php';

use Board3r\MistralSdk\Mistral;
use Board3r\MistralSdk\Dto\Request\ChatCompletionRequest;
use Board3r\MistralSdk\Enums\ModelEnum;

$client = new Mistral('your-api-key');
// Chose the Dto or use a simple array
$request = new ChatCompletionRequest();
// Set some datas
$request->setModel(ModelEnum::small->value);
$request->addUserMessage("Please, help me to have some information about Toulouse")
// make the request
$response = $client->chat()->post($request);
// load the response in to the object
$responseObject = $response->dto();

You also use the API without the DTO

// Chose the Dto or use a simple array
$request = new ChatCompletionRequest();
// make the request
$response = $client->chat()->post(
    [
        'messages'=>[[
            'role'=>'user',
            'content'=>"Please, help me to have some information about Toulouse"
        ]],
        'model'=>'mistral-small-latest'
    ]
);
// load the response into an array
$responseAr = $response->array();

Configuration

Some parameters that you can initiate in the .env file

# Mistral API key can be set directly here or during client instantiation
MISTRAL_API_KEY="[YOUR_API_KEY]"
#  Mistral base url, for Codestral use https://codestral.mistral.ai/v1 and your dedicated api key
MISTRAL_BASE_URL="https://api.mistral.ai/v1"

# Enable session mode for chat messages (available only for chat and agents method) If true the conversation will be keep in session and sent on each call 
MISTRAL_SESSION_ENABLED=false
# Number of user messages to keep in session history
MISTRAL_SESSION_HISTORY=10

# Settings of timeout
MISTRAL_CONNECT_TIMEOUT=30
MISTRAL_REQUEST_TIMEOUT=60

Resources

The resources are directly accessible by the client. They help to send the request and get the response. Call them like that :

// make the request and get response
$response = $client->chat()->post($request);

chat()

• post() | ChatCompletionRequest > ChatCompletionResponse
• postStreamed() | ChatCompletionRequest > ChatCompletionResponse

agents()

• post() | AgentsCompletionRequest > AgentsCompletionResponse
• postStreamed() | AgentsCompletionRequest >~~~~ AgentsCompletionResponse

fim()

• post() | FimCompletionRequest > FimCompletionResponse
• postStreamed() | FimCompletionRequest > FimCompletionResponse

embeddings()

• post() | EmbeddingsRequest > EmbeddingsResponse

classifiers()

• postModeration() | ModerationsRequest > ModerationsResponse
• postChatModeration() | ModerationsChatRequest > ModerationsResponse

files()

• upload() | FileUploadRequest > FileResponse
• list() | FileListRequest > FileListResponse
• get() | FileRequest > FileResponse
• delete() | FileRequest > FileDeleteResponse
• getSignedUrl() | FileSignedUrlRequest > FileSignedUrlRequest
• download() | FileRequest > Binary

Streamed request

The API offer the possibility to steam some response using the method postStreamed().

Below an example to use the stream.

use \Board3r\MistralSdk\Dto\Response\ChatCompletionResponse;
// Returns a generator, which you can iterate over to get the streamed chunks
$stream = $client->chat()->postStreamed($request);

foreach ($stream as $chunk) {

    /** @var ChatCompletionResponse $chunk */
    foreach ($chunk->getChoices() as $choice) {
        $choice->getDelta()->getContent(); // 'Assistant message .'       
    }
}

Chat history Session

Streamed responses are not supported by the Chat history Session.

Use the lazy mode to keep the conversation in session and send it automatically on each request.

Enable session history using the .env configuration or using the helper

use Board3r\MistralSdk\Helpers\HistoryHelper;
HistoryHelper::enable();

To configure the number of messages retained in the conversation history, set a limit on the number of user messages that are stored. While system, assistant, and tool messages will remain in the session, they will not count towards the history limit. This setup helps manage the conversation context efficiently. The limit can be set using the .env configuration or using the helper

use Board3r\MistralSdk\Helpers\HistoryHelper;
HistoryHelper::setParamHistory(10);

If the conversation start with a prompt (system message), this prompt will always be used ast first message and will not be erased from your history.

Data to Objects (DTOs)

The data to object are based on all properties of request or response defined in Mistral.ai API documentation. Each DTOs have a setter and a getter by magical function, so for each property of the API request and response follow this information to set or get the data.

Just use prefix 'set', or 'get' and the API property in PascalCase.

// equivalent to ['model'=>'test']
$dto->setModel('test');
$return = $dto->getModel();
// equivalent to ['presence_penalty'=>1]
$dto->setPressencePenalty(1);
$return = $dto->getPressencePenalty();
// Case with a children property
//equivalent to ['response_format'=>['type'=>'json_object']]
$dto->getResponseFormat()->setType(ResponseFormatEnum::json->value));
// or you can bind directly the DTO
$responseFormat = new ResponseFormat();
$responseFormat->setType(ResponseFormatEnum::json->value);
$dto->setResponseFormat($responseFormat);

$return = $dto->getResponseFormat->getType();

In case of collection, it's possible to bind the array or the object

// equivalent to ['messages'=> [['role'=>'user','content'=>"Information about Toulouse"]]]
$dto->setMessages([['role'=>'user','content'=>"Information about Toulouse"]]);
// or 
$collection = new MessageCollection([['role'=>'user','content'=>"Information about Toulouse"]]);
$dto->setMessages(MessageCollection);
// or
$dto->getMessages()->append(['role'=>'user','content'=>"Information about Toulouse"]);
// or
$message = new Message();
$message->setRole(RoleEnum::user->value);
$message->setContent("Information about Toulouse");
$dto->getMessages()->append($message);

// get all collection 
$return = $dto->getMessages();
// or to get the first message only (can throw not defined)
$return = $dto->getMessages()[0];
// equivalent to (return null if not defined)
$return = $dto->getMessages()->get(0);
// count number of messages
$count = $dto->getMessages()->count()
// or
$count = count($dto->getMessages());

// browse the collection
foreach($dto->getMessages() AS $message){
...
}

Each DTO can be converted to array or json

$ar = $dto->toArray();

$json = $dto->toJson();
// or
$json = (string)$dto;

Some DTO have shortcut function to lazy bind or get data, each function will be described below.

Request Data to Objects

Chat

ChatCompletionRequest

For addFunction() Message's Function trick

// Add tool function in your call
$request->addFunction(callable $callable, ?string $description = null, ?array $paramDesc = null, ?bool $strict = null);
// Add a message with user role
$request->addUserMessage(string|array $message, ?string $type = null);
// Add a message with assistant role
$request->addAssistantMessage(string|array $message, ?string $type = null, ToolCallCollection|array|null $toolCall = null, ?bool $prefix = null);
// Add a message with system role
$request->addSystemMessage(string|array $message);
// Add a message with tool role
$request->addToolMessage(string|array $message, ?string $type = null, ?string $name = null, ?string $toolCallID = null);

Agents

AgentsCompletionRequest

See ChatCompletionRequest

FIM

FimCompletionRequest

Embeddings

EmbeddingsRequest

Classifiers

ModerationsChatRequest

ModerationsRequest

Files

FileListRequest

FileRequest

FileSignedUrlRequest

FileUploadRequest

// To upload a file, just give the path, by default the file will be validate before to send it. The format and the data will be check.
$request->setFile(string $filepath,bool $validate = true);

Response Data to Objects

All properties referer to a timestamp (created, created_at) will return automatically a DateTime object, or a string with formated date if you pass the arguments format calling the method.

$dateTimeObject = $request->getCreated();

$dateFormated = $request->getCreated("Y-m-d H:i:s");

Chat

ChatCompletionResponse

Agents

AgentsCompletionResponse

FIM

FimCompletionResponse

Embeddings

EmbeddingsResponse

Classifiers

ModerationsResponse

// Get the moderation scoring with a float by category Name. You can use ClassificationEnum 
$request->getScore(string $catName); 
// Get a boolean to know if the message is moderate or not by category name.
$request->getModeration(string $catName);

Files

FileResponse

FileSignedUrlResponse

FileListResponse

FileDeleteResponse

Errors

//All errors get the ErrorInterface with this method. Get the error information message.
$error->getErrorMessage();

BasicError

ValidationError

RequestError

Message's Function trick

In Chat and Agents API request you can set a function calling the method setFunction() on the DTO.

This method will set the property 'tools' in the API request Some explanation here about this use.

class MyClass
{
    public static function myFunction(string $param1, ?int $param2 = null): string
    {
        ...
        return $result;
    }
}
// The first parameter must be a callable
$request->addFunction(callable:[MyClass::class,'myFunction'],
                      description:'Give a good description about the function',
                      paramDesc :['param1'=>'Give a good description for param1',
                                  'param2'=>'Give a good description for param2'],
                      strict:true);

Using PHP Doc block, all the block are optional, if they are not set, the information about the function will be built by the reflexion class and the parameters $description and $paramDesc when the method setFunction() is called.

• @mistralName : Alternative name of the function
• @mistralDesc : Good description of the function for Mistral.ai
• @mistralParam format $paramName : Good description of the parameter for Mistral.ai
• @mistralJSON paramName : json based on https://json-schema.org/ to define the parameter, let you use other attributes like enum, regex...
• @mistralRequired $paramName : To make the parameter required in Mistral.ai
• @mistralStrict : Activate the strict mode for the function in Mistral.ai

class MyClass
{
    /**
     * @mistralName myFunction
     * @mistralDesc Give a good description about the function
     * @mistralParam string $param1 Give a good description for param1
     * @mistralJSON param2 {"type": "number","description": "Give a good description about "}
     * @mistralRequired $param1
     * @mistralStrict
     **/
    public static function myFunction(string $param1, ?int $param2 = null): string
    {
        ...
        return $result;
    }
}

$request->setFunction([MyClass::class,'myFunction'],);

Model Enums

Use your model accessing by enum

use \Board3r\MistralSdk\Enums\ModelEnum;

$request->setModel(ModelEnum::large->value);

Premium Models:

• codestral = 'codestral-latest'
• large = 'mistral-large-latest'
• pixtral = 'pixtral-large-latest'
• saba = 'mistral-saba-latest'
• ministral3b = 'ministral-3b-latest'
• ministral8b = 'ministral-8b-latest'
• embed = 'mistral-embed'
• moderation = 'mistral-moderation-latest'

Free Models:

• small = 'mistral-small-latest'
• pixtral12b = 'pixtral-12b-2409'

Research Models:

• nemo = 'open-mistral-nemo'
• mamba = 'open-codestral-mamba'

Legacy Models:

• mistral7b = 'open-mistral-7b'
• mixtral8x7b = 'open-mixtral-8x7b'
• mixtral8x22B = 'open-mixtral-8x22b'
• medium = 'mistral-medium-2312'
• small2402 = 'mistral-small-2402'
• large2402 = 'mistral-large-2402'
• large2407 = 'mistral-large-2407'
• codestral2405 = 'codestral-2405'

Testing

To run tests, use Pest:

vendor/bin/pest

Changelog

For a detailed list of changes and updates, please refer to the CHANGELOG file.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Disclaimer

Mistral and the Mistral logo are trademarks of Mistral.ai. This package is not affiliated with, endorsed by, or sponsored by Mistral.ai. All trademarks and registered trademarks are the property of their respective owners.

See Mistral.AI for more information.

Special Thanks

This package is inspired by Helge Sverre's Mistral.

And their code helped me :

• Saloon PHP / Simplify all the API requests
• Arnold Daniels / Help me to read PHP doc block
• Raphael Stolt / Help me to read Jsonl Files