/ blog v2026.11
Back to blog
GET /v1/posts/clorian-confidence-aware-typed-decisions-for-any-laravel-model 200 OK · 9 min read

Clorian: Confidence-Aware Typed Decisions for Any Laravel Model

The Clorian logo, a hexagonal C around a four-point star, for confidence-aware typed decisions in Laravel

"The parcel arrived crushed, and so did the replacement. I'd like my money back." Should that refund go straight through, or does a manager need to see it? Your app probably answers that question today with a person reading every request, or with a regex on the word "replacement" that is wrong half the time.

A model can read the text and answer. The hard part is knowing which of its answers to trust. That is the problem I built Clorian for Laravel to solve. Clorian (KLOR-yan) is Welsh for scales (as in weighing): every answer is weighed against thresholds you set, confident ones apply themselves, unsure ones wait for a person, and every human decision is recorded so you can see, with evidence, when an answer has earned more trust.

Decisions hiding in text

Most apps have more of these decisions than you would think. They all have the same shape: some free text arrives on a model, and the app has to pick from a small set of options.

  • Support tickets: which team, how urgent, does a person need to reply
  • Marketplace listings: which category, might it be prohibited
  • Reviews and comments: spam or not, what the customer is unhappy about
  • Refunds and claims: what the reason is, does a manager need to see it
  • Contact forms: sales, support or spam, answered while the visitor waits
  • Content tagging: topic and audience for posts, documents or products

Clorian asks those questions with Jev, TypeSafe's typed decision model. Jev does not write text. You give it the content and a set of typed questions, and it returns a probability for every option of every question, in one call. That is exactly what you need to make a decision you can defend.

Questions, probabilities and two thresholds

A policy declares the questions, what to use when an answer cannot be trusted, and what to do with the result. Here is the refund example:

use Illuminate\Database\Eloquent\Model;
use Phoenix1331\Clorian\Policies\Policy;
use Phoenix1331\Clorian\Questions\Question;
use Phoenix1331\Clorian\Resolution\Answers;

class RefundTriage extends Policy
{
    public function questions(): array
    {
        return [
            Question::choice('reason', [
                'damaged' => 'The item arrived broken or crushed',
                'late' => 'The order arrived late or not at all',
                'changed_mind' => 'The customer no longer wants it',
            ])->instructions('Why does the customer in `content` want a refund?'),

            // A wrong "no" costs money, so be sure before acting alone.
            Question::boolean('needs_manager')->accept(0.80),
        ];
    }

    public function defaults(): array
    {
        return ['reason' => null, 'needs_manager' => true];
    }

    public function apply(?Model $subject, Answers $answers): void
    {
        $subject?->update([
            'reason' => $answers->get('reason'),
            'route' => $answers->get('needs_manager') ? 'manager' : 'auto',
        ]);
    }
}

Every answer is checked against two thresholds. At or above accept (0.90 unless you say otherwise) it is applied. Between review (0.60) and accept, it waits for a person and the default applies in the meantime. Below review it is unresolved: the default applies and the answer is kept for the statistics. Reaching a threshold counts.

Notice the default for needs_manager is true. When Clorian cannot trust an answer, or Jev is down, the policy's defaults apply, so make them the safe choice.

Some mistakes cost more than others

Thresholds can be set per question and per option. Auto-accepting "critical" urgency on a support ticket wakes someone up at 3am, so that one option can always go to a person while "low" is accepted sooner:

Question::choice('urgency', ['low', 'normal', 'high', 'critical'])
    ->option('critical', fn (ThresholdOverrides $o) => $o->alwaysReview())
    ->option('low', fn (ThresholdOverrides $o) => $o->accept(0.75)),

Booleans are symmetric: the answer is true at a probability of 0.5 or more, and its confidence is whichever side won. A confident "no" can be accepted just like a confident "yes".

Weigh the model, not the request

You attach a policy to a model with an attribute and a trait. That is the whole integration:

use Phoenix1331\Clorian\Attributes\Weigh;
use Phoenix1331\Clorian\Concerns\HasWeighings;

#[Weigh(RefundTriage::class, fields: ['reason_text'])]
class RefundRequest extends Model
{
    use HasWeighings;
}

The trait registers Clorian's own model listener, so there is nothing else to wire up. When a refund request is created, or one of its #[Weigh] fields changes, Clorian queues a job once the save commits. A rolled-back transaction never reaches Jev, and content that has not changed since its last successful weighing is never sent twice. The job redacts the fields (emails, phone numbers and long digit runs by default), asks Jev every question, checks the answers against their thresholds, stores the lot and calls your apply().

Hooking into model events rather than middleware matters. Content arrives from queued jobs, API imports, Livewire components and console commands, not just web forms, and all of it is weighed. For data with no model, there is a synchronous call with a two second timeout that falls back to the defaults, so a visitor is never left waiting:

$weighing = Clorian::now(ContactIntent::class, $request->message);

if ($weighing->accepted('intent', 'account_access')) {
    return redirect()->route('help.password');
}

Where your code goes

  • apply() changes state on the model. Clorian calls it after every weighing and again after every review
  • Event listeners handle side effects such as emails or paging someone. They are optional: Clorian fires AnswerAccepted, AnswerNeedsReview, AnswerReviewed and WeighingFailed after the save commits, carrying ids and values, never the content
  • Your own screen lists what needs reviewing and calls Clorian::review(). Clorian is headless

Because apply() runs more than once, make it set values rather than do things. Setting a route twice changes nothing. Sending an email twice annoys a customer.

Let the reviews set the thresholds

A reviewer upholds an answer, overturns it to the right option, or marks it missed when no option fits. apply() runs again with their decision in place:

use Phoenix1331\Clorian\Reviews\ReviewAction;

Clorian::review($answer, ReviewAction::Overturned, 'damaged', $request->user());

Every answer stores the thresholds it was judged by, so tuning later never rewrites history. Over time clorian:stats shows, per question and option, how often people agreed with Jev in each confidence band. Once enough reviews from a band upwards are upheld at the target rate, 30 reviews at 95% by default, it suggests accepting from there, and clorian:tune applies it after showing the thresholds before and after.

A suggestion rule that cannot be fooled by its neighbours

My first two attempts at the suggestion rule were both wrong, and the tests showed it. Checking each band on its own needed 30 reviews in a single band, which low-volume options rarely reach. Pooling every review above an edge suggested 0.60 when the only evidence sat at 0.95, and let a weak band hide between two strong ones. The rule that shipped walks down from the top band, only suggests an edge whose own band meets the target, and stops at the first reviewed band that does not. A band that is upheld half the time can never be accepted on the strength of the bands around it.

clorian:tune also warns you about a precedence trap. A tuned threshold for a whole question beats the policy's per-option settings, so tuning "urgency" to accept at 0.80 would quietly start auto-accepting "critical". The command names the option and tells you how to keep it going to a person.

What the test app taught me

I built a Laravel 13 app with 40 realistic support tickets, weighed against live Jev, and a seeded reviewer, then clicked through it in a browser. It found things 576 unit tests had not:

  • Jev reads almost every ticket as needing a person: 30 accepted, but 5 of the 9 the reviewer checked were overturned. That is the calibration loop doing its job, not a bug
  • spam had no category in the ticket policy, so "You have won a £500 gift card" was confidently accepted as billing. The stats made the gap obvious; a real policy adds a spam option
  • the package registered its commands only when running in the console, so Artisan::call('clorian:tune') from a web request failed. Registering commands costs nothing per request, so the guard went
  • running the installer twice published the migrations again under new timestamps, and the next migrate failed. It now copies only migrations the app does not have
  • a refused connection chained Guzzle's exception, which holds the whole request, Authorization header and content included, for any error reporter to record. A security test that walks every object an exception can reach caught it

CI added two more lessons: MySQL re-sorts JSON object keys, so never assert key order, and PHP 8.5 warns when NAN is turned into a string, which exposed that four range checks silently accepted NAN because every comparison with NAN is false.

Try it

Clorian 0.1.0 is on Packagist and needs PHP 8.3+ and Laravel 12 or 13. Install it, then run the installer, which publishes the config and migrations, asks whether to weigh models queued or sync, and runs migrate:

composer require phoenix1331/laravel-clorian
php artisan clorian:install

Add your TypeSafe key to .env and check it with one sample call. clorian:ping reports the Jev version that answered: pin JEV_MODEL to it, because jev-latest moves without notice and a new version invalidates your calibration.

JEV_API_KEY=your-key
JEV_MODEL=jev-1.14.0
CLORIAN_MODE=queued

php artisan clorian:ping
php artisan queue:work

Then add #[Weigh] and HasWeighings to a model and write its policy. To try it without a key, set CLORIAN_DRIVER=fake: weighings still run for real, nothing leaves your app. Clorian is pre-1.0, so a minor release may include breaking changes; the changelog says what changed.

Summary

If your app makes decisions by reading text, you do not have to choose between a person reading everything and a model you cannot audit. Ask typed questions, put a threshold on every answer, make the defaults the safe choice, let a person handle the middle, and record what they decide. Then the thresholds move with evidence instead of hope.

  • one Jev call per weighing, with a probability for every option
  • thresholds per question and per option, with alwaysReview() where a mistake is expensive
  • model events rather than middleware, queued after commit or synchronous with a fallback
  • redaction before anything leaves the app, and encrypted input storage
  • calibration from real reviews, applied with a command that shows its working

Clorian is on GitHub with documentation, including an interactive version of the threshold check. It runs on Laravel 12 and 13 with a fake driver, so your tests never call Jev, and it shares its key with Jev Moderation. If you have decisions hiding in text and want a second opinion on where to start, get in touch via the contact section.