README

A complete Laravel package for implementing RAG (Retrieval-Augmented Generation) systems with external API integrations, vector databases, and a beautiful Alpine.js-powered web interface.

Features

🚀 Plug-and-play installation - Single command setup
🤖 Multiple AI providers - OpenAI, Anthropic with extensible driver system
📄 Document processing - Text, PDF, DOCX support via external APIs
🔍 Hybrid search - Vector similarity + keyword matching with multiple vector DB providers
🎨 Modern web interface - Alpine.js components with real-time updates
📊 Analytics & monitoring - Usage tracking, search analytics, cost monitoring
⚡ Queue-based processing - Async document processing with status tracking
🔧 Extensive configuration - Every aspect is configurable
🧪 Comprehensive testing - Unit and feature tests included

Quick Start

# Install the package
composer require omniglies/laravel-rag

# Install and configure
php artisan rag:install

# Configure your environment
# Add to .env:
RAG_AI_PROVIDER=openai
OPENAI_API_KEY=your_openai_key
RAG_VECTOR_PROVIDER=pinecone
PINECONE_API_KEY=your_pinecone_key

Visit /rag in your browser and start uploading documents!

Installation
Configuration
Usage
External Integrations
Console Commands
Testing
Architecture
Contributing

Installation

Requirements

PHP 8.1+
Laravel 9.x, 10.x, or 11.x
Database (PostgreSQL recommended for full-text search, MySQL/SQLite supported)
Queue system (Redis/Database recommended for production)

Step 1: Install via Composer

composer require omniglies/laravel-rag

Step 2: Install the Package

php artisan rag:install

This command will:

Publish configuration files
Publish and run migrations
Publish views and assets
Display setup instructions

Step 3: Configure Environment

Add these environment variables to your .env:

# AI Provider (required)
RAG_AI_PROVIDER=openai
OPENAI_API_KEY=your_openai_api_key

# Vector Database (required)
RAG_VECTOR_PROVIDER=pinecone
PINECONE_API_KEY=your_pinecone_api_key
PINECONE_ENVIRONMENT=your_pinecone_environment
PINECONE_INDEX_NAME=rag-knowledge

# External Processing API (optional)
RAG_PROCESSING_API_URL=https://your-processing-api.com
RAG_PROCESSING_API_KEY=your_processing_api_key

# Queue Configuration (recommended)
QUEUE_CONNECTION=redis
RAG_QUEUE_CONNECTION=redis

Step 4: Set Up Queue Workers (Production)

# Start queue workers for document processing
php artisan queue:work --queue=rag

Configuration

The package configuration is published to config/rag.php. Key configuration sections:

AI Providers

'ai_provider' => env('RAG_AI_PROVIDER', 'openai'),

'providers' => [
    'openai' => [
        'api_key' => env('OPENAI_API_KEY'),
        'model' => env('RAG_OPENAI_MODEL', 'gpt-3.5-turbo'),
        'max_tokens' => env('RAG_OPENAI_MAX_TOKENS', 1000),
    ],
    'anthropic' => [
        'api_key' => env('ANTHROPIC_API_KEY'),
        'model' => env('RAG_ANTHROPIC_MODEL', 'claude-3-sonnet-20240229'),
    ],
],

Vector Databases

'vector_database' => [
    'provider' => env('RAG_VECTOR_PROVIDER', 'pinecone'),
    'providers' => [
        'pinecone' => [
            'api_key' => env('PINECONE_API_KEY'),
            'environment' => env('PINECONE_ENVIRONMENT'),
            'index_name' => env('PINECONE_INDEX_NAME', 'rag-knowledge'),
        ],
        'weaviate' => [
            'url' => env('WEAVIATE_URL'),
            'api_key' => env('WEAVIATE_API_KEY'),
        ],
        'qdrant' => [
            'url' => env('QDRANT_URL'),
            'api_key' => env('QDRANT_API_KEY'),
        ],
    ],
],

Search Configuration

'search' => [
    'default_limit' => env('RAG_SEARCH_LIMIT', 3),
    'similarity_threshold' => env('RAG_SIMILARITY_THRESHOLD', 0.7),
    'hybrid_search' => [
        'enabled' => env('RAG_HYBRID_SEARCH_ENABLED', true),
        'vector_weight' => env('RAG_VECTOR_WEIGHT', 0.8),
        'keyword_weight' => env('RAG_KEYWORD_WEIGHT', 0.2),
    ],
],

Usage

Web Interface

The package provides a complete web interface accessible at /rag:

Dashboard: Overview of documents and processing status
Documents: Upload, manage, and view document processing status
Chat: AI-powered chat interface with RAG capabilities

Features

Drag-and-drop file uploads
Real-time processing status updates
Vector search with similarity scores
Source attribution in AI responses
Responsive Alpine.js components

API Usage

The package exposes RESTful API endpoints at /api/rag/:

Upload Document

curl -X POST /api/rag/documents \
  -H "Content-Type: multipart/form-data" \
  -F "title=My Document" \
  -F "file=@document.pdf" \
  -F "metadata[author]=John Doe"

Ask Question

curl -X POST /api/rag/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the main topic of the documents?",
    "context_limit": 5,
    "temperature": 0.7
  }'

Search Documents

curl -X GET "/api/rag/search?query=machine learning&limit=10&threshold=0.8"

Get System Status

curl -X GET /api/rag/health

Programmatic Usage

Using the Facade

use Omniglies\LaravelRag\Facades\Rag;

// Ingest a document
$document = Rag::ingestDocument('Document Title', $uploadedFile, [
    'author' => 'John Doe',
    'category' => 'Research'
]);

// Ask a question
$response = Rag::askWithContext('What is machine learning?');
echo $response['answer'];

// Search for similar content
$chunks = Rag::searchRelevantChunks('artificial intelligence', 5);

Using the Service

use Omniglies\LaravelRag\Services\RagService;

class MyController extends Controller
{
    public function __construct(private RagService $ragService) {}

    public function search(Request $request)
    {
        $results = $this->ragService->searchRelevantChunks(
            $request->query,
            $request->limit ?? 10
        );
        
        return response()->json($results);
    }
}

Advanced Usage

use Omniglies\LaravelRag\Services\VectorSearchService;
use Omniglies\LaravelRag\Services\EmbeddingService;

// Direct vector operations
$vectorService = app(VectorSearchService::class);
$embeddingService = app(EmbeddingService::class);

// Generate embeddings
$embedding = $embeddingService->generateEmbedding('sample text');

// Perform vector search
$results = $vectorService->searchSimilar('query text', [
    'limit' => 10,
    'threshold' => 0.8,
    'namespace' => 'documents'
]);

External Integrations

Document Processing API

The package supports external document processing services for advanced file format support:

// Configure external processing
'external_processing' => [
    'enabled' => env('RAG_EXTERNAL_PROCESSING_ENABLED', true),
    'api_url' => env('RAG_PROCESSING_API_URL'),
    'api_key' => env('RAG_PROCESSING_API_KEY'),
    'webhook_secret' => env('RAG_PROCESSING_WEBHOOK_SECRET'),
],

Expected API interface:

POST /documents/process - Submit document for processing
GET /jobs/{id}/status - Check processing status
GET /jobs/{id}/result - Get processed chunks
Webhook support for completion notifications

Vector Database Providers

Pinecone

RAG_VECTOR_PROVIDER=pinecone
PINECONE_API_KEY=your_api_key
PINECONE_ENVIRONMENT=us-west1-gcp
PINECONE_INDEX_NAME=rag-knowledge

Weaviate

RAG_VECTOR_PROVIDER=weaviate
WEAVIATE_URL=http://localhost:8080
WEAVIATE_API_KEY=your_api_key

Qdrant

RAG_VECTOR_PROVIDER=qdrant
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your_api_key

Embedding Providers

OpenAI

RAG_EMBEDDING_PROVIDER=openai
RAG_OPENAI_EMBEDDING_MODEL=text-embedding-ada-002

Cohere

RAG_EMBEDDING_PROVIDER=cohere
COHERE_API_KEY=your_api_key
RAG_COHERE_EMBEDDING_MODEL=embed-english-v3.0

Console Commands

Installation and Setup

# Install the package (run after composer install)
php artisan rag:install

# Test configuration
php artisan rag:status --test-config

Document Management

# Ingest a document
php artisan rag:ingest path/to/document.pdf --title="Research Paper"

# Check document status
php artisan rag:status 123

# Clear all documents
php artisan rag:clear --force

Maintenance

# Optimize search indexes
php artisan rag:optimize --search-indexes

# Sync unsynced vectors
php artisan rag:optimize --vector-sync

# Clean up old records
php artisan rag:optimize --cleanup-old --days=30

System Status

# Check overall system status
php artisan rag:status

# Check specific document
php artisan rag:status 123

# Detailed statistics
php artisan rag:status --detailed

Testing

The package includes comprehensive tests:

# Run all tests
vendor/bin/phpunit

# Run specific test suites
vendor/bin/phpunit --testsuite=Unit
vendor/bin/phpunit --testsuite=Feature

# Run with coverage
vendor/bin/phpunit --coverage-html coverage

Test Structure

Unit Tests: Test individual services and components
Feature Tests: Test HTTP endpoints and integration scenarios
Mocking: External APIs are mocked for reliable testing

Architecture

Core Components

src/
├── Services/           # Core business logic
│   ├── RagService.php             # Main service orchestrator
│   ├── ExternalProcessingService.php  # Document processing API client
│   ├── VectorSearchService.php    # Vector database operations
│   ├── EmbeddingService.php       # Embedding generation
│   └── AiProviders/               # AI provider implementations
├── Models/             # Eloquent models
├── Http/               # Controllers and middleware
├── Jobs/               # Queue jobs for async processing
├── Console/            # Artisan commands
└── Database/           # Migrations

Data Flow

Document Upload → Queue Processing → External API → Chunking → Embeddings → Vector Storage
User Query → Vector Search + Keyword Search → Context Building → AI Generation → Response

Design Patterns

Service Layer: Business logic separation
Strategy Pattern: Pluggable AI and vector providers
Observer Pattern: Event-driven processing updates
Factory Pattern: Provider instantiation
Repository Pattern: Data access abstraction

Alpine.js Components

The web interface uses Alpine.js for reactive components:

Chat Component

<div x-data="ragChat()" x-init="init()">
    <!-- Real-time chat interface with typing indicators -->
</div>

Upload Component

<div x-data="ragUpload()" x-init="init()">
    <!-- Drag-and-drop upload with progress tracking -->
</div>

Search Component

<div x-data="ragSearch()" x-init="init()">
    <!-- Live search with debouncing and results -->
</div>

Performance Considerations

Production Optimization

Queue Workers: Use dedicated queue workers for document processing
Caching: Enable Redis/Memcached for embeddings and search results
Database: Use PostgreSQL for optimal full-text search performance
Vector Database: Choose appropriate vector DB based on scale
Rate Limiting: Configure API rate limits for external services

Scaling

Horizontal Scaling: Multiple queue workers for processing
Vector Database Sharding: Distribute vectors across multiple indexes
CDN: Serve static assets via CDN
Load Balancing: Distribute web requests across multiple instances

Security

API Keys

Store all API keys in environment variables
Use Laravel's encryption for sensitive configuration
Rotate keys regularly

Authentication

Configure authentication middleware for web routes
Use API tokens for programmatic access
Implement rate limiting for API endpoints

Data Privacy

Documents are processed according to your AI provider's terms
Vector embeddings do not contain original text
Implement data retention policies

Troubleshooting

Common Issues

Document Processing Stuck

# Check queue workers
php artisan queue:work --queue=rag

# Check external API status
php artisan rag:status --test-config

# Retry failed jobs
php artisan queue:retry all

Vector Search Not Working

# Test vector database connection
php artisan rag:status --test-config

# Check vector sync status
php artisan rag:optimize --vector-sync

High API Costs

# Check usage statistics
php artisan rag:status --detailed

# Optimize chunk sizes
# Edit config/rag.php chunking settings

Debug Mode

Enable debug logging in config/logging.php:

'channels' => [
    'rag' => [
        'driver' => 'daily',
        'path' => storage_path('logs/rag.log'),
        'level' => 'debug',
    ],
],

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

git clone https://github.com/omniglies/laravel-rag.git
cd laravel-rag
composer install
npm install
npm run dev

Running Tests

composer test
composer test:coverage
composer test:types

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

Roadmap

Support for more file formats (PPT, XLS, etc.)
Built-in document OCR capabilities
GraphQL API support
Advanced analytics dashboard
Multi-tenant support
Document versioning
Collaborative features
Export/import capabilities

Need help? Check out our documentation or open an issue.

omniglies / laravel-rag

Maintainers

Details

README

Features

Quick Start

Table of Contents

Installation

Requirements

Step 1: Install via Composer

Step 2: Install the Package

Step 3: Configure Environment

Step 4: Set Up Queue Workers (Production)

Configuration

AI Providers

Vector Databases

Search Configuration

Usage

Web Interface

Features

API Usage

Upload Document

Ask Question

Search Documents

Get System Status

Programmatic Usage

Using the Facade

Using the Service

Advanced Usage

External Integrations

Document Processing API

Vector Database Providers

Pinecone

Weaviate

Qdrant

Embedding Providers

OpenAI

Cohere

Console Commands

Installation and Setup

Document Management

Maintenance

System Status

Testing

Test Structure

Architecture

Core Components

Data Flow

Design Patterns

Alpine.js Components

Chat Component

Upload Component

Search Component

Performance Considerations

Production Optimization

Scaling

Security

API Keys

Authentication

Data Privacy

Troubleshooting

Common Issues

Document Processing Stuck

Vector Search Not Working

High API Costs

Debug Mode

Contributing

Development Setup

Running Tests

Changelog

Security Vulnerabilities

Credits

License

Roadmap