Getting Started

Minimal Setup

Install Dependencies:
```
composer require symfony/ai-amazeeai-platform
```
Ensure symfony/ai is also installed (required).

Configure Provider: Add amazee.ai/LiteLLM API key to your Symfony config (e.g., .env):

AI_AMAZEEAI_API_KEY=your_amazee_ai_key
AI_AMAZEEAI_PROXY_URL=https://proxy.amazee.ai/v1

Basic Usage: Inject the client into a service and make a completion request:

use Symfony\AI\Client\ClientInterface;
use Symfony\AI\Client\OpenAI\ChatCompletion;

public function __construct(private ClientInterface $aiClient) {}

public function generateResponse(): string {
    $chat = new ChatCompletion('gpt-3.5-turbo', [
        new ChatMessage('user', 'Hello!'),
    ]);
    return $this->aiClient->complete($chat)->getContent();
}

Verify Integration:
- Test with a simple prompt (e.g., "Tell me a joke").
- Check response format matches OpenAI’s structure.

First Use Case: Chatbot

Replace a direct OpenAI call in a chatbot service:

// Before (direct OpenAI)
$response = Http::withHeaders(['Authorization' => 'Bearer '.$apiKey])
    ->post('https://api.openai.com/v1/chat/completions', [...]);

// After (amazee.ai bridge)
$chat = new ChatCompletion('gpt-3.5-turbo', [new ChatMessage('user', $input)]);
$response = $this->aiClient->complete($chat)->getContent();

Implementation Patterns

Core Workflows

1. Provider Configuration

Define supported models in a Provider class (extend Symfony\AI\Client\ProviderInterface):

use Symfony\AI\Client\ProviderInterface;
use Symfony\AI\Client\OpenAI\ChatCompletion;

class AmazeeAIProvider implements ProviderInterface {
    public function complete(ChatCompletion $completion): ChatCompletion {
        $response = Http::post($this->proxyUrl, [
            'body' => $completion->toArray(),
            'headers' => ['Authorization' => 'Bearer '.$this->apiKey],
        ]);
        return ChatCompletion::fromArray($response->toArray());
    }
}

# config/services.yaml
services:
    Symfony\AI\Client\ClientInterface:
        arguments:
            $provider: '@amazee_ai.provider'

2. Model Routing

Use FallbackModelCatalog to define fallback logic (e.g., gpt-4 → mistral-7b):

use Symfony\AI\Client\FallbackModelCatalog;

$catalog = new FallbackModelCatalog([
    'gpt-4' => ['primary' => 'gpt-4', 'fallback' => 'mistral-7b'],
    'gpt-3.5-turbo' => ['primary' => 'gpt-3.5-turbo'],
]);

$this->aiClient->setModelCatalog($catalog);

3. Streaming Responses

Handle streaming with DeltaInterface:

use Symfony\AI\Client\Streaming\StreamingResponse;

$response = $this->aiClient->streamComplete($chat);
foreach ($response as $delta) {
    if ($delta instanceof DeltaInterface) {
        echo $delta->getContent(); // Process incremental updates
    }
}

4. Laravel Integration (Symfony Bridge)

Wrap Symfony’s Client in a Laravel service:

// app/Services/AmazeeAIService.php
namespace App\Services;

use Symfony\AI\Client\ClientInterface;
use Symfony\Component\HttpClient\HttpClient;

class AmazeeAIService {
    public function __construct() {
        $client = HttpClient::create();
        $this->aiClient = new ClientInterface(
            new AmazeeAIProvider($client, config('amazee.ai.key'))
        );
    }

    public function generate(string $prompt): string {
        return $this->aiClient->complete(
            new ChatCompletion('gpt-3.5-turbo', [new ChatMessage('user', $prompt)])
        )->getContent();
    }
}

Integration Tips

Symfony-Specific

Dependency Injection: Prefer constructor injection for ClientInterface.

Configuration: Centralize API keys in config/packages/ai.yaml:

amazee_ai:
    api_key: '%env(AI_AMAZEEAI_API_KEY)%'
    proxy_url: '%env(AI_AMAZEEAI_PROXY_URL)%'

Events: Listen to AiEvent for observability (e.g., log completions):

use Symfony\AI\Event\AiEvent;

$dispatcher->addListener(AiEvent::COMPLETION, function (AiEvent $event) {
    logger()->info('AI Completion', ['model' => $event->getModel()]);
});

Laravel-Specific

Service Binding: Bind the Symfony client to Laravel’s container:

$app->singleton(ClientInterface::class, function ($app) {
    return new ClientInterface(new AmazeeAIProvider(
        HttpClient::create(),
        $app['config']['amazee.ai.key']
    ));
});

Facade Pattern: Create a facade for cleaner syntax:

// app/Facades/AmazeeAI.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class AmazeeAI extends Facade {
    protected static function getFacadeAccessor() {
        return 'amazee.ai.client';
    }
}

Usage:

$response = AmazeeAI::generate('Hello!');

Model Catalog Management

Dynamic Routing: Extend FallbackModelCatalog for custom logic:

class CostOptimizedCatalog extends FallbackModelCatalog {
    public function getModel(string $requestedModel): string {
        if (str_contains($requestedModel, 'gpt-4') && auth()->user()->isPremium()) {
            return $requestedModel;
        }
        return 'mistral-7b'; // Default fallback
    }
}

Testing

Mock Providers: Use MockClient for unit tests:

use Symfony\AI\Client\MockClient;

$mockClient = new MockClient();
$mockClient->expects($this)
    ->complete($chat)
    ->willReturn(new ChatCompletion('gpt-3.5-turbo', [new ChatMessage('assistant', 'Mocked response')]));

$this->aiClient->setClient($mockClient);

Gotchas and Tips

Pitfalls

1. Provider Abstraction Mismatch

Issue: Symfony’s ProviderInterface expects OpenAI-compatible responses. Non-compliant providers (e.g., custom LLMs) may break.

Fix: Validate responses with ChatCompletion::fromArray() or extend the trait:

use Symfony\AI\Client\OpenAI\CompletionsConversionTrait;

class CustomProvider implements ProviderInterface {
    use CompletionsConversionTrait;

    public function complete(ChatCompletion $completion): ChatCompletion {
        $response = $this->callCustomLlm($completion);
        return $this->convertCompletionsResponse($response);
    }
}

2. Streaming Quirks

Issue: DeltaInterface may not handle all provider-specific streaming formats (e.g., non-OpenAI-compatible chunks).

Fix: Normalize streams in the provider:

public function streamComplete(ChatCompletion $completion): StreamingResponse {
    $stream = $this->callStreamingEndpoint($completion);
    yield from $this->normalizeStream($stream);
}

private function normalizeStream(iterable $stream): iterable {
    foreach ($stream as $chunk) {
        yield new DeltaInterface($chunk['content'] ?? '');
    }
}

3. Laravel-Symfony Collisions

Issue: Symfony’s HttpClient may conflict with Laravel’s Http facade.

Fix: Explicitly use Symfony’s client:

use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create();
$this->aiClient = new ClientInterface(new AmazeeAIProvider($client, $apiKey));

4. Model Catalog Overrides

Issue: Fallback logic may not trigger if the primary model succeeds silently (e.g., rate-limited).

Fix: Implement retry logic with fallback:

try {
    return $this->aiClient->complete($chat);
} catch (RateLimitException $e) {
    $chat->setModel('mistral-7b'); // Force fallback
    return $this->aiClient->complete($chat);
}

5. API Key Leaks

Issue: Hardcoded keys in provider classes risk exposure.
Fix: Use environment variables and

Ai Amazee Ai Platform Laravel Package