zenml - Moses Yebei

The Problem

ML teams building LLM workflows and agents face a split: pipelines run in one framework, agents in another, and production infrastructure is a third system. ZenML addresses this by providing a single platform where you define pipelines and agent loops as Python code, then run them on any backend—local, cloud, or Kubernetes—without rewriting the workflow.

What This Does

ZenML is a workflow orchestration platform for ML and AI engineering. The core library lives in src/zenml/ (1,310 files) and lets you define pipelines, steps, and stacks. It containerizes your code, tracks runs with metrics and metadata, and abstracts infrastructure via integrations with MLflow, LangGraph, Langfuse, SageMaker, and Vertex AI.

The repo includes extensive examples (examples/, 394 files) covering agent frameworks (LangChain, CrewAI, AutoGen, Haystack), computer vision, and end-to-end NLP. A Helm chart (helm/) and Dockerfiles (docker/) support self-hosted deployment. The docs (docs/, 820 files) are comprehensive, and there are 692 test files.

How It Is Wired

The import graph shows 1,477 internal modules with 183 edges. The hub module is tests/unit/test_general, with 31 modules depending on it—high blast radius for changes. Ten modules participate in circular imports, including tests/harness/model/__init__.py and tests/harness/deployment/client_sqlite.py; breaking these cycles requires extracting shared types or deferring imports.

Entry points are example-driven. examples/e2e_nlp/gradio/app.py is a Gradio UI for an NLP pipeline; examples/deploying_agent/steps/ingest.py shows the agent ingestion flow. The steps/__init__.py files across examples/mlops_starter, examples/e2e_nlp, and examples/e2e each import 8 modules—these are the pipeline definition points.

Execution flows: pipeline definitions in steps/ → orchestration in src/zenml/ → infrastructure via integrations. The src/zenml/integrations/ directory contains adapters for external systems. The src/zenml/zen_stores/ handles persistence. A run touches the database through the store layer, with the deployment client in tests/harness/deployment/client_sqlite.py (in a cycle) managing SQLite state.

How To Use It

# Clone and install
git clone https://github.com/moses-y/zenml
cd zenml
pip install -e .

# Run an example pipeline
cd examples/e2e_nlp
python run.py

Configuration uses ZenML's stack concept—define a stack in zenml stack init and register backends. The pyproject.toml declares 15 dependencies, but there is no lockfile, so installs are not reproducible. The examples/*/requirements.txt files define per-example dependencies. For containerized deployment, use the Dockerfiles in docker/ or the Helm chart in helm/.

Real-World Use

A team building a customer-support agent with LangGraph could define a pipeline in src/zenml/, use the LangGraph integration from examples/agent_framework_integrations/langgraph/, track runs with Langfuse (declared dependency), and deploy to a Kubernetes stack via the Helm chart. The same pipeline runs locally for development and on production infrastructure without code changes.

Code Health & Issues

Static analysis found 88 findings (17 high, 71 medium) across 6 categories. Key issues:

High - Hub module - tests/unit/test_general.py: 31 modules depend on it; volatile changes have wide impact.
High - Import cycles - 10 modules in circular dependencies, including tests/harness/model/__init__.py and tests/harness/deployment/client_sqlite.py.
High - Deep nesting - 25 instances of indentation depth 6+, notably tests/harness/deployment/client_sqlite.py.
High - Duplicated code - 271 repeated 6-line blocks across 744 files, including src/zenml/integrations/skypilot/__init__.py.
Medium - Broad exception handling - 7 instances, e.g., examples/deploying_agent/steps/ingest.py.
Medium - Unmanaged file handles - 16 instances of open() without context managers.

Code health audit adds: High - no lockfile for pyproject.toml; Medium - mutable base image python:3.9 in examples/e2e_nlp/gradio/Dockerfile; Medium - 7 blobs over 5MB in the repo (largest: 13.7MB GIF). Committed secrets flagged as present—verify before deploying.

The Bottom Line

ZenML is a mature, widely adopted platform (5,500+ stars upstream) with strong docs and integrations. The codebase has real maintainability debt—cycles, deep nesting, duplication—but the architecture is sound for production ML workflows. Teams needing a portable pipeline layer across cloud backends will benefit; those wanting minimal dependencies should look elsewhere.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

3,360 files

Python2204
Markdown455
YAML116
Shell28
HTML15
JSON13

DjangoFlaskFastAPIDockerKubernetesPyTorchTensorFlowTransformersYOLOLangChainpandasSparkAirflowMLflow

Module dependencies

The 10 most depended-upon modules of 1,477, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_tests_unit_test_general["test_general"] n1_tests_harness_model___init__["__init__"] n2_tests_harness_model_base["base"] n3_sts_harness_model_deployment["deployment"] n4_ess_deployment_client_sqlite["client_sqlite"] n5_tests_harness_model_secret["secret"] n6_tests_harness_cli_cli["cli"] n7_ts_harness_model_environment["environment"] n8_egration_functional_conftest["conftest"] n9_gration_functional_cli_utils["utils"] n1_tests_harness_model___init__ --> n2_tests_harness_model_base n1_tests_harness_model___init__ --> n3_sts_harness_model_deployment n1_tests_harness_model___init__ --> n7_ts_harness_model_environment n1_tests_harness_model___init__ --> n5_tests_harness_model_secret n4_ess_deployment_client_sqlite --> n1_tests_harness_model___init__ n3_sts_harness_model_deployment --> n2_tests_harness_model_base n3_sts_harness_model_deployment --> n5_tests_harness_model_secret n5_tests_harness_model_secret --> n2_tests_harness_model_base n7_ts_harness_model_environment --> n2_tests_harness_model_base n7_ts_harness_model_environment --> n3_sts_harness_model_deployment classDef cyc stroke:#ef4444,stroke-width:2px; class n1_tests_harness_model___init__,n3_sts_harness_model_deployment,n4_ess_deployment_client_sqlite,n7_ts_harness_model_environment cyc;

Dependencies

7 of 15 declared dependencies are a major version behind. Resolved 15 of 15 against the registry.

Package	Declared	Latest	Behind
`pandas`	>=1.5.0	3.0.5	2 major
`openai`	>=1.0.0	3.1.0	2 major
`langfuse`	>=2,<3	4.14.4	2 major
`secure`	>=0.3.0	2.0.1	2 major
`langgraph`	>=0.5.0	1.2.11	1 major
`langchain-core`	>=0.3.0	1.5.5	1 major
`numpy`	>=1.21.0	2.5.2	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds examples/agent_comparison/requirements.txt
LowSecret-shaped paths present; the code-health audit confirms or clears them docs/book/api-docs/oss-api-docs/v1/secrets.md, docs/book/how-to/secrets/secrets.md, helm/templates/custom-ca-secrets.yaml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium3

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Pin the container base image by digestmedium

examples/e2e_nlp/gradio/Dockerfile

python:3.9

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Move large binaries to Git LFS or out of the repositorymedium7 occurrences

docs/book/.gitbook/assets/readme_simple_pipeline.gif

7 blobs over 5MB: readme_simple_pipeline.gif 13.7MB, readme_compute.gif 10.9MB, readme_mcp.gif 8.7MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Pin the resolution so a vulnerable version cannot installmedium61 occurrences

no lockfile, and the declared ranges reach litellm@1.40.0 CVE-2026-49468 (critical) +34 more; langchain-core@0.3.0 CVE-2025-68664 (critical) +13 more; jinja2@3.1.0 CVE-2024-56201 (high) +9 more; and 1 more package(s)

The range includes versions with published advisories and nothing in the repository records which one was resolved, so two installs a month apart can differ in whether they are vulnerable and neither is reproducible from what is committed.

Fix: Commit the lockfile, which fixes the resolution and makes this answerable.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.