Native shopping apps and commerce agents. From choosing to confirming to acting.
English · 简体中文
Android · iOS · Run locally · Retail evaluation · Contributing
Android / iOS buyer apps and a React merchant workspace for one retail brand. Shoppers describe what they need, compare products, and confirm transactions. Operators turn business data into proposals, review changes, and approve execution. CityBuddy provides the transaction and identity backend.
| Buyer · Android / iOS | Merchant · React Web |
|---|---|
| Products and specifications, comparisons, shopping plans | Sales trends, inventory alerts, orders and after-sales |
| Product-aware conversations, streaming cards, editable preferences | Read-only SQL analysis and isolated Python computation |
| Cart, quote confirmation, orders, simulated payments and refunds | Product updates, pricing, restocking, promotions and marketing drafts |
| Flash-sale reservations, status lookup, original-operation recovery | Change previews, operator approval, execution receipts |
The product site presents native application footage and interaction demonstrations. The full business flows run with local services.
- Native interfaces, shared rules. Android uses Jetpack Compose; iOS uses SwiftUI. KMP shares SSE decoding, message reduction, quote handling, and recovery rules. Navigation, network cancellation, secure storage, and lifecycle handling stay with each platform.
- Streaming reads and asynchronous state. Text and product cards arrive incrementally. Persisted message IDs survive recovery; older history pages prepend without replacing the active reply. Reading history preserves scroll position; returning to the end resumes following. Catalog pagination belongs to the submitted query, and late product details cannot replace a newer selection. SwiftUI uses immutable message segments as equality boundaries to retain unchanged cards.
- Agent runtime and tool execution. The Chat adapter assembles argument fragments and validates the complete response before dispatching tools. Concurrent results retain their call IDs; cart read-modify-write operations are serialized within a conversation. Main and delegated agents share model-call limits and a deadline, with cancellation propagated to in-flight work. See the execution flow.
- Recover the original operation. Request keys, original arguments, and confirmed quotes are persisted before writes. If a response is lost, recovery checks the original receipt and resumes the same intent. Generation, ordinary shopping, and approvals proceed independently; Java transactions determine the final business state.
- Analysis with explicit execution boundaries. The merchant agent delegates complex queries to a read-only SQL sub-agent; complete, bounded datasets can pass to an isolated Python container. Skills load on demand; old tool-result bodies are trimmed while preserving call/result pairing, and memory is editable. Checkout, payment, refund confirmation, and approval of merchant changes remain user actions.
flowchart TB
App[Android / iOS] --> Host[ShopMate API and agents]
Web[React merchant workspace] --> Host
App -->|Flash-sale reservations and status| Commerce[CityBuddy Commerce]
Host -->|Login and scoped delegation| Auth[CityBuddy Auth]
Host -->|Scoped tools and user actions| Commerce
Host --> State[(SQLite: conversations and recovery)]
Auth --> DB[(MySQL: identity and transactions)]
Commerce --> DB
Merchant analysis uses a separate data path. The host queries reporting views with a read-only account, then passes complete, bounded tables to the network-isolated Python container.
flowchart LR
SQL[Host SQL analysis] -->|SELECT-only| Views[(MySQL reporting views)]
SQL -->|Complete table and code| Python[Python container: no network]
The Python container has no database connection or credentials. Identity, conversation ownership, and business authorization remain enforced by their owning services.
ShopMate currently runs as a single-instance host. SQLite with WAL stores conversations, intents, and preferences; MySQL stores identities, products, orders, and transaction receipts. See the runtime guide for ownership and deployment constraints.
Native tests cover streaming reads, cancellation, catalog pagination and detail races, state across screens, and original-request recovery. Runtime tests cover fragmented arguments, truncated tool requests, concurrent result ownership, and budget cancellation. Business integration tests verify transactions through real APIs and SQL.
The retail evaluation records 18 known scenarios and 30 real-model attempts: 24 passes, 3 business failures, and 3 provider failures. Shopping, payment, refunds, promotional purchases, and merchant analysis are checked against actual responses and database state. The report retains failures, workload definitions, and full source revisions.
StateEval examines authorization separately. Business completion, permission correctness, and response quality are distinct judgments.
Prerequisites: a sibling CityBuddy checkout, Java 21, Python 3.11+, Node.js 24, uv, and Docker Compose. Complete the initial backend setup, then run:
uv sync --frozen
python3 scripts/local_runtime.py up
npm --prefix web ci
npm --prefix web run build
uv run uvicorn shopmate.app:create_app --factory --host 127.0.0.1 --port 8101Open the merchant workspace at http://127.0.0.1:8101/. Build the buyer apps using the Android or iOS guide. Model configuration, demo accounts, data reset, and checks are documented in the runtime guide.
| Directory | Contents |
|---|---|
android/ · ios/ · shared/ |
Native clients and the KMP business core |
web/ |
React merchant workspace |
src/shopmate/ |
Agent host, protocol adapter, and shared budget |
| Buyer loop · Merchant loop · Tool dispatch | Model rounds, tool execution, and result collection |
integration_tests/ · evals/ |
Business-boundary tests and real-model evaluations |
site/ |
Independently built GitHub Pages product site |
Native interfaces, agent execution, and persistent conversations connect to CityBuddy's identity and transaction services. The product site notes describe the native footage and interaction demonstrations; image credits list product photography sources.