Ai Neo4J Store Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Add to composer.json:

   {
     "require": {
       "symfony/ai-neo4j-store": "^0.8",
       "neo4j/neo4j-php-client": "^5.0",
       "symfony/ai": "^1.0"
     }
   }
   

   Run composer update.

2. Configure Neo4j Ensure your Neo4j instance (5.12+) has a semantic vector index pre-configured. Example Cypher:

   CREATE SEMANTIC INDEX `document_embeddings`
   FOR (d:Document)
   OPTIONS {
     `vector.dimensions`: 1536,
     `vector.similarity_function`: 'cosine'
   };
   

3. Basic Laravel Integration Bind the store in AppServiceProvider:

   use Symfony\Component\AI\Store\Neo4jStore;
   use Neo4j\ClientBuilder;
   
   public function register()
   {
       $this->app->singleton(\Symfony\Component\AI\VectorStoreInterface::class, function ($app) {
           $client = ClientBuilder::create()
               ->withUri(env('NEO4J_URI'))
               ->withBasicAuth(env('NEO4J_USER'), env('NEO4J_PASSWORD'))
               ->build();
           return new Neo4jStore($client, 'Document');
       });
   }
   

4. First Use Case: Storing Embeddings

   use Symfony\Component\AI\VectorStoreInterface;
   
   $store = app(VectorStoreInterface::class);
   $store->add(
       id: 'doc_123',
       vector: [0.1, 0.2, ..., 0.9], // Your embedding array
       metadata: ['title' => 'Laravel AI', 'author' => 'Jane Doe']
   );
   

5. Querying with Filters

   $results = $store->similaritySearch(
       query: [0.5, 0.6, ..., 0.4], // Query embedding
       limit: 5,
       filter: ['author' => 'Jane Doe'] // Neo4j property filter
   );
   

Implementation Patterns

Core Workflows

1. Hybrid Graph-Vector Queries

Leverage Neo4j’s native graph traversals alongside vector search. Example:

// Find documents similar to query AND connected to a specific author
$results = $store->similaritySearch(
    query: $queryEmbedding,
    filter: [
        'author' => 'Jane Doe',
        'category' => 'tutorial'
    ]
);
// Under the hood, this translates to Cypher with MATCH clauses.

2. Batched Operations

Use Laravel’s collect() + chunking for bulk inserts:

use Illuminate\Support\Collection;

$documents = collect($rawData)->chunk(100);
$documents->each(function ($chunk) use ($store) {
    foreach ($chunk as $doc) {
        $store->add(
            id: $doc['id'],
            vector: $doc['embedding'],
            metadata: $doc['metadata']
        );
    }
});

3. Dynamic Filtering with User Input

Build a flexible search endpoint:

// routes/web.php
Route::get('/search', function (Request $request, VectorStoreInterface $store) {
    $filter = $request->only(['author', 'category', 'year']);
    $results = $store->similaritySearch(
        query: $request->queryEmbedding,
        filter: $filter
    );
    return response()->json($results);
});

4. Integration with AI Pipelines

Combine with Symfony AI’s EmbeddingGenerator:

use Symfony\Component\AI\EmbeddingGeneratorInterface;

$generator = app(EmbeddingGeneratorInterface::class);
$store = app(VectorStoreInterface::class);

$text = "Explain Laravel Eloquent";
$embedding = $generator->generate($text);
$results = $store->similaritySearch($embedding, limit: 3);

Advanced Patterns

Custom Metadata Indexing

Extend Neo4j’s schema for complex queries:

// Add a relationship index for traversal
CREATE INDEX `doc_author_index` FOR ()-[r:WRITTEN_BY]->(author:Author)

Laravel Query Builder Integration

Create a custom query builder for fluent syntax:

class Neo4jVectorQueryBuilder
{
    public function whereAuthor(string $author): self
    {
        $this->filter['author'] = $author;
        return $this;
    }

    public function whereCategory(string $category): self
    {
        $this->filter['category'] = $category;
        return $this;
    }

    public function build(): array
    {
        return $this->filter;
    }
}

// Usage:
$query = (new Neo4jVectorQueryBuilder())
    ->whereAuthor('Jane Doe')
    ->whereCategory('tutorial')
    ->build();

$results = $store->similaritySearch($embedding, filter: $query);

Caching Layer

Cache frequent queries with Laravel’s cache:

$cacheKey = md5(serialize($queryEmbedding) . json_encode($filter));
$results = cache()->remember($cacheKey, now()->addHours(1), function () use ($store, $queryEmbedding, $filter) {
    return $store->similaritySearch($queryEmbedding, filter: $filter);
});

Event-Driven Updates

Use Laravel events to sync data:

// In a service
event(new DocumentEmbeddingGenerated($documentId, $embedding));

// Listener
public function handle(DocumentEmbeddingGenerated $event, VectorStoreInterface $store)
{
    $store->add(
        id: $event->documentId,
        vector: $event->embedding,
        metadata: ['updated_at' => now()]
    );
}

Gotchas and Tips

Pitfalls

1. Vector Index Configuration

• Issue: Forgetting to create the semantic index before queries.
• Fix: Add a migration or artisan command to verify/index setup:

  // app/Console/Commands/SetupNeo4jIndex.php
  public function handle()
  {
      $client = ClientBuilder::create()->build();
      $client->run('CREATE SEMANTIC INDEX IF NOT EXISTS `document_embeddings` FOR (d:Document) OPTIONS {`vector.dimensions`: 1536}');
  }
  

2. Filter Syntax Mismatches

• Issue: Neo4j filters use Cypher property paths, not dot notation.
  • ❌ Wrong: filter: ['user.name' => 'John']
  • ✅ Correct: filter: ['name' => 'John'] (for User node property)
• Fix: Map Laravel Eloquent-style filters to Neo4j properties explicitly.

3. Embedding Dimension Mismatch

• Issue: Vector dimensions in the index must match your embeddings.
  • ❌ vector.dimensions: 768 (index) vs. embedding length 1536.
• Fix: Validate dimensions during add():

  if (count($vector) !== config('neo4j.vector_dimensions')) {
      throw new \InvalidArgumentException('Vector dimension mismatch');
  }
  

4. Neo4j Driver Timeouts

• Issue: Long-running queries (e.g., large similaritySearch) may timeout.
• Fix: Adjust driver settings:

  $client = ClientBuilder::create()
      ->withConnectionTimeout(30)
      ->withMaxConnectionLifetime(60)
      ->build();
  

5. Metadata Property Limits

• Issue: Neo4j has property size limits.
• Fix: Normalize metadata or use a separate Metadata node with relationships.

Debugging Tips

Enable Neo4j Query Logging

Add this to your AppServiceProvider:

$client = ClientBuilder::create()
    ->withLogging(function ($query, $params) {
        \Log::debug("Neo4j Query: {$query}", $params);
    })
    ->build();

Validate Cypher Queries

Use the Neo4j Browser to test queries manually before integrating:

// Test a similarity search
CALL db.index.vector.queryNodes('document_embeddings', [0.1, 0.2, ...], 5)
YIELD node, score
RETURN node.title, score

Monitor Index Performance

Check index usage in Neo4j:

SHOW INDEXES YIELD name, type, labelsOrTypes, properties, options;

Extension Points

Custom Store Decorator

Wrap the Neo4j store to add pre/post-processing:

class CachedNe