@elyracode/stack-laravel-ai 0.4.0

package/README.md

@@ -0,0 +1,41 @@
+# @elyracode/stack-laravel-ai
+
+Elyra extension for the **Laravel AI SDK** (`laravel/ai`) -- the complete reference for building AI-powered Laravel applications.
+
+## Install
+
+```
+elyra install npm:@elyracode/stack-laravel-ai
+```
+
+## What's included
+
+Comprehensive knowledge of the entire Laravel AI SDK:
+
+- **Agents**: Creating, prompting, conversation context, RemembersConversations
+- **Sub-Agents**: Multi-agent delegation with CanActAsTool, isolated execution
+- **Tools**: Custom tools, provider tools (WebSearch, WebFetch, FileSearch), SimilaritySearch
+- **Structured Output**: JSON schemas with nested objects and arrays
+- **Streaming**: SSE, Vercel AI SDK protocol, broadcasting
+- **Embeddings**: Vector columns (pgvector), similarity queries, caching
+- **Vector Stores**: File indexing, metadata, FileSearch integration
+- **Images**: Generation, reference images, storage
+- **Audio**: TTS, STT, diarization
+- **Reranking**: Semantic reordering with Cohere, Jina, VoyageAI
+- **Files**: Provider file storage, retrieval, deletion
+- **Testing**: Faking agents, images, audio, embeddings, reranking, files, stores
+- **Configuration**: Provider attributes, middleware, failover, provider options
+- **Events**: Full lifecycle event coverage
+
+## Usage
+
+Just ask Elyra about building AI features in Laravel:
+
+```
+> Build a customer service system with a main agent that routes to refund and support sub-agents
+> Create an agent that analyzes sales transcripts with structured output
+> Set up RAG with embeddings and vector stores for my knowledge base
+> Add streaming AI responses to my Laravel app with broadcasting
+```
+
+The agent generates complete, working Laravel AI SDK code following official patterns.

package/extensions/index.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+
+export default function (elyra: ExtensionAPI) {
+    elyra.registerCommand("laravel:ai", {
+        description: "Laravel AI SDK quick reference and scaffolding help",
+        handler: async (_args, ctx) => {
+            ctx.ui.notify(
+                "Laravel AI SDK profile loaded. Skills: laravel-ai. Use /skill:laravel-ai for full reference.",
+            );
+        },
+    });
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@elyracode/stack-laravel-ai",
+  "version": "0.4.0",
+  "description": "Elyra extension for Laravel AI SDK -- agents, sub-agents, tools, structured output, embeddings, and more",
+  "type": "module",
+  "keywords": ["elyra-package", "laravel", "ai-sdk", "agents", "sub-agents", "tools", "embeddings"],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/stack-laravel-ai"
+  },
+  "elyra": {
+    "skills": ["./skills"],
+    "extensions": ["./extensions/index.ts"]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/laravel-ai/SKILL.md

@@ -0,0 +1,1354 @@
+---
+name: laravel-ai
+description: Deep knowledge of the Laravel AI SDK (laravel/ai). Use when building AI agents, tools, sub-agents, structured output, embeddings, vector stores, image generation, audio, reranking, files, or any AI feature in a Laravel application.
+---
+
+# Laravel AI SDK Reference
+
+## Installation
+
+```bash
+composer require laravel/ai
+php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
+php artisan migrate
+```
+
+Creates `agent_conversations` and `agent_conversation_messages` tables for conversation storage.
+
+## Configuration
+
+Set provider keys in `.env`:
+
+```
+ANTHROPIC_API_KEY=
+AZURE_OPENAI_API_KEY=
+COHERE_API_KEY=
+DEEPSEEK_API_KEY=
+ELEVENLABS_API_KEY=
+GEMINI_API_KEY=
+GROQ_API_KEY=
+MISTRAL_API_KEY=
+OLLAMA_API_KEY=
+OPENAI_API_KEY=
+OPENROUTER_API_KEY=
+JINA_API_KEY=
+VOYAGEAI_API_KEY=
+XAI_API_KEY=
+```
+
+Default models for text, images, audio, transcription, and embeddings are configured in `config/ai.php`.
+
+### Custom Base URLs
+
+Route requests through proxies or alternative endpoints:
+
+```php
+// config/ai.php
+'providers' => [
+    'openai' => [
+        'driver' => 'openai',
+        'key' => env('OPENAI_API_KEY'),
+        'url' => env('OPENAI_BASE_URL'),
+    ],
+    'anthropic' => [
+        'driver' => 'anthropic',
+        'key' => env('ANTHROPIC_API_KEY'),
+        'url' => env('ANTHROPIC_BASE_URL'),
+    ],
+],
+```
+
+Supported for: OpenAI, Anthropic, Gemini, Groq, Cohere, DeepSeek, xAI, OpenRouter.
+
+### Lab Enum
+
+Reference providers throughout code with `Laravel\Ai\Enums\Lab`:
+
+```php
+use Laravel\Ai\Enums\Lab;
+
+Lab::Anthropic;
+Lab::OpenAI;
+Lab::Gemini;
+// ...
+```
+
+## Creating Agents
+
+```bash
+php artisan make:agent SalesCoach
+php artisan make:agent SalesCoach --structured
+```
+
+### Agent Class Structure
+
+```php
+<?php
+
+namespace App\Ai\Agents;
+
+use App\Ai\Tools\RetrievePreviousTranscripts;
+use App\Models\History;
+use App\Models\User;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Laravel\Ai\Contracts\Agent;
+use Laravel\Ai\Contracts\Conversational;
+use Laravel\Ai\Contracts\HasStructuredOutput;
+use Laravel\Ai\Contracts\HasTools;
+use Laravel\Ai\Messages\Message;
+use Laravel\Ai\Promptable;
+use Stringable;
+
+class SalesCoach implements Agent, Conversational, HasTools, HasStructuredOutput
+{
+    use Promptable;
+
+    public function __construct(public User $user) {}
+
+    public function instructions(): Stringable|string
+    {
+        return 'You are a sales coach, analyzing transcripts and providing feedback and an overall sales strength score.';
+    }
+
+    public function messages(): iterable
+    {
+        return History::where('user_id', $this->user->id)
+            ->latest()
+            ->limit(50)
+            ->get()
+            ->reverse()
+            ->map(fn ($message) => new Message($message->role, $message->content))
+            ->all();
+    }
+
+    public function tools(): iterable
+    {
+        return [
+            new RetrievePreviousTranscripts,
+        ];
+    }
+
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'feedback' => $schema->string()->required(),
+            'score' => $schema->integer()->min(1)->max(10)->required(),
+        ];
+    }
+}
+```
+
+### Key Interfaces
+
+- `Agent` -- required for all agents, defines `instructions()`
+- `Conversational` -- enables `messages()` for conversation context
+- `HasTools` -- enables `tools()` returning tool/sub-agent instances
+- `HasStructuredOutput` -- enables `schema()` for JSON output
+- `HasMiddleware` -- enables `middleware()` for prompt interception
+- `HasProviderOptions` -- enables `providerOptions()` for provider-specific config
+- `CanActAsTool` -- allows agent to be used as a sub-agent tool
+
+### Key Traits
+
+- `Promptable` -- provides `prompt()`, `stream()`, `queue()`, `broadcastOnQueue()`, `make()`, `fake()`
+- `RemembersConversations` -- auto-stores/retrieves conversation history
+
+## Prompting
+
+```php
+$response = (new SalesCoach)->prompt('Analyze this sales transcript...');
+return (string) $response;
+
+// Container resolution with dependency injection
+$agent = SalesCoach::make(user: $user);
+
+// Override provider/model/timeout
+$response = (new SalesCoach)->prompt(
+    'Analyze this sales transcript...',
+    provider: Lab::Anthropic,
+    model: 'claude-haiku-4-5-20251001',
+    timeout: 120,
+);
+```
+
+## Conversation Context
+
+Implement `Conversational` to return previous messages:
+
+```php
+use Laravel\Ai\Messages\Message;
+
+public function messages(): iterable
+{
+    return History::where('user_id', $this->user->id)
+        ->latest()->limit(50)->get()->reverse()
+        ->map(fn ($m) => new Message($m->role, $m->content))->all();
+}
+```
+
+### RemembersConversations
+
+Auto-stores and retrieves conversation history in the database:
+
+```php
+use Laravel\Ai\Concerns\RemembersConversations;
+use Laravel\Ai\Contracts\Agent;
+use Laravel\Ai\Contracts\Conversational;
+use Laravel\Ai\Promptable;
+
+class SalesCoach implements Agent, Conversational
+{
+    use Promptable, RemembersConversations;
+
+    public function instructions(): string
+    {
+        return 'You are a sales coach...';
+    }
+}
+
+// Start conversation for a user
+$response = (new SalesCoach)->forUser($user)->prompt('Hello!');
+$conversationId = $response->conversationId;
+
+// Continue existing conversation
+$response = (new SalesCoach)
+    ->continue($conversationId, as: $user)
+    ->prompt('Tell me more about that.');
+```
+
+## Structured Output
+
+Implement `HasStructuredOutput` and define a `schema` method:
+
+```php
+public function schema(JsonSchema $schema): array
+{
+    return [
+        'score' => $schema->integer()->required(),
+    ];
+}
+
+$response = (new SalesCoach)->prompt('Analyze...');
+return $response['score']; // Access like array
+```
+
+### Nested Objects
+
+```php
+public function schema(JsonSchema $schema): array
+{
+    return [
+        'score' => $schema->integer()->required(),
+        'metadata' => $schema->object(fn ($schema) => [
+            'confidence' => $schema->string()->enum(['low', 'medium', 'high'])->required(),
+            'language' => $schema->string()->required(),
+        ])->required(),
+    ];
+}
+```
+
+### Arrays of Objects
+
+```php
+public function schema(JsonSchema $schema): array
+{
+    return [
+        'feedback' => $schema->array()
+            ->items(
+                $schema->object(fn ($schema) => [
+                    'comment' => $schema->string()->required(),
+                    'score' => $schema->integer()->required(),
+                ])
+            )
+            ->required(),
+    ];
+}
+```
+
+## Attachments
+
+Pass images and documents with prompts:
+
+```php
+use Laravel\Ai\Files;
+
+$response = (new SalesCoach)->prompt(
+    'Analyze the attached sales transcript...',
+    attachments: [
+        Files\Document::fromStorage('transcript.pdf'),
+        Files\Document::fromPath('/home/laravel/transcript.md'),
+        $request->file('transcript'), // UploadedFile
+    ]
+);
+
+// Images
+$response = (new ImageAnalyzer)->prompt(
+    'What is in this image?',
+    attachments: [
+        Files\Image::fromStorage('photo.jpg'),
+        Files\Image::fromPath('/home/laravel/photo.jpg'),
+        $request->file('photo'),
+    ]
+);
+```
+
+## Streaming
+
+```php
+// Return from route (SSE)
+Route::get('/coach', fn () =>
+    (new SalesCoach)->stream('Analyze this sales transcript...')
+);
+
+// With callback after completion
+(new SalesCoach)
+    ->stream('Analyze this sales transcript...')
+    ->then(function (StreamedAgentResponse $response) {
+        // $response->text, $response->events, $response->usage
+    });
+
+// Iterate events manually
+foreach ((new SalesCoach)->stream('Analyze...') as $event) {
+    // ...
+}
+
+// Vercel AI SDK protocol
+(new SalesCoach)->stream('Analyze...')
+    ->usingVercelDataProtocol();
+```
+
+## Broadcasting
+
+```php
+use Illuminate\Broadcasting\Channel;
+
+// Broadcast events manually
+foreach ((new SalesCoach)->stream('Analyze...') as $event) {
+    $event->broadcast(new Channel('channel-name'));
+}
+
+// Queue + broadcast
+(new SalesCoach)->broadcastOnQueue(
+    'Analyze this sales transcript...',
+    new Channel('channel-name'),
+);
+```
+
+## Queueing
+
+```php
+use Laravel\Ai\Responses\AgentResponse;
+
+Route::post('/coach', function (Request $request) {
+    (new SalesCoach)
+        ->queue($request->input('transcript'))
+        ->then(function (AgentResponse $response) {
+            // ...
+        })
+        ->catch(function (Throwable $e) {
+            // ...
+        });
+
+    return back();
+});
+```
+
+## Tools
+
+```bash
+php artisan make:tool RandomNumberGenerator
+```
+
+### Tool Class Structure
+
+```php
+<?php
+
+namespace App\Ai\Tools;
+
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Laravel\Ai\Contracts\Tool;
+use Laravel\Ai\Tools\Request;
+use Stringable;
+
+class RandomNumberGenerator implements Tool
+{
+    public function description(): Stringable|string
+    {
+        return 'This tool may be used to generate cryptographically secure random numbers.';
+    }
+
+    public function handle(Request $request): Stringable|string
+    {
+        return (string) random_int($request['min'], $request['max']);
+    }
+
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'min' => $schema->integer()->min(0)->required(),
+            'max' => $schema->integer()->required(),
+        ];
+    }
+}
+```
+
+### SimilaritySearch Tool
+
+For RAG -- agents search vector embeddings stored in the database:
+
+```php
+use App\Models\Document;
+use Laravel\Ai\Tools\SimilaritySearch;
+
+public function tools(): iterable
+{
+    return [
+        SimilaritySearch::usingModel(Document::class, 'embedding'),
+    ];
+}
+
+// With filtering options
+SimilaritySearch::usingModel(
+    model: Document::class,
+    column: 'embedding',
+    minSimilarity: 0.7,
+    limit: 10,
+    query: fn ($query) => $query->where('published', true),
+),
+
+// Custom closure for full control
+new SimilaritySearch(using: function (string $query) {
+    return Document::query()
+        ->where('user_id', $this->user->id)
+        ->whereVectorSimilarTo('embedding', $query)
+        ->limit(10)
+        ->get();
+}),
+
+// Custom description
+SimilaritySearch::usingModel(Document::class, 'embedding')
+    ->withDescription('Search the knowledge base for relevant articles.'),
+```
+
+### Provider Tools
+
+Native tools executed by the AI provider, not your application.
+
+#### WebSearch
+
+Supported: Anthropic, OpenAI, Gemini
+
+```php
+use Laravel\Ai\Providers\Tools\WebSearch;
+
+public function tools(): iterable
+{
+    return [
+        new WebSearch,
+        // With limits and domain restrictions
+        (new WebSearch)->max(5)->allow(['laravel.com', 'php.net']),
+        // With location
+        (new WebSearch)->location(city: 'New York', region: 'NY', country: 'US'),
+    ];
+}
+```
+
+#### WebFetch
+
+Supported: Anthropic, Gemini
+
+```php
+use Laravel\Ai\Providers\Tools\WebFetch;
+
+public function tools(): iterable
+{
+    return [
+        new WebFetch,
+        (new WebFetch)->max(3)->allow(['docs.laravel.com']),
+    ];
+}
+```
+
+#### FileSearch
+
+Supported: OpenAI, Gemini
+
+```php
+use Laravel\Ai\Providers\Tools\FileSearch;
+use Laravel\Ai\Providers\Tools\FileSearchQuery;
+
+public function tools(): iterable
+{
+    return [
+        new FileSearch(stores: ['store_id']),
+        // Multiple stores
+        new FileSearch(stores: ['store_1', 'store_2']),
+        // Simple metadata filter
+        new FileSearch(stores: ['store_id'], where: [
+            'author' => 'Taylor Otwell',
+            'year' => 2026,
+        ]),
+        // Complex metadata filter
+        new FileSearch(stores: ['store_id'], where: fn (FileSearchQuery $query) =>
+            $query->where('author', 'Taylor Otwell')
+                ->whereNot('status', 'draft')
+                ->whereIn('category', ['news', 'updates'])
+        ),
+    ];
+}
+```
+
+## Sub-Agents
+
+Sub-agents are agents returned as tools from another agent. The parent delegates tasks to specialized sub-agents. Each sub-agent runs in isolation -- it does NOT receive the parent's conversation history.
+
+### Parent Agent
+
+```php
+class CustomerSupportAgent implements Agent, HasTools
+{
+    use Promptable;
+
+    public function instructions(): string
+    {
+        return 'You help customers with account, order, and billing questions. Delegate refund policy questions to the refunds specialist.';
+    }
+
+    public function tools(): iterable
+    {
+        return [
+            new RefundsAgent,
+            new TechnicalSupportAgent,
+        ];
+    }
+}
+```
+
+### Sub-Agent with CanActAsTool
+
+```php
+use Laravel\Ai\Attributes\Provider;
+use Laravel\Ai\Contracts\Agent;
+use Laravel\Ai\Contracts\CanActAsTool;
+use Laravel\Ai\Contracts\HasTools;
+use Laravel\Ai\Enums\Lab;
+use Laravel\Ai\Promptable;
+
+#[Provider(Lab::Anthropic)]
+class RefundsAgent implements Agent, CanActAsTool, HasTools
+{
+    use Promptable;
+
+    public function instructions(): string
+    {
+        return 'You are a refunds specialist. Use order details and the refund policy to give concise eligibility guidance.';
+    }
+
+    public function name(): string
+    {
+        return 'refunds_specialist';
+    }
+
+    public function description(): string
+    {
+        return 'Determine whether an order is eligible for a refund and explain the next step.';
+    }
+
+    public function tools(): iterable
+    {
+        return [new LookupOrder];
+    }
+}
+```
+
+If a sub-agent does not implement `CanActAsTool`, Laravel uses the class basename as the tool name and a generic description.
+
+## Middleware
+
+```bash
+php artisan make:agent-middleware LogPrompts
+```
+
+```php
+<?php
+
+namespace App\Ai\Middleware;
+
+use Closure;
+use Laravel\Ai\Prompts\AgentPrompt;
+use Laravel\Ai\Responses\AgentResponse;
+
+class LogPrompts
+{
+    public function handle(AgentPrompt $prompt, Closure $next)
+    {
+        Log::info('Prompting agent', ['prompt' => $prompt->prompt]);
+
+        return $next($prompt)->then(function (AgentResponse $response) {
+            Log::info('Agent responded', ['text' => $response->text]);
+        });
+    }
+}
+```
+
+On the agent:
+
+```php
+use Laravel\Ai\Contracts\HasMiddleware;
+
+class SalesCoach implements Agent, HasMiddleware
+{
+    use Promptable;
+
+    public function middleware(): array
+    {
+        return [new LogPrompts];
+    }
+}
+```
+
+## Anonymous Agents
+
+Quick ad-hoc agents without a dedicated class:
+
+```php
+use function Laravel\Ai\{agent};
+
+$response = agent(
+    instructions: 'You are an expert at software development.',
+    messages: [],
+    tools: [],
+)->prompt('Tell me about Laravel');
+
+// With structured output
+$response = agent(
+    schema: fn (JsonSchema $schema) => [
+        'number' => $schema->integer()->required(),
+    ],
+)->prompt('Generate a random number less than 100');
+```
+
+## Agent Configuration (Attributes)
+
+```php
+use Laravel\Ai\Attributes\{Provider, Model, MaxSteps, MaxTokens, Temperature, Timeout, TopP, UseCheapestModel, UseSmartestModel};
+use Laravel\Ai\Enums\Lab;
+
+#[Provider(Lab::Anthropic)]
+#[Model('claude-haiku-4-5-20251001')]
+#[MaxSteps(10)]
+#[MaxTokens(4096)]
+#[Temperature(0.7)]
+#[Timeout(120)]
+#[TopP(0.9)]
+class SalesCoach implements Agent
+{
+    use Promptable;
+    // ...
+}
+
+// Cost optimization -- cheapest model for the provider
+#[UseCheapestModel]
+class SimpleSummarizer implements Agent { use Promptable; }
+
+// Maximum capability -- most capable model for the provider
+#[UseSmartestModel]
+class ComplexReasoner implements Agent { use Promptable; }
+```
+
+Available attributes:
+- `MaxSteps` -- max tool-use steps
+- `MaxTokens` -- max generated tokens
+- `Model` -- specific model name
+- `Provider` -- AI provider (or array for failover)
+- `Temperature` -- sampling temperature (0.0-1.0)
+- `Timeout` -- HTTP timeout in seconds (default: 60)
+- `TopP` -- nucleus sampling probability (0.0-1.0)
+- `UseCheapestModel` -- cheapest model for cost optimization
+- `UseSmartestModel` -- most capable model for complex tasks
+
+## Provider Options
+
+For provider-specific options (OpenAI reasoning, Anthropic thinking, penalties):
+
+```php
+use Laravel\Ai\Contracts\HasProviderOptions;
+use Laravel\Ai\Enums\Lab;
+
+class SalesCoach implements Agent, HasProviderOptions
+{
+    use Promptable;
+
+    public function providerOptions(Lab|string $provider): array
+    {
+        return match ($provider) {
+            Lab::OpenAI => [
+                'reasoning' => ['effort' => 'low'],
+                'frequency_penalty' => 0.5,
+                'presence_penalty' => 0.3,
+            ],
+            Lab::Anthropic => [
+                'thinking' => ['budget_tokens' => 1024],
+                'cache_control' => ['type' => 'ephemeral'],
+            ],
+            default => [],
+        };
+    }
+}
+```
+
+The method receives the current provider, useful with failover to return different options per provider.
+
+## Images
+
+```php
+use Laravel\Ai\Image;
+
+$image = Image::of('A donut sitting on the kitchen counter')->generate();
+$rawContent = (string) $image;
+
+// With options
+$image = Image::of('A donut sitting on the kitchen counter')
+    ->quality('high')    // 'high', 'medium', 'low'
+    ->landscape()        // or ->portrait(), ->square()
+    ->timeout(120)
+    ->generate();
+
+// With reference images
+$image = Image::of('Update this photo to impressionist style.')
+    ->attachments([
+        Files\Image::fromStorage('photo.jpg'),
+        // Files\Image::fromPath('/home/laravel/photo.jpg'),
+        // Files\Image::fromUrl('https://example.com/photo.jpg'),
+        // $request->file('photo'),
+    ])
+    ->landscape()
+    ->generate();
+
+// Storage
+$path = $image->store();
+$path = $image->storeAs('image.jpg');
+$path = $image->storePublicly();
+$path = $image->storePubliclyAs('image.jpg');
+
+// Queue
+Image::of('A donut on the counter')
+    ->portrait()
+    ->queue()
+    ->then(function (ImageResponse $image) {
+        $path = $image->store();
+    });
+```
+
+## Audio (TTS)
+
+```php
+use Laravel\Ai\Audio;
+use Illuminate\Support\Str;
+
+$audio = Audio::of('I love coding with Laravel.')->generate();
+$rawContent = (string) $audio;
+
+// Via Stringable
+$audio = Str::of('I love coding with Laravel.')->toAudio();
+
+// Voice options
+$audio = Audio::of('I love coding with Laravel.')
+    ->female()              // or ->male()
+    ->generate();
+
+$audio = Audio::of('I love coding with Laravel.')
+    ->voice('voice-id-or-name')
+    ->generate();
+
+// With instructions
+$audio = Audio::of('I love coding with Laravel.')
+    ->female()
+    ->instructions('Said like a pirate')
+    ->generate();
+
+// Storage
+$path = $audio->store();
+$path = $audio->storeAs('audio.mp3');
+$path = $audio->storePublicly();
+$path = $audio->storePubliclyAs('audio.mp3');
+
+// Queue
+Audio::of('I love coding with Laravel.')
+    ->queue()
+    ->then(function (AudioResponse $audio) {
+        $path = $audio->store();
+    });
+```
+
+## Transcription (STT)
+
+```php
+use Laravel\Ai\Transcription;
+
+$transcript = Transcription::fromPath('/home/laravel/audio.mp3')->generate();
+$transcript = Transcription::fromStorage('audio.mp3')->generate();
+$transcript = Transcription::fromUpload($request->file('audio'))->generate();
+
+return (string) $transcript;
+
+// With diarization (speaker segmentation)
+$transcript = Transcription::fromStorage('audio.mp3')
+    ->diarize()
+    ->generate();
+
+// Queue
+Transcription::fromStorage('audio.mp3')
+    ->queue()
+    ->then(function (TranscriptionResponse $transcript) {
+        // ...
+    });
+```
+
+## Embeddings
+
+```php
+use Illuminate\Support\Str;
+use Laravel\Ai\Embeddings;
+
+// Single via Stringable
+$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();
+
+// Multiple inputs
+$response = Embeddings::for([
+    'Napa Valley has great wine.',
+    'Laravel is a PHP framework.',
+])->generate();
+
+$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]
+
+// With dimensions and provider
+$response = Embeddings::for(['Napa Valley has great wine.'])
+    ->dimensions(1536)
+    ->generate(Lab::OpenAI, 'text-embedding-3-small');
+```
+
+### Querying Embeddings (PostgreSQL + pgvector)
+
+Migration:
+
+```php
+Schema::ensureVectorExtensionExists();
+
+Schema::create('documents', function (Blueprint $table) {
+    $table->id();
+    $table->string('title');
+    $table->text('content');
+    $table->vector('embedding', dimensions: 1536)->index();
+    $table->timestamps();
+});
+```
+
+Model cast:
+
+```php
+protected function casts(): array
+{
+    return ['embedding' => 'array'];
+}
+```
+
+Queries:
+
+```php
+use App\Models\Document;
+
+// whereVectorSimilarTo accepts array of floats or a plain string
+// When a string is given, Laravel auto-generates embeddings
+$documents = Document::query()
+    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
+    ->limit(10)
+    ->get();
+
+// With minimum similarity threshold
+$documents = Document::query()
+    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
+    ->limit(10)
+    ->get();
+
+// Lower-level methods for full control
+$documents = Document::query()
+    ->select('*')
+    ->selectVectorDistance('embedding', $queryEmbedding, as: 'distance')
+    ->whereVectorDistanceLessThan('embedding', $queryEmbedding, maxDistance: 0.3)
+    ->orderByVectorDistance('embedding', $queryEmbedding)
+    ->limit(10)
+    ->get();
+```
+
+### Caching Embeddings
+
+Enable globally in `config/ai.php`:
+
+```php
+'caching' => [
+    'embeddings' => [
+        'cache' => true,
+        'store' => env('CACHE_STORE', 'database'),
+    ],
+],
+```
+
+Or per-request:
+
+```php
+$response = Embeddings::for(['Napa Valley has great wine.'])
+    ->cache()
+    ->generate();
+
+// Custom duration
+$response = Embeddings::for(['...'])
+    ->cache(seconds: 3600)
+    ->generate();
+
+// Via Stringable
+$embeddings = Str::of('text')->toEmbeddings(cache: true);
+$embeddings = Str::of('text')->toEmbeddings(cache: 3600);
+```
+
+## Reranking
+
+Reorder documents by semantic relevance to a query:
+
+```php
+use Laravel\Ai\Reranking;
+
+$response = Reranking::of([
+    'Django is a Python web framework.',
+    'Laravel is a PHP web application framework.',
+    'React is a JavaScript library for building user interfaces.',
+])->rerank('PHP frameworks');
+
+$response->first()->document; // "Laravel is a PHP web application framework."
+$response->first()->score;    // 0.95
+$response->first()->index;    // 1 (original position)
+
+// Limit results
+$response = Reranking::of($documents)
+    ->limit(5)
+    ->rerank('search query');
+```
+
+### Reranking Collections
+
+```php
+// Rerank by a single field
+$posts = Post::all()->rerank('body', 'Laravel tutorials');
+
+// Rerank by multiple fields (sent as JSON)
+$reranked = $posts->rerank(['title', 'body'], 'Laravel tutorials');
+
+// Rerank using a closure
+$reranked = $posts->rerank(
+    fn ($post) => $post->title.': '.$post->body,
+    'Laravel tutorials'
+);
+
+// With limit and provider
+$reranked = $posts->rerank(
+    by: 'content',
+    query: 'Laravel tutorials',
+    limit: 10,
+    provider: Lab::Cohere
+);
+```
+
+## Files
+
+Store files with AI providers for reuse in conversations without re-uploading:
+
+```php
+use Laravel\Ai\Files\Document;
+use Laravel\Ai\Files\Image;
+
+// Store from various sources
+$response = Document::fromPath('/home/laravel/document.pdf')->put();
+$response = Document::fromStorage('document.pdf', disk: 'local')->put();
+$response = Document::fromUrl('https://example.com/document.pdf')->put();
+$response = Document::fromString('Hello, World!', 'text/plain')->put();
+$response = Document::fromUpload($request->file('document'))->put();
+
+$response = Image::fromPath('/home/laravel/photo.jpg')->put();
+$response = Image::fromStorage('photo.jpg', disk: 'local')->put();
+$response = Image::fromUrl('https://example.com/photo.jpg')->put();
+
+$fileId = $response->id;
+
+// Reference stored file in conversations
+$response = (new SalesCoach)->prompt(
+    'Analyze the attached sales transcript...',
+    attachments: [
+        Document::fromId('file-id'),
+    ]
+);
+
+// Retrieve and delete
+$file = Document::fromId('file-id')->get();
+$file->id;
+$file->mimeType();
+
+Document::fromId('file-id')->delete();
+
+// Specify provider
+$response = Document::fromPath('/path/to/doc.pdf')
+    ->put(provider: Lab::Anthropic);
+```
+
+## Vector Stores
+
+Searchable file collections for RAG:
+
+```php
+use Laravel\Ai\Stores;
+use Laravel\Ai\Files\Document;
+
+// Create
+$store = Stores::create('Knowledge Base');
+$store = Stores::create(
+    name: 'Knowledge Base',
+    description: 'Documentation and reference materials.',
+    expiresWhenIdleFor: days(30),
+);
+
+$storeId = $store->id;
+
+// Retrieve
+$store = Stores::get('store_id');
+$store->id;
+$store->name;
+$store->fileCounts;
+$store->ready;
+
+// Delete
+Stores::delete('store_id');
+$store->delete();
+```
+
+### Adding Files to Stores
+
+```php
+$store = Stores::get('store_id');
+
+// Add already-stored files
+$document = $store->add('file_id');
+$document = $store->add(Document::fromId('file_id'));
+
+// Store and add in one step
+$document = $store->add(Document::fromPath('/path/to/document.pdf'));
+$document = $store->add(Document::fromStorage('manual.pdf'));
+$document = $store->add($request->file('document'));
+
+$document->id;
+$document->fileId;
+
+// With metadata (for filtering with FileSearch)
+$store->add(Document::fromPath('/path/to/document.pdf'), metadata: [
+    'author' => 'Taylor Otwell',
+    'department' => 'Engineering',
+    'year' => 2026,
+]);
+
+// Remove from store
+$store->remove('file_id');
+$store->remove('file_abc123', deleteFile: true); // Also delete from provider storage
+
+// Use with FileSearch tool
+new FileSearch(stores: [$store->id]);
+```
+
+## Failover
+
+Provide an array of providers/models for automatic failover:
+
+```php
+use Laravel\Ai\Image;
+
+$response = (new SalesCoach)->prompt(
+    'Analyze this sales transcript...',
+    provider: [Lab::OpenAI, Lab::Anthropic],
+);
+
+$image = Image::of('A donut on the counter')
+    ->generate(provider: [Lab::Gemini, Lab::xAI]);
+```
+
+## Testing
+
+### Agents
+
+```php
+use App\Ai\Agents\SalesCoach;
+use Laravel\Ai\Prompts\AgentPrompt;
+
+// Fixed response for every prompt
+SalesCoach::fake();
+
+// Ordered responses
+SalesCoach::fake(['First response', 'Second response']);
+
+// Dynamic responses
+SalesCoach::fake(fn (AgentPrompt $prompt) => 'Response for: '.$prompt->prompt);
+
+// Prevent stray prompts (throws if no fake defined)
+SalesCoach::fake()->preventStrayPrompts();
+
+// Assertions
+SalesCoach::assertPrompted('Analyze this...');
+SalesCoach::assertPrompted(fn (AgentPrompt $prompt) => $prompt->contains('Analyze'));
+SalesCoach::assertNotPrompted('Missing prompt');
+SalesCoach::assertNeverPrompted();
+
+// Queued assertions
+SalesCoach::assertQueued('Analyze this...');
+SalesCoach::assertQueued(fn (QueuedAgentPrompt $prompt) => $prompt->contains('Analyze'));
+SalesCoach::assertNotQueued('Missing prompt');
+SalesCoach::assertNeverQueued();
+```
+
+When `fake()` is invoked on a structured output agent, fake data matching the schema is auto-generated.
+
+### Images
+
+```php
+use Laravel\Ai\Image;
+use Laravel\Ai\Prompts\ImagePrompt;
+
+Image::fake();
+Image::fake([base64_encode($firstImage), base64_encode($secondImage)]);
+Image::fake(fn (ImagePrompt $prompt) => base64_encode('...'));
+Image::fake()->preventStrayImages();
+
+Image::assertGenerated(fn (ImagePrompt $prompt) => $prompt->contains('sunset') && $prompt->isLandscape());
+Image::assertNotGenerated('Missing prompt');
+Image::assertNothingGenerated();
+
+// Queued
+Image::assertQueued(fn (QueuedImagePrompt $prompt) => $prompt->contains('sunset'));
+Image::assertNotQueued('Missing prompt');
+Image::assertNothingQueued();
+```
+
+### Audio
+
+```php
+use Laravel\Ai\Audio;
+use Laravel\Ai\Prompts\AudioPrompt;
+
+Audio::fake();
+Audio::fake()->preventStrayAudio();
+
+Audio::assertGenerated(fn (AudioPrompt $prompt) => $prompt->contains('Hello') && $prompt->isFemale());
+Audio::assertNotGenerated('Missing prompt');
+Audio::assertNothingGenerated();
+
+Audio::assertQueued(fn (QueuedAudioPrompt $prompt) => $prompt->contains('Hello'));
+```
+
+### Transcriptions
+
+```php
+use Laravel\Ai\Transcription;
+use Laravel\Ai\Prompts\TranscriptionPrompt;
+
+Transcription::fake();
+Transcription::fake(['First transcription text.', 'Second transcription text.']);
+Transcription::fake()->preventStrayTranscriptions();
+
+Transcription::assertGenerated(fn (TranscriptionPrompt $prompt) => $prompt->language === 'en' && $prompt->isDiarized());
+Transcription::assertNotGenerated(fn (TranscriptionPrompt $prompt) => $prompt->language === 'fr');
+Transcription::assertNothingGenerated();
+```
+
+### Embeddings
+
+```php
+use Laravel\Ai\Embeddings;
+use Laravel\Ai\Prompts\EmbeddingsPrompt;
+
+Embeddings::fake();
+Embeddings::fake()->preventStrayEmbeddings();
+
+Embeddings::assertGenerated(fn (EmbeddingsPrompt $prompt) => $prompt->contains('Laravel') && $prompt->dimensions === 1536);
+Embeddings::assertNotGenerated(fn (EmbeddingsPrompt $prompt) => $prompt->contains('Other'));
+Embeddings::assertNothingGenerated();
+```
+
+### Reranking
+
+```php
+use Laravel\Ai\Reranking;
+use Laravel\Ai\Prompts\RerankingPrompt;
+use Laravel\Ai\Responses\Data\RankedDocument;
+
+Reranking::fake();
+Reranking::fake([
+    [
+        new RankedDocument(index: 0, document: 'First', score: 0.95),
+        new RankedDocument(index: 1, document: 'Second', score: 0.80),
+    ],
+]);
+
+Reranking::assertReranked(fn (RerankingPrompt $prompt) => $prompt->contains('Laravel') && $prompt->limit === 5);
+Reranking::assertNotReranked(fn (RerankingPrompt $prompt) => $prompt->contains('Django'));
+Reranking::assertNothingReranked();
+```
+
+### Files
+
+```php
+use Laravel\Ai\Files;
+use Laravel\Ai\Contracts\Files\StorableFile;
+use Laravel\Ai\Files\Document;
+
+Files::fake();
+
+Document::fromString('Hello, Laravel!', mimeType: 'text/plain')
+    ->as('hello.txt')
+    ->put();
+
+Files::assertStored(fn (StorableFile $file) =>
+    (string) $file === 'Hello, Laravel!' && $file->mimeType() === 'text/plain'
+);
+Files::assertNotStored(fn (StorableFile $file) => (string) $file === 'Hello, World!');
+Files::assertNothingStored();
+
+Files::assertDeleted('file-id');
+Files::assertNotDeleted('file-id');
+Files::assertNothingDeleted();
+```
+
+### Vector Stores
+
+```php
+use Laravel\Ai\Stores;
+
+Stores::fake(); // Also fakes file operations
+
+$store = Stores::create('Knowledge Base');
+
+Stores::assertCreated('Knowledge Base');
+Stores::assertCreated(fn (string $name, ?string $description) => $name === 'Knowledge Base');
+Stores::assertNotCreated('Other Store');
+Stores::assertNothingCreated();
+
+Stores::assertDeleted('store_id');
+Stores::assertNotDeleted('other_store_id');
+Stores::assertNothingDeleted();
+
+// File assertions on store instances
+$store = Stores::get('store_id');
+$store->add('added_id');
+$store->remove('removed_id');
+
+$store->assertAdded('added_id');
+$store->assertRemoved('removed_id');
+$store->assertNotAdded('other_file_id');
+$store->assertNotRemoved('other_file_id');
+
+// Assert by file content
+$store->add(Document::fromString('Hello, World!', 'text/plain')->as('hello.txt'));
+$store->assertAdded(fn (StorableFile $file) => $file->name() === 'hello.txt');
+```
+
+## Events
+
+The SDK dispatches lifecycle events you can listen to:
+
+- `PromptingAgent`, `AgentPrompted`
+- `StreamingAgent`, `AgentStreamed`
+- `InvokingTool`, `ToolInvoked`
+- `GeneratingImage`, `ImageGenerated`
+- `GeneratingAudio`, `AudioGenerated`
+- `GeneratingTranscription`, `TranscriptionGenerated`
+- `GeneratingEmbeddings`, `EmbeddingsGenerated`
+- `Reranking`, `Reranked`
+- `StoringFile`, `FileStored`, `FileDeleted`
+- `CreatingStore`, `StoreCreated`
+- `AddingFileToStore`, `FileAddedToStore`, `RemovingFileFromStore`, `FileRemovedFromStore`
+
+## Multi-Agent Pattern Example
+
+Build a customer service system with a router agent and specialized sub-agents:
+
+```php
+// Main agent routes messages to specialists
+class CustomerServiceRouter implements Agent, HasTools
+{
+    use Promptable;
+
+    public function instructions(): string
+    {
+        return 'You are a customer service router. Analyze the customer message and delegate to the appropriate specialist agent.';
+    }
+
+    public function tools(): iterable
+    {
+        return [
+            new RefundAgent,
+            new TechnicalSupportAgent,
+            new BillingAgent,
+        ];
+    }
+}
+
+// Each sub-agent is a specialist with its own tools and provider
+#[Provider(Lab::Anthropic)]
+#[UseCheapestModel]
+class RefundAgent implements Agent, CanActAsTool, HasTools
+{
+    use Promptable;
+
+    public function instructions(): string
+    {
+        return 'You handle refund requests. Check order status and apply refund policy.';
+    }
+
+    public function name(): string { return 'refund_specialist'; }
+    public function description(): string { return 'Handle refund eligibility and processing.'; }
+
+    public function tools(): iterable
+    {
+        return [new LookupOrder, new ProcessRefund];
+    }
+}
+
+#[Provider(Lab::OpenAI)]
+class TechnicalSupportAgent implements Agent, CanActAsTool, HasTools
+{
+    use Promptable;
+
+    public function instructions(): string
+    {
+        return 'You handle technical support questions. Search the knowledge base and provide solutions.';
+    }
+
+    public function name(): string { return 'technical_support'; }
+    public function description(): string { return 'Troubleshoot technical issues and provide solutions.'; }
+
+    public function tools(): iterable
+    {
+        return [
+            SimilaritySearch::usingModel(KnowledgeArticle::class, 'embedding')
+                ->withDescription('Search technical knowledge base.'),
+        ];
+    }
+}
+```
+
+## Provider Support
+
+| Feature | Providers |
+|---------|-----------|
+| Text | OpenAI, Anthropic, Gemini, Azure, Bedrock, Groq, xAI, DeepSeek, Mistral, Ollama, OpenRouter |
+| Images | OpenAI, Gemini, xAI, Azure, Bedrock, OpenRouter |
+| TTS | OpenAI, ElevenLabs, Gemini |
+| STT | OpenAI, ElevenLabs, Mistral, Gemini |
+| Embeddings | OpenAI, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter |
+| Reranking | Cohere, Jina, VoyageAI |
+| Files | OpenAI, Anthropic, Gemini |