Query understanding

Step 01

Define and Align

Review search examples and annotate the intent, constraints, or judgments that need to change. Explain how your relevance policy handles edge cases.

Output schema

IntentChoose one: Whether the user wants products, an explanation, or a known destination.
product_search
informational
navigational
EntitiesList of values: The things the user is seeking; exclude negated alternatives.
ConstraintsList of values: Explicit requirements and exclusions from the query.
AmbiguityChoose one: Whether essential information for fulfilling the query is missing.
clear
needs_clarification
Clarification questionText · optional: A focused question when clarification is needed; otherwise unknown.

app.sutro.sh/functions/query-understanding

Collecting feedback · 1/3

Interpret the query without inventing entities, compatibility requirements, or user context.

Example 1 of 3

A negated product is not the target

Model input

Query: 13-inch laptop sleeve, not a charger
Search context: Product catalog search. No other user context is available.
Query policy: Product search seeks an item. Informational queries ask for an explanation or instructions. Navigational queries seek a known page or site. Preserve explicit constraints and exclusions. Ask for essential missing compatibility details rather than assuming them.

Model output

Intent

EntitiesMultiple values

ConstraintsMultiple values

Ambiguity

Clarification question

Why? Optional guidance

Step 02

Model Sweep

Compare models against the same expert annotations and choose your quality–cost tradeoff.

Compare models on expert agreement and cost. The interactive chart uses illustrative measurements.

Illustrative sweep · select Value or Best to use that model in your function.

Step 03

Deployment

Call Sutro Functions like any other software. Swap the model as soon as something more performant is released.

Selected modelWaiting for sweep results.

Real-time

import sutro as so

input_data = {
    "query": "13-inch laptop sleeve, not a charger",
    "search_context": "Product catalog search. No other user context is available.",
    "query_policy": "Product search seeks an item. Informational queries ask for an explanation or instructions. Navigational queries seek a known page or site. Preserve explicit constraints and exclusions. Ask for essential missing compatibility details rather than assuming them."
}

result = so.run_function(
    "query-understanding",
    input_data,
)

curl --fail-with-body -X POST "${SUTRO_API_URL%/}/v1/functions/query-understanding/run" \
  -H "Authorization: Key $SUTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "query": "13-inch laptop sleeve, not a charger",
    "search_context": "Product catalog search. No other user context is available.",
    "query_policy": "Product search seeks an item. Informational queries ask for an explanation or instructions. Navigational queries seek a known page or site. Preserve explicit constraints and exclusions. Ask for essential missing compatibility details rather than assuming them."
  }
}'

Batch

import sutro as so

job_id = so.batch_run_function(
    name="query-understanding",
    data="query_understanding.csv",
)
results = so.await_job_completion(job_id)

curl --fail-with-body -X POST "${SUTRO_API_URL%/}/v1/batch-inference" \
  -H "Authorization: Key $SUTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "query-understanding",
  "inputs": [
    {
      "query": "13-inch laptop sleeve, not a charger",
      "search_context": "Product catalog search. No other user context is available.",
      "query_policy": "Product search seeks an item. Informational queries ask for an explanation or instructions. Navigational queries seek a known page or site. Preserve explicit constraints and exclusions. Ask for essential missing compatibility details rather than assuming them."
    }
  ]
}'