Ai Supabase Store Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require symfony/ai-supabase-store
   

   Requires symfony/ai (≥v0.8.0) and supabase/supabase-php (≥v2.0).

2. Database Setup

   • Enable pgvector in your Supabase PostgreSQL instance:

     CREATE EXTENSION vector;
     

   • Create a table with a vector column (e.g., embedding):

     CREATE TABLE documents (
         id UUID PRIMARY KEY,
         content TEXT,
         embedding vector(1536), -- Adjust dimension to your embedding size
         metadata JSONB
     );
     

   • Set up the match_documents RPC (Supabase provides this by default in their AI templates).

3. Laravel Configuration Bind the store in config/ai.php:

   'stores' => [
       'supabase' => [
           'type' => \Symfony\AI\SupabaseStore\Store::class,
           'connection' => 'supabase',
           'table' => 'documents',
           'embedding_column' => 'embedding',
           'id_column' => 'id',
       ],
   ],
   

   Register the Supabase connection in config/database.php:

   'connections' => [
       'supabase' => [
           'driver' => 'supabase',
           'url' => env('SUPABASE_URL'),
           'key' => env('SUPABASE_KEY'),
           'table' => env('SUPABASE_TABLE', 'documents'),
       ],
   ],
   

4. First Use Case: Storing and Querying Embeddings

   use Symfony\AI\Store\StoreInterface;
   use Illuminate\Support\Facades\AI;
   
   // Inject via Laravel's DI or resolve manually
   $store = AI::store('supabase');
   
   // Add an embedding
   $store->add(
       'doc_123',
       [0.1, 0.2, 0.3, ...], // Your embedding array (must match vector dimension)
       ['source' => 'user_guide', 'category' => 'laravel']
   );
   
   // Query similar embeddings
   $results = $store->query(
       [0.5, 0.4, 0.6, ...], // Query embedding
       limit: 5,
       filter: ['category' => 'laravel'] // Metadata filter
   );
   

Implementation Patterns

Common Workflows

1. RAG Pipeline Integration

Use the store to fetch context for LLM prompts:

$relevantDocs = $store->query(
    $queryEmbedding,
    limit: 3,
    filter: ['type' => 'faq']
);

$context = implode("\n\n---\n\n", array_map(
    fn($doc) => $doc['content'],
    $relevantDocs
));

$prompt = "Answer the question using this context: {$context}";

2. Bulk Operations

For initial dataset loading, batch inserts:

$batch = [];
foreach ($rawDocuments as $doc) {
    $batch[] = [
        'id' => $doc['id'],
        'embedding' => $doc['embedding'],
        'metadata' => $doc['metadata'],
    ];
}
// Use Supabase's bulk insert or chunked adds

3. Dynamic Filtering

Combine vector search with metadata:

$results = $store->query(
    $userQueryEmbedding,
    filter: [
        'OR' => [
            ['category' => 'tutorial'],
            ['tags' => 'advanced']
        ],
        'published' => true
    ]
);

4. Laravel Service Integration

Create a dedicated service for AI-powered features:

namespace App\Services;

use Symfony\AI\Store\StoreInterface;
use Illuminate\Support\Facades\AI;

class SemanticSearchService {
    public function __construct(
        protected StoreInterface $store
    ) {}

    public function search(string $query, array $filters = []): array {
        $embedding = $this->generateEmbedding($query); // Use your embedding model
        return $this->store->query($embedding, ['filter' => $filters]);
    }
}

5. Event-Driven Updates

Sync embeddings on content changes:

use Illuminate\Support\Facades\AI;

// After updating a document
$store = AI::store('supabase');
$newEmbedding = $this->generateEmbedding($updatedContent);
$store->add($documentId, $newEmbedding, $documentMetadata);

Integration Tips

Laravel-Specific

1. Dependency Injection Bind the store in AppServiceProvider:

   public function register() {
       $this->app->bind(\Symfony\AI\Store\StoreInterface::class, function ($app) {
           return AI::store('supabase');
       });
   }
   

2. Artisan Commands Create a command to rebuild embeddings:

   use Symfony\AI\Store\StoreInterface;
   use Illuminate\Console\Command;
   
   class RebuildEmbeddingsCommand extends Command {
       protected $signature = 'ai:rebuild-embeddings';
       protected $description = 'Regenerate and update all embeddings';
   
       public function handle(StoreInterface $store) {
           foreach ($this->getAllDocuments() as $doc) {
               $embedding = $this->generateEmbedding($doc['content']);
               $store->add($doc['id'], $embedding, $doc['metadata']);
           }
       }
   }
   

3. Testing Use Laravel’s testing helpers:

   public function testSemanticSearch() {
       $store = AI::store('supabase');
       $store->add('test_doc', [0.1, 0.2, 0.3], ['type' => 'test']);
   
       $results = $store->query([0.15, 0.25, 0.35]);
       $this->assertCount(1, $results);
   }
   

Performance Optimization

1. Indexing Add a GIN index for metadata filtering:

   CREATE INDEX idx_documents_metadata ON documents USING GIN (metadata jsonb_path_ops);
   

2. Batch Queries For large datasets, use match_documents directly with Supabase’s client:

   $client = new \Supabase\Client($_ENV['SUPABASE_URL'], $_ENV['SUPABASE_KEY']);
   $results = $client->rpc('match_documents', [
       'query_embedding' => $embedding,
       'model' => 'cosine',
       'filter' => 'category = \'laravel\'',
       'limit' => 10,
   ]);
   

3. Caching Cache frequent queries (e.g., popular search terms):

   $cacheKey = 'search:' . md5($query);
   return Cache::remember($cacheKey, now()->addHours(1), function () use ($store, $query) {
       return $store->query($this->generateEmbedding($query));
   });
   

Gotchas and Tips

Pitfalls

1. Vector Dimension Mismatch

   • Issue: Adding embeddings with incorrect dimensions (e.g., 768 vs. 1536) causes runtime errors.
   • Fix: Validate dimensions before insertion:

     if (count($embedding) !== 1536) {
         throw new \InvalidArgumentException('Embedding must have 1536 dimensions');
     }
     

2. Supabase RPC Limitations

   • Issue: The match_documents RPC has a default limit (often 100). Exceeding this silently truncates results.
   • Fix: Use limit parameter or call RPC directly with higher limits.

3. Metadata Filtering Quirks

   • Issue: Complex JSON filters may fail if the Supabase RPC doesn’t support them.
   • Fix: Test filters in the Supabase SQL editor first:

     SELECT * FROM documents
     WHERE metadata @> '{"category": "laravel"}';
     

4. Connection Timeouts

   • Issue: Supabase API timeouts (especially on free tier) during bulk operations.
   • Fix: Implement exponential backoff:

     use Symfony\Component\Process\Exception\TimeoutException;
     
     try {
         $store->add(...);
     } catch (TimeoutException $e) {
         sleep(2);
         retry();
     }
     

5. Laravel Caching Conflicts

   • Issue: If using Laravel’s query cache, Supabase’s dynamic RPCs may not cache properly.
   • Fix: Disable caching for AI-related queries:

     DB::disableQueryCache();
     $results = $store->query(...);
     DB::enableQueryCache();