Research new Mistral client

Other proposed solutions from #3460283: Build custom client for Mistral or switch to HelgeSverre lib

* Build our own Guzzle Client for Mistral that can forward errors to an exception.
* (or) try this out: https://github.com/HelgeSverre/mistral

Comparing https://github.com/HelgeSverre/mistral and https://github.com/partITech/php-mistral

php-mistral:

• php-mistral is well supported, includes tool calling, but also more sophisticated le-platform APIs like OCR
• not very popular, but well maintained
• code-base is solid, MIT licensed, comes with test-coverage
• not very popular, but has frequent releases, issues are answered! https://github.com/partITech/php-mistral/issues/78
• solid docs website: https://php-mistral.partitech.com - also covers using the same lib with other providers. in total quite some docs!

HelgeSverre/mistral

• no frequent releases. new 2.0.0 tagged in october, no release since then. Before the latest 1.x release was in 2024!
• no activity for the last two months at all
• not very popular also, even less it seems. it has 6 issues in total created, vs 27 in php-mistral
• documentation is in markdown format in docs directory. Covers important topics also, but not as solid / nicely prepared as done by php-mistral

Then, I've used claude code to help me comparing the libraries, here the result:

Mistral API Client Comparison

| Aspect | HelgeSverre/mistral | partITech/php-mistral |
| --- | --- | --- |
| Package Name | helgesverre/mistral | partitech/php-mistral |
| Version | v2.0.0 (Oct 2025) | v0.1+ (Dec 2025 - actively maintained) |
| GitHub Stars | 49 ⭐ | 25 ⭐ |
| Last Updated | Oct 21, 2025 | Dec 3, 2025 (more recent) |
| License | MIT | MIT |

Dependencies & Compatibility

| Aspect | HelgeSverre/mistral | partITech/php-mistral |
| --- | --- | --- |
| PHP Version | ^8.2 ⚠️ | \>=8.2 ⚠️ |
| Framework | Laravel-specific 🔴 | Framework-agnostic ✅ |
| Core Dependencies | • saloonphp/laravel-plugin• spatie/laravel-data• spatie/laravel-package-tools | • PSR-18 HTTP client (any)• PSR-7 (nyholm/psr7)• Symfony/mime ^6.3 |
| HTTP Client | Saloon (Laravel) | Any PSR-18 client (Guzzle, Symfony, cURL) ✅ |
| Your Project Compatibility | ❌ INCOMPATIBLE(Requires Laravel, you use Drupal) | ✅ COMPATIBLE(Framework-agnostic, works with Symfony) |
| PHP Version Issue | Your project: \>=8.1Package needs: ^8.2 | Your project: \>=8.1Package needs: \>=8.2 |

Features

| Feature | HelgeSverre/mistral | partITech/php-mistral |
| --- | --- | --- |
| Chat Completions | ✅ Streaming & non-streaming | ✅ Streaming & non-streaming |
| Tool/Function Calling | ✅ Standard tool calling | ✅ Advanced MCP support 🌟 |
| MCP (Model Context Protocol) | ❌ | ✅ Full MCP integration 🌟 |
| Tool Recursion Safety | ❌ | ✅ setMcpMaxRecursion() |
| Embeddings | ✅ Dense only | ✅ Dense + Sparse (Splade) |
| Reranking | ❌ | ✅ |
| Guided JSON | ❌ | ✅ |
| Audio/Transcription | ✅ | ✅ (via supported backends) |
| OCR | ✅ | ✅ (via supported backends) |
| Fine-tuning | ✅ | ✅ |
| Files API | ✅ | ✅ |
| Batch Jobs | ✅ | ✅ |
| Agents | ✅ | ✅ |
| Conversations | ✅ | ✅ |
| Moderation | ✅ | ✅ |
| Multi-backend Support | Mistral only | Mistral, OpenAI, HF TGI, vLLM, Ollama, llama.cpp, xAI ✅ |
| Hugging Face Datasets | ❌ | ✅ Full dataset management |
| Document Generation | ❌ | ✅ |

Code Quality & Testing

| Aspect | HelgeSverre/mistral | partITech/php-mistral |
| --- | --- | --- |
| Testing Framework | Pest PHP | PHPUnit |
| Test Structure | • ArchTest• 15 Resource tests• Connector tests | • Functional tests• Unit tests• Client-specific tests |
| Test Coverage | ✅ Good (15+ test files) | ✅ Good (Functional + Unit) |
| Static Analysis | ✅ PHPStan + Larastan | ✅ PHPStan |
| Code Style | ✅ Laravel Pint | Not specified |
| Examples | ✅ 10 detailed examples with docs | ✅ Multiple examples by client type |
| Documentation | ✅ Excellent (744-line README, comprehensive API reference) | ✅ Good (links to external docs site) |
| Typed DTOs | ✅ Full DTO support with \*Dto() methods | Partial |

Tool Calling Support (Critical for Your Needs)

| Feature | HelgeSverre/mistral | partITech/php-mistral |
| --- | --- | --- |
| Basic Tool Calling | ✅ Yes | ✅ Yes |
| Tool Definition | Standard JSON schema | Standard JSON schema + MCP |
| Tool Response Handling | Manual processing | Manual + MCP auto-execution |
| MCP Protocol | ❌ Not supported | ✅ Full MCP support |
| External Tool Servers | ❌ | ✅ Docker/exec MCP runners |
| Recursion Protection | ❌ | ✅ setMcpMaxRecursion() |
| Tool Call Examples | ✅ Detailed in examples/05-function-calling | ✅ Via MCP integration |

Architecture

| Aspect | HelgeSverre/mistral | partITech/php-mistral |
| --- | --- | --- |
| Design Pattern | Resource-based API wrapper | Multi-client abstraction |
| Service Provider | Laravel only | None (framework-agnostic) |
| HTTP Abstraction | Saloon PHP | PSR-18 (any client) |
| Extensibility | Laravel ecosystem | PSR standards |

---

Recommendation for Your Drupal Project

🏆 Winner: partITech/php-mistral

Reasons:

1. ✅ Framework Compatibility: Works with Drupal (you have Symfony components already)
2. ✅ PSR-18 Support: Can use Symfony HttpClient or Guzzle (both common in Drupal)
3. ✅ MCP Support: Advanced tool calling with Model Context Protocol - superior for complex tool interactions
4. ✅ Multi-backend: Works with multiple AI providers, not just Mistral
5. ✅ More Features: Reranking, sparse embeddings, guided JSON, HF datasets

Concerns:

* Both require PHP 8.2, your project specifies \>=8.1 (minor upgrade needed)
* Less GitHub stars (but more recently maintained)
* Slightly less polished documentation than HelgeSverre's

Why NOT HelgeSverre/mistral:

* ❌ Laravel-specific dependencies - Won't work in Drupal without Laravel
* ❌ Requires Laravel service container and packages
* ❌ Not suitable for framework-agnostic use

Action Items:

1. Upgrade project PHP requirement to ^8.2 in composer.json
2. Install partitech/php-mistral
3. Choose HTTP client (recommend Symfony HttpClient since you already use Symfony components)
4. Leverage MCP support for advanced tool calling needs

\-----------------------------

The laravel dependencies rule out HelgeSverre/mistral. But also otherwise, partITech/php-mistral is the winner. Even it turns out becoming un-maintained, it seems to be a solid to base we could continue with. I'd propose to go with php-mistral!

So in the MR I've adapted the code to use the https://github.com/partITech/php-mistral
And also fixed some cspell and phpcs errors.

From what I could test, it works well, but it needs more in-depth testing, especially for cases where there are failures

Also, we have a failing "composer (previous major)" gitlab-ci due to php version - partITech/php-mistral requires php >=8.2
So we would have to drop support for drupal 10, or have a new release with php-mistral, and keep the old release for the drupal 10 compatibilty.

I would agree with bumping php requirement here. I've added an explicit requirement for a minimum of PHP 8.2 in composer.json.

As far as I'm concerned, it is ready for review.

Thanks, I've applied the suggestions.