Nudge

A voice shopping assistant that asks before it buys, and earns freedom one approval at a time.

Comment

Why it matters

You buy the same groceries and household staples again and again. A voice assistant could take that chore off your hands, but only if you stay in charge of the money. Nudge sits between "ask me every time" and "here is my card": it asks first, shows its reasons, and earns more freedom one category at a time.

What it does

Nudge is a simulated voice shopping assistant for the Alexa+ experience. It is shown with Amazon Fresh, Whole Foods Market and Amazon private-label items, but the products, prices, ratings, Prime badges and delivery dates are sample data. Amazon does not sell or price anything here.

  • It shows why. Every suggestion on the Today screen has a reason and a "Why am I seeing this?" link.
  • It reads the order back. Tap Review and buy, and Nudge reads back the item, store, amount, delivery date and the last four digits of the card. When an order needs approval, nothing is bought until you say or tap yes. That yes counts only for the order you just heard.
  • It double-checks big orders. Orders of $100 or more also need a 4-digit code. The code appears on a simulated phone after your first yes.
  • It earns freedom slowly. Each category has three levels: Suggest (ideas only), Ask first (prepares an order and waits for your yes) and Within limits (buys small items on its own). After three approved orders in a category, Nudge offers the next level. The Within limits offer spells out the terms: a per-item limit and a per-day limit that you choose, the stores already used in that category, and an end date. You confirm that exact offer. The per-item limit stays below $100, so a purchase Nudge makes on its own can never skip the code check. Afterwards Nudge tells you what it bought, what it chose not to buy, and why.
  • You can take it back. Pause at any time. Undo an order within 24 hours. If you report a problem with, or undo, an order Nudge bought on its own, that category drops back to Ask first.
  • It does not guess about payments. If the payment step does not answer, Nudge says "Not sure yet" and refuses to buy the same item again until it has checked with the store. In this mock payment workflow, one order is charged at most once.
  • It keeps a record you can check. Every step that changes a purchase writes a signed, hash-chained receipt. Each receipt includes a fingerprint (hash) of the one before it, so editing any earlier receipt breaks the chain. Verify receipts names the first record that changed. This detects later edits; it does not prove that the recorded facts were true.

A fresh start has every category turned off, at Suggest. The demo profile, Maya, starts with groceries at Ask first and two earlier approvals, so one more yes brings the Within limits offer.

Everything is simulated: sample products, sample prices, a mock payment step and a simulated phone. No real card, store or money is involved, and no Amazon or Alexa+ service is called.

How we built it

  • Plain Python, nothing to install. The app uses only the Python standard library and has no build step.
  • A real MCP client and server. MCP (Model Context Protocol) is an open standard that lets an AI assistant call outside tools. Nudge's web page is a genuine MCP client. It talks to Nudge's own MCP server over Streamable HTTP (protocol revision 2025-11-25, plain JSON replies). Sixteen typed tools carry the workflow, such as search_products, propose_purchase, approve_purchase, undo_purchase, report_problem, run_daily_check and verify_receipts. Most buttons, including yes and no, call these tools. The page reads its screen state through an ordinary web API (REST).
  • Rules in code decide, not an AI model. A policy check from the reused approval-receipt core screens every purchase. A connected assistant (an MCP "host") can propose a purchase but cannot say yes for you. A yes needs a separate token that only the page holds.
  • A yes is tied to the exact terms. Each read-back carries an id and a hash of the full terms: product, quantity, delivery, card, unit price and total. If the price or terms change, the yes is refused and nothing is bought.
  • Simple voice commands. A rule-based parser handles typed or spoken commands such as "Pause groceries" or "Undo my last order". Negated, reported and question phrasing ("I didn't ask you to undo") does nothing. An explicit "stop" outranks any other word in the same sentence.
  • Tested. 297 automated tests pass. One of them runs the 67 tests of the reused core. They cover who may approve, the link between a yes and its terms, timeouts, undo, tamper detection, consistency after a restart and MCP protocol behavior. The animated explainer has 12 more tests.

What was reused and what is new

The approval-receipt core (vendor/approval_receipt, version 2.0.0) is an earlier library by the same author. It is included unchanged, with a SHA-256 manifest and a test that checks it, and it is disclosed here as pre-existing work. Everything else was written during the hackathon period in October 2026: the MCP server and client, the shopping levels and earned freedom, the link between a yes and its terms, the code check for large orders, undo and the store check, the voice layer, the web interface, the explainer animation, the documentation and the tests.

Challenges we ran into

  • Making a yes safe. A yes must apply only to the order shown. Each read-back carries an id and a hash of its terms, and a yes is refused if the price or terms changed.
  • Stopping an assistant from approving for you. Roles come from separate per-run tokens, never from a field in the request.
  • Avoiding a second charge. When a payment result is unknown, a repeat purchase is blocked until the store has been checked.
  • Staying consistent after a crash. On restart, Nudge compares its saved state with the receipts and stops with a clear message if they disagree.

What we learned

Trust is earned in small steps. Showing the reason, asking first and keeping a checkable record matter more than speed. The line between "the assistant proposed" and "a person approved" has to be enforced by the app itself, because MCP does not provide it.

What's next, and what is not done

Next: connect to a real Alexa+ device or skill, add real identity checks and sign-in for approvals, and test with real shoppers.

Not done: any real purchase or payment, real proof of identity, a browser-based accessibility audit and a production security review. No user study has been run.

Notices

  • The illustrations in the explainer and the video were generated with AI tools.
  • The narration in the demo video is synthetic speech generated with Kokoro text-to-speech.
  • Amazon, Alexa+ and related names, marks and page designs are the property of Amazon.com, Inc. or its affiliates, shown here only to illustrate an entry in the Build, Ship, Shape Amazon Developer Hackathon. Nudge is an independent simulation, not affiliated with or endorsed by Amazon. All rights remain with their owners.
  • Everything shown is a simulation with sample data and a mock payment step.

Built With

Share this project:

Updates

Submission history