Skip to content

AI engines

Set up Cloudflare Clairic directly or through meirdick/laravel-cf-workersai, or use a chat model through laravel/ai.

Updated

An AI engine is optional. It adds chips for words that the rules did not explain. The AI never writes SQL. The normalizer checks every chip. See How it works.

System One with direct credentials

Set your Cloudflare account ID and an API token in .env.

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token

With SEARCH_CHIPS_ENGINE=auto (the default), the package then uses System One. The package calls the Cloudflare REST API at https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/clairic.

Env variable Config key Default
CLOUDFLARE_ACCOUNT_ID ai.cloudflare.account_id none
CLOUDFLARE_API_TOKEN ai.cloudflare.api_token none
SEARCH_CHIPS_CF_MODEL ai.cloudflare.model @cf/cloudflare/clairic
SEARCH_CHIPS_CF_URL ai.cloudflare.url none

Set SEARCH_CHIPS_CF_URL to the full endpoint to send the request through AI Gateway or a proxy.

System One through meirdick/laravel-cf-workersai

If meirdick/laravel-cf-workersai (1.3 or later) is installed and config/ai.php has a provider for it, System One sends its request through that package. The package adds retries, failover and AI Gateway routing. You then need no keys in this package’s config.

composer require meirdick/laravel-cf-workersai

The package looks for the first provider in ai.providers that uses the workers-ai driver and has a key. To name a provider yourself, set SEARCH_CHIPS_CF_PROVIDER.

Set the transport with SEARCH_CHIPS_CF_TRANSPORT.

Value Behavior
auto (default) Use meirdick/laravel-cf-workersai when it is installed and has a provider. Otherwise call the REST API with the keys above.
direct Always call the REST API with the keys above.

Tuning

These keys are under ai.cloudflare. They have no env variable.

Key Default Meaning
presence_threshold 0.6 An answer needs 1 - p_null at or above this value.
confidence_threshold 0.6 An answer below this value is dropped.
suggest_below 0.85 An answer below this value becomes a suggested chip.
guess_p_null 0.65 A confident guess with p_null at or below this value also becomes a suggested chip.
max_fields 24 The most fields the package sends.
check_names true Keep a name with no cue word as a relation chip only when a related row has that name.
match_values true Ask a Clef decision model which allowed value an unknown word means.
match_model @cf/cloudflare/clef-flash The decision model for that question.
match_url null Full endpoint for that call. Set it when url is set.
match_threshold 0.7 The chosen value needs this probability.
timeout 8 Seconds before the request stops.

A name with no cue word

“einstein” alone can be an author or a topic. “By einstein” states the author.

  • With a cue word (by, from, with, of, for, in, at, or the field name), the relation chip stays.
  • With no cue word, the package looks for a related row with that name. This is one exists query.
  • If no row exists, there is no chip and the word stays in the keyword text.

Set ai.cloudflare.check_names to false to stop this query.

Other words for a value

Clairic copies words from the sentence. For “garden movies” it returns movies as the type, and movies is not an allowed value.

The package then asks a Clef decision model one question: which allowed value does “movies” mean, or none. This is a second request, and it runs only for a word that names no value, no plural, no label and no synonym.

  • A choice with a probability at or above match_threshold becomes the chip value: Type is Video.
  • A choice below suggest_below is a suggested chip.
  • A choice of none, or a lower probability, leaves the word in the keyword text.
  • A failed request leaves the Clairic reading as it was.

Clef knows general language. It does not know your product words. If “shows” means the value podcast in your app, add a synonym: ->synonyms(['show' => 'podcast']).

Set SEARCH_CHIPS_MATCH_VALUES=false to stop this request.

Chat engine

The chat engine uses a chat model through laravel/ai.

composer require laravel/ai
SEARCH_CHIPS_ENGINE=ai
SEARCH_CHIPS_CHAT_PROVIDER=your-provider
SEARCH_CHIPS_CHAT_MODEL=your-model

The provider must exist in your laravel/ai config. The package never uses a laravel/ai default. If laravel/ai is missing, or the provider or model is empty, the engine is not available and the package uses rules only. The timeout is ai.chat.timeout (8 seconds).

The chat engine is tested with the laravel/ai fake only. No live provider has run it. See Limits.

What the AI receives

See Security.

Parse cache

The package caches AI parses. It never caches the rules engine.

Env variable Config key Default
SEARCH_CHIPS_CACHE cache.enabled true
SEARCH_CHIPS_CACHE_STORE cache.store the default cache store
none cache.ttl 300 seconds

The cache key holds the alias, the engine class, the schema version, today’s date and the lowercase sentence. A date word such as last week therefore never goes stale. A failed AI call is not cached. Run php artisan search-chips:clear to drop cached parses.

Cost

The source has no cost figures. These facts come from the code:

  • The rules engine makes no network call.
  • The UI asks for the AI reading after the rules reading. It makes one AI request for each sentence that is not in the cache.
  • A cached sentence makes no request for the cache time.
  • With auto, a test run makes no AI request.
  • The package sends at most max_fields fields.

Check usage and billing in your Cloudflare dashboard or with your chat provider.

Next steps

Type to search…

↑↓ navigate↵ selectEsc close