Skip to main content

​
MlModelsClient Objects

class MlModelsClient()
Client for interacting with Encord’s ML models functionality. This client provides methods to create, manage, and use machine learning models within Encord, including classification, object detection, and instance segmentation models.

​
__init__

def __init__(api_client: ApiClient) -> None
Initialize the ML Models client. Arguments:
  • api_client - An authenticated ApiClient instance

​
create_model

def create_model(*, features: List[str], model: ModelArchitecture, title: str,
                 description: Optional[str]) -> ModelWithIterations
Create a new model in Encord. Arguments:
  • features - List of feature names that define the model’s output layer structure (e.g. [“car”, “person”]). These features are directly mapped to neurons in the model’s final layer and remain fixed across all training iterations. The number and names of features cannot be changed without rebuilding the model’s architecture, since they determine the size and structure of the output layer. This fixed structure enables several key capabilities:
    1. Transfer Learning: The model can be retrained on new datasets while preserving its learned feature detectors, since the output layer structure stays consistent
    2. Cross-Project Usage: The same model can be used across different projects by mapping its fixed features to different ontology features in each project
    3. Flexible Inference: A model trained to detect “vehicle” can be mapped to detect “car”, “truck” etc. in different projects based on their specific ontologies
  • model - The architecture type of the model to create
  • title - Title for the model
  • description - Optional description for the model
Returns:
  • ModelWithIterations - The created model and its iterations

​
get_model

def get_model(*, model_uuid: UUID) -> ModelWithIterations
Get information about a specific model. Arguments:
  • model_uuid - UUID of the model to get information for
Returns:
  • ModelWithIterations - Information about the requested model

​
list_models

def list_models(*, order_by: ModelsListOrderBy, order_asc: bool,
                query: Optional[str]) -> Iterable[ModelWithIterations]
List available models with filtering. Arguments:
  • order_by - Field to order results by
  • order_asc - True for ascending order, False for descending
  • query - Optional search query to filter results
Returns:
  • Iterable[ModelWithIterations] - Iterator of models matching the specified criteria

​
delete_model

def delete_model(*, model_uuid: UUID) -> None
Delete a model. Arguments:
  • model_uuid - UUID of the model to delete

​
update_model

def update_model(*, model_uuid: UUID, title: Optional[str],
                 description: Optional[str]) -> ModelWithIterations
Update a model’s metadata. Arguments:
  • model_uuid - UUID of the model to update
  • title - New title for the model
  • description - New description for the model
Returns:
  • ModelWithIterations - Updated model information

​
create_training_job

def create_training_job(
        *, model_uuid: UUID, batch_size: int, epochs: int,
        features_mapping: Dict[UUID, Dict[str, List[str]]],
        labels_uuids: List[UUID], pretrained_training_uuid: Optional[UUID],
        pretrained_weights_type: Optional[ModelPretrainedWeightsType]) -> UUID
Create a new training job for a model. Arguments:
  • model_uuid - UUID of the model to train
  • batch_size - Training batch size
  • epochs - Number of training epochs
  • features_mapping - Maps project UUIDs to mappings between ontology features and model features. This complex structure allows training examples for model features to be sourced from multiple projects with different ontologies. For example: 
    {
    project_uuid_0: {
        "ontology_0_feature_0": ["model_feature_0"],
        "ontology_0_feature_1": ["model_feature_1"]
    },
    project_uuid_1: {
        "ontology_1_feature_0": ["model_feature_0", "model_feature_1"]
    }
}
    In this case:
    • Training examples for model_feature_0 will come from:
    • project_uuid_0’s ontology_0_feature_0
    • project_uuid_1’s ontology_1_feature_0
    • Training examples for model_feature_1 will come from:
    • project_uuid_0’s ontology_0_feature_1
    • project_uuid_1’s ontology_1_feature_0
    The project-level mapping is essential because:
    1. Different projects can use different ontologies
    2. The same semantic concept (e.g. “car”) might have different feature IDs across ontologies
    3. Allows flexibly combining training data from multiple sources while maintaining correct mappings between ontology features and model features
  • labels_uuids - List of label UUIDs to use for training
  • pretrained_training_uuid - Optional UUID of previous training to use for transfer learning
  • pretrained_weights_type - Optional type of pretrained weights to use
Returns:
  • UUID - The unique identifier of the created training job

​
get_training_status

def get_training_status(
        *,
        model_uuid: UUID,
        training_uuid: UUID,
        timeout_seconds: int = 7 * 24 * 60 * 60) -> ModelIteration
Get the status of a training job. Arguments:
  • model_uuid - UUID of the model being trained
  • training_uuid - UUID of the training job
  • timeout_seconds - Maximum time to wait for training completion. Defaults to 7 days.
Returns:
  • ModelIteration - Information about the training iteration
Raises:
  • EncordException - If training encountered an error
  • ValueError - If status response is invalid
  • RequestException - If there are network connectivity issues

​
get_training_data

def get_training_data(
        *, model_uuid: UUID,
        training_uuid: UUID) -> Iterable[ModelIterationTrainingData]
Get information about data used in a training iteration. Arguments:
  • model_uuid - UUID of the model
  • training_uuid - UUID of the training iteration
Returns:
  • Iterable[ModelIterationTrainingData] - Iterator of training data items
def get_weights_download_link(*, model_uuid: UUID, training_uuid: UUID) -> str
Get a download link for trained model weights. Arguments:
  • model_uuid - UUID of the model
  • training_uuid - UUID of the training iteration
Returns:
  • str - URL for downloading model weights

​
delete_training_iteration

def delete_training_iteration(*, model_uuid: UUID,
                              training_uuid: UUID) -> None
Delete a training iteration. Arguments:
  • model_uuid - UUID of the model
  • training_uuid - UUID of the training iteration to delete

​
create_model_attachment

def create_model_attachment(
        *, project_uuid: UUID, features_mapping: Dict[str, str],
        iteration_policy: ModelIterationPolicy, model_uuid: UUID,
        training_uuids: Optional[List[UUID]]) -> ProjectModelWithIterations
Attach a model to a project by mapping the model’s features to corresponding ontology features in the project. This allows a single trained model to be reused across different projects, even if they use different ontologies to represent the same concepts. Arguments:
  • project_uuid - UUID of the project to attach the model to
  • features_mapping - Maps model features to project ontology features. For example: 
    {
    "model_feature_0": "ontology_feature_hash_1",
    "model_feature_1": "ontology_feature_hash_2"
}
    This mapping connects each model feature (e.g. “car” detection) to the corresponding feature in the project’s ontology. Since different projects may use different ontologies with different feature hashes for the same concept, this mapping allows the same trained model to be reused across projects by correctly mapping its features to each project’s specific ontology structure.
  • iteration_policy - Policy for model iteration selection
  • model_uuid - UUID of the model to attach
  • training_uuids - Optional list of specific training iterations to use. Only required when iteration_policy is set to MANUAL_SELECTION.
Returns:
  • ProjectModelWithIterations - Information about the created model attachment

​
list_model_attachments

def list_model_attachments(
        *, project_uuid: UUID) -> Iterable[ProjectModelWithIterations]
List models attached to a project. Arguments:
  • project_uuid - UUID of the project
Returns:
  • Iterable[ProjectModelWithIterations] - Iterator of attached model information

​
update_model_attachment

def update_model_attachment(
        *, project_uuid: UUID, project_model_uuid: UUID,
        features_mapping: Dict[str,
                               str], iteration_policy: ModelIterationPolicy,
        training_uuids: Optional[List[UUID]]) -> ProjectModelWithIterations
Update how a model is attached to a project by modifying its feature mappings and iteration settings. This allows you to change how the model’s features map to the project’s ontology features, or update which model iterations are used for inference. Arguments:
  • project_uuid - UUID of the project
  • project_model_uuid - UUID identifying this specific model attachment to the project
  • features_mapping - Maps model features to project ontology features. For example: 
    {
    "model_feature_0": "new_ontology_feature_hash_1",
    "model_feature_1": "new_ontology_feature_hash_2"
}
    This lets you remap model features to different ontology features - useful when the project’s ontology has changed or if you want the model to detect different classes than it was originally mapped to.
  • iteration_policy - Updated policy for selecting which trained iteration of the model to use. Can be changed between automatically using latest iteration or manually specified ones.
  • training_uuids - Optional list of specific training iterations to use. Only required when iteration_policy is set to MANUAL_SELECTION. Allows cherry-picking which trained versions of the model to use for inference.
Returns:
  • ProjectModelWithIterations - Information about the updated model attachment

​
delete_model_attachment

def delete_model_attachment(*, project_uuid: UUID,
                            project_model_uuid: UUID) -> None
Remove a model attachment from a project. Arguments:
  • project_uuid - UUID of the project
  • project_model_uuid - UUID of the model attachment to project

​
predict_classification

def predict_classification(
    *, project_uuid: UUID, project_model_uuid: UUID, training_uuid: UUID,
    data_uuid: Optional[UUID], data_path: Optional[Path],
    frame_range_from: Optional[int], frame_range_to: Optional[int],
    conf_thresh: float
) -> Dict[int, Optional[PredictionClassificationResultItem]]
Run classification prediction on either data_uuid or data_path. Arguments:
  • project_uuid - UUID of the project
  • project_model_uuid - UUID of the model attachment to project
  • training_uuid - UUID of the training iteration to use
  • data_uuid - Optional UUID of data to predict on
  • data_path - Optional path to local data file
  • frame_range_from - Optional starting frame for prediction (first frame if not set)
  • frame_range_to - Optional ending frame for prediction (last frame if not set)
  • conf_thresh - Confidence threshold for predictions (0.0 - 1.0)
Returns: Dict[int, Optional[PredictionClassificationResultItem]]: Dictionary mapping frame numbers to classification results

​
predict_instance_segmentation

def predict_instance_segmentation(
    *, project_uuid: UUID, project_model_uuid: UUID, training_uuid: UUID,
    data_uuid: Optional[UUID], data_path: Optional[Path],
    frame_range_from: Optional[int], frame_range_to: Optional[int],
    allocation_enabled: bool, conf_thresh: float, iou_thresh: float,
    rdp_thresh: Optional[float]
) -> Dict[int, List[PredictionInstanceSegmentationResultItem]]
Run instance segmentation prediction on either data_uuid or data_path. Arguments:
  • project_uuid - UUID of the project
  • project_model_uuid - UUID of the model attachment to project
  • training_uuid - UUID of the training iteration to use
  • data_uuid - Optional UUID of data to predict on
  • data_path - Optional path to local data file
  • frame_range_from - Optional starting frame for prediction (first frame if not set)
  • frame_range_to - Optional ending frame for prediction (last frame if not set)
  • allocation_enabled - Whether to enable object id tracking
  • conf_thresh - Confidence threshold for predictions (0.0 - 1.0)
  • iou_thresh - Intersection over Union threshold (0.0 - 1.0)
  • rdp_thresh - Optional Ramer-Douglas-Peucker algorithm threshold for polygon simplification
Returns: Dict[int, List[PredictionInstanceSegmentationResultItem]]: Dictionary mapping frame numbers to lists of instance segmentation results

​
predict_object_detection

def predict_object_detection(
        *, project_uuid: UUID, project_model_uuid: UUID, training_uuid: UUID,
        data_uuid: Optional[UUID], data_path: Optional[Path],
        frame_range_from: Optional[int], frame_range_to: Optional[int],
        allocation_enabled: bool, conf_thresh: float, iou_thresh: float
) -> Dict[int, List[PredictionObjectDetectionResultItem]]
Run object detection prediction on either data_uuid or data_path. Arguments:
  • project_uuid - UUID of the project
  • project_model_uuid - UUID of the model attachment to project
  • training_uuid - UUID of the training iteration to use
  • data_uuid - Optional UUID of data to predict on
  • data_path - Optional path to local data file
  • frame_range_from - Optional starting frame for prediction (first frame if not set)
  • frame_range_to - Optional ending frame for prediction (last frame if not set)
  • allocation_enabled - Whether to enable object id tracking
  • conf_thresh - Confidence threshold for predictions (0.0 - 1.0)
  • iou_thresh - Intersection over Union threshold (0.0 - 1.0)
Returns: Dict[int, List[PredictionObjectDetectionResultItem]]: Dictionary mapping frame numbers to lists of object detection results