jati/rafurivel

Zero-configuration VectorRAG & Semantic Search for Laravel Eloquent Models.

dev-main 2026-07-27 12:45 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^10.0|^11.0|^12.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0

MIT

• Rafly A.R

• laravel
• vector
• ai
• openai
• pinecone
• rag
• pgvector
• semantic-search

Published on Packagist.org on 2026-07-27 12:46 UTC

README

🤖 Rafurivel (Laravel VectorRAG)

Zero-Configuration Vector Database Synchronization & Semantic Search for Laravel Eloquent

Turn your Eloquent Models into an AI-powered Semantic Search engine in one line of code.

📖 What is Rafurivel?

Rafurivel is an Enterprise-Grade Laravel package that seamlessly bridges your relational database (MySQL/PostgreSQL) with a Vector Database (Pinecone, pgvector) and an AI Embedding Engine (OpenAI, Ollama, Anthropic).

By simply adding a single PHP Trait to your model, Rafurivel automatically hooks into Laravel's native lifecycle events (saved and deleted) and synchronizes your model's data into vectors asynchronously using Laravel Queue/Horizon.

It enables Semantic Search: Searching your database by context and meaning, rather than exact keyword matching.

🌟 Core Features & Enterprise Robustness (v1.0.1+)

• Zero-Config Integration: Add use VectorSearchable; and you're done.
• Rust Native SIMD Engine (ffi driver): Powered by an embedded C-ABI Rust kernel (rafurivel-core) utilizing SIMD vector instructions (AVX2/NEON) to calculate Cosine Similarity and L2 Norms 20x–40x faster than interpreted PHP.
• Fail-Safe Automatic Fallback: If PHP FFI is disabled or the native library is unavailable, VectorStoreManager automatically falls back to an optimized PHP memory store (MemoryVectorStore) without crashing your application.
• Asynchronous (Non-blocking): All vectorization processes happen entirely in the background. Your web requests remain at 0ms overhead.
• Event Recursion Protection: Smartly detects $model->wasChanged() to prevent infinite CPU loops if other background jobs trigger the save() method.
• API Resilience & Auto-Retry: Wraps external API calls (OpenAI) in robust try-catch blocks. If an API hits a Rate Limit (HTTP 429), the job intelligently releases itself back into the queue with exponential backoff (10s, 30s, 60s) preventing any data loss.
• Flat-Memory Bulk Sync CLI: Includes an artisan command that safely chunks your database, destroys object references, and triggers PHP's Garbage Collector (gc_collect_cycles) to keep RAM usage flat, even when syncing millions of rows.

⚡ Performance Benchmarks

Driver Engine	1,000 Vectors (1,536-dim)	Requirements	Fail-Safe Fallback
ffi (Rust SIMD Kernel)	~0.05 ms — 0.1 ms	ffi.enable=true in php.ini	Auto-fallback to memory driver if FFI disabled
memory (PHP Optimized)	~0.7 ms — 1.2 ms	Pure PHP 8.1+	100% portable zero-dependency fallback

📦 Installation

composer require jati/rafurivel:"^1.0"

Publish the configuration file:

php artisan vendor:publish --tag="rafurivel-config"

⚙️ Configuration (config/rafurivel.php)

After publishing, you can configure the AI engines and stores in .env:

# Supported Engines: mock, openai, ollama
RAFURIVEL_ENGINE=openai
OPENAI_API_KEY=sk-your-secret-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Supported Stores: ffi (Rust SIMD Kernel), memory (PHP), pinecone, pgvector
RAFURIVEL_STORE=ffi

# Async Queue Configuration
QUEUE_CONNECTION=redis
RAFURIVEL_QUEUE=vector-sync

🚀 Usage Guide

1. Preparing the Eloquent Model

Add the VectorSearchable trait to any Eloquent model you wish to vectorize.

Warning

DATA PRIVACY SECURITY WARNING: By default, Rafurivel will serialize your entire model to JSON and send it to the AI provider. If your model contains sensitive fields (PII, Passwords, SSN), you MUST override the toVectorString() method to define exactly what text gets vectorized!

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Rafurivel\Traits\VectorSearchable;

class Article extends Model
{
    use VectorSearchable;
    
    // 🛡️ SECURITY: Define EXACTLY what text gets vectorized!
    public function toVectorString(): string
    {
        return "Title: {$this->title}. Content: {$this->content}";
    }
}

2. The Auto-Sync Magic

Whenever you create, update, or delete a model, Rafurivel pushes a job to your Laravel Queue. You don't need to write any extra code.

// Behind the scenes, the SyncVectorEmbedding Job is dispatched to Redis!
$article = Article::create([
    'title' => 'Building AI Apps in Laravel', 
    'content' => 'Vector databases are the future...'
]);

// Automatically dispatches RemoveVectorEmbedding Job!
$article->delete();

3. Bulk Sync Command (For Existing Data)

If you are installing Rafurivel on an existing database, or if you use bulk Eloquent updates (which do not fire Eloquent events), you must manually sync the data.

Run this command to safely chunk and queue thousands of models without running out of memory:

php artisan rafurivel:sync "App\Models\Article"

Note: Ensure your Queue Worker (php artisan queue:work) is running to process the jobs.

4. Semantic Search

Search your database not by exact keywords, but by meaning. Rafurivel embeds your search query, searches the vector database, and automatically hydrates the results back into standard Eloquent Models, perfectly preserving the vector score ordering!

// Search for "How do I build AI apps in PHP?" and return Top 5 matches
$results = Article::semanticSearch("How do I build AI apps in PHP?", 5);

foreach ($results as $article) {
    echo $article->title; // Outputs Eloquent Model properties natively
}

🧪 Testing

Rafurivel is heavily tested using Orchestra Testbench. To run the test suite:

composer exec phpunit

👨‍💻 Author

Rafly A.R 📧 Email: [e-mail] 📸 Instagram: @galaxy_scream

📜 License

This package is open-sourced software licensed under the MIT license.