Search by

laravelartist / rag-chat

Plug-and-play local RAG for Laravel with laravel/ai agents

Maintainers

Package info

github.com/Awais-Koder/rag-chat

pkg:composer/laravelartist/rag-chat

Transparency log

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0 2026-08-13 13:46 UTC

Requires

Requires (Dev)

Suggests

None

Provides

None

Conflicts

None

Replaces

None

MIT 103b81671803edecca18796f0b5f3a8d87eb3a03

  • awais-koder <awaistayyab27.woop@gmail.com>

Published on Packagist.org on 2026-09-05 16:01 UTC

This package is auto-updated.

Last update: 2026-09-05 16:02:07 UTC

README

Plug-and-play local RAG for Laravel, powered by laravel/ai.

One install command publishes Laravel AI SDK + this package, migrates, scaffolds a ready RagAgent, and writes provider .env keys. You only set an API key and ingest docs.

Chat runs through a real Laravel AI SDK agent (RagAgent + SearchKnowledge tool). Providers stay in config/ai.php.

Requirements

  • PHP 8.3+
  • Laravel 12 or 13

Install (plug-and-play)

composer require laravelartist/rag-chat
php artisan rag-chat:install

That single command:

  1. Publishes laravel/ai config + conversation migrations
  2. Publishes Rag Chat config + migrations
  3. Publishes app/Ai/Agents/RagAgent.php for optional customization
  4. Patches config/ai.php defaults to env('AI_DEFAULT') / env('AI_DEFAULT_EMBEDDINGS')
  5. Appends missing keys to .env / .env.example
  6. Runs php artisan migrate (skip with --no-migrate)

Connect a provider

Edit .env — set one provider:

AI_DEFAULT=openrouter
AI_DEFAULT_EMBEDDINGS=openrouter
OPENROUTER_API_KEY=sk-or-v1-...

Other options: openai, anthropic, gemini (+ matching OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY).

Ingest + chat

php artisan rag-chat:ingest storage/app/docs
curl -X POST /rag-chat/chat \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"message":"What is the refund policy?"}'

Or in PHP:

use Awais\RagChat\Agents\RagAgent;
use Awais\RagChat\Facades\RagChat;

RagChat::ingest(storage_path('app/docs'));

$response = (new RagAgent)->prompt('What is the refund policy?');
echo $response->text;

Streaming:

return (new RagAgent)->stream('Summarize pricing');
// or POST /rag-chat/chat/stream

What the package owns vs Laravel AI

Concern Owner
Document ingest (txt/md/pdf), chunking, local vector store laravelartist/rag-chat
Embeddings API calls laravel/ai (Embeddings)
Chat agents, tools, streaming, conversations, providers laravel/ai (RagAgent)
Provider API keys Your .env / config/ai.php

Customize instructions/tools in the published app/Ai/Agents/RagAgent.php. Package HTTP routes use Awais\RagChat\Agents\RagAgent by default.

HTTP API

Unauthenticated by default — add middleware in config/rag-chat.php before going public.

Method Path Body
POST /rag-chat/chat { "message": "..." }
POST /rag-chat/chat/stream { "message": "..." } (SSE)
POST /rag-chat/documents { "text": "..." } or multipart file

Vector stores (local RAG)

Driver Config Behaviour
json RAG_STORE=json (default) JSON embeddings + PHP cosine (any SQL DB)
mysql RAG_STORE=mysql MySQL 9 DISTANCE(..., 'COSINE')

Separate from provider-hosted Laravel\Ai\Stores / FileSearch.

Supported files

  • .txt, .md / .markdown, .pdf (text PDFs via smalot/pdfparser)

Tier 4: advanced RAG features

All Tier 4 features are opt-in and off by default — Tier 1–3 behaviour is unchanged.

Metadata filters

Filter retrieval by chunk/document metadata at the retrieval layer (not just app-side):

$rag->retrieve('Laravel backend', ['department' => 'engineering', 'document_type' => 'resume']);
$rag->respond('What projects has the backend team shipped?', filters: ['department' => 'engineering']);

Dot notation works ('meta_group.tier' => 'senior'). Filters apply before the top-K cut, and cache keys include them, so filtered results never leak across scopes or configurations. Scoping is enforced via RagProjectScope (project = tenant); cross-project retrieval is impossible.

Conversation-aware rewriting

$response = $rag->respond('What framework does he use?', history: [
    ['role' => 'user', 'content' => 'Tell me about Muhammad Awais.'],
]);

With RAG_CONVERSATION_ENABLED=true, pronoun-led questions without their own entity are rewritten into a standalone query (heuristic by default, no LLM call; RAG_CONVERSATION_REWRITE=llm for an LLM rewrite). Questions that already name an entity are never rewritten. The original question is kept in response metadata as original_query.

Context compression

With RAG_COMPRESSION_ENABLED=true, chunks below RAG_COMPRESSION_MIN_RELEVANCE are dropped and total context is capped at RAG_COMPRESSION_MAX_CONTEXT_CHARS before the LLM call. Citation metadata survives compression — only the chunk set changes, never source identity.

Answer confidence / groundedness

Every respond() response carries metadata.confidence: high (strong match + citations), medium, low, or unsupported (the not-found fallback). Thresholds: RAG_CONFIDENCE_HIGH (default 0.65), RAG_CONFIDENCE_MEDIUM (default 0.45).

Prompt-injection guard

Retrieved excerpts are presented to the model as untrusted data: the default prompt tells the model to ignore any instructions found inside documents ("ignore previous instructions", "act as…"). Disable with RAG_PROMPT_INJECTION_GUARD=false if you have a reason to.

Knowledge-base management API

$rag->deleteDocument($id);        // document + chunks (driver-independent)
$rag->reindexDocument($id);       // re-ingest from stored source (dedup applies)
$rag->clearKnowledgeBase();       // all docs in the active project scope
$rag->chunks($documentId);        // inspect chunks (project-scoped)
$rag->search($question, $filters); // alias of retrieve()

Evaluation framework

Run a dataset of cases against the real retrieval pipeline and get a hit-rate report:

use Awais\RagChat\Evaluation\EvaluationCase;

$report = app(\Awais\RagChat\Evaluation\RagEvaluator::class)->evaluate([
    new EvaluationCase('How much does the AcmeMover X1 cost?', ['pricing.md']),
    new EvaluationCase('What warranty does Acme offer?', ['warranty.txt'], '12 months'),
]);

$report->retrievalHitRate(); // 1.0

Add a custom per-case evaluator (answer relevance, citation correctness) via the optional $perCase callback.

New config keys

Key Env Default
conversation.enabled RAG_CONVERSATION_ENABLED false
conversation.rewrite RAG_CONVERSATION_REWRITE heuristic (heuristic|llm|disabled)
conversation.history_turns RAG_CONVERSATION_HISTORY_TURNS 4
compression.enabled RAG_COMPRESSION_ENABLED false
compression.min_relevance RAG_COMPRESSION_MIN_RELEVANCE 0.0
compression.max_context_chars RAG_COMPRESSION_MAX_CONTEXT_CHARS 12000
confidence.high_score RAG_CONFIDENCE_HIGH 0.65
confidence.medium_score RAG_CONFIDENCE_MEDIUM 0.45
evaluation.top_k RAG_EVAL_TOP_K 5
prompt.injection_guard RAG_PROMPT_INJECTION_GUARD true

Extension points

  • Retrieval: already composable — RAG_FEATURE_MULTI_QUERY, RAG_RETRIEVAL_HYBRID, RAG_RETRIEVAL_RERANKER (string class implementing Awais\RagChat\Contracts\Reranker), RAG_CONTEXT_EXPANSION.
  • Metadata filters: any array<string, mixed> against chunk/document meta.
  • Evaluators: pass a callable to RagEvaluator::evaluate() for per-case metrics.
  • Scoping: RagProjectScope::set($projectId) before ingest/chat; authorization hooks via RagChat::authorizeResultsUsing().

Testing

composer install
./vendor/bin/phpunit

License

MIT