Skip to content

Latest commit

 

History

History
59 lines (41 loc) · 4.75 KB

adding-jupyter-kernels.md

File metadata and controls

59 lines (41 loc) · 4.75 KB

Adding support for new Jupyter subkernels

.NET Interactive already supports connecting to any Jupyter kernel as a subkernel. The Jupyter kernel can be selected by specifying its kernel spec in the #!connect jupyter command as shown below.

#!connect jupyter --kernel-name pythonkernel --conda-env base --kernel-spec python3

This will enable kernel launch, code execution, and code completion if provided by the kernel. However, by default Jupyter messaging protocol does not have support for variable sharing, so the connected kernel will not have variable sharing enabled.

In .NET Interactive, variable sharing is enabled for the IPython and IR kernels by using the comms message support in Jupyter messaging protocol. As long as a Jupyter kernel supports registering comms targets and handling comms messages, variable sharing can be enabled for these kernels.

To enable variable sharing for a Jupyter subkernel, follow these steps:

  1. Ensure that the kernel to be added supports handling comms messages. If not, variable sharing cannot be enabled.

  2. If intended kernel supports comms messages, create a language specific script for it under the LanguageHandlers folder in the .NET interactive kernel repo.

  3. This script is sent to the kernel on kernel launch, and should then create a comm message handler and a comm target, that is named dotnet_coe_handler_comm. This script is responsible for registering the target and the comm handlers. Take a look at the python script here. The expected schema of messages to be send back in the comm_msg data field is

{
    "data": {
        "type": "object", 
        "description": "comm message data",
        "properties": {
            "commandOrEvent": {
                "type": "string"
                "description": "serialized json string of either KernelEventEnvelope or KernelCommandEnvelope"
            }, 
            "type": {
                "type": "string"
                "description": "`command` or `event`"
            }
        }
      }
}

commandOrEvent is a serialized json string reflecting either the KernelEventEnvelope or the KernelCommandEnvelope. The type field is used to indicate whether the message is an event or a command.

On launch, .NET Interactive will run the script on the kernel to set up target and then try to send a comm_open message to the kernel to establish a comm connection.

Variable sharing will only be enabled when the comm channel sends a ACK back with a kernelReady message and handles the send/request/request_value messages.

Testing your integration

Test your integration be adding the language kernel to the Http and ZMQ Test data in the following tests. The tests should not need to be modified, only your input parameters should be added.

On first run, record the kernel message output by turning on RECORD_FOR_PLAYBACK. This will allow tests to be able to use the recorded output for playback in the build agents. This is only really needed if there is change in the kernel handling logic in the core .NET app as the scripts are not run in the build agent.

In addition, ensure the scripts are testable on their own and correctly return the comm messages. Check out the python and R tests to get a list of scenarios and formatting that needs to be supported by the scripts.