PHPackages ayaashraf/laravel-rag - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. ayaashraf/laravel-rag ActiveLibrary[Utility & Helpers](/categories/utility) ayaashraf/laravel-rag ===================== A production-ready RAG (Retrieval-Augmented Generation) package for Laravel using pgvector and Livewire v1.0.15(1mo ago)024MITPHPPHP ^8.3 Since May 19Pushed 1mo agoCompare [ Source](https://github.com/ayaashraf-cla/laravelRag)[ Packagist](https://packagist.org/packages/ayaashraf/laravel-rag)[ RSS](/packages/ayaashraf-laravel-rag/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (26)Versions (17)Used By (0) Laravel RAG Package =================== [](#laravel-rag-package) A production-ready **Retrieval-Augmented Generation (RAG)** package for Laravel using pgvector and Livewire. Features -------- [](#features) - 🔍 **Vector Semantic Search** using pgvector with PostgreSQL - 📄 **Multi-format Document Processing** (PDF, DOCX, TXT, XLS, XLSX, CSV) - 🧠 **AI-powered Document Chunking** with configurable strategies - 💬 **Real-time Streaming Chat** using Laravel AI SDK - ⚡ **Full-text to Vector Pipeline** with embeddings caching - 🎯 **Bilingual Support** with Arabic language optimization - 📊 **Analytics Dashboard** with token counting and timing metrics - 🔧 **Swappable Embedding Providers** (Gemini, OpenAI, Cohere, Azure, etc.) - 🎨 **Beautiful Livewire UI** with Tailwind CSS & Alpine.js Installation ------------ [](#installation) ``` composer require cla/laravel-rag ``` Publishing Assets ----------------- [](#publishing-assets) Publish configuration, migrations, and views: ``` php artisan vendor:publish --tag=rag-config php artisan vendor:publish --tag=rag-migrations ``` > Note: The package suppresses the redundant `pgvector` vendor migration path so your own `document_chunks` migration remains the only migration path for pgvector extension creation. This avoids running the pgvector migration on the wrong default database connection. Run migrations: ``` php artisan migrate ``` Configuration ------------- [](#configuration) Create a PostgreSQL connection for vectors in `config/database.php`: ``` 'pgsql_vector' => [ 'driver' => 'pgsql', 'host' => env('VECTOR_DB_HOST', 'localhost'), 'port' => env('VECTOR_DB_PORT', 5432), 'database' => env('VECTOR_DB_DATABASE', 'rag_vectors'), 'username' => env('VECTOR_DB_USERNAME', 'postgres'), 'password' => env('VECTOR_DB_PASSWORD', ''), 'charset' => 'utf8', 'prefix' => '', ], ``` Configure environment variables in `.env`: ``` EMBEDDING_PROVIDER=gemini GEMINI_API_KEY=your-key-here GEMINI_EMBEDDING_MODEL=gemini-embedding-001 GEMINI_EMBEDDING_DIMENSIONS=1536 RAG_VECTOR_CONNECTION=pgsql_vector RAG_DOCUMENTS_CONNECTION=mysql RAG_MIN_SIMILARITY=0.45 RAG_ARABIC_MIN_SIMILARITY=0.30 RAG_MAX_CHUNK_CHARS=3000 RAG_CHUNK_OVERLAP=200 RAG_MAX_SEARCH_RESULTS=10 RAG_STORAGE_DISK=rag_documents RAG_CHUNKER_STRATEGY=character RAG_CHAT_PROVIDER=gemini RAG_CHAT_MODEL=gemini-2.0-flash RAG_CHAT_TIMEOUT=120 ``` Usage ----- [](#usage) ### In Blade Templates [](#in-blade-templates) ``` ``` ### Programmatic Usage [](#programmatic-usage) ``` use CLA\LaravelRag\Agents\DocumentSearchAgent; use CLA\LaravelRag\Models\Document; // Query documents with streaming $stream = DocumentSearchAgent::make() ->stream('What is this about?', provider: 'gemini'); foreach ($stream as $chunk) { echo $chunk->text; } // Access documents directly $docs = Document::where('status', 'processed')->get(); $chunks = $docs->first()->chunks; ``` ### With Callback Hooks [](#with-callback-hooks) ``` use CLA\LaravelRag\Agents\DocumentSearchAgent; $stream = DocumentSearchAgent::make() ->onChunksFound(function ($chunks, $metadata) { dump($metadata); // Vector search metrics dump($chunks); // Retrieved document chunks }) ->stream('Your question here', provider: 'gemini'); foreach ($stream as $event) { // Handle streaming events } ``` Database Schema --------------- [](#database-schema) ### Documents Table [](#documents-table) Stores document metadata on MySQL/Primary DB: ``` - id: Primary key - original_name: File name - disk: Storage disk (local, s3, etc) - path: File path - mime_type: MIME type - size: File size in bytes - status: queued|processing|processed|empty|failed - extracted_text: Full extracted text - error: Error message if failed - processed_at: Completion timestamp ``` ### Document Chunks Table [](#document-chunks-table) Stores vector embeddings on PostgreSQL with pgvector: ``` - id: Primary key - document_id: Foreign key to documents - position: Chunk order (0-based) - content: Chunk text - content_hash: SHA-256 of content - embedding: pgvector type (e.g., 768-dimensional) - tokens_count: Token count (optional) ``` Architecture ------------ [](#architecture) The package uses a **multi-database approach**: - **MySQL/Primary**: Document metadata (fast lookups) - **PostgreSQL + pgvector**: Vector embeddings (semantic search) This separation allows: - Optimal query performance - Easy backup of metadata - Scalable vector operations Configuration Options --------------------- [](#configuration-options) All options can be set via `config/rag.php` or `.env` variables: OptionEnv VarDefaultDescriptionembedding\_providerRAG\_EMBEDDING\_PROVIDERgeminiAI provider for embeddingsvector\_connectionRAG\_VECTOR\_CONNECTIONpgsql\_vectorPostgreSQL connection namedocuments\_connectionRAG\_DOCUMENTS\_CONNECTIONmysqlMetadata DB connectionmin\_similarityRAG\_MIN\_SIMILARITY0.45Threshold for English queriesarabic\_min\_similarityRAG\_ARABIC\_MIN\_SIMILARITY0.30Threshold for Arabic queriesembedding\_dimensionsRAG\_EMBEDDING\_DIMENSIONS768Vector dimensionschunk\_sizeRAG\_CHUNK\_SIZE1000Characters per chunkchunk\_overlapRAG\_CHUNK\_OVERLAP200Overlap between chunksmax\_search\_resultsRAG\_MAX\_SEARCH\_RESULTS10Max chunks to retrievestorage\_diskRAG\_STORAGE\_DISKrag\_documentsStorage disk for fileschunker\_strategyRAG\_CHUNKER\_STRATEGYcharacterChunking strategychat.providerRAG\_CHAT\_PROVIDERgeminiChat completion providerchat.modelRAG\_CHAT\_MODELgemini-2.0-flashChat model namechat.timeoutRAG\_CHAT\_TIMEOUT120Request timeout in secondsAdvanced Usage -------------- [](#advanced-usage) ### Custom Embedding Providers [](#custom-embedding-providers) Create your own embedding implementation: ``` use CLA\LaravelRag\Services\EmbeddingGenerator; class CustomEmbeddingGenerator implements EmbeddingGenerator { public function embed(array $texts): array { // Your embedding logic return $vectors; } public function dimensions(): int { return 1536; } } // Register in AppServiceProvider $this->app->bind(EmbeddingGenerator::class, CustomEmbeddingGenerator::class); ``` ### Manual Document Processing [](#manual-document-processing) ``` use CLA\LaravelRag\Models\Document; use CLA\LaravelRag\Services\DocumentTextExtractor; use CLA\LaravelRag\Services\DocumentEmbeddingIndexer; $extractor = app(DocumentTextExtractor::class); $indexer = app(DocumentEmbeddingIndexer::class); $text = $extractor->extract('/path/to/file.pdf'); $chunksCreated = $indexer->index($document, $text); ``` Performance Tips ---------------- [](#performance-tips) 1. **Use Queue Workers** for document processing: ``` php artisan queue:listen ``` 2. **Enable Embedding Caching** in `config/ai.php`: ``` 'caching' => [ 'embeddings' => [ 'cache' => true, 'store' => 'redis', ], ] ``` 3. **Batch Imports** for large document sets: ``` php artisan rag:embed-documents ``` 4. **Tune Similarity Threshold** based on your documents: - Lower threshold (0.30) = More results, lower precision - Higher threshold (0.70) = Fewer results, higher precision Troubleshooting --------------- [](#troubleshooting) ### Vector Search Returns No Results [](#vector-search-returns-no-results) Check the similarity threshold: ``` RAG_MIN_SIMILARITY=0.30 # Lower to get more results ``` ### Out of Memory During PDF Processing [](#out-of-memory-during-pdf-processing) Limit PDF size or process asynchronously: ``` DOCUMENT_TEXT_EXTRACTOR_MAX_SYNC_PDF_KB=20480 ``` ### Embedding API Rate Limiting [](#embedding-api-rate-limiting) Reduce batch size in `config/rag.php`: ``` 'chunk_batch_size' => 8 // Process fewer chunks at once ``` Testing ------- [](#testing) Run the package tests: ``` composer test ``` License ------- [](#license) MIT License - see LICENSE file for details. Support ------- [](#support) For issues, questions, or contributions, please visit the GitHub repository. --- **Made with ❤️ for Laravel developers** ### Health Score 44 — FairBetter than 90% of packages Maintenance91 Actively maintained with recent releases Popularity9 Limited adoption so far Community8 Small or concentrated contributor base Maturity57 Maturing project, gaining track record Bus Factor1 Top contributor holds 59.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 15 Last Release 53d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/285701252?v=4)[ayaashraf-cla](/maintainers/ayaashraf-cla)[@ayaashraf-cla](https://github.com/ayaashraf-cla) --- Top Contributors [![ayaashrafahmed33-sketch](https://avatars.githubusercontent.com/u/239688710?v=4)](https://github.com/ayaashrafahmed33-sketch "ayaashrafahmed33-sketch (16 commits)")[![ayaashraf-cla](https://avatars.githubusercontent.com/u/285701252?v=4)](https://github.com/ayaashraf-cla "ayaashraf-cla (11 commits)") ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/ayaashraf-laravel-rag/health.svg) ``` [![Health](https://phpackages.com/badges/ayaashraf-laravel-rag/health.svg)](https://phpackages.com/packages/ayaashraf-laravel-rag) ``` ### Alternatives [civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 751291.4k46](/packages/civicrm-civicrm-core)[tomshaw/electricgrid A feature-rich Livewire package designed for projects that require dynamic, interactive data tables. 119.4k](/packages/tomshaw-electricgrid)[unopim/unopim UnoPim Laravel PIM 10.5k2.4k](/packages/unopim-unopim)[team-nifty-gmbh/tall-datatables Server-side rendered datatables for Laravel and Livewire 1320.9k4](/packages/team-nifty-gmbh-tall-datatables)[noerd/noerd 101.4k10](/packages/noerd-noerd) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)