orca-sdk 0.0.94__py3-none-any.whl → 0.0.95__py3-none-any.whl

orca_sdk/memoryset.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 import logging
+from abc import ABC
 from datetime import datetime, timedelta
 from os import PathLike
-from typing import Any, Iterable, Literal, cast, overload
+from typing import Any, Generic, Iterable, Literal, Self, TypeVar, cast, overload
 
 import pandas as pd
 import pyarrow as pa
@@ -38,8 +39,11 @@ from ._generated_api_client.api import (
 from ._generated_api_client.models import (
     CascadeEditSuggestionsRequest,
     CascadingEditSuggestion,
-    CloneLabeledMemorysetRequest,
-    CreateLabeledMemorysetRequest,
+    CloneMemorysetRequest,
+    ColumnType,
+    CreateMemorysetRequest,
+    CreateMemorysetRequestIndexParams,
+    CreateMemorysetRequestIndexType,
     DeleteMemoriesRequest,
     EmbeddingEvaluationRequest,
     FilterItem,
@@ -55,8 +59,6 @@ from ._generated_api_client.models import (
     LabeledMemoryLookup as LabeledMemoryLookupResponse,
 )
 from ._generated_api_client.models import (
-    LabeledMemorysetMetadata,
-    LabeledMemorysetUpdate,
     LabeledMemoryUpdate,
     LabeledMemoryUpdateMetadataType0,
     LabeledMemoryWithFeedbackMetrics,
@@ -65,8 +67,21 @@ from ._generated_api_client.models import (
     LookupRequest,
     MemorysetAnalysisConfigs,
     MemorysetAnalysisRequest,
+    MemorysetMetadata,
+    MemorysetUpdate,
+    MemoryType,
     PretrainedEmbeddingModelName,
-    TaskStatus,
+)
+from ._generated_api_client.models import ScoredMemory as ScoredMemoryResponse
+from ._generated_api_client.models import ScoredMemoryInsert, ScoredMemoryInsertMetadata
+from ._generated_api_client.models import (
+    ScoredMemoryLookup as ScoredMemoryLookupResponse,
+)
+from ._generated_api_client.models import (
+    ScoredMemoryUpdate,
+    ScoredMemoryUpdateMetadataType0,
+    ScoredMemoryWithFeedbackMetrics,
+    ScorePredictionMemoryLookup,
     TelemetryFilterItem,
     TelemetryFilterItemOp,
     TelemetryMemoriesRequest,
@@ -75,13 +90,13 @@ from ._generated_api_client.models import (
 )
 from ._generated_api_client.types import UNSET as CLIENT_UNSET
 from ._utils.common import UNSET, CreateMode, DropMode
-from ._utils.task import wait_for_task
 from .datasource import Datasource
 from .embedding_model import (
     FinetunedEmbeddingModel,
     PretrainedEmbeddingModel,
     _EmbeddingModel,
 )
+from .job import Job, Status
 
 TelemetrySortItem = tuple[str, Literal["asc", "desc"]]
 """
@@ -120,8 +135,10 @@ Examples:
     >>> ("feedback_metrics.accuracy.avg", ">", 0.95)
 """
 
+IndexType = Literal["FLAT", "IVF_FLAT", "IVF_SQ8", "IVF_PQ", "HNSW", "DISKANN"]
 
-DEFAULT_COLUMN_NAMES = {"value", "label", "source_id"}
+DEFAULT_COLUMN_NAMES = {"value", "source_id"}
+TYPE_SPECIFIC_COLUMN_NAMES = {"label", "score"}
 FORBIDDEN_METADATA_COLUMN_NAMES = {
     "memory_id",
     "memory_version",
@@ -136,7 +153,10 @@ FORBIDDEN_METADATA_COLUMN_NAMES = {
 
 def _parse_filter_item_from_tuple(input: FilterItemTuple) -> FilterItem | TelemetryFilterItem:
     field = input[0].split(".")
-    if len(field) == 1 and field[0] not in DEFAULT_COLUMN_NAMES | FORBIDDEN_METADATA_COLUMN_NAMES:
+    if (
+        len(field) == 1
+        and field[0] not in DEFAULT_COLUMN_NAMES | TYPE_SPECIFIC_COLUMN_NAMES | FORBIDDEN_METADATA_COLUMN_NAMES
+    ):
         field = ["metadata", field[0]]
     op = FilterItemOp(input[1])
     value = input[2]
@@ -184,23 +204,56 @@ def _parse_sort_item_from_tuple(
     return TelemetrySortOptions(field=field, direction=TelemetrySortOptionsDirection(input[1]))
 
 
-def _parse_memory_insert(memory: dict[str, Any]) -> LabeledMemoryInsert:
+def _parse_memory_insert(memory: dict[str, Any], type: MemoryType) -> LabeledMemoryInsert | ScoredMemoryInsert:
     value = memory.get("value")
     if not isinstance(value, str):
         raise ValueError("Memory value must be a string")
-    label = memory.get("label")
-    if not isinstance(label, int):
-        raise ValueError("Memory label must be an integer")
     source_id = memory.get("source_id")
     if source_id and not isinstance(source_id, str):
         raise ValueError("Memory source_id must be a string")
-    metadata = LabeledMemoryInsertMetadata.from_dict({k: v for k, v in memory.items() if k not in DEFAULT_COLUMN_NAMES})
-    if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
-        raise ValueError(f"The following column names are reserved: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}")
-    return LabeledMemoryInsert(value=value, label=label, source_id=source_id, metadata=metadata)
+    match type:
+        case MemoryType.LABELED:
+            label = memory.get("label")
+            if not isinstance(label, int):
+                raise ValueError("Memory label must be an integer")
+            metadata = LabeledMemoryInsertMetadata.from_dict(
+                {k: v for k, v in memory.items() if k not in DEFAULT_COLUMN_NAMES | {"label"}}
+            )
+            if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
+                raise ValueError(
+                    f"The following column names are reserved: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}"
+                )
+            return LabeledMemoryInsert(value=value, label=label, source_id=source_id, metadata=metadata)
+        case MemoryType.SCORED:
+            score = memory.get("score")
+            if not isinstance(score, (int, float)):
+                raise ValueError("Memory score must be a number")
+            metadata = ScoredMemoryInsertMetadata.from_dict(
+                {k: v for k, v in memory.items() if k not in DEFAULT_COLUMN_NAMES | {"score"}}
+            )
+            if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
+                raise ValueError(
+                    f"The following column names are reserved: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}"
+                )
+            return ScoredMemoryInsert(value=value, score=score, source_id=source_id, metadata=metadata)
 
 
-def _parse_memory_update(update: dict[str, Any]) -> LabeledMemoryUpdate:
+@overload
+def _parse_memory_update(update: dict[str, Any], type: Literal[MemoryType.LABELED]) -> LabeledMemoryUpdate:
+    pass
+
+
+@overload
+def _parse_memory_update(update: dict[str, Any], type: Literal[MemoryType.SCORED]) -> ScoredMemoryUpdate:
+    pass
+
+
+@overload
+def _parse_memory_update(update: dict[str, Any], type: MemoryType) -> ScoredMemoryUpdate | LabeledMemoryUpdate:
+    pass
+
+
+def _parse_memory_update(update: dict[str, Any], type: MemoryType) -> LabeledMemoryUpdate | ScoredMemoryUpdate:
     if "memory_id" not in update:
         raise ValueError("memory_id must be specified in the update dictionary")
     memory_id = update["memory_id"]
@@ -209,21 +262,127 @@ def _parse_memory_update(update: dict[str, Any]) -> LabeledMemoryUpdate:
     value = update.get("value", CLIENT_UNSET)
     if value is not CLIENT_UNSET and not isinstance(value, str):
         raise ValueError("value must be a string or unset")
-    label = update.get("label", CLIENT_UNSET)
-    if label is not CLIENT_UNSET and not isinstance(label, int):
-        raise ValueError("label must be an integer or unset")
     source_id = update.get("source_id", CLIENT_UNSET)
     if source_id is not CLIENT_UNSET and not isinstance(source_id, str):
         raise ValueError("source_id must be a string or unset")
-    metadata = LabeledMemoryUpdateMetadataType0.from_dict(
-        {k: v for k, v in update.items() if k not in DEFAULT_COLUMN_NAMES | {"memory_id"}}
-    )
-    if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
-        raise ValueError(f"Cannot update the following metadata keys: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}")
-    return LabeledMemoryUpdate(memory_id=memory_id, value=value, label=label, source_id=source_id, metadata=metadata)
+    match type:
+        case MemoryType.LABELED:
+            label = update.get("label", CLIENT_UNSET)
+            if label is not CLIENT_UNSET and not isinstance(label, int):
+                raise ValueError("label must be an integer or unset")
+            metadata = LabeledMemoryUpdateMetadataType0.from_dict(
+                {k: v for k, v in update.items() if k not in DEFAULT_COLUMN_NAMES | {"memory_id", "label"}}
+            )
+            if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
+                raise ValueError(
+                    f"Cannot update the following metadata keys: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}"
+                )
+            return LabeledMemoryUpdate(
+                memory_id=memory_id, value=value, label=label, source_id=source_id, metadata=metadata
+            )
+        case MemoryType.SCORED:
+            score = update.get("score", CLIENT_UNSET)
+            if score is not CLIENT_UNSET and not isinstance(score, (int, float)):
+                raise ValueError("score must be a number or unset")
+            metadata = ScoredMemoryUpdateMetadataType0.from_dict(
+                {k: v for k, v in update.items() if k not in DEFAULT_COLUMN_NAMES | {"memory_id", "score"}}
+            )
+            if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
+                raise ValueError(
+                    f"Cannot update the following metadata keys: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}"
+                )
+            return ScoredMemoryUpdate(
+                memory_id=memory_id, value=value, score=score, source_id=source_id, metadata=metadata
+            )
+
+
+class _Memory(ABC):
+    value: str
+    embedding: list[float]
+    source_id: str | None
+    created_at: datetime
+    updated_at: datetime
+    metadata: dict[str, str | float | int | bool | None]
+    metrics: dict[str, Any]
+    memory_id: str
+    memory_version: int
+    feedback_metrics: dict[str, Any]
+    lookup_count: int
+    memory_type: MemoryType  # defined by subclasses
+
+    def __init__(
+        self,
+        memoryset_id: str,
+        memory: (
+            LabeledMemoryResponse
+            | LabeledMemoryLookupResponse
+            | LabeledMemoryWithFeedbackMetrics
+            | LabelPredictionMemoryLookup
+            | ScoredMemoryResponse
+            | ScoredMemoryLookupResponse
+            | ScoredMemoryWithFeedbackMetrics
+            | ScorePredictionMemoryLookup
+        ),
+    ):
+        # for internal use only, do not document
+        self.memoryset_id = memoryset_id
+        self.memory_id = memory.memory_id
+        self.memory_version = memory.memory_version
+        self.value = memory.value
+        self.embedding = memory.embedding
+        self.source_id = memory.source_id
+        self.created_at = memory.created_at
+        self.updated_at = memory.updated_at
+        self.metadata = memory.metadata.to_dict()
+        self.metrics = memory.metrics.to_dict() if memory.metrics else {}
+        self.feedback_metrics = (
+            getattr(memory, "feedback_metrics").to_dict() if hasattr(memory, "feedback_metrics") else {}
+        )
+        self.lookup_count = getattr(memory, "lookup_count", 0)
+
+    def __getattr__(self, key: str) -> Any:
+        if key.startswith("__") or key not in self.metadata:
+            raise AttributeError(f"{key} is not a valid attribute")
+        return self.metadata[key]
+
+    def update(
+        self,
+        *,
+        value: str = UNSET,
+        source_id: str | None = UNSET,
+        **metadata: None | bool | float | int | str,
+    ) -> Self:
+        """
+        Update the memory with new values
 
+        Note:
+            If a field is not provided, it will default to [UNSET][orca_sdk.UNSET] and not be updated.
+
+        Params:
+            value: New value of the memory
+            label: New label of the memory
+            score: New score of the memory
+            source_id: New source ID of the memory
+            **metadata: New values for metadata properties
+
+        Returns:
+            The updated memory
+        """
+        response = update_memory_gpu(
+            self.memoryset_id,
+            body=_parse_memory_update(
+                {"memory_id": self.memory_id}
+                | ({"value": value} if value is not UNSET else {})
+                | ({"source_id": source_id} if source_id is not UNSET else {})
+                | {k: v for k, v in metadata.items() if v is not UNSET},
+                type=self.memory_type,
+            ),
+        )
+        self.__dict__.update(self.__class__(self.memoryset_id, response).__dict__)
+        return self
 
-class LabeledMemory:
+
+class LabeledMemory(_Memory):
     """
     A row of the [`LabeledMemoryset`][orca_sdk.LabeledMemoryset]
 
@@ -248,19 +407,9 @@ class LabeledMemory:
     * **`...`** (<code>[str][str] | [float][float] | [int][int] | [bool][bool] | None</code>): All metadata properties can be accessed as attributes
     """
 
-    value: str | list[list[float]]
-    embedding: list[float]
     label: int
     label_name: str | None
-    source_id: str | None
-    created_at: datetime
-    updated_at: datetime
-    metadata: dict[str, str | float | int | bool | None]
-    metrics: dict[str, Any]
-    memory_id: str
-    memory_version: int
-    feedback_metrics: dict[str, Any]
-    lookup_count: int
+    memory_type = MemoryType.LABELED
 
     def __init__(
         self,
@@ -273,27 +422,9 @@ class LabeledMemory:
         ),
     ):
         # for internal use only, do not document
-        self.memoryset_id = memoryset_id
-        self.memory_id = memory.memory_id
-        self.memory_version = memory.memory_version
-        self.value = memory.value
-        self.embedding = memory.embedding
+        super().__init__(memoryset_id, memory)
         self.label = memory.label
         self.label_name = memory.label_name
-        self.source_id = memory.source_id
-        self.created_at = memory.created_at
-        self.updated_at = memory.updated_at
-        self.metadata = memory.metadata.to_dict()
-        self.metrics = memory.metrics.to_dict() if memory.metrics else {}
-        self.feedback_metrics = (
-            memory.feedback_metrics.to_dict() if isinstance(memory, LabeledMemoryWithFeedbackMetrics) else {}
-        )
-        self.lookup_count = memory.lookup_count if isinstance(memory, LabeledMemoryWithFeedbackMetrics) else 0
-
-    def __getattr__(self, key: str) -> Any:
-        if key.startswith("__") or key not in self.metadata:
-            raise AttributeError(f"{key} is not a valid attribute")
-        return self.metadata[key]
 
     def __repr__(self) -> str:
         return (
@@ -330,17 +461,7 @@ class LabeledMemory:
         Returns:
             The updated memory
         """
-        response = update_memory_gpu(
-            self.memoryset_id,
-            body=_parse_memory_update(
-                {"memory_id": self.memory_id}
-                | ({"value": value} if value is not UNSET else {})
-                | ({"label": label} if label is not UNSET else {})
-                | ({"source_id": source_id} if source_id is not UNSET else {})
-                | metadata
-            ),
-        )
-        self.__dict__.update(LabeledMemory(self.memoryset_id, response).__dict__)
+        super().update(value=value, label=label, source_id=source_id, **metadata)
         return self
 
 
@@ -395,7 +516,136 @@ class LabeledMemoryLookup(LabeledMemory):
         )
 
 
-class LabeledMemoryset:
+class ScoredMemory(_Memory):
+    """
+    A row of the [`ScoredMemoryset`][orca_sdk.ScoredMemoryset]
+
+    Attributes:
+        value: Value represented by the row
+        embedding: Embedding of the value of the memory for semantic search, automatically generated
+            with the [`ScoredMemoryset.embedding_model`][orca_sdk.ScoredMemoryset]
+        score: Score of the memory
+        source_id: Optional unique identifier of the memory in a system of reference
+        metrics: Metrics about the memory, generated when running an analysis on the
+            [`ScoredMemoryset`][orca_sdk.ScoredMemoryset]
+        metadata: Metadata associated with the memory that is not used in the model. Metadata
+            properties are also accessible as individual attributes on the instance.
+        memory_id: Unique identifier for the memory, automatically generated on insert
+        memory_version: Version of the memory, automatically updated when the score or value changes
+        created_at: When the memory was created, automatically generated on insert
+        updated_at: When the memory was last updated, automatically updated on update
+
+    ## Other Attributes:
+    * **`...`** (<code>[str][str] | [float][float] | [int][int] | [bool][bool] | None</code>): All metadata properties can be accessed as attributes
+    """
+
+    score: float
+    memory_type = MemoryType.SCORED
+
+    def __init__(
+        self,
+        memoryset_id: str,
+        memory: (
+            ScoredMemoryResponse
+            | ScoredMemoryLookupResponse
+            | ScorePredictionMemoryLookup
+            | ScoredMemoryWithFeedbackMetrics
+        ),
+    ):
+        # for internal use only, do not document
+        super().__init__(memoryset_id, memory)
+        self.score = memory.score
+
+    def __repr__(self) -> str:
+        return (
+            "ScoredMemory({ "
+            + f"score: {self.score:.2f}"
+            + f", value: '{self.value[:100] + '...' if isinstance(self.value, str) and len(self.value) > 100 else self.value}'"
+            + (f", source_id: '{self.source_id}'" if self.source_id is not None else "")
+            + " })"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, ScoredMemory) and self.memory_id == other.memory_id
+
+    def update(
+        self,
+        *,
+        value: str = UNSET,
+        score: float = UNSET,
+        source_id: str | None = UNSET,
+        **metadata: None | bool | float | int | str,
+    ) -> ScoredMemory:
+        """
+        Update the memory with new values
+
+        Note:
+            If a field is not provided, it will default to [UNSET][orca_sdk.UNSET] and not be updated.
+
+        Params:
+            value: New value of the memory
+            score: New score of the memory
+            source_id: New source ID of the memory
+            **metadata: New values for metadata properties
+
+        Returns:
+            The updated memory
+        """
+        super().update(value=value, score=score, source_id=source_id, **metadata)
+        return self
+
+
+class ScoredMemoryLookup(ScoredMemory):
+    """
+    Lookup result for a memory in a memoryset
+
+    Attributes:
+        lookup_score: Similarity between the memory embedding and search query embedding
+        attention_weight: Weight the model assigned to the memory during prediction if this lookup
+            happened as part of a prediction
+        value: Value represented by the row
+        embedding: Embedding of the value of the memory for semantic search, automatically generated
+            with the [`ScoredMemoryset.embedding_model`][orca_sdk.ScoredMemoryset]
+        score: Score of the memory
+        source_id: Optional unique identifier of the memory in a system of reference
+        metrics: Metrics about the memory, generated when running an analysis on the
+            [`ScoredMemoryset`][orca_sdk.ScoredMemoryset]
+        memory_id: The unique identifier for the memory, automatically generated on insert
+        memory_version: The version of the memory, automatically updated when the score or value changes
+        created_at: When the memory was created, automatically generated on insert
+        updated_at: When the memory was last updated, automatically updated on update
+
+    ## Other Attributes:
+    * **`...`** (<code>[str][str] | [float][float] | [int][int] | [bool][bool] | None</code>): All metadata properties can be accessed as attributes
+    """
+
+    lookup_score: float
+    attention_weight: float | None
+
+    def __init__(self, memoryset_id: str, memory_lookup: ScoredMemoryLookupResponse | ScorePredictionMemoryLookup):
+        # for internal use only, do not document
+        super().__init__(memoryset_id, memory_lookup)
+        self.lookup_score = memory_lookup.lookup_score
+        self.attention_weight = (
+            memory_lookup.attention_weight if isinstance(memory_lookup, ScorePredictionMemoryLookup) else None
+        )
+
+    def __repr__(self) -> str:
+        return (
+            "ScoredMemoryLookup({ "
+            + f"score: {self.score:.2f}"
+            + f", lookup_score: {self.lookup_score:.2f}"
+            + f", value: '{self.value[:100] + '...' if isinstance(self.value, str) and len(self.value) > 100 else self.value}'"
+            + (f", source_id: '{self.source_id}'" if self.source_id is not None else "")
+            + " })"
+        )
+
+
+MemoryT = TypeVar("MemoryT", bound=_Memory)
+MemoryLookupT = TypeVar("MemoryLookupT", bound=_Memory)
+
+
+class _Memoryset(Generic[MemoryT, MemoryLookupT], ABC):
     """
     A Handle to a collection of memories with labels in the OrcaCloud
 
@@ -403,7 +653,6 @@ class LabeledMemoryset:
         id: Unique identifier for the memoryset
         name: Unique name of the memoryset
         description: Description of the memoryset
-        label_names: Names for the class labels in the memoryset
         length: Number of memories in the memoryset
         embedding_model: Embedding model used to embed the memory values for semantic search
         created_at: When the memoryset was created, automatically generated on create
@@ -413,14 +662,17 @@ class LabeledMemoryset:
     id: str
     name: str
     description: str | None
-    label_names: list[str]
+    memory_type: MemoryType  # defined by subclasses
+
     length: int
     created_at: datetime
     updated_at: datetime
-    insertion_status: TaskStatus
+    insertion_status: Status
     embedding_model: _EmbeddingModel
+    index_type: IndexType
+    index_params: dict[str, Any]
 
-    def __init__(self, metadata: LabeledMemorysetMetadata):
+    def __init__(self, metadata: MemorysetMetadata):
         # for internal use only, do not document
         if metadata.pretrained_embedding_model_name:
             self.embedding_model = PretrainedEmbeddingModel._get(metadata.pretrained_embedding_model_name)
@@ -431,26 +683,51 @@ class LabeledMemoryset:
         self.id = metadata.id
         self.name = metadata.name
         self.description = metadata.description
-        self.label_names = metadata.label_names
         self.length = metadata.length
         self.created_at = metadata.created_at
         self.updated_at = metadata.updated_at
-        self.insertion_status = metadata.insertion_status
+        self.insertion_status = Status(metadata.insertion_status.value)
         self._last_refresh = datetime.now()
+        self.index_type = metadata.index_type.value
+        self.index_params = metadata.index_params.to_dict()
+        self.memory_type = MemoryType(metadata.memory_type.value)
 
     def __eq__(self, other) -> bool:
-        return isinstance(other, LabeledMemoryset) and self.id == other.id
+        return isinstance(other, _Memoryset) and self.id == other.id
 
     def __repr__(self) -> str:
         return (
-            "LabeledMemoryset({\n"
+            "Memoryset({\n"
             f"    name: '{self.name}',\n"
             f"    length: {self.length},\n"
-            f"    label_names: {self.label_names},\n"
             f"    embedding_model: {self.embedding_model},\n"
             "})"
         )
 
+    @overload
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        datasource: Datasource,
+        *,
+        embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
+        value_column: str = "value",
+        label_column: str | None = None,
+        score_column: str | None = None,
+        source_id_column: str | None = None,
+        description: str | None = None,
+        label_names: list[str] | None = None,
+        max_seq_length_override: int | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
+        if_exists: CreateMode = "error",
+        background: Literal[True],
+    ) -> Job[Self]:
+        pass
+
+    @overload
     @classmethod
     def create(
         cls,
@@ -459,14 +736,40 @@ class LabeledMemoryset:
         *,
         embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
         value_column: str = "value",
-        label_column: str = "label",
+        label_column: str | None = None,
+        score_column: str | None = None,
         source_id_column: str | None = None,
         description: str | None = None,
         label_names: list[str] | None = None,
         max_seq_length_override: int | None = None,
         remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
         if_exists: CreateMode = "error",
-    ) -> LabeledMemoryset:
+        background: Literal[False] = False,
+    ) -> Self:
+        pass
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        datasource: Datasource,
+        *,
+        embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
+        value_column: str = "value",
+        label_column: str | None = None,
+        score_column: str | None = None,
+        source_id_column: str | None = None,
+        description: str | None = None,
+        label_names: list[str] | None = None,
+        max_seq_length_override: int | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
+        if_exists: CreateMode = "error",
+        background: bool = False,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset in the OrcaCloud
 
@@ -481,6 +784,7 @@ class LabeledMemoryset:
             value_column: Name of the column in the datasource that contains the memory values
             label_column: Name of the column in the datasource that contains the memory labels,
                 these must be contiguous integers starting from 0
+            score_column: Name of the column in the datasource that contains the memory scores
             source_id_column: Optional name of the column in the datasource that contains the ids in
                 the system of reference
             description: Optional description for the memoryset, this will be used in agentic flows,
@@ -495,8 +799,12 @@ class LabeledMemoryset:
                 sequence length if not provided
             remove_duplicates: Whether to remove duplicates from the datasource before inserting
                 into the memoryset
+            index_type: Type of vector index to use for the memoryset, defaults to `"FLAT"`. Valid
+                values are `"FLAT"`, `"IVF_FLAT"`, `"IVF_SQ8"`, `"IVF_PQ"`, `"HNSW"`, and `"DISKANN"`.
+            index_params: Parameters for the vector index, defaults to `{}`
             if_exists: What to do if a memoryset with the same name already exists, defaults to
                 `"error"`. Other option is `"open"` to open the existing memoryset.
+            background: Whether to run the operation none blocking and return a job handle
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
@@ -508,6 +816,9 @@ class LabeledMemoryset:
         if embedding_model is None:
             embedding_model = PretrainedEmbeddingModel.CDE_SMALL
 
+        if label_column is None and score_column is None:
+            raise ValueError("label_column or score_column must be provided")
+
         if cls.exists(name):
             if if_exists == "error":
                 raise ValueError(f"Memoryset with name {name} already exists")
@@ -519,11 +830,12 @@ class LabeledMemoryset:
                 return existing
 
         response = create_memoryset(
-            body=CreateLabeledMemorysetRequest(
+            body=CreateMemorysetRequest(
                 name=name,
                 description=description,
                 datasource_id=datasource.id,
                 datasource_label_column=label_column,
+                datasource_score_column=score_column,
                 datasource_value_column=value_column,
                 datasource_source_id_column=source_id_column,
                 pretrained_embedding_model_name=(
@@ -532,16 +844,30 @@ class LabeledMemoryset:
                 finetuned_embedding_model_id=(
                     embedding_model.id if isinstance(embedding_model, FinetunedEmbeddingModel) else None
                 ),
-                label_names=label_names or [],
+                label_names=label_names,
                 max_seq_length_override=max_seq_length_override,
                 remove_duplicates=remove_duplicates,
+                index_type=CreateMemorysetRequestIndexType[index_type],
+                index_params=CreateMemorysetRequestIndexParams.from_dict(index_params),
             ),
         )
-        wait_for_task(response.insertion_task_id, description="Inserting datasource")
-        return cls.open(response.id)
+        job = Job(response.insertion_task_id, lambda: cls.open(response.id))
+        return job if background else job.result()
 
+    @overload
     @classmethod
-    def from_hf_dataset(cls, name: str, hf_dataset: Dataset, **kwargs: Any) -> LabeledMemoryset:
+    def from_hf_dataset(cls, name: str, hf_dataset: Dataset, background: Literal[True], **kwargs: Any) -> Self:
+        pass
+
+    @overload
+    @classmethod
+    def from_hf_dataset(cls, name: str, hf_dataset: Dataset, background: Literal[False] = False, **kwargs: Any) -> Self:
+        pass
+
+    @classmethod
+    def from_hf_dataset(
+        cls, name: str, hf_dataset: Dataset, background: bool = False, **kwargs: Any
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a Hugging Face [`Dataset`][datasets.Dataset] in the OrcaCloud
 
@@ -557,15 +883,41 @@ class LabeledMemoryset:
             kwargs: Additional parameters for creating the memoryset. See
                 [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
 
-
         Returns:
             Handle to the new memoryset in the OrcaCloud
         """
         datasource = Datasource.from_hf_dataset(
             f"{name}_datasource", hf_dataset, if_exists=kwargs.get("if_exists", "error")
         )
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
+    @classmethod
+    def from_pytorch(
+        cls,
+        name: str,
+        torch_data: TorchDataLoader | TorchDataset,
+        *,
+        column_names: list[str] | None = None,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_pytorch(
+        cls,
+        name: str,
+        torch_data: TorchDataLoader | TorchDataset,
+        *,
+        column_names: list[str] | None = None,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
     @classmethod
     def from_pytorch(
         cls,
@@ -573,8 +925,9 @@ class LabeledMemoryset:
         torch_data: TorchDataLoader | TorchDataset,
         *,
         column_names: list[str] | None = None,
+        background: bool = False,
         **kwargs: Any,
-    ) -> LabeledMemoryset:
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a PyTorch [`DataLoader`][torch.utils.data.DataLoader] or
         [`Dataset`][torch.utils.data.Dataset] in the OrcaCloud
@@ -590,20 +943,52 @@ class LabeledMemoryset:
             torch_data: PyTorch data loader or dataset to create the memoryset from
             column_names: If the provided dataset or data loader returns unnamed tuples, this
                 argument must be provided to specify the names of the columns.
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
                 [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
 
-
         Returns:
             Handle to the new memoryset in the OrcaCloud
         """
         datasource = Datasource.from_pytorch(
             f"{name}_datasource", torch_data, column_names=column_names, if_exists=kwargs.get("if_exists", "error")
         )
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
+    @classmethod
+    def from_list(
+        cls,
+        name: str,
+        data: list[dict],
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_list(
+        cls,
+        name: str,
+        data: list[dict],
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
     @classmethod
-    def from_list(cls, name: str, data: list[dict], **kwargs: Any) -> LabeledMemoryset:
+    def from_list(
+        cls,
+        name: str,
+        data: list[dict],
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a list of dictionaries in the OrcaCloud
 
@@ -616,6 +1001,7 @@ class LabeledMemoryset:
         Params:
             name: Name for the new memoryset (must be unique)
             data: List of dictionaries to create the memoryset from
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
                 [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
 
@@ -629,10 +1015,42 @@ class LabeledMemoryset:
             ... ])
         """
         datasource = Datasource.from_list(f"{name}_datasource", data, if_exists=kwargs.get("if_exists", "error"))
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
+    @classmethod
+    def from_dict(
+        cls,
+        name: str,
+        data: dict,
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_dict(
+        cls,
+        name: str,
+        data: dict,
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
     @classmethod
-    def from_dict(cls, name: str, data: dict, **kwargs: Any) -> LabeledMemoryset:
+    def from_dict(
+        cls,
+        name: str,
+        data: dict,
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a dictionary of columns in the OrcaCloud
 
@@ -645,6 +1063,7 @@ class LabeledMemoryset:
         Params:
             name: Name for the new memoryset (must be unique)
             data: Dictionary of columns to create the memoryset from
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
                 [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
 
@@ -659,10 +1078,42 @@ class LabeledMemoryset:
             ... })
         """
         datasource = Datasource.from_dict(f"{name}_datasource", data, if_exists=kwargs.get("if_exists", "error"))
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
+    @classmethod
+    def from_pandas(
+        cls,
+        name: str,
+        dataframe: pd.DataFrame,
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_pandas(
+        cls,
+        name: str,
+        dataframe: pd.DataFrame,
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
     @classmethod
-    def from_pandas(cls, name: str, dataframe: pd.DataFrame, **kwargs: Any) -> LabeledMemoryset:
+    def from_pandas(
+        cls,
+        name: str,
+        dataframe: pd.DataFrame,
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a pandas [`DataFrame`][pandas.DataFrame] in the OrcaCloud
 
@@ -675,6 +1126,7 @@ class LabeledMemoryset:
         Params:
             name: Name for the new memoryset (must be unique)
             dataframe: Dataframe to create the memoryset from
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
                 [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
 
@@ -682,10 +1134,42 @@ class LabeledMemoryset:
             Handle to the new memoryset in the OrcaCloud
         """
         datasource = Datasource.from_pandas(f"{name}_datasource", dataframe, if_exists=kwargs.get("if_exists", "error"))
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
+    @classmethod
+    def from_arrow(
+        cls,
+        name: str,
+        pyarrow_table: pa.Table,
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_arrow(
+        cls,
+        name: str,
+        pyarrow_table: pa.Table,
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
     @classmethod
-    def from_arrow(cls, name: str, pyarrow_table: pa.Table, **kwargs: Any) -> LabeledMemoryset:
+    def from_arrow(
+        cls,
+        name: str,
+        pyarrow_table: pa.Table,
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a PyArrow [`Table`][pyarrow.Table] in the OrcaCloud
 
@@ -698,6 +1182,7 @@ class LabeledMemoryset:
         Params:
             name: Name for the new memoryset (must be unique)
             pyarrow_table: PyArrow table to create the memoryset from
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
                 [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
 
@@ -707,10 +1192,42 @@ class LabeledMemoryset:
         datasource = Datasource.from_arrow(
             f"{name}_datasource", pyarrow_table, if_exists=kwargs.get("if_exists", "error")
         )
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
+    @classmethod
+    def from_disk(
+        cls,
+        name: str,
+        file_path: str | PathLike,
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_disk(
+        cls,
+        name: str,
+        file_path: str | PathLike,
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
     @classmethod
-    def from_disk(cls, name: str, file_path: str | PathLike, **kwargs: Any) -> LabeledMemoryset:
+    def from_disk(
+        cls,
+        name: str,
+        file_path: str | PathLike,
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a file on disk in the OrcaCloud
 
@@ -730,6 +1247,7 @@ class LabeledMemoryset:
                 - .csv: [`CSV`][csv] files
                 - .parquet: [`Parquet`][pyarrow.parquet.ParquetFile] files
                 - dataset directory: Directory containing a saved HuggingFace [`Dataset`][datasets.Dataset]
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
                 [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
 
@@ -737,10 +1255,11 @@ class LabeledMemoryset:
             Handle to the new memoryset in the OrcaCloud
         """
         datasource = Datasource.from_disk(f"{name}_datasource", file_path, if_exists=kwargs.get("if_exists", "error"))
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
     @classmethod
-    def open(cls, name: str) -> LabeledMemoryset:
+    def open(cls, name: str) -> Self:
         """
         Get a handle to a memoryset in the OrcaCloud
 
@@ -774,14 +1293,14 @@ class LabeledMemoryset:
             return False
 
     @classmethod
-    def all(cls) -> list[LabeledMemoryset]:
+    def all(cls) -> list[Self]:
         """
         Get a list of handles to all memorysets in the OrcaCloud
 
         Returns:
             List of handles to all memorysets in the OrcaCloud
         """
-        return [cls(metadata) for metadata in list_memorysets()]
+        return [cls(metadata) for metadata in list_memorysets(type=cls.memory_type)]
 
     @classmethod
     def drop(cls, name_or_id: str, if_not_exists: DropMode = "error"):
@@ -803,17 +1322,52 @@ class LabeledMemoryset:
             if if_not_exists == "error":
                 raise
 
-    def update_metadata(self, *, description: str | None = UNSET, label_names: list[str] | None = None):
+    def set(self, *, name: str = UNSET, description: str | None = UNSET, label_names: list[str] = UNSET):
         """
-        Update the metadata of the memoryset
+        Update editable attributes of the memoryset
+
+        Note:
+            If a field is not provided, it will default to [UNSET][orca_sdk.UNSET] and not be updated.
 
         Params:
-            description: Value to set for the description, defaults to `[UNSET]` if not provided.
-            label_names: Value to replace existing label names with, defaults to None if not provided.
+            description: Value to set for the description
+            name: Value to set for the name
+            label_names: Value to replace existing label names with
         """
-        update_memoryset(self.id, body=LabeledMemorysetUpdate(description=description, label_names=label_names))
+        update_memoryset(
+            self.id,
+            body=MemorysetUpdate(
+                name=name if name is not UNSET else CLIENT_UNSET,
+                description=description if description is not UNSET else CLIENT_UNSET,
+                label_names=label_names if label_names is not UNSET else CLIENT_UNSET,
+            ),
+        )
         self.refresh()
 
+    @overload
+    def clone(
+        self,
+        name: str,
+        *,
+        embedding_model: PretrainedEmbeddingModel | FinetunedEmbeddingModel | None = None,
+        max_seq_length_override: int | None = None,
+        if_exists: CreateMode = "error",
+        background: Literal[True],
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    def clone(
+        self,
+        name: str,
+        *,
+        embedding_model: PretrainedEmbeddingModel | FinetunedEmbeddingModel | None = None,
+        max_seq_length_override: int | None = None,
+        if_exists: CreateMode = "error",
+        background: Literal[False] = False,
+    ) -> Self:
+        pass
+
     def clone(
         self,
         name: str,
@@ -821,14 +1375,14 @@ class LabeledMemoryset:
         embedding_model: PretrainedEmbeddingModel | FinetunedEmbeddingModel | None = None,
         max_seq_length_override: int | None = None,
         if_exists: CreateMode = "error",
-    ) -> LabeledMemoryset:
+        background: bool = False,
+    ) -> Self | Job[Self]:
         """
         Create a clone of the memoryset with a new name
 
         Params:
             name: Name for the new memoryset (must be unique)
             embedding_model: Optional new embedding model to use for re-embedding the memory values
-            max_seq_length_override: Maximum sequence length of values in the memoryset, if the
                 value is longer than this it will be truncated, will default to the model's max
                 sequence length if not provided
             if_exists: What to do if a memoryset with the same name already exists, defaults to
@@ -858,7 +1412,7 @@ class LabeledMemoryset:
 
         metadata = clone_memoryset(
             self.id,
-            body=CloneLabeledMemorysetRequest(
+            body=CloneMemorysetRequest(
                 name=name,
                 pretrained_embedding_model_name=(
                     embedding_model._model_name if isinstance(embedding_model, PretrainedEmbeddingModel) else None
@@ -869,8 +1423,11 @@ class LabeledMemoryset:
                 max_seq_length_override=max_seq_length_override,
             ),
         )
-        wait_for_task(metadata.insertion_task_id, description="Cloning memoryset")
-        return LabeledMemoryset.open(metadata.id)
+        job = Job(
+            metadata.insertion_task_id,
+            lambda: self.open(metadata.id),
+        )
+        return job if background else job.result()
 
     def refresh(self, throttle: float = 0):
         """
@@ -884,7 +1441,7 @@ class LabeledMemoryset:
         if (current_time - self._last_refresh) < timedelta(seconds=throttle):
             return
 
-        self.__dict__.update(LabeledMemoryset.open(self.id).__dict__)
+        self.__dict__.update(self.open(self.id).__dict__)
         self._last_refresh = current_time
 
     def __len__(self) -> int:
@@ -893,14 +1450,14 @@ class LabeledMemoryset:
         return self.length
 
     @overload
-    def __getitem__(self, index: int | str) -> LabeledMemory:
+    def __getitem__(self, index: int | str) -> MemoryT:
         pass
 
     @overload
-    def __getitem__(self, index: slice) -> list[LabeledMemory]:
+    def __getitem__(self, index: slice) -> list[MemoryT]:
         pass
 
-    def __getitem__(self, index: int | slice | str) -> LabeledMemory | list[LabeledMemory]:
+    def __getitem__(self, index: int | slice | str) -> MemoryT | list[MemoryT]:
         """
         Get memories from the memoryset by index or memory id
 
@@ -946,16 +1503,14 @@ class LabeledMemoryset:
             raise ValueError(f"Invalid index type: {type(index)}")
 
     @overload
-    def search(self, query: str, *, count: int = 1) -> list[LabeledMemoryLookup]:
+    def search(self, query: str, *, count: int = 1) -> list[MemoryLookupT]:
         pass
 
     @overload
-    def search(self, query: list[str], *, count: int = 1) -> list[list[LabeledMemoryLookup]]:
+    def search(self, query: list[str], *, count: int = 1) -> list[list[MemoryLookupT]]:
         pass
 
-    def search(
-        self, query: str | list[str], *, count: int = 1
-    ) -> list[LabeledMemoryLookup] | list[list[LabeledMemoryLookup]]:
+    def search(self, query: str | list[str], *, count: int = 1) -> list[MemoryLookupT] | list[list[MemoryLookupT]]:
         """
         Search for memories that are semantically similar to the query
 
@@ -989,12 +1544,22 @@ class LabeledMemoryset:
         """
         response = memoryset_lookup_gpu(
             name_or_id=self.id,
-            body=LookupRequest(
-                query=query if isinstance(query, list) else [query],
-                count=count,
-            ),
+            body=LookupRequest(query=query if isinstance(query, list) else [query], count=count),
         )
-        lookups = [[LabeledMemoryLookup(self.id, lookup_response) for lookup_response in batch] for batch in response]
+        lookups = [
+            [
+                cast(
+                    MemoryLookupT,
+                    (
+                        LabeledMemoryLookup(self.id, lookup_response)
+                        if isinstance(lookup_response, LabeledMemoryLookupResponse)
+                        else ScoredMemoryLookup(self.id, lookup_response)
+                    ),
+                )
+                for lookup_response in batch
+            ]
+            for batch in response
+        ]
         return lookups if isinstance(query, list) else lookups[0]
 
     def query(
@@ -1004,7 +1569,7 @@ class LabeledMemoryset:
         filters: list[FilterItemTuple] = [],
         with_feedback_metrics: bool = False,
         sort: list[TelemetrySortItem] | None = None,
-    ) -> list[LabeledMemory]:
+    ) -> list[MemoryT]:
         """
         Query the memoryset for memories that match the filters
 
@@ -1030,7 +1595,14 @@ class LabeledMemoryset:
 
         if with_feedback_metrics:
             return [
-                LabeledMemory(self.id, memory)
+                cast(
+                    MemoryT,
+                    (
+                        LabeledMemory(self.id, memory)
+                        if isinstance(memory, LabeledMemoryWithFeedbackMetrics)
+                        else ScoredMemory(self.id, memory)
+                    ),
+                )
                 for memory in list_memories_with_feedback(
                     body=TelemetryMemoriesRequest(
                         memoryset_id=self.id,
@@ -1049,7 +1621,14 @@ class LabeledMemoryset:
             logging.warning("Sorting is not supported when with_feedback_metrics is False. Sort value will be ignored.")
 
         return [
-            LabeledMemory(self.id, memory)
+            cast(
+                MemoryT,
+                (
+                    LabeledMemory(self.id, memory)
+                    if isinstance(memory, LabeledMemoryResponse)
+                    else ScoredMemory(self.id, memory)
+                ),
+            )
             for memory in query_memoryset(
                 self.id,
                 body=ListMemoriesRequest(
@@ -1070,6 +1649,7 @@ class LabeledMemoryset:
 
                 - `value`: Value of the memory
                 - `label`: Label of the memory
+                - `score`: Score of the memory
                 - `source_id`: Optional unique ID of the memory in a system of reference
                 - `...`: Any other metadata to store for the memory
 
@@ -1082,23 +1662,26 @@ class LabeledMemoryset:
         insert_memories_gpu(
             self.id,
             body=(
-                [
-                    _parse_memory_insert(memory)
-                    for memory in (cast(list[dict[str, Any]], [items]) if isinstance(items, dict) else items)
-                ]
+                cast(
+                    list[LabeledMemoryInsert] | list[ScoredMemoryInsert],
+                    [
+                        _parse_memory_insert(memory, type=self.memory_type)
+                        for memory in (cast(list[dict[str, Any]], [items]) if isinstance(items, dict) else items)
+                    ],
+                )
             ),
         )
         self.refresh()
 
     @overload
-    def get(self, memory_id: str) -> LabeledMemory:  # type: ignore -- this takes precedence
+    def get(self, memory_id: str) -> MemoryT:  # type: ignore -- this takes precedence
         pass
 
     @overload
-    def get(self, memory_id: Iterable[str]) -> list[LabeledMemory]:
+    def get(self, memory_id: Iterable[str]) -> list[MemoryT]:
         pass
 
-    def get(self, memory_id: str | Iterable[str]) -> LabeledMemory | list[LabeledMemory]:
+    def get(self, memory_id: str | Iterable[str]) -> MemoryT | list[MemoryT]:
         """
         Fetch a memory or memories from the memoryset
 
@@ -1127,22 +1710,38 @@ class LabeledMemoryset:
             ]
         """
         if isinstance(memory_id, str):
-            return LabeledMemory(self.id, get_memory(self.id, memory_id))
+            response = get_memory(self.id, memory_id)
+            return cast(
+                MemoryT,
+                (
+                    LabeledMemory(self.id, response)
+                    if isinstance(response, LabeledMemoryResponse)
+                    else ScoredMemory(self.id, response)
+                ),
+            )
         else:
+            response = get_memories(self.id, body=GetMemoriesRequest(memory_ids=list(memory_id)))
             return [
-                LabeledMemory(self.id, memory)
-                for memory in get_memories(self.id, body=GetMemoriesRequest(memory_ids=list(memory_id)))
+                cast(
+                    MemoryT,
+                    (
+                        LabeledMemory(self.id, memory)
+                        if isinstance(memory, LabeledMemoryResponse)
+                        else ScoredMemory(self.id, memory)
+                    ),
+                )
+                for memory in response
             ]
 
     @overload
-    def update(self, updates: dict[str, Any]) -> LabeledMemory:
+    def update(self, updates: dict[str, Any]) -> MemoryT:
         pass
 
     @overload
-    def update(self, updates: Iterable[dict[str, Any]]) -> list[LabeledMemory]:
+    def update(self, updates: Iterable[dict[str, Any]]) -> list[MemoryT]:
         pass
 
-    def update(self, updates: dict[str, Any] | Iterable[dict[str, Any]]) -> LabeledMemory | list[LabeledMemory]:
+    def update(self, updates: dict[str, Any] | Iterable[dict[str, Any]]) -> MemoryT | list[MemoryT]:
         """
         Update one or multiple memories in the memoryset
 
@@ -1176,17 +1775,30 @@ class LabeledMemoryset:
         """
         response = update_memories_gpu(
             self.id,
-            body=[
-                _parse_memory_update(update)
-                for update in (cast(list[dict[str, Any]], [updates]) if isinstance(updates, dict) else updates)
-            ],
+            body=cast(
+                list[LabeledMemoryUpdate] | list[ScoredMemoryUpdate],
+                [
+                    _parse_memory_update(update, type=self.memory_type)
+                    for update in (cast(list[dict[str, Any]], [updates]) if isinstance(updates, dict) else updates)
+                ],
+            ),
         )
-        updated_memories = [LabeledMemory(self.id, memory) for memory in response]
+        updated_memories = [
+            cast(
+                MemoryT,
+                (
+                    LabeledMemory(self.id, memory)
+                    if isinstance(memory, LabeledMemoryResponse)
+                    else ScoredMemory(self.id, memory)
+                ),
+            )
+            for memory in response
+        ]
         return updated_memories[0] if isinstance(updates, dict) else updated_memories
 
     def get_cascading_edits_suggestions(
-        self: LabeledMemoryset,
-        memory: LabeledMemory,
+        self,
+        memory: MemoryT,
         *,
         old_label: int,
         new_label: int,
@@ -1264,9 +1876,33 @@ class LabeledMemoryset:
         logging.info(f"Deleted {len(memory_ids)} memories from memoryset.")
         self.refresh()
 
+    @overload
+    def analyze(
+        self,
+        *analyses: Iterable[dict[str, Any] | str],
+        lookup_count: int = 15,
+        clear_metrics: bool = False,
+        background: Literal[True],
+    ) -> Job[dict]:
+        pass
+
+    @overload
     def analyze(
-        self, *analyses: Iterable[dict[str, Any] | str], lookup_count: int = 15, clear_metrics: bool = False
+        self,
+        *analyses: Iterable[dict[str, Any] | str],
+        lookup_count: int = 15,
+        clear_metrics: bool = False,
+        background: Literal[False] = False,
     ) -> dict:
+        pass
+
+    def analyze(
+        self,
+        *analyses: Iterable[dict[str, Any] | str],
+        lookup_count: int = 15,
+        clear_metrics: bool = False,
+        background: bool = False,
+    ) -> Job[dict] | dict:
         """
         Run analyses on the memoryset to find duplicates, clusters, mislabelings, and more
 
@@ -1357,34 +1993,58 @@ class LabeledMemoryset:
                 clear_metrics=clear_metrics,
             ),
         )
-        wait_for_task(analysis.task_id, description="Analyzing duplicates")
-        analysis = get_analysis(self.id, analysis.task_id)
-        assert analysis.results is not None
-        return analysis.results.to_dict()
-
-    def display_label_analysis(self):
-        """Display a UI to review and act upon the label analysis results"""
-        from ._utils.analysis_ui import display_suggested_memory_relabels
-
-        display_suggested_memory_relabels(self)
+        job = Job(
+            analysis.task_id,
+            lambda: (r := get_analysis(self.id, analysis.task_id).results) and r.to_dict(),
+        )
+        return job if background else job.result()
 
     def get_potential_duplicate_groups(self):
         """Group potential duplicates in the memoryset"""
         response = potential_duplicate_groups(self.name)
         return response
 
+    @overload
+    @staticmethod
+    def run_embedding_evaluation(
+        datasource: Datasource,
+        *,
+        value_column: str = "value",
+        label_column: str = "label",
+        source_id_column: str | None = None,
+        neighbor_count: int = 5,
+        embedding_models: list[str] | None = None,
+        background: Literal[True],
+    ) -> Job[dict]:
+        pass
+
+    @overload
     @staticmethod
     def run_embedding_evaluation(
         datasource: Datasource,
+        *,
         value_column: str = "value",
         label_column: str = "label",
         source_id_column: str | None = None,
         neighbor_count: int = 5,
         embedding_models: list[str] | None = None,
+        background: Literal[False] = False,
     ) -> dict:
+        pass
+
+    @staticmethod
+    def run_embedding_evaluation(
+        datasource: Datasource,
+        *,
+        value_column: str = "value",
+        label_column: str = "label",
+        source_id_column: str | None = None,
+        neighbor_count: int = 5,
+        embedding_models: list[str] | None = None,
+        background: bool = False,
+    ) -> Job[dict] | dict:
         """
-        This function runs an embedding evaluation on the datasource. The embedding evaluation will
-        test the quality of embeddings for the datasource by computing metrics such as prediction accuracy.
+        Test the quality of embeddings for the datasource by computing metrics such as prediction accuracy.
 
         Params:
             datasource: The datasource to run the embedding evaluation on
@@ -1415,8 +2075,69 @@ class LabeledMemoryset:
         )
 
         response = create_embedding_evaluation(name_or_id=datasource.id, body=request)
-        wait_for_task(response.task_id, description="Running embedding evaluation")
+        job = Job(
+            response.task_id,
+            lambda: (r := get_embedding_evaluation(datasource.id, response.task_id).result) and r.to_dict(),
+        )
+        return job if background else job.result()
+
+
+class LabeledMemoryset(_Memoryset[LabeledMemory, LabeledMemoryLookup]):
+    """
+    A Handle to a collection of memories with labels in the OrcaCloud
+
+    Attributes:
+        id: Unique identifier for the memoryset
+        name: Unique name of the memoryset
+        description: Description of the memoryset
+        label_names: Names for the class labels in the memoryset
+        length: Number of memories in the memoryset
+        embedding_model: Embedding model used to embed the memory values for semantic search
+        created_at: When the memoryset was created, automatically generated on create
+        updated_at: When the memoryset was last updated, automatically updated on updates
+    """
 
-        response = get_embedding_evaluation(datasource.id, response.task_id)
-        assert response.result is not None
-        return response.result.to_dict()
+    label_names: list[str]
+    memory_type: MemoryType = MemoryType.LABELED
+
+    def __init__(self, metadata: MemorysetMetadata):
+        super().__init__(metadata)
+        assert metadata.label_names is not None
+        self.label_names = metadata.label_names
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, LabeledMemoryset) and self.id == other.id
+
+    @classmethod
+    def create(cls, name: str, datasource: Datasource, *, label_column: str | None = "label", **kwargs):
+        return super().create(name, datasource, label_column=label_column, score_column=None, **kwargs)
+
+    def display_label_analysis(self):
+        """Display a UI to review and act upon the label analysis results"""
+        from ._utils.analysis_ui import display_suggested_memory_relabels
+
+        display_suggested_memory_relabels(self)
+
+
+class ScoredMemoryset(_Memoryset[ScoredMemory, ScoredMemoryLookup]):
+    """
+    A Handle to a collection of memories with scores in the OrcaCloud
+
+    Attributes:
+        id: Unique identifier for the memoryset
+        name: Unique name of the memoryset
+        description: Description of the memoryset
+        length: Number of memories in the memoryset
+        embedding_model: Embedding model used to embed the memory values for semantic search
+        created_at: When the memoryset was created, automatically generated on create
+        updated_at: When the memoryset was last updated, automatically updated on updates
+    """
+
+    memory_type: MemoryType = MemoryType.SCORED
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, ScoredMemoryset) and self.id == other.id
+
+    @classmethod
+    def create(cls, name: str, datasource: Datasource, *, score_column: str | None = "score", **kwargs):
+        return super().create(name, datasource, score_column=score_column, label_column=None, **kwargs)