---
title: "Custom engine"
description: "Add your own engine with SearchChips::extend() and the Parser contract."
---

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

# Custom engine

You can add an engine that reads the sentence in your own way. Register it by name, then select it by name.

## Register and select

```php
use Meirdick\SearchChips\Facades\SearchChips;

SearchChips::extend('mine', fn ($app) => new MyParser);
```

The closure receives the container and returns a `Parser`. Select the engine with `SEARCH_CHIPS_ENGINE=mine`, or with the `engine` option of one model.

## The Parser contract

Implement `Meirdick\SearchChips\Contracts\Parser`.

```php
use Meirdick\SearchChips\Contracts\Parser;
use Meirdick\SearchChips\Data\ModelSchema;
use Meirdick\SearchChips\Data\ParsedQuery;

class MyParser implements Parser
{
    public function available(): bool
    {
        return true;
    }

    public function parse(string $query, ModelSchema $schema): ParsedQuery
    {
        return new ParsedQuery([
            [
                'field' => 'type',
                'operator' => 'equals',
                'value' => 'podcast',
                'source' => 'ai',
                'spans' => [['start' => 0, 'end' => 4]],
            ],
        ], null, null, 'mine');
    }
}
```

| Method | Meaning |
| --- | --- |
| `available(): bool` | Return `false` when the engine cannot run, for example when credentials are missing. The package then uses rules only. |
| `parse(string $query, ModelSchema $schema): ParsedQuery` | Return raw filters for the schema. |

Treat the sentence as untrusted input. Stay within the fields of the schema. The normalizer does the final check.

## ParsedQuery

The constructor takes: `filters`, `leftover` (default `null`), `sort` (default `null`), `engine` (default `'rules'`), `warnings`, `consumed` and `keywords`.

Each raw filter is an array. The keys are `field`, `operator`, `value`, `negated`, `confidence`, `spans`, `unit`, `suggested`, `explicit`, `id`, `label` and `source`.

- A filter with `'source' => 'ai'` or `'source' => 'system-one'` must have valid `spans`. A span is a byte offset pair, `['start' => 0, 'end' => 4]`, into the sentence. The normalizer drops a filter of these sources that has no usable span.
- `operator` must be valid for the field kind. See [Operators](https://auto-search-chips.mdick85.workers.dev/docs/reference/operators/).
- Set `suggested` to `true` for a chip that the user must accept.

## How the package uses it

A custom engine works like an AI engine. The rules engine runs first. Your engine then adds chips, under the merge policy in [How it works](https://auto-search-chips.mdick85.workers.dev/docs/concepts/how-it-works/). If your engine throws an `EngineUnavailableException`, the rules chips stand.

The package caches the result of an AI engine. See [AI engines](https://auto-search-chips.mdick85.workers.dev/docs/guides/ai-engines/#parse-cache).

## Next steps

- See the engines that ship with the package in [Engines](https://auto-search-chips.mdick85.workers.dev/docs/concepts/engines/).

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