Download the PHP package m-tech-stack/laravel-ai-engine without Composer

Laravel AI Engine

Laravel AI Engine is a Laravel package for AI chat orchestration, deterministic tool execution, GraphRAG/RAG, and node federation across multiple Laravel apps.

Status (May 2026)

Current codebase includes:

• modular orchestrator (IntentRouter, AgentPlanner, action execution, response finalizer)
• RAG decision runtime split into focused services (decision, execution, context/state, policy, feedback, structured data)
• deterministic node routing via ownership and manifest metadata (no AI-only node guessing)
• standardized response envelope (success, message, data, error, meta)
• localization stack (locale middleware, lexicons, prompt templates)
• prompt policy learning with DB-backed feedback events and policy versions
• infrastructure hardening (remote migration guard, Qdrant self-check, startup health gate)
• admin UI with user/email/IP access controls
• central Neo4j graph sync and read path
• planner-driven graph retrieval with query-kind-aware traversal templates
• scoped graph knowledge-base acceleration (plan cache, result cache, entity snapshots)
• host-app background KB build flow
• host-app capability memory primitives for semantic tool/action/module routing
• compacted agent conversation memory for long chat sessions
• provider-tool lifecycle APIs, MCP/App tool bridge, realtime tool dispatch, hosted artifacts, and observability exporters

Compatibility

• package: m-tech-stack/laravel-ai-engine
• PHP: ^8.1
• Laravel: 8.x | 9.x | 10.x | 11.x | 12.x
• Guzzle: ^7.0
• OpenAI PHP client: ^0.8 | ^0.9 | ^0.10
• Symfony HTTP client: ^5.4 | ^6.0 | ^7.0

Source of truth: composer.json.

Install

Runtime Architecture

• Engine facade and app('ai-engine') resolve to UnifiedEngineManager
• UnifiedEngineManager is the public fluent entrypoint
• AIEngineService is the direct typed execution API for internal services and explicit AIRequest flows
• DriverRegistry is the single driver construction path

Breaking Upgrade Note

AIEngineManager and EngineBuilder were removed. If your application instantiated or type-hinted them directly, migrate to:

• LaravelAIEngine\\Services\\UnifiedEngineManager for fluent facade-style usage
• LaravelAIEngine\\Services\\AIEngineService for direct request execution
• LaravelAIEngine\\Services\\EngineProxy as the fluent builder returned by engine() / model()

Reference-pack upgrade note:

• selected_looks with more than one item now defaults to strict_selected_set
• look_id without an explicit mode now defaults to guided
• guided starts from your app-selected look, then can continue into vendor-generated variants
• use look_mode=strict_stored if you need deterministic production references from one approved stored look
• use look_mode=strict_selected_set if one pack must cover multiple approved stored looks in exact order
• strict_stored_looks=true is supported as a shorthand for strict production mode

Minimal Production Baseline

For multi-app federation:

For central GraphRAG with Neo4j:

Fresh installs are now Neo4j-first by default. If Neo4j is not fully configured, runtime read-path resolution falls back to the configured vector driver, which remains qdrant by default.

For shared Neo4j clusters, prefer a dedicated vector slot per app or tenant:

That produces names like chunk_embedding_index_billing_app and embedding_billing_app so you do not collide with other apps on the same Neo4j database.

High-Value Commands

Diagnostics

ai:test-everything is the umbrella validation command:

• safe: package graph and chat slices, plus root mocked chat route when available
• graph: safe plus package live Neo4j graph checks
• full: graph plus root-app live graph/chat tests
• all: full plus billed provider live matrix

ai:backend-status shows the effective read backend and whether Neo4j is active or falling back.

ai:model-status "App\\Models\\Project" shows whether a model is ready for indexing, graph publishing, and chat retrieval. Use --id=<record> to inspect a real row instead of a blank instance, which is useful when a model only becomes indexable after required attributes are populated.

ai:test-real-agent includes only generic built-in scripts: minimal and followup. Use repeated --message options for quick checks, and use --script-file for app-specific business flows.

Model Catalog

Model metadata (engine, driver, credit index, content type, context window, capability flags) resolves database-first: an ai_models row wins, then the package catalog at resources/models.json, then name-pattern heuristics. No database rows are required — the shipped catalog covers every predefined model out of the box. Seed it when you want metadata editable as data (admin UIs, per-tenant pricing), and sync from live provider APIs to adopt models newer than the shipped catalog.

Provider, MCP, and Realtime APIs

Register observability exporters in ai-engine.observability.exporters to send traces and evaluations to HTTP collectors, OpenTelemetry OTLP, LangSmith, or logs.

For agent chat tasks, /api/v1/agent/chat is synchronous by default. Send execution_mode=auto to let the package keep simple chat synchronous and queue durable work such as goal/sub-agent runs, streaming work, structured collection callbacks, and matched skills. Send execution_mode=async to force a queued run.

SSE works without a WebSocket service. Enable Laravel Broadcasting when the app uses Reverb, Pusher, Soketi, Ably, or another broadcast driver.

See docs/chat-flow.mdx for the full ChatFlow trace from request validation through runtime routing, dispatcher execution, response metadata, and the focused test suite.

Headless Assistant Runtime

The package includes a reusable assistant foundation while leaving domain repositories, authorization, and UI in the host application:

• task-specific primary/fallback model routes with readiness diagnostics
• model-selected structured resource retrieval through search_assistant_resources
• tenant/workspace/user-scoped entity focus for follow-up questions such as “tell me more about the course above”
• scoped knowledge-source contracts for shared, tenant-public, tenant-private, workspace-private, subscription-limited, and user-private documents
• a replaceable multi-scope knowledge index that connects authorized provider documents to standard RAG retrieval
• structured responses for cards, carousels, metrics, actions, sources, and speech metadata
• headless browser clients for live transcription, activity, answer deltas, SSE, microphone/WebRTC voice, authoritative tool dispatch, mute, interruption, and cancellation

Publish the client and validate configuration:

The publish tag writes both assistant-client.js and assistant-voice-client.js. The voice client is UI-framework neutral:

See docs/headless-realtime-voice-sdk.mdx for tool dispatch, security, mixed-language turn detection, cancellation, and UI integration.

Version 3.0 removes the compatibility aliases deprecated in 2.x. Inspect the machine-readable removal inventory with php artisan ai:compatibility --json; --fail-on-deprecated succeeds when the host has completed the cutover. See docs/upgrade-3.0-deprecations.mdx.

Register host adapters in config/ai-agent.php:

Resource providers should call application services/repositories and return AssistantResourceResult; they should not query Eloquent directly. The package passes trusted user, tenant, and workspace scope into each query and applies a second access-policy check before results reach the model.

The vector knowledge-index driver uses the configured package vector backend, batch embeddings, document fingerprints, and scope-safe storage IDs. Search results are checked against the current authorized document set even when a custom vector driver ignores filters. The dependency-free memory driver remains the default for backward compatibility.

See docs-site/guides/assistant-runtime.mdx for contracts, examples, streaming events, security rules, host integration, and production deployment.

Structured Chat Collection

Pass $collection->toArray() as the chat collection option. addField() remains the generic JSON-schema escape hatch, while helpers such as addText(), addEmail(), addDate(), addSelect(), and addMultiSelect() add schema plus UI metadata. The agent extracts canonical values, asks for missing values in the user's language, returns localized collection.fields options for frontends, asks for confirmation, closes the session, then sends the completed JSON payload to the callback and fires AgentStructuredCollectionCompleted. Frontend controls may submit exact canonical enum values as field: value; enum arrays accept a comma-separated list or JSON array. These schema-qualified control messages are applied deterministically without an AI request, while invalid or free-text messages retain the normal model path.

For models qualified for provider-native function calling, pass structured_collection_transport => 'native_tools' beside the collection option (or set AI_AGENT_STRUCTURED_COLLECTION_TRANSPORT=native_tools). The package requires a typed structured_collection_turn call and reads its arguments directly, avoiding text-JSON formatting variance. Set structured_collection_native_field_scope => 'required' when a compact native schema should expose required fields plus already-collected fields; the default all scope preserves broad optional-field extraction. The backward-compatible transport default remains prompt_json.

withPreview('html') adds a safe package-rendered preview under collection.preview; the HTML is escaped and uses external assets from /vendor/ai-engine/structured-collection.css and /vendor/ai-engine/structured-collection.js. Use withPreview('component') when the frontend should render the package component contract itself.

Federation (Safe Flow)

Neo4j GraphRAG and Knowledge Base

Prompt Policy Learning (Policy-Level)

Entity List UX (Important)

List responses are model-driven:

• implement toRAGListPreview(?string $locale = null) for clean multi-line list cards
• implement toAISummarySource() for compact summary cache input

If toRAGListPreview() exists, it is preferred over fallback summary rendering in structured list responses.

Agent Capability Memory

Capability memory stores what an agent can do, not business records. Use it when a host app needs semantic routing over available tools, CRUD actions, modules, relations, and query surfaces before deciding whether to call deterministic tools, RAG, or the LLM.

Package-owned primitives:

• LaravelAIEngine\Contracts\AgentCapabilityProvider
• LaravelAIEngine\DTOs\AgentCapabilityDocument
• LaravelAIEngine\Services\Agent\AgentCapabilityRegistry

Host apps own the domain provider and vector sync command. A typical provider reads app-specific registries such as actions, model catalogs, and tool configs, then returns compact capability documents:

Register providers in the host app:

Then the host app can sync AgentCapabilityRegistry::documents() to Qdrant, Neo4j, Redis, or any other memory layer using its own command/service. Keep domain knowledge in the app provider; keep reusable contracts and registry behavior in this package.

Agent Turn Routing and Retrieval Policy

AI-native turns expose generic, host-overridable routing and retrieval contracts while preserving existing behavior through passthrough defaults. Hosts may provide precomputed turn/retrieval decisions, scope find_tools discovery to the turn's exposed tool roster, and add multilingual discovery aliases without weakening execution-time authorization.

See Agent Turn Routing and Retrieval Policy for extension points, failure behavior, telemetry, and backward-compatibility guarantees.

Action Framework

For app-wide CRUD and action flows, the package owns the reusable action framework and the host app owns domain services, permissions, DTOs, repositories, and database writes.

Package contracts:

• LaravelAIEngine\Contracts\ActionDefinitionProvider
• LaravelAIEngine\Contracts\ActionRelationResolver
• LaravelAIEngine\Contracts\ActionAuditLogger
• LaravelAIEngine\Contracts\ActionExecutor
• LaravelAIEngine\Contracts\ConversationMemory
• LaravelAIEngine\Contracts\AgentCapabilityProvider

Package services:

• LaravelAIEngine\Services\Actions\ActionRegistry
• LaravelAIEngine\Services\Actions\ActionOrchestrator
• LaravelAIEngine\Services\Actions\GenericModuleActionDefinitionProvider
• LaravelAIEngine\Services\Actions\DefaultActionFlowHandler
• LaravelAIEngine\Services\Actions\NullActionAuditLogger
• LaravelAIEngine\Services\Memory\CacheConversationMemory

Register static definitions, provider classes, and relation resolvers in the host app:

ActionDefinitionProvider publishes action definitions. prepare and handler callbacks prepare and execute one action through app services. ActionRelationResolver resolves or creates related records around prepare/execute. ConversationMemory lets package flows store pending payloads without hardcoding a storage backend.

Action definitions use a generic schema:

• operation: create, update, delete, status, convert, or custom
• risk: low, medium, high, or destructive
• confirmation_required: optional; defaults from risk
• required, parameters, summary_fields, prepare, handler, suggest, and relation_resolvers

Confirmed writes can include _idempotency_key or idempotency_key in the payload, or metadata.idempotency_key in the UnifiedActionContext. Successful results are replayed for the same user/action/key instead of executing again. Bind ActionAuditLogger in the host app to persist prepare/execute audit records; the package uses NullActionAuditLogger by default.

Generic Module Actions

For CRUD-like modules, host apps can register metadata instead of writing one action class per model. The package generates create_{resource} and update_{resource} definitions from ai-agent.generic_module_actions, validates payloads, resolves declared relations, applies safe defaults, scopes writes with configurable ownership fields, and filters writes to real database columns.

This generic layer is package-level. The module list, model classes, permissions, sensitive-field allowlist, and relation lookup names remain app-specific.

Ownership is intentionally host-configurable. By default the package checks common actor fields in this order: created_by, creator_id, owner_id, user_id, then the actor id. Apps with a different tenant or organization model can provide a callable:

AI-Native Skill Intake

Multi-turn action intake now runs through AI-native skills and declared tools. A skill describes the target JSON, relations, expected track, and final tool. The runtime gives that schema and tool catalog to the model, then Laravel validates, confirms, audits, scopes, and executes through ActionOrchestrator.

Host apps still own the domain-specific parts: action definitions, permissions, validation, relation resolution, confirmation, and database writes.

Model-config tool handlers receive both the selected parameters and the current UnifiedActionContext, so host apps can keep drafts scoped to the active user/session and avoid global auth assumptions:

If a handler returns metadata.agent_strategy, the agent response preserves that strategy and includes the tool result in response metadata. This lets host apps expose stable intents such as business_action_needs_input, business_action_prepare, and business_action_execute while the model still decides which tool to call next.

Relevant environment settings:

Agent Conversation Context Compaction

Agent chat history is compacted before persistence and prompt construction so long sessions keep useful context without sending every old turn back to the model. The package keeps recent messages verbatim, folds older messages into metadata.conversation_summary, and reuses that summary in conversational prompts, intent routing, and RAG decision context.

Default settings are conservative:

This memory is for conversation state only. Business records and capability documents should still be indexed through the host app's RAG, graph, or capability-memory sync pipeline.

Durable conversation memory is also available through ai_conversation_memories. Normal chat transcripts stay in ai_conversations through ConversationTranscriptService, while durable memory extracts small scoped facts from compacted turns, retrieves only relevant memories under AI_AGENT_MEMORY_MAX_PROMPT_CHARS, and can optionally use a configured vector index while SQL remains the authorization source of truth. See docs/agent-memory.mdx.

The Learn layer stores reusable examples and rules that can be searched later by scope. It is generic enough for design packs, business workflows, support tone, API examples, or UI component guidance:

getdesign is supported as an optional adapter for DESIGN.md sources; see docs/learning.mdx.

The same flow is available from Artisan when the package should create the artifact:

Agent chat responses can also return bullet/numbered response points as structured arrays and include next-step suggestions from registered actions, skills, and tools:

Use response_points_format=text|array|both|none. Suggestions are generic: register an invoice action, email reply skill, or any other capability and the package matches against its metadata instead of hardcoding business modules.

Search Document and Graph Contracts

Use explicit contracts for indexed and graph-aware models:

• toSearchDocument()
• toGraphObject()
• getGraphRelations()
• getAccessScope()
• toRAGSummary()
• toRAGDetail()
• toRAGListPreview(?string $locale = null)

Ontology Packs and Live Provider Matrices

You can enable built-in ontology packs to bias relation inference toward your app domain:

Current packs:

• project_management
• messaging
• support
• crm
• commerce

For broader billed live coverage in CI or scheduled validation, provide provider matrices:

These values are read through config('ai-engine.testing.live_provider_matrix.*'), so set them before running php artisan config:cache in cached environments.

OpenRouter has a dedicated live smoke for routed multimodal features:

Optional overrides:

To let OpenRouter prefer free/cheapest routed chat models, enable the optional cost optimizer:

Per request, pass cost_optimization: true plus an optional models list when one workflow should use a specific free/cheap pool. The driver sends OpenRouter models fallbacks and provider.sort.by=price; it keeps the requested model as a paid fallback unless disabled.

Provider shortcuts are available for built-in engines, so common calls can use the provider name directly while keeping engine('provider') as the explicit escape hatch:

Use withProviderOptions() when a provider adds fields faster than the package API. Normal chat/media requests now support generic and provider-specific passthrough options:

For OpenAI Responses state, set a conversation id and opt into remembering/reusing response ids:

Graph retrieval now prefers matched chunk context plus entity_ref and object payloads for follow-ups and UI reuse.

Admin UI

Enable:

Open: /ai-engine/admin (or your configured prefix).

API Contract

Built-in direct generation endpoints:

• POST /api/v1/ai/generate/text
• POST /api/v1/ai/generate/image
• POST /api/v1/ai/generate/transcribe
• POST /api/v1/ai/generate/tts

For consistent TTS per saved character, store voice_id and optional voice settings when you save the character, then call /api/v1/ai/generate/tts with use_character or use_last_character. OpenAI, Gemini native TTS, Google Cloud Text-to-Speech, ElevenLabs, and lower-cost media providers can all be routed through the same direct audio generation flow.

Authenticated calls are credit-enforced (same policy as chat/RAG), including image/audio endpoints.

FAL output units are charged through the model credit_index and engine rate. The default FAL engine rate is 1.3, so FAL usage includes a 30% margin before app-specific plan pricing. Input/reference media is charged with fixed extra credits per input unit, not a percentage of the output cost. The package ships conservative defaults and lets apps override them per model:

Gemini defaults to AI_GEMINI_RATE=1.2, giving Gemini usage a 20% margin by default. Override AI_FAL_AI_RATE or AI_GEMINI_RATE in the host app when your subscription tiers need different margins.

Gemini audio_generation defaults to native TTS (gemini-2.5-flash-preview-tts). The driver converts Gemini inline PCM audio to WAV files before returning media URLs. lyria-002 remains available for music-generation style routing under music_generation.

Use the pricing audit and dry-run commands before enabling live traffic:

Apps can also call POST /api/v1/ai/pricing/preview with engine, model, prompt, and parameters to show the same credit breakdown before making a live provider request.

When direct requests omit engine, the package can resolve the provider from the requested model and configured availability. By default it prefers the model's native provider first, then OpenRouter-compatible fallbacks. Tune this with AI_ENGINE_REQUEST_PROVIDER_PRIORITY.

For text generation you can also omit both engine and model and send a simple preference like cost, speed, performance, or quality. The package resolves a suitable model/provider first, then applies the normal credit checks against the final route.

Toggle/prefix with env:

Inject your own middleware into package API routes:

Documentation

Deep docs are in docs-site (Mintlify).

Run locally:

Recommended reading order:

1. guides/quickstart
2. guides/concepts
3. guides/single-app-setup
4. guides/model-config-tools
5. guides/capability-memory
6. guides/graph-relation-modeling
7. guides/knowledge-base-security
8. guides/direct-generation-recipes
9. guides/entity-list-preview-ux
10. guides/rag-indexing
11. guides/graph-rag-neo4j
12. guides/end-to-end-graph-walkthrough
13. guides/copy-paste-playbooks
14. guides/multi-app-federation
15. guides/neo4j-ops-runbook
16. guides/policy-learning
17. guides/testing-playbook
18. guides/troubleshooting

Upgrading Existing Installs

If config was published before recent refactors, refresh it:

See docs-site/reference/upgrade.mdx for the upgrade checklist and removed-class migration notes.

For central graph migration and operations, use:

• docs-site/reference/qdrant-to-neo4j-migration.mdx
• docs-site/guides/neo4j-ops-runbook.mdx
• docs-site/guides/knowledge-base-security.mdx

License

MIT