0
# Pydantic Models
1

2
ZenML uses Pydantic for data validation and API request/response modeling. The `zenml.models` module contains 200+ Pydantic model classes representing all ZenML resources and operations.
3

4
## Model Categories
5

6
### Base Models
7

8
Foundation classes for all ZenML Pydantic models.
9

10
```python { .api }
11
class BaseZenModel:
12
    """Base Pydantic model for all ZenML models."""
13

14
class BaseRequest:
15
    """Base for request models."""
16

17
class BaseResponse:
18
    """Base for response models."""
19

20
class BaseUpdate:
21
    """Base for update models."""
22

23
class BaseFilter:
24
    """Base filter class for querying resources."""
25

26
class Page:
27
    """
28
    Paginated response container.
29

30
    Attributes:
31
    - index: Current page index
32
    - max_size: Maximum items per page
33
    - total_pages: Total number of pages
34
    - total: Total number of items
35
    - items: List of items on current page
36
    """
37
```
38

39
Import from:
40

41
```python
42
from zenml.models import (
43
    BaseZenModel,
44
    BaseRequest,
45
    BaseResponse,
46
    Page
47
)
48
```
49

50
### Resource Models
51

52
Each ZenML resource has multiple model variants:
53
- **Request**: For creating resources
54
- **Response**: Returned from API calls
55
- **Update**: For updating resources
56
- **Filter**: For querying/filtering resources
57

58
#### User Models
59

60
```python { .api }
61
class UserRequest:
62
    """Request model for creating users."""
63

64
class UserResponse:
65
    """Response model with user information."""
66

67
class UserUpdate:
68
    """Update model for modifying users."""
69

70
class UserFilter:
71
    """Filter for querying users."""
72
```
73

74
#### Project Models
75

76
```python { .api }
77
class ProjectRequest:
78
    """Request model for creating projects."""
79

80
class ProjectResponse:
81
    """Response model with project information."""
82

83
class ProjectUpdate:
84
    """Update model for modifying projects."""
85

86
class ProjectFilter:
87
    """Filter for querying projects."""
88
```
89

90
#### Stack Models
91

92
```python { .api }
93
class StackRequest:
94
    """Request model for creating stacks."""
95

96
class StackResponse:
97
    """Response model with stack information."""
98

99
class StackUpdate:
100
    """Update model for modifying stacks."""
101

102
class StackFilter:
103
    """Filter for querying stacks."""
104
```
105

106
#### Pipeline Models
107

108
```python { .api }
109
class PipelineRequest:
110
    """Request model for creating pipelines."""
111

112
class PipelineResponse:
113
    """Response model with pipeline information."""
114

115
class PipelineFilter:
116
    """Filter for querying pipelines."""
117
```
118

119
#### Pipeline Run Models
120

121
```python { .api }
122
class PipelineRunRequest:
123
    """Request model for creating pipeline runs."""
124

125
class PipelineRunResponse:
126
    """
127
    Response model with pipeline run information.
128

129
    Attributes:
130
    - id: Run UUID
131
    - name: Run name
132
    - status: Execution status
133
    - pipeline: Associated pipeline
134
    - stack: Stack used for execution
135
    - user: User who created the run
136
    - start_time: Run start time
137
    - end_time: Run end time
138
    - metadata: Run metadata
139
    """
140

141
class PipelineRunFilter:
142
    """Filter for querying pipeline runs."""
143
```
144

145
#### Step Run Models
146

147
```python { .api }
148
class StepRunRequest:
149
    """Request model for creating step runs."""
150

151
class StepRunResponse:
152
    """
153
    Response model with step run information.
154

155
    Attributes:
156
    - id: Step run UUID
157
    - name: Step name
158
    - status: Execution status
159
    - inputs: Input artifacts
160
    - outputs: Output artifacts
161
    - metadata: Step metadata
162
    - start_time: Step start time
163
    - end_time: Step end time
164
    """
165

166
class StepRunFilter:
167
    """Filter for querying step runs."""
168
```
169

170
#### Artifact Models
171

172
```python { .api }
173
class ArtifactRequest:
174
    """Request model for creating artifacts."""
175

176
class ArtifactResponse:
177
    """Response model with artifact information."""
178

179
class ArtifactUpdate:
180
    """Update model for modifying artifacts."""
181

182
class ArtifactFilter:
183
    """Filter for querying artifacts."""
184
```
185

186
#### Artifact Version Models
187

188
```python { .api }
189
class ArtifactVersionRequest:
190
    """Request model for creating artifact versions."""
191

192
class ArtifactVersionResponse:
193
    """
194
    Response model with artifact version information.
195

196
    Attributes:
197
    - id: Artifact version UUID
198
    - artifact: Parent artifact
199
    - version: Version identifier
200
    - uri: Storage URI
201
    - type: Artifact type
202
    - materializer: Materializer used
203
    - data_type: Python data type
204
    - tags: Associated tags
205
    - metadata: Version metadata
206
    """
207

208
class LazyArtifactVersionResponse:
209
    """Lazy-loaded artifact version response."""
210

211
class ArtifactVersionFilter:
212
    """Filter for querying artifact versions."""
213
```
214

215
#### Model Models
216

217
```python { .api }
218
class ModelRequest:
219
    """Request model for creating models."""
220

221
class ModelResponse:
222
    """Response model with model information."""
223

224
class ModelUpdate:
225
    """Update model for modifying models."""
226

227
class ModelFilter:
228
    """Filter for querying models."""
229
```
230

231
#### Model Version Models
232

233
```python { .api }
234
class ModelVersionRequest:
235
    """Request model for creating model versions."""
236

237
class ModelVersionResponse:
238
    """
239
    Response model with model version information.
240

241
    Attributes:
242
    - id: Model version UUID
243
    - model: Parent model
244
    - version: Version identifier
245
    - stage: Model stage (staging, production, etc.)
246
    - description: Version description
247
    - tags: Associated tags
248
    - metadata: Version metadata
249
    - artifact_links: Linked artifacts
250
    - pipeline_run_links: Linked pipeline runs
251
    """
252

253
class ModelVersionUpdate:
254
    """Update model for modifying model versions."""
255

256
class ModelVersionFilter:
257
    """Filter for querying model versions."""
258
```
259

260
#### Secret Models
261

262
```python { .api }
263
class SecretRequest:
264
    """Request model for creating secrets."""
265

266
class SecretResponse:
267
    """Response model with secret information (no values)."""
268

269
class SecretUpdate:
270
    """Update model for modifying secrets."""
271

272
class SecretFilter:
273
    """Filter for querying secrets."""
274
```
275

276
#### Service Connector Models
277

278
```python { .api }
279
class ServiceConnectorRequest:
280
    """Request model for creating service connectors."""
281

282
class ServiceConnectorResponse:
283
    """Response model with connector information."""
284

285
class ServiceConnectorUpdate:
286
    """Update model for modifying connectors."""
287

288
class ServiceConnectorFilter:
289
    """Filter for querying connectors."""
290
```
291

292
#### Tag Models
293

294
```python { .api }
295
class TagRequest:
296
    """Request model for creating tags."""
297

298
class TagResponse:
299
    """
300
    Response model with tag information.
301

302
    Attributes:
303
    - id: Tag UUID
304
    - name: Tag name
305
    - color: Tag color
306
    - tagged_count: Number of tagged resources
307
    """
308

309
class TagUpdate:
310
    """Update model for modifying tags."""
311

312
class TagFilter:
313
    """Filter for querying tags."""
314
```
315

316
### Filter Models
317

318
Specialized filter classes for querying.
319

320
```python { .api }
321
class StrFilter:
322
    """String filtering operations."""
323

324
class BoolFilter:
325
    """Boolean filtering operations."""
326

327
class NumericFilter:
328
    """Numeric filtering operations."""
329

330
class UUIDFilter:
331
    """UUID filtering operations."""
332
```
333

334
### Service Connector Type Models
335

336
```python { .api }
337
class ServiceConnectorTypeModel:
338
    """Service connector type definition."""
339

340
class AuthenticationMethodModel:
341
    """Authentication method definition."""
342

343
class ResourceTypeModel:
344
    """Resource type definition."""
345

346
class ServiceConnectorResourcesModel:
347
    """Available resources for connector."""
348
```
349

350
## Usage Examples
351

352
### Working with Response Models
353

354
```python
355
from zenml.client import Client
356

357
client = Client()
358

359
# Get pipeline run (returns PipelineRunResponse)
360
run = client.get_pipeline_run("run_id")
361

362
# Access response attributes
363
print(f"Run ID: {run.id}")
364
print(f"Name: {run.name}")
365
print(f"Status: {run.status}")
366
print(f"Start time: {run.start_time}")
367

368
# Access nested models
369
print(f"Pipeline: {run.pipeline.name}")
370
print(f"Stack: {run.stack.name}")
371
print(f"User: {run.user.name}")
372
```
373

374
### Using Filters
375

376
```python
377
from zenml.client import Client
378

379
client = Client()
380

381
# Filter pipeline runs
382
runs = client.list_pipeline_runs(
383
    pipeline_id="pipeline_id",
384
    status="completed",
385
    sort_by="created",
386
    size=10
387
)
388

389
# Access paginated results
390
print(f"Total runs: {runs.total}")
391
print(f"Page: {runs.index}/{runs.total_pages}")
392

393
for run in runs.items:
394
    print(f"Run: {run.name}, Status: {run.status}")
395
```
396

397
### Creating Resources
398

399
```python
400
from zenml.client import Client
401

402
client = Client()
403

404
# Create stack (uses StackRequest internally)
405
stack = client.create_stack(
406
    name="my_stack",
407
    components={
408
        "orchestrator": "local",
409
        "artifact_store": "local"
410
    },
411
    description="Development stack"
412
)
413

414
# Returns StackResponse
415
print(f"Created stack: {stack.id}")
416
print(f"Components: {stack.components}")
417
```
418

419
### Updating Resources
420

421
```python
422
from zenml.client import Client
423

424
client = Client()
425

426
# Update model version (uses ModelVersionUpdate internally)
427
updated = client.update_model_version(
428
    model_name_or_id="my_model",
429
    version_name_or_id="1.0.0",
430
    stage="production",
431
    add_tags=["promoted", "validated"]
432
)
433

434
# Returns ModelVersionResponse
435
print(f"Updated version: {updated.version}")
436
print(f"Stage: {updated.stage}")
437
print(f"Tags: {updated.tags}")
438
```
439

440
### Accessing Nested Models
441

442
```python
443
from zenml.client import Client
444

445
client = Client()
446

447
# Get step run with nested artifact information
448
step_run = client.get_run_step("step_run_id")
449

450
# Access output artifacts (ArtifactVersionResponse models)
451
for output_name, artifact in step_run.outputs.items():
452
    print(f"Output: {output_name}")
453
    print(f"  Artifact: {artifact.artifact.name}")
454
    print(f"  Version: {artifact.version}")
455
    print(f"  Type: {artifact.type}")
456
    print(f"  URI: {artifact.uri}")
457
```
458

459
### Model Serialization
460

461
```python
462
from zenml.client import Client
463

464
client = Client()
465

466
# Get model (Pydantic model)
467
model = client.get_model("my_model")
468

469
# Serialize to dict
470
model_dict = model.dict()
471
print(model_dict)
472

473
# Serialize to JSON
474
model_json = model.json()
475
print(model_json)
476

477
# Model has Pydantic validation
478
try:
479
    invalid_model = model.copy(update={"invalid_field": "value"})
480
except Exception as e:
481
    print(f"Validation error: {e}")
482
```
483

484
All models in `zenml.models` are Pydantic models with automatic validation, serialization, and type checking. They represent the complete API surface for interacting with ZenML resources programmatically.
485

486
Import from:
487

488
```python
489
from zenml.models import (
490
    PipelineRunResponse,
491
    StepRunResponse,
492
    ArtifactVersionResponse,
493
    ModelVersionResponse,
494
    # ... and 200+ other models
495
)
496
```
497