README

This PHP library provides a simple wrapper for the Mistral API, allowing you to easily integrate the Mistral API into your PHP projects.

Features

• Easy integration with Mistral API
• Supports all Mistral API endpoints
• Streaming support for real-time responses in chat completions
• Utilizes PSR-17 and PSR-18 compliant HTTP clients and factories for making API requests

Requirements

• PHP 8.1 or higher
• A PSR-17 HTTP Factory implementation (e.g., guzzle/psr7 or nyholm/psr7)
• A PSR-18 HTTP Client implementation (e.g., guzzlehttp/guzzle or symfony/http-client)

Installation

You can install the library via Composer:

composer require softcreatr/php-mistral-ai-sdk

Usage

First, include the library in your project:

<?php

require_once 'vendor/autoload.php';

Then, create an instance of the MistralAI class with your API key, organization (optional), an HTTP client, an HTTP request factory, and an HTTP stream factory:

use SoftCreatR\MistralAI\MistralAI;

$apiKey = 'your_api_key';

// Replace these lines with your chosen PSR-17 and PSR-18 compatible HTTP client and factories
$httpClient = new YourChosenHttpClient();
$requestFactory = new YourChosenRequestFactory();
$streamFactory = new YourChosenStreamFactory();
$uriFactory = new YourChosenUriFactory();

$mistral = new MistralAI($requestFactory, $streamFactory, $uriFactory, $httpClient, $apiKey);

Now you can call any supported MistralAI API endpoint using the magic method __call. The first array argument is reserved for URL/path parameters. If an endpoint has no placeholders you can either provide your request payload directly as the first argument or use the optional second $options array. The examples below use the $options argument to make the intent explicit:

$response = $mistral->createChatCompletion([], [
    'model' => 'mistral-tiny',
    'messages' => [
        [
            'role' => 'user',
            'content' => 'Who is the most renowned French painter?'
        ],
    ],
]);

// Process the API response
if ($response->getStatusCode() === 200) {
    $responseObj = json_decode($response->getBody()->getContents(), true);
    
    print_r($responseObj);
} else {
    echo "Error: " . $response->getStatusCode();
}

Streaming Example

You can enable real-time streaming for chat completions:

$streamCallback = static function ($data) {
    if (isset($data['choices'][0]['delta']['content'])) {
        echo $data['choices'][0]['delta']['content'];
    }
};

$mistral->createChatCompletion([], [
    'model' => 'mistral-small-latest',
    'messages' => [
        [
            'role' => 'user',
            'content' => 'Tell me a story about a brave knight.',
        ],
    ],
    'stream' => true,
], $streamCallback);

When an endpoint requires query-string parameters in addition to a JSON body (for example, promoting an agent to a specific version), include them via the reserved query key inside the $options array: ['query' => ['version' => '2.0.0']].

For more details on how to use each endpoint, refer to the Mistral API documentation, and the examples provided in the repository.

Example Coverage

Every documented endpoint ships with a runnable script under examples/. Newly added directories include examples/audio, examples/batch, examples/agents_beta, examples/conversations, examples/libraries (and examples/libraries/documents), examples/classifiers, and examples/ocr, covering the latest transcription, batch, agents (beta), conversations (beta), knowledge libraries, moderation/classification, and OCR APIs.

Supported Methods

Chat Completions

• Create Chat Completion – Example
  • createChatCompletion(array $parameters = [], array $options = [], ?callable $streamCallback = null)

Audio Transcriptions

• Create Audio Transcription
  • createAudioTranscription(array $parameters = [], array $options = [], ?callable $streamCallback = null)
• Stream Audio Transcription
  • createAudioTranscriptionStream(array $parameters = [], array $options = [], ?callable $streamCallback = null)

Embeddings

• Create Embedding – Example
  • createEmbedding(array $parameters = [], array $options = [])

Models

• List Models
  • listModels(array $parameters = [], array $options = [])
• Retrieve / Delete Model
  • retrieveModel(array $parameters = [], array $options = [])
  • deleteModel(array $parameters = [], array $options = [])
• Fine-tuned Model Lifecycle
  • updateFineTunedModel(array $parameters = [], array $options = [])
  • archiveModel(array $parameters = [], array $options = [])
  • unarchiveModel(array $parameters = [], array $options = [])

Batch Jobs

• Batch Job APIs
  • listBatchJobs(), createBatchJob(array $parameters = [], array $options = [])
  • retrieveBatchJob(array $parameters = []), cancelBatchJob(array $parameters = [])

Files

• File Management – Examples
  • uploadFile(array $parameters = [], array $options = [])
  • listFiles(array $parameters = [], array $options = [])
  • retrieveFile(array $parameters = [], array $options = [])
  • deleteFile(array $parameters = [], array $options = [])
  • downloadFile(array $parameters = [], array $options = [])
  • retrieveFileSignedUrl(array $parameters = [], array $options = [])

Fine-Tuning Jobs

• Fine-Tuning Jobs – Examples
  • listFineTuningJobs(), retrieveFineTuningJob(array $parameters = [])
  • createFineTuningJob(array $parameters = [], array $options = [])
  • cancelFineTuningJob(array $parameters = []), startFineTuningJob(array $parameters = [])

FIM Completion

• Create FIM Completion – Example
  • createFimCompletion(array $parameters = [], array $options = [], ?callable $streamCallback = null)

Agents Completion

• Create Agents Completion – Example
  • createAgentsCompletion(array $parameters = [], array $options = [], ?callable $streamCallback = null)

Agents API (Beta)

• Manage Agents
  • listAgents(), createAgent(array $parameters = [], array $options = [])
  • retrieveAgent(array $parameters = []), updateAgent(array $parameters = [], array $options = [])
  • updateAgentVersion(array $parameters = [], array $options = []), deleteAgent(array $parameters = [])

Conversations API (Beta)

• Conversational Workflows
  • listConversations(), startConversation(array $parameters = [], array $options = [], ?callable $streamCallback = null)
  • retrieveConversation(array $parameters = []), appendConversation(array $parameters = [], array $options = [], ?callable $streamCallback = null)
  • deleteConversation(array $parameters = []), restartConversation(array $parameters = [], array $options = [], ?callable $streamCallback = null)
  • Streaming helpers: startConversationStream, appendConversationStream, restartConversationStream
  • History helpers: listConversationHistory(array $parameters = []), listConversationMessages(array $parameters = [])

Knowledge Libraries (Beta)

• Libraries & Shares
  • listLibraries(), createLibrary(array $parameters = [], array $options = [])
  • retrieveLibrary(array $parameters = []), updateLibrary(array $parameters = [], array $options = [])
  • deleteLibrary(array $parameters = []), listLibraryShares(array $parameters = [])
  • upsertLibraryShare(array $parameters = [], array $options = []), deleteLibraryShare(array $parameters = [])
• Library Documents
  • listLibraryDocuments(array $parameters = []), uploadLibraryDocument(array $parameters = [], array $options = [])
  • retrieveLibraryDocument(array $parameters = []), updateLibraryDocument(array $parameters = [], array $options = [])
  • deleteLibraryDocument(array $parameters = []), retrieveLibraryDocumentStatus(array $parameters = [])
  • retrieveLibraryDocumentTextContent(array $parameters = [])
  • retrieveLibraryDocumentSignedUrl(array $parameters = [])
  • retrieveLibraryDocumentExtractedTextSignedUrl(array $parameters = [])
  • reprocessLibraryDocument(array $parameters = [], array $options = [])

Moderations & Classifications

• Safety & Classifier APIs
  • createModeration(array $parameters = [], array $options = [])
  • createChatModeration(array $parameters = [], array $options = [])
  • createClassification(array $parameters = [], array $options = [])
  • createChatClassification(array $parameters = [], array $options = [])

OCR

• Create OCR Job
  • createOcr(array $parameters = [], array $options = [])

Changelog

For a detailed list of changes and updates, please refer to the CHANGELOG.md file. We adhere to Semantic Versioning and document notable changes for each release.

Known Problems and Limitations

Streaming Support

Streaming is now supported for real-time token generation in chat completions. Please make sure you are handling streams correctly using a callback, as demonstrated in the examples.

License

This library is licensed under the ISC License. See the LICENSE file for more information.

Maintainers 🛠️

Sascha Greuel

Contributors ✨