smartcart

Show Product Images

Open an INTERACTIVE image gallery (carousel with photos, prev/next and an add-to-cart button) for SPECIFIC products the user/agent wants to SEE. Pass their `product_ids` (e.g. the top 5 from a prior search) and the current session_id. This does NOT search — it shows exactly those items.

Go Shopping

Open LA VIDRIERA — the visual shopping window over the WHOLE catalog: a root screen with two tabs (all categories / all stores), breadcrumb navigation to go back up, facet filters and an add-to-cart button on every product card. It can NEVER open empty: entry points that don't resolve fall back to the root with an `aviso` for you to relay. Entry points (server-resolved, combinable): `query` opens that search (`store` narrows it; `category` is ignored with an aviso); else `category` (slug OR huma

Fetch Catalog

App-only: full catalog payload (items + aisles + stores) for the shop window iframe. Called by the view over the bridge; not for the model.

Init Session

Start or resume a shopping session. Returns a SessionInit with session_id, user_id, reanudada, carritos_pendientes and avisos_wishlist. The cart lives on the server; pass session_id to every other tool. Call with NO args for a quick anonymous session. If the human wants to be remembered across visits, ask ONCE for an alias/email and pass it as `user` — then the server returns their `carritos_pendientes` (past carts with items). If there are any, OFFER to resume one BEFOR

Search Products

Semantic product search (bilingual EN/ES). Returns a SearchResult with `modo`, `resultados`, `sugerencias`, `instruccion_agente` and `resumen`. `instruccion_agente`: when present it is a server order for THIS turn — obey it literally; the server outranks these instructions. modo="lista": `resultados` are real matches (in stock; each has product_id, store_id, title, brand, price, currency, score, plus tipo_venta/unidad_venta and precio_regular when on sale — say "on sale

Search Products Bulk

Search a WHOLE shopping list in ONE call. `queries` is an array whose items are either a plain string or an object `{q, brand?, tag?, store?, price_min?, price_max?}` (per-query filters). Body-level filters apply as defaults to all queries; a query-object overrides them per field. `store` accepts store_id ("ksp-01") or name ("KSP"). Put constraints in the filter FIELDS, never inside `q`. Returns `{por_query, instruccion_agente}`: one entry per query `{query, modo, re

Get Categories

List ALL the store aisles ("góndolas"): each category with how many in-stock products it has (`cantidad`) and in how many stores (`cantidad_tiendas`, plus the store ids in `tiendas`). SQLite index, NO search. USE THIS (not search_products) for OPEN questions — "what categories are there?", "what else do you have?", "what's in computer parts?", "what do you sell?": a vague semantic search returns an arbitrary sample and the user believes they saw everything. Pass `store` (

Browse Category

Walk an aisle — "what's THERE", not "what looks similar": NO semantic search. The axis is a `category` (from get_categories), a whole `store` (id or name — "what does Bug have?", a store is a meta-aisle), or both; pass AT LEAST one. Returns {total, offset, items, facetas}. `facetas` (brands/tags/stores AND `categorias` — the store's aisles when browsing a store/price range) come ONLY on the first page (offset=0): narrate from them ("14 products, 4 brands, ₪480–₪5,200") an

Get Store

Get a store's hard data: name, shipping policy (free shipping, free shipping threshold) and logo_url. Use it to answer shipping questions with real data, and show the store logo in markdown: .

Add To Cart

Add `quantity` units (default 1) of a product to the session's cart. If the product is already in the cart it increments. Fails if the accumulated quantity exceeds stock. Requires a session_id from init_session. UNIT OF SALE (Nivel 2): `quantity` counts SALE UNITS (see tipo_venta/unidad_venta). ALWAYS state the unit when confirming ("added 2 kg of salmon", "3 packs of flour") and sanity-check amounts ("for 4 people" ≈ 1 kg of salmon = quantity 1, not 4) BEFORE adding — if

Add To Cart Bulk

Add MANY products to the cart in ONE call. `items` is an array of {product_id, quantity}. Prefer this over calling add_to_cart in a loop. Default is PARTIAL-with-report: adds everything it can and returns `{agregados, fallas}` — `fallas` lists EVERY failure with a readable `motivo` (insufficient stock with numbers + sale unit, or nonexistent product). Narrate it ("added 17; out of stock: X; Y doesn't exist"). Set `todo_o_nada=true` for all-or-nothing (nothing is added if

Remove From Cart

Remove a product from the session's cart. Without `quantity` it removes the whole line; with `quantity` it subtracts that many units (removing the line if it reaches zero). Requires a session_id from init_session.

Clear Cart

Empty the ENTIRE cart for a session in a single call (do not remove items one by one). This is destructive: ALWAYS ask the user to confirm before calling it. Before clearing, remind the user of the alternative: instead of emptying, they can keep this cart and start a fresh one with init_session (which returns a NEW session_id), and come back to the current cart later by reusing its session_id. SHOW the user the current session_id so they don't lose it. Requires a session_

List Cart

List the current cart for a session. Returns {items, totales, total_general}: `items` (product_id, store_id, title, price, currency, quantity), `totales` per store ({store_id, total, currency}) and `total_general`. ALWAYS use these server-computed totals; never sum the cart yourself. `total_general` is null if the cart mixes currencies (then show the per-store totales). Requires a session_id from init_session.

Checkout

Generate checkout for the session: items grouped by store, one payment link and estimated total per store (each with store_logo_url), plus warnings (e.g. the same item in more than one store). Call it ONLY when the user wants to pay / close the purchase — it is NOT a read-only query (it marks the session as checkout-generated). To answer shipping questions ("do I get free shipping?") use get_store + the totals from list_cart instead. Requires a session_id from init_sessio

Add To Wishlist

Save a product to the user's wishlist ("I'll think about it"). Stores the current price so the server can later flag drops/promos. Idempotent. OFFER this only at NATURAL moments — the user hesitates ("let me think", "it's pricey"), compares without deciding, or removes something from the cart — never on every message. Needs the user_id (from init_session); if the shopper has none yet, ask once for an alias.

Remove From Wishlist

Remove a product from the user's wishlist. Idempotent. Needs the user_id.

List Wishlist

List the user's wishlist: each item has precio_al_guardar, precio_actual, currency, and server-computed flags `bajo_de_precio` (cheaper than when saved) and `en_promo` (on sale now). Present drops/promos as good news, without pushing. Needs the user_id (from init_session).

Claim Prize

Claim this week's prize from La Estantería (see `estanteria` in init_session). NO prize parameter: the SERVER draws it (the user does NOT choose) — never draw, pick, or promise a prize yourself. One claim per user per week. Returns the drawn prize in `mensaje`/`premio` + an `instruccion_agente`: tell the user WHAT they got with energy (celebrate a good one; humor + "it refills Friday" for the consolation one), then CASUALLY pivot to their pending cart or wishlist discount to