feat(auto-tune): SDK convenience for closing the feedback loop

Add create_interaction_from_result() and create_interactions_batch()
helpers that auto-extract feature_id, position, execution_id, and
feature_uri from search results — one-liner interaction creation.

Add examples/auto_tune.py showing full lifecycle: create retriever with
learned fusion → execute → record interaction → verify personalization.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: esteininger

examples/auto_tune.py

@@ -0,0 +1,169 @@
+"""
+Mixpeek Auto-Tune Example — Learned Fusion + Interaction Feedback Loop
+
+Demonstrates:
+  1. Creating a retriever with learned fusion (multi-feature, bandit-learned weights)
+  2. Executing a search query
+  3. Recording user interactions to train the learned fusion model
+  4. Verifying personalisation by re-querying
+
+Before running, set your environment:
+
+    export MIXPEEK_API_KEY="your_api_key_here"
+    export MIXPEEK_NAMESPACE="your_namespace_id"
+"""
+
+from mixpeek import Mixpeek, ApiException
+from mixpeek_dev.interactions import create_interaction_from_result
+
+
+def main():
+    try:
+        client = Mixpeek()
+    except ValueError as e:
+        print(f"Error: {e}")
+        print("Set MIXPEEK_API_KEY and MIXPEEK_NAMESPACE environment variables.")
+        return
+
+    print("Mixpeek Auto-Tune Example\n")
+
+    # ----------------------------------------------------------------
+    # 1. Create a retriever with learned fusion
+    # ----------------------------------------------------------------
+    print("1. Creating retriever with learned fusion...")
+
+    retriever_config = {
+        "name": "auto_tune_demo",
+        "stages": [
+            {
+                "stage_type": "search",
+                "stage_id": "multi_feature_search",
+                "config": {
+                    "queries": [
+                        {
+                            "feature_uri": "mixpeek://text-embedding@latest/description",
+                            "query_input": {"type": "text", "value": "INPUT.query"},
+                        },
+                        {
+                            "feature_uri": "mixpeek://text-embedding@latest/title",
+                            "query_input": {"type": "text", "value": "INPUT.query"},
+                        },
+                    ],
+                    "parameters": {
+                        "limit": 20,
+                        "fusion_strategy": {
+                            "fusion": "learned",
+                            "learning_config": {
+                                "context_features": ["INPUT.user_id"],
+                                "reward_signal": "click",
+                            },
+                        },
+                    },
+                },
+            }
+        ],
+    }
+
+    try:
+        retriever = client.retrievers.create(**retriever_config)
+        retriever_id = retriever["retriever_id"]
+        print(f"   Created retriever: {retriever_id}")
+    except ApiException as e:
+        print(f"   Error creating retriever: {e.reason}")
+        return
+
+    # ----------------------------------------------------------------
+    # 2. Execute a search query
+    # ----------------------------------------------------------------
+    print("\n2. Executing search query...")
+
+    user_id = "user_123"
+    session_id = "sess_abc"
+    query = "comfortable running shoes"
+
+    try:
+        results = client.retrievers.execute(
+            retriever_id,
+            inputs={
+                "query": query,
+                "user_id": user_id,
+                "session_id": session_id,
+            },
+        )
+        documents = results.get("documents", [])
+        print(f"   Got {len(documents)} results")
+        for i, doc in enumerate(documents[:5]):
+            score = doc.get("score", 0)
+            doc_id = doc.get("document_id", "?")
+            print(f"   [{i}] {doc_id} (score: {score:.4f})")
+    except ApiException as e:
+        print(f"   Search error: {e.reason}")
+        return
+
+    if not documents:
+        print("   No documents returned. Add data to your collection first.")
+        return
+
+    # ----------------------------------------------------------------
+    # 3. Record a user interaction (click on 3rd result)
+    # ----------------------------------------------------------------
+    print("\n3. Recording interaction (click on result #2)...")
+
+    clicked_index = 2 if len(documents) > 2 else 0
+    try:
+        interaction = create_interaction_from_result(
+            client=client,
+            retriever_id=retriever_id,
+            result=documents[clicked_index],
+            interaction_type=["click"],
+            position=clicked_index,
+            user_id=user_id,
+            session_id=session_id,
+            execution_response=results,
+            query_snapshot={"query": query},
+        )
+        print(f"   Recorded interaction: {interaction.get('interaction_id', '?')}")
+    except Exception as e:
+        print(f"   Interaction error: {e}")
+
+    # ----------------------------------------------------------------
+    # 4. Re-query to see personalised results
+    # ----------------------------------------------------------------
+    print("\n4. Re-querying with same user (weights should start adapting)...")
+
+    try:
+        results2 = client.retrievers.execute(
+            retriever_id,
+            inputs={
+                "query": query,
+                "user_id": user_id,
+                "session_id": session_id,
+            },
+        )
+        documents2 = results2.get("documents", [])
+        print(f"   Got {len(documents2)} results")
+        for i, doc in enumerate(documents2[:5]):
+            score = doc.get("score", 0)
+            doc_id = doc.get("document_id", "?")
+            print(f"   [{i}] {doc_id} (score: {score:.4f})")
+    except ApiException as e:
+        print(f"   Re-query error: {e.reason}")
+
+    # ----------------------------------------------------------------
+    # 5. Clean up
+    # ----------------------------------------------------------------
+    print("\n5. Cleaning up...")
+    try:
+        client.retrievers.delete(retriever_id)
+        print(f"   Deleted retriever: {retriever_id}")
+    except ApiException as e:
+        print(f"   Cleanup error: {e.reason}")
+
+    print("\nAuto-Tune demo complete!")
+    print("\nThe learned fusion model improves over time as more interactions")
+    print("are recorded. In production, weights adapt per-user based on the")
+    print("context_features configured in learning_config.")
+
+
+if __name__ == "__main__":
+    main()

mixpeek_dev/interactions.py

@@ -0,0 +1,200 @@
+"""Convenience helpers for recording retriever interactions.
+
+These utilities auto-populate interaction fields from search results,
+reducing boilerplate when integrating feedback loops (Auto-Tune).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING, Union
+
+if TYPE_CHECKING:
+    from mixpeek._client.client import Mixpeek
+
+
+def create_interaction_from_result(
+    client: Mixpeek,
+    retriever_id: str,
+    result: Dict[str, Any],
+    interaction_type: List[str],
+    *,
+    position: Optional[int] = None,
+    user_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    execution_id: Optional[str] = None,
+    query_snapshot: Optional[Dict[str, Any]] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    result_set_size: Optional[int] = None,
+    execution_response: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Create an interaction from a retriever result document.
+
+    Auto-extracts ``feature_id``, ``document_score``, and ``execution_id``
+    from the result document and/or the full execution response so callers
+    don't have to pluck them out manually.
+
+    Args:
+        client: An initialised ``Mixpeek`` client instance.
+        retriever_id: The retriever that produced the results.
+        result: A single document dict from the execution response's
+            ``documents`` list.  The helper looks for ``document_id``
+            (or ``feature_id``), ``score``, and payload metadata.
+        interaction_type: One or more interaction type strings
+            (e.g. ``["click"]``, ``["view", "long_view"]``).
+        position: 0-indexed position of the result.  If *None* and the
+            result dict contains a ``position`` key, that value is used.
+            Falls back to ``0``.
+        user_id: Persistent user identifier for personalisation.
+        session_id: Ephemeral session identifier.
+        execution_id: Explicit execution ID.  Auto-extracted from
+            *execution_response* or from the result's metadata when not
+            provided.
+        query_snapshot: The original query input dict.  Recommended for
+            training optimisation.
+        metadata: Extra context (device, viewport, duration, etc.).
+            The helper merges in ``feature_uri`` from the result's
+            payload when present.
+        result_set_size: Total results shown to the user.  Auto-extracted
+            from *execution_response* when not provided.
+        execution_response: The full dict returned by
+            ``client.retrievers.execute()``.  Used to auto-populate
+            ``execution_id`` and ``result_set_size``.
+
+    Returns:
+        The API response dict (contains ``interaction_id`` and
+        ``timestamp``).
+
+    Example::
+
+        results = client.retrievers.execute(
+            retriever_id, inputs={"query": "shoes", "user_id": "u1"}
+        )
+        create_interaction_from_result(
+            client=client,
+            retriever_id=retriever_id,
+            result=results["documents"][2],
+            interaction_type=["click"],
+            user_id="u1",
+            execution_response=results,
+        )
+    """
+    # --- feature_id --------------------------------------------------------
+    feature_id = (
+        result.get("feature_id")
+        or result.get("document_id")
+        or result.get("id")
+    )
+    if not feature_id:
+        raise ValueError(
+            "Cannot determine feature_id from result dict. "
+            "Expected 'feature_id', 'document_id', or 'id' key."
+        )
+
+    # --- position ----------------------------------------------------------
+    if position is None:
+        position = result.get("position", 0)
+
+    # --- document_score ----------------------------------------------------
+    document_score = result.get("score")
+
+    # --- execution_id (from explicit arg, execution_response, or result) ---
+    if execution_id is None and execution_response is not None:
+        execution_id = execution_response.get("execution_id")
+    if execution_id is None:
+        execution_id = result.get("execution_id")
+
+    # --- result_set_size ---------------------------------------------------
+    if result_set_size is None and execution_response is not None:
+        docs = execution_response.get("documents")
+        if docs is not None:
+            result_set_size = len(docs)
+
+    # --- metadata enrichment -----------------------------------------------
+    merged_metadata: Dict[str, Any] = {}
+    # Pull feature_uri from payload if present
+    payload = result.get("payload", {})
+    if isinstance(payload, dict):
+        feature_uri = payload.get("feature_uri")
+        if feature_uri:
+            merged_metadata["feature_uri"] = feature_uri
+    if metadata:
+        merged_metadata.update(metadata)
+
+    # --- build request body ------------------------------------------------
+    body: Dict[str, Any] = {
+        "feature_id": feature_id,
+        "interaction_type": interaction_type,
+        "position": position,
+        "retriever_id": retriever_id,
+    }
+    if user_id is not None:
+        body["user_id"] = user_id
+    if session_id is not None:
+        body["session_id"] = session_id
+    if execution_id is not None:
+        body["execution_id"] = execution_id
+    if query_snapshot is not None:
+        body["query_snapshot"] = query_snapshot
+    if document_score is not None:
+        body["document_score"] = document_score
+    if result_set_size is not None:
+        body["result_set_size"] = result_set_size
+    if merged_metadata:
+        body["metadata"] = merged_metadata
+
+    return client._request(
+        "POST",
+        f"/retrievers/{retriever_id}/interactions",
+        body=body,
+    )
+
+
+def create_interactions_batch(
+    client: Mixpeek,
+    retriever_id: str,
+    results: List[Dict[str, Any]],
+    interaction_type: List[str],
+    *,
+    user_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    execution_response: Optional[Dict[str, Any]] = None,
+    query_snapshot: Optional[Dict[str, Any]] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> List[Dict[str, Any]]:
+    """Record interactions for multiple results in one call.
+
+    Convenience wrapper that calls ``create_interaction_from_result`` for
+    each result, using the list index as the position.
+
+    Args:
+        client: An initialised ``Mixpeek`` client.
+        retriever_id: The retriever that produced the results.
+        results: List of result dicts (e.g. all results the user saw).
+        interaction_type: Interaction type(s) to record for every result.
+        user_id: Persistent user identifier.
+        session_id: Ephemeral session identifier.
+        execution_response: Full execution response (for auto-extraction).
+        query_snapshot: Original query input dict.
+        metadata: Extra context dict applied to every interaction.
+
+    Returns:
+        List of API response dicts.
+    """
+    responses = []
+    result_set_size = len(results)
+    for idx, result in enumerate(results):
+        resp = create_interaction_from_result(
+            client=client,
+            retriever_id=retriever_id,
+            result=result,
+            interaction_type=interaction_type,
+            position=idx,
+            user_id=user_id,
+            session_id=session_id,
+            execution_response=execution_response,
+            query_snapshot=query_snapshot,
+            metadata=metadata,
+            result_set_size=result_set_size,
+        )
+        responses.append(resp)
+    return responses