Mai Trading Matchmaking

The problem it addresses

A credible buyer-merchant match often fails because the conversation is missing a deterministic state base: whether inventory is real, whether quotes use the same product version, whether order transitions are traceable, whether payment evidence exists, and whether risks are stated plainly. Mai separates what an AI agent is good at—natural language, negotiation, summaries, and risk explanations—from the marketplace state maintained by scripts/mai.py, so the model does not infer inventory or payment success from chat context alone.

How it works

• State and generation are split: deterministic data lives in a CLI-backed state layer, while the model converts intent into search, comparison, quoting, confirmation, and status updates.
• Buyer and merchant flows: the merchant can create a profile, publish SKUs, adjust stock, record buyer messages, and advance orders only when inventory and terms are clear; the buyer can discover merchants and products, compare shortlisted SKUs, inspect review signals, log discussion, and create a draft order.
• Explicit transaction states: orders move through states such as draft, quoted, confirmed, payment_pending, paid_external, fulfilled, and completed, while disputes can enter disputed and then resolve, refund, or cancel.
• Payment boundaries are explicit: Mai does not custody funds directly. Local mode records payment_url and payment_reference; registry mode records PSP custody events. It should not claim payment success, release, or refund without PSP or external evidence.

Where it fits

It is useful for private catalogs, registry-backed discovery, product comparison, and order-status tracking, but it is not a real escrow or automatic payment-completion service. For stock, quotes, order confirmation, refunds, and disputes, the state records and external evidence should drive the decision.