Migration Guide¶

This guide covers breaking changes and new features for each SDK version, with before/after code examples and migration checklists.

Current Version: 1.61.x¶

The latest stable release. See the sections below to migrate from earlier versions.

Upgrading from 1.53.x to 1.54.x¶

New Features¶

Button Tertiary Style and Extended Colors

Buttons now support a TERTIARY style (chip-like appearance) and 15 color options beyond the original three.

from virtualitics_sdk import Button, ButtonStyle, ButtonColor

# New tertiary style with rounded corners
button = Button(
    title="Tag",
    style=ButtonStyle.TERTIARY,
    color=ButtonColor.PURPLE,
    rounded=True
)

New colors: AMBER, BLUE, CYAN, FUCHSIA, GREEN, GRASS, INDIGO, ORANGE, PURPLE, RED, TEAL, VIOLET, YELLOW (in addition to the existing ACCENT, NEUTRAL, ALERT).

GridColumn Value Options

Editable table columns can now provide value_options for single-select dropdowns within cells.

Breaking Changes¶

None.

Action Required¶

Update requirements.txt: virtualitics-sdk>=1.54.0
No code changes required

Upgrading from 1.52.x to 1.53.x¶

New Features¶

Table Row Selection APIs

Tables now expose a TableSelectionType enum and support programmatic row selection through StoreInterface.

from virtualitics_sdk import Table, TableSelectionType

table = Table(
    id="my_table",
    data=df,
    selection_type=TableSelectionType.MULTIPLE
)

SegmentedControl Improvements

Configurable controls position and max width
Label ellipsis for long labels

Breaking Changes¶

None.

Action Required¶

Update requirements.txt: virtualitics-sdk>=1.53.0

Upgrading from 1.51.x to 1.52.x¶

New Features¶

SegmentedControl Element

A new element for creating tabbed/segmented views within a card.

from virtualitics_sdk import SegmentedControl
from virtualitics_sdk.page.card import Segment

segment1 = Segment(label="Overview")
segment1.add_content([table, plot])

segment2 = Segment(label="Details")
segment2.add_content([detail_table])

control = SegmentedControl(
    id="my_tabs",
    title="Views",
    segments=[segment1, segment2],
    active_segment_index=0
)

SingletonApp

A new app type for apps that should only have one active instance at a time.

from virtualitics_sdk import SingletonApp

app = SingletonApp(
    name="Live Monitor",
    description="Single-instance monitoring dashboard"
)

Trigger System

A new module for automatically spawning flows based on external events:

S3Trigger — monitor S3 buckets for new files
AssetTrigger — monitor asset uploads/changes
PostgresTrigger — monitor database table changes
CompositeTrigger — combine multiple triggers

from virtualitics_sdk.triggers import S3Trigger

trigger = S3Trigger(
    bucket="my-bucket",
    prefix="data/",
    callback=my_trigger_callback
)

Breaking Changes¶

None.

Action Required¶

Update requirements.txt: virtualitics-sdk>=1.52.0

Upgrading from 1.50.x to 1.51.x¶

Breaking Changes¶

Major Breaking Change

CustomEvent has been fully removed. All CustomEvent subclasses are gone. Use Button with the new callback system instead.

Removed classes:

CustomEvent
AssetDownloadCustomEvent
TriggerFlowCustomEvent
CustomEventType
CustomEventPosition

Removed row action classes:

UpdateRowAction
UpdateRedirectRowAction
RedirectRowAction

Migration: CustomEvent to Button¶

Before (v1.50 and earlier):

from virtualitics_sdk import CustomEvent

event = CustomEvent(
    title="Run Analysis",
    on_click=my_callback
)

After (v1.51+):

from virtualitics_sdk import Button, ButtonStyle, ButtonColor
from virtualitics_sdk.types.callbacks import standard_event_callback

@standard_event_callback
async def my_callback(store_interface):
    # your logic here
    return "Analysis complete!"

button = Button(
    title="Run Analysis",
    label="Run Analysis",
    style=ButtonStyle.PRIMARY,
    color=ButtonColor.ACCENT,
    on_click=my_callback
)

Migration: AssetDownloadCustomEvent to Button¶

Before:

from virtualitics_sdk import AssetDownloadCustomEvent

download = AssetDownloadCustomEvent(
    title="Download Report",
    asset=my_asset
)

After:

from virtualitics_sdk import Button
from virtualitics_sdk.types.callbacks import AssetDownloadCallback

button = Button(
    title="Download Report",
    label="Download Report",
    on_click=AssetDownloadCallback(),
    asset=my_asset,
    extension=".csv",
    mime_type="text/csv"
)

Migration: Row Actions¶

Before:

from virtualitics_sdk import Table, UpdateRowAction

table = Table(
    data=df,
    row_actions=[UpdateRowAction(title="Edit", ...)]
)

After:

from virtualitics_sdk import Table
from virtualitics_sdk.types.callbacks import page_update_callback

@page_update_callback
async def edit_row(store_interface):
    # handle row edit
    pass

# Row actions now use the callback system

Action Required¶

Replace all CustomEvent imports with Button + callbacks
Replace AssetDownloadCustomEvent with Button + AssetDownloadCallback
Replace TriggerFlowCustomEvent with Button + trigger_flow_execution
Update row actions to use callback-based pattern
Remove all imports of deleted classes
Update requirements.txt: virtualitics-sdk>=1.51.0

Upgrading from 1.49.x to 1.50.x¶

Breaking Changes¶

None. This release contained performance improvements and minor bug fixes.

Action Required¶

Update requirements.txt: virtualitics-sdk>=1.50.0

Upgrading from 1.48.x to 1.49.x¶

Breaking Changes¶

Major Breaking Change

The callback system has been overhauled. All callbacks must now be async functions decorated with one of the new callback decorators.

Old callback signature (v1.48):

def my_callback(store_interface: StoreInterface, **step_clients) -> str:
    return "Done"

New callback signature (v1.49+):

from virtualitics_sdk.types.callbacks import standard_event_callback

@standard_event_callback
async def my_callback(store_interface: StoreInterface) -> str:
    return "Done"

New Callback Decorators¶

Decorator	Purpose	Return Type
`@standard_event_callback`	Toast notification, no page re-render	`str`
`@page_update_callback`	Modify page elements, auto re-render	`None`
`@drilldown_callback(type, size)`	Open modal or popover	`None`
`@auto_refresh_callback(rate)`	Periodic page refresh	`dict`

New Callback Classes¶

Class	Purpose
`ContainerToggleCallback(visible, container_id)`	Toggle Container visibility
`AssetDownloadCallback()`	Trigger file download

New Features¶

Container Element

A new Card subclass that can be shown/hidden via ContainerToggleCallback.

from virtualitics_sdk import Container, Button
from virtualitics_sdk.types.callbacks import ContainerToggleCallback

container = Container(id="details", title="Details", visible=False)
container.add_content([RichText("Hidden content")])

toggle = Button(
    title="Show",
    on_click=ContainerToggleCallback(visible=True, container_id="details")
)

Table Column Grouping

Group related columns under a shared header.

from virtualitics_sdk.elements.table import ColumnGroup, ColumnField

grouping = [
    ColumnGroup(
        group_id="personal",
        children=[
            ColumnField(field="firstName"),
            ColumnField(field="lastName")
        ]
    )
]

table = Table(data=df, column_grouping=grouping)

Action Required¶

Convert all callback functions to async
Add appropriate decorator to each callback (@standard_event_callback, @page_update_callback, etc.)
Remove **step_clients from callback signatures
Update requirements.txt: virtualitics-sdk>=1.49.0

Upgrading from 1.47.x to 1.48.x¶

Breaking Changes¶

None.

New Features¶

Enhanced table column options
Improved LLM integration
Additional input validation

Action Required¶

Update requirements.txt: virtualitics-sdk>=1.48.0

Upgrading from 1.46.x to 1.47.x¶

Breaking Changes¶

The Step.action() method signature changed to include flow_metadata.

Before:

def action(self):
    pass

After:

def action(self, flow_metadata):
    pass

Action Required¶

Update all action() method signatures to accept flow_metadata
Update requirements.txt: virtualitics-sdk>=1.47.0

Quick Migration Checklist (1.48 to 1.54)¶

If migrating from v1.48 directly to v1.54, here is a combined checklist:

Convert all callbacks to async with decorators (v1.49)
Remove **step_clients from callback signatures (v1.49)
Replace all CustomEvent with Button + callbacks (v1.51)
Replace AssetDownloadCustomEvent with Button + AssetDownloadCallback (v1.51)
Replace TriggerFlowCustomEvent with Button + trigger_flow_execution (v1.51)
Update row actions to callback-based pattern (v1.51)
Remove all imports of deleted classes (v1.51)
Update requirements.txt: virtualitics-sdk>=1.54.0
Consider adopting new features: Container, SegmentedControl, SingletonApp, triggers, expanded button colors

Best Practices¶

Test in staging: Always test migrations in a staging environment first
Pin versions: Pin SDK version in requirements.txt until ready to upgrade
Incremental upgrades: Upgrade one major version at a time when possible
Check imports: Search for removed class names after upgrading
Run your app: Verify all steps execute correctly after migration