hamzi / nativerag

v1.2.0 2026-10-04 16:14 UTC

Requires

• php: ^8.2|^8.5
• illuminate/database: ^11.0|^12.0|^13.0
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0
• symfony/http-foundation: ^7.0|^8.0

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^9.0|^10.0|^11.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Hamdy Elbatal

• php
• laravel
• ai
• embedding
• llm
• ollama
• rag
• lmstudio
• vector-search
• local-ai

Published on Packagist.org on 2026-10-04 16:15 UTC

README

Laravel NativeRAG

Local retrieval-augmented generation tools for Laravel applications

NativeRAG connects Laravel applications to local chat and embedding models hosted in Ollama or LM Studio.

It stores document chunks, embeddings, and conversations in your application database, so small RAG workflows can run without a separate vector service.

Features

• Switch between Ollama and LM Studio using Laravel's manager pattern.
• Store embeddings in the application database and search them with SQLite or PHP-side cosine similarity.
• Stream chat responses over server-sent events.
• Add automatic chunking and embedding sync to Eloquent models with the Embeddable trait.
• Persist conversation history with count-based or token-based pruning.
• Optionally encrypt stored conversation content and metadata.
• Run on PHP 8.2+ with PHPUnit, Pint, and PHPStan configuration included.

Compatibility

Laravel	PHP	Status
13.x	8.2, 8.3, 8.4, 8.5	Supported
12.x	8.2, 8.3, 8.4, 8.5	Supported
11.x	8.2, 8.3, 8.4, 8.5	Supported

Installation

Install the package via Composer:

composer require hamzi/nativerag

Publish configuration and migrations:

php artisan vendor:publish --tag="nativerag-config"
php artisan vendor:publish --tag="nativerag-migrations"
php artisan migrate

Configuration

Set your driver settings in .env:

NATIVE_RAG_DRIVER=ollama

# Ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_CHAT_MODEL=llama3
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

# LM Studio
LMSTUDIO_BASE_URL=http://localhost:1234
LMSTUDIO_CHAT_MODEL=meta-llama-3-8b-instruct
LMSTUDIO_EMBEDDING_MODEL=nomic-embed-text

# Chunking & Search
NATIVE_RAG_CHUNK_SIZE=1000
NATIVE_RAG_CHUNK_OVERLAP=200
NATIVE_RAG_MIN_SCORE=0.35

# Conversation Memory
NATIVE_RAG_MAX_HISTORY_COUNT=10
NATIVE_RAG_PRUNING_STRATEGY=count
NATIVE_RAG_PRESERVE_SYSTEM_MESSAGES=true

# Security
NATIVE_RAG_ENCRYPT_PAYLOADS=false

Usage

Chat Completions

use Hamzi\NativeRag\Facades\NativeRag;

$response = NativeRag::chat([
    ['role' => 'system', 'content' => 'You are an experienced software engineer.'],
    ['role' => 'user',   'content' => 'Explain service containers briefly.'],
]);

echo $response->content;
echo $response->promptTokens;
echo $response->completionTokens;

Server-Sent Events (SSE) Streaming

use Hamzi\NativeRag\Facades\NativeRag;
use Illuminate\Support\Facades\Route;

Route::post('/api/ai/stream', function () {
    return NativeRag::stream([
        ['role' => 'user', 'content' => 'Write a short overview of Laravel Eloquent.'],
    ]);
});

Consume in JavaScript:

const source = new EventSource('/api/ai/stream');

source.onmessage = ({ data }) => {
    const { content, done } = JSON.parse(data);
    if (done) {
        source.close();
        return;
    }
    document.querySelector('#output').insertAdjacentText('beforeend', content);
};

Auto-Indexing Models

Implement EmbeddableContract and use the Embeddable trait on an Eloquent model:

namespace App\Models;

use Hamzi\NativeRag\Contracts\EmbeddableContract;
use Hamzi\NativeRag\Traits\Embeddable;
use Illuminate\Database\Eloquent\Model;

class Article extends Model implements EmbeddableContract
{
    use Embeddable;

    public function toEmbeddableString(): string
    {
        return "Title: {$this->title}\n\nContent: {$this->content}";
    }
}

When saved, the model's embeddable text is automatically chunked and synchronized. Unchanged records are skipped via MD5 hash comparison.

Semantic Vector Search

Search indexed chunks with a text query or a raw vector array:

use Hamzi\NativeRag\Facades\NativeRag;

// Search directly using a question string (embeds automatically)
$results = NativeRag::search('How does database indexing work?', limit: 5, minScore: 0.40);

foreach ($results as $chunk) {
    echo $chunk->chunk_content;
    echo $chunk->similarity;
}

// Or search with an existing embedding vector
$vector = NativeRag::embedding()->embed('Query text');
$results = NativeRag::search($vector, limit: 5);

Multi-Turn Conversations

use Hamzi\NativeRag\Models\NativeRagConversation;

$conversation = NativeRagConversation::create([
    'name' => 'Support Session #101',
]);

$conversation->addSystemMessage('You are a technical support representative.');

$response = $conversation->ask('How do I run database migrations?');
echo $response->content;

// The next message keeps the full conversation history
$followUp = $conversation->ask('Can I roll back the last batch?');
echo $followUp->content;

Memory Pruning

• count (default): Retains the latest N messages.
• token: Retains messages within a token threshold (ceil(chars / 4) approximation when token count is null).
• preserve_system_messages: System prompts are preserved from deletion by default.

Driver Switching

use Hamzi\NativeRag\Facades\NativeRag;

$response = NativeRag::driver('lmstudio')->chat([
    ['role' => 'user', 'content' => 'Summarize this file.'],
]);

Security

• Local Inference: Queries never leave your server.
• Database Encryption: Enable NATIVE_RAG_ENCRYPT_PAYLOADS=true to encrypt stored message bodies and metadata via Laravel's encryption service.
• Prepared Queries: Built entirely on Laravel's query builder.

Testing & Quality Checks

composer test
composer lint
composer analyse

Contributing

Please review CONTRIBUTING.md for guidelines on code style, tests, and pull requests.

Security Vulnerabilities

Please report security issues according to our policy in SECURITY.md.

License

The MIT License (MIT). See LICENSE.md for details.