Kotlin Kernel for Jupyter notebooks

The Kotlin Kernel for Jupyter notebooks is a tool that enables writing and running Kotlin code within the Jupyter Notebook environment. It acts as a bridge between Jupyter and the Kotlin compiler, providing interactive features such as:

• Immediate output from code cells.
• Basic code completion and error analysis.
• Access to APIs within cells and for handling outputs.
• Ability to retrieve information from previously executed snippets.
• Easy library importing and integration.

You can use the Kotlin Kernel in IntelliJ IDEA (via the Kotlin Notebook plugin), Datalore (natively supported), or standard Jupyter clients (JupyterLab, Jupyter Notebook, Jupyter Console).

The project provides several documentation resources:

• Docs site: Contains rendered KDoc comments from the codebase.
• Library Integration Docs: Guidance on integrating new libraries. Library authors should note:
  • The api module is relevant for library integration.
  • The lib module contains entities available from Notebook cells.
  • The intellij-dependencies-shared module is used for Jupyter REPL integration into standalone applications or IntelliJ IDEA plugins.
• Kotlin Notebook Docs: Information on features, use cases, and tutorials for the Kotlin Notebook plugin.

There are two primary methods to integrate a library into the Kotlin Kernel for Jupyter notebooks:

1. Creating a JSON library descriptor: An easy solution that does not require modifying the library itself. You create a JSON file that defines features like properties, renderers, and initial imports. Libraries integrated this way can be loaded using the %use line magic.

2. Using the Kotlin API: This method involves adding integration logic directly to the library code (or a separate integration project). The library is automatically integrated when its JAR containing a META-INF/kotlin-jupyter-libraries/libraries.json file (specifying the integration class name) is added to the notebook classpath. You can trigger this integration using the @file:DependsOn annotation or via a JSON descriptor that defines the dependency.

When deciding how to integrate a library, choose based on your level of control over the library source:

The jupyter-lib/protocol module provides the core protocol logic and data structures required for Jupyter kernel communication. It is designed to be a lightweight module with minimal dependencies, making it suitable for import into other projects without requiring the Kotlin compiler or other kernel-specific logic.

It contains the org.jetbrains.kotlinx.jupyter.protocol package and parts of org.jetbrains.kotlinx.jupyter.messaging.

Rendering is the process of transforming a value into a displayable format for the Jupyter client. The kernel follows a specific hierarchy:

1. Renderers: The kernel first attempts to use RenderersProcessor to convert a value into a Renderable or DisplayResult object. If successful, the result is converted to JSON via toJson().
2. Text Rendering: If no Renderable is found, the TextRenderersProcessor attempts to find a text renderer that returns a non-null string. If all fail, the kernel falls back to the object's .toString() method wrapped in text/plain.
3. Throwable Rendering: If a cell execution fails, the kernel uses Throwable renderers to display the exception. If none are available, the error is printed to standard error.

Libraries can define custom renderers to handle specific types (like charts or data frames) during any of these stages.

There are three primary ways to integrate library features into a Kotlin Kernel notebook:

1. Descriptor API: Create a JSON file containing feature descriptions. This file is loaded using the %use line magic. You can also load a JSON string directly using loadLibraryDescriptor inside a notebook cell.
2. JupyterIntegration API: Add features directly from a notebook cell using the USE { ... } block. This is the most common programmatic method.
3. LibraryDefinition API: Use a LibraryDefinition instance (created via libraryDefinition { ... }) passed to the USE() function. This is typically used when building a Kotlin JVM library to provide integration logic.

You can load libraries from Maven repositories using a USE { ... } block in any cell. This allows you to specify repositories, credentials, and dependencies using a syntax similar to Gradle.

Limitations: This is not a full Gradle execution. Gradle metadata is not resolved, and advanced configurations like top-level Multiplatform dependencies are not supported. For Multiplatform libraries, you must manually specify the -jvm variant.

USE {
	repositories {
		maven {
			url = "https://my.secret.repo/maven/"
			credentials {
				username = USER
				password = TOKEN
			}
		}
	}

	dependencies {
		val ktorVersion = "2.0.3"

		implementation("my.secret:artifact:1.0-beta")
		implementation("io.ktor:ktor-client-core:$ktorVersion")
		implementation("io.ktor:ktor-client-apache:$ktorVersion")
	}
}