Make SKaiNET deepr integrated into Kotlin Notebook

[michalharakal]

• typealiases for common types with short names, especially one for DSLs
• Notebook API for automatic "imports"

https://github.com/Kotlin/kotlin-jupyter/blob/df62d79c5df2b5a6d3f68ba25fa8f19c8b6e2235/api-examples/getting-started/src/main/kotlin/org/jetbrains/kotlinx/jupyter/example/GettingStartedIntegration.kt

[michalharakal]

Integrating a JVM Library with Kotlin Notebooks (IntelliJ & CLI)

Background: Dependencies in Kotlin Notebooks

Kotlin Notebooks (whether in IntelliJ IDEA or via Jupyter / CLI) allow dynamic dependency loading. In any notebook, you can pull in a Maven artifact by specifying its coordinates.

@file:DependsOn("your.group:your-library:1.0")

This fetches the JAR from Maven Central (and any transitive dependencies) and adds it to the notebook’s classpath.
Repositories can be added via @file:Repository if needed (not required for Maven Central).

Once the dependency is loaded, you still need to import the library’s packages or classes:

import com.example.mylib.*

You must run the cell containing imports before running cells that use them.

This repetition across notebooks is what we aim to eliminate.

---

Default Imports and %use Magics

Kotlin Notebooks provide the %use magic command to simplify common imports and setup.

When executed, %use:

• Downloads the dependency
• Adds default imports
• Runs initialization code

Example:

%use dataframe

When a %use statement is executed, it downloads the library dependencies and adds the default imports to your notebook.

Limitations

• Only works for libraries explicitly integrated with the Kotlin kernel
• Unsupported libraries require @DependsOn + manual imports

Library authors can fix this using one of two integration mechanisms.

---

Integration Approaches

1. JSON Library Descriptor (Legacy)

A JSON descriptor defines:

• Maven coordinates
• Default imports
• Initialization code
• Optional renderers

Users activate it via:

%use mylib

Drawbacks

• External to the library → version drift
• Fragile if APIs change
• Complex logic embedded as strings
• Poor support for transitive integrations

---

2. Kotlin Notebook API Integration (Recommended)

This modern approach embeds integration logic directly into the library.

Step 1: Apply the Gradle Plugin

plugins {
    kotlin("jvm")
    id("org.jetbrains.kotlin.jupyter.api") version "<latest-version>"
}

Step 2: Add an Integration Class

import org.jetbrains.kotlinx.jupyter.api.annotations.JupyterLibrary
import org.jetbrains.kotlinx.jupyter.api.JupyterIntegration
import org.jetbrains.kotlinx.jupyter.api.libraries.Builder

@JupyterLibrary
internal class Integration : JupyterIntegration() {
    override fun Builder.onLoaded() {
        import("com.example.mylib.*")
    }
}

This automatically imports your API when the library is added to the notebook classpath.

Step 3: Publish Normally

Once published to Maven Central, users can write:

@file:DependsOn("com.example:mylib:1.0")

val obj = MyClass()

No manual imports required 🎉

---

Advanced Capabilities

With the Notebook API, you can also:

• Register custom renderers
• Add additional dependencies dynamically
• Define cell lifecycle hooks
• Provide notebook-only utilities or magics

These features make your library feel native to notebooks.

---

IntelliJ IDEA Usage

Project-Based Notebooks

1. Add your library as a Gradle dependency
2. Open Notebook Settings (⚙️)
3. Select Modules to Use in the Notebook
4. Restart the kernel

Your integration will run automatically.

Scratch or Standalone Notebooks

Use:

@file:DependsOn("com.example:mylib:1.0")

That’s it.

---

Jupyter / CLI Usage

In JupyterLab, VS Code, or CLI environments:

@file:DependsOn("com.example:mylib:1.0")

The Kotlin kernel will:

1. Download the library
2. Discover @JupyterLibrary
3. Apply default imports and setup

---

Best Practices

• Prefer Kotlin Notebook API integration over JSON descriptors
• Keep integration classes internal
• Test in both IntelliJ and Jupyter
• Document notebook usage in your README

Optional:

• Provide a JSON descriptor only if you want a %use alias

---

Conclusion

Embedding Kotlin Notebook integration directly into your library provides a zero‑boilerplate experience for users.
No repetitive imports, no extra setup—just add the dependency and start coding.

Your library becomes truly notebook‑friendly.

[michalharakal]

Go with json descriptor first https://github.com/Kotlin/kotlin-jupyter-libraries/blob/master/kstats.json