# Statistical Machine Intelligence & Learning Engine
[](https://central.sonatype.com/artifact/com.github.haifengl/smile-core)
[](https://github.com/haifengl/smile/actions/workflows/ci.yml)
SMILE (Statistical Machine Intelligence & Learning Engine) is a comprehensive,
high-performance machine learning framework for the JVM. SMILE v5+ requires
**Java 25**; v4.x requires Java 21; all previous versions require Java 8.
SMILE also provides idiomatic APIs for **Scala** and **Kotlin**.
With advanced data structures and algorithms, SMILE delivers state-of-the-art
performance across every aspect of machine learning.
SMILE Studio is an agentic IDE for data science using Python, Java, or Scala.
See [studio/README.md](studio/README.md) how to get your first project up and
start interacting with your data with natural language in a few minutes.
---
## Table of Contents
1. [Features](#features)
2. [Module Map](#module-map)
3. [Installation](#installation)
- [Maven](#maven)
- [SBT (Scala)](#sbt-scala)
- [Gradle (Kotlin)](#gradle-kotlin)
- [Native Libraries (BLAS / LAPACK)](#native-libraries-blas--lapack)
4. [Quick Start](#quick-start)
5. [SMILE Studio & Shell](#smile-studio--shell)
6. [Model Serialization](#model-serialization)
7. [Visualization](#visualization)
8. [License](#license)
9. [Issues & Discussions](#issues--discussions)
10. [Contributing](#contributing)
11. [Maintainers](#maintainers)
12. [Gallery](#gallery)
---
## Features
| Area | Highlights |
|---|---|
| **LLM** | LLaMA-3 inference, tiktoken BPE tokenizer, OpenAI-compatible REST server, SSE chat streaming |
| **Deep Learning** | LibTorch/GPU backend, EfficientNet-V2 image classification, custom layer API |
| **Classification** | SVM, Decision Trees, Random Forest, AdaBoost, Gradient Boosting, Logistic Regression, Neural Networks, RBF Networks, MaxEnt, KNN, Naïve Bayes, LDA/QDA/RDA |
| **Regression** | SVR, Gaussian Process, Regression Trees, GBDT, Random Forest, RBF, OLS, LASSO, ElasticNet, Ridge |
| **Clustering** | BIRCH, CLARANS, DBSCAN, DENCLUE, Deterministic Annealing, K-Means, X-Means, G-Means, Neural Gas, Growing Neural Gas, Hierarchical, SIB, SOM, Spectral, Min-Entropy |
| **Manifold Learning** | IsoMap, LLE, Laplacian Eigenmap, t-SNE, UMAP, PCA, Kernel PCA, Probabilistic PCA, GHA, Random Projection, ICA |
| **Feature Engineering** | Genetic Algorithm selection, Ensemble selection, TreeSHAP, SNR, Sum-Squares ratio, data transformations, formula API |
| **NLP** | Sentence / word tokenization, Bigram test, Phrase & Keyword extraction, Stemmer, POS tagging, Relevance ranking |
| **Association Rules** | FP-growth frequent itemset mining |
| **Sequence Learning** | Hidden Markov Model, Conditional Random Field |
| **Nearest Neighbor** | BK-Tree, Cover Tree, KD-Tree, SimHash, LSH |
| **Numerical Methods** | Linear algebra, numerical optimization (BFGS, L-BFGS), interpolation, wavelets, RBF, distributions, hypothesis tests |
| **Visualization** | Swing plots (scatter, line, bar, box, histogram, surface, heatmap, contour, …) and declarative Vega-Lite charts |
---
## Module Map
Each module has its own detailed user guide. Click the **README** link for
the module overview, or drill into individual topic guides.
### `base/` — Foundation
> Data structures, math, linear algebra, statistical utilities, I/O
| Document | Topics |
|---|---|
| [README](base/README.md) | Module overview and dependency setup |
| [DATA_FRAME.md](base/DATA_FRAME.md) | DataFrame API — creation, selection, transformation |
| [DATA_IO.md](base/DATA_IO.md) | CSV, JSON, Parquet, Arrow, JDBC, Avro readers/writers |
| [DATA_TRANSFORMATION.md](base/DATA_TRANSFORMATION.md) | Scalers, encoders, imputers, feature transforms |
| [DATASET.md](base/DATASET.md) | Built-in benchmark and real-world datasets |
| [FORMULA.md](base/FORMULA.md) | R-style formula language for model matrices |
| [DISTRIBUTIONS.md](base/DISTRIBUTIONS.md) | Probability distributions (Normal, Poisson, Beta, …) |
| [HYPOTHESIS_TESTING.md](base/HYPOTHESIS_TESTING.md) | t-test, chi-squared, ANOVA, KS-test, … |
| [DISTANCES.md](base/DISTANCES.md) | Euclidean, Mahalanobis, Hamming, edit distance, … |
| [NEAREST_NEIGHBOR.md](base/NEAREST_NEIGHBOR.md) | KD-Tree, Cover Tree, BK-Tree, LSH |
| [KERNELS.md](base/KERNELS.md) | Gaussian, polynomial, Laplacian, and other kernel functions |
| [RBF.md](base/RBF.md) | Radial basis function networks |
| [INTERPOLATION.md](base/INTERPOLATION.md) | Linear, cubic spline, bilinear, bicubic |
| [GRAPH.md](base/GRAPH.md) | Adjacency list/matrix graph, BFS/DFS, spanning trees |
| [SORT.md](base/SORT.md) | Quick sort, heap sort, counting sort, index sort |
| [HASH.md](base/HASH.md) | Locality-sensitive hashing, SimHash |
| [RNG.md](base/RNG.md) | Random number generators, sampling, permutations |
| [BFGS.md](base/BFGS.md) | L-BFGS and BFGS numerical optimizers |
| [ICA.md](base/ICA.md) | Independent Component Analysis |
| [TENSOR.md](base/TENSOR.md) | N-dimensional array (CPU tensor without LibTorch) |
| [WAVELET.md](base/WAVELET.md) | DWT, CWT, and wavelet families |
| [GAP.md](base/GAP.md) | GAP statistic for optimal cluster count estimation |
| [COMPRESSED_SENSING.md](base/COMPRESSED_SENSING.md) | Compressed sensing and basis pursuit |
### `core/` — Machine Learning Algorithms
> Classification, regression, clustering, manifold learning, and more
| Document | Topics |
|---|---|
| [README](core/README.md) | Module overview |
| [CLASSIFICATION.md](core/CLASSIFICATION.md) | SVM, Random Forest, AdaBoost, GBDT, KNN, Naïve Bayes, LDA, … |
| [REGRESSION.md](core/REGRESSION.md) | SVR, Gaussian Process, LASSO, Ridge, ElasticNet, GBDT, … |
| [CLUSTERING.md](core/CLUSTERING.md) | K-Means, DBSCAN, BIRCH, SOM, Spectral Clustering, … |
| [FEATURE_ENGINEERING.md](core/FEATURE_ENGINEERING.md) | Feature selection, PCA, ICA, projection, encoding |
| [MANIFOLD.md](core/MANIFOLD.md) | t-SNE, UMAP, IsoMap, LLE, Laplacian Eigenmap |
| [ANOMALY_DETECTION.md](core/ANOMALY_DETECTION.md) | IsolationForest, one-class SVM, local outlier factor |
| [ASSOCIATION_RULE_MINING.md](core/ASSOCIATION_RULE_MINING.md) | FP-growth, association rules, frequent itemsets |
| [SEQUENCE.md](core/SEQUENCE.md) | HMM (Baum-Welch, Viterbi), CRF |
| [TIME_SERIES.md](core/TIME_SERIES.md) | ARIMA, box-plots, autocorrelation |
| [REGRESSION.md](core/REGRESSION.md) | Full regression API reference |
| [TRAINING.md](core/TRAINING.md) | Cross-validation, bootstrap, hyper-parameter search |
| [VALIDATION.md](core/VALIDATION.md) | Hold-out, k-fold, leave-one-out evaluation |
| [VALIDATION_METRICS.md](core/VALIDATION_METRICS.md) | Accuracy, AUC, F1, RMSE, MAE, confusion matrix |
| [HYPER_PARAMETER_OPTIMIZATION.md](core/HYPER_PARAMETER_OPTIMIZATION.md) | Grid search, random search, Bayesian optimization |
| [VECTOR_QUANTIZATION.md](core/VECTOR_QUANTIZATION.md) | LVQ, Neural Gas, SOM as vector quantizers |
| [ONNX.md](core/ONNX.md) | Exporting and importing models via ONNX |
### `deep/` — Deep Learning & LLMs
> LibTorch-backed GPU/CPU tensor operations, neural network layers, LLaMA-3 inference, EfficientNet
| Document | Topics |
|---|---|
| [README](deep/README.md) | Full deep-learning & LLM user guide (tensors, layers, loss, optimizer, EfficientNet, LLaMA) |
The `deep/README.md` covers:
- **`smile.deep.tensor`** — Tensor factory, indexing, arithmetic, AutoScope memory management, dtype/device
- **`smile.deep.layer`** — Linear, Conv2d, pooling, normalization (BN/GN/RMS), dropout, embedding, sequential blocks
- **`smile.deep.activation`** — ReLU, GELU, SiLU, Tanh, Sigmoid, Softmax, GLU, HardShrink, …
- **`smile.deep.Loss`** — MSE, cross-entropy, BCE, Huber, KL, hinge, and more
- **`smile.deep.Optimizer`** — SGD, Adam, AdamW, RMSprop
- **`smile.deep.Model`** — Abstract base class + training loop
- **`smile.deep.metric`** — Accuracy, Precision, Recall, F1Score with macro/micro/weighted averaging
- **`smile.llm`** — `Message`, `Role`, `FinishReason`, `ChatCompletion` records; sinusoidal & RoPE positional encodings
- **`smile.llm.tokenizer`** — `Tokenizer` interface, `Tiktoken` BPE implementation (LLaMA-3 compatible)
- **`smile.llm.model.llama`** — Full LLaMA-3 stack: `Llama.build()`, `generate()`, `chat()`, streaming via `SubmissionPublisher`
- **`smile.vision`** — `VisionModel`, `ImageDataset`, `EfficientNet.V2S/M/L()` pretrained models, ImageNet labels
- **`smile.vision.transform`** — `Transform` interface, `ImageClassification` pipeline, resize/crop/toTensor helpers
### `nlp/` — Natural Language Processing
> Text normalization, tokenization, POS tagging, stemming, relevance ranking
| Document | Topics |
|---|---|
| [README](nlp/README.md) | Module overview |
| [TOKENIZER.md](nlp/TOKENIZER.md) | Sentence splitter, word tokenizer, regex tokenizer |
| [POS.md](nlp/POS.md) | Part-of-speech tagging (Brill tagger, HMM tagger) |
| [STEM.md](nlp/STEM.md) | Porter, Lancaster, Lovins stemmers; lemmatization |
| [COLLOCATION.md](nlp/COLLOCATION.md) | Bigram/trigram statistical tests, phrase extraction |
| [RELEVANCE.md](nlp/RELEVANCE.md) | TF-IDF, BM25, keyword extraction |
| [TAXONOMY.md](nlp/TAXONOMY.md) | WordNet integration, synsets, hypernyms |
### `plot/` — Data Visualization
> Swing-based interactive plots and declarative Vega-Lite charts
| Document | Topics |
|---|---|
| [README](plot/README.md) | Swing plotting API — scatter, line, bar, box, histogram, heatmap, surface, contour, wireframe |
| [VEGA.md](plot/VEGA.md) | Declarative `smile.plot.vega` (Vega-Lite) — JSON spec generation, web/Jupyter rendering |
### `serve/` — Inference Server
> Quarkus-based REST inference service with OpenAI-compatible API and SSE streaming
| Document | Topics |
|---|---|
| [README](serve/README.md) | Building and running the server, `/chat/completions` endpoint, SSE streaming, configuration |
### `studio/` — Interactive Shell & Desktop IDE
> An agentic IDE for data science using Python or SMILE
| Document | Topics |
|-------------------------------|---|
| [README.md](studio/README.md) | Desktop Studio UX |
| [CLI](studio/CLI.md) | CLI entry points (`smile`, `smile shell`, `smile scala`, `smile serve`) |
### `scala/` — Scala API
> Idiomatic Scala shim — concise wrappers, symbolic operators, Scala collections integration
| Document | Topics |
|---|---|
| [README](scala/README.md) | API overview, `smile.classification`, `smile.regression`, `smile.clustering`, `smile.plot` in Scala |
### `kotlin/` — Kotlin API
> Idiomatic Kotlin shim — extension functions, named parameters, builder DSLs
| Document | Topics |
|---|---|
| [README](kotlin/README.md) | API overview, extension functions, Kotlin-style builders |
| [packages.md](kotlin/packages.md) | Full package-by-package listing of all Kotlin extension functions |
### `json/` — JSON Library (Scala)
> Lightweight zero-dependency JSON library for Scala with a clean DSL
| Document | Topics |
|---|---|
| [README](json/README.md) | Parsing, building, pattern matching, path navigation, serialization |
### `spark/` — Apache Spark Integration
> Use SMILE models inside Spark ML pipelines
| Document | Topics |
|---|---|
| [README](spark/README.md) | `SmileTransformer`, `SmileClassifier`, `SmileRegressor`; training and scoring in Spark DataFrames |
---
## Installation
### Maven
```xml