Collaborate on a deployed model

Use the rai models CLI to manage deployed models, collaborate through shared model history, and tear down models safely.

Prerequisites

• You have a model deployed to a Snowflake schema. See Deploy a model.
• You have the PyRel CLI installed and a project raiconfig.yaml configured to connect to the model. See Install and run PyRel and Configure PyRel.

How deployments are tracked

In PyRel 1.28 and later, op log recording is enabled by default. Pulling shared model changes requires op log recording to be enabled. With recording enabled, a successful rai models deploy installs your model’s resources and outputs into the target schema and records the difference between your model and the previously deployed version as a series of operations in the schema’s op log. When recording is explicitly disabled, deploy still installs your model’s resources and outputs, but it records no history, and the shared-model synchronization is unavailable.

The op log is your model’s history: an ordered record of how the model has changed from one deploy to the next. When a deploy records changes, PyRel tells you how many:

Recorded 3 change(s) to the snowflake oplog.

You never edit the op log directly. The rai models commands maintain it for you. Each model keeps its own op log. Deploy appends changes to that history, and rai models pull uses it to synchronize shared changes.

Control op log recording

You do not need to add an oplog section to record history in PyRel 1.28 or later. To deploy the model without recording change history, set oplog.enabled: false in raiconfig.yaml:

oplog:
  enabled: false

oplog is a top-level section, alongside connections, model, and deployment. With recording disabled, rai models deploy installs your model without recording history, and the shared-model synchronization is unavailable. To restore the default, remove the enabled: false override or set oplog.enabled: true.

The rai models commands read oplog.enabled from the raiconfig.yaml that PyRel discovers when the command runs, so set the override there for command-line workflows. For other ways to set it, including from Python, see Configure op log recording.

Select the model you want to manage

Before you deploy, pull, or tear down a model, check the deployment settings in raiconfig.yaml. The public_schema, identity.internal_schema, identity.object_name_prefix, and identity.object_name_suffix settings select the current model and its deployment location. Use the same deployment settings as your collaborators when working on a shared model. See Configure deployment.

Use rai models list to see the models that exist:

rai models list

Collaborate through a shared model

Several developers can work against the same deployed model. The op log becomes the shared deployment history because each deploy appends to it. Every collaborator needs op log recording enabled: rai models pull reconciles shared changes through the op log, and rai models deploy records changes to the shared history only when recording is on. With recording off, pull fails with Oplog recording is disabled (config.oplog.enabled = false), while deploy installs without contributing to the shared history. Op log recording is enabled by default in PyRel 1.28 and later; if it was explicitly disabled, see Control op log recording.

A model has two parts, and they stay in sync in different ways:

• The part you own: the model source you author. You can split it across as many files as you like and name them however you want. The op log records your changes to these entities too, but PyRel does not sync your source for you: you share it and resolve any conflicts the usual way, through version control (for example, git pull). When you deploy owned changes, PyRel reminds you to commit them to source control.
• The shared part: entities contributed through the op log, including by your collaborators. PyRel projects these into a generated file named shared_model.py, written alongside your source. This file becomes part of the same model. It is not a separate, parallel model. PyRel wires it in automatically on deploy and pull. rai models pull keeps it current by regenerating it from the op log, so shared changes are reconciled for you automatically. You normally let PyRel maintain this file, but you can also edit it directly: as long as your copy is up to date, your edits are deployed and pushed to the op log just like a change to your own source.

In short, rai models pull reconciles shared changes for you automatically, while owned changes are yours to manage in version control.

Note that:

The one exception to that automatic sync: if you have hand-edited shared_model.py, neither rai models pull nor rai models deploy will overwrite it unless you pass --force - both regenerate the file and refuse to clobber hand edits. With --force, your current file is backed up to a timestamped shared_model.py.<timestamp>.bak first.

To reference shared entities from your own code:

from shared_model import build_shared

shared = build_shared(m)   # shared.Person, shared.orders, ...

A typical collaboration loop:

1. Pull before you start

   rai models pull

   For command details and options, see rai models pull.

2. Make your changes and deploy

   rai models deploy

   If a collaborator deployed since your last pull, the deploy is refused with a message telling you to pull first. Run rai models pull and deploy again to get back in sync.

Tear down a model

rai models teardown removes the objects that PyRel created for a deployed model. This includes model output objects and meta objects such as the model state, intermediate results, and refresh tasks. It leaves both the public schema and the internal schema in place, along with all the objects in them that were not created by PyRel, other models’ objects, and shared ownership tags.

By default, teardown is a dry run: it prints exactly what would be removed and stops. Re-run with --force to actually perform it.

rai models teardown          # dry run: shows what would be removed
rai models teardown --force  # actually remove them

Note

Teardown never drops the schemas themselves, even with --force. Snowflake offers no way to prove a schema is empty, so dropping one could destroy objects PyRel did not create. If you want the schema gone, you can drop it manually after teardown finishes.

Teardown leaves raiconfig.yaml untouched, so deployment.public_schema still names the model you just tore down. That pointer is now stale: deploying with it again redeploys into the same schema. To target a different model, update the deployment settings in raiconfig.yaml. Teardown also leaves your model source and shared_model.py untouched.

If a deploy, pull, or teardown step does not behave as you expect, use Troubleshoot a deployed model to narrow down the cause.