Download the PHP package laraigent/larai-kit without Composer

LarAI Kit — Laravel RAG & AI Agent Toolkit

Production-ready RAG, AI agents, document ingestion, vector search, and streaming chat for Laravel 12 and 13. Drop-in package built on top of Laravel's first-party AI SDK — works with OpenAI, Anthropic, and Gemini; supports Pinecone and pgvector for vector search; parses PDF, DOCX, plain text, and URLs out of the box.

Install in 30 seconds. No lock-in. Fully backward compatible. Multi-tenant ready.

Table of Contents

• Why LarAI Kit?
• Use Cases
• Features
• Quickstart
• Feature Tiers
• Configuration
• Usage
  • Chat with RAG context
  • Conversations (persistent chat threads)
  • Streaming chat (SSE)
  • Ingest documents
  • Create a custom agent
  • Web health endpoint (JSON)
• Artisan Commands
• Architecture
• Ingestion Pipeline
• Supported File Types
• Requirements
• Documentation
• FAQ
• Contributing
• License

Why LarAI Kit?

Laravel's AI SDK gives you the low-level building blocks (Agent, Tool, prompt()). But building a production RAG (Retrieval-Augmented Generation) pipeline for a Laravel app still requires a lot of plumbing:

• How do I parse PDFs and DOCX files into clean text?
• How do I chunk documents and generate OpenAI / Anthropic / Gemini embeddings?
• How do I store and search vectors in Pinecone or pgvector?
• How do I inject relevant context into my agent's prompt without hand-crafting it?
• How do I scope retrieval per tenant so customers never see each other's data?
• How do I make all this not break when one service is unavailable?

LarAI Kit solves all of this. One composer require, a few .env keys, and you have a working Laravel RAG pipeline with source-cited answers and streaming SSE chat.

Use Cases

LarAI Kit is the fastest path to building:

• Customer support chatbots — RAG over your FAQ, help-center docs, product manuals, and policies with automatic source citations
• Internal knowledge search — semantic search over Confluence exports, Notion dumps, wikis, and internal PDFs for your team
• Multi-tenant SaaS chatbots — scope every ingest, retrieval, and conversation per customer (Chatbase-style platforms, but self-hosted)
• Document Q&A — upload PDFs, Word docs, or URLs; ask natural-language questions over them
• AI agents with tools — booking agents, product-lookup agents, order-status bots with custom tool calling
• Streaming AI responses — Server-Sent Events (SSE) streaming with token-by-token deltas and final source attribution
• Compliance-aware AI features — Laravel-native scoping and per-tenant isolation that plays nicely with your existing auth/authorization

Features

Quickstart

You now have a RAG-enabled AI agent wired into your Laravel app — ingest your first document and chat with it:

Before you go to production — three things to know

1. The namespace is LarAIgent\AiKit\... (case-sensitive — matters on Linux deployments)
2. Run php artisan queue:work in a separate process, or set QUEUE_CONNECTION=sync in .env — otherwise ingestion jobs queue silently
3. OpenAI tier-1 keys allow ~3 RPM for embeddings — a 50KB document may rate-limit you. Set LARAI_RETRY_MAX=5 or upgrade your OpenAI tier.

Feature Tiers

LarAI Kit detects which services are available and enables features accordingly — never crashes on missing config:

Configuration

All settings are managed via .env. No code changes to switch providers.

AI Provider

Vector Store

Database

Full Config Reference

Run php artisan vendor:publish --tag=larai-kit-config to publish config/larai-kit.php, then see Configuration Docs for all tunables.

Usage

Chat with RAG context

Conversations (persistent chat threads)

Streaming chat (SSE)

Ingest documents

Create a custom agent

Create a custom tool

Check system health

Web health endpoint (JSON)

Enable in .env:

Returns structured JSON with all check results — wire into monitoring dashboards (Datadog, New Relic, Grafana, UptimeRobot, etc.). Set LARAI_HEALTH_MIDDLEWARE= (empty) to expose publicly behind an ingress allowlist, or LARAI_HEALTH_MIDDLEWARE=throttle:10,1 to rate-limit without auth. Use | to stack (e.g. auth|throttle:60,1) — commas inside a single middleware parameter (Laravel's rate-limit syntax) are preserved.

Usage tracking

Events (ChatCompleted, EmbeddingsCompleted) are always dispatched with real provider-reported token counts — listen for custom billing, analytics, or cost dashboards even without DB persistence.

Interactive CLI chat

Artisan Commands

Architecture

Ingestion Pipeline

When you ingest a document (file, text, or URL), this happens automatically:

Each step is a queued job (or runs synchronously when QUEUE_CONNECTION=sync):

• ParseAssetJob — extracts text from PDF, DOCX, HTML, or plain text
• ChunkAssetJob — splits into overlapping chunks (configurable size)
• EmbedChunksJob — generates embeddings and upserts to Pinecone / pgvector

State is tracked in the ai_ingestions table: queued → parsing → chunking → embedding → indexed. Subscribe to AssetIndexed / AssetFailed events for post-ingest workflows (see Ingestion Pipeline Docs).

Supported File Types

Install optional parsers:

Requirements

• PHP 8.3+
• Laravel 12 or 13
• laravel/ai ^0.4
• Database: MySQL 8+ or PostgreSQL 14+
• AI provider API key: OpenAI, Anthropic, or Gemini
• Vector store (optional): Pinecone account or PostgreSQL with pgvector extension

Documentation

Community Examples

Real-world starter prompts built and tested by the community. Browse examples/ or jump straight to:

• SaaS Chatbot Platform — Build a full multi-tenant chatbot SaaS (like Chatbase) with Laravel 13

FAQ

How is LarAI Kit different from the Laravel AI SDK?

The Laravel AI SDK provides low-level primitives: Agent, Tool, prompt(), embeddings, streaming. LarAI Kit is additive — it sits on top and provides the RAG pipeline (document parsing, chunking, embedding, vector storage, retrieval, prompt injection, source citations) that the SDK intentionally leaves out. You still use the SDK directly for anything custom; LarAI Kit just saves you from rebuilding the common pieces.

Can I use LarAI Kit without Pinecone?

Yes. Set LARAI_VECTOR_STORE=pgvector to use PostgreSQL's pgvector extension, or LARAI_VECTOR_STORE=none to disable RAG entirely (chat still works). No code changes.

Does it work with Laravel 11?

No — LarAI Kit requires Laravel 12 or 13 because it depends on laravel/ai ^0.4, which itself requires the Laravel 12+ container. If you're on Laravel 11, upgrade first (the upgrade from 11 → 12 is typically small).

Which LLM providers are supported?

OpenAI (default), Anthropic (Claude 3.5 Sonnet / 4), and Google Gemini. Switch via LARAI_AI_PROVIDER=openai|anthropic|gemini. Chat, streaming, and tool calling all route through the same Agent contract — your code doesn't change when you switch providers.

How do I ingest a PDF?

The pipeline detects the MIME type, routes through PdfParser, chunks with overlap, embeds in batches, and upserts to your vector store. Check $asset->ingestion->state for the final status.

How does multi-tenant scoping work?

Pass a scope array on every ingest / retrieve / conversation call:

Pinecone uses metadata $eq filters under the hood; pgvector uses JSON WHERE clauses. Tenants never see each other's vectors — crucial for SaaS chatbot platforms where each customer uploads their own knowledge base.

Is streaming SSE supported out of the box?

Yes. ChatService::streamMessage() returns a ChatStreamResponse that implements Laravel's Responsable interface — return it directly from a controller and you get a fully-formed SSE response (token-by-token deltas, sources at the end, [done] event). No manual StreamedResponse wiring needed.

How do I track AI usage and costs?

Listen for the ChatCompleted and EmbeddingsCompleted events — they carry real provider-reported token counts:

Or set LARAI_TRACK_USAGE=true to persist automatically to the ai_usage table.

Can I use LarAI Kit with an existing Laravel AI SDK app?

Yes — LarAI Kit adds services without touching anything the SDK provides. Your existing Agent classes, tools, and prompt() calls keep working unchanged. LarAI Kit just gives you the RAG layer on top.

v0.2.4 Notes

• IngestionService::ingestFromDisk($disk, $path, $scope) is now available for re-index and recovery workflows.
• ChatStreamResponse::withOnComplete() lets you chain post-stream persistence without rebuilding the SSE loop.
• ingestText() and ingestUrl() now run through queued entry jobs for consistency with ingestFile().
• Terminal ingestion events (AssetIndexed, AssetFailed) are now aligned with transaction commit boundaries.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License. See LICENSE for details.

Credits

• Built on Laravel AI SDK
• Inspired by the gap between Python RAG frameworks (LangChain, LlamaIndex) and the Laravel ecosystem — Laravel developers deserve first-class RAG tooling too