almond-sh/almond

Almond is a Jupyter kernel for Scala that enables interactive code execution, rich display rendering, and reactive updates within notebook environments. It supports multiple Scala versions (2.12, 2.13, and 3) with features like script reloading, code completion, and integration with Python via ScalaPy. The system provides a robust infrastructure for dependency management, proxy support, and automated testing, serving as a bridge between Scala code and the Jupyter ecosystem.

19 changes.

The project rebranded from Jupyter Scala to Almond, migrating its build infrastructure from SBT to Mill and removing legacy CLI and configuration entry points. This period focused on refactoring the core Scala interpreter to support Scala 3, enhancing Jupyter protocol features like updatable results and magic commands, and establishing comprehensive test coverage for the new architecture.

11 changes.

This period focused on significantly improving the Scala interpreter's developer experience by adding script reloading, compile-only evaluation, and richer code completion with documentation. It also introduced robust automation for Docker image publishing and website deployment, alongside enhanced ANSI color rendering and ScalaPy rich display support.

10 changes.

This period focused on modernizing the Almond kernel's core architecture, notably introducing a two-step launcher for improved reliability and a new Jackson-based JSON serialization API. Concurrently, the project significantly expanded its testing capabilities by implementing a shared integration test kit, automated example notebook validation, and robust CI retry mechanisms to ensure stability across Scala versions and network environments.

A new 'Echo' kernel is now available, implemented in the modules/echo directory. It serves as a minimal, deterministic interpreter for testing and development, supporting basic code execution (echoing input or printing via 'print '), code completion, and inspection. The kernel includes CLI options for installation, logging levels, connection file handling, and binding to random ports.

modules/echo/src/main · high confidence

The \LoggerMacros\ component in the shared logger module now includes the Scala 2 macro definitions for error, warn, info, and debug logging levels, including variants that accept throwables. This change introduces the underlying macro logic required to support the Scala 2 version of the logging API, enabling compile-time optimization of log statements based on enabled levels.

modules/shared/logger-scala2-macros · high confidence

New shell scripts have been added to automate the publishing of the website and the management of versioned documentation. The \push-website.sh\ script handles cloning the \gh-pages\ branch, cleaning existing content while preserving specific files, copying the new build artifacts, and committing/pushing the changes. The \versioned-docs.sh\ script manages the synchronization of versioned documentation and sidebars from a separate repository, allowing users to update the documentation for a specific git tag by passing the \--update\ flag.

scripts/website0 · high confidence

New shell scripts (\install-kernels.sh\ and \update-docker-images.sh\) are introduced to automate the installation of Almond Jupyter kernels and the building/publishing of Docker images. The update script leverages Mill to determine Scala versions (2.12, 2.13, 3) and handles both snapshot builds (pushing a single \snapshot\ image) and release builds (pushing versioned images for each Scala version plus a \latest\ tag), ensuring Docker images are automatically updated upon release.

scripts · high confidence

The Scala interpreter now provides richer feedback in the editor. Code completion results include metadata such as the kind of symbol (e.g., method, class, value) and full signatures, allowing users to distinguish between overloaded methods or different types more easily. Additionally, when inspecting code (e.g., via hover or info tooltips), the interpreter now fetches and displays Scaladoc comments for symbols, improving discoverability of API details without leaving the editor.

modules/scala/scala-interpreter/src/main/scala-2/almond/internals · high confidence

Added a new \modules/shared/test-kit\ module providing a DSL and infrastructure for running integration tests against the Almond kernel. This includes \ClientStreams\ to capture and inspect kernel messages (execute replies, display data, errors), a \Dsl\ object with a fluent \execute\ method for writing test scenarios, and configurable \TestLogging\ to control output verbosity via environment variables.

modules/shared/test-kit · high confidence

A new \json-api-jackson\ module has been added, providing \AlmondJackson\ utilities that allow users to serialize arbitrary Scala objects to JSON using the Jackson library. This introduces extension methods for \DisplayData\ (to add JSON values) and \OutputHandler\ (to display data objects or add payload objects), enabling richer, structured data display in notebooks. The change also includes the \test-definitions\ module, which contains integration tests verifying this new functionality alongside other kernel behaviors like future updates and interrupt handling.

modules/scala/test-definitions · high confidence

A new \almond-rx\ module has been added, providing a \setup\ function that integrates the \rx\ reactive library with Jupyter updatable results. When initialized, it configures the REPL printer to automatically display and update the current value of \Rx\ objects in real-time as they change, enhancing the interactive experience for reactive programming workflows.

modules/scala/almond-rx · high confidence

Python objects executed via ScalaPy now render rich content (such as images, HTML, Markdown, and LaTeX) in Jupyter notebooks. This is achieved by registering a custom Jupyter displayer that executes Python representation methods (e.g., \\_repr\png\\, \\_repr\html\\) and formats the resulting data and metadata for display.

modules/scala/almond-scalapy · high confidence

The kernel now supports loading and reloading Ammonite scripts using the \//\> using script\ and \//\> using scripts\ directives. This change introduces new directive handlers in the \kernel-helpers\ module that parse script paths and integrate them into the kernel's execution context, allowing scripts to be compiled and run once with their wrapper objects brought into scope. Scripts that have changed since they were last loaded are automatically reloaded, providing a dynamic scripting experience similar to Ammonite's \$file\ imports.

modules/scala/kernel-helpers · high confidence

The Scala interpreter now supports reloading modified scripts within a live notebook session and offers a compile-only execution mode. A new \ReloadingSourceHook\ detects changes in imported scripts by hashing their content and re-imports them with versioned wrapper names, ensuring that subsequent cells see the updated code without restarting the kernel. Additionally, a \CompileOnlyEvaluator\ allows users to execute cells in a mode that compiles the code but skips runtime execution, which is useful for syntax checking or dependency resolution without side effects. These changes are implemented in the \almond.amm\ package, introducing \AmmInterpreter\, \CompileOnlyEvaluator\, \HookEvaluator\, and \ReloadingSourceHook\ to manage these new behaviors.

modules/scala/scala-interpreter/src/main/scala/almond/amm · high confidence

The Scala kernel now supports Toree-style cell and line magic commands (such as %%html, %%javascript, %AddDeps, and %AddJar) for backward compatibility with existing notebooks, alongside a new variable inspector API that allows users to inspect the state of variables in their sessions.

modules/scala/scala-kernel-api · high confidence

The project has removed the legacy Conscript launch configuration files for Jupyter Scala (\jupyter-scala-embedded\ and \jupyter-scala\). Users relying on these specific embedded launch setups via the Conscript tooling will no longer have these configurations available, as the associated Scala 2.11.6 and repository definitions have been deleted from the source tree.

src/main · high confidence

The CLI entry-point classes \JupyterScala\ and \JupyterScalaEmbedded\ have been removed from the \cli/src/main/scala\ directory. This eliminates the direct command-line interfaces that previously launched the Jupyter kernel server using \caseapp\ argument parsing and \xsbti\ launch wrappers, effectively removing these specific CLI execution paths from the product.

cli/src/main/scala · high confidence

The files in \kernel/src/main/scala/jupyter/scala\ have been deleted, removing the previous Scala kernel implementation. This includes the \CustomPreprocessor\ for parsing REPL snippets, the \ScalaInterpreter\ wrapping Ammonite, the \IvyHelper\ and \SbtChainResolver\ for dependency resolution, and the \ScalaModule\/\EmbeddedScalaModule\ definitions. Users will no longer have access to the Scala kernel provided by this specific codebase location.

kernel/src/main/scala · high confidence

The project has migrated its build infrastructure from SBT to Mill (version 2.0.0-M2), replacing the previous SBT configuration with a new build.mill file and Mill launcher scripts. This change is accompanied by a rebranding from 'Jupyter Scala' to 'almond', reflected in updated documentation, README, and project metadata. The migration also includes the removal of Travis CI in favor of GitHub Actions, the addition of Gitpod support for cloud-based development environments, and the introduction of a Dockerfile for containerized kernel images.

(repo-wide) · high confidence

The Scala interpreter now supports more granular variable inspection and debugging. Users can enable the \--log-code\ option to view the source code actually passed to the compiler after preprocessing, aiding in debugging. The interpreter also introduces a \silentImports\ feature to suppress import-related noise in the variable inspector and improves the handling of \lazy val\ and \var\ definitions for better change detection and inspection integration.

modules/scala/scala-interpreter/src/main/scala-2/almond/amm · high confidence

The examples directory now uses uv to manage Python dependencies, pinning Python 3.12 and locking versions in uv.lock, which removes the need for pre-installed Python tools. New example notebooks have been added to demonstrate rich display capabilities (HTML, LaTeX, Markdown, progress bars) in both Scala and ScalaPy, as well as Plotly charting. The JupyterLab development environment is configured with custom overrides for theming and indentation, and the Scala kernel metadata has been updated to use the .sc file extension and Scala 2.12.20.

examples · high confidence

The interpreter now uses a custom HTML-based ANSI processor to render terminal colors more accurately in notebook interfaces. This change ensures that text colors and backgrounds are correctly mapped to CSS classes and inline styles, improving the visual fidelity of output for users viewing results in JupyterLab, nteract, and nbviewer.

modules/scala/scala-interpreter/src/main/java · high confidence

The integration test framework has been updated to automatically retry flaky tests when running on CI. Tests that fail due to transient issues (such as ZeroMQ connection timeouts or overloaded runners) will now be retried up to three times with an exponential backoff, significantly improving the reliability of the test suite in continuous integration environments.

modules/scala/integration/src/main · high confidence

The Scala kernel now uses a new two-step startup process where a lightweight launcher component (Launcher, LauncherInterpreter, LauncherOptions, LauncherOutputHandler) handles initial connection, directive parsing, and output buffering before spawning the actual kernel process. This allows the launcher to process using directives, manage shared dependencies, and handle output streams independently, improving startup reliability and resource management.

modules/scala/launcher/src/main/scala · high confidence

The build system has been upgraded to Mill 1.0, introducing a new \build.mill\ root module and a comprehensive set of internal build modules under \almondbuild\ (including dependency management, Scala version handling, and publishing logic). This refactor supports the latest Scala versions (2.12.21, 2.13.18, 3.9.0) and integrates \uv\ for managing Python dependencies in Jupyter commands, while also adding support for Jupyter AI agents via ACP.

mill-build · high confidence

The Scala 3 interpreter internals now include a new \ConfigureCompiler\ object to handle compiler option configuration via \ScalacCommand\, and a comprehensive \ScalaInterpreterCompletions\ module that provides code completion with type signatures and metadata by wrapping user input in an autocomplete context and filtering results. Additionally, \ScalaInterpreterInspections\ is introduced as a placeholder implementation that currently returns no inspection data, decoupling inspection logic from the metabrowse server dependency.

modules/scala/scala-interpreter/src/main/scala-3/almond/internals · high confidence

The API module introduces a new \almond.display\ package with dedicated classes for rendering content (Html, Markdown, Image, etc.) and a refactored \DisplayData\ model that supports detailed data and metadata values (strings vs JSON) for better fidelity. The old \almond.api.helpers.Display\ utilities are deprecated in favor of the new types, and Scala 2/3 compatibility shims are added to maintain binary compatibility during the transition.

modules/api · high confidence

The interpreter now introduces a new internal mechanism to capture and mirror user code's stdout and stderr, controlled by a new 'quiet' parameter that determines whether output is sent to the console. Additionally, it implements updatable results, allowing variables displayed in the notebook to be updated in place (e.g., during loops) with coalesced updates to prevent excessive traffic, and supports updating futures as they complete.

modules/scala/scala-interpreter/src/main/scala/almond/internals · high confidence

The Scala interpreter's execution logic has been restructured into dedicated components: the core execution loop is now handled by the new Execute class, while the Jupyter API and REPL API implementations are provided by JupyterApiImpl and ReplApiImpl respectively. This refactoring introduces support for execution hooks (pre- and post-run), post-interrupt hooks, and exception handlers via the Jupyter API, allowing users to inject custom behavior into the code execution lifecycle. The interpreter parameters (ScalaInterpreterParams) have been expanded to support these new capabilities, including options for thread-based interruption, lazy initialization, and specific execution modes like compile-only.

modules/scala/scala-interpreter/src/main/scala/almond · high confidence

The kernel's command-line and configuration options have been consolidated into a new \Options\ class, introducing several user-facing changes: users can now enable code navigation via a metabrowse server (disabled by default), trap stdout/stderr output from user code, silence import printing, and view only the last value of each cell. Additionally, the kernel now supports formatting code cells using Scalafmt via the \--scalafmt\ option (enabled by default) and allows customizing the wrapper class name and package name for user code. Thread management has been refactored to use dedicated execution contexts for better resource handling.

modules/scala/scala-kernel/src/main · high confidence

The kernel module has been restructured to support Scala 3, introducing version-specific compatibility layers for ZeroMQ threading and a macro-based logger implementation. The ZeroMQ connection layer now supports binding to random ports, improving reliability in environments with port conflicts. Additionally, the interpreter interface has been modernized with a new \IOInterpreter\ trait for better effect handling, and the \ZeromqThreads\ API has been updated to use \ExecutionContextExecutorService\ for more precise thread management.

modules/shared/kernel/src/main · high confidence

The Jupyter configuration file (jupyter.conf) has been removed from the kernel resources. This file previously defined module bindings for Scala and Embedded Scala Jupyter modules; its deletion indicates that these specific Jupyter integration settings are no longer applied by default.

kernel/src/main/resources · high confidence

The project has removed its legacy SBT build infrastructure, specifically deleting the \project/JupyterScalaBuild.scala\ definition file, \project/build.properties\, and \project/plugins.sbt\. This eliminates the SBT-based build system (including plugins like sbt-pack, sbt-sonatype, and sbt-release) and the associated project structure for the kernel and CLI modules, indicating a migration away from SBT to a different build tool.

project · high confidence

The Scala 3 interpreter now supports a --log-code option that allows users to view the preprocessed code sent to the compiler, aiding in debugging. It also introduces silent imports to reduce noise from generated wrapper code and suppresses specific Scala 3.9+ warnings about identifiers containing '$'. These changes improve the user experience by providing better visibility into the compilation process and cleaner output.

modules/scala/scala-interpreter/src/main/scala-3/almond/amm · high confidence

Added TestOutputHandler for capturing interpreter output in tests; Added automated tests to execute and validate Scala example notebooks; Added comprehensive test coverage for the Scala interpreter; Added integration tests for running Almond behind authenticated proxies and repository mirrors; Added integration tests for two-step kernel startup across Scala versions; Added tests for EchoInterpreter execution, completion, and inspection; Added tests for the code formatting feature; Added unit tests for kernel components.

This change introduces the initial \package.json\ and \package-lock.json\ files for the \docs/website\ directory, pinning the Docusaurus development dependency to version 1.14.7. It also adds the initial \package.json\ and \package-lock.json\ for the \examples/acp-agents\ directory, establishing dependencies for the \@agentclientprotocol/claude-agent-acp\ (0.81.2) and \@agentclientprotocol/codex-acp\ (1.13.1) packages. Additionally, an initial \pyproject.toml\ is added for the \examples\ directory, defining Python dependencies for Jupyter components (client, console, lab, notebook, nbconvert) and an optional AI group including \jupyter-ai\.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 37 → 59 (+22.0)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 71 → 89 (+17.9)
• Architecture 69 → 91 (+21.5)
• Maturity 57 → 47 (-10.1)
• Readiness 16 → 56 (+39.4)
• Security 49 → 82 (+32.4)

• Consequences/trade-offs are not stated and fall after a clip marker (installation notebook is an action, not a trade-off) (docs/website/blog/2019-03-11-0.3.1.md)
• Dimension evaluation failed
• High IaC: DS-0002 (.gitpod.Dockerfile)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 18 more

• AlmondFunSuite.test0 (cognitive 16) (modules/scala/integration/src/main/scala/almond/integration/AlmondFunSuite.scala)
• AmmInterpreter.apply (cognitive 35) (modules/scala/scala-interpreter/src/main/scala/almond/amm/AmmInterpreter.scala)
• AmmInterpreter.apply (cyclomatic 31) (modules/scala/scala-interpreter/src/main/scala/almond/amm/AmmInterpreter.scala)
• Boundary-crossing change coupling: EchoKernel.scala ↔ KernelLauncher.scala (modules/echo/src/main/scala/almond/echo/EchoKernel.scala)
• Boundary-crossing change coupling: EchoKernel.scala ↔ Launcher.scala (modules/echo/src/main/scala/almond/echo/EchoKernel.scala)
• Boundary-crossing change coupling: EchoKernel.scala ↔ ScalaKernel.scala (modules/echo/src/main/scala/almond/echo/EchoKernel.scala)
• Change coupling: AlmondPreprocessor.scala ↔ AmmInterpreter.scala (modules/scala/scala-interpreter/src/main/scala-2/almond/amm/AlmondPreprocessor.scala)
• Change coupling: LauncherOptions.scala ↔ ScalaKernel.scala (modules/scala/launcher/src/main/scala/almond/launcher/LauncherOptions.scala)
• Change coupling: ScalaInterpreterParams.scala ↔ Options.scala (modules/scala/scala-interpreter/src/main/scala/almond/ScalaInterpreterParams.scala)
• CompileOnlyEvaluator.evaluationResult (cognitive 19) (modules/scala/scala-interpreter/src/main/scala/almond/amm/CompileOnlyEvaluator.scala)
• Dependency hygiene PARTLY measured — Python dependencies read, no exact pin to grade for currency
• Documentation: no installation or build instructions (README.md)
• Documentation: no project overview (README.md)
• Duplicated block (10 lines × 2) (modules/shared/test-kit/src/main/scala/almond/testkit/ClientStreams.scala)
• Duplicated block (11 lines × 3) (modules/shared/test-kit/src/main/scala/almond/testkit/ClientStreams.scala)
• Duplicated block (11 lines × 4) (mill-build/src/almondbuild/modules/BootstrapLauncher.scala)
• Duplicated block (12 lines × 2) (modules/scala/scala-interpreter/src/main/scala/almond/internals/FunctionInputStream.scala)
• Duplicated block (15 lines × 2) (modules/shared/test-kit/src/main/scala/almond/testkit/ClientStreams.scala)
• Duplicated block (15–16 lines × 2) (modules/shared/kernel/src/main/scala/almond/interpreter/messagehandlers/MessageHandler.scala)
• Duplicated block (17 lines × 3) (modules/echo/src/main/scala/almond/echo/EchoKernel.scala)
• …and 126 more

• 83 commits — 80 feature/other, 3 fixes

• (root) — 25 commits
• mill-build/src — 19 commits
• modules/scala — 11 commits
• (repo) — 6 commits
• docs/pages — 6 commits
• .github/workflows — 4 commits
• docs/website — 3 commits
• examples/requirements.txt — 3 commits
• modules/shared — 3 commits
• .github/scripts — 1 commit
• examples/acp-agents — 1 commit
• modules/api — 1 commit

• fix: Fix Sonatype Central publishing for tagged releases
• fix: Fix env in kernel.json serialized as array instead of JSON object (issue #1499) (#1666)
• fix: Revert annoying changes
• change: Add --last-value-only option (#1764)
• change: Add --version option to launcher (#1747)
• change: Add .gitattributes to specify Scala files
• change: Add Jupyter AI and ACP agents to dev commands
• change: Add a new command to run JupyterLab from sources
• change: Add instructions about weird build errors in AGENTS.md
• change: Add services.json
• change: Address compilation warning (#1646)
• change: Address compilation warnings in build sources (#1767)
• change: Allow completions during cell execution (#1755)
• change: Bump brace-expansion from 1.1.11 to 1.1.18 in /docs/website (#1719)
• change: Bump js-yaml from 3.14.2 to 3.15.2 in /docs/website (#1735)
• change: Bump mistune from 3.3.0 to 3.3.3 in /examples (#1729)
• change: Bump soupsieve from 2.8.4 to 2.9 in /examples (#1740)
• change: Bump tornado from 6.5.7 to 6.5.8 in /examples (#1727)
• change: Cancel redundant CI runs
• change: Coalesce automatic variable updates (#1757)
• …and 63 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

almond-sh/almond was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.