# Search behaviour

The website filters recipes in the browser with [Fuse.js](https://fusejs.io) 7.4.2. The MCP server
does not approximate that: it ports the matcher and is tested against golden outputs produced by
the website's own JavaScript. For the same query and filters, both return the same recipe set.

## The pipeline

1. **Exact filters first.** `tag` and `easy_only` are applied in catalog order. Tags are compared
   by identity, exactly like the website's `===`.
2. **Empty query** returns the filtered catalog, in website order, with strategy `catalog` and no
   score.
3. **Tokenize.** The query is lowercased and split on whitespace.
4. **Keep significant tokens.** A token counts when it is at least **two UTF-16 code units** long
   and is not in the website's Spanish stopword list (`de`, `la`, `el`, `en`, `y`, `con`, `para`,
   `que`, …). The UTF-16 detail matters: an emoji counts as two units, because JavaScript counts
   code units, not code points.
5. **No significant token** (for example a query of only stopwords) falls back to a **substring**
   match: any token contained in the name, a tag or a normalized ingredient keeps the recipe.
   Strategy is `substring`.
6. **Otherwise every significant token must match.** Each token is searched independently with a
   per-token threshold, and the result sets are intersected — a recipe must match all of them.
   Strategy is `fuzzy`. A query such as `papas fritas` requires both words, which is why it can
   legitimately return nothing.

### Thresholds

The threshold grows with token length, capped at 0.45:

```text
threshold = min(0.1 + (length_in_utf16_units - 1) * 0.035, 0.45)
```

So `pan` needs a closer match than `chocolate`. This is the website's own formula, not a tuning
knob of this project.

### Fuse options

These values are fixed to the website's index:

| Option | Value |
| --- | --- |
| `includeScore` | `true` |
| `threshold` | per token, see above |
| `location` | `0` |
| `distance` | `100` |
| `ignoreLocation` | `false` |
| `ignoreFieldNorm` | `false` |
| `fieldNormWeight` | `1` |
| `minMatchCharLength` | `1` |
| `findAllMatches` | `false` |
| `maxPatternLength` | `32` (longer patterns are chunked) |

Keys and weights are the website's: `name` weight 2, `tags` 1.5, `cleaned_ingredientes` 1. Text is
folded to its base letters first, so `papa` matches `papá` and `Jamon` matches `Jamón` — but
identity comparisons such as tag filters keep the original spelling.

### Ordering and paging

- `sort: "relevance"` orders by ascending combined score, with catalog order as the tie-break.
- `sort: "catalog"` keeps website order, which is what the site itself shows.
- `limit` is 1–50 and `offset` starts at 0. The two are independent of the website's fixed page
  size of six.
- `site_search_url` becomes a real website page only for catalog order. With relevance order it
  points at the start of the result set, because the website has no relevance sort.

The matched set is identical in both orders; only the presentation changes.

## Where this diverges from the website

Two behaviours are deliberate and documented here so they never surprise you:

1. **Unknown tag is an error.** The website silently shows zero results when a tag does not exist.
   The server raises a tool error with up to five close matches, because silence teaches a model
   nothing and reads like "no recipes".
2. **Unknown ingredient is an error.** Same reasoning: `find_recipes_by_ingredients` validates
   every name against the catalog vocabulary and suggests close matches. A valid ingredient that
   genuinely appears in no recipe still returns a normal empty result.

Both divergences only affect invalid input; for valid input the results follow the website.

## How parity is proven

`tests/test_site_parity.py` replays **100 recorded search cases** and **12 ingredient cases**
through the tools and compares the recipe sets with the goldens in `tests/fixtures/goldens/`. The
goldens are not hand-written: `tools/goldens.mjs` imports the website's own
`src/utils/index.js` and `src/utils/queCocino.js`, runs them against the same dataset and records
the output, together with the Fuse version, recipe count, dataset hash and site commit.

Regenerate them after a website change (requires a checkout of `al_horno_con_papa` and Node):

```bash
ALHORNO_SITE_DIR=../al_horno_con_papa node tools/goldens.mjs
ALHORNO_SITE_DIR=../al_horno_con_papa node tools/goldens.mjs --check
```

`--check` exits non-zero when the committed goldens no longer match the website, which is the
signal to review the difference instead of guessing.

## Examples

| Query | Strategy | Matches | Why |
| --- | --- | --- | --- |
| `` (empty) | `catalog` | 246 | Listing mode. |
| `papas fritas` | `fuzzy` | 0 | No recipe matches both tokens. |
| `torta de chocolate` | `fuzzy` | several | `de` is a stopword; `torta` and `chocolate` must both match. |
| `de la` | `substring` | several | Only stopwords left, so substring mode runs. |
| `fideos` | `fuzzy` | 7 | Matches names and ingredients. |

!!! tip "Use `list_tags` before filtering"

    `tag` is an exact, case-sensitive match. `pollo` is not `Pollo`. One `list_tags` call costs
    little and removes a whole class of failed calls.
