Ai Neo4J Store Laravel Package

Technical Evaluation

Architecture Fit

• Hybrid Graph-Vector Use Cases: The package is a perfect fit for Laravel applications requiring semantic search with relational context, such as:
  • Knowledge graphs (e.g., legal research, scientific literature).
  • Recommendation engines (e.g., "Users who bought X also liked Y, and are in the same demographic").
  • Fraud detection (e.g., "Find transactions similar to this pattern and connected to high-risk entities").
• Symfony AI Ecosystem: If the Laravel app already uses Symfony AI components (e.g., for embeddings or LLM orchestration), this package integrates natively. For pure Laravel, minimal abstraction (e.g., a service wrapper) is required to avoid Symfony dependencies.
• Alternatives Comparison:
  • Overkill for simple vector search: If graph context isn’t needed, consider symfony/ai-memory-store or symfony/ai-postgresql-store.
  • Better for scalability: For planet-scale vector search, specialized stores like Pinecone or Weaviate may outperform Neo4j’s vector indexes.

Integration Feasibility

• Neo4j Setup:
  • Requires Neo4j 5.12+ and the neo4j-php-client. Laravel can deploy this via Docker or a managed service (e.g., AuraDB).
  • Schema Design: Vector indexes must be pre-configured via Cypher (one-time cost). Example:

    CREATE SEMANTIC INDEX `document_embeddings`
    FOR (d:Document)
    OPTIONS {indexConfig: {
      `vector.dimensions`: 768,
      `vector.similarity_function`: 'cosine',
      `vector.index_type`: 'vector-hnsw'
    }}
    

• Laravel-Symfony Bridge:
  • Bind Symfony’s VectorStoreInterface to the Neo4j store in Laravel’s service container:

    $this->app->bind(\Symfony\Component\AI\VectorStoreInterface::class, function ($app) {
        return new \Symfony\Component\AI\Store\Neo4jStore(
            new \Neo4j\ClientBuilder()->withUri(env('NEO4J_URI'))->build()
        );
    });
    

• Data Migration:
  • No built-in tools; use Cypher LOAD CSV or custom Laravel jobs. Example:

    LOAD CSV WITH HEADERS FROM 'file:///data.csv' AS row
    CREATE (:Document {
      text: row.content,
      embedding: apoc.convert.fromJsonList(row.vector),
      metadata: apoc.convert.fromJsonMap(row.metadata)
    })
    

Technical Risk

Key Questions

1. Is Neo4j’s graph context a hard requirement, or could a simpler vector store (e.g., pgvector) suffice for the use case?
2. What’s the expected query pattern? Neo4j excels at graph-aware filtering (e.g., "Find embeddings where author = X AND year > 2020 AND category IN ['AI', 'ML']").
3. How will data be ingested? Bulk loads via Cypher or incremental updates via Laravel jobs?
4. What’s the fallback if Neo4j’s vector search is too slow? Consider hybrid caching (e.g., Redis for hot vectors) or pre-filtering with a traditional index.
5. Are there existing Neo4j graphs to leverage, or will this require a new schema? If new, plan for data modeling workshops to design relationships.
6. How will monitoring and observability be implemented? Neo4j’s query performance should be tracked (e.g., EXPLAIN plans, latency metrics).
7. What’s the disaster recovery plan? Neo4j backups must be automated and tested for restore speed.

Integration Approach

Stack Fit

• Laravel + Symfony AI:
  • Option 1: Direct Symfony AI integration (if Laravel can tolerate Symfony dependencies).
  • Option 2: Create a Laravel-compatible facade to hide Symfony classes:

    namespace App\Services;
    
    use Symfony\Component\AI\VectorStoreInterface;
    use Neo4j\ClientBuilder;
    
    class Neo4jVectorStore implements \Symfony\Component\AI\VectorStoreInterface {
        public function __construct(private VectorStoreInterface $store) {}
        // Delegate to Symfony store with Laravel-friendly methods...
    }
    

• Neo4j Compatibility:
  • Driver: neo4j/neo4j-php-client (v5+ for vector support).
  • Schema: Requires semantic indexes (configured via Cypher).
  • Alternatives: If Neo4j is overkill, consider:
    • PostgreSQL + pgvector (for simpler vector search with SQL familiarity).
    • Milvus/Weaviate (for distributed scaling and open-source maturity).

Migration Path

1. Assess Current State:
   • Audit existing vector storage (e.g., Elasticsearch, flat files, or in-memory arrays).
   • Map entities to Neo4j nodes/relationships (e.g., Post → :Document, User → :Author).
2. Schema Design:
   • Define labels, properties, and relationships (e.g., :Document {text: string, embedding: float[], category: string}).
   • Plan for semantic index creation (one-time setup) and constraints (e.g., CREATE CONSTRAINT ON (d:Document) ASSERT d.id IS UNIQUE).
3. Data Migration:
   • Use Cypher LOAD CSV for bulk imports or Laravel jobs for incremental updates:

     // Example Laravel job for bulk import
     public function handle() {
         $records = Model::chunk(1000, function ($chunk) {
             $this->neo4jClient->run(
                 'UNWIND $records AS r
                  CREATE (d:Document {
                    text: r.content,
                    embedding: apoc.convert.fromJsonList(r.vector),
                    metadata: apoc.convert.fromJsonMap(r.metadata)
                  })',
                 ['records' => $chunk->toArray()]
             );
         });
     }
     

4. Laravel Integration:
   • Install dependencies:

     composer require symfony/ai-neo4j-store neo4j/neo4j-php-client
     

   • Bind the store in AppServiceProvider:

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

5. Testing:
   • Validate CRUD operations with unit tests:

     public function testNeo4jVectorStore() {
         $store = $this->app->make(\Symfony\Component\AI\VectorStoreInterface::class);
         $embedding = [1.0, 2.0, 3.0];
         $store->add($embedding);
         $results = $store->similaritySearch([1.1, 2.1, 3.1]);
         $this->assertCount(1, $results);
     }
     

   • Test graph-aware queries:

     $results = $store->similaritySearch([1.1, 2.1, 3.1], [
         '