Add AI provider abstraction and asset storage (tasks #33, #34)

AiProviderDriver: one generic interface (generate(prompt, options) ->
AiGenerationResult) rather than per-capability interfaces, since text
(OpenAI chat completions), image (StabilityAI stable-image), and
speech (ElevenLabs TTS) generation all reduce to prompt-in/content-out.
Drivers throw AiGenerationException on failure; AiProviderManager
resolves the right driver from an AiProvider record's `provider`
column and guards on is_active. Real request/response shapes per each
provider's API, verified with Http::fake() — no live API keys
available yet to smoke test against the real services.

AssetStorage: stores generated content under
video-projects/{id}/{type}/v{n}.{ext}, versioned per (project, type[,
step]) slot so retries don't clobber earlier output, plus
contents/url/delete and pruneOldVersions for cleanup.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

app/Providers/AppServiceProvider.php

@@ -2,6 +2,10 @@
 
 namespace App\Providers;
 
+use App\Support\AiProviders\AiProviderManager;
+use App\Support\AiProviders\ElevenLabsDriver;
+use App\Support\AiProviders\OpenAiDriver;
+use App\Support\AiProviders\StabilityAiDriver;
 use App\Support\Publishing\LinkedInPublisher;
 use App\Support\Publishing\PublisherManager;
 use App\Support\Publishing\RedditPublisher;
@@ -22,6 +26,12 @@ class AppServiceProvider extends ServiceProvider
             $app->make(TwitterPublisher::class),
             $app->make(LinkedInPublisher::class),
         ]));
+
+        $this->app->singleton(AiProviderManager::class, fn ($app) => new AiProviderManager([
+            'openai' => $app->make(OpenAiDriver::class),
+            'stability_ai' => $app->make(StabilityAiDriver::class),
+            'elevenlabs' => $app->make(ElevenLabsDriver::class),
+        ]));
     }
 
     /**

app/Support/AiProviders/AiGenerationException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace App\Support\AiProviders;
+
+use RuntimeException;
+
+class AiGenerationException extends RuntimeException {}

app/Support/AiProviders/AiGenerationResult.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Support\AiProviders;
+
+final class AiGenerationResult
+{
+    /**
+     * @param  string  $content  Text or raw binary bytes, depending on $contentType.
+     * @param  array<string, mixed>  $raw  The provider's decoded response, for debugging/metadata.
+     */
+    public function __construct(
+        public readonly string $content,
+        public readonly string $contentType,
+        public readonly array $raw = [],
+    ) {}
+}

app/Support/AiProviders/AiProviderDriver.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Support\AiProviders;
+
+use App\Models\AiProvider;
+
+interface AiProviderDriver
+{
+    /**
+     * Generate content from a prompt. What "content" means depends on the
+     * provider — text for a text generator, image bytes for an image
+     * generator, audio bytes for a speech synthesizer. $options overrides
+     * $provider->config for this call only (e.g. model, voice_id).
+     *
+     * @param  array<string, mixed>  $options
+     *
+     * @throws AiGenerationException on any failure (bad credentials,
+     *                                unreachable API, rejected prompt, unexpected response shape).
+     */
+    public function generate(AiProvider $provider, string $prompt, array $options = []): AiGenerationResult;
+}

app/Support/AiProviders/AiProviderManager.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Support\AiProviders;
+
+use App\Models\AiProvider;
+
+class AiProviderManager
+{
+    /**
+     * @param  array<string, AiProviderDriver>  $drivers  Keyed by AiProvider::PROVIDERS value.
+     */
+    public function __construct(private readonly array $drivers) {}
+
+    public function driverFor(AiProvider $provider): AiProviderDriver
+    {
+        if (! isset($this->drivers[$provider->provider])) {
+            throw new AiGenerationException("No driver registered for AI provider '{$provider->provider}'.");
+        }
+
+        return $this->drivers[$provider->provider];
+    }
+
+    /**
+     * @param  array<string, mixed>  $options
+     */
+    public function generate(AiProvider $provider, string $prompt, array $options = []): AiGenerationResult
+    {
+        if (! $provider->is_active) {
+            throw new AiGenerationException("AI provider '{$provider->name}' is not active.");
+        }
+
+        return $this->driverFor($provider)->generate($provider, $prompt, $options);
+    }
+}

app/Support/AiProviders/ElevenLabsDriver.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Support\AiProviders;
+
+use App\Models\AiProvider;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Http;
+
+/**
+ * Text-to-speech via ElevenLabs. Used for narration/voiceover. Unlike the
+ * other drivers, a successful response body IS the generated content
+ * (raw audio bytes), not JSON.
+ */
+class ElevenLabsDriver implements AiProviderDriver
+{
+    public function generate(AiProvider $provider, string $prompt, array $options = []): AiGenerationResult
+    {
+        $voiceId = $options['voice_id'] ?? $provider->config['voice_id'] ?? null;
+
+        if (! $voiceId) {
+            throw new AiGenerationException("AI provider '{$provider->name}' has no voice_id configured for text-to-speech.");
+        }
+
+        $modelId = $options['model_id'] ?? $provider->config['model_id'] ?? 'eleven_multilingual_v2';
+
+        try {
+            $response = Http::withHeaders(['xi-api-key' => $provider->api_key])
+                ->post("https://api.elevenlabs.io/v1/text-to-speech/{$voiceId}", [
+                    'text' => $prompt,
+                    'model_id' => $modelId,
+                ]);
+        } catch (ConnectionException $e) {
+            throw new AiGenerationException("could not connect to ElevenLabs: {$e->getMessage()}");
+        }
+
+        if ($response->failed()) {
+            $error = $response->json('detail.message') ?? $response->json('detail') ?? 'unexpected response from ElevenLabs';
+
+            throw new AiGenerationException(is_string($error) ? $error : 'unexpected response from ElevenLabs');
+        }
+
+        return new AiGenerationResult($response->body(), 'audio/mpeg');
+    }
+}

app/Support/AiProviders/OpenAiDriver.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Support\AiProviders;
+
+use App\Models\AiProvider;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Http;
+
+/**
+ * Text generation via OpenAI's Chat Completions API. Used for scripts,
+ * metadata (titles/descriptions/tags), and similar text content.
+ */
+class OpenAiDriver implements AiProviderDriver
+{
+    public function generate(AiProvider $provider, string $prompt, array $options = []): AiGenerationResult
+    {
+        $model = $options['model'] ?? $provider->config['model'] ?? 'gpt-4o-mini';
+
+        try {
+            $response = Http::withToken($provider->api_key)
+                ->post('https://api.openai.com/v1/chat/completions', [
+                    'model' => $model,
+                    'messages' => [
+                        ['role' => 'user', 'content' => $prompt],
+                    ],
+                ]);
+        } catch (ConnectionException $e) {
+            throw new AiGenerationException("could not connect to OpenAI: {$e->getMessage()}");
+        }
+
+        if ($response->failed()) {
+            throw new AiGenerationException($response->json('error.message') ?? 'unexpected response from OpenAI');
+        }
+
+        $content = $response->json('choices.0.message.content');
+
+        if (! $content) {
+            throw new AiGenerationException('unexpected response from OpenAI: missing message content');
+        }
+
+        return new AiGenerationResult($content, 'text/plain', $response->json());
+    }
+}

app/Support/AiProviders/StabilityAiDriver.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Support\AiProviders;
+
+use App\Models\AiProvider;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Http;
+
+/**
+ * Image generation via StabilityAI's Stable Image Core API. Used for
+ * storyboard frames, thumbnails, and scene visuals.
+ */
+class StabilityAiDriver implements AiProviderDriver
+{
+    public function generate(AiProvider $provider, string $prompt, array $options = []): AiGenerationResult
+    {
+        $outputFormat = $options['output_format'] ?? $provider->config['output_format'] ?? 'png';
+
+        try {
+            $response = Http::withToken($provider->api_key)
+                ->accept('application/json')
+                ->asMultipart()
+                ->attach('prompt', $prompt)
+                ->attach('output_format', $outputFormat)
+                ->post('https://api.stability.ai/v2beta/stable-image/generate/core');
+        } catch (ConnectionException $e) {
+            throw new AiGenerationException("could not connect to StabilityAI: {$e->getMessage()}");
+        }
+
+        if ($response->failed()) {
+            $error = $response->json('errors.0') ?? $response->json('message') ?? 'unexpected response from StabilityAI';
+
+            throw new AiGenerationException($error);
+        }
+
+        $base64 = $response->json('image');
+
+        if (! $base64) {
+            throw new AiGenerationException('unexpected response from StabilityAI: missing image data');
+        }
+
+        $bytes = base64_decode($base64);
+
+        return new AiGenerationResult($bytes, "image/{$outputFormat}", [
+            'seed' => $response->json('seed'),
+            'finish_reason' => $response->json('finish_reason'),
+        ]);
+    }
+}

app/Support/AssetStorage/AssetStorage.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Support\AssetStorage;
+
+use App\Models\Asset;
+use App\Models\VideoProject;
+use App\Models\WorkflowStep;
+use Illuminate\Support\Facades\Storage;
+
+/**
+ * Stores generated content (scripts, images, video, audio) on disk and
+ * records it as an Asset. Versioned per (project, type[, step]) slot —
+ * storing again for the same slot doesn't overwrite, it adds the next
+ * version, so a rejected/retried step's earlier output stays around.
+ */
+class AssetStorage
+{
+    /**
+     * @param  array<string, mixed>  $metadata
+     */
+    public function store(
+        VideoProject $project,
+        string $type,
+        string $contents,
+        string $extension,
+        ?WorkflowStep $step = null,
+        ?string $mimeType = null,
+        array $metadata = [],
+    ): Asset {
+        $version = $this->nextVersion($project, $type, $step);
+        $path = "video-projects/{$project->id}/{$type}/v{$version}.".ltrim($extension, '.');
+
+        Storage::put($path, $contents);
+
+        return $project->assets()->create([
+            'workflow_step_id' => $step?->id,
+            'type' => $type,
+            'disk_path' => $path,
+            'mime_type' => $mimeType,
+            'size_bytes' => strlen($contents),
+            'version' => $version,
+            'metadata' => $metadata,
+        ]);
+    }
+
+    public function nextVersion(VideoProject $project, string $type, ?WorkflowStep $step = null): int
+    {
+        $query = $project->assets()->where('type', $type);
+
+        if ($step) {
+            $query->where('workflow_step_id', $step->id);
+        }
+
+        return ((int) $query->max('version')) + 1;
+    }
+
+    public function contents(Asset $asset): string
+    {
+        return Storage::get($asset->disk_path);
+    }
+
+    public function url(Asset $asset): ?string
+    {
+        return Storage::exists($asset->disk_path) ? Storage::url($asset->disk_path) : null;
+    }
+
+    public function delete(Asset $asset): void
+    {
+        Storage::delete($asset->disk_path);
+        $asset->delete();
+    }
+
+    /**
+     * Keep only the newest $keep versions for a (project, type[, step])
+     * slot; delete the file + record for the rest. Returns how many were
+     * pruned.
+     */
+    public function pruneOldVersions(VideoProject $project, string $type, ?WorkflowStep $step = null, int $keep = 3): int
+    {
+        $query = $project->assets()->where('type', $type);
+
+        if ($step) {
+            $query->where('workflow_step_id', $step->id);
+        }
+
+        $stale = $query->orderByDesc('version')->get()->slice($keep);
+
+        foreach ($stale as $asset) {
+            $this->delete($asset);
+        }
+
+        return $stale->count();
+    }
+}