trulens-notebook-execution

TruLens Notebook Execution

Execute Jupyter notebooks, display progress to the user, and handle API key requirements.

When to Use This Skill

Use this skill when:

• Running TruLens quickstart or example notebooks
• Demonstrating TruLens functionality via notebooks
• Testing notebook examples end-to-end
• User asks to "run the notebook" or "execute the notebook"

Execution Method

Always use jupyter nbconvert --execute to run notebooks. This:

• Maintains state across cells (variables persist)
• Captures all output properly
• Handles async operations correctly
• Works with OTEL tracing

DO NOT try to run notebooks by:

• Extracting cells and running them individually in bash
• Using python -c with heredocs
• Running as a standalone Python script (loses notebook context)

Basic Execution Command

jupyter nbconvert --to notebook --execute --inplace <notebook_path>

Execution with Timeout (for long-running notebooks)

jupyter nbconvert --to notebook --execute --inplace \
  --ExecutePreprocessor.timeout=600 \
  <notebook_path>

Execution with Output to stdout

jupyter nbconvert --to notebook --execute --stdout <notebook_path>

Displaying Progress to User

When running a notebook, display section headers as each cell executes - NOT generic "BASH_OUTPUT" messages.

Step 1: Parse the Notebook Structure First

Before executing, read the notebook JSON to build a map of:

• Markdown headers (## Section Name)
• Which code cells belong to which section

import json

with open("notebook.ipynb") as f:
    nb = json.load(f)

sections = []
current_section = "Setup"

for i, cell in enumerate(nb["cells"]):
    if cell["cell_type"] == "markdown":
        source = "".join(cell["source"])
        # Extract header
        for line in source.split("\n"):
            if line.startswith("## "):
                current_section = line.replace("## ", "").strip()
    sections.append((i, current_section))