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

# Adding a Custom Model

> Prepare and add a custom model or custom pipeline to the Simplismart platform.

For **custom models or custom pipelines**, you must **prepare the model configuration before adding the model to the platform**. This includes defining the model logic, dependencies, and runtime environment. The platform expects all required files to be packaged together and provided as a single artifact (a ZIP file).

This page describes how to implement the model interface, define runtime configuration, package your model, and add it through the Simplismart platform.

## Model interface (`model.py`)

Your custom model must implement a standard interface so the platform can load and run it correctly.

**Method requirements:**

* **`load()`**: Handles model initialization and weight loading
* **`preprocess()`**: Optional input preprocessing
* **`predict()`**: Core inference logic
* **`postprocess()`**: Optional output formatting

Example:

```python theme={null}
class Model:
    def __init__(self):
        self.model = None

    def load(self):
        # Initialize or load model weights
        self.model = "Model Initialization"

    def preprocess(self, request):
        """
        Preprocess the incoming request.
        Input can be a Pydantic BaseModel, dict, or string.
        """
        return request

    def predict(self, request):
        # Run inference
        output = self.model.predict()
        return output

    def postprocess(self, request):
        # Postprocess the model output
        return request
```

## Runtime configuration (`config.yaml`)

The `config.yaml` file defines the execution environment for the custom model.

| Section                 | Purpose                                     |
| ----------------------- | ------------------------------------------- |
| `python_version`        | Python runtime version                      |
| `environment_variables` | Custom environment variables (if any)       |
| `requirements`          | Python dependencies                         |
| `system_packages`       | OS-level packages                           |
| `custom_setup_script`   | Optional setup script executed during build |

Example:

```yaml theme={null}
python_version: "3.10"

environment_variables: {}

requirements:
  - accelerate==0.20.3
  - bitsandbytes==0.39.1
  - peft==0.3.0
  - protobuf==4.23.3
  - sentencepiece==0.1.99
  - torch==2.0.1
  - transformers==4.30.2

system_packages:
  - wget
  - curl

custom_setup_script: "script.sh"
```

## Packaging the custom model

Before adding the model to the platform, package all required files into a single ZIP file.

<Steps>
  <Step title="Create a single directory">
    Place the following in one folder:

    * `model.py`
    * `config.yaml`
    * Any additional scripts or assets (e.g. `script.sh`)
  </Step>

  <Step title="Compress the directory">
    Create a **ZIP file** containing the directory contents.
  </Step>

  <Step title="Upload the ZIP">
    Upload the ZIP to one of the supported model sources:

    * **AWS S3**
    * **GCP GCS**
    * **Public URL**
  </Step>
</Steps>

<Note>
  Upload your trained model to **AWS S3** or **GCP GCS**, share the [access credentials](model-suite/integrations/secrets), and the platform will compile and prepare it for deployment. Models built to your specifications are integrated into the platform.
</Note>

## Adding the custom model to the platform

In the UI, point the platform to your ZIP, choose **Custom Pipeline** as the model type, and add the model. The platform then unpacks the archive and loads your model.

On the Simplismart platform, provide your ZIP file, choose **Custom Pipeline** as the model type, and add the model. The platform then unpacks the archive and loads your model.

<Steps>
  <Step title="Open Add Model">
    Go to [**My Models**](https://app.simplismart.ai/my-models) and click **Add a Model** (top-right).

    <img src="https://mintcdn.com/simplismart-3f10d72e/5wZwN9uOAdVmfPx5/images/model-suite/optimize/adding-a-custom-model/1-my-models.png?fit=max&auto=format&n=5wZwN9uOAdVmfPx5&q=85&s=103d7947c96120d4fe0c1e93384ce109" alt="My models" width="3024" height="1650" data-path="images/model-suite/optimize/adding-a-custom-model/1-my-models.png" />
  </Step>

  <Step title="Enter model details">
    * **Model name**: A name for your model.
    * **Model source**: Hugging Face, AWS S3, GCP GCS, or Public URL (use the source where you uploaded the ZIP).
    * **Model path**: Path to the ZIP file (e.g. S3 URI, GCS URI, or public URL).
    * If using AWS or GCP, select the linked [**Cloud credentials**](/model-suite/integrations/secrets).

          <img src="https://mintcdn.com/simplismart-3f10d72e/hjIl_h3RVuDkUjjA/images/model-suite/optimize/adding-a-custom-model/2-add-model-details.png?fit=max&auto=format&n=hjIl_h3RVuDkUjjA&q=85&s=0a375c7da7bf3457f6293904f328bbbe" alt="Add model details form" width="4320" height="2256" data-path="images/model-suite/optimize/adding-a-custom-model/2-add-model-details.png" />
  </Step>

  <Step title="Set model class">
    Under **Model Class**, choose **Custom Pipeline** (or **Custom Model**).
  </Step>

  <Step title="Select infrastructure">
    Choose **Simplismart Cloud** or **Bring Your Own Cloud**. Select **Accelerator type** and machine type based on your model size and compute requirements.
  </Step>

  <Step title="Pipeline configuration (Optional)">
    Use the **Pipeline Config Editor** or **Extra Params** to tune deployment. For custom models, set `type` to `"custom"`. See the table and example below.
  </Step>

  <Step title="Add the model">
    Click **Add Model** to start compilation. The platform unpacks the archive, sets up the environment, and loads the model.
  </Step>
</Steps>

### Extra parameters (optional)

Based on your model pipeline, you can add extra parameters in JSON format under **Extra Params**.

| Field                | Type   | Default    | Description                                                                   |
| -------------------- | ------ | ---------- | ----------------------------------------------------------------------------- |
| `workers_per_device` | Int    | `1`        | Parallel workers per device (higher can improve inference speed).             |
| `device`             | string | `cpu`      | `"cpu"` or `"cuda"`.                                                          |
| `endpoint`           | string | `/predict` | URL path for inference requests.                                              |
| `type`               | string | (required) | Use `"custom"` for custom models; other values: `"whisper"`, `"llm"`, `"sd"`. |

<Tip>
  For custom models, set `type` to `"custom"` in the pipeline configuration.
</Tip>

Example:

```json theme={null}
{
  "type": "custom",
  "extra_params": {
    "workers_per_device": 2,
    "device": "cuda",
    "endpoint": "/predict"
  }
}
```

***

## Next steps

Once the model is compiled, see [Deploy a custom model](/model-suite/deployments/deploy-a-custom-model) to deploy your custom model.