Ai Kit Ui Livewire Laravel Package

Getting Started

ai-kit is a Laravel package (vendor solution-forest/ai-kit) that gives you an end-to-end RAG stack: document ingestion, vector storage/retrieval, and cited chat agents, with multiple front doors (Livewire, Filament, CLI, HTTP, MCP).

1. Install and publish config/migrations:

   composer require solution-forest/ai-kit
   php artisan vendor:publish --provider="SolutionForest\AiKit\AiKitServiceProvider"
   php artisan migrate
   

2. Configure your providers in config/ai-kit.php (or the published equivalent): LLM provider/credentials, embedding model, and vector store driver. This is the first file to read — it tells you which drivers, chunking defaults, and agent options are available in this version.
3. Check the service provider (AiKitServiceProvider) for what it auto-registers: routes, Livewire components, Filament plugin, commands, and MCP server. That registration list is effectively the package's surface area map.
4. First use case — ingest a document and ask a question:

   php artisan ai-kit:ingest storage/app/manuals/handbook.pdf
   

   Then hit the Livewire chat route (or the Filament panel page) and ask a question that only exists in that PDF. If the answer comes back with a citation pointing at the right chunk, your pipeline is wired correctly end-to-end.
5. Look first at: the config file, the migrations (to understand the schema: documents, chunks, embeddings, conversations), and the HTTP routes. Those three give you 80% of the mental model.

Implementation Patterns

Ingestion as a queued pipeline. Don't ingest synchronously in a request. Wrap ai-kit:ingest (or the underlying ingestor service) in a job, and dispatch per file. Ingesting a batch of PDFs is CPU/IO-heavy (parsing + embedding calls) and will time out otherwise. Use a dedicated queue so embedding rate limits don't stall your main workers.

Source-per-tenant / source-per-domain partitioning. Because retrieval quality degrades badly when unrelated corpora are mixed, scope ingestion and retrieval by a namespace, collection, or metadata tag (tenant ID, project ID, product line). Check the config for a collection/namespace concept and thread it through both ingest and query. This is the single highest-leverage architectural decision with a RAG package.

Multi-surface, one agent definition. Define your RAG agent once (system prompt, retrieval settings, citation behaviour) and expose it through the surfaces the package already gives you rather than reimplementing:

• Livewire for a quick internal chat UI,
• Filament for admin-side document management + chat in the same panel,
• HTTP API for your own SPA/mobile frontend,
• CLI for batch jobs and smoke tests,
• MCP to let external AI tooling query your corpus.

Treat the HTTP API and MCP server as thin adapters over the same agent service — if you find yourself writing retrieval logic in a controller, stop and call the package service instead.

Streaming responses. For anything user-facing, use the streaming path (if exposed by the HTTP API/Livewire component) rather than awaiting the full completion. RAG answers are slow because of retrieval + long context; non-streaming will feel broken.

Citations as first-class data. The package advertises cited answers. Persist the retrieved chunk IDs alongside each assistant message so you can (a) render sources later, (b) debug "why did it say that", and (c) build feedback loops ("this citation was wrong"). Don't discard the retrieval payload after rendering.

Refresh and re-ingest strategy. Documents change. Plan for re-ingestion: key ingested documents by a stable external ID + content hash, skip unchanged files, and delete stale chunks. Check whether the package handles updates or whether you must delete-then-reingest. Schedule this as a nightly job for large corpora.

Integrate with existing models. Rather than a separate document table you never look at, link ingested documents back to your domain models (e.g. a Document belongsTo a Project) via metadata, so retrieval can be filtered by "only documents this user can see." Permissions-aware retrieval is the difference between a demo and a shippable feature.

Testing. In tests, point the vector store at an in-memory/fake driver and stub the LLM. Assert on retrieval (correct chunks returned) separately from generation (correct prompt assembled) — otherwise every test burns tokens and is flaky.

Gotchas and Tips

v0.2.0 means the API is not stable. At 0.x, expect breaking changes in config keys, service class names, and route names between minor versions. Pin the version ("solution-forest/ai-kit": "0.2.*") and read the changelog before every bump. Wrap package calls behind your own thin service/adapter so a breaking change is a one-file fix.

Config caching will bite you. After editing config/ai-kit.php, run php artisan config:clear. A stale cached config with old embedding dimensions or a wrong vector driver produces confusing retrieval failures that look like model bugs.

Embedding dimension mismatches. If you switch embedding models after ingesting, existing vectors are the wrong size and retrieval silently returns garbage or errors. Re-ingest the entire corpus when changing embedding models. Store the model name/dimension alongside the chunks so you can detect this.

Chunking is where quality lives. Defaults are rarely right for your content. Tune chunk size/overlap — too large and citations are vague, too small and answers lose context. Test with a set of questions you know the answers to; keep it as a small eval suite.

Long-running ingestion in the CLI. Expect memory growth on large PDFs/Excel files. Cap batch sizes, run in chunks, and watch for Allowed memory size exhausted. Set sensible timeouts on the queue worker too.

PDF/Excel parsing is the usual weak link. Scanned PDFs need OCR (which the package may not do), and multi-sheet Excel files often ingest poorly. Validate a sample of extracted text before trusting a bulk import — garbage in, confidently-cited garbage out.

Vector store choice matters operationally. SQLite/pgvector/外部 vector DBs have very different setup costs and filtering capabilities. Metadata filtering (tenant, permissions, date) is the feature that most often forces you off the simplest driver. Decide early, because migrating vectors later means re-embedding everything.

Cost and rate limits. Ingestion embeds every chunk; a large corpus is a real bill. Add batching, retry-with-backoff on 429s, and a hard cap on tokens per ingestion job. Log embedding token usage per document.

MCP and HTTP surfaces are attack surface. If the MCP server or API is reachable beyond localhost, it can read your corpus. Put it behind auth, restrict to trusted clients, and never expose it with the default config in production. Check what the published routes actually register.

Livewire/Filament are conveniences, not your product UI contract. They're great for internal tools and demos, but their components can change between 0.x releases. If chat is a customer-facing feature, build against the HTTP API and control your own frontend.

Debugging retrieval, not just answers. When an answer is wrong, first check whether the right chunks were retrieved at all. Add a debug mode or command that dumps retrieved chunks + scores for a query. Most "the AI is dumb" reports are retrieval failures, not generation failures.

Extension points to favour: the agent/prompt configuration, chunking strategy, custom ingestors for your own file types, and custom retrieval filters. Prefer these over forking the package — a fork of a 0.x package becomes unmaintainable fast.