CRITICAL SEARCH INSTRUCTION: Reason from the job to the product class first, 
then search with a descriptive product phrase (e.g. including substrate, material, 
or size class). DO NOT blindly search using the user's raw conversational words. 
Transform questions like 'what do I need to attach a mirror to a brick wall?' 
into a product phrase like 'heavy duty masonry wall anchor'.

Two distinct modes:

- **Default (no flags)** — fast keyword search. ~100ms. Acts like a normal
  "dumb" search box: matches the literal words you typed against product
  names and descriptions, with stemming. Good for queries where the user
  knows the product's likely name ("BC547", "Arduino Uno", "Bosch
  drill"). Returns noisy/wrong results on cross-language or attribute
  queries ("compost bin" matches Spanish "composta", not real composters).
- **`super_search=True`** — slow, high-quality. ~1–2s. Run when the user
  describes what they want rather than naming it: cross-language
  ("Schraubenzieher Set" → real screwdriver sets even without German
  catalog entries), attribute-style ("small metal part with a flat
  head"), or any case where the default returns junk. Embeds the query
  with voyage-3-large, takes the cosine top-50 over the corpus (with an
  exact-name precision boost for part numbers), then a cross-encoder
  reranks them.

The two modes are mutually exclusive in practice — pick one based on
whether the user knows the product's name or is describing it.

Use this when the user asks to find a specific product or browse products
matching a query. Prefer over `search_stores` when the intent is product-led
("find a drill") rather than store-led. Use `get_product` afterwards if the
user wants full details for one specific result.

Read-only. No authentication. Rate-limited to 100 requests/hour per IP.

Args:
    query: Free-text search term. In default mode, treated as keywords
        (each word matched against product text). In `super_search=True`,
        treated as a natural-language description.
    min_price: Lower bound on price in EUR. Omit for no lower bound.
        Null-priced rows are NOT excluded by this filter — pass
        `has_price=True` if you need only priced listings.
    max_price: Upper bound on price in EUR. Omit for no upper bound.
        Tip — narrow by budget: `min_price=10, max_price=50,
        sort_by="price_asc", has_price=True`. Products without a listed
        price (a large fraction of the scraped catalog) sort last under
        either price ordering and are kept in results unless `has_price`
        filters them out.
    tags: Comma-separated tag filter (e.g. "electronics,bluetooth"). Tags
        are AND-ed together.
    store_id: Restrict results to a single store. Use the integer `id` from
        `search_stores` results.
    sort_by: One of `price_asc`, `price_desc`, `name_asc`, `newest`,
        `oldest`. Omit to use the default search-relevance ranking.
    has_price: When True, exclude products without a listed price (~most
        of the scraped catalog). Use this for competitive pricing or
        budget-bounded shopping. When False, return only null-priced
        listings (rarely useful). Omit to include both.
    semantic: Legacy flag. Pure vector ordering, ~250ms. Mostly
        superseded by `super_search=True` (which uses the same vector
        retrieval plus a cross-encoder rerank for materially better
        ordering at the cost of another ~700ms). Keep using it only if
        you specifically want vector retrieval *without* the rerank.
    super_search: **Enable for natural-language / "describe what I
        want" queries.** ~1–2s. Embeds the query with voyage-3-large,
        takes the cosine top-50 (with a precision boost for exact-name
        matches like part numbers / SKUs), then a cross-encoder reranks
        them. Use whenever the user is describing rather than naming —
        cross-language ("Schraubenzieher Set"), attribute-style
        ("small black metal bracket"), or any case where the default
        keyword path returns junk. Don't combine with cheap
        browse-style queries where the user typed an exact product
        name — keyword default is faster there.

        On `relevance_score` here: better than the bi-encoder cosine,
        but still not a "did I find what the user wanted" gauge.
        Behavior to expect: gibberish or fully-off-topic queries cap
        around 0.35; loosely-related catalogue clusters can score 0.7+
        even when no item truly matches (a "ceramic vase" query in a
        catalog with no vases but many ceramic flowerpots will still
        score high). **Read the product names** before claiming a
        match. The score is most useful as a relative signal within
        one result set — a sharp drop between rank N and N+1 marks
        where the catalog stops being useful for this query.
    limit: Max results (1–100, default 20). Larger limits are slower and
        consume rate budget faster.
    offset: Skip this many results before returning. Use for pagination
        (offset += limit on each follow-up call).

Returns:
    A list of products. Each includes `id`, `name`, `price`, `currency`,
    `url`, `description`, `store` (id/name/address), `tags`, `images`, a
    canonical `partle_url`, and `relevance_score` (cosine similarity 0–1
    between the query and the product's embedding when a query was
    provided; `None` otherwise). **Always share `partle_url` with the
    user so they can view the listing.**

    Caveat on `relevance_score`: it is monotonic *within a single search
    result set* (useful for spotting a big drop-off between rank 3 and
    rank 4), but its absolute value is not well-calibrated across
    queries — most results land in 0.55–0.80 regardless of whether the
    catalog has truly relevant items. Don't infer "this is a great
    match" from a 0.75 score alone.