Search Models
Data structures for unified search across all entity types.
ConversationTurn
A single turn in a conversation history, used to give the server enough context to reformulate a search query.
| Prop | Type | Default | Description |
|---|---|---|---|
role | string | — | Speaker role (e.g. "user", "agent"). Must be non-empty. |
content | string | — | Message text for this turn. Must be non-empty. |
UnifiedSearchRequest
Request model for searching across all entity types in a single call.
| Prop | Type | Default | Description |
|---|---|---|---|
query | string | — | Search query text |
top_k? | integer | 5 | Maximum results per entity type, from 1 through 100. The response may contain fewer than `top_k` results — including zero — when nothing clears the cross-encoder relevance floor (see `retrieval_floor` config). |
threshold? | float | model-specific | Strict cosine-similarity threshold for the vector arm. The FTS arm remains eligible in hybrid mode. Omit it to use the embedding model's default. |
agent_version? | string | — | Filter by agent version (agent_playbooks, user_playbooks) |
playbook_name? | string | — | Filter by playbook name (agent_playbooks, user_playbooks) |
user_id? | string | — | Filter by user ID (profiles, user_playbooks) and identify the user for retrieval-experiment assignment. Required for agent traffic while an experiment is active. At most 255 characters. |
source? | string | — | Exact source filter shared by every selected entity type. Agent playbooks match when any linked source user playbook has this source. Omitted, null, or empty means no source filter. |
request_id? | string | — | Caller correlation ID for the search turn. At most 255 characters. |
tags? | array[string] | — | Match entities having any requested tag (OR semantics). Omitted, null, or empty means no tag filter. |
entity_types? | array[string] | — | Entity types to search ("profiles", "user_playbooks", "agent_playbooks"). When omitted, all three are searched. |
agent_playbook_status_filter? | array[PlaybookStatus] | — | Approval statuses to include for agent_playbooks. When omitted, defaults to [APPROVED, PENDING] so REJECTED playbooks are suppressed. Pass an explicit list to opt into REJECTED items. |
conversation_history? | array[ConversationTurn] | — | Prior conversation turns for context-aware query reformulation |
enable_reformulation? | boolean | false | Enable query reformulation for improved search results |
enable_agent_answer? | boolean | false | Enable agentic answer synthesis when the configured search backend supports it |
search_mode? | SearchMode | "hybrid" | Search mode: "vector", "fts", or "hybrid" |
session_id? | string | — | Agent session this search serves. At most 255 characters. When provided, results already returned to the same session are skipped and the next-best matches are backfilled, so repeated searches within one session surface new items instead of duplicates. Also used for usage attribution. Omit for session-less searches (dashboards, evaluation), which neither read nor record session dedup state. |
interaction_id? | integer | — | Optional positive integer (minimum 1) used to attribute served results to the caller interaction. |
UnifiedSearchResponse
Response model for unified search across all entity types.
Retrieved results are reranked by a cross-encoder and dropped below a per-arm relevance floor (see retrieval_floor in the configuration models). Unified search also omits source user playbooks already represented by returned agent playbooks. As a result, each result array may contain fewer than top_k items — including an empty array — when nothing clears the floor or user playbooks are suppressed. An empty array means nothing was relevant, not that the search failed.
When a retrieval experiment is active, the response includes experiment.
Holdout searches also return success=true, but all learning result arrays are
empty and retrieval is skipped. Dashboard inspection bypasses experiment
assignment.
| Prop | Type | Default | Description |
|---|---|---|---|
success | boolean | — | Whether the search was successful |
profiles? | array[UserProfile] | [] | Matching user profiles |
agent_playbooks? | array[AgentPlaybook] | [] | Matching agent playbooks |
user_playbooks? | array[UserPlaybook] | [] | Matching user playbooks |
reformulated_query? | string | — | The query used after reformulation (None if reformulation disabled) |
degraded? | boolean | false | True when the query embedding could not be generated and the search fell back to full-text (lexical) only. Results are still returned, but without the vector-similarity arm. |
search_mode_effective? | string | — | The search mode actually used. Set to "fts" when the search degraded to full-text-only after an embedding failure; None when the requested mode was used unchanged. |
agent_answer? | string | — | LLM-synthesised answer populated by the agentic backend; None for the classic backend |
agent_trace? | string | — | Reasoning trace behind the agent answer, when available |
rehydrated_text? | string | — | Full source text rehydrated for the matched results, when available |
experiment? | RetrievalExperimentAssignment | — | Active experiment ID and deterministic user arm. Echo both values on publish. Omitted when no experiment applies. |
msg? | string | — | Additional message |
RetrievalExperimentAssignment
Attribution returned by unified, profile, user-playbook, and agent-playbook learning searches while an experiment applies.
| Prop | Type | Default | Description |
|---|---|---|---|
experiment_id | string | — | Active retrieval experiment ID. |
arm | "treatment" | "holdout" | — | Stable user-level assignment. |