Templates API - Magpie Cloud Python SDK

Templates Overview

Templates allow you to create reusable job configurations with variable substitution. Instead of hardcoding values in your scripts, you can define placeholders using {{ variable }} syntax and provide different values when running the template.

This is particularly useful for parameterizing common workflows, creating standardized job configurations across teams, and separating configuration from execution. Templates reduce duplication and make it easy to run the same job logic with different inputs.

Variable Substitution

Variables in templates use double curly brace syntax: {{ variable_name }}. When you run a template, you provide a dictionary of variable values, and Magpie substitutes them into the script before execution.

Example Template Script

echo "Processing dataset: {{ dataset_name }}"
python train.py --epochs {{ epochs }} --lr {{ learning_rate }}
echo "Saving results to {{ output_path }}"

templates.create()

Create a new job template with variable placeholders for reusable configurations.

client.templates.create(name, script, vcpus=None, memory_mb=None, variables=None, **kwargs)

Parameters

Parameter	Type	Description
name required	str	A unique name for the template. Used for identification and retrieval.
script required	str	The bash script with {{ variable }} placeholders for substitution.
vcpus optional	int	Number of virtual CPUs to allocate. Defaults to 1.
memory_mb optional	int	Memory allocation in megabytes. Defaults to 512 MB.
variables optional	list	List of variable names that can be used in the template. Used for validation.
**kwargs optional	dict	Additional job configuration options (stateful, persistent, env, timeout, etc.).

Returns

Returns a template object with properties including id, name, script, vcpus, memory_mb, and variables.

Example

from magpie import Magpie

client = Magpie(api_key="your_api_key_here")

# Create a simple template
template = client.templates.create(
    name="data-processor",
    script="""
        echo "Processing {{ input_file }}"
        python process.py --input {{ input_file }} --output {{ output_file }}
        echo "Results saved to {{ output_file }}"
    """,
    vcpus=2,
    memory_mb=2048,
    variables=["input_file", "output_file"]
)

print(f"Template ID: {template.id}")
print(f"Variables: {template.variables}")

# Create a template for ML training
ml_template = client.templates.create(
    name="ml-training",
    script="""
        pip install torch numpy
        python train.py \\
            --dataset {{ dataset }} \\
            --epochs {{ epochs }} \\
            --batch-size {{ batch_size }} \\
            --lr {{ learning_rate }} \\
            --model-path /workspace/models/{{ model_name }}
    """,
    vcpus=8,
    memory_mb=16384,
    variables=["dataset", "epochs", "batch_size", "learning_rate", "model_name"],
    stateful=True,
    env={
        "CUDA_VISIBLE_DEVICES": "0"
    }
)

# Create a template with dynamic resources
dynamic_template = client.templates.create(
    name="flexible-job",
    script="""
        echo "Running with {{ cores }} cores and {{ memory }} MB memory"
        ./run_task.sh {{ task_name }}
    """,
    vcpus=4,
    memory_mb=8192,
    variables=["cores", "memory", "task_name"]
)

templates.run()

Run a template by providing values for its variables, creating a job with substituted values.

client.templates.run(template_id, variables=None)

Parameters

Parameter	Type	Description
template_id required	str	The unique identifier of the template to run.
variables optional	dict	Dictionary mapping variable names to their values for substitution.

Returns

Returns a job object that was created from the template with all variables substituted. The job object contains the same properties as jobs created with jobs.create().

Example

from magpie import Magpie

client = Magpie(api_key="your_api_key_here")

# Run a data processing template
job1 = client.templates.run(
    template_id="template_abc123",
    variables={
        "input_file": "/data/raw/dataset1.csv",
        "output_file": "/data/processed/dataset1.parquet"
    }
)

print(f"Job started: {job1.id}")

# Run the same template with different inputs
job2 = client.templates.run(
    template_id="template_abc123",
    variables={
        "input_file": "/data/raw/dataset2.csv",
        "output_file": "/data/processed/dataset2.parquet"
    }
)

# Run ML training template
training_job = client.templates.run(
    template_id="template_ml_xyz",
    variables={
        "dataset": "imagenet",
        "epochs": "100",
        "batch_size": "32",
        "learning_rate": "0.001",
        "model_name": "resnet50_v1"
    }
)

print(f"Training job ID: {training_job.id}")
print(f"Status: {training_job.status}")

# Run template with minimal variables
simple_job = client.templates.run(
    template_id="template_simple",
    variables={
        "task_name": "backup"
    }
)

templates.get()

Retrieve detailed information about a specific template by its ID.

client.templates.get(template_id)

Parameters

Parameter	Type	Description
template_id required	str	The unique identifier of the template to retrieve.

Returns

Returns a template object containing all template details including name, script, variables, resource configuration, and timestamps.

Example

from magpie import Magpie

client = Magpie(api_key="your_api_key_here")

# Get template details
template = client.templates.get("template_abc123xyz")

print(f"Template Name: {template.name}")
print(f"vCPUs: {template.vcpus}")
print(f"Memory: {template.memory_mb} MB")
print(f"Variables: {template.variables}")
print(f"Created: {template.created_at}")

print("\nTemplate Script:")
print(template.script)

# Check if specific variables are defined
if "dataset" in template.variables:
    print("This template requires a dataset parameter")

# Inspect template configuration before running
config = client.templates.get("template_xyz")
if config.stateful:
    print("This template uses stateful storage")

templates.list()

List all templates in your account with optional pagination.

client.templates.list(limit=None, offset=None)

Parameters

Parameter	Type	Description
limit optional	int	Maximum number of templates to return. Defaults to 100.
offset optional	int	Number of templates to skip for pagination. Defaults to 0.

Returns

Returns a list of template objects, each containing template details including id, name, variables, and resource configuration.

Example

from magpie import Magpie

client = Magpie(api_key="your_api_key_here")

# List all templates
templates = client.templates.list()

print(f"Total templates: {len(templates)}")

for template in templates:
    print(f"\nID: {template.id}")
    print(f"Name: {template.name}")
    print(f"Variables: {template.variables}")
    print(f"Resources: {template.vcpus} vCPUs, {template.memory_mb} MB")

# List with pagination
first_page = client.templates.list(limit=10, offset=0)
second_page = client.templates.list(limit=10, offset=10)

print(f"First page: {len(first_page)} templates")
print(f"Second page: {len(second_page)} templates")

# Find templates by name pattern
all_templates = client.templates.list()
ml_templates = [t for t in all_templates if "ml" in t.name.lower()]

print(f"\nFound {len(ml_templates)} ML templates:")
for template in ml_templates:
    print(f"  - {template.name}")

# Get templates with specific resource requirements
high_memory = [t for t in all_templates if t.memory_mb >= 8192]
print(f"\nHigh memory templates: {len(high_memory)}")

templates.delete()

Permanently delete a template. This does not affect jobs that were created from the template.

client.templates.delete(template_id)

Parameters

Parameter	Type	Description
template_id required	str	The unique identifier of the template to delete.

Returns

Returns a confirmation object indicating the template has been deleted successfully.

Note: Deleting a template does not affect jobs that were previously created from it. Those jobs will continue to exist and function normally. Only the template definition itself is removed, preventing new jobs from being created from it.

Example

from magpie import Magpie

client = Magpie(api_key="your_api_key_here")

# Create a temporary template
template = client.templates.create(
    name="temp-template",
    script="echo 'Hello {{ name }}'",
    vcpus=1,
    memory_mb=512,
    variables=["name"]
)

# Use the template
job = client.templates.run(
    template_id=template.id,
    variables={"name": "World"}
)

print(f"Job created: {job.id}")

# Delete the template
result = client.templates.delete(template.id)
print(f"Template deleted: {result}")

# The job still exists and runs normally
status = client.jobs.get_status(job.id)
print(f"Job status: {status}")

# But we can't create new jobs from the deleted template
try:
    client.templates.run(template.id, variables={"name": "Test"})
except Exception as e:
    print(f"Error: {e}")  # Template not found

# Clean up old templates
templates = client.templates.list()
for template in templates:
    # Delete templates older than a certain date or matching criteria
    if "deprecated" in template.name:
        client.templates.delete(template.id)
        print(f"Deleted deprecated template: {template.name}")

Next Steps

Jobs API View Examples Client API