rubyat/laravel-rag

A production-ready Retrieval-Augmented Generation (RAG) toolkit for Laravel with PostgreSQL + pgvector. Ingest documents, store embeddings, and answer questions grounded only in your own content — with source citations.

Features

• 🧩 Document ingestion — text is chunked (configurable size/overlap), embedded, and stored.
• 🔎 pgvector vector search — cosine similarity over an HNSW index for high recall at any scale.
• 💬 RAG pipeline — retrieves the most relevant chunks and asks an LLM to answer from them.
• 📎 Source citations — every answer returns the chunks it used, with similarity scores.
• 🔌 Driver-based — swap embedding/chat providers; OpenAI built-in, plus deterministic fake drivers for offline dev and tests (no API key, no network).
• ⚙️ Sync or queued ingestion — inline by default, or dispatch a job for large documents.
• 🌐 HTTP API — ready-to-use POST /api/rag/ingest and POST /api/rag/ask endpoints.
• ✅ Tested — ships with a Pest suite that runs against pgvector using the fake drivers.

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13
• PostgreSQL with the pgvector extension (0.5+ for HNSW)

Installation

composer require rubyat/laravel-rag

Publish the config and run the migration:

php artisan vendor:publish --tag=rag-config
php artisan migrate

The migration runs CREATE EXTENSION IF NOT EXISTS vector, which needs a database role allowed to create extensions. The pgvector Docker image (pgvector/pgvector:pg16) is the quickest way to get it locally.

Configure a provider (or keep the offline fake drivers — no network needed):

OPENAI_API_KEY=sk-...
RAG_EMBEDDING_DRIVER=openai
RAG_CHAT_DRIVER=openai

Quick Start

In code

use Rubyat\LaravelRag\Ingestion\DocumentIngestor;
use Rubyat\LaravelRag\Rag\RagPipeline;

// Ingest a document (chunk -> embed -> store in pgvector)
app(DocumentIngestor::class)->ingest('handbook.md', $longText);

// Ask a question grounded in the ingested chunks
$result = app(RagPipeline::class)->ask('How does pgvector search work?');

$result['answer'];     // string — grounded in your documents
$result['citations'];  // array — [{ source, chunk_index, content, score }, ...]

HTTP API

Ingest:

curl -X POST http://localhost:8000/api/rag/ingest \
  -H "Content-Type: application/json" \
  -d '{"source": "handbook.md", "content": "Postgres pgvector stores embeddings and supports cosine similarity search..."}'
# => 201 { "message": "Document ingested.", "source": "handbook.md", "chunks": 1 }

Ask:

curl -X POST http://localhost:8000/api/rag/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "How does pgvector search work?", "top_k": 4}'
# => 200
# {
#   "answer": "pgvector stores embeddings and supports cosine similarity search...",
#   "citations": [
#     { "source": "handbook.md", "chunk_index": 0, "content": "...", "score": 0.83 }
#   ]
# }

Configuration

Published to config/rag.php. Every option is environment-driven:

The fake drivers are deterministic and require no network access — they power the test suite and let you try the full flow without API keys.

Swappable drivers

Embedding and chat providers are resolved from config and implement small contracts, so you can plug in your own:

use Rubyat\LaravelRag\Contracts\EmbeddingDriver;
use Rubyat\LaravelRag\Contracts\ChatDriver;

Built in: OpenAiEmbeddingDriver / OpenAiChatDriver (HTTP) and FakeEmbeddingDriver / FakeChatDriver (offline, deterministic).

How it works

            ingest                                   ask
              │                                        │
              ▼                                        ▼
      DocumentChunker                          VectorRetriever
              │ chunks                                 │ query embedding
              ▼                                         ▼
      EmbeddingDriver ─── embeddings ──►  pgvector documents (HNSW, cosine)
                                                        │ top-k chunks
                                                        ▼
                                                  RagPipeline
                                                  (context + LLM)
                                                        ▼
                                              answer + citations

Documents are stored one row per chunk in the documents table (source, chunk_index, content, metadata, embedding vector(n)), indexed with HNSW (vector_cosine_ops). Retrieval orders by cosine distance (embedding <=> :query) and returns a similarity score in [0, 1].

Testing

The suite runs against PostgreSQL + pgvector using the deterministic fake drivers, so no API keys or network are required:

./vendor/bin/pest

License

The MIT License (MIT). See LICENSE.