Skip to content

Product Retrieval Intents

Objective

Define how product-domain data should be retrieved from the marketing BFF, and how natural-language requests should map onto those retrieval patterns.

Retrieval Scope

The current retrieval scope includes:

  • product headers
  • full product records
  • product collections
  • property definitions

Natural-Language Intent Pattern

Product retrieval should support requests such as:

  • which properties are related to solar racking mechanical systems?
  • show me the collections for C&I systems
  • find products in collection X
  • get the full product for key Y

These are not direct endpoint names. They are human retrieval intents that the assistant must resolve into one or more BFF queries.

Current BFF Retrieval Endpoints

Products

  • getProduct(productKey)
  • getProductHeaders(filters)
  • getProductsByKeys(productKeys)
  • getProductCollection(collectionKey)
  • getProductCollections(first, collectionKey)
  • getProductCollectionHeaders(first, query)
  • getProductCollectionsByKeys(collectionKeys)

Properties

  • getProperty(propertyKey)
  • getPropertiesByKeys(propertyKeys)
  • getPropertyHeaders(filters)

Retrieval Resolution Rule

The assistant should resolve natural-language product questions in this order:

  1. identify the target object class
  2. product
  3. collection
  4. property
  5. item
  6. identify whether the request is:
  7. exact lookup
  8. header search
  9. batch lookup
  10. collection expansion
  11. call the smallest BFF endpoint that can answer the question safely
  12. if semantic discovery is needed, use a discovery layer such as MCP before final BFF selection

Discovery Layer Direction

Product retrieval will soon need a discovery layer so domain-language requests can be resolved semantically.

Example:

  • human asks: which properties are related to solar racking mechanical systems?
  • discovery layer expands this into likely property candidates such as:
  • mounting structure
  • pillar type
  • rail type
  • fastener type
  • bracket type
  • assistant then uses BFF retrieval to fetch the relevant properties

The discovery layer should not replace BFF. It should help decide what to ask BFF for.

Retrieval Safety Rules

  • Prefer read-only header/list endpoints before full-object queries when discovery is still ambiguous.
  • Prefer canonical keys returned by BFF.
  • Do not infer object existence from naming similarity alone.
  • If multiple candidate objects match the same natural-language request, return the candidate set before mutating anything.