bauplan-migrate-to-typed-sdk

Migrating a Bauplan Pipeline to the Typed SDK

Bauplan 0.3.x replaces the old declaration style with type annotations that double as a semantic layer: column projections and output contracts become TableSchema classes, model inputs become Annotated[pa.Table, Model(...)] parameters, and run parameters become Annotated[<type>, Parameter(...)]. This skill takes an existing old-style project, rewrites it to the typed style, and validates the result until the pipeline runs green.

The complete old-to-new pattern catalog with real code is in examples.md. Read it before rewriting any file.

What changes, in one look

Old (0.1.x or 0.2.x)	New (0.3.x)
data=bauplan.Model("t", columns=[...], filter=...)	data: Annotated[pa.Table, Model("t", projection_schema=SomeSchema, filter=...)]
@bauplan.model(columns=[...])	@bauplan.model() + -> Annotated[pa.Table, OutputSchema]
no schema objects	class SomeSchema(TableSchema) with typed fields, optional TableField(name=, doc=, lineage=)
x=bauplan.Parameter("x")	x: Annotated[float, Parameter("x")]
return list/pandas/polars/arrow	return an actual pa.Table

CRITICAL: Branch Safety

NEVER run pipelines on main branch. Always checkout to a test branch first: bauplan checkout -b <username>.<branch_name> --from-ref main. ALWAYS validate the migrated pipeline on a separate data branch.

Get the username by running bauplan info.

Input

Before starting, you need to find all the Bauplan projects that need migration. A Bauplan project is a folder containing bauplan_project.yml or bauplan_project.yaml.

You can find them using e.g. find . -name 'bauplan_project.yml' -o -name 'bauplan_project.yaml'.

Migration Workflow

Step 1: Inventory

Read every models.py, expectations.py, other *.py model files, *.sql files, and bauplan_project.yml (also accepted as bauplan_project.yaml) in the project. List:

• every @bauplan.model and @bauplan.expectation function
• every bauplan.Model(...) input and its columns / filter / other kwargs
• every bauplan.Parameter(...) and its type: in bauplan_project.yml
• every columns=[...] on a @bauplan.model() decorator
• every internet_access=... on a @bauplan.model() decorator
• every model return statement and what it returns (arrow, polars, pandas, list of dicts)