The technical gateway to RetailAgentOS
An open specification and a tested reference engine, not a walled product. This page links to the primary sources instead of duplicating them.
328/328 automated tests passing · 93.8% line coverage (rules engine scope) — see the scorecard
What RetailAgentOS is, technically
An open specification (RAOS) plus a tested reference engine that evaluates a retailer’s eligibility, pricing, inventory, fulfilment and quote rules against a buyer’s context, and returns a deterministic, explainable DecisionRecord.
Relationship to UCP
UCP defines the discovery and transport rails commerce agents use to talk to a store. RetailAgentOS is the reasoning layer that sits behind those rails — it decides what an agent should be told, UCP carries the message.
Reference-engine overview
Published as @retailagentos/engine — pure, deterministic evaluation functions with no I/O, no wall-clock reads, and no randomness. Same inputs always produce the same DecisionRecord.
See the architecture→Decision pipeline overview
A staged, fault-isolated pipeline runs each extension in priority order, folding reasons into one ordered record. A throwing evaluator degrades safely instead of crashing the pipeline.
See the pipeline model→Extension model
Each capability — eligibility, pricing, inventory, fulfilment, quote integrity, trust — is a namespaced extension (com.os.retailagent.shopping.*) with a pure evaluate function, negotiated per merchant via the discovery manifest.
See the extension registry→Decision records and reasons
Every decision carries a uniform reason vocabulary (code, severity, source, requirements) and renders into audience-specific traces — merchant ops, buyer-facing, or raw developer JSON.
Available specifications
Adoption Guide
The @retailagentos/engine package entry point and the tiered adoption ladder.
Live Playground
Run real buyer contexts against the reference engine and inspect the decision trace.
Conformance
What a conformant implementation must satisfy, checked against the code.
Known limitations
- No live MCP transport ships yet — the engine is packaged so one can be built outside this repo.
- Cryptographic signing is simulated by locked decision, labeled TRUST_SIMULATED wherever it applies.
- No agent authentication, rate limiting, persistence, or multi-tenant production infrastructure.
- Promotion stacking, loyalty and restricted-goods enforcement are designed but not implemented.