---
title: "AI engines"
description: "Set up Cloudflare Clairic directly or through meirdick/laravel-cf-workersai, or use a chat model through laravel/ai."
---

> Documentation Index
> Fetch the complete documentation index at: https://auto-search-chips.mdick85.workers.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI engines

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](https://auto-search-chips.mdick85.workers.dev/docs/concepts/how-it-works/).

## System One with direct credentials

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

```dotenv
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.

```bash
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`.

```bash
composer require laravel/ai
```

```dotenv
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](https://auto-search-chips.mdick85.workers.dev/docs/limits/).

## What the AI receives

See [Security](https://auto-search-chips.mdick85.workers.dev/docs/guides/security/#what-an-ai-provider-receives).

## 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

- Read what the engines send in [Security](https://auto-search-chips.mdick85.workers.dev/docs/guides/security/).
- See every key in [Configuration](https://auto-search-chips.mdick85.workers.dev/docs/reference/configuration/).

Source: https://auto-search-chips.mdick85.workers.dev/docs/guides/ai-engines/index.mdx
