A high-level library for training, evaluating, and serving binary text classifiers with Axon.
Usage
1. Dataset Inspection & Splitting
data = [
%{text: "This is a positive text", label: 1},
%{text: "This is a negative text", label: 0},
# ... more data
]
# Inspect dataset balance and text statistics:
summary = BinClass.summary(data)
IO.puts(BinClass.format_summary(summary))
# Stratified train / validation split:
{train_data, val_data} = BinClass.Dataset.split(data, validation_split: 0.1, seed: 42)2. Training
classifier = BinClass.train(train_data,
epochs: 5,
labels: %{0 => "negative", 1 => "positive"},
label_smoothing: 0.02
)3. Evaluation
result = BinClass.evaluate(classifier, val_data)
IO.puts(BinClass.format_report(result))4. Serialization
BinClass.save(classifier, "model.bin")5. Prediction & Serving
# Load model as Nx.Serving for concurrent web applications:
serving = BinClass.load("model.bin", compiler: EXLA)
result = Nx.Serving.run(serving, "Some text to classify")
# Or compile an ultra-low latency direct predictor function:
predict = BinClass.compile_predictor(classifier)
result = predict.("Instant prediction")Summary
Functions
Compiles a predictor for one complete document.
Compiles the classifier into a highly optimized, in-process prediction function.
Deserializes a saved model from a binary and returns an Nx.Serving struct.
Deserializes a saved model from a binary and returns a BinClass.Classifier struct.
Evaluates a trained classifier or predictor on a dataset and returns performance metrics.
Formats an evaluation result map into a human-readable text report.
Formats a dataset summary map into a human-readable text report.
Loads a saved model from a file and returns an Nx.Serving struct.
Loads a saved model from a file and returns a BinClass.Classifier struct.
Saves the classifier to a file.
Serializes the classifier to a binary.
Builds an Nx.Serving from a classifier.
Computes summary statistics on a binary classification dataset.
Trains a binary classifier.
Functions
Compiles a predictor for one complete document.
The returned function accepts exactly one string. It splits the entire input into overlapping token windows, predicts every chunk in batches, and returns each chunk's text, zero-based index, encoded token count, active-token count, original start/end byte offsets, and raw classification result.
No text is normalized or truncated. :start_byte is inclusive and
:end_byte is exclusive, and both refer to the exact string passed to the
predictor. Empty or whitespace-only documents return no chunks and
status: :insufficient_input.
The document status is :ok when at least one chunk passes the classifier's
minimum_input_tokens validation. Individual insufficient chunks remain in
the output with their raw probabilities. A chunk's :token_count includes
encoded padding special tokens present in the source; :active_token_count
excludes them and is the value used for minimum-input validation. This
function does not aggregate chunks or apply a document-level decision policy.
Options
:compiler- A module implementingNx.Defn.Compiler. Defaults toEXLA.:batch_size- Positive maximum number of chunks predicted per model invocation. Defaults to16.:chunk_size- Maximum token count per chunk. Defaults to the classifier's vector length and cannot exceed it.:chunk_overlap- Overlap as a non-negative token count below:chunk_size, or as a fraction from0.0up to1.0. Defaults to0.25.
Example
predict =
BinClass.compile_document_predictor(classifier,
chunk_overlap: 128,
batch_size: 32
)
%{status: :ok, chunks: chunks} = predict.(large_document)Compiles the classifier into a highly optimized, in-process prediction function.
This is intended for scenarios where lowest possible latency is required and batching (provided by Nx.Serving) is not necessary (e.g. CLI tools, single-user scripts, or very low-concurrency high-speed inference).
Returns an anonymous function that takes a text (string) or a non-empty list
of texts and returns the classification results. Inputs below the classifier's
minimum_input_tokens return label: :insufficient_input and
confidence: nil, while retaining raw class probabilities. Every result
includes :active_token_count, defined consistently as the number of
truncated token IDs that are not the tokenizer's padding ID.
Options
:compiler- A module implementingNx.Defn.Compiler. Defaults toEXLA.:batch_size- The positive batch size to compile for. Inputs larger than this are processed in chunks. Defaults to 1 (lowest latency).
Deserializes a saved model from a binary and returns an Nx.Serving struct.
Deserializes a saved model from a binary and returns a BinClass.Classifier struct.
Serialized classifiers must contain the complete current schema, including an explicit decision policy and minimum-input validation setting. The stored vocabulary size, padding ID, and unknown-token ID must match the tokenizer JSON.
Evaluates a trained classifier or predictor on a dataset and returns performance metrics.
Delegates to BinClass.Evaluation.evaluate/3.
Formats an evaluation result map into a human-readable text report.
Delegates to BinClass.Evaluation.format_report/1.
Formats a dataset summary map into a human-readable text report.
Delegates to BinClass.Dataset.format_summary/1.
Loads a saved model from a file and returns an Nx.Serving struct.
Loads a saved model from a file and returns a BinClass.Classifier struct.
Saves the classifier to a file.
Serializes the classifier to a binary.
The serialized data includes tokenizer state, its exact vocabulary and special-token IDs, model parameters, labels, vector length, named model architecture and graph revision, training metadata (including target mode and threshold), and the explicit decision policy and minimum-input validation setting.
Builds an Nx.Serving from a classifier.
Model architecture, tokenizer metadata, labels, vector length, decision policy, and minimum-input validation always come from the classifier.
Options
:compiler- A module implementingNx.Defn.Compiler. Defaults toEXLA.:batch_size- The positive serving batch size. Defaults to16.:defn_options- A keyword list passed to the compiled definition. Defaults to[].
Computes summary statistics on a binary classification dataset.
Delegates to BinClass.Dataset.summary/2.
Trains a binary classifier.
Delegates to BinClass.Trainer.train/2. See BinClass.Trainer.train/2 for full option details.