Download the PHP package solution-forest/ai-kit-core without Composer

ai-kit-core

The engine of the ai-kit suite — document ingestion, chunking, extraction, vector retrieval, and RAG agents for Laravel, built on the official Laravel AI SDK.

composer require → php artisan ai-kit:install → a grounded, cited RAG assistant over your own documents — with no external vector database required.

• Two vector drivers behind one contract: SQLite (zero-infra, default) and pgvector (production).
• Two RAG modes via one config flag: tool (agentic) and inject (classic).
• Ingest PDF, Word (.docx), Excel (.xlsx), HTML, Markdown, plain text, and URLs.
• Provider-agnostic — OpenAI, Anthropic, OpenRouter, Gemini, Groq, Mistral, … (anything the AI SDK supports).
• Fully testable offline — no API keys needed in CI.

Why ai-kit?

Building a grounded, cited RAG chatbot over your own documents in Laravel means wiring together a dozen moving parts: parsing PDFs/Word/Excel, chunking text, generating embeddings, running a vector store, similarity search, prompt orchestration, streaming, citations, conversation history, and cost tracking.

ai-kit does all of that for you — on the official Laravel AI SDK, with no external vector database. composer require → php artisan ai-kit:install → a working, source-cited assistant in under 30 minutes. Then expose it however you like: a Livewire chat widget, an admin panel, a JSON API, a CLI, or an MCP server for AI agents.

Architecture

One core, four faces. Every surface calls the same service layer, so RAG behaviour is identical whether a user chats in the browser, you script the CLI, another service hits the API, or an AI agent connects over MCP.

Requirements

• PHP 8.3+
• Laravel 12 or 13
• laravel/ai ^0.9

Install

The installer:

1. Publishes config/ai-kit.php + migrations (including the AI SDK's conversation tables).
2. Interactively asks for your AI provider config (chat + embeddings provider/model/key) and writes it to .env.
3. Scaffolds App\Ai\SupportAgent (extends RagAgent).
4. Runs migrations.
5. Optionally seeds a demo knowledge base.

Then set your keys (the installer adds the scaffold; fill in the value):

Quick start

Or from the CLI:

How ingestion works

• Synchronous (sync: true) — runs inline; used by ai-kit:demo and CLI. No queue worker needed.
• Queued (default) — dispatches a chained ExtractText → ChunkDocument → EmbedChunks batch; document status moves pending → processing → indexed (or failed).

Every chunk stores its raw embedding and the embedding model name, so re-indexing with a different model is detectable and you can switch drivers without re-embedding blindly.

Supported document types

Legacy binary .doc / .xls are not supported.

Two RAG modes

config('ai-kit.mode'):

• tool (default) — the agent gets a SearchKnowledgeBase tool and decides when/what to search (agentic RAG; supports multi-hop). Requires a model with reliable tool-calling.
• inject — no tool; ContextInjector retrieves and prepends context to the prompt before the model runs (classic RAG). Grounding never depends on the model choosing to search — safer with small models.

Both consume the same Retriever contract.

Two vector drivers

config('ai-kit.retrieval.driver'):

• sqlite (default) — uses the sqlite-vec (vec1) extension when present, otherwise an exact pure-PHP cosine scan (correct everywhere, zero setup — ideal for demos and small/medium corpora). Optional extension path: AI_KIT_SQLITE_VEC_PATH.
• pgvector — a vector column indexed with HNSW/IVFFlat, searched with the <=> cosine operator. Scales to millions of chunks.

Building agents

RagAgent reads config and wires the configured chat provider/model into every prompt() / stream():

Customise instructions by extending it (the installer scaffolds this):

Point AI_KIT_AGENT=App\Ai\SupportAgent at it. The default instructions are strict-grounded (search-first, refuse-if-unsupported, cite by document title).

Conversation persistence & token usage

When a prompt runs for an authenticated participant (->forUser($user) / ->continue($id, $user)), the AI SDK persists the exchange to agent_conversations / agent_conversation_messages, including per-message token usage. Aggregate it with UsageStats:

Cost is estimated from config('ai-kit.pricing') ($ per 1M tokens, per model) using the active chat model's rate.

Multi-tenancy

Every table has a nullable tenant_id. Scope models + retrieval:

Enable with AI_KIT_TENANCY=true.

Contracts (swap any layer)

Configuration reference

config/ai-kit.php: mode, default_collection, agent (class + instructions), chat (provider/model/fallback/streaming), embeddings (provider/model/dimensions/cache/timeout), chunking (size/overlap), retrieval (driver/top_k/min_score/sqlite/pgvector), ingestion (queue/embed_batch), tenancy, database (connection/prefix), features (dashboard/token_usage), pricing. Every value has an env() override.

Commands

Headless surfaces (CLI · HTTP API · MCP)

Everything the Filament panel does is reachable without Filament. All four surfaces call the same service layer (ChatService, CollectionService, DocumentService), so behaviour is identical everywhere.

CLI

HTTP API (optional)

Enable with AI_KIT_API=true. Locked behind auth by default (config('ai-kit.api.middleware') = ['api','auth:sanctum']); set your own guard, or ['api'] for public. Prefix: AI_KIT_API_PREFIX (default api/ai-kit).

MCP server (optional)

Expose ai-kit to MCP clients (Claude Desktop, IDE agents). Requires composer require laravel/mcp, then AI_KIT_MCP=true. Tools: search_knowledge_base, ask_knowledge_base, list_collections, ingest_url. Serve over stdio:

Set AI_KIT_MCP_WEB=true to also register an HTTP transport route (config('ai-kit.mcp.web_route'), guarded by mcp.web_middleware).

Examples

HTTP API (Bearer auth by default):

MCP — point a client (e.g. Claude Desktop) at the stdio server:

Programmatic (any surface, same result):

Testing

The suite runs offline with no API keys — LLM calls use the AI SDK's fakes, embeddings use a deterministic in-memory double.

The ai-kit suite

One core, four faces — the Livewire UI, CLI, HTTP API, and MCP server all call the same service layer (ChatService, CollectionService, DocumentService), so behaviour is identical everywhere.

ai-kit-ui-livewire and ai-kit-filament are optional; core is fully usable headless.

License

MIT © SolutionForest