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

orca_sdk/embedding_model.py

@@ -1,93 +1,327 @@
 from __future__ import annotations
 
-from abc import abstractmethod
+from abc import ABC, abstractmethod
 from datetime import datetime
-from typing import TYPE_CHECKING, Sequence, cast, overload
-
-from ._generated_api_client.api import (
-    create_finetuned_embedding_model,
-    delete_finetuned_embedding_model,
-    embed_with_finetuned_model_gpu,
-    embed_with_pretrained_model_gpu,
-    get_finetuned_embedding_model,
-    get_pretrained_embedding_model,
-    list_finetuned_embedding_models,
-    list_pretrained_embedding_models,
-)
-from ._generated_api_client.models import (
+from typing import TYPE_CHECKING, Literal, Sequence, cast, get_args, overload
+
+from ._shared.metrics import ClassificationMetrics, RegressionMetrics
+from ._utils.common import UNSET, CreateMode, DropMode
+from .client import (
+    EmbeddingEvaluationRequest,
     EmbeddingFinetuningMethod,
     EmbedRequest,
     FinetunedEmbeddingModelMetadata,
     FinetuneEmbeddingModelRequest,
-    FinetuneEmbeddingModelRequestTrainingArgs,
+    OrcaClient,
     PretrainedEmbeddingModelMetadata,
     PretrainedEmbeddingModelName,
 )
-from ._utils.common import CreateMode, DropMode
-from ._utils.task import TaskStatus, wait_for_task
 from .datasource import Datasource
+from .job import Job, Status
 
 if TYPE_CHECKING:
     from .memoryset import LabeledMemoryset
 
 
-class _EmbeddingModel:
-    name: str
+class EmbeddingModelBase(ABC):
     embedding_dim: int
     max_seq_length: int
     uses_context: bool
+    supports_instructions: bool
 
-    def __init__(self, *, name: str, embedding_dim: int, max_seq_length: int, uses_context: bool):
-        self.name = name
+    def __init__(
+        self, *, name: str, embedding_dim: int, max_seq_length: int, uses_context: bool, supports_instructions: bool
+    ):
         self.embedding_dim = embedding_dim
         self.max_seq_length = max_seq_length
         self.uses_context = uses_context
+        self.supports_instructions = supports_instructions
 
     @classmethod
     @abstractmethod
-    def all(cls) -> Sequence[_EmbeddingModel]:
+    def all(cls) -> Sequence[EmbeddingModelBase]:
         pass
 
+    def _get_instruction_error_message(self) -> str:
+        """Get error message for instruction not supported"""
+        if isinstance(self, FinetunedEmbeddingModel):
+            return f"Model {self.name} does not support instructions. Instruction-following is only supported by models based on instruction-supporting models."
+        elif isinstance(self, PretrainedEmbeddingModel):
+            return f"Model {self.name} does not support instructions. Instruction-following is only supported by instruction-supporting models."
+        else:
+            raise ValueError("Invalid embedding model")
+
     @overload
-    def embed(self, value: str, max_seq_length: int | None = None) -> list[float]:
+    def embed(self, value: str, max_seq_length: int | None = None, prompt: str | None = None) -> list[float]:
         pass
 
     @overload
-    def embed(self, value: list[str], max_seq_length: int | None = None) -> list[list[float]]:
+    def embed(
+        self, value: list[str], max_seq_length: int | None = None, prompt: str | None = None
+    ) -> list[list[float]]:
         pass
 
-    def embed(self, value: str | list[str], max_seq_length: int | None = None) -> list[float] | list[list[float]]:
+    def embed(
+        self, value: str | list[str], max_seq_length: int | None = None, prompt: str | None = None
+    ) -> list[float] | list[list[float]]:
         """
         Generate embeddings for a value or list of values
 
         Params:
             value: The value or list of values to embed
             max_seq_length: The maximum sequence length to truncate the input to
+            prompt: Optional prompt for prompt-following embedding models.
 
         Returns:
             A matrix of floats representing the embedding for each value if the input is a list of
                 values, or a list of floats representing the embedding for the single value if the
                 input is a single value
         """
-        request = EmbedRequest(values=value if isinstance(value, list) else [value], max_seq_length=max_seq_length)
+        payload: EmbedRequest = {
+            "values": value if isinstance(value, list) else [value],
+            "max_seq_length": max_seq_length,
+            "prompt": prompt,
+        }
+        client = OrcaClient._resolve_client()
         if isinstance(self, PretrainedEmbeddingModel):
-            embeddings = embed_with_pretrained_model_gpu(self._model_name, body=request)
+            embeddings = client.POST(
+                "/gpu/pretrained_embedding_model/{model_name}/embedding",
+                params={"model_name": cast(PretrainedEmbeddingModelName, self.name)},
+                json=payload,
+                timeout=30,  # may be slow in case of cold start
+            )
         elif isinstance(self, FinetunedEmbeddingModel):
-            embeddings = embed_with_finetuned_model_gpu(self.id, body=request)
+            embeddings = client.POST(
+                "/gpu/finetuned_embedding_model/{name_or_id}/embedding",
+                params={"name_or_id": self.id},
+                json=payload,
+                timeout=30,  # may be slow in case of cold start
+            )
         else:
             raise ValueError("Invalid embedding model")
         return embeddings if isinstance(value, list) else embeddings[0]
 
+    @overload
+    def evaluate(
+        self,
+        datasource: Datasource,
+        *,
+        value_column: str = "value",
+        label_column: str,
+        score_column: None = None,
+        eval_datasource: Datasource | None = None,
+        subsample: int | None = None,
+        neighbor_count: int = 5,
+        batch_size: int = 32,
+        weigh_memories: bool = True,
+        background: Literal[True],
+    ) -> Job[ClassificationMetrics]:
+        pass
 
-class _PretrainedEmbeddingModelMeta(type):
-    def __getattr__(cls, name: str) -> PretrainedEmbeddingModel:
-        if cls != FinetunedEmbeddingModel and name in PretrainedEmbeddingModelName.__members__:
-            return PretrainedEmbeddingModel._get(name)
+    @overload
+    def evaluate(
+        self,
+        datasource: Datasource,
+        *,
+        value_column: str = "value",
+        label_column: str,
+        score_column: None = None,
+        eval_datasource: Datasource | None = None,
+        subsample: int | None = None,
+        neighbor_count: int = 5,
+        batch_size: int = 32,
+        weigh_memories: bool = True,
+        background: Literal[False] = False,
+    ) -> ClassificationMetrics:
+        pass
+
+    @overload
+    def evaluate(
+        self,
+        datasource: Datasource,
+        *,
+        value_column: str = "value",
+        label_column: None = None,
+        score_column: str,
+        eval_datasource: Datasource | None = None,
+        subsample: int | None = None,
+        neighbor_count: int = 5,
+        batch_size: int = 32,
+        weigh_memories: bool = True,
+        background: Literal[True],
+    ) -> Job[RegressionMetrics]:
+        pass
+
+    @overload
+    def evaluate(
+        self,
+        datasource: Datasource,
+        *,
+        value_column: str = "value",
+        label_column: None = None,
+        score_column: str,
+        eval_datasource: Datasource | None = None,
+        subsample: int | None = None,
+        neighbor_count: int = 5,
+        batch_size: int = 32,
+        weigh_memories: bool = True,
+        background: Literal[False] = False,
+    ) -> RegressionMetrics:
+        pass
+
+    def evaluate(
+        self,
+        datasource: Datasource,
+        *,
+        value_column: str = "value",
+        label_column: str | None = None,
+        score_column: str | None = None,
+        eval_datasource: Datasource | None = None,
+        subsample: int | None = None,
+        neighbor_count: int = 5,
+        batch_size: int = 32,
+        weigh_memories: bool = True,
+        background: bool = False,
+    ) -> (
+        ClassificationMetrics
+        | RegressionMetrics
+        | Job[ClassificationMetrics]
+        | Job[RegressionMetrics]
+        | Job[ClassificationMetrics | RegressionMetrics]
+    ):
+        """
+        Evaluate the finetuned embedding model
+        """
+        payload: EmbeddingEvaluationRequest = {
+            "datasource_name_or_id": datasource.id,
+            "datasource_label_column": label_column,
+            "datasource_value_column": value_column,
+            "datasource_score_column": score_column,
+            "eval_datasource_name_or_id": eval_datasource.id if eval_datasource is not None else None,
+            "subsample": subsample,
+            "neighbor_count": neighbor_count,
+            "batch_size": batch_size,
+            "weigh_memories": weigh_memories,
+        }
+        client = OrcaClient._resolve_client()
+        if isinstance(self, PretrainedEmbeddingModel):
+            response = client.POST(
+                "/pretrained_embedding_model/{model_name}/evaluation",
+                params={"model_name": self.name},
+                json=payload,
+            )
+        elif isinstance(self, FinetunedEmbeddingModel):
+            response = client.POST(
+                "/finetuned_embedding_model/{name_or_id}/evaluation",
+                params={"name_or_id": self.id},
+                json=payload,
+            )
         else:
-            raise AttributeError(f"'{cls.__name__}' object has no attribute '{name}'")
+            raise ValueError("Invalid embedding model")
 
+        def get_result(task_id: str) -> ClassificationMetrics | RegressionMetrics:
+            client = OrcaClient._resolve_client()
+            if isinstance(self, PretrainedEmbeddingModel):
+                res = client.GET(
+                    "/pretrained_embedding_model/{model_name}/evaluation/{task_id}",
+                    params={"model_name": self.name, "task_id": task_id},
+                )["result"]
+            elif isinstance(self, FinetunedEmbeddingModel):
+                res = client.GET(
+                    "/finetuned_embedding_model/{name_or_id}/evaluation/{task_id}",
+                    params={"name_or_id": self.id, "task_id": task_id},
+                )["result"]
+            else:
+                raise ValueError("Invalid embedding model")
+            assert res is not None
+            return (
+                RegressionMetrics(
+                    coverage=res.get("coverage"),
+                    mse=res.get("mse"),
+                    rmse=res.get("rmse"),
+                    mae=res.get("mae"),
+                    r2=res.get("r2"),
+                    explained_variance=res.get("explained_variance"),
+                    loss=res.get("loss"),
+                    anomaly_score_mean=res.get("anomaly_score_mean"),
+                    anomaly_score_median=res.get("anomaly_score_median"),
+                    anomaly_score_variance=res.get("anomaly_score_variance"),
+                )
+                if "mse" in res
+                else ClassificationMetrics(
+                    coverage=res.get("coverage"),
+                    f1_score=res.get("f1_score"),
+                    accuracy=res.get("accuracy"),
+                    loss=res.get("loss"),
+                    anomaly_score_mean=res.get("anomaly_score_mean"),
+                    anomaly_score_median=res.get("anomaly_score_median"),
+                    anomaly_score_variance=res.get("anomaly_score_variance"),
+                    roc_auc=res.get("roc_auc"),
+                    pr_auc=res.get("pr_auc"),
+                    pr_curve=res.get("pr_curve"),
+                    roc_curve=res.get("roc_curve"),
+                )
+            )
+
+        job = Job(response["task_id"], lambda: get_result(response["task_id"]))
+        return job if background else job.result()
+
+
+class _ModelDescriptor:
+    """
+    Descriptor for lazily loading embedding models with IDE autocomplete support.
+
+    This class implements the descriptor protocol to provide lazy loading of embedding models
+    while maintaining IDE autocomplete functionality. It delays the actual loading of models
+    until they are accessed, which improves startup performance.
 
-class PretrainedEmbeddingModel(_EmbeddingModel, metaclass=_PretrainedEmbeddingModelMeta):
+    The descriptor pattern works by defining how attribute access is handled. When a class
+    attribute using this descriptor is accessed, the __get__ method is called, which then
+    retrieves or initializes the actual model on first access.
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize a model descriptor.
+
+        Args:
+            name: The name of the embedding model in PretrainedEmbeddingModelName
+        """
+        self.name = name
+        self.model = None  # Model is loaded lazily on first access
+
+    def __get__(self, instance, owner_class):
+        """
+        Descriptor protocol method called when the attribute is accessed.
+
+        This method implements lazy loading - the actual model is only initialized
+        the first time it's accessed. Subsequent accesses will use the cached model.
+
+        Args:
+            instance: The instance the attribute was accessed from, or None if accessed from the class
+            owner_class: The class that owns the descriptor
+
+        Returns:
+            The initialized embedding model
+
+        Raises:
+            AttributeError: If no model with the given name exists
+        """
+        # When accessed from an instance, redirect to class access
+        if instance is not None:
+            return self.__get__(None, owner_class)
+
+        # Load the model on first access
+        if self.model is None:
+            try:
+                self.model = PretrainedEmbeddingModel._get(cast(PretrainedEmbeddingModelName, self.name))
+            except (KeyError, AttributeError):
+                raise AttributeError(f"No embedding model named {self.name}")
+
+        return self.model
+
+
+class PretrainedEmbeddingModel(EmbeddingModelBase):
     """
     A pretrained embedding model
 
@@ -100,28 +334,60 @@ class PretrainedEmbeddingModel(_EmbeddingModel, metaclass=_PretrainedEmbeddingMo
     - **`CDE_SMALL`**: Context-aware CDE small model from Hugging Face ([jxm/cde-small-v1](https://huggingface.co/jxm/cde-small-v1))
     - **`CLIP_BASE`**: Multi-modal CLIP model from Hugging Face ([sentence-transformers/clip-ViT-L-14](https://huggingface.co/sentence-transformers/clip-ViT-L-14))
     - **`GTE_BASE`**: Alibaba's GTE model from Hugging Face ([Alibaba-NLP/gte-base-en-v1.5](https://huggingface.co/Alibaba-NLP/gte-base-en-v1.5))
+    - **`DISTILBERT`**: DistilBERT embedding model from Hugging Face ([distilbert-base-uncased](https://huggingface.co/distilbert-base-uncased))
+    - **`GTE_SMALL`**: GTE-Small embedding model from Hugging Face ([Supabase/gte-small](https://huggingface.co/Supabase/gte-small))
+    - **`E5_LARGE`**: E5-Large instruction-tuned embedding model from Hugging Face ([intfloat/multilingual-e5-large-instruct](https://huggingface.co/intfloat/multilingual-e5-large-instruct))
+    - **`GIST_LARGE`**: GIST-Large embedding model from Hugging Face ([avsolatorio/GIST-large-Embedding-v0](https://huggingface.co/avsolatorio/GIST-large-Embedding-v0))
+    - **`MXBAI_LARGE`**: Mixbreas's Large embedding model from Hugging Face ([mixedbread-ai/mxbai-embed-large-v1](https://huggingface.co/mixedbread-ai/mxbai-embed-large-v1))
+    - **`QWEN2_1_5B`**: Alibaba's Qwen2-1.5B instruction-tuned embedding model from Hugging Face ([Alibaba-NLP/gte-Qwen2-1.5B-instruct](https://huggingface.co/Alibaba-NLP/gte-Qwen2-1.5B-instruct))
+    - **`BGE_BASE`**: BAAI's BGE-Base instruction-tuned embedding model from Hugging Face ([BAAI/bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5))
+
+    **Instruction Support:**
+
+    Some models support instruction-following for better task-specific embeddings. You can check if a model supports instructions
+    using the `supports_instructions` attribute.
 
     Examples:
         >>> PretrainedEmbeddingModel.CDE_SMALL
         PretrainedEmbeddingModel({name: CDE_SMALL, embedding_dim: 768, max_seq_length: 512})
 
+        >>> # Using instruction with an instruction-supporting model
+        >>> model = PretrainedEmbeddingModel.E5_LARGE
+        >>> embeddings = model.embed("Hello world", prompt="Represent this sentence for retrieval:")
+
     Attributes:
         name: Name of the pretrained embedding model
         embedding_dim: Dimension of the embeddings that are generated by the model
         max_seq_length: Maximum input length (in tokens not characters) that this model can process. Inputs that are longer will be truncated during the embedding process
         uses_context: Whether the pretrained embedding model uses context
+        supports_instructions: Whether this model supports instruction-following
     """
 
-    _model_name: PretrainedEmbeddingModelName
+    # Define descriptors for model access with IDE autocomplete
+    CDE_SMALL = _ModelDescriptor("CDE_SMALL")
+    CLIP_BASE = _ModelDescriptor("CLIP_BASE")
+    GTE_BASE = _ModelDescriptor("GTE_BASE")
+    DISTILBERT = _ModelDescriptor("DISTILBERT")
+    GTE_SMALL = _ModelDescriptor("GTE_SMALL")
+    E5_LARGE = _ModelDescriptor("E5_LARGE")
+    GIST_LARGE = _ModelDescriptor("GIST_LARGE")
+    MXBAI_LARGE = _ModelDescriptor("MXBAI_LARGE")
+    QWEN2_1_5B = _ModelDescriptor("QWEN2_1_5B")
+    BGE_BASE = _ModelDescriptor("BGE_BASE")
+
+    name: PretrainedEmbeddingModelName
 
     def __init__(self, metadata: PretrainedEmbeddingModelMetadata):
         # for internal use only, do not document
-        self._model_name = metadata.name
+        self.name = metadata["name"]
         super().__init__(
-            name=metadata.name.value,
-            embedding_dim=metadata.embedding_dim,
-            max_seq_length=metadata.max_seq_length,
-            uses_context=metadata.uses_context,
+            name=metadata["name"],
+            embedding_dim=metadata["embedding_dim"],
+            max_seq_length=metadata["max_seq_length"],
+            uses_context=metadata["uses_context"],
+            supports_instructions=(
+                bool(metadata["supports_instructions"]) if "supports_instructions" in metadata else False
+            ),
         )
 
     def __eq__(self, other) -> bool:
@@ -138,16 +404,46 @@ class PretrainedEmbeddingModel(_EmbeddingModel, metaclass=_PretrainedEmbeddingMo
         Returns:
             A list of all pretrained embedding models available in the OrcaCloud
         """
-        return [cls(metadata) for metadata in list_pretrained_embedding_models()]
+        client = OrcaClient._resolve_client()
+        return [cls(metadata) for metadata in client.GET("/pretrained_embedding_model")]
 
     _instances: dict[str, PretrainedEmbeddingModel] = {}
 
     @classmethod
-    def _get(cls, name: PretrainedEmbeddingModelName | str) -> PretrainedEmbeddingModel:
+    def _get(cls, name: PretrainedEmbeddingModelName) -> PretrainedEmbeddingModel:
         # for internal use only, do not document - we want people to use dot notation to get the model
-        if str(name) not in cls._instances:
-            cls._instances[str(name)] = cls(get_pretrained_embedding_model(cast(PretrainedEmbeddingModelName, name)))
-        return cls._instances[str(name)]
+        cache_key = str(name)
+        if cache_key not in cls._instances:
+            client = OrcaClient._resolve_client()
+            metadata = client.GET(
+                "/pretrained_embedding_model/{model_name}",
+                params={"model_name": name},
+            )
+            cls._instances[cache_key] = cls(metadata)
+        return cls._instances[cache_key]
+
+    @classmethod
+    def open(cls, name: PretrainedEmbeddingModelName) -> PretrainedEmbeddingModel:
+        """
+        Open an embedding model by name.
+
+        This is an alternative method to access models for environments
+        where IDE autocomplete for model names is not available.
+
+        Params:
+            name: Name of the model to open (e.g., "GTE_BASE", "CLIP_BASE")
+
+        Returns:
+            The embedding model instance
+
+        Examples:
+            >>> model = PretrainedEmbeddingModel.open("GTE_BASE")
+        """
+        try:
+            # Always use the _get method which handles caching properly
+            return cls._get(name)
+        except (KeyError, AttributeError):
+            raise ValueError(f"Unknown model name: {name}")
 
     @classmethod
     def exists(cls, name: str) -> bool:
@@ -160,8 +456,25 @@ class PretrainedEmbeddingModel(_EmbeddingModel, metaclass=_PretrainedEmbeddingMo
         Returns:
             True if the pretrained embedding model exists, False otherwise
         """
-        return name in PretrainedEmbeddingModelName
+        return name in get_args(PretrainedEmbeddingModelName)
+
+    @overload
+    def finetune(
+        self,
+        name: str,
+        train_datasource: Datasource | LabeledMemoryset,
+        *,
+        eval_datasource: Datasource | None = None,
+        label_column: str = "label",
+        value_column: str = "value",
+        training_method: EmbeddingFinetuningMethod = "classification",
+        training_args: dict | None = None,
+        if_exists: CreateMode = "error",
+        background: Literal[True],
+    ) -> Job[FinetunedEmbeddingModel]:
+        pass
 
+    @overload
     def finetune(
         self,
         name: str,
@@ -170,10 +483,26 @@ class PretrainedEmbeddingModel(_EmbeddingModel, metaclass=_PretrainedEmbeddingMo
         eval_datasource: Datasource | None = None,
         label_column: str = "label",
         value_column: str = "value",
-        training_method: EmbeddingFinetuningMethod | str = EmbeddingFinetuningMethod.CLASSIFICATION,
+        training_method: EmbeddingFinetuningMethod = "classification",
         training_args: dict | None = None,
         if_exists: CreateMode = "error",
+        background: Literal[False] = False,
     ) -> FinetunedEmbeddingModel:
+        pass
+
+    def finetune(
+        self,
+        name: str,
+        train_datasource: Datasource | LabeledMemoryset,
+        *,
+        eval_datasource: Datasource | None = None,
+        label_column: str = "label",
+        value_column: str = "value",
+        training_method: EmbeddingFinetuningMethod = "classification",
+        training_args: dict | None = None,
+        if_exists: CreateMode = "error",
+        background: bool = False,
+    ) -> FinetunedEmbeddingModel | Job[FinetunedEmbeddingModel]:
         """
         Finetune an embedding model
 
@@ -184,10 +513,11 @@ class PretrainedEmbeddingModel(_EmbeddingModel, metaclass=_PretrainedEmbeddingMo
             label_column: Column name of the label
             value_column: Column name of the value
             training_method: Training method to use
-            training_args: Optional override for Hugging Face [`TrainingArguments`](transformers.TrainingArguments).
+            training_args: Optional override for Hugging Face [`TrainingArguments`][transformers.TrainingArguments].
                 If not provided, reasonable training arguments will be used for the specified training method
             if_exists: What to do if a finetuned embedding model with the same name already exists, defaults to
                 `"error"`. Other option is `"open"` to open the existing finetuned embedding model.
+            background: Whether to run the operation in the background and return a job handle
 
         Returns:
             The finetuned embedding model
@@ -208,34 +538,41 @@ class PretrainedEmbeddingModel(_EmbeddingModel, metaclass=_PretrainedEmbeddingMo
         elif exists and if_exists == "open":
             existing = FinetunedEmbeddingModel.open(name)
 
-            if existing.base_model_name != self._model_name:
+            if existing.base_model_name != self.name:
                 raise ValueError(f"Finetuned embedding model '{name}' already exists, but with different base model")
 
             return existing
 
         from .memoryset import LabeledMemoryset
 
-        train_datasource_id = train_datasource.id if isinstance(train_datasource, Datasource) else None
-        train_memoryset_id = train_datasource.id if isinstance(train_datasource, LabeledMemoryset) else None
-        assert train_datasource_id is not None or train_memoryset_id is not None
-        res = create_finetuned_embedding_model(
-            body=FinetuneEmbeddingModelRequest(
-                name=name,
-                base_model=self._model_name,
-                train_memoryset_id=train_memoryset_id,
-                train_datasource_id=train_datasource_id,
-                eval_datasource_id=eval_datasource.id if eval_datasource is not None else None,
-                label_column=label_column,
-                value_column=value_column,
-                training_method=EmbeddingFinetuningMethod(training_method),
-                training_args=(FinetuneEmbeddingModelRequestTrainingArgs.from_dict(training_args or {})),
-            ),
+        payload: FinetuneEmbeddingModelRequest = {
+            "name": name,
+            "base_model": self.name,
+            "label_column": label_column,
+            "value_column": value_column,
+            "training_method": training_method,
+            "training_args": training_args or {},
+        }
+        if isinstance(train_datasource, Datasource):
+            payload["train_datasource_name_or_id"] = train_datasource.id
+        elif isinstance(train_datasource, LabeledMemoryset):
+            payload["train_memoryset_name_or_id"] = train_datasource.id
+        if eval_datasource is not None:
+            payload["eval_datasource_name_or_id"] = eval_datasource.id
+
+        client = OrcaClient._resolve_client()
+        res = client.POST(
+            "/finetuned_embedding_model",
+            json=payload,
         )
-        wait_for_task(res.finetuning_task_id, description="Finetuning embedding model")
-        return FinetunedEmbeddingModel.open(res.id)
+        job = Job(
+            res["finetuning_task_id"],
+            lambda: FinetunedEmbeddingModel.open(res["id"]),
+        )
+        return job if background else job.result()
 
 
-class FinetunedEmbeddingModel(_EmbeddingModel):
+class FinetunedEmbeddingModel(EmbeddingModelBase):
     """
     A finetuned embedding model in the OrcaCloud
 
@@ -250,22 +587,27 @@ class FinetunedEmbeddingModel(_EmbeddingModel):
     """
 
     id: str
+    name: str
     created_at: datetime
     updated_at: datetime
-    _status: TaskStatus
+    base_model_name: PretrainedEmbeddingModelName
+    _status: Status
 
     def __init__(self, metadata: FinetunedEmbeddingModelMetadata):
         # for internal use only, do not document
-        self.id = metadata.id
-        self.created_at = metadata.created_at
-        self.updated_at = metadata.updated_at
-        self.base_model_name = metadata.base_model
-        self._status = metadata.finetuning_status
+        self.id = metadata["id"]
+        self.name = metadata["name"]
+        self.created_at = datetime.fromisoformat(metadata["created_at"])
+        self.updated_at = datetime.fromisoformat(metadata["updated_at"])
+        self.base_model_name = metadata["base_model"]
+        self._status = Status(metadata["finetuning_status"])
+
         super().__init__(
-            name=metadata.name,
-            embedding_dim=metadata.embedding_dim,
-            max_seq_length=metadata.max_seq_length,
-            uses_context=metadata.uses_context,
+            name=metadata["name"],
+            embedding_dim=metadata["embedding_dim"],
+            max_seq_length=metadata["max_seq_length"],
+            uses_context=metadata["uses_context"],
+            supports_instructions=self.base_model.supports_instructions,
         )
 
     def __eq__(self, other) -> bool:
@@ -277,7 +619,7 @@ class FinetunedEmbeddingModel(_EmbeddingModel):
             f"    name: {self.name},\n"
             f"    embedding_dim: {self.embedding_dim},\n"
             f"    max_seq_length: {self.max_seq_length},\n"
-            f"    base_model: PretrainedEmbeddingModel.{self.base_model_name.value}\n"
+            f"    base_model: PretrainedEmbeddingModel.{self.base_model_name}\n"
             "})"
         )
 
@@ -294,7 +636,8 @@ class FinetunedEmbeddingModel(_EmbeddingModel):
         Returns:
             A list of all finetuned embedding model handles in the OrcaCloud
         """
-        return [cls(metadata) for metadata in list_finetuned_embedding_models()]
+        client = OrcaClient._resolve_client()
+        return [cls(metadata) for metadata in client.GET("/finetuned_embedding_model")]
 
     @classmethod
     def open(cls, name: str) -> FinetunedEmbeddingModel:
@@ -310,7 +653,12 @@ class FinetunedEmbeddingModel(_EmbeddingModel):
         Raises:
             LookupError: If the finetuned embedding model does not exist
         """
-        return cls(get_finetuned_embedding_model(name))
+        client = OrcaClient._resolve_client()
+        metadata = client.GET(
+            "/finetuned_embedding_model/{name_or_id}",
+            params={"name_or_id": name},
+        )
+        return cls(metadata)
 
     @classmethod
     def exists(cls, name_or_id: str) -> bool:
@@ -341,7 +689,11 @@ class FinetunedEmbeddingModel(_EmbeddingModel):
             LookupError: If the finetuned embedding model does not exist and `if_not_exists` is `"error"`
         """
         try:
-            delete_finetuned_embedding_model(name_or_id)
-        except LookupError:
+            client = OrcaClient._resolve_client()
+            client.DELETE(
+                "/finetuned_embedding_model/{name_or_id}",
+                params={"name_or_id": name_or_id},
+            )
+        except (LookupError, RuntimeError):
             if if_not_exists == "error":
                 raise