- A property manager does not always know the product name hidden in a supplier catalogue.
- They know what happened in the building.
- “I need something to stop a bathroom door slamming.”
- “Find a replacement filter for this unit.”
The client problem
A property manager does not always know the product name hidden in a supplier catalogue.
They know what happened in the building.
“I need something to stop a bathroom door slamming.”
“Find a replacement filter for this unit.”
“Show me an equivalent to this SKU, available nearby and under the property’s budget.”
A conventional e-commerce search box is designed for a different conversation. It is excellent when the shopper types a product name, brand or recognisable keyword. In property procurement, the buyer often arrives with a symptom, a job to complete, an old reference and several commercial constraints at once.
That was the client problem we addressed on a B2B marketplace built with Medusa and Elasticsearch. The answer was not to let a language model search the catalogue freely. It was to give AI one narrow responsibility: translate the buyer’s words into a structured, inspectable search plan. The platform then validates that plan against the real catalogue and executes it through the same commercial rules as every other search.
AI helps interpret the request. It never becomes the catalogue.
Why procurement language breaks the classic search-box model
Retail search assumes that product language and buyer language overlap. Someone searching for “black running shoes size 42” has supplied terms that are likely to appear in titles, descriptions or attributes.
Procurement questions are often indirect.
A maintenance buyer may describe an outcome: reduce noise, remove mould, repair a valve or secure an entrance. They may include a quantity and unit that describe the job rather than the product. “I need 200 feet for three buildings” should not automatically turn every number into a catalogue filter. They may also combine product intent with rules that cannot be negotiated: a maximum price, current stock, an approved supplier, a service radius or a specific brand chosen in the interface.
Keyword search sees words. The business needs an interpretation.
Pure semantic search is not enough either. It can improve recall by connecting related concepts, but a plausible semantic neighbour is not necessarily an eligible product. A result can sound right and still be unavailable, outside the buyer’s geography, hidden from their organisation or more expensive than the explicit ceiling they entered.
The real challenge is therefore twofold:
- understand what the buyer is trying to accomplish;
- preserve every commercial rule that decides what they are allowed and able to buy.
The dangerous shortcut: ask the model for products
The shortest AI implementation sends the natural-language query and a catalogue extract to a model, then asks for recommendations.
It produces an impressive demo because the output reads well. It also collapses several responsibilities into a probabilistic answer.
The model can mention a category that does not exist. It can interpret a manufacturer as a brand, invent a specification value or quietly broaden the request when nothing matches. It may return product identifiers that were never in the supplied context. Even when every suggestion exists, the answer can bypass the established logic for price, availability, organisation access and delivery geography.
For a procurement platform, those are not cosmetic errors. They change the buying decision.
We chose a different contract. The model does not return products. It returns a plan that the application is free to reject, repair or reduce before any catalogue query runs.
Step one: turn the request into a bounded plan
The planner receives the buyer’s words and produces structured JSON. The schema allows a small, explicit set of decisions:
- the retrieval mode, such as lexical, hybrid or semantic;
- cleaned search text;
- recognised catalogue filters;
- deterministic sorting intent, such as nearest or lowest price;
- an optional known SKU when the buyer asks for an equivalent.
This matters because prose is difficult to govern. A structured plan can be validated field by field.
If the model proposes an unsupported filter key, the validator removes it. If it names a category, brand, manufacturer or specification value that is not part of the allowed catalogue vocabulary, that value is rejected. Invalid numeric ranges do not reach Elasticsearch. If a proposed text expansion is not permitted for the chosen retrieval mode, the system falls back to the buyer’s original words.
The model is useful precisely because its authority is small. It can organise ambiguity, but it cannot expand the application’s vocabulary by assertion.
Step two: validate against the catalogue that exists today
A static prompt cannot be the source of truth for a living catalogue.
Suppliers change. Categories evolve. Brands appear. Specification values are added or cleaned up. A value that was valid last month may no longer be a useful filter today.
The search system therefore derives its allowed vocabulary from Elasticsearch catalogue facts. Categories, brands, manufacturers and specification values are supplied to the validation layer from the same search projection that buyers use.
The distinction is subtle but fundamental.
The model may suggest that the query refers to a particular manufacturer. The application decides whether that manufacturer exists. The model may infer a category. The application checks whether that category belongs to the current taxonomy. Language interpretation remains flexible; catalogue identity remains deterministic.
This prevents a common form of AI drift: the answer sounds increasingly polished while becoming less connected to the products the merchant can actually sell.
Step three: extract rules that do not need AI discretion
Not every part of the request belongs in a model prompt.
Some buyer intentions can be handled more reliably with deterministic controls. A request for the “cheapest” viable option has a clear sorting consequence. “Near this property” points to distance ordering. Explicit price and proximity expressions can be parsed and mapped without asking the model to reinterpret their business meaning.
Separating those controls has two benefits.
First, it reduces the number of decisions entrusted to a probabilistic system. Second, it makes the final plan easier to explain. An operator can see that the buyer’s explicit maximum price produced a price filter, while the descriptive part of the request influenced retrieval text.
This is an important design rule for practical AI: use the model where language is genuinely ambiguous, and use code where the application already knows the rule.
Explicit buyer choices always win
The buyer may arrive at natural-language search after using the interface. They may already have selected a brand, price range, distance or other filter in the URL.
Those explicit choices are stronger than an inferred plan.
When the accepted plan is mapped onto the product query, explicitly supplied filters keep priority. The AI layer cannot remove a brand the buyer selected or replace their price ceiling with a broader interpretation. The planner adds understanding around the request; it does not take ownership of the search session.
This protects user intent and makes the feature predictable. A buyer can refine results with familiar controls without wondering whether the assistant will silently undo them on the next query.
For the merchant, it also preserves the existing search contract. AI becomes an additional input to the product route rather than a parallel storefront with different rules.
Execute through the real product-search pipeline
Once validated, the plan is translated into the platform’s Elasticsearch product query.
The retrieval mode can change how candidates are found. Lexical retrieval prioritises the buyer’s actual terms. Semantic retrieval can connect the described problem with related product language. Hybrid retrieval combines both result sets.
But candidate retrieval is only one layer. The product route remains responsible for the commercial reality around those candidates: catalogue visibility, buyer access, stock, pricing and geography.
This is why the planner architecture is safer than asking a model for final recommendations. The AI does not create a second definition of an eligible product. It enters the same search machinery that already knows the marketplace’s constraints.
Medusa remains the commerce engine. Elasticsearch remains the searchable catalogue projection. The AI planner sits before them as an interpreter, not above them as an authority.
Quantity and units are context, not automatically filters
Procurement language contains numbers everywhere.
“Twenty apartments.”
“A 50-foot corridor.”
“Three cases per property.”
“Under $500.”
Treating every number identically creates absurd results. Some numbers describe the job, some describe the required product, and some are commercial constraints.
The structured plan makes those meanings separable. A maximum price can become a deterministic filter. A quantity can remain context for the cleaned query or a later calculation. A measurement should only become a product specification when it maps to a supported catalogue field and value.
That discipline avoids a particularly convincing class of error: a search that returns technically matching products because the model converted an incidental number into the wrong filter.
“Find something like this” needs a real anchor
Equivalent-product search is valuable in procurement because buyers often know an existing SKU even when it is unavailable or no longer approved.
The planner supports a similar-product mode, but only with an auditable anchor SKU. If no valid anchor is present, validation removes that mode and falls back to a broader retrieval strategy.
This prevents the model from inventing the reference item that defines similarity. The buyer or application supplies the anchor; the search system can then look for alternatives around a product that genuinely exists.
The same principle applies beyond SKUs. Whenever an AI feature promises “similar to,” “compatible with” or “replacement for,” the identity of the reference object should come from the application, not from generated prose.
What happens when the plan is imperfect
A production search experience cannot depend on every model response being ideal.
The validation layer is designed to degrade the plan safely. Unsupported fields disappear. Invented catalogue entities are removed. Invalid ranges are discarded. Retrieval modes that lack required inputs fall back to a supported mode. The original buyer text remains available when an expansion cannot be trusted.
This gives the system a useful failure posture: less AI, not less commerce control.
The shopper may receive a more conventional search result when interpretation is weak. The accepted plan still returns to the established product pipeline, where catalogue visibility, price, stock, access and geography are applied. The fallback reduces AI influence instead of creating a bypass around commerce. That trade-off is exactly right for procurement: a modest result that respects the buying contract is better than a brilliant-sounding result that cannot be purchased.
Testing behaviour, not the personality of the model
AI search testing becomes manageable when the contract is expressed as plans and invariants.
The project includes focused scenarios for planner safety, catalogue truth, edge cases, route behaviour and plan-to-query mapping. The tests ask concrete questions:
- Does an unknown category get removed?
- Does a buyer-selected filter keep priority?
- Does “nearest” produce deterministic distance ordering?
- Is semantic expansion blocked outside the modes that permit it?
- Does similar-product search require an anchor?
- Does an invalid plan fall back without broadening commercial access?
These are more durable than testing whether one model response contains a particular sentence. Models and prompts can evolve while the application contract remains stable.
A practical architecture for bounded AI search
For teams designing the same capability, the sequence is straightforward.
- Start with the buyer language that keyword search cannot express well.
- Define the smallest structured plan that captures the needed ambiguity.
- Populate allowed entities from the live catalogue, not a static prompt.
- Validate every model-proposed field as untrusted input.
- Keep explicit UI filters and deterministic controls authoritative.
- Execute the accepted plan through the existing product-search pipeline.
- Define safe fallbacks that reduce AI influence without reducing commerce rules.
- Test invariants and scenarios at the plan boundary.
This architecture does not make AI invisible. It makes AI accountable.
What the merchant gains
The buyer gets a search box that understands more of the way procurement work is actually described. They can begin with a symptom, an outcome, a known reference or a mixture of natural language and explicit constraints.
The merchant keeps control of the catalogue. Categories and brands cannot be invented into existence. Price, stock, access and geography remain application decisions. Existing filters continue to behave as buyers expect.
And the product team gains a feature it can evolve. Retrieval strategies can improve, models can change and new procurement vocabulary can be added without handing the entire buying journey to a black box.
That is why we chose Medusa and Elasticsearch as foundations rather than replacing the commerce stack with an AI answer engine. They gave us stable product and commercial contracts. We added a bounded interpretation layer where the client’s procurement use case demanded one.
If your buyers know the job they need to complete but not the exact catalogue language, WeAreSouk can help map that gap and design an AI search layer that improves discovery without surrendering control of the buying rules.