Ai Typesense Store Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require symfony/ai-typesense-store typesense/typesense
   

   Ensure symfony/ai (≥v0.8.0) is also installed.

2. Configure Typesense Client: Create a Typesense client instance (e.g., in config/typesense.php):

   return [
       'nodes' => ['http://typesense.example.com:8108'],
       'api_key' => env('TYPESENSE_API_KEY'),
       'connection_timeout_seconds' => 2,
   ];
   

3. First Use Case: Semantic Search Initialize the store and query embeddings:

   use Symfony\AI\Store\StoreInterface;
   use Symfony\AI\TypesenseStore\TypesenseStore;
   use Typesense\Typesense;
   
   $client = new Typesense(config('typesense.nodes'), config('typesense.api_key'));
   $store = new TypesenseStore($client, 'products'); // 'products' = collection name
   
   // Add a vector (e.g., from an embedding)
   $store->add($embeddingVector, ['id' => 123, 'name' => 'Smartphone']);
   
   // Query similar vectors
   $results = $store->find(
       (new Query())->setVector($queryEmbedding)->setLimit(5)
   );
   

Where to Look First

• Package Docs: Symfony AI Typesense Store (limited but sufficient for basics).
• Typesense API: Vector Search Docs for advanced queries.
• Symfony AI Store Interface: StoreInterface for method signatures.

Implementation Patterns

Core Workflows

1. Vector Storage/Retrieval:

   // Store
   $store->add($vector, $metadata);
   
   // Retrieve (with filtering)
   $results = $store->find(
       (new Query())
           ->setVector($queryVector)
           ->setFilter('category: "electronics"')
           ->setLimit(10)
   );
   

2. Batching for Efficiency: Use bulk operations to reduce API calls:

   $store->addMany([
       [$vector1, $metadata1],
       [$vector2, $metadata2],
   ]);
   

3. Dynamic Collection Management: Create collections on-the-fly (e.g., per-tenant):

   $client->collections()->create('tenant_1_products', [
       'fields' => [
           ['name' => 'vector', 'type' => 'float[]', 'facet' => false],
           ['name' => 'id', 'type' => 'int32'],
       ],
   ]);
   

Integration Tips

• Laravel Service Provider: Bind the store to the container for dependency injection:

  public function register()
  {
      $this->app->singleton(StoreInterface::class, function ($app) {
          $client = new Typesense(config('typesense.nodes'), config('typesense.api_key'));
          return new TypesenseStore($client, config('typesense.collection'));
      });
  }
  

• Query Builder Pattern: Chain methods for complex queries:

  $query = (new Query())
      ->setVector($embedding)
      ->setFilter('price > 50 AND stock > 0')
      ->setLimit(5)
      ->setIncludeMetadata(true);
  

• Error Handling: Wrap store operations in try-catch blocks:

  try {
      $results = $store->find($query);
  } catch (TypesenseException $e) {
      Log::error("Typesense query failed: " . $e->getMessage());
      // Fallback logic (e.g., return cached results)
  }
  

• Hybrid Search: Combine keyword and vector search using Typesense’s query_by:

  $query->setQueryBy('vector', $embedding);
  $query->setQueryBy('text', 'smartphone'); // Fallback to keyword
  

Gotchas and Tips

Pitfalls

1. Schema Mismatches:

   • Issue: Typesense requires explicit schema definitions. Adding vectors without pre-defining fields (e.g., vector, id) will fail.
   • Fix: Define collections upfront or use dynamic schema updates:

     $client->collections()->create('dynamic_collection', [
         'fields' => [
             ['name' => 'vector', 'type' => 'float[]'],
             ['name' => 'metadata', 'type' => 'json'],
         ],
     ]);
     

2. Vector Dimension Limits:

   • Issue: Typesense has a hard limit of 100K dimensions. Exceeding this throws errors.
   • Fix: Validate embedding dimensions before storage:

     if (count($embedding) > 100000) {
         throw new \InvalidArgumentException('Embedding exceeds Typesense dimension limit.');
     }
     

3. Filter Syntax:

   • Issue: Incorrect filter syntax (e.g., missing quotes, wrong operators) causes silent failures.
   • Fix: Use Typesense’s filter syntax guide and validate filters:

     $query->setFilter('category: "electronics" AND price: >50'); // Note: `>` requires space
     

4. Connection Timeouts:

   • Issue: Slow responses or timeouts during peak loads.
   • Fix: Adjust Typesense client timeouts:

     $client = new Typesense(config('typesense.nodes'), config('typesense.api_key'), [
         'connection_timeout_seconds' => 5,
         'read_timeout_seconds' => 10,
     ]);
     

5. Metadata Size Limits:

   • Issue: Large metadata payloads (>64KB) may be truncated.
   • Fix: Compress or split metadata:

     $store->add($embedding, [
         'id' => $id,
         'name' => $name,
         // Avoid storing large blobs here; use external references instead
     ]);
     

Debugging Tips

• Enable Logging: Configure the Typesense client to log requests/responses:

  $client = new Typesense(config('typesense.nodes'), config('typesense.api_key'), [
      'log_level' => \Monolog\Logger::DEBUG,
  ]);
  

• Query Validation: Use Typesense’s API playground to test queries before implementing them in code.

• Performance Profiling: Monitor query latency with:

  $start = microtime(true);
  $results = $store->find($query);
  $latency = microtime(true) - $start;
  Log::debug("Query latency: {$latency}s");
  

Extension Points

1. Custom Distance Metrics: Extend the store to support non-Euclidean distances (e.g., cosine similarity):

   class CustomTypesenseStore extends TypesenseStore {
       public function __construct(Typesense $client, string $collection, string $distanceMetric = 'euclidean') {
           parent::__construct($client, $collection);
           $this->distanceMetric = $distanceMetric;
       }
   
       protected function buildQuery(Query $query): array {
           return [
               'vector' => $query->getVector(),
               'distance_metric' => $this->distanceMetric,
               // ... other params
           ];
       }
   }
   

2. Batch Processing: Implement chunked operations for large datasets:

   public function addBatch(array $vectors, array $metadatas, int $chunkSize = 100) {
       foreach (array_chunk($vectors, $chunkSize) as $i => $chunk) {
           $this->addMany(array_map(null, $chunk, array_chunk($metadatas, $chunkSize)));
       }
   }
   

3. Fallback Mechanisms: Decorate the store to handle failures gracefully:

   class FallbackTypesenseStore implements StoreInterface {
       public function __construct(private StoreInterface $store, private StoreInterface $fallback) {}
   
       public function find(Query $query) {
           try {
               return $this->store->find($query);
           } catch (Exception $e) {
               Log::warning("Typesense fallback triggered: " . $e->getMessage());
               return $this->fallback->find($query);
           }
       }
   }
   

4. Dynamic Collection Routing: Route vectors to collections based on metadata:

   public function add($vector, $metadata) {
       $collection = $metadata['tenant_id'] ?? 'default';
       $store = new TypesenseStore($this->client, $