Black Swan Group

Applied software and automation

Black Swan Commerce

In development · Active 2026 · Last verified 2026-09-29

Problem

Purchase intent is trapped inside retailer-specific search boxes. Customers repeatedly restate the same requirements while every seller represents products, availability, pricing, and carts differently.

Product

Black Swan Commerce is an API-first commerce engine. It turns a plain-text shopping list into a reviewable set of product selections, then pushes the confirmed picks into a real merchant cart. Every search, ranking, and selection decision is recorded so selection quality can be measured rather than guessed.

Intended user

Individual consumers, technically sophisticated shoppers, households, small businesses, contractors, purchasing agents, and AI agents acting under user-defined constraints.

Thesis

A purchase request should be written once, remain under the customer's control, and work across whichever seller or interface responds best.

Request flow

  1. 01Plain-text shopping list
  2. 02Commerce session (canonical, schema-validated items)
  3. 03Resolve: supplier search, ranking, and selection (async)
  4. 04Review and confirm the selection document
  5. 05Cart build through the merchant adapter (Kroger today)

Architecture

Retailer-specific logic stays isolated behind supplier adapters rather than leaking into the canonical model. The Black Swan domain model is not allowed to become a collection of Kroger-, Walmart-, or Home Depot-specific assumptions — every adapter translates a merchant's own API into the same typed request/result shapes the rest of the system already speaks.

One engine sits behind three thin interfaces — command line, MCP, and a versioned REST API — and the REST API is the sole product surface, including customer login and cart-add. The command-line client is itself just an HTTP client of that API, so there is no second code path to drift.

A commerce session is an explicit state machine: open, resolving, resolved, confirmed, cart built, closed. Resolution runs asynchronously on a job queue drained by a separate worker; editing an item reopens the session and marks the prior selection stale, and an invalid transition is rejected rather than silently applied.

Product selection is a replaceable strategy — a deterministic ranking heuristic, a language model, or a chain that falls back from one to the other — behind a provider-neutral inference interface. Hard constraints such as a price ceiling or excluded brands are applied as a filter before any selection strategy sees the candidates, so no strategy can return a violating product.

We deliberately left a known ranking weakness unfixed — distinguishing a plain product from its variants in real merchant data — and instead recorded every supplier request and response and every per-candidate score. A tuned or learned ranker can then be compared against today's baseline on the same candidates, rather than tuned on intuition.

Evidence

  • Canonical, schema-validated request model shared across every interfaceImplemented
  • Command-line, MCP, and versioned REST interfaces on one engine, with REST as the sole product surfaceImplemented
  • Stateful commerce sessions (resolve, review, confirm, cart) on an asynchronous job queue and workerImplemented
  • Replaceable selection strategy (ranking heuristic or language model, with fallback) behind a provider-neutral inference interfaceImplemented
  • Recorded decision trail: verbatim supplier requests and responses plus per-candidate ranking scoresImplemented
  • Kroger authentication, product search, and cart-add, verified by a real end-to-end grocery run into a live cartImplemented
  • Supplier-adapter architecture isolating retailer-specific logic from the core modelImplemented
  • Self-hosted deployment (PostgreSQL, API, worker) on owner-controlled infrastructureImplemented
  • Selection-accuracy analysis over the recorded decision trailPlanned
  • Second merchant integrationPlanned

Open assumptions

  • Whether the supplier contract generalizes cleanly to a second merchant with a materially different API shape.
  • Whether additional merchants will grant production API access beyond the developer-tier access currently in place.
  • How much value remains when a merchant's API ends at the cart: Kroger's exposes no checkout or cart-removal, so curation has to happen before the cart, inside the session.
  • Which business model — consumer app, commerce API, or licensed retailer-normalization technology — the evidence ultimately supports.

Next milestone

Add a second merchant through the same supplier contract without retailer-specific assumptions leaking into the core model, and use the recorded decision trail to measure selection accuracy before tuning ranking.

Future direction

We are exploring a second bounded context for selling owned inventory, sharing the same market data — listings, price observations, comparables — that purchasing already uses, inside one deployable service rather than a second application. This is direction, not a committed plan.

Partnership

Black Swan Group is interested in merchants and API partners willing to support a second integration, and in technically sophisticated early users willing to run real shopping lists through the REST API or command-line client.