Ai Ollama Platform Laravel Package

Getting Started

Minimal Setup for Laravel

1. Install the Package

   composer require symfony/ai-ollama-platform
   

   Note: Laravel lacks native Symfony AI integration, so this is a "low-level" package. Use it for HTTP calls only.

2. Configure Ollama Client Create a service to wrap the Symfony client with Laravel’s HTTP client:

   // app/Services/OllamaService.php
   use Symfony\Component\AI\Ollama\OllamaClient;
   use Illuminate\Support\Facades\Http;
   
   class OllamaService
   {
       public function __construct()
       {
           $this->client = new OllamaClient(
               Http::macro('createClient', fn() => Http::client())
           );
       }
   
       public function chat(string $model, string $message): string
       {
           return $this->client->chat($model, [$message]);
       }
   }
   

3. Register the Service Bind it in AppServiceProvider:

   public function register()
   {
       $this->app->singleton(OllamaService::class, fn($app) => new OllamaService());
   }
   

4. First Use Case: Chat Completion

   use App\Services\OllamaService;
   
   $response = app(OllamaService::class)->chat('llama3', 'Explain Laravel 11 features.');
   echo $response;
   

5. Where to Look Next

   • Ollama API Docs (for model-specific parameters).
   • OllamaClient methods: generate(), embed(), list().
   • Symfony AI’s Provider abstraction (for advanced routing).

Implementation Patterns

Core Workflows

1. Chat Completions (Synchronous)

// Basic chat
$response = $ollama->chat('llama3', ['What is Laravel?']);

// With structured output (v0.7.0+)
$response = $ollama->chat('llama3', [
 'What are Laravel 11 features?',
], [
 'options' => ['structured_output' => true],
]);

2. Streaming Responses (NDJSON)

use Symfony\Component\AI\Streaming\StreamingResponse;

$stream = $ollama->chatStream('llama3', ['Explain Symfony AI.']);

foreach ($stream as $delta) {
    echo $delta->getContent(); // Incremental output
}

Laravel Tip: Use Swoole or ReactPHP for async streaming in Laravel’s request lifecycle.

3. Embeddings for Search

$embeddings = $ollama->embed('llama3', ['vectorize this text']);
// Process embeddings for vector search (e.g., with Laravel Scout).

4. Model Routing (v0.8.0+)

// Define a provider to route models dynamically
use Symfony\Component\AI\Ollama\ModelProviderInterface;

class LaravelModelProvider implements ModelProviderInterface
{
    public function getModel(string $name): string
    {
        return match ($name) {
            'math' => 'llama3:8b',
            default => 'llama3',
        };
    }
}

// Inject into OllamaClient
$client = new OllamaClient($httpClient, new LaravelModelProvider());

Integration Tips

Laravel-Specific Adaptations

• HTTP Client: Replace Symfony’s HttpClient with Laravel’s Http facade by overriding the client factory:

  $client = new OllamaClient(
      Http::macro('createClient', fn() => Http::client())
  );
  

• Error Handling: Wrap calls in try-catch for Ollama-specific exceptions:

  try {
      $response = $ollama->chat('nonexistent-model', ['...']);
  } catch (\Symfony\Component\AI\Exception\OllamaException $e) {
      report($e);
      return back()->withError('Model not found.');
  }
  

• Configuration: Store Ollama server URL in .env:

  OLLAMA_URL=http://localhost:11434
  

  Then inject it into the client:

  $client = new OllamaClient(
      Http::baseUrl(config('ollama.url'))
  );
  

Common Use Cases

Testing

• Unit Tests: Mock OllamaClient and test Laravel services:

  $mockClient = Mockery::mock(OllamaClient::class);
  $mockClient->shouldReceive('chat')
             ->andReturn('Mock response');
  
  $service = new OllamaService($mockClient);
  

• Integration Tests: Spin up a Dockerized Ollama instance for end-to-end tests:

  docker run -d -p 11434:11434 ollama/ollama
  

  Then test against http://localhost:11434.

Gotchas and Tips

Pitfalls

1. Symfony-Specific Abstractions

• Issue: The package assumes Symfony’s HttpClient, AI component, and Messenger.
• Fix: Wrap dependencies as shown above. Avoid using ProviderInterface directly unless you replicate Symfony’s DI container.

2. Streaming in Laravel

• Issue: NDJSON streaming may block Laravel’s synchronous request lifecycle.
• Fix:
  • Use Swoole or ReactPHP for async streaming:

    $loop = React\EventLoop\Factory::create();
    $consumer = new React\AI\OllamaStreamConsumer($ollama->chatStream(...));
    $loop->run();
    

  • For WebSocket UIs, broadcast chunks via Laravel Echo:

    $stream->onDelta(fn($delta) => broadcast(new OllamaDelta($delta))->toOthers());
    

3. Model Catalog Management

• Issue: OllamaApiCatalog requires network calls to list models.
• Fix: Cache the catalog in Laravel’s cache or database:

  $catalog = Cache::remember('ollama_models', now()->addHours(1), fn() =>
      new OllamaApiCatalog($ollama->list())
  );
  

4. Audio/Multimodal Quirks

• Issue: Models like gemma:2b require base64-encoded audio input.
• Fix: Use Laravel’s Storage facade to encode files:

  $audioBase64 = base64_encode(
      file_get_contents(storage_path('app/audio.wav'))
  );
  $response = $ollama->chat('gemma:2b', [$audioBase64]);
  

5. PHP Version Mismatches

• Issue: The package targets PHP 8.1+, but Laravel 8.x uses PHP 7.4.
• Fix: Upgrade PHP or use a polyfill for Stringable interfaces:

  composer require symfony/polyfill-stringable
  

Debugging Tips

Common Errors and Fixes

Logging

Enable debug logging for Ollama requests