Smart Counsellor 1.3 — Release Notes

Smart Counsellor — Release Notes (What’s New)

The Smart Counter AI selling layer on the POS. These notes cover the recommendation engine that powers up-sell, substitution, cross-sell, and the feedback loop, plus the model-quality tuning that ships in this update.


Release version	Smart Counsellor 1.3 — “Smart Counter Update”
Release date	2026-06-08
Applies to	POS → Smart Counter screen
Availability	Premium add-on, enabled per pharmacy

New Features

Trade-up ribbon (up-sell). A slim ribbon appears under a cart line when a higher-margin equivalent exists — e.g. “Trade up to Surgicryl Rapid 3/0 · +Rs 256 margin for you” — with an Upgrade button. Multiple options collapse to a +N options ranked popover with a Best value pick.
Substitution menu. When a line is out of stock, it turns amber with an “N equivalents in stock now → Substitute” prompt. A quiet ⇄ swap icon on any line opens the same menu on demand. Alternatives are ranked by clinical closeness — Same molecule → Diff. strength → Same class — with live stock, price delta, and molecule·form. Same-class swaps require pharmacist approval (Swap*) and are logged to the sale.
Cross-sell rack. A Cross-sell tab in the Smart Counsellor rack surfaces “customers who bought this also bought…” for the current basket, computed from the tenant’s own 90-day sales (no AI).
Report a recommendation. A quiet flag on every up-sell and substitution suggestion lets a cashier report a wrong AI suggestion (reason + optional note). The sale is never affected; the flagged suggestion hides on the reporter’s own screen immediately.
AI product classification engine. A background engine infers each product’s active ingredient, strength, pack size, and route from name + brand alone, so up-sell and substitution work even on the typical Pakistani catalogue that records nothing else.

Improvements

Up-sell now ranks by gross margin, not cheapest price. A trade-up only appears when it earns the pharmacy more margin than the line already in the cart; if nothing beats the focal, no ribbon shows.
Clearer reason bullets. Bullets now say who benefits — “+Rs N margin for you”, “Better margin · X% for you”, “Customer pays X% less per tab” — and surface customer savings on any genuinely cheaper swap.
Up-sell suggests in-stock items only, matching substitution behaviour.
Clinical safety locks added to up-sell matching: route/form lock (never suggests a suppository or injection for a tablet) and release lock (never suggests immediate-release for sustained-release, and vice-versa).
Better classification coverage via slug canonicalization — the same molecule expressed different ways (Vitamin B12, Vitamin D3, combo ingredient order, cosmetic salts) is no longer split into singletons that have nothing to suggest.
Device size and suture material captured so a 6 Fr catheter never substitutes for a 24 Fr one, and absorbable vs non-absorbable sutures don’t mix.
Cross-sell de-cluttered — ubiquitous staples (syringes, saline, IV sets, gauze) no longer dominate suggestions, thanks to a ubiquity penalty and a thin-sample (support-shrinkage) correction so genuine affinity wins.
Pack-size extraction reads counts from names like 10's, 2x14's → 28.

Bug Fixes

Out-of-stock trade-ups were still suggested. The up-sell RPC ranked out-of-stock candidates last but never filtered them, so when every same-strength equivalent was out of stock at the counter the ribbon still offered them. Now filtered to stock > 0. (migration 20260607120000)
Misclassified SKUs polluted suggestion groups. Products whose recorded ingredients disagreed with the AI’s molecule (e.g. Deprel/trazodone and Trapeze/sitagliptin surfacing as sertraline trade-ups) are now vetoed by a fuzzy ingredient check. (migration 20260607140000)
Cheaper, higher-margin-% swaps showed no value. A swap that was cheaper but carried a lower Rs margin previously displayed no bullet; it now surfaces both the margin-% gain and the customer saving. (migration 20260607130000)
Cross-form / cross-release suggestions (suppository for a tablet; IR for SR on carbamazepine, nitroglycerin, tramadol, diabetes combos) are now blocked by the route and release locks. (migration 20260605140000)
Cross-sell margin leak where popularity overrode affinity — re-scored so lift leads. (migrations 20260605150000, 20260605220000)

Known Issues

Combo-drug secondary strength is not locked. Two combinations sharing the same primary ingredient/strength but differing on the secondary (e.g. an ACE-inhibitor + 25 mg vs 12.5 mg HCTZ) can cross-match. The primary-strength lock covers the common case; full secondary-strength locking is deferred (needs a schema change). (tuning item D)
Recall gaps on obscure local brand names. A minority of products (≈6–12%) can’t be decoded from the brand name alone and won’t get suggestions until the tenant fills in generic_category/composition. (tuning item C2)
Some pack sizes still read as 1 on unusual naming; affects larger-pack trade-ups and per-unit price bullets only. (tuning item C1)
A full re-classification backfill is in progress for already-onboarded tenants so every classifier fix lands on every existing SKU; newly in-stock products are picked up automatically within the hour.

Notes for operators

A background sweep enqueues newly in-stock products, so a restocked item becomes suggestible within the hour and a typical catalogue is fully classified within a couple of hours.
Tenants without the module see nothing.

For the complete behaviour, formulas, and data model, see the internal legacy_docs/smart-counsellor-module.md. For the model-tuning backlog, see legacy_docs/smart-counsellor-upsell-tuning.md.