Skip to main content

​
Interaction Signals

Capture implicit user behavior — clicks, views, dwell time, purchases — to feed into retrieval optimization. 
curl -X POST "https://api.mixpeek.com/v1/retrievers/$RETRIEVER_ID/interactions" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": "exec_abc",
    "document_id": "doc_xyz",
    "signal_type": "click",
    "position": 3,
    "metadata": { "dwell_time_ms": 4500 }
  }'

​
Signal Strength

SignalWeightWhen to track
impressionLowDocument appeared in results
clickMediumUser clicked a result
viewMediumUser viewed the detail page
dwellHighUser spent significant time
purchase / convertHighestUser completed a goal action
Track position for every signal — it’s critical for learning which results should rank higher. Interaction API →

​
Fusion Strategies

When a retriever has multiple search stages, fusion strategies determine how scores combine into the final ranking.
StrategyHow it worksBest for
RRF (Reciprocal Rank Fusion)Combines ranks, not scores. 1/(k + rank)Default — works well with no tuning
DBSF (Distribution-Based Score Fusion)Normalizes score distributions then averagesWhen scores have different scales
WeightedManual weights per stageWhen you know which stage matters more
MaxTakes the highest score across stagesWhen any match is sufficient
LearnedAuto-tunes weights from interaction signalsWhen you have 500+ interactions
Configure fusion on the retriever: 
{
  "fusion_strategy": {
    "type": "learned",
    "fallback": "rrf",
    "min_interactions": 500
  }
}
Learned fusion uses Thompson Sampling to automatically shift weight toward stages that produce results users engage with. It starts with the fallback strategy and transitions as interactions accumulate.

​
Evaluations

Measure retriever quality against ground truth datasets with standard IR metrics. 
# Create a ground truth dataset
curl -X POST "https://api.mixpeek.com/v1/retrievers/$RETRIEVER_ID/evaluations/datasets" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_name": "product-search-eval",
    "queries": [
      { "query": {"query_text": "wireless headphones"}, "relevant_document_ids": ["doc_1", "doc_2"] }
    ]
  }'

# Run evaluation
curl -X POST "https://api.mixpeek.com/v1/retrievers/$RETRIEVER_ID/evaluations" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{ "dataset_id": "'$DATASET_ID'", "limit": 20 }'
Returns Precision, Recall, F1, NDCG, MAP, and MRR at configurable cutoffs. Use evaluations to compare retriever configurations before deploying changes. Evaluation API →

​
Analytics

Monitor retriever performance in production:
  • Stage latency breakdown — identify which stages are slow
  • Cache hit rates — verify caching is effective
  • Score distributions — detect relevance drift
  • Query patterns — understand what users search for
Use the analytics endpoints to build dashboards or trigger alerts on degradation.

​
The Feedback Loop

Search → Results → User interacts → Signal captured → Fusion learns → Better results
  1. Users search via retrievers
  2. Interaction signals capture what they engage with
  3. Learned fusion adjusts stage weights automatically
  4. Annotations provide explicit ground truth for edge cases
  5. Evaluations measure improvement quantitatively
  6. The cycle repeats — retrieval improves with usage