search_products

xyz.rubenayla.partle/marketplace · Verify this server

Search Partle's product catalog by name or description. 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.