Vektor Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require centamiv/vektor
   

   • Check composer.json for PHP version requirements (likely ^8.1).

2. Basic Initialization

   use Centamiv\Vektor\VectorDB;
   
   $db = new VectorDB('path/to/storage/directory');
   

   • Storage directory must be writable by the PHP process.

3. First Use Case: Insert & Query

   // Insert a vector (e.g., from an embedding model)
   $db->insert('collection_name', [0.1, 0.5, -0.3, ...]);
   
   // Query nearest neighbors
   $results = $db->query('collection_name', [0.2, 0.6, -0.4], limit: 5);
   

Where to Look First

• Documentation (if available) for API reference.
• src/Centamiv/Vektor/ for core classes (e.g., VectorDB, Collection).
• Benchmark scripts in /tests to understand performance tradeoffs.

Implementation Patterns

Workflow: Embedding Pipeline

1. Generate Embeddings Use a library like php-ai/phpsentencebert or symfony/serializer to convert text/images to vectors.

   $embedding = $embeddingModel->embed("Your data here");
   

2. Batch Insertion

   $db->insertBatch('products', [
       ['vector1', 'metadata1'],
       ['vector2', 'metadata2'],
   ]);
   

3. Hybrid Search Combine with Laravel’s query builder for metadata filtering:

   $vectorResults = $db->query('products', $queryVector, limit: 10);
   $filtered = Product::whereIn('id', $vectorResults['ids'])->get();
   

Integration Tips

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

  $this->app->singleton(VectorDB::class, function ($app) {
      return new VectorDB(storage_path('app/vektor'));
  });
  

• Caching Results Cache frequent queries with Illuminate\Support\Facades\Cache:

  $results = Cache::remember("vector_query_{$queryHash}", now()->addHours(1), function () use ($db) {
      return $db->query('collection', $vector);
  });
  

• Async Processing Use Laravel Queues for heavy embedding tasks:

  InsertEmbeddingJob::dispatch($data, 'collection_name');
  

Gotchas and Tips

Pitfalls

1. Binary Storage Quirks

   • Vectors are stored as raw binary. Ensure your vectors are normalized (unit length) to avoid distance metric skew.
   • Debugging Tip: Use hex2bin() to inspect stored vectors if queries return unexpected results.

2. RAM Overhead Myth

   • While advertised as "Zero-RAM," bulk operations may still spike memory. Test with memory_get_usage():

     $usage = memory_get_usage(true);
     

3. Collection Locking

   • Concurrent writes to the same collection may corrupt data. Use Laravel’s database connection locking:

     DB::transaction(function () use ($db) {
         $db->insert('collection', $vector);
     });
     

Debugging

• Verify Vector Dimensions Mismatched dimensions cause silent failures. Log dimensions pre-insert:

  $dimensions = count($vector);
  $db->insert('collection', $vector); // Throws if $dimensions !== collection's expected dims
  

• Check Storage Permissions If inserts fail, verify the storage directory is writable:

  chmod -R 755 storage/app/vektor
  

Extension Points

1. Custom Distance Metrics Extend Centamiv\Vektor\Metrics\DistanceInterface for cosine/specialized distances:

   class CustomMetric implements DistanceInterface {
       public function calculate(array $a, array $b): float { ... }
   }
   

2. Indexing Strategies Override Centamiv\Vektor\Collection::buildIndex() for custom partitioning (e.g., by metadata).

3. Laravel Scout Driver Implement a VektorEngine for Laravel Scout:

   class VektorEngine extends Engine {
       public function search($query, array $options) { ... }
   }