Skip to content

Getting Started

This guide will walk you through creating your first Virtualitics SDK app from scratch.

Prerequisites

Before you begin, ensure you have:

  • Python 3.11 or later
  • The Virtualitics AI Platform installed (via Docker or deployed instance)
  • Basic familiarity with Python

Installation

The Virtualitics SDK is bundled with the Virtualitics AI Platform — no separate install is required when developing apps that ship to a deployed platform.

Install the CLI (Optional)

For uploading apps to the platform:

pip install virtualitics-cli

Your First App

Let's create a simple data analysis app that loads a dataset and displays it in a table.

Step 1: Import Required Components

from virtualitics_sdk import (
    App,
    Step,
    StepType,
    Page,
    Section,
    Card,
    Table,
    Dataset,
    RichText
)
import pandas as pd

Step 2: Create a Data Loading Step

class LoadDataStep(Step):
    """Step to load and display a dataset."""

    def run(self, flow_metadata):
        # Create a sample dataset
        data = pd.DataFrame({
            'Product': ['Widget A', 'Widget B', 'Widget C'],
            'Sales': [1200, 800, 1500],
            'Region': ['North', 'South', 'East']
        })

        # Convert to Dataset
        dataset = Dataset(
            name="Sales Data",
            data=data
        )

        # Store in link for next steps
        self._outLink.dataset = dataset

        # Create the page with a table
        return Page(
            title="Data Overview",
            sections=[
                Section(
                    title="Sales Dataset",
                    cards=[
                        Card(
                            title="Data Table",
                            content=[
                                Table(data=data)
                            ]
                        )
                    ]
                )
            ]
        )

Step 3: Create the App

# Initialize the app
my_app = App(
    name="Sales Dashboard",
    description="A simple sales data viewer",
    is_shareable=True
)

# Create the step instance
load_step = LoadDataStep(
    title="Load Data",
    description="Load and display sales data",
    parent="Data",
    type=StepType.RESULTS,
    page=Page(title="Loading...", sections=[])
)

# Add step to app
my_app.chain([load_step])

Step 4: Project Structure

Organize your app as a Python module:

my_first_app/
├── __init__.py
├── app.py          # Your app definition
└── requirements.txt

__init__.py: 

from .app import my_app

__all__ = ['my_app']

requirements.txt: 

virtualitics-sdk>=1.54.0
pandas>=2.0.0

Step 5: Deploy Your App

Option A: Local Development

  1. Add your project to the PROJECTS_LIST environment variable
  2. Mount the directory in docker-compose.yml
  3. Restart the platform
# docker-compose.yml
services:
  backend:
    volumes:
      - ./my_first_app:/opt/app-root/src/my_first_app
    environment:
      - PROJECTS_LIST=["predict_demos", "my_first_app"]

Option B: Upload via CLI

# Package your app
cd my_first_app
python -m build

# Upload to platform
virtualitics-cli upload dist/my_first_app-1.0.0-py3-none-any.whl \
  --host https://your-platform.com \
  --username your-username

Adding More Steps

Let's add a visualization step:

from virtualitics_sdk import PlotlyPlot
import plotly.express as px

class VisualizeStep(Step):
    """Step to create visualizations."""

    def run(self, flow_metadata):
        # Get data from previous step
        dataset = self._inLink.dataset
        df = dataset.data

        # Create a bar chart
        fig = px.bar(
            df,
            x='Product',
            y='Sales',
            color='Region',
            title='Sales by Product'
        )

        return Page(
            title="Visualizations",
            sections=[
                Section(
                    title="Sales Analysis",
                    cards=[
                        Card(
                            title="Sales Chart",
                            content=[
                                PlotlyPlot(figure=fig)
                            ]
                        )
                    ]
                )
            ]
        )

# Create and add the step
viz_step = VisualizeStep(
    title="Visualize",
    description="Create sales visualizations",
    parent="Analysis",
    type=StepType.DASHBOARD,
    page=Page(title="Loading...", sections=[])
)

# Update app with both steps
my_app.chain([load_step, viz_step])

Adding User Inputs

Make your app interactive with input elements:

from virtualitics_sdk import SingleDropdown

class FilterStep(Step):
    """Step with user input."""

    def run(self, flow_metadata):
        # Get data
        dataset = self._inLink.dataset
        df = dataset.data

        # Create dropdown for region selection
        region_dropdown = SingleDropdown(
            title="Select Region",
            id="region_filter",
            options=df['Region'].unique().tolist(),
            default=df['Region'].iloc[0]
        )

        return Page(
            title="Filter Data",
            sections=[
                Section(
                    title="Filters",
                    cards=[
                        Card(
                            title="Select Region",
                            content=[region_dropdown]
                        )
                    ]
                )
            ]
        )

    def action(self, flow_metadata):
        """Handle user input."""
        # Get selected region
        selected_region = self.page.get_element_by_id("region_filter").value

        # Filter dataset
        dataset = self._inLink.dataset
        filtered_df = dataset.data[dataset.data['Region'] == selected_region]

        # Store filtered data
        self._outLink.filtered_dataset = Dataset(
            name=f"Sales Data - {selected_region}",
            data=filtered_df
        )

        # Update page
        return Page(
            title="Filtered Data",
            sections=[
                Section(
                    title=f"Sales in {selected_region}",
                    cards=[
                        Card(
                            title="Filtered Results",
                            content=[
                                Table(data=filtered_df)
                            ]
                        )
                    ]
                )
            ]
        )

Best Practices

  1. Organize Your Steps: Group related functionality into logical steps
  2. Use Type Hints: Make your code more maintainable
  3. Handle Errors: Validate inputs and handle edge cases
  4. Document Your Code: Add docstrings to classes and methods
  5. Test Locally: Verify your app works before deploying
  6. Use Links: Pass data between steps via _inLink and _outLink

Next Steps

Now that you've created your first app:

Common Issues

App Not Appearing

  • Verify PROJECTS_LIST includes your module
  • Check backend logs for import errors
  • Ensure your module has an __init__.py

Data Not Persisting Between Steps

  • Store data in self._outLink
  • Retrieve from self._inLink in subsequent steps
  • Use Dataset, Model, or other Asset types

UI Not Updating

  • Return a new Page from action() method
  • Ensure element IDs are unique
  • Check browser console for errors

Get Help