Building an action foundation model chain in Zipline.AI
Six declarative Python configs define a three-model action FM chain that Zipline.AI compiles into backfills, live streams, online lookups, and isolated rollouts.
Part 4 of 4 in our series on action foundation models: Part 1: Foundations · Part 2: Training · Part 3: Serving · Part 4: In Zipline.AI
In Part 1, Part 2, and Part 3, we designed a chain of three models around user sequences. An off-the-shelf content encoder embeds item text, an action FM summarizes ordered user events into an actor embedding, and a downstream model scores live tasks. Production use relies on four guarantees: point-in-time training sets, shared offline-online logic, surgical recomputes, and atomic branch releases.
1. Declaring the chain in six Python configs
In Zipline.AI, you declare sources, aggregations, joins, and model calls as Python objects. One compiler translates those definitions into Spark jobs for backfills (recomputing historical features across past dates), Flink streaming jobs, and online key-value lookups.
Six configs connect the full pipeline. Step 1 embeds item descriptions, while steps 2 and 3 build each user's recent action sequence with item vectors attached. Steps 4 and 5 run and stream the action FM, and step 6 joins the actor embedding into checkout fraud features.
_Six linked Python configs build the fraud training table._ Step 1. Embed unstructured item content (Model + ModelTransforms + GroupBy)
The chain begins on the item catalog with Vertex AI's gemini-embedding-001 encoder on each listing's headline and description. A GroupBy keyed by listing_id stores the latest vector for each item.
# Embed each listing's headline and description with Vertex AI gemini-embedding-001 and store by listing_id.
item_description_model = Model(
version="1",
inference_spec=InferenceSpec(
model_backend=ModelBackend.VERTEXAI,
model_backend_params={
"model_name": "gemini-embedding-001",
"model_type": "publisher",
},
),
input_mapping={
"instance": "named_struct('content', concat_ws('; ', listing_id_headline, listing_id_long_description))",
},
output_mapping={
"item_embedding": "gcp_listing_item_description_model__1__embeddings.values",
},
value_fields=[("embeddings", embeddings_schema)],
)
listing_mt = ModelTransforms(
sources=[JoinSource(
join=listing_details_join,
query=Query(wheres=[
"(listing_id_headline IS NOT NULL AND listing_id_headline != '') OR "
"(listing_id_long_description IS NOT NULL AND listing_id_long_description != '')"
]),
)],
models=[item_description_model],
passthrough_fields=["listing_id"],
version=1,
)
item_embedding = GroupBy(
sources=[listing_mt],
keys=["listing_id"],
aggregations=[
Aggregation(
input_column="gcp_listing_item_description_model__1__item_embedding",
operation=Operation.LAST,
),
],
accuracy=Accuracy.TEMPORAL,
online=True,
version=1,
)Before calling Vertex AI, listing_mt uses a wheres filter to drop empty strings, which managed embedding APIs reject. Because gemini-embedding-001 is a frozen vendor model trained outside your logs, it needs no training_conf and cannot peek at your future.
Step 2. Collect the user's last 128 actions (GroupBy)
With item vectors stored by listing_id, a GroupBy on user_activities_source tracks user behavior. Using Operation.LAST_K(128), it collects each user's 128 most recent actions over a 7-day window.
# Collect each user's 128 most recent actions over a 7-day window.
user_activities_gb = GroupBy(
sources=[user_activities_source],
keys=["user_id"],
aggregations=[
Aggregation(
input_column="user_event_struct",
operation=Operation.LAST_K(128),
windows=[Window(length=7, time_unit=TimeUnit.DAYS)],
),
],
accuracy=Accuracy.TEMPORAL,
online=True,
version=1,
)Setting accuracy=Accuracy.TEMPORAL clamps historical sequences to event timestamps during backfills. Pairing it with online=True keeps that 128-event window updated live on the stream.
Step 3. Chain item embeddings onto recent actions (Join onto Join)
The action FM reads the 128 behavioral events for long-range history, while attaching dense item vectors only to the 15 latest actions. Each resolved item adds one online key-value lookup, and capping enrichment at 15 slots keeps live fan-out fast. Zipline.AI's Join-onto-Join pattern connects them: a parent Join fetches the 128 actions, and a child Join looks up the 15 latest item_embedding values.
# Chain a Join onto a parent Join so each recent user action resolves its item_embedding by listing_id.
recent_actions = Join(
left=user_activities_source,
right_parts=[JoinPart(group_by=user_activities_gb)],
online=True,
version=1,
)
events_col = "user_id_user_event_struct_last128_7d"
enriched_actions_join = Join(
left=JoinSource(
join=recent_actions,
query=Query(selects={
"user_id": "user_id",
events_col: events_col,
**{f"recent_{i}": f"{events_col}[{i - 1}].listing_id" for i in range(1, 16)},
}),
),
right_parts=[
*[
JoinPart(
group_by=item_embedding,
key_mapping={f"recent_{i}": "listing_id"},
prefix=f"recent_{i}",
)
for i in range(1, 16)
],
],
online=True,
version=1,
)Offline, enriched_actions_join reads recent_actions's output table in Spark. Online, the fetcher resolves recent_actions and looks up each recent listing's vector. Slots for users with fewer recent actions return null features without an error.
Step 4. Run the custom action FM (Model + ModelTransforms)
actor_embedding_mt passes enriched_actions_join into our custom action FM on Vertex AI. That endpoint encodes the enriched sequence into a single actor embedding per user event.
# Run the custom action FM on the enriched 128-action sequence to produce an actor embedding.
action_fm = Model(
version="1",
inference_spec=InferenceSpec(
model_backend=ModelBackend.VERTEXAI,
model_backend_params={"model_name": "user-action-fm", "model_type": "custom"},
),
# Pack the 128 actions and the 15 recent item embeddings into the request your endpoint expects.
input_mapping={"instances": "named_struct('actions', user_id_user_event_struct_last128_7d, 'items', array(...))"},
# Response columns are named <team>_<file>_<variable>__<version>__<field>.
output_mapping={"actor_embedding": "gcp_models_action_fm__1__embeddings.values"},
value_fields=[("embeddings", embeddings_schema)],
training_conf=TrainingConf(...),
)
actor_embedding_mt = ModelTransforms(
sources=[JoinSource(join=enriched_actions_join)],
models=[action_fm],
passthrough_fields=["user_id"],
version=1,
)Here action_fm learns from internal logs and sets training_conf, whereas the frozen vendor encoder in step 1 omitted it. With training_conf set, the planner waits for walk-forward model redeploys as new training data lands.
Step 5. Backfill and stream the actor embedding (GroupBy)
After actor_embedding_mt emits an actor embedding per event, a GroupBy keyed by user_id stores the latest vector. Downstream consumers read that stored vector offline and online without re-running the transformer.
# Store each user's latest actor embedding for point-in-time backfills and live streaming serving.
actor_embedding_gb = GroupBy(
sources=[actor_embedding_mt],
keys=["user_id"],
aggregations=[
Aggregation(
input_column="gcp_models_action_fm__1__actor_embedding",
operation=Operation.LAST,
windows=[Window(length=7, time_unit=TimeUnit.DAYS)],
),
],
accuracy=Accuracy.TEMPORAL,
online=True,
version=1,
)Setting Operation.LAST with accuracy=Accuracy.TEMPORAL generates point-in-time historical vectors during Spark backfills. Adding online=True launches the Flink job that writes updated vectors into the online store at write time.
Step 6. Consume the actor embedding in a downstream Join
With fresh vectors stored in actor_embedding_gb, any downstream model adds that GroupBy to its Join. Here checkout_fraud_join combines the actor embedding with tabular velocity and device risk signals.
# Join the user's actor embedding with existing tabular features for the downstream checkout fraud model.
checkout_fraud_join = Join(
left=checkout_events_source,
right_parts=[
JoinPart(group_by=actor_embedding_gb),
JoinPart(group_by=user_payment_velocity_gb),
JoinPart(group_by=device_risk_signals_gb),
],
online=True,
version=1,
)Adding one JoinPart exposes the actor embedding to checkout fraud, and ranking or support joins can share actor_embedding_gb the same way. Those six configs declare the offline and online pipeline in Python.
2. Enforcing the four guarantees in Zipline.AI
Those six objects record lineage edges and time windows explicitly in the dependency graph. Zipline.AI's compiler and runtime read that graph to enforce each guarantee from Part 1.
Point-in-time correctness for features and weights
Preventing future leaks combines timestamp-clamped feature windows with time-pinned model snapshots. Setting accuracy=Accuracy.TEMPORAL on item_embedding, user_activities_gb, and actor_embedding_gb restricts historical joins to data from before each example's timestamp. Declaring training_conf on action_fm coordinates walk-forward snapshots (fm@v1.t2) with the planner. During backfills, the planner waits for each period's retrained model redeploy before embedding later periods.
Training-serving consistency and online serving paths
Sharing one Python graph across batch and online engines keeps live feature vectors aligned with historical training tables. Zipline.AI compiles the configs in section 1 into Spark backfills and provides two online serving paths for ModelTransforms:
- Write-time Flink streaming: Pointing
actor_embedding_gbatactor_embedding_mtwithonline=Truelaunches a Flink job. It chains join enrichment and model inference as async operators with tunable timeouts and capacities (join_enrichment_async_timeout_ms,model_async_timeout_ms). Flink writes updated vectors to the online store as events arrive, and live callers perform a fast key read. - On-demand fetch (
fetchModelTransforms): For synchronous request-time scoring without windowed aggregation, callers invokefetcher.fetchModelTransforms. It fetches parent join features first and calls the model inline. Any model error is recorded in a<model_name>_exceptioncolumn without failing the response.
Versioned, surgical recomputes
Iterating on that shared graph safely starts with versioned column names and static lineage checks before any job runs. Each GroupBy, Join, and ModelTransforms appends __<version> to its entity and output table names, and Model versions appear in output columns like gcp_models_action_fm__1__actor_embedding. Bumping action_fm to version="2" writes gcp_models_action_fm__2__actor_embedding and leaves existing v1 columns untouched while you test v2. If you forget to update actor_embedding_gb's input_column, zipline compile fails locally or in CI with UNRESOLVED_COLUMN and prints the broken lineage tree.
When compilation passes and zipline backfill runs on checkout_fraud_join, Zipline.AI computes a semantic hash (a fingerprint of the full column-level definition) per feature. The engine compares new hashes against existing tables and reuses unchanged columns like user_payment_velocity_gb and device_risk_signals_gb from the prior backfill. Only columns whose semantic hash changed, here the new actor embedding, get recomputed.
Isolated branches with atomic release
Shipping either a version="2" edit or a scheduled fm@v1.t2 snapshot follows one sequence: deploy on a branch, shadow live traffic, and promote atomically. After zipline compile passes on a git branch, zipline deploy spins up isolated batch pipelines, streaming jobs, serving indices, and schedules. Compute sharing is one-way: the branch reads unchanged production tables where possible and never writes back to production.
On that deployed branch, you shadow live traffic before exposing users to changes. The branch pipeline processes live events, updates its isolated serving index, and logs downstream predictions for comparison against production without acting on them. For scheduled snapshot updates where each downstream model pins its training snapshot (fm@v1.t2 feeding m@v1.t3), Zipline.AI also runs the GroupBy upload and semantic-hashed Join backfill across all users. That full refresh overwrites old fm@v1.t1 vectors for inactive accounts.
After shadow logs and an A/B test pass, merging the pull request to main cuts traffic over with zero data downtime. Snapshot fm@v1.t2 (or version="2"), the refreshed embeddings for all users, and the retrained downstream model m@v1.t3 go live together, and schedule-all retires old schedules automatically.
This series started in Part 1 with ordered action sequences and content encoders, and Part 2 showed how walk-forward snapshots prevent weight leakage in backtests. Part 3 covered write-time streaming and pinned snapshot releases, and these six Python configs put the full chain into production in Zipline.AI.