Our take on AI here is to aim it at the support agent, not the customer. The human owns the conversation. The model makes the reply a little cleaner and a little faster. There There is in private beta, and you can apply for early access at there-there.app.

We're building There There with Laravel and Inertia. One package we've come to rely on is Laravel Wayfinder. It generates typed TypeScript functions for every route and controller in your Laravel app, so the frontend talks to the backend without a single hardcoded URL. This post is about why that matters.

Using Wayfinder

A React codebase quickly fills up with URL strings. Every fetch, every form action, every link points to a route by way of a template literal. Then you rename a route in Laravel, or add a required parameter, and nothing breaks at compile time. You find out in production, or when a teammate clicks the wrong thing.

Wayfinder fixes this by generating a function per named route. You import it and call .url() to build the URL.

Here's a snippet from our team membership toggle.

import {
    add as addTeamMember,
    remove as removeTeamMember,
} from '@/routes/app/settings/workspace/teams/members';

removeTeamMember.url({ team: team.ulid, user: member.ulid });
addTeamMember.url({ team: team.ulid, user: member.ulid });

Two things are worth pointing out. First, the parameters are type-checked. If you rename the user route parameter to member, TypeScript catches every caller. Second, the route names map cleanly to import paths, so finding them is just autocomplete.

Wayfinder also generates a typed function per controller. We use that when we talk to an endpoint via plain fetch, outside of an Inertia visit. Here's the retry action for a failed outbound message.

import MessageRetryController from '@/actions/App/Http/Controllers/Tickets/MessageRetryController';

await fetch(
    MessageRetryController.url({ ticket: current.ulid, message: message.ulid }),
    { method: 'POST' },
);

Same deal. The URL is type-safe, the parameters are checked, and renaming the controller in PHP breaks the TypeScript build rather than production.

To make all of this work, we hook Wayfinder into Vite. Here's the relevant bit of our vite.config.js.

import { wayfinder } from "@laravel/vite-plugin-wayfinder";

export default defineConfig({
    plugins: [
        // ...
        wayfinder(),
    ],
});

The plugin watches your Laravel routes and controllers during development, and regenerates the typed functions whenever something changes. Imports stay in sync with your backend without any manual step.

In closing

Wayfinder has shaved a whole category of bug off our work. No more grep-the-codebase when a route changes, no more "why is this fetch returning 404", no more arguing about trailing slashes. You write the route in Laravel, import it in TypeScript, and the two stay honest with each other.

You can read more about it in the Wayfinder repo on GitHub. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

A lot of the fun is on the AI side. We're not using it to replace support agents, we're using it to make them faster. The human reads the ticket, thinks, and clicks a button. The model pulls up relevant history, drafts a reply, tags the ticket, closes a duplicate. There There is in private beta right now, and you can apply for early access at there-there.app.

The whole AI layer is built on the new Laravel AI SDK. It's been a joy to work with, and I'd like to walk through how we use it.

Using the Laravel AI SDK

Everything starts with an agent class. Ours is called ThereThereAgent. It declares which model to use, what the system prompt looks like, which tools the model can call, and what conversation history to replay.

Here's a trimmed version.

use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

#[Temperature(0.3)]
#[MaxSteps(10)]
class ThereThereAgent implements Agent, Conversational, HasTools
{
    use Promptable;

    public function __construct(
        protected Workspace $workspace,
        protected User $user,
        protected ?Ticket $contextTicket = null,
        protected array $conversationHistory = [],
    ) {}

    public function model(): string
    {
        return config('ai-pricing.default.name');
    }

    public function instructions(): string
    {
        return view('prompts.ai.there-there-agent-system', [
            'workspace' => $this->workspace,
            'user' => $this->user,
            'contextTicket' => $this->contextTicket,
        ])->render();
    }

    public function tools(): iterable
    {
        return [
            new ChangeTicketStatusTool($this->workspace),
            new AssignTicketTool($this->workspace),
            new AddNoteToTicketTool($this->workspace),
            new ManageTicketTagsTool($this->workspace),
        ];
    }
}

A few things I like here. The #[Temperature] and #[MaxSteps] attributes are declarative. No wiring through constructor parameters, no config file. The instructions() method renders a Blade view, which means our system prompt is a regular template with includes and partials. And tools() returns an iterable, so we can turn tools on and off depending on context.

Tools are where it gets fun. Each one is a class the model can decide to call, with a typed JSON schema so arguments are validated before they hit our code. Here's the tool that changes a ticket's status.

class ChangeTicketStatusTool implements Tool
{
    use FindsTicketsInWorkspace;

    public function __construct(protected Workspace $workspace) {}

    public function description(): string
    {
        return 'Change the status of a ticket. Use this when the agent asks to close, reopen, or mark a ticket as spam.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'ticket_subject' => $schema->string()->description('The subject, title, or ULID of the ticket.')->required(),
            'contact_email' => $schema->string()->description('The contact email on the ticket.')->required(),
            'new_status' => $schema->string()->description('The new status: open, closed, or spam.')->required(),
        ];
    }

    public function handle(Request $request): string
    {
        $status = TicketStatus::tryFrom($request['new_status'] ?? '');

        if (! $status) {
            return 'Invalid status. Must be one of: open, closed, spam.';
        }

        $ticket = $this->findTicket($request['ticket_subject'], $request['contact_email']);

        if (! $ticket) {
            return 'Could not find a matching ticket.';
        }

        app(ChangeTicketStatusAction::class)->execute($ticket, $status);

        return json_encode([
            'result' => 'success',
            'ticket' => $ticket->displayTitle(),
            'new_status' => $status->label(),
        ]);
    }
}

description() is what the model reads when deciding whether to call this tool. schema() returns the typed JSON schema the model has to match. handle() runs the tool and returns a string that goes back into the model's context. We return JSON on success so the model has structured data to refer to when it writes its final reply.

Notice we don't do heavy lifting inside the tool. The actual work is delegated to ChangeTicketStatusAction, a regular domain action. The tool is just an AI-facing adapter over code we already had.

Calling the agent from an action is a couple of lines.

$agent = new ThereThereAgent(
    workspace: $workspace,
    user: $user,
    contextTicket: $agentChat->contextTicket,
    conversationHistory: $agentChat->getConversationHistoryExcludingLatest(),
);

return $this->streamingService->stream($agent, $messageForAi, $agentChat);

We hand the agent off to our streaming service, which turns the SDK's response stream into events the frontend can consume. That's another post.

TODO: short video of the Ask There There agent picking up a message, calling a tool like changing a ticket status, and replying.

In closing

The Laravel AI SDK has hit a sweet spot for our use case. The agent and tool abstractions are simple, the Blade-backed prompt is a joy to edit, and the typed schema means the model rarely mangles its arguments. We've barely scratched the surface of what it can do.

You can read more in the Laravel AI SDK repo. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

There There, the helpdesk we're building, is built exactly like that. Tickets, messages, members, custom sidebar sections, all of it crosses the bridge. We'd go insane maintaining those types by hand. So we don't. There There is in private beta right now, and you can apply for early access at there-there.app.

Two Spatie packages make this painless. spatie/laravel-data shapes outgoing payloads into typed PHP classes, and spatie/laravel-typescript-transformer turns those classes into TypeScript definitions at build time. Let me show what that looks like in practice.

Keeping types in sync

A payload starts life as a Data class. Here's our MemberData, which we send down every time we render the member detail page.

use Spatie\LaravelData\Data;
use Spatie\TypeScriptTransformer\Attributes\TypeScript;

#[TypeScript]
class MemberData extends Data
{
    public function __construct(
        public int $id,
        public string $ulid,
        public string $name,
        public string $email,
        public ?string $avatar_url,
        public WorkspaceMemberRole $role,
        public string $joined_at,
        public bool $restricted_channel_access = false,
    ) {}

    public static function fromPivotUser(User $user): self
    {
        return new self(
            id: $user->id,
            ulid: $user->ulid,
            name: $user->name,
            email: $user->email,
            avatar_url: $user->getAvatarUrlWithFallback(),
            role: WorkspaceMemberRole::from($user->pivot->role),
            joined_at: $user->pivot->created_at->toIso8601String(),
            restricted_channel_access: (bool) $user->pivot->restricted_channel_access,
        );
    }
}

The #[TypeScript] attribute is the opt-in. Any PHP class that carries it is picked up by the transformer. The constructor properties become the TypeScript type, including the enum WorkspaceMemberRole, the nullable string, and the boolean with a default.

The transformer itself is a regular Laravel package with a config file. Here's the relevant part of ours.

return [
    'auto_discover_types' => [
        app_path(),
    ],

    'transformers' => [
        SpatieStateTransformer::class,
        EnumTransformer::class,
        DataTypeScriptTransformer::class,
        DtoTransformer::class,
    ],

    'default_type_replacements' => [
        Carbon\Carbon::class => 'string',
    ],

    'output_file' => resource_path('js/types/generated.d.ts'),
];

Three things worth knowing. auto_discover_types scans app/ for any annotated class. transformers handles data classes, DTOs, enums, and Spatie state machines. default_type_replacements lets you swap PHP types for their TypeScript equivalents, which is how every Carbon date becomes a plain string on the frontend.

When the transformer runs, it writes resources/js/types/generated.d.ts. For our MemberData, the output looks like this.

declare namespace App.Domain.Settings.Data {
    export type MemberData = {
        id: number;
        ulid: string;
        name: string;
        email: string;
        avatar_url: string | null;
        role: App.Domain.Workspace.Enums.WorkspaceMemberRole;
        joined_at: string;
        restricted_channel_access: boolean;
    };
}

The namespace mirrors the PHP namespace. The property shapes line up with the constructor. Enums are cross-referenced to their own generated types, so renaming an enum case in PHP propagates to every TypeScript caller.

You could regenerate this file manually with php artisan typescript:transform, but we wire it into Vite so it happens whenever a data class or enum changes.

handleHotUpdate({ file }) {
    if (isServe && file.endsWith('.php') && (file.includes('/Data/') || file.includes('/Enums/'))) {
        generate();
    }
},

That snippet sits inside a small custom Vite plugin. When the dev server is running and a PHP file under Data/ or Enums/ changes, we shell out to php artisan typescript:transform and the frontend types update in place. No manual step, no stale definitions.

There's a simpler option in v3 of spatie/laravel-typescript-transformer: the package includes a built-in watch mode. After installing chokidar, run php artisan typescript:transform --watch. We're on v2.6, whose typescript:transform command has no --watch option, so the Vite plugin above handles changes for us.

Here's what that looks like in the editor. The fields from MemberData show up as TypeScript suggestions:

In closing

This setup has erased a whole category of papercut. We rename a PHP property, the TypeScript compiler lights up on every frontend caller. We add a field, it's available to autocomplete in seconds. The two sides stay honest.

You can find the packages on GitHub: laravel-data and laravel-typescript-transformer. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

This is a small pattern, but it's one of those things that makes a codebase nicer to live in. There There is in private beta right now, and you can apply for early access at there-there.app.

Exceptions that explain themselves

The conventional answer for a domain error is something like throw new InvalidArgumentException("Only notes can be deleted"). It works, the test passes, the user sees a 500 page. But then three months later you try to catch just this specific error and you can't, because InvalidArgumentException is thrown from a dozen other places.

Our pattern is one class per domain error, with a static factory method per reason. Here's the one that fires when someone tries to delete a message that isn't a note.

namespace App\Domain\Tickets\Exceptions;

use App\Domain\Tickets\Models\Message;
use Exception;
use Illuminate\Contracts\Debug\ShouldntReport;

class CouldNotDeleteMessage extends Exception implements ShouldntReport
{
    public static function onlyNotesCanBeDeleted(Message $message): self
    {
        return new self("Could not delete message id {$message->id} of type {$message->type->value}. Only messages of type `note` can be deleted.");
    }
}

Two things worth calling out. The static method name spells out the failure reason in English, which makes the throw site read like a sentence: throw CouldNotDeleteMessage::onlyNotesCanBeDeleted($message). And the method takes the typed context as a parameter, which makes the message impossible to build without the relevant data.

Here's the throw site, inside our DeleteNoteAction.

class DeleteNoteAction
{
    public function execute(Message $message): void
    {
        if (! $message->isNote()) {
            throw CouldNotDeleteMessage::onlyNotesCanBeDeleted($message);
        }

        // ... delete the note
    }
}

When the throw site is this readable, you don't need a comment explaining what went wrong. The exception name, the method name, and the message all agree with each other.

The ShouldntReport marker is a small Laravel convention. We implement it so these exceptions don't end up in our error tracker. They're expected domain errors, not bugs, and they surface through user action. Keeping them out of the error log makes the signal there actually signal.

If a domain has several failure modes, we add methods. Our CouldNotInviteMember class has half a dozen static factories, one per reason the invitation couldn't be sent. Every throw site is a one-liner that tells you exactly what went wrong.

In closing

Custom exceptions look like over-engineering until the first time you need to catch one. Then they look like the obvious move. And because every exception class is tiny, they don't add much weight to the codebase.

If you'd like to see how the rest of There There is put together, we're in private beta right now and you can apply for early access at there-there.app.

A quick reminder on our angle. After two decades of running our own customer support, we wanted a helpdesk where AI makes support agents faster, not one that tries to replace them. The human reads, thinks, and directs. The model drafts and retrieves in real time while they watch. There There is in private beta right now, and you can apply for early access at there-there.app.

Streaming from Laravel to React

The obvious way to hand an LLM response to the browser is to wait for it to finish, then render the whole thing. That's easy, but it makes the agent feel sluggish. What we actually want is for the reply to appear word by word, and for the agent's own reasoning (like which tool it's calling) to be narrated along the way.

The Laravel AI SDK exposes each step of a conversation as a typed event. We iterate over that stream and emit newline-delimited JSON for the frontend, one line per event.

Here's the core of our AgentStreamingService.

public function stream(Agent&HasTools $agent, string $message, AgentChat $chat): StreamedResponse
{
    return response()->stream(function () use ($agent, $message, $chat): Generator {
        yield from $this->streamAgent($agent, $message, $chat);
    }, 200, [
        'Content-Type' => 'application/x-ndjson',
        'Cache-Control' => 'no-cache',
    ]);
}

private function streamAgent(Agent&HasTools $agent, string $message, AgentChat $chat): Generator
{
    set_time_limit(120);

    $fullContent = '';
    $toolCalls = [];

    foreach ($agent->stream($message) as $event) {
        if ($event instanceof ToolCall) {
            yield json_encode(['type' => 'tool_call', 'tool_name' => $event->toolCall->name])."\n";
        }

        if ($event instanceof TextDelta) {
            $fullContent .= $event->delta;
            yield json_encode(['type' => 'delta', 'content' => $event->delta])."\n";
        }

        if ($event instanceof ToolResult) {
            $toolCalls[] = [
                'name' => $event->toolResult->name,
                'arguments' => $event->toolResult->arguments,
                'result' => $event->toolResult->result,
            ];
        }
    }

    $chat->messages()->create([
        'role' => MessageRole::Assistant,
        'content' => $fullContent,
        'tool_calls' => $toolCalls ?: null,
    ]);

    yield json_encode([
        'type' => 'done',
        'html' => $this->parser->buildFinalHtml($fullContent),
    ])."\n";
}

A few things are worth calling out. response()->stream() accepts a generator and flushes each yield to the client immediately, which is the whole trick for server-pushed progress. We type the events (delta, tool_call, done) so the frontend can tell a text chunk apart from a tool invocation. And we persist the finished message to the database in the same pass. The stream itself is the source of truth, and the persisted copy is what we rehydrate the next time the user opens the chat.

On the frontend we consume the stream with plain fetch. No library needed, no SSE framing to worry about. Here's the hook we use, trimmed to the bits that matter.

const response = await fetch(sendUrl, {
    method: 'POST',
    headers: { ...csrfHeaders(), 'Content-Type': 'application/json' },
    body: JSON.stringify(buildBody(text, html)),
    signal: controller.signal,
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop() ?? '';

    for (const line of lines) {
        processLine(line);
    }
}

if (buffer.trim()) {
    processLine(buffer);
}

The buffer pattern is the only thing you have to get right. A single reader.read() call can hand you a partial line, a whole line, or several lines at once. We split on \n, keep the last (possibly incomplete) chunk in buffer, and flush it at the end. Every completed line is one of our events.

Dispatching each event to state is a short switch.

if (event.type === 'tool_call') {
    setMessages((prev) => updateLastStreaming(prev, {
        toolStatus: formatToolName(event.tool_name),
    }));
} else if (event.type === 'delta') {
    setMessages((prev) => updateLastStreaming(prev, (last) => ({
        content: last.content + event.content,
        toolStatus: null,
    })));
} else if (event.type === 'done') {
    setMessages((prev) => updateLastStreaming(prev, {
        html: event.html,
        isStreaming: false,
    }));
}

When a tool_call arrives, we show a small "Looking up tickets" label above the still-streaming reply. When deltas start landing, we clear the tool label and append to the message content. When done arrives, we swap in the server-rendered HTML and flip the streaming flag off. The whole round-trip feels like the agent is typing in front of you.

TODO: short video of the Ask There There agent replying to a question, with a "Looking up tickets" label appearing briefly and then the tokens streaming in.

In closing

There are heavier ways to do this. Server-sent events, websockets, a full streaming library on each side. For a chat interface, none of it is necessary. A generator on the server, NDJSON on the wire, and a small buffer loop on the client is about a hundred lines end to end, and it behaves exactly like a proper streaming LLM chat should.

You can read more about the events the SDK emits in the Laravel AI SDK repo. And if you'd like to try There There yourself, we're in private beta right now and you can apply for early access at there-there.app.

That post ended with a promise that we'd find more uses for Jev. Here are two we have since added to There There: smart conditions for workflows, and automatic assignment to a team or person.

Describing a workflow condition in plain language

Workflows already let you match a subject, sender, or message body against text. That works when the words are predictable. A customer asking for a refund can also write "I was charged twice", "Could you reverse this payment?", or something in another language. A list of keywords gets long quickly.

With a smart condition, you describe what should match. Here's one of the example workflows in our local app:

The condition says "The customer asks for a refund or to cancel a payment." When it matches, the workflow adds a private note asking us to review the payment. The note is fixed text. We turn the description into a Jev Boolean question:

public static function question(string $description): Boolean
{
    return new Boolean(
        "The incoming message matches this workflow description: {$description}",
        [
            'true' => 'The incoming message fits the description.',
            'false' => 'The incoming message does not fit the description.',
        ],
    );
}

This question joins the spam and auto-reply questions from the first post in the same inbound classification request. The answer is stored with the message, and the workflow reads its probability from there. It doesn't call Jev again when the workflow runs.

The editor also lets you try a sample email or an existing ticket and see the score before you enable the workflow. Here, a customer asking about a duplicate charge gets a strong match:

Only incoming email is checked. Jev gets the subject, sender, and message text, not the whole ticket history.

Letting Jev choose who should handle a ticket

When a ticket comes in, we need to get it to the right person. At Spatie, one person might handle billing questions, while someone else is better placed to help with a browser issue or a design question. We know who can handle what. The hard part is translating every way a customer might describe a problem into fixed routing rules.

In a workflow, you select the people Jev may choose from and add a short description of what each handles. Here, Dries handles frontend issues, Jef takes billing questions, Jimi handles design, and Zuzana picks up general support:

We ask Jev a Choice question with the people selected in the workflow. It chooses from that list, with one extra option for when nobody fits:

$response = Classification::of($state)
    ->questions(['assignee' => new Choice(
        $instructions,
        [
            ...collect($options)
                ->map(fn (Team|User $assignee) => $candidates->descriptionFor($assignee))
                ->all(),
            'None of these' => 'None of the others clearly fits this ticket.',
        ],
    )])
    ->timeout(10)
    ->classify();

We only assign when Jev has a clear favorite. Sending a vague ticket to the wrong person creates an unnecessary hand-off, so when nobody clearly fits, the action makes no change. Another workflow can pick it up later.

Before asking Jev, we remove disabled members and anyone who can't access the ticket's channel. The same approach can assign a team, with its own list and descriptions. Team and person assignment are separate actions, so choosing a team doesn't restrict which people Jev can choose from. Spam and automatic replies are skipped before either assignment action runs.

In closing

These additions make our workflows a lot more flexible. We can describe what we're looking for in plain language and route matching tickets to the people best placed to help. The workflow still decides what happens next.

If you missed the first part, read how we detect spam and auto-replies with Jev. You can also read the workflow conditions and workflow actions docs, or try There There.

How Jev is different from an LLM

Jev is made by TypeSafe. An LLM generates text: you ask it something, it writes an answer, and if you want structured data back you have to ask for it and hope. Jev doesn't generate anything. You give it some state and a question, and it gives you back a number.

TypeSafe calls these System One models. They read natural language like an LLM does, but instead of writing a reply they pick between answers that you define up front. The probabilities are calibrated, which means they're trained against real outcomes, so across a batch of answers a 0.9 should be right about nine times out of ten.

In practice that means no prose to parse, and no prompt asking the model to please respond with valid JSON.

The Syntax folks made a video explaining it:

Noul, Choice and Score

You define what the answers can be using one of three question types.

A Noul is a yes or no question. The answer is a single number: the probability that the answer is yes. Here's how you ask one:

use Laravel\Ai\Classification;
use Laravel\Ai\Classification\Boolean;

$result = Classification::of('I have asked three times now. Can I please talk to a real person?')
    ->question('urgent', new Boolean('Does this request need an immediate response?'))
    ->classify();

$result['urgent']->probability;            // 0.94
$result['urgent']->isTrue(threshold: 0.8); // true

Notice that you get back 0.94 instead of true. You decide where the cutoff is, which means you can set a different one per question.

A Choice picks one option out of a set that you name. Here's an example:

use Laravel\Ai\Classification\Choice;

$result = Classification::of('My card was charged twice for order A-104. Please refund the duplicate.')
    ->question('department', new Choice('Which team should handle this request?', [
        'billing' => 'Payments, invoices, and refunds',
        'technical' => 'Bugs, outages, and integrations',
        'sales' => 'Pricing, plans, and upgrades',
    ]))
    ->classify();

$result['department']->choice;                   // 'billing'
$result['department']->probabilityOf('billing'); // 0.87
$result['department']->confidence;               // 0.82

Next to the option it picked, you also get a probability for every option, and a confidence score that tells you how concentrated those probabilities were.

A Score rates something against levels that you describe yourself. You could ask how frustrated a customer is, where 0 is calm, 1 is frustrated and 2 is very angry. The answer can land between two levels, so a 1.4 is a perfectly good answer.

The state doesn't have to be a string. When a decision depends on more than one thing, you can pass an array so every part has a name:

Classification::of([
    'subject' => 'Duplicate charge',
    'message' => 'My card was charged twice for order A-104.',
    'order' => ['id' => 'A-104', 'charges' => [49, 49]],
    'refund_policy' => 'Duplicate charges are eligible for a refund.',
])->question('refund_due', new Boolean('The policy entitles this customer to a refund.'))
    ->classify();

That's still one state, even though it holds a message, an order and a policy.

You configure Jev like any other provider in config/ai.php, with a TYPESAFE_API_KEY in your env file.

The problem we wanted to solve

You might have noticed that we launched There There yesterday as well, our new helpdesk. A lot of the mail that arrives in a helpdesk isn't from a customer. Out-of-office replies, bounces, subscription confirmations, DMARC reports. You don't want those in your inbox, and you don't want to pay an LLM to write a title and a summary for each one.

Some of that mail says what it is in the headers. Auto-Submitted, an empty return path, a sender called mailer-daemon. Checking those costs nothing, so we do that first.

Plenty of mail servers don't set those headers. For those we had a list of subject prefixes: Automatische Antwort, Réponse automatique, Out of office, in fifteen languages. Nine more for bounces. On top of that, rules so that a customer asking a question about auto-replies didn't get treated as one.

Every time we found mail that the list missed, we added another string to it.

Replacing the list

The header checks still run first. Everything they can't answer goes to Jev.

We describe each question once, as a case on an enum that also carries its own threshold. That way adding a fourth question is a single case instead of an edit in four files.

enum InboundJudgement: string
{
    case IsAutoResponse = 'is_auto_response';
    case IsBounce = 'is_bounce';
    case IsSpam = 'is_spam';

    public function question(): Boolean
    {
        return match ($this) {
            self::IsAutoResponse => new Boolean(
                'A system sent this mail on its own, rather than a person choosing to write to us.',
                [
                    'true' => 'Sent on a trigger with no human involved at send time: out-of-office
                        notices, delivery reports, ticket acknowledgements, subscription
                        confirmations, digests and alerts. Wording composed in advance still counts',
                    'false' => 'A person sat down and sent this. Still false when a contact form or
                        chat widget wrapped their words in a template and added lines such as Name,
                        E-mail or Subject',
                ],
            ),
            self::IsSpam => new Boolean(
                'This mail is unsolicited bulk mail, a scam, or phishing rather than a genuine
                    message from a customer.',
                [
                    'true' => 'Cold sales outreach, marketing blasts, scams, phishing, or anything
                        the recipient never asked for',
                    'false' => 'A real person writing about the product, their account, or their own
                        support request, however brief or badly written',
                ],
            ),
            // ...
        };
    }

    public function threshold(): float
    {
        return match ($this) {
            self::IsAutoResponse => 0.75,
            self::IsBounce, self::IsSpam => 0.9,
        };
    }
}

Those true and false descriptions are optional, but I'd recommend writing them. They do more work than the question above them.

All the questions the headers couldn't answer go out in one request. Jev reads the state once and answers them in parallel, and you only pay for input tokens, so asking three questions costs the same as asking one. Here's the action that does it:

public function execute(Message $message, Ticket $ticket, Workspace $workspace): void
{
    $judgements = array_filter(
        InboundJudgement::cases(),
        fn (InboundJudgement $judgement) => ! $judgement->settledByHeaders($message),
    );

    if ($judgements === []) {
        return;
    }

    try {
        $response = Classification::of([
            'subject' => $ticket->subject,
            'from_name' => $message->author_name,
            'from_email' => $message->author_email ?? $ticket->contact?->email,
            'message' => Str::limit($message->body_text, 10_000),
        ])
            ->questions($this->questionsFor($judgements))
            ->timeout(10)
            ->classify();

        $verdicts = $this->verdicts($judgements, $response);
    } catch (Throwable $exception) {
        Log::warning('Could not classify an inbound message.', [
            'message_id' => $message->id,
            'error' => $exception->getMessage(),
        ]);

        return;
    }

    $message->updateQuietly([...$verdicts, 'classification' => $response->answers]);
}

There are two things in there I'd suggest copying. The whole call sits in a try block that logs the problem and moves on, because a classification is a nice to have and it shouldn't be able to break the mail pipeline it's helping. And we truncate the message, because an inbound mail can be megabytes long and nothing past the first part of it changes what the mail is.

Turning the answers into booleans is where each question's own threshold is applied. We store the raw probabilities next to them, so we can change a threshold later and see what it would have done:

private function verdicts(array $judgements, ClassificationResponse $response): array
{
    $verdicts = [];

    foreach ($judgements as $judgement) {
        $answer = $response->answer($judgement->value);

        $verdicts[$judgement->value] = $answer->isTrue($judgement->threshold());
    }

    return $verdicts;
}

Those verdicts are stored on the message. When a customer builds a workflow in There There with an "Is spam" condition, checking that condition reads a single column and doesn't call Jev at all.

In closing

I like that Jev does one small thing. It gives you a number and leaves the rest of the decisions in your own code, where you can read them and write tests for them.

It's also fast and cheap enough that you don't really have to think about it. Classifying a mail with three questions at once takes 639ms, and we get around 48 per second when we run them in parallel. We didn't spend any time tuning that, so I'm sure you could get more out of it, but for what we're doing it's fast enough. Jev costs $0.042 per million input tokens and output tokens are free, which for us comes down to four hundredths of a cent per mail, or about 36 cents a month.

We have a list of other places where we want to use this in There There, and in our other products. Expect more Jev powered features soon.

If you want to read more, there are the TypeSafe docs and the Laravel AI SDK. And if you'd like to see the spam detection at work, you can try There There.