> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ml models client

## MlModelsClient Objects

```python theme={"dark"}
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\_\_

```python theme={"dark"}
def __init__(api_client: ApiClient) -> None
```

Initialize the ML Models client.

**Arguments**:

* `api_client` - An authenticated ApiClient instance

#### create\_model

```python theme={"dark"}
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

```python theme={"dark"}
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

```python theme={"dark"}
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

```python theme={"dark"}
def delete_model(*, model_uuid: UUID) -> None
```

Delete a model.

**Arguments**:

* `model_uuid` - UUID of the model to delete

#### update\_model

```python theme={"dark"}
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

```python theme={"dark"}
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:

  ```json theme={"dark"}
  {
      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

```python theme={"dark"}
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

```python theme={"dark"}
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

#### get\_weights\_download\_link

```python theme={"dark"}
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

```python theme={"dark"}
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

```python theme={"dark"}
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:
  ```json theme={"dark"}
  {
      "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

```python theme={"dark"}
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

```python theme={"dark"}
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:
  ```json theme={"dark"}
  {
      "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

```python theme={"dark"}
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

```python theme={"dark"}
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

```python theme={"dark"}
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

```python theme={"dark"}
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