README

A lightweight Symfony bundle to integrate with Mistral AI APIs. It provides:

• A configurable HTTP client (MistralClient) with typed options
• A high-level service (Mistral) with DTOs for requests and responses
• Support for standard chat completions and server-sent events (streaming)
• OCR (Document AI) convenience method with helpers to build payloads

This bundle targets Symfony 7.3 and PHP 8.2+.

Requirements

• PHP 8.2+
• Symfony 7.3 components: framework-bundle, http-client, serializer, validator, property-access, property-info

Installation

• Install via Composer:

composer require kap/mistral-bundle

The bundle is a modern Symfony bundle (extends AbstractBundle) and is auto-registered when installed.

Configuration

Create config/packages/kap_mistral.yaml:

kap_mistral:
  api_key: '%env(MISTRAL_API_KEY)%'
  base_uri: 'https://api.mistral.ai' # optional, default shown
  default_model: 'mistral-small-latest' # one of MistralModelEnum values

• api_key: required, your Mistral API key
• base_uri: optional, defaults to https://api.mistral.ai
• default_model: optional, any value from Kap\MistralBundle\Enum\MistralModelEnum

Available model enum values (see Kap\MistralBundle\Enum\MistralModelEnum):

• ministral-3b-latest
• ministral-8b-latest
• mistral-small-latest
• open-mistral-7b
• open-mixtral-8x7b
• open-mixtral-8x22b
• pixtral-large-latest
• pixtral-12b
• devstral-small-2507
• voxtral-small-latest
• voxtral-mini-latest
• mistral-medium-latest
• mistral-large-latest
• mistral-saba-latest

Services

The bundle registers and exposes the following public services:

• Kap\MistralBundle\Mistral: High-level service with convenient methods and DTOs
• Kap\MistralBundle\Client\MistralClientInterface: Low-level client interface
• Kap\MistralBundle\Client\MistralClient: Concrete HTTP client (aliased to the interface)

Both Mistral and MistralClientInterface are public and can be fetched from the container.

Usage

Chat completion (non-streaming)

use Kap\MistralBundle\DTO\ChatRequestDTO;
use Kap\MistralBundle\Mistral;

public function ask(Mistral $mistral): string
{
    $dto = new ChatRequestDTO(
        messages: [
            ['role' => 'user', 'content' => 'Explain Symfony bundles in one sentence.'],
        ],
        temperature: 0.3,
        maxTokens: 512,
        topP: null,
        model: null,     // use default configured model
        stream: false,
        safePrompt: false,
        systemPrompt: 'You are a helpful assistant.'
    );

    $response = $mistral->chat($dto);

    return $response->content; // string
}

The ChatResponseDTO also exposes: model, finishReason, promptTokens, completionTokens, totalTokens, latencyMs. If you enable the Mistral service to include raw responses (constructor flag), rawResponse will contain the full decoded API payload.

Chat completion (streaming)

use Kap\MistralBundle\DTO\ChatRequestDTO;
use Kap\MistralBundle\Mistral;

public function stream(Mistral $mistral): void
{
    $dto = new ChatRequestDTO(
        messages: ['Stream a haiku about autumn winds.'],
        stream: true,
    );

    foreach ($mistral->chatStream($dto) as $chunk) {
        echo $chunk->content;        // partial token
        // $chunk->model (string|null), $chunk->finishReason (string|null), $chunk->usage (array|null)
    }
}

Note: chat() requires stream=false and will throw if a streaming response is returned by the API. chatStream() requires stream=true and will throw if a non-stream response is returned.

OCR (Document AI)

use Kap\MistralBundle\Mistral;
use Kap\MistralBundle\Enum\MistralOCRModelEnum;

public function ocrExample(Mistral $mistral): void
{
    // You can pass a file path/URL/base64 string, or build a MistralOCRDocumentDTO via helper
    $result = $mistral->ocr(
        document: '/absolute/path/to/document.pdf',
        model: MistralOCRModelEnum::DOCUMENT_AI,
        options: [
            'include_image_base64' => true,
            'pages' => [1, 2, 3],
        ]
    );

    foreach ($result->pages as $page) {
        $markdown = $page->markdown; // string|null
        // $page->images, $page->dimensions, etc.
    }
}

The Mistral service validates response structure and will throw a Kap\MistralBundle\Exception\MistralException if required fields (like model) are missing.

Testing

The repository includes functional tests using a minimal testing kernel. To run locally:

composer install
vendor/bin/phpunit

If you add or change autoload rules, regenerate the Composer autoloader:

composer dump-autoload -o

Configuration Reference

For completeness, here is the reference as defined by the bundle:

• kap_mistral.api_key (string, required, not empty)
• kap_mistral.base_uri (string, default: https://api.mistral.ai)
• kap_mistral.default_model (enum string, defaults to mistral-small-latest)

Links

• Documentation
• License: MIT (see LICENSE)