Configure a custom code widget

In reports, you can write your own Python code and render it as an interactive widget. The code is executed in a secure sandbox and the widget reacts to viewer actions, such as filtering and selecting runs.

The custom code widget supports rendering everything compatible with Jupyter and IPython, for example:

• pandas tables
• Matplotlib plots
• Plotly charts
• HTML and JavaScript elements

note

The custom code widget is an experimental feature. To view and create such widgets, first enable them:

1. In your account settings, go to Experimental features.
2. Enable Custom code widgets.

Create a widget

To add a custom code widget to your report:

1. In the top toolbar, click New widget and select Custom code.

2. (Optional) Change the widget title.

Define the widget code

The widget code consists of three parts:

• === TYPE DEFINITIONS & CONTEXT VARIABLES ===

  This is the read-only code that represents the current state of the report.

  In your custom code, reference the variables and type definitions included in this section to make the widget respond to viewer actions.

• === EXAMPLE FUNCTION ===

  The widget comes with a predefined function that returns a runs table with the attributes of the sys namespace for the currently selected runs.

  Replace this function with your own code. See examples.

• === HOW TO EXECUTE LOCALLY ===

  The line if __name__ == "__main__": ensures safe importing of the main module. For details, see the Python documentation.

  This part is necessary to execute the code locally.

Configure widget inputs

To let report viewers interact with the widget, define inputs. For example, you can add search, sorting, or filtering directly in the widget.

To add a widget input:

1. In Widget inputs, click Add input.

2. In Type, select one of the following options:

   • Text
   • Number
   • Slider
   • Dropdown
   • Checkbox

3. In Label, provide a descriptive identifier of the input for the report viewers.

4. The value of the ID field is auto-generated. Use it to reference the input in your custom code.

Supported packages

The custom code widget requires Python 3.13 and supports the following packages:

• httpx
• Jinja2
• matplotlib
• neptune-query
• numpy
• pandas
• plotly
• pydantic
• requests

Execute the code locally

To grab the existing code and develop it in your local environment, use the Copy code button.

Move or duplicate a widget

You can move the custom code widget to a new or existing report. You can also duplicate the widget in the report that you're currently working on.

To access the options, open the widget menu ().

Examples

See the following examples of custom code widgets optimized for analyzing LLM eval results.

Visualize multi-dimensional data

This example shows how to visualize multi-dimensional data with plotly and neptune-query:

• The returned scatter plot uses symbols to distinguish between experiments.
• Report viewers can choose which attributes to display on the Y-axis and change their color.

tip

• To speed up your queries, apply filters using neptune-query and narrow down the results to the specific attributes that you want to display.
• When loading series that have over 1000 steps, choose fetch_metric_buckets() over fetch_metrics().

Interactive table

This example shows an interactive table that lets report viewers analyze individual eval samples:

• Use neptune-query to load a CSV file selected by the report viewer.
• Display the selected file as an HTML table styled with CSS.
• Use JavaScript to hide long chain-of-thought strings and make them visible on button click.

tip

Any string returned by your main() function is interpreted as HTML. That means you can use the <style> tag to apply CSS styles and the <script> tag to include JavaScript code.

note

Due to security reasons, it might be impossible to use some of the third-party JavaScript libraries in your environment. For help, contact your administrator or Neptune support.