orca-sdk 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

orca_sdk/memoryset.py

@@ -16,11 +16,7 @@ from typing import (
     overload,
 )
 
-import pandas as pd
-import pyarrow as pa
 from datasets import Dataset
-from torch.utils.data import DataLoader as TorchDataLoader
-from torch.utils.data import Dataset as TorchDataset
 
 from ._utils.common import UNSET, CreateMode, DropMode
 from .async_client import OrcaAsyncClient
@@ -30,6 +26,7 @@ from .client import (
     CreateMemorysetFromDatasourceRequest,
     CreateMemorysetRequest,
     FilterItem,
+    LabeledBatchMemoryUpdatePatch,
 )
 from .client import LabeledMemory as LabeledMemoryResponse
 from .client import (
@@ -49,6 +46,7 @@ from .client import (
     MemorysetUpdate,
     MemoryType,
     OrcaClient,
+    ScoredBatchMemoryUpdatePatch,
 )
 from .client import ScoredMemory as ScoredMemoryResponse
 from .client import (
@@ -74,6 +72,12 @@ from .job import Job, Status
 from .telemetry import ClassificationPrediction, RegressionPrediction
 
 if TYPE_CHECKING:
+    # peer dependencies that are used for types only
+    from pandas import DataFrame as PandasDataFrame  # type: ignore
+    from pyarrow import Table as PyArrowTable  # type: ignore
+    from torch.utils.data import DataLoader as TorchDataLoader  # type: ignore
+    from torch.utils.data import Dataset as TorchDataset  # type: ignore
+
     from .classification_model import ClassificationModel
     from .regression_model import RegressionModel
 
@@ -94,7 +98,21 @@ FilterOperation = Literal["==", "!=", ">", ">=", "<", "<=", "in", "not in", "lik
 Operations that can be used in a filter expression.
 """
 
-FilterValue = str | int | float | bool | datetime | None | list[str | None] | list[int] | list[float] | list[bool]
+FilterValue = (
+    str
+    | int
+    | float
+    | bool
+    | datetime
+    | list[None]
+    | list[str]
+    | list[str | None]
+    | list[int]
+    | list[int | None]
+    | list[float]
+    | list[bool]
+    | None
+)
 """
 Values that can be used in a filter expression.
 """
@@ -134,7 +152,21 @@ def _is_metric_column(column: str):
     return column in ["feedback_metrics", "lookup"]
 
 
-def _parse_filter_item_from_tuple(input: FilterItemTuple) -> FilterItem | TelemetryFilterItem:
+@overload
+def _parse_filter_item_from_tuple(input: FilterItemTuple, allow_metric_fields: Literal[False]) -> FilterItem:
+    pass
+
+
+@overload
+def _parse_filter_item_from_tuple(
+    input: FilterItemTuple, allow_metric_fields: Literal[True] = True
+) -> FilterItem | TelemetryFilterItem:
+    pass
+
+
+def _parse_filter_item_from_tuple(
+    input: FilterItemTuple, allow_metric_fields: bool = True
+) -> FilterItem | TelemetryFilterItem:
     field = input[0].split(".")
     if (
         len(field) == 1
@@ -146,6 +178,8 @@ def _parse_filter_item_from_tuple(input: FilterItemTuple) -> FilterItem | Teleme
     if isinstance(value, datetime):
         value = value.isoformat()
     if _is_metric_column(field[0]):
+        if not allow_metric_fields:
+            raise ValueError(f"Cannot filter on {field[0]} - metric fields are not supported")
         if not (
             (isinstance(value, list) and all(isinstance(v, float) or isinstance(v, int) for v in value))
             or isinstance(value, float)
@@ -165,7 +199,7 @@ def _parse_filter_item_from_tuple(input: FilterItemTuple) -> FilterItem | Teleme
         return TelemetryFilterItem(field=cast(TelemetryField, tuple(field)), op=op, value=value)
 
     # Convert list to tuple for FilterItem field type
-    return FilterItem(field=tuple(field), op=op, value=value)  # type: ignore[assignment]
+    return FilterItem(field=tuple[Any, ...](field), op=op, value=value)
 
 
 def _parse_sort_item_from_tuple(
@@ -238,17 +272,29 @@ def _parse_memory_insert(memory: dict[str, Any], type: MemoryType) -> LabeledMem
             }
 
 
-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"]
-    if not isinstance(memory_id, str):
-        raise ValueError("memory_id must be a string")
-    payload: LabeledMemoryUpdate | ScoredMemoryUpdate = {"memory_id": memory_id}
-    if "value" in update:
-        if not isinstance(update["value"], str):
-            raise ValueError("value must be a string or unset")
-        payload["value"] = update["value"]
+def _extract_metadata_for_patch(update: dict[str, Any], exclude_keys: set[str]) -> dict[str, Any] | None:
+    """Extract metadata from update dict for patch operations.
+
+    Returns the metadata dict to include in the payload, or None if metadata should be omitted
+    (to preserve existing metadata on the server).
+    """
+    if "metadata" in update and update["metadata"] is not None:
+        # User explicitly provided metadata dict (could be {} to clear all metadata)
+        metadata = update["metadata"]
+        if not isinstance(metadata, dict):
+            raise ValueError("metadata must be a dict")
+        return metadata
+    # Extract metadata from top-level keys, only include if non-empty
+    metadata = {k: v for k, v in update.items() if k not in DEFAULT_COLUMN_NAMES | exclude_keys}
+    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 metadata if metadata else None
+
+
+def _parse_memory_update_patch(
+    update: dict[str, Any], type: MemoryType
+) -> LabeledBatchMemoryUpdatePatch | ScoredBatchMemoryUpdatePatch:
+    payload: LabeledBatchMemoryUpdatePatch | ScoredBatchMemoryUpdatePatch = {}
     if "source_id" in update:
         source_id = update["source_id"]
         if source_id is not None and not isinstance(source_id, str):
@@ -261,31 +307,41 @@ def _parse_memory_update(update: dict[str, Any], type: MemoryType) -> LabeledMem
         payload["partition_id"] = partition_id
     match type:
         case "LABELED":
-            payload = cast(LabeledMemoryUpdate, payload)
+            payload = cast(LabeledBatchMemoryUpdatePatch, payload)
             if "label" in update:
                 if not isinstance(update["label"], int):
                     raise ValueError("label must be an integer or unset")
                 payload["label"] = update["label"]
-            metadata = {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)}"
-                )
-            payload["metadata"] = metadata
+            metadata = _extract_metadata_for_patch(update, {"memory_id", "label", "metadata"})
+            if metadata is not None:
+                payload["metadata"] = metadata
             return payload
         case "SCORED":
-            payload = cast(ScoredMemoryUpdate, payload)
+            payload = cast(ScoredBatchMemoryUpdatePatch, payload)
             if "score" in update:
                 if not isinstance(update["score"], (int, float)):
                     raise ValueError("score must be a number or unset")
                 payload["score"] = update["score"]
-            metadata = {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)}"
-                )
-            payload["metadata"] = metadata
-            return cast(ScoredMemoryUpdate, payload)
+            metadata = _extract_metadata_for_patch(update, {"memory_id", "score", "metadata"})
+            if metadata is not None:
+                payload["metadata"] = metadata
+            return payload
+
+
+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"]
+    if not isinstance(memory_id, str):
+        raise ValueError("memory_id must be a string")
+    payload: LabeledMemoryUpdate | ScoredMemoryUpdate = {"memory_id": memory_id}
+    if "value" in update:
+        if not isinstance(update["value"], str):
+            raise ValueError("value must be a string or unset")
+        payload["value"] = update["value"]
+    for key, value in _parse_memory_update_patch(update, type).items():
+        payload[key] = value
+    return payload
 
 
 class MemoryBase(ABC):
@@ -1817,7 +1873,7 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
     def from_pandas(
         cls,
         name: str,
-        dataframe: pd.DataFrame,
+        dataframe: PandasDataFrame,
         *,
         background: Literal[True],
         **kwargs: Any,
@@ -1829,7 +1885,7 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
     def from_pandas(
         cls,
         name: str,
-        dataframe: pd.DataFrame,
+        dataframe: PandasDataFrame,
         *,
         background: Literal[False] = False,
         **kwargs: Any,
@@ -1840,7 +1896,7 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
     def from_pandas(
         cls,
         name: str,
-        dataframe: pd.DataFrame,
+        dataframe: PandasDataFrame,
         *,
         background: bool = False,
         **kwargs: Any,
@@ -1883,7 +1939,7 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
     def from_arrow(
         cls,
         name: str,
-        pyarrow_table: pa.Table,
+        pyarrow_table: PyArrowTable,
         *,
         background: Literal[True],
         **kwargs: Any,
@@ -1895,7 +1951,7 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
     def from_arrow(
         cls,
         name: str,
-        pyarrow_table: pa.Table,
+        pyarrow_table: PyArrowTable,
         *,
         background: Literal[False] = False,
         **kwargs: Any,
@@ -1906,7 +1962,7 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
     def from_arrow(
         cls,
         name: str,
-        pyarrow_table: pa.Table,
+        pyarrow_table: PyArrowTable,
         *,
         background: bool = False,
         **kwargs: Any,
@@ -2090,7 +2146,7 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
         ]
 
     @classmethod
-    def drop(cls, name_or_id: str, if_not_exists: DropMode = "error"):
+    def drop(cls, name_or_id: str, if_not_exists: DropMode = "error", cascade: bool = False):
         """
         Delete a memoryset from the OrcaCloud
 
@@ -2098,13 +2154,16 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
             name_or_id: Name or id of the memoryset
             if_not_exists: What to do if the memoryset does not exist, defaults to `"error"`.
                 Other options are `"ignore"` to do nothing if the memoryset does not exist.
+            cascade: If True, also delete all associated predictive models and predictions.
+                Defaults to False.
 
         Raises:
             LookupError: If the memoryset does not exist and if_not_exists is `"error"`
+            RuntimeError: If the memoryset has associated models and cascade is False
         """
         try:
             client = OrcaClient._resolve_client()
-            client.DELETE("/memoryset/{name_or_id}", params={"name_or_id": name_or_id})
+            client.DELETE("/memoryset/{name_or_id}", params={"name_or_id": name_or_id, "cascade": cascade})
             logging.info(f"Deleted memoryset {name_or_id}")
         except LookupError:
             if if_not_exists == "error":
@@ -2436,10 +2495,6 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
         filters: list[FilterItemTuple] = [],
         with_feedback_metrics: bool = False,
         sort: list[TelemetrySortItem] | None = None,
-        partition_id: str | None = None,
-        partition_filter_mode: Literal[
-            "ignore_partitions", "include_global", "exclude_global", "only_global"
-        ] = "include_global",
     ) -> list[MemoryT]:
         """
         Query the memoryset for memories that match the filters
@@ -2460,26 +2515,16 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
                 LabeledMemory({ label: <negative: 0>, value: "I am sad" }),
             ]
         """
-        parsed_filters = [
-            _parse_filter_item_from_tuple(filter) if isinstance(filter, tuple) else filter for filter in filters
-        ]
 
+        client = OrcaClient._resolve_client()
         if with_feedback_metrics:
-            if partition_id:
-                raise ValueError("Partition ID is not supported when with_feedback_metrics is True")
-            if partition_filter_mode != "include_global":
-                raise ValueError(
-                    f"Partition filter mode {partition_filter_mode} is not supported when with_feedback_metrics is True. Only 'include_global' is supported."
-                )
-
-            client = OrcaClient._resolve_client()
             response = client.POST(
                 "/telemetry/memories",
                 json={
                     "memoryset_id": self.id,
                     "offset": offset,
                     "limit": limit,
-                    "filters": parsed_filters,
+                    "filters": [_parse_filter_item_from_tuple(filter) for filter in filters],
                     "sort": [_parse_sort_item_from_tuple(item) for item in sort] if sort else None,
                 },
             )
@@ -2497,16 +2542,13 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
         if sort:
             logging.warning("Sorting is not supported when with_feedback_metrics is False. Sort value will be ignored.")
 
-        client = OrcaClient._resolve_client()
         response = client.POST(
             "/memoryset/{name_or_id}/memories",
             params={"name_or_id": self.id},
             json={
                 "offset": offset,
                 "limit": limit,
-                "filters": cast(list[FilterItem], parsed_filters),
-                "partition_id": partition_id,
-                "partition_filter_mode": partition_filter_mode,
+                "filters": [_parse_filter_item_from_tuple(filter, allow_metric_fields=False) for filter in filters],
             },
         )
         return [
@@ -2524,11 +2566,16 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
         filters: list[FilterItemTuple] = [],
         with_feedback_metrics: bool = False,
         sort: list[TelemetrySortItem] | None = None,
-    ) -> pd.DataFrame:
+    ) -> PandasDataFrame:
         """
         Convert the memoryset to a pandas DataFrame
         """
-        return pd.DataFrame(
+        try:
+            from pandas import DataFrame as PandasDataFrame  # type: ignore
+        except ImportError:
+            raise ImportError("Install pandas to use this method")
+
+        return PandasDataFrame(
             [
                 memory.to_dict()
                 for memory in self.query(
@@ -2699,18 +2746,28 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
             ]
 
     @overload
-    def update(self, updates: dict[str, Any], *, batch_size: int = 32) -> MemoryT:
+    def update(self, updates: dict[str, Any] | Iterable[dict[str, Any]], *, batch_size: int = 32) -> int:
         pass
 
     @overload
-    def update(self, updates: Iterable[dict[str, Any]], *, batch_size: int = 32) -> list[MemoryT]:
+    def update(
+        self,
+        *,
+        filters: list[FilterItemTuple],
+        patch: dict[str, Any],
+    ) -> int:
         pass
 
     def update(
-        self, updates: dict[str, Any] | Iterable[dict[str, Any]], *, batch_size: int = 32
-    ) -> MemoryT | list[MemoryT]:
+        self,
+        updates: dict[str, Any] | Iterable[dict[str, Any]] | None = None,
+        *,
+        batch_size: int = 32,
+        filters: list[FilterItemTuple] | None = None,
+        patch: dict[str, Any] | None = None,
+    ) -> int:
         """
-        Update one or multiple memories in the memoryset
+        Update one or multiple memories in the memoryset.
 
         Params:
             updates: List of updates to apply to the memories. Each update should be a dictionary
@@ -2723,10 +2780,12 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
                 - `partition_id`: Optional new partition ID of the memory
                 - `...`: Optional new values for metadata properties
 
-            batch_size: Number of memories to update in a single API call
+            filters: Filters to match memories against. Each filter is a tuple of (field, operation, value).
+            patch: Patch to apply to matching memories (only used with filters).
+            batch_size: Number of memories to update in a single API call (only used with updates)
 
         Returns:
-            Updated memory or list of updated memories
+            The number of memories updated.
 
         Examples:
             Update a single memory:
@@ -2742,32 +2801,57 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
             ...     {"memory_id": m.memory_id, "label": 2}
             ...     for m in memoryset.query(filters=[("tag", "==", "happy")])
             ... )
+
+            Update all memories matching a filter:
+            >>> memoryset.update(filters=[("label", "==", 0)], patch={"label": 1})
         """
         if batch_size <= 0 or batch_size > 500:
             raise ValueError("batch_size must be between 1 and 500")
+
         client = OrcaClient._resolve_client()
-        updates_list = cast(list[dict[str, Any]], [updates]) if isinstance(updates, dict) else list(updates)
-        # update memories in batches to avoid API timeouts
-        updated_memories: list[MemoryT] = []
-        for i in range(0, len(updates_list), batch_size):
-            batch = updates_list[i : i + batch_size]
-            response = client.PATCH(
-                "/gpu/memoryset/{name_or_id}/memories",
-                params={"name_or_id": self.id},
-                json=cast(
-                    list[LabeledMemoryUpdate] | list[ScoredMemoryUpdate],
-                    [_parse_memory_update(update, type=self.memory_type) for update in batch],
-                ),
-            )
-            updated_memories.extend(
-                cast(
-                    MemoryT,
-                    (LabeledMemory(self.id, memory) if "label" in memory else ScoredMemory(self.id, memory)),
+
+        # Convert updates to list
+        single_update = isinstance(updates, dict)
+        updates_list: list[dict[str, Any]] | None
+        if single_update:
+            updates_list = [updates]  # type: ignore[list-item]
+        elif updates is not None:
+            updates_list = [u for u in updates]  # type: ignore[misc]
+        else:
+            updates_list = None
+
+        # Batch updates to avoid API timeouts
+        if updates_list and len(updates_list) > batch_size:
+            updated_count: int = 0
+            for i in range(0, len(updates_list), batch_size):
+                batch = updates_list[i : i + batch_size]
+                response = client.PATCH(
+                    "/gpu/memoryset/{name_or_id}/memories",
+                    params={"name_or_id": self.id},
+                    json={"updates": [_parse_memory_update(update, type=self.memory_type) for update in batch]},
                 )
-                for memory in response
-            )
+                updated_count += response["updated_count"]
+            return updated_count
 
-        return updated_memories[0] if isinstance(updates, dict) else updated_memories
+        # Single request for all other cases
+        response = client.PATCH(
+            "/gpu/memoryset/{name_or_id}/memories",
+            params={"name_or_id": self.id},
+            json={
+                "updates": (
+                    [_parse_memory_update(update, type=self.memory_type) for update in updates_list]
+                    if updates_list is not None
+                    else None
+                ),
+                "filters": (
+                    [_parse_filter_item_from_tuple(filter, allow_metric_fields=False) for filter in filters]
+                    if filters is not None
+                    else None
+                ),
+                "patch": _parse_memory_update_patch(patch, type=self.memory_type) if patch is not None else None,
+            },
+        )
+        return response["updated_count"]
 
     def get_cascading_edits_suggestions(
         self,
@@ -2826,37 +2910,128 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
             },
         )
 
-    def delete(self, memory_id: str | Iterable[str], *, batch_size: int = 32) -> None:
+    @overload
+    def delete(self, memory_id: str | Iterable[str], *, batch_size: int = 32) -> int:
+        pass
+
+    @overload
+    def delete(
+        self,
+        *,
+        filters: list[FilterItemTuple],
+    ) -> int:
+        pass
+
+    def delete(
+        self,
+        memory_id: str | Iterable[str] | None = None,
+        *,
+        batch_size: int = 32,
+        filters: list[FilterItemTuple] | None = None,
+    ) -> int:
         """
-        Delete memories from the memoryset
+        Delete memories from the memoryset.
+
 
         Params:
             memory_id: unique identifiers of the memories to delete
-            batch_size: Number of memories to delete in a single API call
+            filters: Filters to match memories against. Each filter is a tuple of (field, operation, value).
+            batch_size: Number of memories to delete in a single API call (only used with memory_id)
+
+        Returns:
+            The number of memories deleted.
 
         Examples:
-            Delete a single memory:
+            Delete a single memory by ID:
             >>> memoryset.delete("0195019a-5bc7-7afb-b902-5945ee1fb766")
 
-            Delete multiple memories:
+            Delete multiple memories by ID:
             >>> memoryset.delete([
             ...     "0195019a-5bc7-7afb-b902-5945ee1fb766",
             ...     "019501a1-ea08-76b2-9f62-95e4800b4841",
-            ... )
+            ... ])
+
+            Delete all memories matching a filter:
+            >>> deleted_count = memoryset.delete(filters=[("label", "==", 0)])
 
         """
         if batch_size <= 0 or batch_size > 500:
             raise ValueError("batch_size must be between 1 and 500")
+        if memory_id is not None and filters is not None:
+            raise ValueError("Cannot specify memory_ids together with filters")
+
         client = OrcaClient._resolve_client()
-        memory_ids = [memory_id] if isinstance(memory_id, str) else list(memory_id)
-        # delete memories in batches to avoid API timeouts
-        for i in range(0, len(memory_ids), batch_size):
-            batch = memory_ids[i : i + batch_size]
-            client.POST(
-                "/memoryset/{name_or_id}/memories/delete", params={"name_or_id": self.id}, json={"memory_ids": batch}
-            )
-        logging.info(f"Deleted {len(memory_ids)} memories from memoryset.")
-        self.refresh()
+
+        # Convert memory_id to list
+        if isinstance(memory_id, str):
+            memory_ids = [memory_id]
+        elif memory_id is not None:
+            memory_ids = list(memory_id)
+        else:
+            memory_ids = None
+
+        # Batch memory_id deletions to avoid API timeouts
+        if memory_ids and len(memory_ids) > batch_size:
+            total_deleted = 0
+            for i in range(0, len(memory_ids), batch_size):
+                batch = memory_ids[i : i + batch_size]
+                response = client.POST(
+                    "/memoryset/{name_or_id}/memories/delete",
+                    params={"name_or_id": self.id},
+                    json={"memory_ids": batch},
+                )
+                total_deleted += response.get("deleted_count", 0)
+            if total_deleted > 0:
+                logging.info(f"Deleted {total_deleted} memories from memoryset.")
+                self.refresh()
+            return total_deleted
+
+        # Single request for all other cases
+        response = client.POST(
+            "/memoryset/{name_or_id}/memories/delete",
+            params={"name_or_id": self.id},
+            json={
+                "memory_ids": memory_ids,
+                "filters": (
+                    [_parse_filter_item_from_tuple(filter, allow_metric_fields=False) for filter in filters]
+                    if filters is not None
+                    else None
+                ),
+            },
+        )
+        deleted_count = response["deleted_count"]
+        logging.info(f"Deleted {deleted_count} memories from memoryset.")
+        if deleted_count > 0:
+            self.refresh()
+        return deleted_count
+
+    def truncate(self, *, partition_id: str | None = UNSET) -> int:
+        """
+        Delete all memories from the memoryset or a specified partition.
+
+        Params:
+            partition_id: Optional partition ID to truncate, `None` refers to the global partition.
+
+        Returns:
+            The number of deleted memories.
+        """
+        client = OrcaClient._resolve_client()
+        response = client.POST(
+            "/memoryset/{name_or_id}/memories/delete",
+            params={"name_or_id": self.id},
+            json={
+                "filters": (
+                    [FilterItem(field=("partition_id",), op="==", value=partition_id)]
+                    if partition_id is not UNSET
+                    else [FilterItem(field=("memory_id",), op="!=", value=None)]  # match all
+                ),
+            },
+        )
+        deleted_count = response["deleted_count"]
+        logging.info(f"Deleted {deleted_count} memories from memoryset.")
+        if deleted_count > 0:
+            self.refresh()
+        return deleted_count
 
     @overload
     def analyze(
@@ -3003,10 +3178,21 @@ class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
         job = Job(analysis["job_id"], get_analysis_result)
         return job if background else job.result()
 
-    def get_potential_duplicate_groups(self) -> list[list[MemoryT]]:
-        """Group potential duplicates in the memoryset"""
+    def get_potential_duplicate_groups(self) -> list[list[MemoryT]] | None:
+        """
+        Group potential duplicates in the memoryset.
+
+        Returns:
+            List of groups of potentially duplicate memories, where each group is a list of memories.
+            Returns None if duplicate analysis has not been run on this memoryset yet.
+
+        Raises:
+            LookupError: If the memoryset does not exist.
+        """
         client = OrcaClient._resolve_client()
         response = client.GET("/memoryset/{name_or_id}/potential_duplicate_groups", params={"name_or_id": self.id})
+        if response is None:
+            return None
         return [
             [cast(MemoryT, LabeledMemory(self.id, m) if "label" in m else ScoredMemory(self.id, m)) for m in ms]
             for ms in response
@@ -3434,6 +3620,22 @@ class LabeledMemoryset(MemorysetBase[LabeledMemory, LabeledMemoryLookup]):
 
         display_suggested_memory_relabels(self)
 
+    @property
+    def classification_models(self) -> list[ClassificationModel]:
+        """
+        List all classification models that use this memoryset
+
+        Returns:
+            List of classification models associated with this memoryset
+        """
+        from .classification_model import ClassificationModel
+
+        client = OrcaClient._resolve_client()
+        return [
+            ClassificationModel(metadata)
+            for metadata in client.GET("/classification_model", params={"memoryset_name_or_id": str(self.id)})
+        ]
+
 
 class ScoredMemoryset(MemorysetBase[ScoredMemory, ScoredMemoryLookup]):
     """
@@ -3809,3 +4011,19 @@ class ScoredMemoryset(MemorysetBase[ScoredMemory, ScoredMemoryLookup]):
                 subsample=subsample,
                 memory_type="SCORED",
             )
+
+    @property
+    def regression_models(self) -> list[RegressionModel]:
+        """
+        List all regression models that use this memoryset
+
+        Returns:
+            List of regression models associated with this memoryset
+        """
+        from .regression_model import RegressionModel
+
+        client = OrcaClient._resolve_client()
+        return [
+            RegressionModel(metadata)
+            for metadata in client.GET("/regression_model", params={"memoryset_name_or_id": str(self.id)})
+        ]