Gaurmon

The user's Gaurmon plan: trial days left, or the paid plan and when it renews. Free.

For each item, the best comparable flyer offer at each banner near a place (priced offers first, the item itself by name, then lowest unit price), plus per-banner totals. Items with no flyer offer come back null: try shelf_prices for those.

Banners, current flyer weeks, store counts and known gaps (e.g. FreshCo store locations unknown; shelf prices No Frills only, with Statistics Canada Ontario averages as a labelled fallback). Free. Call it before telling a user something isn't on sale.

The user's grocery list and the meals behind it, kept by Gaurmon so they're the same in every agent and device. Each item is costed near a place for the amount needed (its own amount plus its meals'), from the cheapest flyer offer or everyday shelf price: by weight, by whole packages, multibuys per item; `price.how` says how and `approximate` when the size isn't comparable. `stops` groups items by store (at most `maxStores`, only `preferBanners` when set). `meals` lists each meal's ingredients and cost share; `mealIds` on an item says which meals need it. Unpriced items aren't counted in `totals`. Ids are for update_list and update_meals. Which stores to visit, and when, is yours to suggest.

The flyer crop an offer was read from (as an image), with its page, dates and banner. Use it to show the user, or for a price match at the till.

The running savings record, as estimates compared with typical prices nearby: the headline `vsTypical` (paid vs the typical, median price of the same items around the store on the same days; positive = under typical), `vsCheapest` (left on the table) and `vsPriciest`, totals by flyer week and by month, the best and worst lines, every line with the prices behind it, `summary` (lead with this: what was compared, what wasn't and why), `shareable`, one sentence the user can post, and `method` with `methodUrl`, a short plain explanation of how savings are counted and where it's published, to give the user when they ask. Totals count ranged lines only; thin and unranged lines are counted separately. Free, including after the trial.

Place a Canadian postal code, FSA or lat,lng as coordinates. Free. Use it to check a location before searching.

An item's observed unit-price range (min, median, max per kg, L or item) by flyer week (Thursday to Wednesday), from flyer offers and shelf prices near a place, plus `longRun`: the Statistics Canada monthly average unit price for the item since 2017 (Ontario, else Canada), with its 1- and 5-year change. `weeksKnown` says how many weeks Gaurmon has: its history started with the Oct 29 2026 flyer week and grows by one each Thursday, so say so when it's short, and say `longRun` is a provincial average, not a store price.

Where a price sits: the cheapest, typical (median) and priciest qualified unit price for the same item across stores near a place on a day (flyer offers valid that day, shelf prices read within a week), how many prices each rests on, and `status` ranged | thin_range | unranged. Give quantity, unit and paidMinor to get the percentile and savings for a price. Use it before a purchase to say what a fair price is; record_purchases stores the same numbers.

Add a receipt to the user's savings record: one row per line (generic item, quantity, unit, paidMinor in cents, optional offerId from search_offers). Each line is stored with its price range around the store that day (cheapest, typical, priciest) and returns savings vs each plus the percentile; negative savings (paid above typical) are kept. Lines on a thin range are shown but not totalled. Each line has `basis` (what it was compared with) or `notCounted` (why not) and a plain `summary`; the receipt has a `summary`, `method` and `methodUrl` (how savings are counted, an estimate compared with typical prices nearby) to pass on to the user. Append-only and idempotent: reuse `operationId` to retry safely; to fix a purchase, record a new one with `supersedesPurchaseId`.

This week's flyer offers for item words, an aisle, or deals near a place: give at least one of `query`, `aisle` or `near`. Each row has a comparable unit price (per kg, L or item), dates (`valid` is the first and last day, Toronto time), the nearest store carrying it, and an offerId for get_offer_evidence and show_offers. At most 50 rows a call; use `aisle` and `unit` filters and `fields` to keep answers small.

Regular (non-flyer) prices for staples, for items not on sale this week. Store shelf prices are No Frills only for now. One row per product; `proxy: true` means the price was read at another branch of the banner. Each row carries `baseline`, the Statistics Canada Ontario average for that kind of item when there is one, and `vsOntarioAveragePct`. When no store price exists (e.g. Food Basics, FreshCo), `hits` is empty and `fallback` holds only the StatCan averages: say they are provincial averages, not what a store charges.

Show the user a titled Gaurmon card of flyer offers you chose, in your order: your ranking of the week's best deals, or picks from several searches. Pass offerIds from search_offers or compare_items, plus the same `near` so each row names its nearest store. Use it when the user asks to see, list or rank offers you've already found, instead of writing the list out. Adds no new offers.

Stores within a radius, nearest first, each with every flyer it runs this week and how many offers each flyer has.

Add items to, remove items from, or tick items on the user's grocery list by hand (at most 100 items; an item already on the list isn't added twice, but one there only for a meal becomes wanted by hand too). Give an amount for each item so it's costed right. Use item ids from get_list. `clear: "checked"` removes ticked items after a shop; `clear: "all"` empties the list and its meals. For a meal's ingredients use update_meals instead, so they stay linked. Returns the list like get_list. After a shop, offer to record what was bought with record_purchases.

Add, remove, replace or edit the meals behind the user's grocery list; their ingredients go on and off the list to match, in one transaction. Send a whole plan at once with `add` (at most 21 meals, 40 ingredients each, amounts in any unit). Shared ingredients are combined where units allow. Removing a meal lowers what's needed of shared items and removes items no other meal needs, but never items added by hand; ticked items stay, marked noLongerNeeded. `replace` swaps a meal for another in one step. Returns the list like get_list plus `change` (items added and removed, estimate before and after) and `undo`: the update_meals arguments that reverse it.