Implementation:Interpretml Interpret StitchWidget

Knowledge Sources	Interpretml Interpret
Domains	Visualization, Jupyter_Widgets, Python
Last Updated	2026-02-07 12:00 GMT

Overview

Python backend class for the Stitch Jupyter widget that provides bidirectional communication between the Jupyter kernel and a sandboxed iframe via synchronized Unicode traits.

Description

The StitchWidget class extends ipywidgets.DOMWidget to serve as the Python-side counterpart of the TypeScript StitchModel/StitchView. It defines six synchronized traits that mirror the frontend model:

kernelmsg -- Unicode trait for sending messages from the kernel to the iframe. Setting this value triggers a postMessage to the sandboxed iframe.
clientmsg -- Unicode trait that receives messages from the iframe. Observing this trait allows Python code to react to user interactions in the visualization.
srcdoc -- Unicode trait containing the HTML content loaded into the iframe. Can be dynamically updated to change the visualization.
initial_height / initial_width / initial_border -- Unicode traits controlling the initial iframe dimensions and border styling.

All traits are tagged with sync=True to ensure they are automatically synchronized between the Python kernel and the JavaScript frontend via the Jupyter widget protocol. The model and view names (StitchModel, StitchView) link to the TypeScript implementations.

Usage

Use this widget as the communication bridge between Python visualization logic and JavaScript/HTML rendering in Jupyter notebooks. It is the foundation for InterpretML's interactive visualization system, allowing explanations and model insights to be rendered in sandboxed iframes with bidirectional message passing.

Code Reference

Source Location

Repository: Interpretml_Interpret
File: python/stitch/stitch/stitch.py

Signature

class StitchWidget(DOMWidget):
    """Widget that purely handles communication between an iframe and kernel via postMessage."""

    _model_name = Unicode("StitchModel").tag(sync=True)
    _model_module = Unicode(module_name).tag(sync=True)
    _model_module_version = Unicode(module_version).tag(sync=True)
    _view_name = Unicode("StitchView").tag(sync=True)
    _view_module = Unicode(module_name).tag(sync=True)
    _view_module_version = Unicode(module_version).tag(sync=True)

    kernelmsg = Unicode("").tag(sync=True)
    clientmsg = Unicode("").tag(sync=True)
    srcdoc = Unicode("<p>srcdoc should be defined by the user</p>").tag(sync=True)

    initial_height = Unicode("1px").tag(sync=True)
    initial_width = Unicode("1px").tag(sync=True)
    initial_border = Unicode("0").tag(sync=True)

Import

from stitch.stitch import StitchWidget

I/O Contract

Inputs

Name	Type	Required	Description
srcdoc	str	No	HTML content to render in the sandboxed iframe (default: placeholder paragraph)
kernelmsg	str	No	Message to send from kernel to the iframe (default: "")
initial_height	str	No	Initial iframe height (default: "1px")
initial_width	str	No	Initial iframe width (default: "1px")
initial_border	str	No	Initial iframe border (default: "0")

Outputs

Name	Type	Description
clientmsg	str	Messages received from the iframe, synchronized back to the kernel

Usage Examples

from stitch.stitch import StitchWidget

# Create a widget with custom HTML content
widget = StitchWidget(
    srcdoc="<html><body><h1>Hello from InterpretML</h1></body></html>",
    initial_height="400px",
    initial_width="100%",
)

# Display in Jupyter notebook
display(widget)

# Send a message to the iframe
widget.kernelmsg = '{"action": "update", "data": [1, 2, 3]}'

# Observe messages from the iframe
def on_client_message(change):
    print(f"Received from client: {change['new']}")

widget.observe(on_client_message, names=['clientmsg'])

Related Pages

Interpretml_Interpret_StitchWidget_TS -- TypeScript frontend that pairs with this Python backend
Interpretml_Interpret_VisRenderer -- React visualization renderer that can be loaded in the widget's iframe

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment