octrow/buy-smarter

An explainable shopping assistant for Kazakhstan. You describe what you need in plain words
("a portable water flosser, IPX7, under 40,000 ₸, Almaty"). buy-smarter searches Kaspi.kz,
Ozon.kz and OLX.kz (used items), and ranks the offers for your budget, city and must-have features.
For every pick it shows which axes scored it and why. It runs as a CLI, as an MCP server for Claude and as an HTTP API
with a job queue.
It does not hunt for "the best product in general". It looks for the best one for you, today, under your
limits, and tells you what it could not verify.
## What a report looks like
An excerpt from a real run (a saved report, query: adapalene 0.1% cream under 10,000 ₸, Almaty):
text
🥇 ELEGANT COSMED Eleklin-A gel, 15 g [kaspi]
Score 66/100 · Confidence 70% · 7,700 ₸
| Axis | Score | Why |
| ingredient | 25/25 | active ingredient present (0.1%) |
| brand | 1.5/10 | unknown brand, no trust data |
| price | 11/25 | 7,700 vs pool median 5,238 (ratio 1.47) |
| reviews | 3.4/12 | 4.9/5 across 31 reviews; review trust 0.5: 96% five-star |
| availability | 10/10 | in stock |
cheaper analog by active ingredient: Kormesic Adapalene gel, 50 g, 2.6× cheaper
unknown brand · weak reviews · weak popularity
The report goes on with a review summary, alternatives (best value, best budget), the top N with links and a
"Used on OLX" section.
## Why not just ask a chatbot or sort by rating?
Kazakh marketplaces. General assistants (ChatGPT shopping, Perplexity, Google AI Mode) barely see Kaspi
or OLX.kz. buy-smarter reads their JSON endpoints directly and survives one source going down.
Ratings get gamed. Review trust looks at the five-star share across the full distribution, bursts of
reviews on the same dates, junk texts ("haven't tried it yet", "courier was fast"), unverified purchases
and defect complaints. Then it discounts the reviews axis accordingly.
Your requirements are checked, not assumed. A required feature the specs don't confirm is checked
against reviews. The quote must exist verbatim in a review and appear at least twice, or the verdict stays
"not enough data".
Brand and model knowledge. Brand tiers and model aliases are seeded for water flossers. Any other
category gets them via learn-category, so "me 705" on OLX resolves to "Xiaomi Water Flosser 2". Without it,
every brand ranks as unknown: run learn-category "смартфон" once before phone queries. Knowledge goes to
the local store.
Auto-learning. A query for a category with no knowledge anywhere learns it first (opus with web search,
1-3 minutes, paid), then searches with it. The desktop app shows the learning with a timer: "Искать без
изучения" searches now while it goes on, "Отмена" stops both. The CLI offers the same choices on a terminal:
learn first (default) or search now while it learns, then repeat the search; --learn learns first without
asking, also off a terminal. A failed learn searches without the
knowledge. MCP (with parsewithllm) learns in the background after the report: repeat the query once it is
done. At most 10 starts per hour (BUYSMARTERAUTOLEARNPERHOUR); 0 turns auto-learning off, and the
report says so. The API never learns on its own unless BUYSMARTERAUTOLEARN=true.