Overview

Prerequisites

What You'll Learn

What You'll Need

What You'll Build

Environment Setup

Clone the Repository

git clone https://github.com/Snowflake-Labs/sf-hcls-solutions.git
cd sf-hcls-solutions/solutions/scientific-workbench

Install Snowflake CLI

pip install snowflake-cli

Configure a Connection

snow connection add \
  --connection-name workbench-deploy \
  --account <your-account> \
  --user <your-user> \
  --role ACCOUNTADMIN \
  --warehouse COMPUTE_WH

snow connection test --connection workbench-deploy

Obtain NVIDIA API Key

Quick Start (One Command)

bash deploy.sh --connection workbench-deploy --nvidia-key <your-nvidia-key>

SWB_ASSUME_YES=1 bash deploy.sh --connection workbench-deploy --nvidia-key <your-nvidia-key>

Configuration File (Optional)

cp workbench.config.yaml.example workbench.config.yaml

snowflake:
  # Snowflake CLI connection name from ~/.snowflake/config.toml
  connection: default

secrets:
  # NVIDIA API key from build.nvidia.com (for hosted NIM API calls)
  nvidia_api_key: ""
  # NGC API key from ngc.nvidia.com (for SPCS NIM container weight downloads)
  ngc_api_key: ""

databases:
  workbench: SCIENTIFIC_WORKBENCH      # Platform database
  reference: WORKBENCH_REFERENCE       # Read-only reference data
  projects: WORKBENCH_PROJECTS         # Per-project schemas

warehouses:
  xs: WORKBENCH_XS                     # Lightweight queries, admin tasks
  small: WORKBENCH_S                   # Tool execution, data loading
  ml: WORKBENCH_ML                     # Heavy ML workloads, large data scans

# Enable specific NIM containers on SPCS GPU compute pools
nim_services:
  boltz2: false                        # L40S GPU required
  genmol: false                        # A10G GPU sufficient
  diffdock: false                      # L40S GPU required
  rfdiffusion: false                   # L40S GPU required
  proteinmpnn: false                   # A10G GPU sufficient
  molmim: false                        # A10G GPU sufficient
  openfold2: false                     # A10G GPU sufficient
  openfold3: false                     # L40S GPU required
  msa_search: false                    # A10G + 500 GiB block volume

agents:
  deploy_legacy_sql: true              # Deploy agents via SQL scripts
  deploy_agent_studio: true            # Deploy agents via Agent Studio YAML

marketplace:
  pubmed_cke: false                    # Set true if PubMed CKE is subscribed
  clinicaltrials_cke: false            # Set true if ClinicalTrials.gov CKE is subscribed

bash deploy.sh --config workbench.config.yaml

bash scripts/validate-config.sh

deploy.sh Reference

Teardown

bash scripts/teardown.sh --connection workbench-deploy -y

Deploy Infrastructure

Phase 1: Run Infrastructure Scripts

Database Layout

SCIENTIFIC_WORKBENCH          -- Platform database
  CATALOG                     -- Tool registry, assets, agents, chat sessions
  WORKFLOWS                   -- Workflow templates and run history
  GOVERNANCE                  -- Promotion log, canary assertions
  PROVENANCE                  -- Provenance audit trail
  PROJECTS                    -- Shared project space

WORKBENCH_REFERENCE           -- Read-only reference data
  GENOMICS                    -- HGNC gene nomenclature
  CHEMBL                      -- Bioactivity measurements
  CLINICAL                    -- ClinicalTrials.gov
  PATHWAYS                    -- Reactome, MSigDB, GO
  PROTEIN                     -- UniProt entries

WORKBENCH_PROJECTS            -- Per-project schemas
  DEMO_NSCLC                  -- NSCLC patient cohort demo
  DEMO_COMPOUNDS              -- Compound screening demo
  DEMO_CLINICAL               -- Clinical trials demo
  DEMO_STRUCTURAL             -- Protein targets demo

RBAC Roles

Verify Infrastructure

-- Check databases exist
SHOW DATABASES LIKE 'SCIENTIFIC_WORKBENCH';
SHOW DATABASES LIKE 'WORKBENCH_REFERENCE';
SHOW DATABASES LIKE 'WORKBENCH_PROJECTS';

-- Check roles
SHOW ROLES LIKE 'WORKBENCH_%';

-- Check external access integrations
SHOW EXTERNAL ACCESS INTEGRATIONS LIKE 'NVIDIA_%';

Deploy NIMs on SPCS

Prerequisites for SPCS NIMs

GPU Requirements

Compute Pools

-- Already created by 02-warehouses.sql:
-- NIM_GPU_A10G_POOL: GPU_NV_S (A10G 24 GiB) — GenMol, ProteinMPNN, MolMIM, OpenFold2
-- NIM_GPU_L40S_POOL: GPU_L40S_G1_16 (L40S 48 GiB) — Boltz-2, DiffDock, RFdiffusion, OpenFold3

-- Verify pools exist
SHOW COMPUTE POOLS LIKE 'NIM_GPU_%';

Step 1: Mirror NIM Images

bash deploy.sh --connection workbench-deploy \
  --nvidia-key <your-nvidia-key> \
  --ngc-key <your-ngc-key> \
  --mirror-nims

# Login to NGC registry
docker login nvcr.io -u '$oauthtoken' -p <your-ngc-key>

# Login to Snowflake image registry
snow spcs image-registry login --connection workbench-deploy

# Get your Snowflake registry URL
REPO_URL=$(snow sql --connection workbench-deploy \
  --query "SHOW IMAGE REPOSITORIES IN SCHEMA SCIENTIFIC_WORKBENCH.CATALOG" \
  --format json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print([r['repository_url'] for r in data if 'nim_gpu_images' in r.get('repository_url','').lower()][0])
")

# Mirror Boltz-2 (example — repeat for each NIM)
docker pull nvcr.io/nim/mit/boltz2:1.8.0
docker tag nvcr.io/nim/mit/boltz2:1.8.0 $REPO_URL/boltz2:1.8.0
docker push $REPO_URL/boltz2:1.8.0

docker pull --platform linux/amd64 nvcr.io/nim/mit/boltz2:1.8.0

Step 2: Create SPCS Services

USE DATABASE SCIENTIFIC_WORKBENCH;
USE SCHEMA CATALOG;

CREATE SERVICE SCIENTIFIC_WORKBENCH.CATALOG.NIM_BOLTZ2_SVC
  IN COMPUTE POOL NIM_GPU_L40S_POOL
  FROM SPECIFICATION $$
spec:
  containers:
    - name: boltz2
      image: /SCIENTIFIC_WORKBENCH/CATALOG/NIM_GPU_IMAGES/boltz2:1.8.0
      env:
        NIM_HTTP_API_PORT: "8000"
        NIM_LOG_LEVEL: "INFO"
      secrets:
        - snowflakeSecret: SCIENTIFIC_WORKBENCH.CATALOG.NGC_API_KEY
          secretKeyRef: SECRET_STRING
          envVarName: NGC_API_KEY
      volumeMounts:
        - name: dshm
          mountPath: /dev/shm
      resources:
        requests:
          nvidia.com/gpu: 1
          memory: 32Gi
        limits:
          nvidia.com/gpu: 1
          memory: 90Gi
      readinessProbe:
        port: 8000
        path: /v1/health/ready
  endpoints:
    - name: boltz2
      port: 8000
      public: true
  volumes:
    - name: dshm
      source: memory
      size: 16Gi
  $$
  EXTERNAL_ACCESS_INTEGRATIONS = (NIM_RUNTIME_EAI)
  MIN_INSTANCES = 1
  MAX_INSTANCES = 1;

Step 3: Verify Service Health

-- Check service status
SELECT SYSTEM$GET_SERVICE_STATUS('SCIENTIFIC_WORKBENCH.CATALOG.NIM_BOLTZ2_SVC');

-- View container logs
SELECT SYSTEM$GET_SERVICE_LOGS('SCIENTIFIC_WORKBENCH.CATALOG.NIM_BOLTZ2_SVC', 0, 'boltz2', 50);

-- Check endpoint URL
SHOW ENDPOINTS IN SERVICE SCIENTIFIC_WORKBENCH.CATALOG.NIM_BOLTZ2_SVC;

Endpoint Path Reference

curl http://<service-endpoint>:8000/openapi.json | python3 -m json.tool | grep '"paths"' -A 20

Cost Management

-- Suspend a service (stops GPU billing)
ALTER SERVICE SCIENTIFIC_WORKBENCH.CATALOG.NIM_BOLTZ2_SVC SUSPEND;

-- Resume when needed
ALTER SERVICE SCIENTIFIC_WORKBENCH.CATALOG.NIM_BOLTZ2_SVC RESUME;

Special Cases

Load Reference Data

Phase 2: Reference Data

# If deploying manually, run these scripts:
# scripts/04-reference-data.sql (schema setup)
# data/loaders/load_chembl.sql
# data/loaders/load_remaining.sql
# data/synthetic/load_synthetic_data.sql

Data Domains

Verify Data Loading

-- Check row counts across reference schemas
SELECT TABLE_SCHEMA, TABLE_NAME, ROW_COUNT
FROM WORKBENCH_REFERENCE.INFORMATION_SCHEMA.TABLES
WHERE TABLE_SCHEMA IN ('GENOMICS', 'CHEMBL', 'CLINICAL', 'PATHWAYS', 'PROTEIN')
  AND TABLE_TYPE = 'BASE TABLE'
ORDER BY TABLE_SCHEMA, TABLE_NAME;

Register Tools

Tool Taxonomy

How Tools Are Structured

CREATE OR REPLACE PROCEDURE CATALOG.MY_TOOL(...)
RETURNS VARCHAR
LANGUAGE PYTHON
...
COMMENT = 'TOOL:{"display_name":"My Tool","description":"...","domains":"genomics","params":{...},"return_type":"VARCHAR","example":"CALL CATALOG.MY_TOOL(...)"}'
AS $$
...
$$;

CALL CATALOG.REGISTER_TOOL(
  'my_tool',                                    -- name (unique)
  'My Tool',                                    -- display_name
  'Description of what the tool does.',         -- description
  'genomics,drug-discovery',                    -- domains (comma-separated)
  'procedure',                                  -- tool_type
  'SCIENTIFIC_WORKBENCH.CATALOG.MY_TOOL',       -- function_reference
  '{"param1":"STRING","param2":"INT"}',         -- parameters (JSON)
  'VARCHAR',                                    -- return_type
  'CALL CATALOG.MY_TOOL(''value'', 42)'         -- example_usage
);

NVIDIA BioNeMo NIM Tools

Verify Tool Registration

SELECT tool_type, COUNT(*) AS count
FROM SCIENTIFIC_WORKBENCH.CATALOG.TOOLS
WHERE status = 'active'
GROUP BY tool_type
ORDER BY count DESC;

-- Expected: 28 total active tools
SELECT COUNT(*) AS total_active_tools
FROM SCIENTIFIC_WORKBENCH.CATALOG.TOOLS
WHERE status = 'active';

Configure AI Services

Cortex Search and Governance

Semantic Views (Cortex Analyst)

Agent Architecture

                    DISCOVERY_AGENT
                    (user-facing)
                         |
               uses semantic views +
               search + code execution
                         |
                  ORCHESTRATOR_AGENT
                  (routes to domains)
                   /     |     \
        GENOMICS   CHEMISTRY  STRUCTURAL
         AGENT      AGENT      AGENT
           |          |          |
        5 tools    4 tools    9 tools
                         |
                   CLINICAL_AGENT
                   (4 semantic views)

Verify Agent Configuration

-- Test the Discovery Agent with a simple query
SELECT SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
  'SCIENTIFIC_WORKBENCH.CATALOG.DISCOVERY_AGENT',
  '{"query": "What tools are available for protein structure prediction?"}',
  TRUE
) AS response;

Deploy the Application

SAR Deployment

cd solutions/scientific-workbench/app
snow app deploy --connection workbench-deploy

App ready at https://<hash>-<account>.snowflakecomputing.app

Grant Access to Users

-- Scientists can use the app
GRANT USAGE ON APPLICATION SERVICE SCIENTIFIC_WORKBENCH_APP
  TO ROLE WORKBENCH_SCIENTIST;

-- Viewers get read-only access
GRANT USAGE ON APPLICATION SERVICE SCIENTIFIC_WORKBENCH_APP
  TO ROLE WORKBENCH_VIEWER;

App Modules

Verify Deployment

Local Development

Setup

cd solutions/scientific-workbench/app
npm install

Environment Variables

# Option 1: Key-pair auth (recommended)
SNOWFLAKE_ACCOUNT=<account>
SNOWFLAKE_USER=<user>
SNOWFLAKE_PRIVATE_KEY_PATH=~/.snowflake/rsa_key.p8
SNOWFLAKE_WAREHOUSE=WORKBENCH_XS
SNOWFLAKE_ROLE=WORKBENCH_ADMIN

# Option 2: config.toml (zero config — uses default connection)
# No env vars needed if ~/.snowflake/config.toml is configured

# Enable admin features in local dev
SWB_LOCAL_DEV_ADMIN=true

Run the Dev Server

npm run dev

Key Differences from SPCS

Testing Changes

npx tsc --noEmit       # Type checking
npx next build         # Full production build

Run a Discovery Workflow

Open the Chat

Example: Multi-Step Drug Discovery

Find compounds in ChEMBL that target EGFR with IC50 below 100 nM, validate their drug-likeness, and predict binding poses for the top 3 candidates against PDB structure 1M17.

Example: Genomics Analysis

Run differential expression analysis comparing Stage I vs Stage III patients in the NSCLC cohort, then perform pathway enrichment on the upregulated genes.

Example: Protein Structure Prediction

Predict the structure of the first 200 residues of human TP53 protein and assess confidence.

View Results

Extend the Platform

Adding a New Native Tool

CREATE OR REPLACE PROCEDURE CATALOG.MY_NEW_TOOL(
    "P_INPUT" VARCHAR,
    "P_OUTPUT_TABLE" VARCHAR
)
RETURNS VARCHAR
LANGUAGE PYTHON
RUNTIME_VERSION = '3.11'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'run'
COMMENT = 'TOOL:{"display_name":"My New Tool","description":"What it does","domains":"genomics","params":{"input":"STRING","output_table":"STRING"},"return_type":"VARCHAR","example":"CALL CATALOG.MY_NEW_TOOL(input, output)"}'
AS $$
import json

def run(session, p_input: str, p_output_table: str) -> str:
    # Your tool logic here
    result = {"status": "success", "output_table": p_output_table}
    return json.dumps(result)
$$;

CALL CATALOG.REGISTER_TOOL(
    'my_new_tool', 'My New Tool',
    'What it does',
    'genomics', 'procedure',
    'SCIENTIFIC_WORKBENCH.CATALOG.MY_NEW_TOOL',
    '{"input":"STRING","output_table":"STRING"}',
    'VARCHAR',
    'CALL CATALOG.MY_NEW_TOOL(''test'', ''RESULTS.OUTPUT'')'
);

CALL CATALOG.SEED_ASSETS();

Adding a New NIM Wrapper

Custom Tool Onboarding

Adding Reference Data

INSERT INTO SCIENTIFIC_WORKBENCH.CATALOG.ASSETS
    (asset_id, asset_name, asset_type, description, domain, schema_name, owner)
VALUES
    ('asset-data-WORKBENCH_REFERENCE.MY_SCHEMA.MY_TABLE',
     'MY_TABLE', 'dataset', 'Description of the dataset',
     'MY_SCHEMA', 'MY_SCHEMA', CURRENT_USER());

Security Model

Platform Roles and Hierarchy

SYSADMIN
  └── WORKBENCH_ADMIN       (full platform administration)
        └── WORKBENCH_SCIENTIST   (run tools, execute workflows, share results)
              └── WORKBENCH_VIEWER      (read-only access to results and catalog)

Access Control by Schema

Scientific Personas

Assigning Roles to Users

-- Grant a scientist role to a user
GRANT ROLE WORKBENCH_SCIENTIST TO USER jane_doe;

-- Grant admin role
GRANT ROLE WORKBENCH_ADMIN TO USER platform_admin;

-- Grant viewer role
GRANT ROLE WORKBENCH_VIEWER TO USER manager_smith;

USE ROLE WORKBENCH_SCIENTIST;

Named Query Allowlist

Client: { query: "column_info", params: { schema: "GENOMICS", table: "HGNC_GENES" } }
                                    |
                              resolveNamedQuery()
                                    |
Server: SELECT COLUMN_NAME, DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS
        WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
        binds: ['GENOMICS', 'HGNC_GENES']

Authorization Patterns

// Check caller's role via SPCS user token
const [row] = await querySnowflake("SELECT CURRENT_ROLE() AS role", { callersRights: true })
const callerRole = String(row?.ROLE ?? "").toUpperCase()

if (!ALLOWED_ROLES.has(callerRole)) {
  return Response.json({ error: "Forbidden" }, { status: 403 })
}

External Access Integrations

Conclusion and Resources

What You Learned

Related Resources