The Learning Loop & Alias Engine

One of the central differentiators of KHOLO is its ability to learn and adapt to informal wholesale jargon, regional dialects, brand nicknames, and shorthand abbreviations without requiring manual rule coding.

This document details the mechanics of the Extraction Engine, the SKU Matcher, and the Human-in-the-Loop "Resolve & Teach" learning mechanism.

1. The Real-World Challenge: Informal B2B TradeCopy Anchor Link

In South African wholesale and FMCG distribution, retail customers (spaza shops, general dealers, restaurants, catering businesses) do not order using formal ERP codes. They message via WhatsApp in freeform text or voice:

2. Phase 1: Strict AI Extraction (OrderExtractor)Copy Anchor Link

A common mistake in AI order processing is asking an LLM to simultaneously extract items and pick the database SKU. This causes hallucinations, wrong pack sizes, and ERP sync failures.

KHOLO strictly separates Extraction from Catalog Matching:

[{"item": "whites 12.5kg", "qty": 10},
{"item": "coke 2lt", "qty": 5}]

The System Prompt ArchitectureCopy Anchor Link

The extraction prompt is conditioned specifically for wholesale trade:

• Recognizes African quantity words and mixed language patterns (e.g., "fipha 10", "ngicela 5").
• Separates customer conversational pleasantries ("Good morning brother, how is family...") from genuine order lines.
• Identifies order intent (new_order, add_to_order, remove_from_order, status_check).

3. Phase 2: Multi-Tier Matching (SkuMatcher)Copy Anchor Link

Once OrderExtractor isolates { raw_item, quantity }, SkuMatcher evaluates the item against the distributor's catalog using a 5-step waterfall algorithm:

1. Trade CanonicalizationCopy Anchor Link

Before searching, the input string is cleaned and standardized:

• Units normalized: 10 kgs, 10 kilo, 10k $\rightarrow$ 10kg.
• Volumes normalized: 2 litres, 2 lt, 2lts $\rightarrow$ 2l.
• Well-known South African FMCG brand expansions:
  • whites $\rightarrow$ white star maize meal
  • stoney $\rightarrow$ stoney ginger beer
  • ricoffy $\rightarrow$ nescafe ricoffy
  • sunlight green $\rightarrow$ sunlight green laundry soap bar
  • dlite $\rightarrow$ dlite cooking oil

2. Size & Pack Penalty LogicCopy Anchor Link

If the customer asks for 10kg and the candidate product is 2.5kg, KHOLO imposes an automatic penalty to prevent dangerous incorrect picks:

if (itemSize && candidateSize && itemSize !== candidateSize) {
  // Severe confidence penalty for mismatched packaging sizes
  confidence = confidence * 0.4;
}

4. Phase 3: The Human-in-the-Loop "Resolve & Teach" MechanismCopy Anchor Link

When confidence falls below the auto-approval threshold ($< 0.85$) or multiple ambiguous products exist, the order is routed to the Clerk Control Centre (/dashboard):

What Happens When the Clerk Confirms:Copy Anchor Link

1. Instant Order Correction: The current OrderLine updates to productId = 'WSTAR-12.5KG' with recalculation of unit prices and line subtotals.
2. Permanent Alias Ingestion: A new record is inserted into ProductAlias:

INSERT INTO "ProductAlias" ("tenantId", "productId", "aliasText", "customerId")
VALUES ('tenant-uuid', 'prod-wstar-12.5', '12.5 whites', 'customer-uuid');

3. Audit Trail: An immutable AuditLog record is captured documenting the user ID, timestamp, before/after values, and the newly taught phrase.
4. Immediate Learning: The next time this customer sends "12.5 whites", Step 2 triggers: Confidence = 1.0 (Instant Green).

5. Accuracy Compounding Over TimeCopy Anchor Link

In pilot deployments, KHOLO demonstrates a rapid compounding accuracy curve: