Natural-language search and conversation models

Two search parameters need a model configured before you can turn them on: nl_query and conversation. Both work inside a normal search request — they change how searchCollection/multiSearch parse and follow up on q, not a separate chat endpoint. For retrieval-augmented answers with citations over your documents, use assistants instead; these two features are lower-level query understanding on the engine itself, and need your own LLM credentials.

Every operation on this page needs a full key.

Natural-language search models

nl_query: true on a search sends the query text to a model that translates "red shoes under $50" into q/filter_by/sort_by for a normal search — the response carries the interpretation in parsed_nl_query. nl_model_id on the search picks which registered model does the translating.

const model = await client.nlSearchModels.createNLSearchModel({
  id: "openai-nl",
  model_name: "gpt-4o-mini",
  api_key: process.env.NL_MODEL_API_KEY!,
  system_prompt: "Translate the shopper's question into query_by/filter_by for a product search.",
  max_bytes: 8192,
  temperature: 0,
});

api_key, api_url and, for Google/Vertex AI, api_version, project_id, access_token and refresh_token are the target model service's own credentials — the platform calls out to your model, not one it hosts. top_p, top_k and stop_sequences are Google-specific sampling controls.

curl -G https://api.aacsearch.com/v1/collections/products/documents/search \
  -H "X-NOVA-API-KEY: $NOVA_SEARCH_KEY" \
  --data-urlencode "q=red shoes under \$50" \
  --data-urlencode "nl_query=true" --data-urlencode "nl_model_id=openai-nl"

nl_query_debug=true returns the model's raw response in parsed_nl_query.llm_response, useful while tuning the system_prompt. nl_query_prompt_cache_ttl (default 86400 seconds) caches the schema prompt built for the model so repeated searches don't resend your whole collection schema.

Conversation models

conversation: true on a search layers multi-turn memory onto the engine's own search, so a follow-up query ("show me it in blue") can be interpreted against the previous turn. conversation_model_id picks the registered model; conversation_id continues a previous exchange.

await client.conversationModels.createConversationModel({
  id: "openai-conversation",
  model_name: "gpt-4o-mini",
  max_bytes: 8192,
  history_collection: "conversation_history",
});

history_collection is a collection you create beforehand — the platform stores each turn's history there. Requiring your own LLM credentials on the model (unlike assistants, which run on the platform's own models) is the trade-off for the engine handling the conversational memory itself:

curl -G https://api.aacsearch.com/v1/collections/products/documents/search \
  -H "X-NOVA-API-KEY: $NOVA_SEARCH_KEY" \
  --data-urlencode "q=show me it in blue" \
  --data-urlencode "conversation=true" \
  --data-urlencode "conversation_model_id=openai-conversation" \
  --data-urlencode "conversation_id=$PREVIOUS_CONVERSATION_ID"

conversation_stream=true streams the conversational answer as Server-Sent Events (data: {"conversation": {"message": "...", "conversation_id": "..."}}, ending with data: [DONE]) after the final event carries the complete search response.

Which one do I want?

See assistants for the platform-hosted alternative.