0
# Artifacts
1

2
Artifact management functions for saving, loading, and registering artifacts outside the standard step output flow. ZenML automatically tracks artifact lineage, versions, and metadata.
3

4
## Capabilities
5

6
### Save Artifact
7

8
Save an artifact to the artifact store programmatically.
9

10
```python { .api }
11
def save_artifact(
12
    data,
13
    name: str,
14
    version: str = None,
15
    artifact_type = None,
16
    tags: list = None,
17
    extract_metadata: bool = True,
18
    include_visualizations: bool = True,
19
    user_metadata: dict = None,
20
    materializer: type = None,
21
    uri: str = None
22
):
23
    """
24
    Save an artifact to the artifact store.
25

26
    Parameters:
27
    - data: Data object to save
28
    - name: Artifact name
29
    - version: Artifact version (auto-generated if None)
30
    - artifact_type: Type of artifact (e.g., ArtifactType.MODEL, ArtifactType.DATA)
31
    - tags: List of tag names to attach
32
    - extract_metadata: Extract metadata automatically (default: True)
33
    - include_visualizations: Generate visualizations (default: True)
34
    - user_metadata: Custom metadata dict
35
    - materializer: Custom materializer class for serialization
36
    - uri: Optional URI to use for the artifact (advanced usage)
37

38
    Returns:
39
    ArtifactVersionResponse: Created artifact version object
40

41
    Example:
42
    ```python
43
    from zenml import save_artifact
44
    from zenml.enums import ArtifactType
45

46
    # Save a simple artifact
47
    artifact = save_artifact(
48
        data={"accuracy": 0.95, "loss": 0.05},
49
        name="model_metrics",
50
        tags=["evaluation", "production"]
51
    )
52
    print(f"Saved artifact: {artifact.id}")
53

54
    # Save with custom metadata and artifact type
55
    artifact = save_artifact(
56
        data=[1, 2, 3, 4, 5],
57
        name="training_data",
58
        version="v1.0",
59
        artifact_type=ArtifactType.DATA,
60
        user_metadata={"source": "database", "rows": 5}
61
    )
62
    ```
63
    """
64
```
65

66
Import from:
67

68
```python
69
from zenml import save_artifact
70
```
71

72
### Load Artifact
73

74
Load an artifact from the artifact store.
75

76
```python { .api }
77
def load_artifact(
78
    name_or_id: str,
79
    version: str = None
80
):
81
    """
82
    Load an artifact from the artifact store.
83

84
    Parameters:
85
    - name_or_id: Artifact name or UUID
86
    - version: Artifact version (loads latest if None)
87

88
    Returns:
89
    Data object loaded from artifact store
90

91
    Example:
92
    ```python
93
    from zenml import load_artifact
94

95
    # Load latest version by name
96
    data = load_artifact("training_data")
97

98
    # Load specific version
99
    data = load_artifact("training_data", version="v1.0")
100

101
    # Load by UUID
102
    data = load_artifact("12345678-1234-1234-1234-123456789012")
103
    ```
104
    """
105
```
106

107
Import from:
108

109
```python
110
from zenml import load_artifact
111
```
112

113
### Register Artifact
114

115
Register an existing artifact from a URI.
116

117
```python { .api }
118
def register_artifact(
119
    folder_or_file_uri: str,
120
    name: str,
121
    version: str = None,
122
    artifact_type=None,
123
    tags: list = None,
124
    has_custom_name: bool = True,
125
    artifact_metadata: dict = {}
126
):
127
    """
128
    Register existing data stored in the artifact store as a ZenML Artifact.
129

130
    The URI must point to a location within the active artifact store.
131

132
    Parameters:
133
    - folder_or_file_uri: Full URI within the artifact store to folder or file
134
    - name: Artifact name in ZenML
135
    - version: Artifact version (auto-incremented if None)
136
    - artifact_type: Type of artifact (defaults to 'data' if not given)
137
    - tags: List of tag names
138
    - has_custom_name: If artifact name is custom and should be listed in dashboard
139
    - artifact_metadata: Metadata dictionary to attach to the artifact version
140

141
    Returns:
142
    ArtifactVersionResponse: Registered artifact version object
143

144
    Raises:
145
    FileNotFoundError: If the folder URI is outside the artifact store bounds
146

147
    Example:
148
    ```python
149
    from zenml import register_artifact
150
    from zenml.enums import ArtifactType
151

152
    # Register artifact from artifact store
153
    artifact = register_artifact(
154
        folder_or_file_uri="s3://artifact-store/models/model.pkl",
155
        name="pretrained_model",
156
        version="v1.0",
157
        tags=["pretrained", "imported"],
158
        artifact_metadata={"source": "external"},
159
        artifact_type=ArtifactType.MODEL
160
    )
161

162
    # Register file in artifact store
163
    artifact = register_artifact(
164
        folder_or_file_uri="gs://artifact-store/data/data.csv",
165
        name="external_dataset"
166
    )
167
    ```
168
    """
169
```
170

171
Import from:
172

173
```python
174
from zenml import register_artifact
175
```
176

177
### Log Artifact Metadata
178

179
Log metadata for an artifact.
180

181
```python { .api }
182
def log_artifact_metadata(
183
    metadata: dict,
184
    artifact_name: str = None,
185
    artifact_version: str = None
186
):
187
    """
188
    Log metadata for an artifact.
189

190
    Can be called within a step to attach metadata to output artifacts,
191
    or called outside step execution to attach metadata to any artifact.
192

193
    Parameters:
194
    - metadata: Metadata dict to log (keys must be strings)
195
    - artifact_name: Artifact name (uses current step output if None)
196
    - artifact_version: Artifact version
197

198
    Example:
199
    ```python
200
    from zenml import step, log_artifact_metadata
201

202
    @step
203
    def train_model(data: list) -> dict:
204
        model = {"weights": [0.1, 0.2], "accuracy": 0.95}
205

206
        # Log metadata for the output artifact
207
        log_artifact_metadata(
208
            metadata={
209
                "training_time": "120s",
210
                "epochs": 10,
211
                "optimizer": "adam"
212
            }
213
        )
214

215
        return model
216

217
    # Log metadata for existing artifact
218
    from zenml import log_artifact_metadata
219

220
    log_artifact_metadata(
221
        metadata={"reviewed": True, "reviewer": "data-team"},
222
        artifact_name="training_data",
223
        artifact_version="v1.0"
224
    )
225
    ```
226
    """
227
```
228

229
Import from:
230

231
```python
232
from zenml import log_artifact_metadata
233
```
234

235
## Related Types
236

237
### Artifact Type Enum
238

239
```python { .api }
240
class ArtifactType(str, Enum):
241
    """
242
    Types of artifacts.
243

244
    Values:
245
    - DATA: General data artifacts
246
    - MODEL: Model artifacts
247
    - DATA_ANALYSIS: Data analysis results
248
    - SERVICE: Service artifacts
249
    - STATISTICS: Statistical data
250
    - SCHEMA: Schema definitions
251
    - BASE: Base artifact type
252
    """
253
    DATA = "data"
254
    MODEL = "model"
255
    DATA_ANALYSIS = "data_analysis"
256
    SERVICE = "service"
257
    STATISTICS = "statistics"
258
    SCHEMA = "schema"
259
    BASE = "base"
260
```
261

262
Import from:
263

264
```python
265
from zenml.enums import ArtifactType
266
```
267

268
## Usage Examples
269

270
### Saving and Loading Artifacts
271

272
```python
273
from zenml import save_artifact, load_artifact
274
from zenml.enums import ArtifactType
275

276
# Train a model
277
model_data = {
278
    "weights": [0.1, 0.2, 0.3],
279
    "bias": 0.5,
280
    "accuracy": 0.95
281
}
282

283
# Save model as artifact
284
saved = save_artifact(
285
    data=model_data,
286
    name="my_model",
287
    version="v1.0",
288
    artifact_type=ArtifactType.MODEL,
289
    tags=["production", "trained"],
290
    user_metadata={
291
        "framework": "custom",
292
        "training_time": "300s"
293
    }
294
)
295

296
print(f"Saved model artifact: {saved.id}")
297

298
# Later, load the model
299
loaded_model = load_artifact("my_model", version="v1.0")
300
print(f"Model accuracy: {loaded_model['accuracy']}")
301
```
302

303
### Registering Artifacts from Artifact Store
304

305
```python
306
from zenml import register_artifact
307
from zenml.enums import ArtifactType
308

309
# Register a pre-trained model in artifact store
310
model_artifact = register_artifact(
311
    folder_or_file_uri="s3://artifact-store/models/bert-base.bin",
312
    name="bert_base_pretrained",
313
    version="huggingface-v1",
314
    tags=["pretrained", "transformer", "nlp"],
315
    artifact_type=ArtifactType.MODEL,
316
    artifact_metadata={
317
        "source": "huggingface",
318
        "model_id": "bert-base-uncased",
319
        "parameters": "110M"
320
    }
321
)
322

323
# Register dataset in artifact store
324
data_artifact = register_artifact(
325
    folder_or_file_uri="gs://artifact-store/data/train.parquet",
326
    name="processed_training_data",
327
    tags=["training", "processed"],
328
    artifact_type=ArtifactType.DATA
329
)
330
```
331

332
### Logging Metadata in Steps
333

334
```python
335
from zenml import step, log_artifact_metadata
336
from typing import Tuple
337

338
@step
339
def preprocess_and_train(raw_data: list) -> Tuple[dict, dict]:
340
    """Preprocess data and train model."""
341

342
    # Preprocessing
343
    processed_data = [x * 2 for x in raw_data]
344

345
    # Log metadata for first output (processed_data)
346
    log_artifact_metadata(
347
        metadata={
348
            "preprocessing": "scaling",
349
            "scale_factor": 2,
350
            "rows": len(processed_data)
351
        }
352
    )
353

354
    # Training
355
    model = {"weights": [0.1, 0.2], "accuracy": 0.95}
356

357
    # Log metadata for second output (model)
358
    log_artifact_metadata(
359
        metadata={
360
            "training_epochs": 10,
361
            "optimizer": "adam",
362
            "learning_rate": 0.001
363
        }
364
    )
365

366
    return processed_data, model
367
```
368

369
### Working with Artifact Versions
370

371
```python
372
from zenml import save_artifact, load_artifact, log_artifact_metadata
373

374
# Save multiple versions
375
for i in range(3):
376
    model = {"version": i, "accuracy": 0.9 + i * 0.01}
377
    save_artifact(
378
        data=model,
379
        name="evolving_model",
380
        version=f"v{i}.0",
381
        tags=["training"]
382
    )
383

384
# Load latest version
385
latest = load_artifact("evolving_model")
386
print(f"Latest version: {latest}")
387

388
# Load specific version
389
v1 = load_artifact("evolving_model", version="v1.0")
390
print(f"V1.0: {v1}")
391

392
# Add metadata to specific version
393
log_artifact_metadata(
394
    metadata={"status": "production", "deployed": True},
395
    artifact_name="evolving_model",
396
    artifact_version="v2.0"
397
)
398
```
399

400
### Custom Materializer
401

402
```python
403
from zenml import save_artifact, load_artifact
404
from zenml.materializers import CloudpickleMaterializer
405

406
# Custom object
407
class CustomModel:
408
    def __init__(self, weights):
409
        self.weights = weights
410

411
    def predict(self, x):
412
        return sum(w * x for w, x in zip(self.weights, x))
413

414
model = CustomModel([0.1, 0.2, 0.3])
415

416
# Save with custom materializer
417
save_artifact(
418
    data=model,
419
    name="custom_model",
420
    materializer=CloudpickleMaterializer
421
)
422

423
# Load
424
loaded = load_artifact("custom_model")
425
prediction = loaded.predict([1, 2, 3])
426
print(f"Prediction: {prediction}")
427
```
428

429
### Artifact Operations from Client
430

431
```python
432
from zenml.client import Client
433

434
client = Client()
435

436
# Get artifact by name
437
artifact = client.get_artifact("training_data")
438
print(f"Artifact: {artifact.name}")
439

440
# List all versions
441
versions = client.list_artifact_versions(name="training_data")
442
for v in versions:
443
    print(f"Version {v.version}: {v.uri}")
444

445
# Get specific version
446
version = client.get_artifact_version("training_data", version="v1.0")
447
print(f"URI: {version.uri}")
448

449
# Update artifact metadata
450
client.update_artifact_version(
451
    name_or_id=version.id,
452
    add_tags=["validated"]
453
)
454

455
# Delete artifact version
456
client.delete_artifact_version(version.id)
457
```
458