Download the PHP package moneo/laravel-rag without Composer

Laravel RAG

A complete, driver-based RAG (Retrieval-Augmented Generation) pipeline for Laravel. Built on Prism PHP for provider-agnostic LLM and embedding support.

Features

• Driver-based vector stores — pgvector (production) and sqlite-vec (local dev), swappable via .env
• Blueprint macros — $table->vector(), $table->vectorIndex() feel native to Laravel
• Model traits — HasVectorSearch and AutoEmbeds for zero-boilerplate integration
• Embedding cache — SHA-256 deduplication reduces API costs by 60-80%
• Chunking strategies — Character, Sentence, Markdown, and Semantic chunkers
• Fluent RAG pipeline — Rag::from(Document::class)->ask('question')
• Streaming SSE — Real-time response streaming via Server-Sent Events
• Agentic RAG — Iterative retrieval with sufficiency evaluation
• Hybrid search — Reciprocal Rank Fusion (RRF) combining semantic + full-text
• LLM re-ranking — Score and re-order chunks by relevance
• Conversation memory — Threaded conversations with automatic context summarization
• RAG Evals — First Laravel-native evaluation framework (Faithfulness, Relevancy, Context Recall)
• MCP Server — Expose your RAG as MCP tools for Claude Desktop, Cursor, etc.
• Artisan commands — rag:index, rag:test, rag:estimate, rag:eval, rag:mcp-serve
• DevTools — Debugbar collector and Telescope watcher
• Livewire component — Drop-in <livewire:rag-chat> with streaming and sources
• Filament plugin — Admin panel for documents, embeddings, and interactive testing

Requirements

• PHP 8.2+
• Laravel 11+
• Prism PHP ^0.100

Vector store (choose one):

• pgvector (recommended for production) — PostgreSQL + pgvector extension
• sqlite-vec (local dev, Docker/Linux only) — sqlite-vec

Note: sqlite-vec requires PHP compiled with SQLite extension loading support. macOS PHP (Herd, Homebrew) does not support this. Use Docker, Laravel Sail, or switch to pgvector on macOS.

Installation

Publish the config:

Run migrations:

Configuration

Vector Store Setup

Option A: pgvector (recommended)

Works everywhere. Requires PostgreSQL with pgvector extension.

Option B: sqlite-vec (Docker/Linux only)

Zero-infrastructure local dev. Does NOT work on macOS Herd/Homebrew PHP.

Linux (Ubuntu/Debian):

Docker / Laravel Sail:

macOS: sqlite-vec is not supported with Herd or Homebrew PHP. Use pgvector instead:

Quick Start

1. Prepare Your Model

2. Create a Migration

3. Ingest Content

4. Query

Streaming

Hybrid Search

Re-ranking

Agentic RAG

Conversation Memory

Chunking Strategies

RAG Evals

CLI:

MCP Server

Artisan Commands

Livewire Component

Filament Plugin

DevTools

Debugbar

Auto-registers when barryvdh/laravel-debugbar is installed. Shows:

• RAG call count, chunks retrieved
• Cache hit/miss rate
• Retrieval vs generation timing

Telescope

Auto-registers when laravel/telescope is installed. Records:

• Embedding generation events
• Cache hit events

Error Handling & Retry

All Prism API calls are wrapped in PrismRetryHandler with exponential backoff:

• Rate limits (429): retried with backoff + jitter, throws EmbeddingRateLimitException after 3 attempts
• Server errors (5xx): retried once, throws EmbeddingServiceException
• Timeouts: throws EmbeddingTimeoutException
• Malformed responses: throws EmbeddingResponseException
• Dimension mismatch: throws DimensionMismatchException before storage

Exception hierarchy:

Structured Logging

All operations emit structured logs via RagLogger (channel: rag.*):

• rag.embedding.* — API calls, cache hits/misses
• rag.retrieval.* — search operations
• rag.generation.* — LLM generation
• rag.cache.* — cache operations
• rag.error.* — all caught exceptions with context

Text fields are SHA-256 hashed for privacy — raw user input never appears in logs.

Custom Vector Store Driver

Implement VectorStoreContract:

Register in a service provider:

Benchmarks

Benchmarks run on Apple M2 Pro, PostgreSQL 16 with pgvector 0.7. Results may vary.

Security

This package ships with built-in security hardening:

• Input Sanitisation — InputSanitiser::clean() strips 40+ known prompt injection patterns before text reaches the LLM
• Vector Validation — VectorValidator::validate() checks dimensions, NaN, and infinity before every upsert
• Cache Integrity — HMAC-signed cache keys prevent tampered cache entries; corrupted entries are auto-evicted
• SQL Injection Protection — Table names are validated against a strict regex before SQL interpolation
• MCP Input Validation — Malformed JSON-RPC requests return errors without executing retrieval

Testing

Quality Gates

All of these must pass before merge:

Contributing

1. Fork the repo and create a feature branch
2. Write tests first — every new feature needs unit + feature tests

3. Run the full quality gate suite locally:

4. Ensure all architecture tests pass: vendor/bin/pest --testsuite=Architecture
5. Submit a PR — CI will run the full matrix automatically

Adding a Custom Vector Store Driver

Community drivers should:

• Follow naming: moneo/laravel-rag-{driver} (e.g., moneo/laravel-rag-qdrant)
• Implement VectorStoreContract
• Extend VectorStoreContractTest from this package to prove compliance
• Target MSI >= 90% for the driver code

Security

See SECURITY.md for vulnerability disclosure policy and security measures.

License

MIT License. See LICENSE for details.