Model Management

Models on OpenGradient are managed through model repositories — structured containers that hold every version of a model along with its metadata, files, and documentation.

Repository Structure

A model repository represents a single model project. It contains:

• Name — A unique identifier (e.g., opengradient-1-hour-volatility-ethusdt1)
• Description — A Markdown-formatted explanation of the model's purpose, architecture, and usage
• Task — The problem domain (e.g., DeFi Forecasting, Risk Model, LLM, Image Generation)
• License — The license governing usage and redistribution
• Tags — Freeform labels for discovery (e.g., ethereum, time-series, onnx)
• Visibility — Public (visible to everyone) or Private (visible only to you)

Within each repository, you create releases (versions) that hold the actual model files.

Releases & Versioning

Each release is an independently usable snapshot of the model. Releases follow a major.minor versioning scheme:

• v1.00 — Initial release
• v1.01 — Minor update (e.g., retrained with more data, hyperparameter tweak)
• v2.00 — Major update (e.g., new architecture, breaking input/output changes)

Every release can include:

• Model files — The core model artifacts (e.g., .onnx files). For large models like LLMs, a single release can hold multiple model files.
• Documentation — READMEs, architecture notes, training logs
• Supporting files — Config files, example scripts, sample data, or anything else useful to consumers

When you create a new model repository, version 1.00 is automatically initialized for you.

TIP

Consumers reference a model by its Blob ID — a content-addressed identifier for a specific file in a specific release. Uploading a new version never changes existing Blob IDs, so existing consumers are unaffected.

Managing Models via the Web UI

The Hub website provides a visual interface for the full model lifecycle:

1. Create a new model repository — set name, description, task, license, tags, and visibility
2. Upload files to a release — drag-and-drop or file picker, with duplicate detection
3. Create new releases — bump the version and add release notes
4. Edit metadata — update descriptions, tags, license, or visibility at any time
5. Rename or delete — available in the model settings panel

Managing Models via the SDK & CLI

The Python SDK and CLI provide the same capabilities for scripted and automated workflows.

CLI

# Create a new model repository
opengradient create-model-repo --repo "my_model" --description "My volatility model"

# Create a new version
opengradient create-version --repo "my_model" --notes "Retrained on Q4 data"

# Upload a file to a specific version
opengradient upload-file path/to/model.onnx --repo "my_model" --version "1.01"

# List files in a version
opengradient list-files --repo "my_model" --version "1.01"

Python Library

import opengradient as og

client = og.Client(private_key="<private_key>", email="<email>", password="<password>")

# Create a model repository (automatically initializes v1.00)
client.model_hub.create_model("my_model", model_desc="My volatility model")

# Create a new minor version
version = client.model_hub.create_version("my_model", notes="Retrained on Q4 data")

# Upload model file
client.model_hub.upload(
    model_path="model.onnx",
    model_name="my_model",
    version=version
)

# List files
files = client.model_hub.list_files("my_model", version)

TIP

Refer to the Getting Started guide to obtain your private key and credentials, and the API Reference for detailed method signatures.