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-tokenWith 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-workersaiThe 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
existsquery. - 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_thresholdbecomes the chip value:Type is Video. - A choice below
suggest_belowis 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/aiSEARCH_CHIPS_ENGINE=ai
SEARCH_CHIPS_CHAT_PROVIDER=your-provider
SEARCH_CHIPS_CHAT_MODEL=your-modelThe 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_fieldsfields.
Check usage and billing in your Cloudflare dashboard or with your chat provider.
Next steps
- Read what the engines send in Security.
- See every key in Configuration.