DiamondScope Engine

Open-source pricing engine that reverse-engineers South African diamond pricing across the three retail channel tiers (manufacturer-direct, boutique retail, chain retail) using a Rapaport-equivalent ZAR baseline and verified channel premiums.

Powers the free public tool at naturaldiamond.co.za/diamondscope.

---

Why this exists

Rapaport publishes a wholesale diamond price list every Friday. It is paywalled and trade-only. Most South African buyers have no way to see it. That information asymmetry is what lets chain retail jewellers add a 100 to 150 percent premium over the underlying stone cost and still feel like a fair deal.

The DiamondScope engine fixes that asymmetry. Given any diamond spec, it returns:

1. The editorial Rapaport-equivalent ZAR baseline for that stone.
2. The expected price across three retail channels (manufacturer-direct, boutique retail, chain retail).
3. Specific per-retailer quotes for the major South African jewellers.
4. Adjacent-spec deltas ("drop to H colour, save R7,400").
5. Auto-generated editorial commentary.
6. Confidence indicator for the baseline.

It runs entirely client-side. No backend. No telemetry. No external API dependencies.

---

Install

npm install @awenroswer/diamondscope-engine
# or
pnpm add @awenroswer/diamondscope-engine
# or
yarn add @awenroswer/diamondscope-engine

If you prefer not to use the package manager, the entire engine is a single TypeScript file at src/index.ts. Copy it into your project.

---

Quick start

import { scope, formatZAR } from '@awenroswer/diamondscope-engine';

const result = scope({
  shape: 'round',
  carat: 1.00,
  colour: 'G',
  clarity: 'SI1',
  cut: 'GIA-Excellent',
});

console.log('Rapaport-equivalent baseline:', formatZAR(result.rapaportZAR));
// > Rapaport-equivalent baseline: R100,000

console.log('Manufacturer-direct (mid):',
  formatZAR(result.channels.manufacturerDirect.mid));
// > Manufacturer-direct (mid): R65,000

console.log('Chain retail (mid):',
  formatZAR(result.channels.chain.mid));
// > Chain retail (mid): R85,000

for (const r of result.retailerQuotes) {
  console.log(`${r.retailer}: ${formatZAR(r.price)} (${r.channel})`);
}
// > Prodiam Trading: R65,000 (manufacturer-direct)
// > Nungu Diamonds: R68,000 (manufacturer-direct)
// > Jack Friedman: R85,000 (boutique)
// > ... etc

---

API reference

scope(spec, retailQuoteZAR?)

Main entry point. Returns a ScopeResult with the full pricing breakdown, retailer quotes, commentary, and confidence score.

rapaportZAR(spec)

Returns the Rapaport-equivalent ZAR baseline as a single number.

computeChannels(rapZAR)

Returns { manufacturerDirect, boutique, chain } with { low, mid, high } for each.

computeRetailerQuotes(rapZAR)

Returns an array of RetailerQuote objects with one entry per known SA retailer.

identifyRetailer(url)

Given a URL from a SA jewellery retailer's product page, returns { retailer, channel, ofRapaport } or null.

adjacentDeltas(spec)

Returns "what if you adjusted one grade" delta cards (drop a colour grade, upgrade a clarity grade, etc.) with the price savings or cost.

whatsappProdiam(spec) and emailProdiam(spec)

Builds pre-filled deep links for WhatsApp or email to the editor's recommended manufacturer-direct supplier (Prodiam Trading, Bedfordview).

Full type definitions

See src/index.ts for the complete TypeScript type definitions including DiamondSpec, DiamondShape, DiamondColour, DiamondClarity, DiamondCut, ScopeResult, RetailerQuote, and SpecDelta.

---

Methodology

Rapaport-equivalent ZAR baseline

The engine maintains a per-stone Rapaport-equivalent ZAR baseline calibrated against published SA manufacturer-direct quotes. The baseline is set for a 1.00 ct round brilliant, G colour, SI1 clarity, GIA-Excellent cut at R100,000. All other specs scale from there via four coefficient tables:

1. Carat coefficient: non-linear scaling from 0.30 ct to 5.00 ct. Anchor points were calibrated from naturaldiamond.co.za's published pricing pages (1-carat, 2-carat, 3-carat).
2. Colour multiplier: D (1.45) to K (0.62), relative to G.
3. Clarity multiplier: FL (1.70) to I1 (0.55), relative to SI1.
4. Cut multiplier: GIA-Excellent (1.00) to GIA-Fair (0.55).
5. Shape multiplier: round (1.00) to emerald (0.72), capturing the rough- crystal yield difference between cuts.

For specs not falling on an anchor point (e.g. 1.35 ct), the engine linearly interpolates between the nearest two carat anchors.

Channel premiums

The three channels each have a multiplier on the Rapaport-equivalent baseline:

• Manufacturer-direct: 0.55 to 0.75 of Rap (mid 0.65). RAP-minus 25 to 45%.
• Boutique retail: 0.80 to 1.05 of Rap (mid 0.92). RAP-minus 5 to 20%.
• Chain retail: 0.55 to 1.20 of Rap (mid 0.85). Highly variable because chain retailers often drop the cut grade to Very Good at the marketed price point.

Per-retailer premiums

The engine ships with a hand-maintained list of 9 major SA jewellery retailers with their observed premium multipliers, calibrated from product-line monitoring (May 2026 snapshot). The retailer list includes Prodiam Trading, Nungu Diamonds, Jack Friedman, Charles Greig, Shimansky, Browns, American Swiss, Sterns, and NWJ.

Confidence

The engine returns a confidence score (0 to 1) for each result. Confidence degrades at the edges of the dataset:

• Carat < 0.50 or > 3.00: confidence drops 0.10
• Carat > 5.00: drops 0.15
• D or K colour: drops 0.05
• FL or IF clarity: drops 0.05
• I1 clarity: drops 0.08
• Non-round shapes: drops 0.05
• Non-Excellent cut: drops 0.05

For a 1.00 ct round brilliant G/SI1 GIA-Excellent stone (the calibration anchor), confidence is 0.92.

---

Calibration data sources

The engine's pricing data is calibrated from two independent sources:

1. Naturaldiamond.co.za pricing pages (manufacturer-direct quotes). See https://naturaldiamond.co.za/1-carat-diamond-price-south-africa/, /2-carat-diamond-ring-price-south-africa/, and /3-carat-diamond-ring-price-south-africa/.
2. Direct conversation with Prodiam Trading (Bedfordview cutting house, De Beers DBCM Emerging Beneficiation Customer). See https://www.prodiam.co.za.

The full editorial methodology is documented in docs/methodology.md.

---

Update cadence

• Channel premiums: refreshed quarterly from product-line monitoring across the major SA retailers.
• Rapaport-equivalent baseline: refreshed monthly. Diamond pricing changes weekly with the Rapaport list.
• Per-retailer multipliers: refreshed quarterly.

---

What this is not

• Not a real-time Rapaport feed. Rapaport is a paywalled trade publication. We do not republish their list. We maintain an independent editorial approximation calibrated against publicly available manufacturer-direct quotes from South African cutting houses.
• Not a binding quote. For the actual price on a specific stone, contact the cutter or jeweller directly. The engine is editorial. Use it to ask better questions, not to skip asking the questions.
• Not affiliated with Rapaport USA, Inc. Rapaport is a registered trademark of Rapaport USA, Inc.

---

Where the engine is used

• Live demo: naturaldiamond.co.za/diamondscope
• Editorial publication: Natural Diamond
• Editor's first-pick manufacturer-direct supplier: Prodiam Trading, Bedfordview, Johannesburg

---

Contributing

Pull requests welcome. Specifically valued contributions:

1. Better per-retailer premium calibration (data, not opinion).
2. Additional retailer entries (with the data behind the premium estimate).
3. Refinements to the carat coefficient at the edges (sub-0.50 ct and > 3 ct).
4. Internationalisation. The current calibration is SA market-specific; a second calibration for UK, AU, or US would be a strong addition.

For any change to a coefficient or multiplier, please cite the data source in the pull request description.

---

Licence

MIT. See LICENSE.

---

Credits

Built by Sarah-Anne Ndlovu, editor at Natural Diamond. Engine design and calibration by the Natural Diamond editorial team.

If you find the engine useful, the most helpful thing you can do is point a South African diamond buyer at the live tool at naturaldiamond.co.za/diamondscope.