Implementation:Recommenders team Recommenders Notebook Utils

Knowledge Sources	Recommenders
Domains	Jupyter, Testing, Notebook Execution
Last Updated	2026-02-10 00:00 GMT

Overview

Utilities for Jupyter notebook environment detection, programmatic notebook execution with parameter injection, and metadata storage and retrieval in notebook outputs.

Description

This module provides five functions that support notebook-centric workflows in the Recommenders library:

• is_jupyter detects whether code is running in a Jupyter notebook by checking if get_ipython().__class__.__name__ equals "ZMQInteractiveShell".

• is_databricks detects whether code is running on Databricks by checking if the current working directory is "/databricks/driver".

• execute_notebook enables programmatic execution of Jupyter notebooks with parameter injection. It loads a notebook via nbformat, finds code cells tagged with "parameters" in their metadata, replaces parameter values using regex substitution (via the internal _update_parameters helper), executes the notebook using ExecutePreprocessor, and saves the result to an output path.

• store_metadata embeds named key-value pairs into notebook cell outputs using IPython's display() function with a custom MIME type (application/notebook_utils.json+json). This enables extraction of computed values from executed notebooks.

• read_notebook loads an executed notebook and extracts all stored metadata by scanning cell outputs for the custom MIME type, returning a dictionary of name-value pairs.

The internal _update_parameters helper uses regex pattern matching to replace parameter assignments in cell source code, handling both string and non-string values appropriately.

Usage

Use execute_notebook for automated testing and CI pipelines to run example notebooks with modified parameters (e.g., smaller datasets or fewer epochs). Use store_metadata and read_notebook to extract metrics or results from executed notebooks for validation. Use is_jupyter and is_databricks to adapt code behavior based on the execution environment.

Code Reference

Source Location

• Repository: Recommenders
• File: recommenders/utils/notebook_utils.py
• Lines: 1-152

Signature

def is_jupyter()

def is_databricks()

def execute_notebook(input_notebook, output_notebook, parameters={}, kernel_name="python3", timeout=2200)

def store_metadata(name, value)

def read_notebook(path)

Import

from recommenders.utils.notebook_utils import (
    is_jupyter,
    is_databricks,
    execute_notebook,
    store_metadata,
    read_notebook,
)

I/O Contract

Inputs

execute_notebook

Name	Type	Required	Description
input_notebook	str	Yes	Path to the input Jupyter notebook
output_notebook	str	Yes	Path where the executed notebook will be saved
parameters	dict	No	Dictionary of parameter name-value pairs to inject into cells tagged with "parameters" (default: {})
kernel_name	str	No	Jupyter kernel name to use for execution (default: "python3")
timeout	int	No	Timeout in seconds for each cell execution (default: 2200)

store_metadata

Name	Type	Required	Description
name	str	Yes	Name/key for the stored data
value	int, float, or str	Yes	Value to store in the notebook output

read_notebook

Name	Type	Required	Description
path	str	Yes	Path to the executed notebook to read metadata from

Outputs

Name	Type	Description
return (is_jupyter)	bool	True if running in a Jupyter notebook, False otherwise
return (is_databricks)	bool	True if running on Databricks, False otherwise
return (read_notebook)	dict	Dictionary of name-value pairs extracted from notebook cell outputs

Usage Examples

Basic Usage

from recommenders.utils.notebook_utils import execute_notebook, read_notebook, store_metadata

# Execute a notebook with custom parameters for testing
execute_notebook(
    input_notebook="examples/sar_quickstart.ipynb",
    output_notebook="output/sar_quickstart_test.ipynb",
    parameters={"TOP_K": 5, "MOVIELENS_DATA_SIZE": "100k"},
    kernel_name="python3",
    timeout=600,
)

# Read metrics stored in an executed notebook
results = read_notebook("output/sar_quickstart_test.ipynb")
print(results)  # e.g., {"precision": 0.32, "recall": 0.18}

# Inside a notebook cell, store a metric for later retrieval
store_metadata("precision_at_k", 0.326)