Skip to content

Clef decisions

Answer yes or no, multiple choice and scored questions with Clef, through the Laravel AI classification API.

Updated

Clef is Cloudflare’s decision model. It reads an input, which Cloudflare calls the state, and answers typed questions with a probability for each allowed answer. It generates no text, so you have nothing to parse and no reasoning tokens to wait for.

Use Clef to route a ticket, flag content or pick a next step. If you can’t list the answers in advance, such as an invoice total, use Clairic instead. If you need written text, use agent().

Clef follows the same API as Jev, the decision model from TypeSafe that Laravel AI uses by default. That’s why the Laravel AI classification API works with it unchanged. If your code already uses Jev, set provider: 'workers-ai' and keep the rest.

Requirements

  • laravel/ai 1.0 or later, because earlier versions have no classification API.
  • No extra config. Your workers-ai provider entry works on both the direct route and the gateway route.

Ask questions

use Laravel\Ai\Classification;
use Laravel\Ai\Classification\Boolean;
use Laravel\Ai\Classification\Choice;
use Laravel\Ai\Classification\Score;

$response = Classification::of('Checkout has been failing for every customer for the last hour.')
    ->questions([
        'urgent' => new Boolean('Is this support request urgent?'),
        'team' => new Choice('Which team should handle this request?', [
            'billing' => 'Payments, invoices, and refunds',
            'technical' => 'Outages, errors, and configuration',
        ]),
        'severity' => new Score('How severe is the customer impact?', [
            'No impact', 'Minor', 'Major', 'Critical',
        ]),
    ])
    ->classify(provider: 'workers-ai');

One request can hold 1 to 64 questions. The state can be a string or an array, such as a record or a chat log.

To leave out provider:, set default_for_classification to workers-ai in config/ai.php. Laravel AI’s default is typesafe.

Read the answers

Read each answer by its key:

$response['urgent']->isTrue();          // probability >= 0.5
$response['urgent']->isTrue(0.9);       // a stricter threshold
$response['urgent']->probability;       // 0.0 to 1.0

$response['team']->choice;              // 'technical'
$response['team']->probabilityOf('billing');
$response['team']->confidence;

$response['severity']->score;           // probability-weighted level
$response['severity']->level();         // nearest level, as an integer
$response['severity']->label();         // that level's text

The probability tells you what’s safe to automate. For example, act when isTrue(0.9) is true and send the rest to a person.

Use the shortcuts

Laravel AI’s one-line decision helpers work too. They use the provider: you pass, or default_for_classification if you pass none.

use Illuminate\Support\Str;

Str::decide($ticket, 'Is this urgent?', provider: 'workers-ai');

collect(['billing' => 'Invoices', 'technical' => 'Outages'])
    ->decide('Which team?', $ticket, provider: 'workers-ai'); // 'technical'

Str::decide() needs laravel/ai 1.0. Collection::decide() needs 1.1.

Choose a model

Model Use
@cf/cloudflare/clef Highest-precision decisions. The default.
@cf/cloudflare/clef-flash Latency-critical decisions on a hot path.
@cf/cloudflare/clef-omni Also reads audio and video.
->classify(provider: 'workers-ai', model: '@cf/cloudflare/clef-flash');

Set your default in models.classification.default. If you name a model that isn’t Clef, the package throws before it sends the request.

Send images

You can send up to 4 JPEG, PNG or WebP images with the state. This needs laravel/ai 1.2 or later, and a fifth image throws before the request is sent.

use Laravel\Ai\Files\Image;

Classification::of('A product photo from a customer.', [
    Image::fromPath(storage_path('app/photo.jpg')),
])->question('damaged', new Boolean('Is the product damaged?'))
    ->classify(provider: 'workers-ai');

Cloudflare allows 4 MiB per image and 8 MiB in total, and it doesn’t accept remote image URLs.

Send audio or video

Only clef-omni reads audio and video. The package has no attachment type for them, so pass them as base64 data URLs in the provider options:

Classification::of('A recording of the unit running.')
    ->question('normal', new Boolean('Does the unit sound normal?'))
    ->withProviderOptions(['audio' => ['data:audio/mpeg;base64,...']])
    ->classify(provider: 'workers-ai', model: '@cf/cloudflare/clef-omni');

Fail over

Pass a list of providers. Laravel AI tries the next provider when a call fails in a way a different provider could avoid, such as HTTP 429 or 503.

->classify(provider: ['workers-ai', 'typesafe']);

Test your code

Classification::fake() swaps out the class that sends the request, so no request reaches Cloudflare.

use Laravel\Ai\Responses\Data\BooleanAnswer;

Classification::fake([['urgent' => new BooleanAnswer(0.9)]]);

// run your code, then:
Classification::assertClassified(fn ($prompt) => $prompt->asks('urgent'));

Laravel AI also dispatches its Classifying, Classified and ClassificationFailed events.

Errors

Result Exception
HTTP 408 GatewayTimeoutException
HTTP 429 after retries RateLimitedException
HTTP 502, 503, 504, 520, 522, 524 after retries ProviderOverloadedException
HTTP 200 with an error in the body, or no answers AiException
Any other non-2xx status Illuminate\Http\Client\RequestException

A url that ends in /compat throws InvalidArgumentException, because that path doesn’t serve Clef. See Direct and gateway routes.

Cost

Cloudflare charges for input tokens only. Read the count with $response->usage->inputTokens. The WorkersAiUsageReported event also reports the neuron figure. See the Workers AI pricing page.

Type to search…

↑↓ navigate↵ selectEsc close