The catalogue is the real retail knowledge base

On the Thursday before a month-end weekend, a grandmother in Soweto asks the meal assistant for "pap and wors for Saturday, ten people, and amasi for the morning". The plan comes back quickly: maize meal, boerewors, a tomato-and-onion relish. Then a polite apology: amasi is not available, and here is a Greek yoghurt instead. Her local store had amasi on the shelf. The catalogue listed it as "Maas, fermented milk, 2 L", and nothing in the search index connected that name to the word she used.

Anyone reading that conversation would blame the model. That is the trap: catalogue failures arrive dressed as AI failures, and teams spend weeks tuning prompts for a problem that lives in product data.

Ubuntu Grocer is a composite, a fictional South African grocery retailer whose scenario draws on lessons from real retail-agent delivery; its people, systems and figures are illustrative. Part 4 showed that hard constraints are filters over catalogue attributes. This part is about whether those attributes, and everything else the agent needs, are actually there.

Most of the agent's answers come from the catalogue

Walk the journey and count where each decision gets its facts. The meal plan comes from the model, constrained by the shopper. Almost everything after that comes from product data: which product matches "amasi", whether it contains peanuts, whether it is halaal-certified, what pack sizes exist, which product is an acceptable substitute, what it costs at this store and whether it is in stock.

For the language model (LLM) the catalogue plays the role a document collection plays in retrieval-augmented generation (RAG): it is the knowledge the answer is built from. But it is stricter knowledge. A slightly stale document gives a slightly stale answer; a wrong allergen field gives an unsafe basket.

Sipho Nkosi, Ubuntu Grocer's catalogue and product-data owner, had made the catalogue good enough for a website, where a person reads the pack photo and decides. The assistant needs data a machine can decide on without the photo.

Anatomy of a product record an agent can use

The record that served the website well was mostly a name, a photo, a price and a category. The record the agent needs has seven parts.

• Identity. A stable internal product identifier, the barcode identifiers that map to it, and its variant family. Pack sizes are separate products: the GS1 GTIN Management Standard requires a new Global Trade Item Number (GTIN) whenever declared net content changes, and when a certification mark such as halaal or kosher is added to or removed from the pack. Reformulation is less tidy: it needs a new GTIN only if it alters legally required pack information and the brand owner expects shoppers to notice. And a certificate can lapse with no pack change at all. The barcode alone does not prove the allergens or the certification are current.
• Names and synonyms. The display name, plus the words shoppers actually use: amasi and maas, mealie meal and maize meal, wors and boerewors, morogo for leafy greens. Mixed-language requests are normal, not edge cases.
• Taxonomy. Where the product sits, at a depth the matcher can use: "dairy, fermented milk" rather than "dairy". The ingredient-to-product matcher from part 3 maps canonical ingredients to categories first.
• Attributes. Allergen "contains" and "may contain" fields, dietary certifications with the certifier and expiry, pack size with a normalised unit, storage type (fresh, frozen, pantry). These are the fields the hard filter reads.
• Relationships. Acceptable substitutes, variants and complements, with the substitution rules that apply.
• Commerce and stock. Price, promotions and stock per store or fulfilment node. These change by the hour and are always looked up live.
• Provenance. For each field: where it came from, who owns it, when it was last confirmed and which version is current.

The last part is the one most catalogues lack, and it is the one that makes the others trustworthy. A field without provenance cannot be used for a hard constraint, because nobody can say whether it is true.

Retrieval is a pipeline, and availability belongs inside it

Finding "amasi" is a retrieval problem, and Ubuntu Grocer's matcher uses the same pattern as a good document search: keyword and vector search side by side, results fused, then a re-ranking step. Our articles on why vector search alone is not enough and hybrid search explain the mechanics. Here, the order of the steps around retrieval matters more than the algorithm.

1. Reformulate. A smaller model turns "amasi for the morning" into a canonical ingredient and a few search terms, including known synonyms.
2. Search two ways, filtered. Keyword search catches exact names, brand words and pack sizes such as "2 L". Vector search catches meaning when the words differ. Both queries carry the hard filter from part 4 as a pre-filter on attributes.
3. Fuse the two ranked lists into one.
4. Join availability for the shopper's store or fulfilment node, live.
5. Re-rank only what is left, with the LLM, using the shopper's soft preferences.

Where the hard filter runs matters. Filtering after fusion looks equivalent, but it is a recall trap: if every product in a fused top 30 contains peanuts or lacks certification, post-filtering silently empties the list and the assistant reports "not available" for something the store stocks. Push the filter into both queries, or over-fetch generously where an index cannot filter.

Two more rules follow. First, never put price or stock into the embedding or the index text. They change too often, and an index that "knows" a product is in stock is an index that is wrong by lunchtime. Embed what a product is; look up what it costs and whether it is there. Second, join availability before re-ranking, not after. Re-ranking is the expensive step, and spending it on products the store cannot supply produces a confident first choice that must then be silently replaced.

In our worked example, for illustration only, the filtered searches for "amasi" return 8 eligible products, 3 are in stock at the shopper's store, and the re-ranker chooses between those three real options.

Catalogue quality shows up as answer quality

Because unknown attributes are excluded by the hard filter, a thin catalogue does not usually produce wrong answers. It produces small ones: fewer eligible products, more "not available", more recipes that cannot be completed. That makes catalogue quality measurable from the assistant's own behaviour, and Ruan Botha's team tracks it as part of answer quality rather than as a separate data project.

• Zero-result ingredient lines. How often a canonical ingredient finds no candidate at all: say, 3% of ingredient lines in a month, for illustration. Each one is a missing synonym, a taxonomy gap or a range gap, and the list is a work queue for the catalogue team.
• Excluded for unknown. How many candidates the hard filter removed because a field was blank, by category and by supplier.
• Synonym yield. How often a match came through a synonym rather than the display name. A sudden drop usually means a synonym list was overwritten.
• Availability freshness. How old the stock figure was when it was used.

This is the discipline of evaluating retrieval separately from the answer, applied to products. The amasi failure would have shown up as a zero-result line weeks before a grandmother found it.

Synonyms need one more rule. A model is good at proposing them from zero-result searches, but it is not the right authority to approve them. "Maas" for amasi is correct. "Yoghurt" for amasi is a substitution, which is a commercial and sometimes dietary decision. Proposed synonyms go to a person in Sipho's team, and approved ones become data.

Name an owner for every field

The deeper fix was organisational. When the team traced each field the agent relies on, several had no owner at all, and two had three.

The table answers the question every incident review eventually asks: who should have known that field was wrong? Our article on how AI projects expose weak data ownership explains why this question is usually harder than the technology.

The trade-offs

Curation costs money and never finishes. Ubuntu Grocer prioritised by journey impact: the categories that appear most often in meal plans, and the attributes that hard constraints depend on, came first. Long-tail fields waited.

Supplier data is uneven: some suppliers send structured allergen data, others a photo of the pack. A model can propose values from pack images, but a proposed allergen value is not confirmed until a person or a trusted feed confirms it.

Questions to take into your architecture review

1. Which fields does the agent rely on for hard constraints, and what percentage of eligible products have each field filled and confirmed?
2. Does every field have a recorded source, owner and last-confirmed date?
3. How are pack sizes and variants identified, and how does the system detect a reformulation that kept its barcode?
4. Where do synonyms and local-language terms come from, and who approves them?
5. Is price or stock anywhere in the index or embeddings?
6. Is availability joined before the re-ranking step, and for the shopper's actual store or node?
7. What is the zero-result rate for ingredient lines this month, and who works the list?
8. Can you show an incident where catalogue data was the cause, and how it was traced?

Key points

• Catalogue failures look like model failures. Check the product data before tuning the prompt.
• An agent-ready product record has identity, names and synonyms, taxonomy, attributes, relationships, live commerce data and provenance.
• Retrieval is a pipeline: reformulate, search two ways with the hard filter inside both queries, fuse, join live availability, then re-rank.
• Never embed price or stock. Embed what a product is; look up what it costs and whether it is there.
• Measure catalogue quality from the assistant's behaviour, and give every field the agent depends on a named owner.

CloudNala's point of view

The most valuable AI investment many retailers can make this year is in their product data, and it will not look like AI work. In reviews of retail-agent programmes, the teams that do best treat the catalogue as a governed product with owners, service levels and a backlog fed by the assistant's own failures. A better model on a thin catalogue still recommends Greek yoghurt to someone who asked for amasi.

Next: Part 6, Design the agent boundary before the agent. All parts are on the series page.

Background reading: GS1 GTIN Management Standard, release 1.1, and the GTIN allocation rules fact sheet (GS1 New Zealand, version 2, December 2021), both checked on 5 November 2026.

How CloudNala can help

CloudNala runs catalogue readiness assessments for retail assistants. We trace the fields each step of the journey depends on, measure coverage and provenance, review the retrieval pipeline and where availability is joined, set up zero-result and excluded-for-unknown reporting, and help you assign owners, so that the catalogue can carry the decisions the agent is being asked to make.

Work with CloudNala

CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.

Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.

Book an Agentic Retail Review or write to us at consult@cloudnala.co.za