Your first use case

The quickstart went fast. This tutorial takes the same churn use case slowly: what each file decides, what each command checked, and how to read what the run produced.

1. Read the folder

Open usecases/churn/usecase.yaml. It says what the model is, who owns it, which pipelines it has and how a version is promoted and served. Everything else is under config/, one concern per file. Start with config/data.yaml: the data contract is the promise every file must keep before anything learns from it.

data:
  contract:
    columns:
      - { name: customer_id,   type: string,  required: true, max_null_fraction: 0 }
      - { name: tenure_months, type: integer, min: 0, max: 1000 }
      - { name: churned,       type: integer, allowed: [0, 1] }
    min_rows: 500
    unique: [customer_id]

Then config/evaluation.yaml: the gates a model must pass, and the champion it must beat.

2. Check it before it costs anything

pipewright validate --env dev
pipewright doctor   --env dev

validate works offline: schemas, references to the manifest’s names, table schemas, and cross-checks such as a gate on a metric nobody computes. doctor reads the live environment: the team’s identity, dataset and landing prefix, that the pipelines compile, and the permissions a run will need. Each failure says who to ask.

Break something on purpose: change min: 0.75 to minimum: 0.75 in a gate and run validate again. The error names the file, the path and what was expected.

3. Release it

pipewright tables sync --env dev
git add -A && git commit -m "churn: contract and gates"
pipewright release --env dev
pipewright status  --env dev --usecase churn

The release builds the component image from your code, compiles each pipeline, pushes both by digest, writes the contract once, verifies it and moves the live pointer. Run the release again: nothing changes, because nothing did.

4. Train and judge

gcloud storage cp usecases/churn/data/sample_customers.csv gs://<project>-pw-landing/incoming/<your-team>/
pipewright status     --env dev --usecase churn
pipewright model list --env dev --usecase churn

The file landing starts a training run of the live release. Watch it in the Agent Platform console under Pipelines: each box is a step, a container from the release’s image, and the small items between them are the artifacts each step hands the next. The run ingests the file, checks the contract, prepares and splits the rows, trains, evaluates against the gates and the champion, records its metrics, and registers the model only if it passed.

5. Decide

With approvals.promote_model: manual, a passing model is a candidate. Look at it, then decide:

pipewright model check   --env dev --usecase churn --version 1
pipewright model approve --env dev --usecase churn --version 1

Pipewright recomputes the gates from the version’s evaluation record before it makes it the champion. Train a second time with the same file and compare: the second version must beat the first to be registered as a better champion.

What you learned

• Decisions live in YAML, reviewed like code; your model code stays yours.
• A release is a fact: the same commit always means the same images and templates.
• A model reaches the registry only by passing its gates, and becomes the champion only when a person says so.