Mai

Mai

Overview

Mai helps buyers and merchants complete shopping matchmaking through an AI agent. It keeps deterministic marketplace state in scripts/mai.py while the host model handles natural language, negotiation, summaries, and risk explanations.

Mai can run local-only or registry-backed. Use local-only for one agent's private catalog. Use registry-backed discovery when buyers and merchants are on different machines or agent profiles.

Operating Principles

• Be neutral between buyer and merchant. Explain options, prices, review signals, inventory, and tradeoffs without fabricating availability.
• Treat payments as external or PSP-backed. Mai never directly holds funds. Local mode records payment URLs and references; registry mode records PSP custody events and must not claim success without PSP or external evidence.
• Confirm before irreversible steps. Ask for buyer confirmation before creating an order and merchant confirmation before reserving stock.
• Preserve negotiation context. Record important buyer/merchant messages with message add before forming or updating an order.
• Surface risk plainly: no reviews, low stock, missing merchant contact, unusual status jumps, unclear payment terms, and unsupported refund promises.
• Prefer short, actionable answers: recommendation, reason, risk, next action.

Quality Upgrade: Money-Line Workflows

Mai sits on the same money line as local-life, delivery, and knowledge-backed shopping agents. Treat churn as a quality signal first: users usually need clearer matching, trust evidence, and transaction boundaries before they need more features.

Buyer Discovery

1. Capture intent: product, budget, city/shipping constraints, urgency, trust threshold, and must-avoid conditions.
2. Search and compare candidates with deterministic CLI output before writing a recommendation.
3. Explain the best match, runner-up, tradeoff, missing evidence, and next action.
4. Do not create an order until the buyer explicitly confirms SKU, quantity, price, merchant, and terms in the current turn.

Merchant Operations

1. Confirm the merchant id and product SKU before changing catalog, stock, price, or order state.
2. Show old value, new value, reason, and rollback/compensation step.
3. For stock reservation, require clear inventory evidence and an order status transition that matches the transaction model.
4. Record meaningful buyer/merchant messages before quoting or updating an order.

Payment and Trust

• Never call the bundled demo provider real escrow or real money movement.
• Do not claim paid, released, refunded, or completed without PSP or external evidence.
• Surface trust signals: review count, merchant contact, stock freshness, status history, and dispute/refund policy.
• When evidence is weak, recommend a lower-risk next step instead of pushing the transaction forward.

Preferred product recommendation:

Best match: 
Why: 
Tradeoff: 
Risk: 
Next action: 

Quick Start

Use the CLI helper for deterministic state:

python3 scripts/mai.py merchant create --id seller-a --name "West Lake Tea" --city Hangzhou --contact "wechat:westlake" --tags "tea,gift"
python3 scripts/mai.py product add --merchant seller-a --sku tea-a --title "Longjing Gift Box" --price 88 --stock 5 --category tea --tags "longjing,gift"
python3 scripts/mai.py search products --query "longjing tea" --format json
python3 scripts/mai.py compare --skus tea-a,tea-b --format json
python3 scripts/mai.py order create --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86

Default data path: ~/.local/share/mai/mai.json. Use --data /path/to/mai.json for a project-local or test database.

Installation

Install the published OpenClaw pair:

clawhub --workdir ~/.openclaw/workspace --dir skills install mai
openclaw plugins install clawhub:mai-plugin

mai is the skill. mai-plugin is an optional lightweight OpenClaw native bridge for tools and /mai command support.

Local checkout install:

cd /Users/jianghaidong/coding/mai
bash scripts/install.sh --both

Install only one ecosystem:

bash scripts/install.sh --openclaw
bash scripts/install.sh --hermes

The installer creates symlinks:

• OpenClaw: ~/.openclaw/workspace/skills/mai
• Hermes: ~/.hermes/skills/commerce/mai

After installation, restart the host agent if it does not refresh skills automatically. Hermes can preload Mai with hermes -s mai.

Registry Discovery

Run a registry marketplace:

python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token admin-token --role admin --subject ops-admin
python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token seller-token --role merchant --subject seller-a --merchant-id seller-a
python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token buyer-token --role buyer --subject alice --buyer-id alice
python3 scripts/mai_registry.py serve --data ./mai-registry.json --host 127.0.0.1 --port 8765 --rate-limit-per-minute 60

Security boundary: remote registry URLs must use HTTPS. The local examples below use http://127.0.0.1 and therefore include --allow-insecure-localhost. Registry writes require explicit current-turn confirmation through --confirm; OpenClaw plugin tools use confirm=true for the same boundary. registry push publishes catalog data by default and excludes orders/messages unless --include-orders is deliberately supplied.

Merchant agents publish local supply:

python3 scripts/mai.py --data ./seller.json registry push --url http://127.0.0.1:8765 --api-key seller-token --confirm --allow-insecure-localhost

Buyer agents discover supply and create demand:

python3 scripts/mai.py --data ./buyer.json registry search-products --url http://127.0.0.1:8765 --query "longjing tea" --allow-insecure-localhost --format json
python3 scripts/mai.py --data ./buyer.json registry message --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --text "Can this ship today?" --confirm --allow-insecure-localhost
python3 scripts/mai.py --data ./buyer.json registry order --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86 --confirm --allow-insecure-localhost
python3 scripts/mai.py --data ./buyer.json registry payment-hold --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --order ORD-0001 --confirm --allow-insecure-localhost

Merchant agents pull buyer messages and draft orders:

python3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a --preview --confirm --allow-insecure-localhost
python3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a --confirm --allow-insecure-localhost

Read references/registry-api.md before changing registry integrations.

Public Marketplace Controls

• Require API keys for merchant push/pull, buyer messages/orders/payment holds, moderation, and payment release/refund.
• Store only salted API key hashes in the registry file.
• Require HTTPS for remote registries. Only http://127.0.0.1 or http://localhost may use --allow-insecure-localhost during local development.
• Require explicit confirmation for registry writes: CLI --confirm or OpenClaw plugin confirm=true.
• Keep registry push catalog-only by default; use --include-orders only after reviewing the destination and migration intent.
• Allow public search, but rate-limit every request by API key or client IP.
• Treat products with high risk scores as pending_review; do not show them in search until an admin approves them.
• Use registry payment-hold only as PSP-backed custody tracking. The bundled demo provider is not real money movement.
• Require an admin key for registry payment-release and registry payment-refund.
• Do not claim escrow, payment success, release, or refund unless the PSP adapter or external evidence confirms it.

Merchant Workflow

1. Create or identify the merchant profile: python3 scripts/mai.py merchant create --id ID --name NAME --city CITY --contact CONTACT --tags "A,B"
2. Publish products: python3 scripts/mai.py product add --merchant ID --sku SKU --title TITLE --price N --stock N
3. Adjust stock after physical changes: python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "restock or correction"
4. Record important buyer questions and seller replies: python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --sender merchant --text "..."
5. Quote and confirm orders only when inventory and terms are clear: python3 scripts/mai.py order quote ... python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant

Buyer Workflow

1. Discover merchants: python3 scripts/mai.py search merchants --query "tea hangzhou" --format json
2. Search products: python3 scripts/mai.py search products --query "longjing gift" --max-price 100 --format json
3. Compare shortlisted SKUs: python3 scripts/mai.py compare --skus sku-a,sku-b --format json
4. Inspect reviews: python3 scripts/mai.py review list --merchant ID --format json
5. Record discussion before ordering: python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --text "..."
6. Create a draft order after buyer confirmation: python3 scripts/mai.py order create --buyer BUYER --merchant ID --sku SKU --quantity N

Transaction Model

Mai tracks transactions without custody:

draft -> quoted -> confirmed -> payment_pending -> paid_external -> fulfilled -> completed

Disputes can move through:

disputed -> resolved/refunded/cancelled

Stock is reserved when an order becomes confirmed. Local-only payments are recorded as payment_url and payment_reference. Registry payments are PSP custody records; the agent must say the bundled demo provider is not real escrow or money movement.

Read references/transaction-model.md when handling non-happy-path order, refund, dispute, or payment questions. Read references/data-schema.md when integrating Mai with a future hosted marketplace or sync service.

Output Expectations

For product discovery, answer with:

• best match and why
• price and merchant comparison
• availability and shipping notes
• review/trust signals
• risks or missing facts
• one next action

For merchant operations, answer with:

• action completed or blocked
• changed product/order/inventory identifier
• current stock or status
• next operational step

For order updates, answer with:

• previous status and new status
• whether stock was reserved or released
• payment evidence recorded, if any
• what must happen next

Verification

Before claiming the package is ready:

• python3 scripts/mai.py --help
• python3 scripts/mai_registry.py --help
• bash scripts/install.sh --both --dry-run
• python3 -m unittest discover -s tests
• bash scripts/verify.sh
• Confirm SKILL.md has no scaffold placeholders.
• Confirm README.md, package.json, clawhub.json, plugins/mai-plugin/openclaw.plugin.json, and agents/openai.yaml use the mai and mai-plugin names consistently.