<p align="center"><img src="./art/header.png"></p>

Laravel Client for Mistral.AI

The Mistral.ai Laravel Client enables laravel applications to interact with the Mistral.ai API, providing straightforward access to features like chat completions and text embeddings.

Get your API key at console.mistral.ai.

Installation

You can install the package via composer:

composer require helgesverre/mistral

You can publish the config file with:

php artisan vendor:publish --tag="mistral-config"

This is the contents of the published config file:

return [
    'api_key' => env('MISTRAL_API_KEY'),
    'base_url' => env('MISTRAL_BASE_URL', 'https://api.mistral.ai'),
    'timeout' => env('MISTRAL_TIMEOUT', 30),
];

Usage

Client Instantiation

Create an instance of the Mistral client to start interacting with the API. This instance will be your primary interface for sending requests to Mistral.AI.

use HelgeSverre\Mistral\Enums\Model;
use HelgeSverre\Mistral\Mistral;

// Instantiate the client
$mistral = new Mistral(apiKey: config('mistral.api_key'));

// Or use the Facade (Laravel)
Mistral::chat();
Mistral::simpleChat();
Mistral::embedding();
Mistral::models();

Examples

The package includes 10 hands-on examples in the examples/ directory, each with detailed documentation, working code, and explanations. These examples are the fastest way to learn the SDK and see it in action.

Quick Start: Begin with 01-getting-started to set up your first working integration.

| Example | Description | |---------|-------------| | 01-getting-started | Install the SDK, configure authentication, and make your first API call | | 02-basic-chat | Learn chat completions, system messages, and multi-turn conversations | | 03-chat-parameters | Master temperature, top_p, max_tokens, and other generation parameters | | 04-streaming-chat | Implement real-time streaming responses with Server-Sent Events | | 05-function-calling | Enable AI to call PHP functions and interact with your application | | 06-embeddings | Generate vector embeddings for semantic search and similarity matching | | 07-ocr | Extract and process text from images and documents using OCR | | 08-audio | Transcribe audio files with support for multiple languages and formats | | 09-moderation | Identify and filter inappropriate content with content moderation | | 10-error-handling | Implement robust error handling, retry logic, and rate limit management |

Each example includes:

• Step-by-step implementation guide
• Complete working code
• Real-world use cases
• Troubleshooting tips
• Links to related examples

To run an example:

cd examples/01-getting-started
php getting-started.php

Available Resources & Methods

The Mistral PHP client provides 14 resource classes, each offering both Response-returning methods and typed DTO methods for convenient type-safe usage.

Chat Resource

Access via $mistral->chat()

Methods:

• create(...): Response - Create a chat completion
• createDto(...): ChatCompletionResponse - Create a chat completion and return typed DTO
• createStreamed(...): Generator - Stream chat completions

Example:

$completion = $mistral->chat()->createDto(
    messages: [['role' => 'user', 'content' => 'Hello!']],
    model: Model::small->value
);

SimpleChat Resource

Access via $mistral->simpleChat()

Methods:

• create(...): SimpleChatResponse - Simplified chat completion (returns flattened DTO directly)
• stream(...): Generator - Stream simplified chat completions

Example:

$response = $mistral->simpleChat()->create(
    messages: [['role' => 'user', 'content' => 'Hello!']],
    model: Model::medium->value
);
echo $response->content; // Direct access to content

Embedding Resource

Access via $mistral->embedding()

Methods:

• create(array $input, ...): Response - Create embeddings
• createDto(array $input, ...): EmbeddingResponse - Create embeddings and return typed DTO

Example:

$embeddings = $mistral->embedding()->createDto([
    'Text to embed',
    'Another text'
]);

Models Resource

Access via $mistral->models()

Methods:

• list(): Response - List available models
• listDto(): ModelList - List models and return typed DTO
• retrieve(string $modelId): BaseModelCard|FTModelCard - Get model details
• delete(string $modelId): DeleteModelOut - Delete a fine-tuned model

Example:

$models = $mistral->models()->listDto();
foreach ($models->data as $model) {
    echo $model->id;
}

OCR Resource

Access via $mistral->ocr()

Methods:

• process(...): Response - Process document with OCR
• processDto(...): OCRResponse - Process and return typed DTO
• processUrl(string $url, ...): Response - Process document from URL
• processUrlDto(string $url, ...): OCRResponse - Process URL and return typed DTO
• processBase64(string $base64, ...): Response - Process base64 encoded document
• processBase64Dto(string $base64, ...): OCRResponse - Process base64 and return typed DTO

Example:

$result = $mistral->ocr()->processUrlDto(
    url: 'https://example.com/document.pdf'
);

FIM Resource (Fill-in-the-Middle)

Access via $mistral->fim()

Methods:

• create(...): Response - Create FIM completion
• createDto(...): FIMCompletionResponse - Create and return typed DTO
• createStreamed(...): Generator - Stream FIM completions

Example:

$completion = $mistral->fim()->createDto(
    model: 'codestral-latest',
    prompt: 'def fibonacci(',
    suffix: '    return result'
);

Agents Resource

Access via $mistral->agents()

Methods:

• create(AgentCreationRequest $request): Response - Create an agent
• createDto(AgentCreationRequest $request): Agent - Create and return typed DTO
• list(?int $page, ?int $pageSize): Response - List agents
• listDto(?int $page, ?int $pageSize): AgentList - List and return typed DTO
• get(string $agentId): Response - Get agent details
• getDto(string $agentId): Agent - Get agent and return typed DTO
• update(string $agentId, AgentUpdateRequest $request): Response - Update agent
• updateDto(string $agentId, AgentUpdateRequest $request): Agent - Update and return typed DTO
• updateVersion(string $agentId, int $version): Response - Switch agent version
• updateVersionDto(string $agentId, int $version): Agent - Switch version and return typed DTO

Conversations Resource

Access via $mistral->conversations()

Methods:

• create(ConversationRequest $request): Response - Create conversation
• createDto(ConversationRequest $request): ConversationResponse - Create and return typed DTO
• createStreamed(ConversationRequest $request): Generator - Create with streaming
• list(?int $page, ?int $pageSize, ?string $order): Response - List conversations
• listDto(...): ConversationList - List and return typed DTO
• get(string $conversationId): Response - Get conversation
• getDto(string $conversationId): ConversationResponse - Get and return typed DTO
• append(string $conversationId, ConversationAppendRequest $request): Response - Append to conversation
• appendDto(...): ConversationResponse - Append and return typed DTO
• appendStreamed(...): Generator - Append with streaming
• getHistory(string $conversationId): Response - Get conversation history
• getHistoryDto(string $conversationId): ConversationHistory - Get history and return typed DTO
• getMessages(string $conversationId): Response - Get conversation messages
• getMessagesDto(string $conversationId): ConversationMessages - Get messages and return typed DTO
• restart(string $conversationId, ConversationRestartRequest $request): Response - Restart conversation
• restartDto(...): ConversationResponse - Restart and return typed DTO
• restartStreamed(...): Generator - Restart with streaming

Audio Resource

Access via $mistral->audio()

Methods:

• transcribe(string $filePath, ...): Response - Transcribe audio
• transcribeDto(string $filePath, ...): TranscriptionResponse - Transcribe and return typed DTO
• transcribeStreamed(string $filePath, ...): Generator - Transcribe with streaming

Example:

$transcription = $mistral->audio()->transcribeDto(
    filePath: '/path/to/audio.mp3',
    model: 'whisper-large-v3'
);

Files Resource

Access via $mistral->files()

Methods:

• upload(string $filePath, ?FilePurpose $purpose): Response - Upload file
• uploadDto(...): UploadFileOut - Upload and return typed DTO
• list(...): Response - List files with filters
• listDto(...): ListFilesOut - List and return typed DTO
• retrieve(string $fileId): Response - Get file metadata
• retrieveDto(string $fileId): RetrieveFileOut - Get metadata and return typed DTO
• delete(string $fileId): Response - Delete file
• deleteDto(string $fileId): DeleteFileOut - Delete and return typed DTO
• download(string $fileId): Response - Download file content
• getSignedUrl(string $fileId, ?int $expiry): Response - Get signed download URL
• getSignedUrlDto(string $fileId, ?int $expiry): FileSignedURL - Get URL and return typed DTO

FineTuning Resource

Access via $mistral->fineTuning()

**