SMILE Studio User Guide

SMILE Studio is an integrated development environment (IDE) for machine learning and data science using the SMILE library. It combines an interactive notebook, an AI-powered agent panel, a file explorer, and a kernel explorer in a single, modern desktop application. The launcher (smile / smile.bat) also exposes several command-line entry points. For the User Guide for CLI, see CLI.md.

Table of Contents

1. Overview
2. Starting SMILE Studio
3. Application Layout
4. Menus and Toolbar
5. The Notebook
   • 5.1 Opening and Creating Notebooks
   • 5.2 Supported File Formats
   • 5.3 Cells
   • 5.4 Cell Types
   • 5.5 Running Code
   • 5.6 AI Code Completion and Generation
   • 5.7 Saving Notebooks
   • 5.8 Auto-Save
   • 5.9 External File Changes
6. Execution Kernels
   • 6.1 Java Kernel (JShell)
   • 6.2 Scala Kernel
   • 6.3 Python Kernel (iPython)
   • 6.4 Restarting and Stopping a Kernel
   • 6.5 Magic Commands (Java Kernel)
7. Project Explorer
8. Kernel Explorer
   • 8.1 Inspecting Variables
   • 8.2 Saving Models
   • 8.3 Starting an Inference Service
9. AI Agent Panel
   • 9.1 Clair the Analyst
   • 9.2 James the Java Guru
   • 9.3 Guido the Pythonista
   • 9.4 Intent Types
   • 9.5 Slash Commands
   • 9.6 Shell Commands
   • 9.7 Long-Term Memory (SMILE.md)
   • 9.8 Reasoning Effort
   • 9.9 Auto-Compact
10. Notepad
11. Settings — AI Service Configuration
12. Status Bar
13. Font Size
14. MCP (Model Context Protocol) Integration
15. LSP (Language Server Protocol) Integration
16. Themes / Look-and-Feel
17. Keyboard Shortcuts Reference
18. Configuration Files
19. Troubleshooting

1. Overview

SMILE Studio brings together four major components in one window:

All four panels are arranged in a resizable split-pane layout, and the application remembers which notebooks were open across sessions.

2. Starting SMILE Studio

Run SMILE Studio from your project's root directory so that relative paths in notebooks resolve correctly:

# Unix / macOS
cd /your/project
path/to/smile/bin/smile

# Windows
cd C:\your\project
path\to\smile\bin\smile

Note: SMILE Studio must be started in a graphical (non-headless) environment. If the JVM is running in headless mode the application will print an error and exit.

System Requirements

• Java 25+ (with --enable-native-access=ALL-UNNAMED for the Java kernel's JShell remote VM)
• Python 3.x with ipython installed for Python notebooks (pip install ipython)
• Scala engine (included via the JSR-223 script engine)
• At least 4 GB RAM; 8 GB recommended for large datasets

3. Application Layout

┌─────────────────────────────────────────────────────────────────────┐
│  Menu Bar:  File  |  Cell  |  Help                                  │
│  Toolbar:  [New] [Open] [Save] [SaveAs] | [AddCell] [Run] [Clear]   │
│             [Restart] [Stop]                                        │
├──────────────────────────────┬──────────────────────────────────────┤
│  Explorer Tabs               │  Agent Tabs                          │
│  ┌──────────┬──────────┐     │  📊 Clair | ☕ James | 🐍 Guido     │
│  │ Project  │  Kernel  │     │                                      │
│  └──────────┴──────────┘     │  [Intent input / conversation area]  │
│                              │                                      │
│  File tree / Variable tree   ├──────────────────────────────────────┤
│                              │  Notebook Tabs                       │
│                              │  ┌─────────────────────────────────┐ │
│                              │  │  Cell 1: [▶][⏭][▾][↑][↓][🧹][⌦]│ │
│                              │  │  [code editor]                  │ │
│                              │  │  [output area]                  │ │
│                              │  ├─────────────────────────────────┤ │
│                              │  │  Cell 2 …                       │ │
│                              │  └─────────────────────────────────┘ │
├──────────────────────────────┴──────────────────────────────────────┤
│  Status Bar:  [status message]         [Heap: 512 MB  CPU: 12%]     │
└─────────────────────────────────────────────────────────────────────┘

• Left split – Project explorer (top) / Kernel explorer (bottom), switchable by tab.
• Center split – Notebook tabs.
• Right split – AI Agent tabs.
• Bottom – Status bar.

The divider positions are persisted and restored between sessions.

4. Menus and Toolbar

File Menu

Cell Menu

Help Menu

5. The Notebook

5.1 Opening and Creating Notebooks

• New (toolbar or File > New) — opens a fresh Untitled.java notebook pre-populated with the standard SMILE import block.
• Open… (toolbar or File > Open…) — file chooser filtered to supported extensions.
• Double-click a supported file in the Project Explorer — opens it directly in the notebook.

Previously opened notebooks are restored automatically at startup from .smile/studio.properties in the working directory.

5.2 Supported File Formats

Jupyter compatibility: When saving a .ipynb file, Studio writes back code cells, markdown cells, and raw cells. Cell outputs are not yet persisted to the .ipynb file.

5.3 Cells

Each cell is an independent editing unit consisting of:

• Header toolbar with action buttons (see below)
• Code editor – syntax-highlighted, resizable, with code folding
• Output area – appears below the editor after execution; supports Markdown rendering and clickable hyperlinks

Cell Header Buttons

5.4 Cell Types

5.5 Running Code

Execution is asynchronous; the UI remains responsive while code runs. A second run request while code is executing shows a warning dialog rather than allowing concurrent execution.

Variable values are printed automatically after each successful snippet evaluation:

⇒ DataFrame df = [200 rows × 5 columns]

Errors are highlighted in the output area with pink highlighting.

5.6 AI Code Completion and Generation

Both features require an AI service to be configured in Settings.

TAB — Line Completion

Press Tab at any non-first line to trigger single-line AI completion. The AI uses the surrounding code context (previous cell + current cell) to suggest a completion. If a completion is in progress, Tab inserts a literal tab character instead.

Prompt Field — Code Generation

1. Type a natural language description in the Prompt text field at the top of a cell (e.g., "load iris.csv into a DataFrame").
2. Press Enter.
3. The AI streams generated code directly into the editor, with the task description included as a comment.

The generation context includes the text of the previous cell and the existing content of the current cell.

5.7 Saving Notebooks

• Ctrl + S equivalent → File > Save
• File > Save As… prompts for a new path. If no extension is given, .java is appended.
• The tab title reflects the filename. Unsaved changes are tracked internally; a save-before-close prompt appears when closing a tab.

5.8 Auto-Save

Enable File > Auto Save to automatically save all open notebooks that have unsaved changes every 60 seconds. Only notebooks that have been previously saved to a file (i.e., have an associated path) are auto-saved; new Untitled notebooks are not.

5.9 External File Changes

If a file that is open in the notebook is modified by an external process (e.g., git checkout, another editor), Studio detects the change via a background file-watcher and prompts:

"'filename' has been changed externally. Reload?"

Choosing Yes reloads the file from disk, preserving the tab's position. Choosing No keeps the current in-memory version.

6. Execution Kernels

6.1 Java Kernel (JShell)

The Java kernel uses the JDK's built-in JShell API running in a separate JVM process. This isolation means:

• The remote VM inherits the full application classpath (java.class.path).
• JVM flags set for the remote process: -XX:MaxMetaspaceSize=1024M, -Xss4M, -XX:MaxRAMPercentage=75, -XX:+UseZGC.
• FlatLightLaf is automatically initialized in the remote JVM so that smile.plot.swing charts display correctly.

Snippet Output Format

New Java Notebook Starter Imports

When creating a new .java notebook, the first cell is pre-populated with:

import java.awt.Color;
import java.time.*;
import java.util.*;
import static java.lang.Math.*;
import smile.plot.swing.*;
import static smile.swing.SmileUtilities.*;
import org.apache.commons.csv.CSVFormat;
import smile.io.*;
import smile.data.*;
import smile.data.formula.*;
// … and many more SMILE packages

6.2 Scala Kernel

The Scala kernel uses the JSR-223 ScriptEngine API ("scala" engine name). Output is captured by redirecting System.out and System.err around each evaluation. The Scala engine initialization is deferred 5 seconds at startup to avoid capturing LSP/MCP process output.

Returned values are printed as:

$result0: fully.qualified.Type = value

6.3 Python Kernel (iPython)

The Python kernel launches an iPython REPL subprocess (ipython --simple-prompt --colors NoColor --no-banner --no-pdb). Multi-line code is submitted via iPython's %cpaste magic. The kernel reads output lines and displays them in the output area.

Prerequisite: iPython must be installed:

pip install ipython

If iPython is not found, Studio shows an informational dialog with the install command.

6.4 Restarting and Stopping a Kernel

6.5 Magic Commands (Java Kernel)

Lines starting with //! inside a Java cell are intercepted before being sent to JShell. The currently supported magic is:

//!mvn groupId:artifactId:version

This resolves the Maven dependency (transitively) via Eclipse Aether and adds the JARs to the JShell classpath at runtime, allowing you to use any Maven artifact without restarting the kernel.

Example:

//!mvn org.apache.commons:commons-math3:3.6.1

7. Project Explorer

The Project tab in the left panel shows the file tree rooted at the current working directory.

• Navigate the tree by expanding folders.
• Double-click a supported source file (.java, .jsh, .scala, .sc, .py, .ipynb) to open it in the notebook.
• Double-click any other non-binary text file to open it in the Notepad editor.
• Binary files are silently ignored on double-click.

8. Kernel Explorer

The Kernel tab in the left panel shows a live tree of runtime objects tracked by the active notebook's kernel. Switch between notebooks in the tab strip to refresh the explorer automatically.

The tree has four top-level categories:

8.1 Inspecting Variables

Double-click any DataFrames or Matrix leaf node to open the variable in a SMILE viewer window:

// Equivalent action generated by Studio:
var dfWindow = smile.swing.SmileUtilities.show(df);
dfWindow.setTitle("df");

8.2 Saving Models

Double-click a Models leaf node to open a Save dialog. Studio serializes the selected model variable using smile.io.Write.object(model, path) and saves it to a .sml file. After saving, if the model is a ClassificationModel or RegressionModel, it is automatically registered under the Services node with its schema.

8.3 Starting an Inference Service

Double-click a Services leaf node to open the Start Service dialog, which configures and launches a REST inference server for the saved model.

9. AI Agent Panel

The right panel hosts three AI agents, each in its own tab. All agents require an AI service to be configured (see Section 11).

9.1 Clair the Analyst

📊 Clair the Analyst — end-to-end ML/AI assistant

Clair handles the complete data science workflow:

• Automatic ML/AI solutions from natural language requirements
• Data loading from CSV, ARFF, JSON, Avro, Parquet, Iceberg, SQL
• Advanced interactive data visualization
• Model training, evaluation, and ensembling
• Inference server management

9.2 James the Java Guru

☕ James the Java Guru — Java programming assistant

James helps with Java and SMILE-specific code:

• Code completion and generation in the notebook (via Tab)
• Reviewing and explaining Java code
• SMILE API guidance

9.3 Guido the Pythonista

🐍 Guido the Pythonista — Python programming assistant

Guido assists with Python notebooks:

• Code completion and generation
• Python data science library guidance

9.4 Intent Types

Each intent (conversation turn) has a type selector in the footer:

Switch the intent type using the combo box, or use the shortcuts below.

9.5 Slash Commands

Type / followed by a command name and press Ctrl + Enter:

Additional custom slash commands can be defined as agent skills in SMILE.md.

Hint window: As you type a slash command, a hint tooltip appears showing the expected arguments.

9.6 Shell Commands

Set the intent type to Shell (or prefix your input with !) and enter any shell command. On Windows, commands run through powershell.exe -Command; on Unix/macOS, through bash -c. The output is streamed in real time to the output area. A Stop button appears to forcibly terminate long-running processes.

9.7 Long-Term Memory (SMILE.md)

Agents can maintain long-term, project-specific context stored in SMILE.md within the current working directory. This file is automatically loaded into the agent's system prompt. Use /memory add or /memory edit to update it.

Initializing context:

/init

Clair's /init skill creates a SMILE.md file by analysing the project and recording its structure, key decisions, and preferences.

9.8 Reasoning Effort

Each intent input shows a Reasoning Effort combo box. The available levels depend on the configured LLM:

Increasing reasoning effort produces more careful responses at the cost of higher latency and token usage.

9.9 Auto-Compact

If a conversation session exceeds 180,000 tokens (configurable via the system property smile.agent.auto.compact), the agent automatically runs /compact to summarize the conversation and free context window space.

10. Notepad

The Notepad is a standalone text editor window opened for non-notebook files. It is accessible via:

• Double-clicking a non-binary, non-source file in the Project Explorer
• The /edit <file> agent command
• The /memory edit command

Features

11. Settings — AI Service Configuration

Open via File > Settings…. Choose an AI service provider from the drop-down:

All fields (API key, base URL, model) are stored in Java Preferences (OS keychain / registry). API keys set in Settings take precedence over environment variables.

Supported models are listed as suggestions in each provider's combo box; you can also type any model name manually since the fields are editable.

After clicking OK the new LLM instance is initialized immediately.

Security note: API keys are stored in the JVM Preferences store. On macOS this is the system Keychain; on Windows it is the Registry; on Linux it is ~/.java/.userPrefs.

12. Status Bar

The status bar at the bottom of the window displays:

• Left – Status messages from current operations (kernel initialization, LSP startup, MCP connections, file saves, kernel restarts). Messages automatically reset to "Ready" after 60 seconds.
• Right – Live system metrics refreshed every second: JVM heap usage and CPU load percentage.

Ty server initialized                            Heap: 1.2 GB  CPU: 8%

13. Font Size

The monospaced font used in all code editors, output areas, and agent intent panes can be resized globally:

The Markdown rendering font size scales proportionally (by ±0.1 em per step).

14. MCP (Model Context Protocol) Integration

SMILE Studio automatically connects to MCP servers defined in any of the following configuration files at startup (in order):

1. $SMILE_HOME/conf/mcp.json
2. ~/.smile/mcp.json
3. .smile/mcp.json (project-level, in current working directory)

All three files are loaded if they exist; tools from all connected servers become available to agents. Servers are gracefully shut down on application exit.

Example mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/project"]
    },
    "web-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "your_key_here" }
    }
  }
}

15. LSP (Language Server Protocol) Integration

SMILE Studio starts two language servers in the background:

Both servers are started automatically. The jdtls binary is expected at $SMILE_HOME/jdtls/bin/jdtls.

Auto-completion is powered by the LSP providers and activates:

• Automatically after 300 ms of inactivity (configurable)
• On . — immediately triggers member completion for Java and Python

The completion popup is provided by RSyntaxTextArea's AutoCompletion infrastructure wired to a custom LspCompletionProvider.

16. Themes / Look-and-Feel

SMILE Studio uses FlatLaf for its look-and-feel. The theme is stored in application preferences under the key Theme:

Change the theme by setting the Theme preference (e.g., programmatically or via a custom preference editor) and restarting the application.

JetBrains Mono is installed as the default monospaced font via FlatJetBrainsMonoFont.install().

macOS: Full window content mode and transparent title bar are enabled automatically for a native look.

Windows: Per-monitor DPI scaling is disabled (sun.java2d.uiScale=1.0) to prevent blurry icons.

17. Keyboard Shortcuts Reference

Notebook

Notepad

Agent Panel

18. Configuration Files

19. Troubleshooting

"Cannot start SMILE Studio as JVM is running in headless mode"

The display environment is not set. On Linux, ensure DISPLAY is set or run through a desktop session. On CI servers, use a virtual display (Xvfb).

Python kernel fails to start

Ensure ipython is installed in the Python environment on PATH:

pip install ipython
python -c "import IPython; print(IPython.__version__)"

Scala kernel produces no output

The Scala script engine needs the smile.home system property and the classpath to include Scala libraries. Ensure you are launching Studio via the provided smile studio script which sets these properties.

JDT LS / Ty server doesn't start

Check that $SMILE_HOME/jdtls/bin/jdtls exists and is executable. Errors are logged to the application log and shown briefly in the status bar.

AI features not working (Tab completion, code generation, agents)

Open File > Settings… and verify your AI provider credentials. Check the status bar for initialization errors. Ensure network access to the provider's API endpoint is available.

Notebook not saving

If Save shows an error dialog, check file system permissions for the target path. Untitled.java notebooks must be saved via Save As… before auto-save takes effect.

Variables not appearing in Kernel Explorer

The Kernel Explorer refreshes when you switch notebook tabs. Switch away and back, or run a cell to trigger a refresh. Only named (non-scratch) variables appear; JShell scratch variables (e.g., $1, $2) are excluded.

Out-of-memory errors in JShell

The remote JVM is allocated up to 75% of the system RAM (-XX:MaxRAMPercentage=75). On memory-constrained machines, reduce this by restarting the kernel after modifying the heap settings via a //! magic in the first cell, or add JVM options in the launch script.

SMILE Studio is free software under the GNU General Public License v3. For commercial use enquiries contact [email protected].