Download the PHP package sellinnate/rag-engine without Composer

RAG Engine for Laravel

[]() []() []() []() []()

📖 Full documentation: laravel-rag-engine.selli.io

Add semantic search and AI answers over your own content to any Laravel app. RAG Engine owns the whole Retrieval-Augmented Generation pipeline — ingesting documents, splitting them, turning them into searchable vectors, and retrieving the most relevant passages for any query. Writing a final answer with an LLM is an optional layer on top.

Infrastructure, not a feature. The engine owns ingestion → retrieval; generation is optional and decoupled. Vertical packages, internal agents and search modules build on top without re-implementing ingestion, chunking, embedding or retrieval.

What you can build

• 🔎 Semantic search — a search box that matches by meaning, not keywords.
• 🤖 AI Q&A / chatbots — LLM answers grounded in your content, with citations.
• 📚 "Ask your docs / tickets / wiki" features inside an existing app.
• 🧭 Similarity / recommendations — "find records like this one".

Use just the search half (no LLM, no AI bill) or add generation later — same code, one config switch.

Table of contents

• Features
• Requirements
• Installation
• Quick start
• Indexing Eloquent models
• Asking questions with an LLM
• Configuration
• Supported drivers
• Security & multi-tenancy
• Documentation
• Testing & development
• License

Features

• Multi-format ingestion — raw text, file uploads, URLs (SSRF-guarded), cloud storage and Eloquent records. Safely parses Markdown, HTML, XML, CSV, JSON, DOCX and PDF.
• Pluggable everything — parsing, chunking, embedding, vector store, reranking and LLM are swappable drivers behind stable contracts.
• 10 embedding providers — OpenAI, Azure OpenAI, Mistral, Jina, Voyage, Cohere, Gemini, Hugging Face, Ollama, plus a deterministic fake driver for tests.
• Powerful retrieval — metadata filters, hybrid (semantic + keyword) search with RRF, MMR diversification, reranking, relevance thresholds and small-to-big (parent-child) context expansion.
• Embeddable Eloquent models — make any model searchable via one contract; recursive composition of relations, auto-sync on change, and vector→model trace-back.
• Security by design — BYOK envelope encryption with a KMS abstraction (local + AWS KMS), crypto-shredding for "right to erasure", and PII redaction on by default.
• OCR for scanned PDFs — pluggable OCR (Tesseract) kicks in when a PDF has no text layer.
• Quality evaluation — measure recall@k, precision@k, hit-rate and MRR over a labelled dataset (rag:evaluate).
• Resilient providers — LLM, reranker and embedder HTTP calls retry transient failures with exponential backoff.
• Multi-tenancy — automatic, fail-closed per-tenant scoping of every query.
• Operations from day one — immutable (WORM) audit log, cost tracking, lifecycle events, queued/batchable ingestion and Artisan commands.
• EU-resident by default — content and embeddings stay in the EU unless you explicitly opt into a non-EU provider.

Requirements

A dedicated vector database is not required to begin: the default store is in-memory, and the database store works on plain Postgres/MySQL/SQLite. Use native pgvector or Qdrant at larger scale.

Installation

The service provider and Rag facade auto-register via package discovery. Out of the box the package uses zero-network, deterministic drivers (fake embedder, in-memory store, local KMS) so your test suite runs offline.

[!IMPORTANT] The fake embedder is for tests only — it doesn't understand meaning. For a real search feature, configure a real embedder (see Configuration).

Quick start

Refine retrieval fluently:

Indexing Eloquent models

If the content you want to search already lives in your database, make the model embeddable — it then stays in sync automatically as rows change, and every vector traces back to its model.

Model file fields (a PDF/DOCX upload) can be embedded too — addFile() parses the file to text and folds it into the model's embedding; non-embeddable binaries (zip/exe…) are skipped or rejected per policy. See docs/concepts/eloquent-models.md.

Asking questions with an LLM

Search returns the relevant chunks; an LLM turns them into a written, cited answer via Rag::ask(). This layer is optional and decoupled — with the default null driver, ask() returns the sources with an empty answer, so search-only apps carry no LLM dependency.

The package ships two LLM drivers: anthropic (Claude) and openai (OpenAI and any OpenAI-compatible API — Mistral, Ollama, Groq, OpenRouter…).

[!NOTE] Anthropic has no embedding API, so anthropic is a generation-only driver. Keep a real RAG_EMBEDDER (Mistral, OpenAI, Ollama…) for the search side. A common combo is Mistral/Ollama embeddings + Claude answers.

Retrieved content is treated as untrusted: the default prompt fences it and tells the model not to follow instructions inside it (prompt-injection hardening). Full guide: docs/concepts/generation.md.

Configuration

Configuration lives in config/rag-engine.php and works like Laravel's config/database.php: you define named connections per subsystem and pick a default. Switching provider = changing one name in .env.

[!NOTE] API keys go in .env, never in the committed config. A copy-ready list of every variable ships as .env.example. See docs/getting-started/configuration.md.

Supported drivers

Embedders (RAG_EMBEDDER)

Vector stores (RAG_VECTOR_STORE): memory (tests/dev) · database (portable SQL: Postgres/MySQL/SQLite, brute-force) · pgvector (native Postgres ANN: vector column + HNSW + <=>) · qdrant (EU self-hostable, ANN at scale). Full setup, including where to configure the Postgres connection, is in the Vector stores guide.

LLMs (RAG_LLM, for ask()): anthropic (Claude) · openai (OpenAI and any OpenAI-compatible API: Mistral, Ollama, Groq, OpenRouter…) · null/fake. Anthropic is generation-only (no embeddings). Answers can be streamed with Rag::ask(...)->stream().

Rerankers (RAG_RERANKER, optional cross-encoder pass): cohere · jina (EU) · null/fake.

KMS (RAG_KMS, BYOK key management): local (dev) · aws (AWS KMS, production).

OCR (RAG_OCR, scanned-PDF fallback): null · tesseract.

Parsers: plain text · Markdown · HTML · XML · CSV/TSV · JSON · DOCX · PDF (+ OCR for scans).

Chunkers: recursive (default) · sentence · markdown · fixed (char- or token-based), with optional parent-child and contextual headers.

All drivers share one contract — switching backends needs no code changes, and you can register your own (see docs/guides/custom-drivers.md).

Security & multi-tenancy

• BYOK envelope encryption — content is encrypted at rest with per-item DEKs wrapped by a tenant KEK in a KMS; the plaintext key never persists.
• Crypto-shredding — honour "right to erasure" by destroying the key, making data unrecoverable everywhere (including DB backups) at once.
• PII redaction — emails, cards (Luhn), IBANs (mod-97), Italian fiscal codes and phone numbers are redacted before indexing, by default.
• Fail-closed multi-tenancy — every query is automatically scoped to the current tenant; scope can never be widened from a query (a tested invariant).
• Tamper-evident audit log — append-only with database-level WORM triggers.

See docs/concepts/security.md and docs/concepts/multi-tenancy.md.

Documentation

The full documentation is hosted at laravel-rag-engine.selli.io. The sources live in docs/ and are built into a static site with docmd:

Start here:

• 🧠 What is RAG? — concepts + glossary, from zero.
• 🚀 Quickstart — a complete worked example.
• 🏗️ Architecture — how the pieces fit together.
• 📥 Ingesting content · 🔎 Retrieval & search · 💬 Generation
• 🗄️ Vector stores & configuration — incl. pgvector Postgres setup.
• 📊 Evaluating quality — recall@k, MRR, rag:evaluate.
• 🧩 Contracts reference · 🛠️ Custom drivers

Testing & development

Quality gates kept green on every change: 429 tests, PHPStan level 8, Pint clean, ≥90% coverage.

License

MIT — see LICENSE.md.