- A property manager rarely searches like a catalogue specialist.
- They do not always know the exact product title, category path or manufacturer vocabulary.
- A conventional keyword search can recognise “dishwasher”.
- That was the client problem in a property-procurement marketplace built on Medusa.
The client problem
A property manager rarely searches like a catalogue specialist.
They do not always know the exact product title, category path or manufacturer vocabulary. They know the job: replace a dishwasher, stay under budget, use a product that is in stock and receive it quickly.
A conventional keyword search can recognise “dishwasher”. A semantic search can understand the broader meaning. Neither should be allowed to forget “cheapest”, “within two days” or a brand filter the buyer already selected.
That was the client problem in a property-procurement marketplace built on Medusa. We needed natural-language discovery without turning stock, price, supplier access and delivery constraints into suggestions.
We combined three retrieval behaviours inside one commercial search pipeline. Exact language can stay lexical. Broader problem descriptions can use semantic retrieval. Hybrid search can blend both. In every mode, the accepted plan returns to the same Elasticsearch route, where explicit buyer filters and validated business constraints remain authoritative.
The result is not an AI product recommendation detached from commerce. It is a better way to enter a real, governed catalogue search.
The client problem: relevance and eligibility are different questions
Search has two jobs that are easy to confuse.
The first is relevance: which products appear related to what the buyer meant?
The second is eligibility: which products may this buyer actually purchase under the active commercial conditions?
Semantic retrieval can improve the first answer. It can connect “fridge leaking” with parts or products whose descriptions use different words. But it has no authority to decide that a $1,200 item satisfies a $900 ceiling, that unavailable stock is acceptable or that a distant supplier should replace a location filter.
We kept those jobs separate. Retrieval proposes relevant candidates. The established product pipeline applies identity, access, price, availability, delivery, geography and specification rules.
This separation is the core architecture decision. AI changes how the question is understood, not what counts as a valid commercial result.
Choose lexical search when the buyer is already precise
Some queries should not be expanded.
A SKU, manufacturer part number or exact technical phrase is valuable because it is precise. Adding related concepts may dilute it and surface products that sound similar but are operationally wrong.
The planner can therefore select lexical retrieval. In that mode, the rewritten text may normalise or remove irrelevant words, but it cannot introduce concepts the buyer never typed.
If the buyer enters a known part number followed by “compressor”, the search preserves that evidence. Elasticsearch can use the catalogue's exact fields, token-aware matching and existing ranking rules.
The public value is simple: the AI layer knows when not to be creative.
This matters in procurement because a nearly correct component can still be the wrong component. Precision is not an inferior fallback; it is the right retrieval strategy when the buyer supplies an exact identifier.
Use semantic retrieval for problem language
Other buyers describe symptoms or jobs.
“The refrigerator is leaking.” “The dryer takes too long.” “I need something equivalent for this unit.” Those phrases may not share the literal words used in a product title.
Semantic retrieval can connect the intent to meaning represented in the catalogue's semantic text. The planner is allowed to expand concepts only when it explicitly selects semantic mode. That decision is visible in the plan rather than hidden inside an uncontrolled rewrite.
Semantic-first search then executes a filtered semantic request through Elasticsearch. It does not ask a language model to invent or rank a list of products from memory.
That distinction keeps catalogue truth in the catalogue. The model helps formulate the retrieval instruction; Elasticsearch retrieves documents that actually exist.
For the buyer, symptom-based language becomes useful without replacing the merchant's product data with generated answers.
Blend lexical and semantic evidence when both help
Many searches sit between exact and conceptual.
The buyer may name a product family but describe a problem in ordinary language. A hybrid strategy can run the normal lexical request and, when appropriate, a semantic request.
The route compares the two result sets. Products found by both sources are strong overlap candidates. Semantic-only results can broaden discovery. Lexical-only results preserve direct textual matches.
The blend changes according to the strength and size of the lexical result set. When lexical search is already confident, the route can avoid unnecessary semantic work. When lexical results are scarce, semantic candidates can receive more room. A semantic-first plan can make the semantic set primary.
This is not a claim that one fixed blend is universally optimal. It is an implemented operating model that chooses among lexical, hybrid and semantic behaviour instead of forcing every buyer query through the same technique.
Apply the same commercial filters to semantic retrieval
A semantic request is a second Elasticsearch query. It does not automatically inherit every filter attached to the lexical request.
That creates a dangerous failure mode. The lexical result may respect brand, manufacturer, price, supplier, stock, delivery and specification filters while the semantic result quietly ignores one of them. Merging both lists would reintroduce products the buyer explicitly ruled out.
The platform structurally reapplies the active filters to the semantic request before retrieving and merging results. Negative constraints, such as excluded brands or categories, are carried across as well.
Tests verify that active facet filters survive semantic retrieval. The same principle applies to plan-derived hard constraints.
The buyer therefore receives one commercial search, not two incompatible opinions stitched together at the interface.
This is where the work becomes more than adding a vector field. Retrieval quality is useful only when eligibility remains consistent across every branch.
Let explicit buyer controls win over the plan
The interface may already contain structured choices before the buyer asks an AI-assisted question.
They may have selected a brand, set a maximum price, chosen pickup or limited distance. The planner can interpret the text, but it must not silently replace those controls.
When the accepted plan is mapped onto the product query, every explicitly supplied URL filter retains priority. If the buyer selected a $75 ceiling and the model proposes $50, the active buyer ceiling remains $75. If the buyer selected a brand, a model-proposed brand does not overwrite it.
The same precedence applies to category, manufacturers, suppliers, price bounds, distance, specifications, pickup, stock, delivery speed and sorting controls.
This gives the interaction a stable rule: direct buyer action outranks inferred intent.
The plan can fill gaps. It cannot rewrite decisions the buyer has already made visible.
Extract “cheapest” and “nearest” deterministically
Some commercial language is too important to leave entirely to model discretion.
The platform extracts clear price and proximity intent through deterministic controls. “Under $900” becomes a price ceiling grounded in the buyer's text. “Cheapest” forces ascending price order. “Within 30 miles” becomes a distance ceiling. “Closest” forces ascending distance.
If the model proposes a conflicting sort, the deterministic interpretation wins and the rejected value appears in the plan's dropped-field record.
Units are normalised. A radius in kilometres can be converted to miles because the downstream distance contract uses miles.
This makes the most consequential purchasing constraints predictable. The AI can understand broad language around the request, while simple numerical and ordering rules follow code that can be tested directly.
Ground brands, suppliers and specifications in live catalogue truth
A language model can produce a plausible manufacturer or specification that does not exist in the merchant's catalogue.
The plan validator compares proposed brands, manufacturers, suppliers, categories and specification values with live Elasticsearch vocabularies. Unknown values are removed instead of becoming filters that guarantee zero results or misrepresent catalogue structure.
Numeric specifications receive additional care. A bare “17.5” should not automatically become width, capacity or another dimension. When the buyer provides the unit and the catalogue confirms the value, it can become a structured filter. When the number is ambiguous, it remains useful as search text rather than being assigned a fabricated meaning.
The result is a plan built from real catalogue language. AI interpretation cannot manufacture a brand, category or indexed specification simply because it sounds credible.
Preserve stock, pickup, delivery and distance together
Commercial constraints often interact.
Pickup implies that the product must be in stock at an eligible pickup location. A “within 30 miles” request needs the active property context and product-location distance evidence. Delivery-speed filters rely on available shipping-option information. Supplier access can restrict which products the organisation may see.
The plan maps these requests into the existing product-query state. The normal route then applies the underlying availability and access machinery.
This is intentionally different from asking the model to reason about inventory. The model says that the buyer requested pickup. The commerce platform decides which indexed products satisfy pickup under the current context.
Keeping that boundary lets the search layer benefit from natural language while Medusa and its extensions remain responsible for commerce truth.
Relax retrieval text without relaxing the purchase
An accepted plan can still produce zero results. Perhaps the rewritten text is too narrow even though its structured constraints are correct.
The platform can retry Elasticsearch with the buyer's original wording. Crucially, it preserves the validated state: brand, supplier, price, distance, stock, delivery, specifications, category scope and exclusions remain attached.
Only the retrieval text becomes less restrictive.
If the raw lexical retry still returns nothing, the route can continue to a filtered semantic request with those same commercial controls.
This is a useful fail-open behaviour. The buyer gets another chance at relevance without the system “helpfully” dropping the budget or availability requirement.
A fallback should broaden language, not alter the purchase contract.
Test behaviours as buying scenarios
Search safety is easier to understand through scenarios than isolated helper functions.
We exercise the search journey with exact part numbers, category synonyms, brand and manufacturer filters, supplier filters, price ceilings and ranges, dimensions with explicit units, ambiguous numbers, stock, pickup, delivery speed, nearest-property sorting and distance conversion.
Other tests feed the planner imperfect or hostile drafts and verify which fields are retained or dropped. Integration tests confirm URL precedence, semantic filter propagation and fallback constraint preservation.
These tests do not claim a universal relevance score or a production conversion uplift. They prove the behavioural contract we wanted the platform to enforce.
For an operator, that contract is more valuable than “AI-powered search” as a label. It describes what the system will refuse to forget.
Why Medusa was the right foundation
The client needed a search experience shaped by procurement language and governed by commerce reality.
Medusa supplied the product, price, inventory and customer context. Elasticsearch supplied the live searchable catalogue and both lexical and semantic retrieval. We added a bounded planner and mapped its output back into the established route.
Because the platform is extensible, the AI layer could sit in front of commerce instead of beside it. The result still respects the same products, access rules, price lists, stock locations and fulfilment constraints as ordinary search.
That is the architectural advantage: new interpretation capability without creating a second source of commercial truth.
A practical retrieval checklist
Before combining AI and commerce search, define:
- Which queries should remain lexical?
- When may the system expand concepts semantically?
- How are lexical and semantic result sets blended?
- Does semantic retrieval receive every active commercial filter?
- Do excluded brands and categories survive the second request?
- Do explicit buyer controls outrank inferred plan values?
- Are price and proximity language extracted deterministically?
- Are catalogue entities validated against live vocabularies?
- How are ambiguous numerical specifications handled?
- Does pickup imply stock in the query state?
- Does distance use the active property context?
- Can fallback relax text without relaxing constraints?
- Is planner failure allowed to return to ordinary search?
- Are critical buying scenarios executable as tests?
These decisions turn retrieval techniques into a dependable procurement experience.
The broader lesson
The client did not need every query to become semantic.
They needed the platform to choose the right retrieval behaviour while preserving the commercial meaning of the request.
We kept exact language lexical, used semantic retrieval for broader intent and blended both where useful. Every branch returns to the same filtered Elasticsearch pipeline. Buyer-selected controls win, live catalogue vocabularies constrain proposed entities and fallback broadens words without dropping price, stock, delivery or distance.
For the buyer, search becomes more forgiving. For the merchant, the rules remain enforceable. For the platform, AI improves interpretation without becoming the authority on what can be bought.