# Project Structure

## Overview

Starting with version 3.0, Apache OpenNLP has been reorganized from a single monolithic `opennlp-tools` artifact into a set of fine-grained modules. This modularization allows users to depend only on the components they actually need, resulting in a smaller dependency footprint. At the same time, the public API remains stable and fully compatible with previous 2.x releases.

The following sections describe each module, its purpose, and when to include it as a dependency.

## API Module

The `opennlp-api` module defines the public interfaces and abstractions that form the contract between OpenNLP and its users. It contains the core interfaces such as `Tokenizer`, `SentenceDetector`, `POSTagger`, `TokenNameFinder`, `Chunker`, `Parser`, `LanguageDetector`, `Lemmatizer`, and `DocumentCategorizer`.

This module also provides shared base classes such as `BaseModel`, the `ObjectStream` abstraction for data processing, the command-line argument parsing framework, and common utility types. It is a transitive dependency of `opennlp-runtime` and typically does not need to be declared explicitly.

    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-api</artifactId>
        <version>CURRENT_OPENNLP_VERSION</version>
    </dependency>

## Runtime Module

The `opennlp-runtime` module is the primary dependency for most users. It contains the core NLP tool implementations including sentence detection, tokenization, part-of-speech tagging, named entity recognition, chunking, parsing, language detection, lemmatization, and document categorization.

By default, `opennlp-runtime` ships with the Maximum Entropy machine learning implementation. If you need other ML algorithms, add the corresponding ML module as described below.

    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-runtime</artifactId>
        <version>CURRENT_OPENNLP_VERSION</version>
    </dependency>

## Machine Learning Modules

The machine learning implementations have been separated into individual modules so that applications can include only the algorithms they use. Each module provides a specific ML algorithm and is loaded at runtime via the `ExtensionLoader` service discovery mechanism.

- `opennlp-ml-commons` — Shared ML utilities and base classes used by all ML algorithm modules. This is a transitive dependency of each ML module and does not need to be declared explicitly.

- `opennlp-ml-maxent` — Maximum Entropy classifier. This is the default algorithm and is included transitively via `opennlp-runtime`.

- `opennlp-ml-perceptron` — Perceptron-based learning algorithm. Add this dependency if your models use the Perceptron or Perceptron Sequence trainer.

- `opennlp-ml-bayes` — Naive Bayes classifier. Add this dependency if your models use the Naive Bayes trainer.

- `opennlp-ml-libsvm` — Support Vector Machine (SVM) based text classification via zlibsvm. This module provides `DocumentCategorizerSVM`, an SVM-based implementation of the `DocumentCategorizer` interface with configurable term weighting (binary, TF, TF-IDF, log-normalized TF), feature selection (information gain, chi-square, term frequency, document frequency), and feature scaling.

For example, to use the Perceptron trainer alongside the default Maximum Entropy, add:

    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-ml-perceptron</artifactId>
        <version>CURRENT_OPENNLP_VERSION</version>
    </dependency>

## Models Module

The `opennlp-model-resolver` module provides classpath-based model discovery and loading. It enables applications to bundle pre-trained OpenNLP models as JAR files and load them at runtime without explicit file path references. See for details on classpath model loading.

    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-model-resolver</artifactId>
        <version>CURRENT_OPENNLP_VERSION</version>
    </dependency>

## Formats Module

The `opennlp-formats` module supports reading and writing various NLP training and evaluation data formats, including CoNLL, BioNLP, BRAT, AD (Floresta), Leipzig, and others. Include this module if you need to train models from data in non-native OpenNLP formats.

    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-formats</artifactId>
        <version>CURRENT_OPENNLP_VERSION</version>
    </dependency>

## Deep Learning Modules

OpenNLP provides optional support for ONNX-based neural models via two modules:

- `opennlp-dl` — Integrates the ONNX Runtime for CPU-based inference. This module enables the use of models trained by external frameworks such as PyTorch or TensorFlow, exported in the ONNX format.

- `opennlp-dl-gpu` — Replaces the CPU ONNX Runtime with the GPU-accelerated variant for systems with supported GPU hardware. Use this module instead of `opennlp-dl` when GPU acceleration is available and desired.

    <!-- CPU variant -->
    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-dl</artifactId>
        <version>CURRENT_OPENNLP_VERSION</version>
    </dependency>

    <!-- OR GPU variant (do not include both) -->
    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-dl-gpu</artifactId>
        <version>CURRENT_OPENNLP_VERSION</version>
    </dependency>

## CLI Module

The `opennlp-cli` module provides the command-line tools for training, evaluating, and running OpenNLP models from a terminal. It is included in the binary distribution and not typically needed as a library dependency. See for details on available CLI commands.

## Tools Module (Aggregated Jar)

The `opennlp-tools` module is an aggregated artifact that bundles all core modules (`opennlp-api`, `opennlp-runtime`, all ML modules, `opennlp-model-resolver`, `opennlp-formats`, and `opennlp-cli`) into a single JAR. It is provided for backwards compatibility with 2.x and for the binary distribution.

For new projects, we recommend depending on `opennlp-runtime` plus only the specific additional modules you need, rather than pulling in the full `opennlp-tools` artifact.

## Extension Modules

OpenNLP provides optional extension modules for integration with external frameworks:

- `opennlp-morfologik` — Integrates the Morfologik library for dictionary-based stemming and lemmatization. See for usage details.

- `opennlp-spellcheck` — Provides a native, language-agnostic spell corrector based on the SymSpell (Symmetric Delete) algorithm, including CLI tools, a pluggable edit distance, and pipeline integration. See for usage details.

- `opennlp-uima` — Provides a set of Apache UIMA annotators that wrap OpenNLP components for use in UIMA pipelines. See for integration details.

## Migrating from 2.x to 3.x

The 3.x release introduces no known breaking API changes. Existing code using the `opennlp-tools` artifact will continue to work without modification. However, we strongly recommend migrating to the modular dependency structure for a smaller footprint.

A minimal migration replaces:

    <!-- 2.x: single monolithic dependency -->
    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-tools</artifactId>
        <version>2.x.y</version>
    </dependency>

with:

    <!-- 3.x: modular dependencies — add only what you need -->
    <dependency>
        <groupId>org.apache.opennlp</groupId>
        <artifactId>opennlp-runtime</artifactId>
        <version>CURRENT_OPENNLP_VERSION</version>
    </dependency>
    <!-- Add opennlp-model-resolver, opennlp-ml-perceptron, opennlp-dl, etc. as needed -->

The `opennlp-runtime` module includes the Maximum Entropy ML implementation by default. If your models were trained with the Perceptron or Naive Bayes algorithm, add the corresponding `opennlp-ml-perceptron` or `opennlp-ml-bayes` dependency.