Rekhu Assistant is a custom AI assistant you build into your own Laravel application, for your own customers. It answers questions from your help, sends people to the right page, and carries out tasks through the routes you mark, as the signed-in user, with your validation, policies and middleware. Every conversation is metered per customer by Rekhu, so you can offer the assistant to your customers and bill them for it.

Contents

1. Requirements
2. Getting started
3. Choose your setup: Blade · Livewire · Inertia · API with Nuxt, Next or a mobile app
4. Actions
5. Pages
6. Help
7. A public chat for visitors
8. Applications, usage and limits
9. How it works
10. Security
11. Configuration
12. Commands
13. Troubleshooting

Requirements

Getting started

1. Get an app key

Create a Rekhu account and put credit on it under Billing (from $10). The assistant draws from that credit per conversation; without credit it cannot answer.

Then open Apps → Rekhu Assistant, create an application (for example "Shop", built with Laravel, monolith or multi-tenant) and, on its page, add a key for your first environment (local). Add one per environment later (staging, production); they all count toward the same application. A key is shown once, together with the commands of the next step.

2. Install the package

composer require rekhu/assistant-laravel
php artisan rekhu:assistant-install --key=agk_…

The install command checks the key with Rekhu, writes REKHU_ASSISTANT_KEY to .env, publishes config/rekhu-assistant.php and creates resources/rekhu/help.

3. Add the widget

In your layout, before </body>:

<x-rekhu-assistant />

The chat button appears for signed-in users.

4. Mark a first action

use Rekhu\Assistant\Attributes\Tool;

class OrderController extends Controller
{
    #[Tool('Reorder a past order: the same product and address as a new order; the quantity can be changed')]
    public function reorder(ReorderRequest $request, Order $order)
    {
        // your own code, as for the form on the order page
    }
}

5. Check what the assistant sees

php artisan rekhu:assistant --user=1

It shows your credit, lists the actions, pages and help topics that user can reach, and tests the connection to Rekhu. Then sign in, open the chat and ask "order my last business cards again".

Choose your setup

The package runs the chat on your server in every setup. What differs is how the widget is added and how the user is signed in.

Blade

Step 3 of Getting started is all there is. The tag uses the user's session and the page's CSRF token, and the package serves the widget's script itself: no npm and no build step.

{{-- resources/views/layouts/app.blade.php --}}
<body>
    {{ $slot }}

    <x-rekhu-assistant />
</body>

The tag accepts attributes that override the config for one layout:

<x-rekhu-assistant name="Shop assistant" greeting="Hi! How can I help with your order?" color="#0f766e" />

Livewire

Use the same Blade tag in the layout. With wire:navigate, keep it on the page while users navigate, so an open conversation stays on screen:

@persist('rekhu-assistant')
    <x-rekhu-assistant />
@endpersist

To refresh a component after the assistant changed data, pass the widget's event on to Livewire:

document.addEventListener('rekhu:action', () => Livewire.dispatch('rekhu-action'));

use Livewire\Attributes\On;

#[On('rekhu-action')]
public function refreshAfterAssistant(): void
{
    // an empty listener re-renders the component
}

[!NOTE] Actions are controller routes. Livewire component methods are not routes, so they cannot carry #[Tool] yet. Put the work in a route, or in a route that calls the same action class, and mark that route. Support for Livewire methods is planned.

Inertia (Vue or React)

The Blade tag in resources/views/app.blade.php works unchanged, but its page buttons reload the whole page. To open pages with Inertia's router and reload the props after an action, mount the npm widget instead:

npm install @rekhu/assistant-widget

{{-- resources/views/app.blade.php, in <head> --}}
<meta name="csrf-token" content="{{ csrf_token() }}">
@auth
    <meta name="rekhu-user" content="1">
@endauth

// resources/js/app.js, after createInertiaApp(…)
import { router } from '@inertiajs/vue3'; // or '@inertiajs/react'
import { mount } from '@rekhu/assistant-widget';

if (document.querySelector('meta[name="rekhu-user"]')) {
    mount({
        endpoint: '/rekhu/assistant/chat',
        csrf: document.querySelector('meta[name="csrf-token"]').content,
        navigate: (path) => router.visit(path),
        onAction: () => router.reload(),
    });
}

The middleware stays web,auth: the user's session signs them in.

An API with Nuxt, Next or a mobile app

The front end runs on its own domain and signs in with a token.

On the Laravel side, put the chat behind your API guard in .env:

REKHU_ASSISTANT_MIDDLEWARE=api,auth:sanctum

and allow the front end's domain in config/cors.php:

'paths' => ['api/*', 'sanctum/csrf-cookie', 'rekhu/assistant/*'],
'allowed_origins' => ['https://app.example.com'],

Your actions can be API routes or web routes. They run as the token's user, and a controller that redirects with a flashed message still reports that message to the assistant.

In the front end, mount @rekhu/assistant-widget with the token. In Nuxt, as plugins/rekhu-assistant.client.ts:

import { mount } from '@rekhu/assistant-widget';

export default defineNuxtPlugin(() => {
    const token = useCookie('token'); // wherever your app keeps it
    const router = useRouter();
    if (!token.value) return;

    mount({
        endpoint: 'https://api.example.com/rekhu/assistant/chat',
        headers: () => ({ Authorization: `Bearer ${token.value}` }),
        credentials: 'omit',
        navigateOrigins: ['https://api.example.com'],
        navigate: (path, url) => router.push(url.pathname + url.search),
        onAction: () => refreshNuxtData(),
    });
});

The widget's README shows the same for Next.js and plain HTML. A mobile app, or a chat screen of your own, uses the same endpoint; protocol 1 describes every request and event.

Actions

Mark a controller method with #[Tool]. The assistant calls the route exactly as when the user submits the form: its middleware (auth, can: and your own), the form request's authorize() and rules, route model binding, policies and events all apply. When the app refuses, the assistant is told why and explains it to the user.

use Rekhu\Assistant\Attributes\Tool;

#[Tool('List the user\'s orders with number, product, status and total', name: 'list_orders')]
public function index(Request $request) { … }        // GET: a read action; return JSON when $request->expectsJson()

#[Tool('Change the delivery address of an order that has not shipped yet', rules: ['address' => 'required|string|max:200'])]
public function address(Request $request, Order $order) { … }   // validates inline, so the rules are given here

#[Tool('Cancel an order that has not shipped yet')]
public function cancel(Order $order) { … }           // DELETE: the user confirms with a click first

Confirmations. When an action needs confirming, nothing runs until the user clicks Confirm on the card. The action and its exact input are kept on the server; a typed "yes", or anything the model writes, cannot run it.

Pages

Every named GET route is a page the assistant can offer, except routes the user may not open (can:, guest) and names matching pages.exclude in the config. The user gets a button to open the page; the assistant never navigates on its own. A description helps it pick the right page:

use Rekhu\Assistant\Attributes\Page;

#[Page('Invoices', help: 'All invoices of the account, with download and payment status')]
public function index() { … }

#[Page('Internal tools', hidden: true)]   // never offered
public function tools() { … }

Help

Write help as markdown files in resources/rekhu/help, one topic per file. The first # heading is the topic's title.

resources/rekhu/help/
├── shipping.md
└── returns.md

The assistant searches these topics for how-to questions and answers from them in the user's language. When the help does not cover a question, it says so instead of guessing.

A public chat for visitors

The same assistant can serve people who are not signed in, for example for questions before a quote. It is off by default:

REKHU_ASSISTANT_GUESTS=true

The same <x-rekhu-assistant /> tag then also shows for visitors, connected to a separate public endpoint. Mark what visitors may use:

#[Tool('Calculate a price quote for a product and quantity', guests: true)]
public function quote(QuoteRequest $request) { … }   // the route must work without login

Applications, usage and limits

Your Rekhu account keeps everything per application, like a project: open Apps → Rekhu Assistant and click an application.

• Keys per environment. One secret key for local, staging and production; all of them count toward the application.
• One monthly limit and a pause for the whole application, with a message on your notification channels at 80% and 100%. At the limit, or paused, the application's assistant answers nobody; your other applications go on. Its users read that the assistant is not available right now, and your app's log says why.
• Usage per user or per tenant, tracked, not limited: per user for a monolith, per tenant (with its users) for a multi-tenant app, as you choose when you create the application. Conversations, messages and usage per month, and a CSV to bill from.

For a multi-tenant app, tell the package which tenant a user belongs to, in a service provider, so usage shows per tenant:

use Rekhu\Assistant\RekhuAssistant;

public function boot(): void
{
    RekhuAssistant::tenantUsing(fn ($user) => $user->team);   // a model, or ['id' => …, 'name' => …]
}

Users are identified to Rekhu by their id only, never by name or e-mail.

How it works

Browser (widget)  ──▶  your Laravel app (this package)  ──▶  Rekhu  ──▶  the model
                         │
                         └──▶ your routes, run as the user

1. The widget sends the user's message to the package's chat endpoint in your app, with the user's own session or token.
2. The package builds the assistant's view of your app for this user: the actions and pages they may use, and your help topics.
3. It calls Rekhu, which meters the call for the user's company and forwards it to the model.
4. When the model asks for an action, the package runs your route in the same request, as the user, and reports the result back.
5. The answer streams back to the widget as text, steps and cards (a page to open, an action to confirm, a result).

Security

Configuration

php artisan rekhu:assistant-install publishes the config. To publish it again:

php artisan vendor:publish --tag=rekhu-assistant-config

config/rekhu-assistant.php also holds:

Commands

Troubleshooting

Changelog

See CHANGELOG.md for what changed in each version.

Licence

Licensed, not sold, to holders of a Rekhu account under the Rekhu Terms of Service. See LICENSE.txt.