orca-sdk 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

orca_sdk/telemetry.py

@@ -1,34 +1,49 @@
 from __future__ import annotations
 
 import logging
+import os
+from abc import ABC
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Iterable, overload
-from uuid import UUID
-
-from orca_sdk._utils.common import UNSET
-
-from ._generated_api_client.api import (
-    drop_feedback_category_with_data,
-    get_prediction,
-    list_feedback_categories,
-    list_predictions,
-    record_prediction_feedback,
-    update_prediction,
-)
-from ._generated_api_client.models import (
-    FeedbackType,
+from typing import TYPE_CHECKING, Any, Iterable, Literal, Self, overload
+
+from httpx import Timeout
+
+from ._utils.common import UNSET
+from .client import (
     LabelPredictionWithMemoriesAndFeedback,
-    ListPredictionsRequest,
+    OrcaClient,
     PredictionFeedbackCategory,
     PredictionFeedbackRequest,
+    ScorePredictionWithMemoriesAndFeedback,
     UpdatePredictionRequest,
 )
-from ._generated_api_client.types import UNSET as CLIENT_UNSET
-from ._utils.prediction_result_ui import inspect_prediction_result
-from .memoryset import LabeledMemoryLookup, LabeledMemoryset
+from .memoryset import (
+    LabeledMemoryLookup,
+    LabeledMemoryset,
+    ScoredMemoryLookup,
+    ScoredMemoryset,
+)
 
 if TYPE_CHECKING:
     from .classification_model import ClassificationModel
+    from .regression_model import RegressionModel
+
+TelemetryMode = Literal["off", "on", "sync", "async"]
+"""
+Mode for saving telemetry. One of:
+
+- `"off"`: Do not save telemetry
+- `"on"`: Save telemetry asynchronously unless the `ORCA_SAVE_TELEMETRY_SYNCHRONOUSLY` environment variable is set.
+- `"sync"`: Save telemetry synchronously
+- `"async"`: Save telemetry asynchronously
+"""
+
+
+def _get_telemetry_config(override: TelemetryMode | None = None) -> tuple[bool, bool]:
+    return (
+        override != "off",
+        os.getenv("ORCA_SAVE_TELEMETRY_SYNCHRONOUSLY", "0") != "0" or override == "sync",
+    )
 
 
 def _parse_feedback(feedback: dict[str, Any]) -> PredictionFeedbackRequest:
@@ -38,12 +53,15 @@ def _parse_feedback(feedback: dict[str, Any]) -> PredictionFeedbackRequest:
     prediction_id = feedback.get("prediction_id", None)
     if prediction_id is None:
         raise ValueError("`prediction_id` must be specified")
-    return PredictionFeedbackRequest(
-        prediction_id=prediction_id,
-        category_name=category,
-        value=feedback.get("value", CLIENT_UNSET),
-        comment=feedback.get("comment", CLIENT_UNSET),
-    )
+    output: PredictionFeedbackRequest = {
+        "prediction_id": prediction_id,
+        "category_name": category,
+    }
+    if "value" in feedback:
+        output["value"] = feedback["value"]
+    if "comment" in feedback:
+        output["comment"] = feedback["comment"]
+    return output
 
 
 class FeedbackCategory:
@@ -67,11 +85,10 @@ class FeedbackCategory:
     created_at: datetime
 
     def __init__(self, category: PredictionFeedbackCategory):
-        # for internal use only, do not document
-        self.id = category.id
-        self.name = category.name
-        self.value_type = bool if category.type == FeedbackType.BINARY else float
-        self.created_at = category.created_at
+        self.id = category["id"]
+        self.name = category["name"]
+        self.value_type = bool if category["type"] == "BINARY" else float
+        self.created_at = datetime.fromisoformat(category["created_at"])
 
     @classmethod
     def all(cls) -> list[FeedbackCategory]:
@@ -81,7 +98,8 @@ class FeedbackCategory:
         Returns:
             List with information about all existing feedback categories.
         """
-        return [FeedbackCategory(category) for category in list_feedback_categories()]
+        client = OrcaClient._resolve_client()
+        return [FeedbackCategory(category) for category in client.GET("/telemetry/feedback_category")]
 
     @classmethod
     def drop(cls, name: str) -> None:
@@ -98,113 +116,163 @@ class FeedbackCategory:
         Raises:
             LookupError: If the category is not found.
         """
-        drop_feedback_category_with_data(name)
-        logging.info(f"Dropped feedback category {name} with all associated feedback")
+        client = OrcaClient._resolve_client()
+        client.DELETE("/telemetry/feedback_category/{name_or_id}", params={"name_or_id": name})
+        logging.info(f"Deleted feedback category {name} with all associated feedback")
 
     def __repr__(self):
         return "FeedbackCategory({" + f"name: {self.name}, " + f"value_type: {self.value_type}" + "})"
 
 
-class LabelPrediction:
-    """
-    A prediction made by a model
+class AddMemorySuggestions:
+    suggestions: list[tuple[str, str]]
+    memoryset_id: str
+    model_id: str
+    prediction_id: str
 
-    Attributes:
-        prediction_id: Unique identifier for the prediction
-        label: Predicted label for the input value
-        label_name: Name of the predicted label
-        confidence: Confidence of the prediction
-        memory_lookups: List of memories used to ground the prediction
-        input_value: Input value that this prediction was for
-        model: Model that was used to make the prediction
-        memoryset: Memoryset that was used to lookup memories to ground the prediction
-        expected_label: Optional expected label that was set for the prediction
-        tags: tags that were set for the prediction
-        feedback: Feedback recorded, mapping from category name to value
-    """
+    def __init__(self, suggestions: list[tuple[str, str]], memoryset_id: str, model_id: str, prediction_id: str):
+        self.suggestions = suggestions
+        self.memoryset_id = memoryset_id
+        self.model_id = model_id
+        self.prediction_id = prediction_id
 
-    prediction_id: str
-    label: int
-    label_name: str | None
+    def __repr__(self):
+        return (
+            "AddMemorySuggestions({"
+            + f"suggestions: {self.suggestions}, "
+            + f"memoryset_id: {self.memoryset_id}, "
+            + f"model_id: {self.model_id}, "
+            + f"prediction_id: {self.prediction_id}"
+            + "})"
+        )
+
+    def apply(self) -> None:
+        memoryset = LabeledMemoryset.open(self.memoryset_id)
+        label_name_to_label = {label_name: label for label, label_name in enumerate(memoryset.label_names)}
+        memoryset.insert(
+            [{"value": suggestion[0], "label": label_name_to_label[suggestion[1]]} for suggestion in self.suggestions]
+        )
+
+
+class PredictionBase(ABC):
+    prediction_id: str | None
     confidence: float
-    memoryset: LabeledMemoryset
-    model: ClassificationModel
+    anomaly_score: float | None
 
     def __init__(
         self,
-        prediction_id: str,
+        prediction_id: str | None,
         *,
-        label: int,
+        label: int | None,
         label_name: str | None,
+        score: float | None,
         confidence: float,
-        memoryset: LabeledMemoryset | str,
-        model: ClassificationModel | str,
-        telemetry: LabelPredictionWithMemoriesAndFeedback | None = None,
+        anomaly_score: float | None,
+        memoryset: LabeledMemoryset | ScoredMemoryset,
+        model: ClassificationModel | RegressionModel,
+        telemetry: LabelPredictionWithMemoriesAndFeedback | ScorePredictionWithMemoriesAndFeedback | None = None,
+        logits: list[float] | None = None,
+        input_value: str | None = None,
     ):
-        # for internal use only, do not document
-        from .classification_model import ClassificationModel
-
         self.prediction_id = prediction_id
         self.label = label
         self.label_name = label_name
+        self.score = score
         self.confidence = confidence
-        self.memoryset = LabeledMemoryset.open(memoryset) if isinstance(memoryset, str) else memoryset
-        self.model = ClassificationModel.open(model) if isinstance(model, str) else model
+        self.anomaly_score = anomaly_score
+        self.memoryset = memoryset
+        self.model = model
         self.__telemetry = telemetry if telemetry else None
-
-    def __repr__(self):
-        return (
-            "LabelPrediction({"
-            + f"label: <{self.label_name}: {self.label}>, "
-            + f"confidence: {self.confidence:.2f}, "
-            + f"input_value: '{str(self.input_value)[:100] + '...' if len(str(self.input_value)) > 100 else self.input_value}'"
-            + "})"
-        )
+        self.logits = logits
+        self._input_value = input_value
 
     @property
-    def _telemetry(self) -> LabelPredictionWithMemoriesAndFeedback:
+    def _telemetry(self) -> LabelPredictionWithMemoriesAndFeedback | ScorePredictionWithMemoriesAndFeedback:
         # for internal use only, do not document
         if self.__telemetry is None:
-            self.__telemetry = get_prediction(prediction_id=UUID(self.prediction_id))
+            if self.prediction_id is None:
+                raise ValueError("Cannot fetch telemetry with no prediction ID")
+            client = OrcaClient._resolve_client()
+            self.__telemetry = client.GET(
+                "/telemetry/prediction/{prediction_id}", params={"prediction_id": self.prediction_id}
+            )
         return self.__telemetry
 
     @property
-    def memory_lookups(self) -> list[LabeledMemoryLookup]:
-        return [LabeledMemoryLookup(self.memoryset.id, lookup) for lookup in self._telemetry.memories]
+    def input_value(self) -> str:
+        if self._input_value is not None:
+            return self._input_value
+        assert isinstance(self._telemetry["input_value"], str)
+        return self._telemetry["input_value"]
 
     @property
-    def input_value(self) -> str | None:
-        return self._telemetry.input_value
+    def memory_lookups(self) -> list[LabeledMemoryLookup] | list[ScoredMemoryLookup]:
+        if "label" in self._telemetry:
+            return [
+                LabeledMemoryLookup(self._telemetry["memoryset_id"], lookup) for lookup in self._telemetry["memories"]
+            ]
+        else:
+            return [
+                ScoredMemoryLookup(self._telemetry["memoryset_id"], lookup) for lookup in self._telemetry["memories"]
+            ]
 
     @property
     def feedback(self) -> dict[str, bool | float]:
         return {
-            f.category_name: (
-                f.value if f.category_type == FeedbackType.CONTINUOUS else True if f.value == 1 else False
+            f["category_name"]: (
+                f["value"] if f["category_type"] == "CONTINUOUS" else True if f["value"] == 1 else False
             )
-            for f in self._telemetry.feedbacks
+            for f in self._telemetry["feedbacks"]
         }
 
     @property
-    def expected_label(self) -> int | None:
-        return self._telemetry.expected_label
+    def tags(self) -> set[str]:
+        return set(self._telemetry["tags"])
 
     @property
-    def tags(self) -> set[str]:
-        return set(self._telemetry.tags)
+    def explanation(self) -> str:
+        if self._telemetry["explanation"] is None:
+            client = OrcaClient._resolve_client()
+            self._telemetry["explanation"] = client.GET(
+                "/telemetry/prediction/{prediction_id}/explanation",
+                params={"prediction_id": self._telemetry["prediction_id"]},
+                parse_as="text",
+                timeout=30,
+            )
+        return self._telemetry["explanation"]
+
+    def explain(self, refresh: bool = False) -> None:
+        """
+        Print an explanation of the prediction as a stream of text.
+
+        Params:
+            refresh: Force the explanation agent to re-run even if an explanation already exists.
+        """
+        if not refresh and self._telemetry["explanation"] is not None:
+            print(self._telemetry["explanation"])
+        else:
+            client = OrcaClient._resolve_client()
+            with client.stream(
+                "GET",
+                f"/telemetry/prediction/{self.prediction_id}/explanation?refresh={refresh}",
+                timeout=Timeout(connect=3, read=None),
+            ) as res:
+                for chunk in res.iter_text():
+                    print(chunk, end="")
+            print()  # final newline
 
     @overload
     @classmethod
-    def get(cls, prediction_id: str) -> LabelPrediction:  # type: ignore -- this takes precedence
+    def get(cls, prediction_id: str) -> Self:  # type: ignore -- this takes precedence
         pass
 
     @overload
     @classmethod
-    def get(cls, prediction_id: Iterable[str]) -> list[LabelPrediction]:
+    def get(cls, prediction_id: Iterable[str]) -> list[Self]:
         pass
 
     @classmethod
-    def get(cls, prediction_id: str | Iterable[str]) -> LabelPrediction | list[LabelPrediction]:
+    def get(cls, prediction_id: str | Iterable[str]) -> Self | list[Self]:
         """
         Fetch a prediction or predictions
 
@@ -223,6 +291,7 @@ class LabelPrediction:
             LabelPrediction({
                 label: <positive: 1>,
                 confidence: 0.95,
+                anomaly_score: 0.1,
                 input_value: "I am happy",
                 memoryset: "my_memoryset",
                 model: "my_model"
@@ -237,6 +306,7 @@ class LabelPrediction:
                 LabelPrediction({
                     label: <positive: 1>,
                     confidence: 0.95,
+                    anomaly_score: 0.1,
                     input_value: "I am happy",
                     memoryset: "my_memoryset",
                     model: "my_model"
@@ -244,68 +314,75 @@ class LabelPrediction:
                 LabelPrediction({
                     label: <negative: 0>,
                     confidence: 0.05,
+                    anomaly_score: 0.2,
                     input_value: "I am sad",
                     memoryset: "my_memoryset", model: "my_model"
                 }),
             ]
         """
-        if isinstance(prediction_id, str):
-            prediction = get_prediction(prediction_id=UUID(prediction_id))
+        from .classification_model import ClassificationModel
+        from .regression_model import RegressionModel
+
+        def create_prediction(
+            prediction: LabelPredictionWithMemoriesAndFeedback | ScorePredictionWithMemoriesAndFeedback,
+        ) -> Self:
+
+            if "label" in prediction:
+                memoryset = LabeledMemoryset.open(prediction["memoryset_id"])
+                model = ClassificationModel.open(prediction["model_id"])
+            else:
+                memoryset = ScoredMemoryset.open(prediction["memoryset_id"])
+                model = RegressionModel.open(prediction["model_id"])
+
             return cls(
-                prediction_id=prediction.prediction_id,
-                label=prediction.label,
-                label_name=prediction.label_name,
-                confidence=prediction.confidence,
-                memoryset=prediction.memoryset_id,
-                model=prediction.model_id,
+                prediction_id=prediction["prediction_id"],
+                label=prediction.get("label", None),
+                label_name=prediction.get("label_name", None),
+                score=prediction.get("score", None),
+                confidence=prediction["confidence"],
+                anomaly_score=prediction["anomaly_score"],
+                memoryset=memoryset,
+                model=model,
                 telemetry=prediction,
             )
+
+        client = OrcaClient._resolve_client()
+        if isinstance(prediction_id, str):
+            return create_prediction(
+                client.GET("/telemetry/prediction/{prediction_id}", params={"prediction_id": prediction_id})
+            )
         else:
             return [
-                cls(
-                    prediction_id=prediction.prediction_id,
-                    label=prediction.label,
-                    label_name=prediction.label_name,
-                    confidence=prediction.confidence,
-                    memoryset=prediction.memoryset_id,
-                    model=prediction.model_id,
-                    telemetry=prediction,
-                )
-                for prediction in list_predictions(body=ListPredictionsRequest(prediction_ids=list(prediction_id)))
+                create_prediction(prediction)
+                for prediction in client.POST("/telemetry/prediction", json={"prediction_ids": list(prediction_id)})
             ]
 
     def refresh(self):
         """Refresh the prediction data from the OrcaCloud"""
-        self.__dict__.update(LabelPrediction.get(self.prediction_id).__dict__)
-
-    def inspect(self):
-        """Open a UI to inspect the memories used by this prediction"""
-        inspect_prediction_result(self)
+        if self.prediction_id is None:
+            raise ValueError("Cannot refresh prediction with no prediction ID")
+        self.__dict__.update(self.get(self.prediction_id).__dict__)
 
-    def update(self, *, expected_label: int | None = UNSET, tags: set[str] | None = UNSET) -> None:
-        """
-        Update editable prediction properties.
-
-        Params:
-            expected_label: Value to set for the expected label, defaults to `[UNSET]` if not provided.
-            tags: Value to replace existing tags with, defaults to `[UNSET]` if not provided.
-
-        Examples:
-            Update the expected label:
-            >>> prediction.update(expected_label=1)
-
-            Add a new tag:
-            >>> prediction.update(tags=prediction.tags | {"new_tag"})
-
-            Remove expected label and tags:
-            >>> prediction.update(expected_label=None, tags=None)
-        """
-        update_prediction(
-            prediction_id=self.prediction_id,
-            body=UpdatePredictionRequest(
-                expected_label=expected_label if expected_label is not UNSET else CLIENT_UNSET,
-                tags=[] if tags is None else list(tags) if tags is not UNSET else CLIENT_UNSET,
-            ),
+    def _update(
+        self,
+        *,
+        tags: set[str] | None = UNSET,
+        expected_label: int | None = UNSET,
+        expected_score: float | None = UNSET,
+    ) -> None:
+        if self.prediction_id is None:
+            raise ValueError("Cannot update prediction with no prediction ID")
+
+        payload: UpdatePredictionRequest = {}
+        if tags is not UNSET:
+            payload["tags"] = [] if tags is None else list(tags)
+        if expected_label is not UNSET:
+            payload["expected_label"] = expected_label
+        if expected_score is not UNSET:
+            payload["expected_score"] = expected_score
+        client = OrcaClient._resolve_client()
+        client.PATCH(
+            "/telemetry/prediction/{prediction_id}", params={"prediction_id": self.prediction_id}, json=payload
         )
         self.refresh()
 
@@ -316,7 +393,7 @@ class LabelPrediction:
         Params:
             tag: Tag to add to the prediction
         """
-        self.update(tags=self.tags | {tag})
+        self._update(tags=self.tags | {tag})
 
     def remove_tag(self, tag: str) -> None:
         """
@@ -325,7 +402,7 @@ class LabelPrediction:
         Params:
             tag: Tag to remove from the prediction
         """
-        self.update(tags=self.tags - {tag})
+        self._update(tags=self.tags - {tag})
 
     def record_feedback(
         self,
@@ -361,12 +438,14 @@ class LabelPrediction:
             ValueError: If the value does not match previous value types for the category, or is a
                 [`float`][float] that is not between `-1.0` and `+1.0`.
         """
-        record_prediction_feedback(
-            body=[
+        client = OrcaClient._resolve_client()
+        client.PUT(
+            "/telemetry/prediction/feedback",
+            json=[
                 _parse_feedback(
                     {"prediction_id": self.prediction_id, "category": category, "value": value, "comment": comment}
                 )
-            ]
+            ],
         )
         self.refresh()
 
@@ -380,7 +459,245 @@ class LabelPrediction:
         Raises:
             ValueError: If the category is not found.
         """
-        record_prediction_feedback(
-            body=[PredictionFeedbackRequest(prediction_id=self.prediction_id, category_name=category, value=None)]
+        if self.prediction_id is None:
+            raise ValueError("Cannot delete feedback with no prediction ID")
+
+        client = OrcaClient._resolve_client()
+        client.PUT(
+            "/telemetry/prediction/feedback",
+            json=[PredictionFeedbackRequest(prediction_id=self.prediction_id, category_name=category, value=None)],
         )
         self.refresh()
+
+    def inspect(self) -> None:
+        """
+        Display an interactive UI with the details about this prediction
+
+        Note:
+            This method is only available in Jupyter notebooks.
+        """
+        from ._utils.prediction_result_ui import inspect_prediction_result
+
+        inspect_prediction_result(self)
+
+
+class ClassificationPrediction(PredictionBase):
+    """
+    Labeled prediction result from a [`ClassificationModel`][orca_sdk.ClassificationModel]
+
+    Attributes:
+        prediction_id: Unique identifier of this prediction used for feedback
+        label: Label predicted by the model
+        label_name: Human-readable name of the label
+        confidence: Confidence of the prediction
+        anomaly_score: Anomaly score of the input
+        input_value: The input value used for the prediction
+        expected_label: Expected label for the prediction, useful when evaluating the model
+        expected_label_name: Human-readable name of the expected label
+        memory_lookups: Memories used by the model to make the prediction
+        explanation: Natural language explanation of the prediction, only available if the model
+            has the Explain API enabled
+        tags: Tags for the prediction, useful for filtering and grouping predictions
+        model: Model used to make the prediction
+        memoryset: Memoryset that was used to lookup memories to ground the prediction
+    """
+
+    label: int
+    label_name: str
+    logits: list[float] | None
+    model: ClassificationModel
+    memoryset: LabeledMemoryset
+
+    def __repr__(self):
+        return (
+            "ClassificationPrediction({"
+            + f"label: <{self.label_name}: {self.label}>, "
+            + f"confidence: {self.confidence:.2f}, "
+            + (f"anomaly_score: {self.anomaly_score:.2f}, " if self.anomaly_score is not None else "")
+            + f"input_value: '{str(self.input_value)[:100] + '...' if len(str(self.input_value)) > 100 else self.input_value}'"
+            + "})"
+        )
+
+    @property
+    def memory_lookups(self) -> list[LabeledMemoryLookup]:
+        assert "label" in self._telemetry
+        return [LabeledMemoryLookup(self._telemetry["memoryset_id"], lookup) for lookup in self._telemetry["memories"]]
+
+    @property
+    def expected_label(self) -> int | None:
+        assert "label" in self._telemetry
+        return self._telemetry["expected_label"]
+
+    @property
+    def expected_label_name(self) -> str | None:
+        assert "label" in self._telemetry
+        return self._telemetry["expected_label_name"]
+
+    def update(
+        self,
+        *,
+        tags: set[str] | None = UNSET,
+        expected_label: int | None = UNSET,
+    ) -> None:
+        """
+        Update the prediction.
+
+        Note:
+            If a field is not provided, it will default to [UNSET][orca_sdk.UNSET] and not be updated.
+
+        Params:
+            tags: New tags to set for the prediction. Set to `None` to remove all tags.
+            expected_label: New expected label to set for the prediction. Set to `None` to remove.
+        """
+        self._update(tags=tags, expected_label=expected_label)
+
+    def recommend_action(self, *, refresh: bool = False) -> tuple[str, str]:
+        """
+        Get an action recommendation for improving this prediction.
+
+        Analyzes the prediction and suggests the most effective action to improve model
+        performance, such as adding memories, detecting mislabels, removing duplicates,
+        or finetuning.
+
+        Params:
+            refresh: Force the action recommendation agent to re-run even if a recommendation already exists
+
+        Returns:
+            Tuple of (action, rationale) where:
+            - action: The recommended action ("add_memories", "detect_mislabels", "remove_duplicates", or "finetuning") that would resolve the mislabeling
+            - rationale: Explanation for why this action was recommended
+
+        Raises:
+            ValueError: If the prediction has no prediction ID
+            RuntimeError: If the lighthouse API key is not configured
+
+        Examples:
+            Get action recommendation for an incorrect prediction:
+            >>> action, rationale = prediction.recommend_action()
+            >>> print(f"Recommended action: {action}")
+            >>> print(f"Rationale: {rationale}")
+        """
+        if self.prediction_id is None:
+            raise ValueError("Cannot get action recommendation with no prediction ID")
+
+        client = OrcaClient._resolve_client()
+        response = client.GET(
+            "/telemetry/prediction/{prediction_id}/action",
+            params={"prediction_id": self.prediction_id},
+            timeout=30,
+        )
+        return (response["action"], response["rationale"])
+
+    def generate_memory_suggestions(self, *, num_memories: int = 3) -> AddMemorySuggestions:
+        """
+        Generate synthetic memory suggestions to improve this prediction.
+
+        Creates new example memories that are similar to the input but have clearer
+        signals for the expected label. These can be added to the memoryset to improve
+        model performance on similar inputs.
+
+        Params:
+            num_memories: Number of memory suggestions to generate (default: 3)
+
+        Returns:
+            List of dictionaries that can be directly passed to memoryset.insert().
+            Each dictionary contains:
+            - "value": The suggested memory text
+            - "label": The suggested label as an integer
+
+        Raises:
+            ValueError: If the prediction has no prediction ID
+            RuntimeError: If the lighthouse API key is not configured
+
+        Examples:
+            Generate memory suggestions for an incorrect prediction:
+            >>> suggestions = prediction.generate_memory_suggestions(num_memories=3)
+            >>> for suggestion in suggestions:
+            ...     print(f"Value: {suggestion['value']}, Label: {suggestion['label']}")
+            >>>
+            >>> # Add suggestions directly to memoryset
+            >>> model.memoryset.insert(suggestions)
+        """
+        if self.prediction_id is None:
+            raise ValueError("Cannot generate memory suggestions with no prediction ID")
+
+        client = OrcaClient._resolve_client()
+        response = client.GET(
+            "/telemetry/prediction/{prediction_id}/memory_suggestions",
+            params={"prediction_id": self.prediction_id, "num_memories": num_memories},
+            timeout=30,
+        )
+
+        return AddMemorySuggestions(
+            suggestions=[(m["value"], m["label_name"]) for m in response["memories"]],
+            memoryset_id=self.memoryset.id,
+            model_id=self.model.id,
+            prediction_id=self.prediction_id,
+        )
+
+
+class RegressionPrediction(PredictionBase):
+    """
+    Score-based prediction result from a [`RegressionModel`][orca_sdk.RegressionModel]
+
+    Attributes:
+        prediction_id: Unique identifier of this prediction used for feedback
+        score: Score predicted by the model
+        confidence: Confidence of the prediction
+        anomaly_score: Anomaly score of the input
+        input_value: The input value used for the prediction
+        expected_score: Expected score for the prediction, useful when evaluating the model
+        memory_lookups: Memories used by the model to make the prediction
+        explanation: Natural language explanation of the prediction, only available if the model
+            has the Explain API enabled
+        tags: Tags for the prediction, useful for filtering and grouping predictions
+        model: Model used to make the prediction
+        memoryset: Memoryset that was used to lookup memories to ground the prediction
+    """
+
+    score: float
+    model: RegressionModel
+    memoryset: ScoredMemoryset
+
+    def __repr__(self):
+        return (
+            "RegressionPrediction({"
+            + f"score: {self.score:.2f}, "
+            + f"confidence: {self.confidence:.2f}, "
+            + (f"anomaly_score: {self.anomaly_score:.2f}, " if self.anomaly_score is not None else "")
+            + f"input_value: '{str(self.input_value)[:100] + '...' if len(str(self.input_value)) > 100 else self.input_value}'"
+            + "})"
+        )
+
+    @property
+    def memory_lookups(self) -> list[ScoredMemoryLookup]:
+        assert "score" in self._telemetry
+        return [ScoredMemoryLookup(self._telemetry["memoryset_id"], lookup) for lookup in self._telemetry["memories"]]
+
+    @property
+    def explanation(self) -> str:
+        """The explanation for this prediction. Requires `lighthouse_client_api_key` to be set."""
+        raise NotImplementedError("Explanation is not supported for regression predictions")
+
+    @property
+    def expected_score(self) -> float | None:
+        assert "score" in self._telemetry
+        return self._telemetry["expected_score"]
+
+    def update(
+        self,
+        *,
+        tags: set[str] | None = UNSET,
+        expected_score: float | None = UNSET,
+    ) -> None:
+        """
+        Update the prediction.
+
+        Note:
+            If a field is not provided, it will default to [UNSET][orca_sdk.UNSET] and not be updated.
+
+        Params:
+            tags: New tags to set for the prediction. Set to `None` to remove all tags.
+            expected_score: New expected score to set for the prediction. Set to `None` to remove.
+        """
+        self._update(tags=tags, expected_score=expected_score)