kjarni::classifier

High-level text classification API.

This module provides a simple interface for text classification tasks like sentiment analysis, topic classification, and more.

Quick Start

use kjarni::classifier;

// One-liner
let result = classifier::classify("sentiment-model", "I love this!").await?;
println!("{}: {:.1}%", result.label, result.score * 100.0);

// With builder
let classifier = Classifier::builder("sentiment-model")
    .gpu()
    .top_k(3)
    .build()
    .await?;

let results = classifier.classify("Great product!").await?;

Batch Classification

let texts = ["I love it", "Terrible experience", "It's okay"];
let results = classifier.classify_batch(&texts).await?;

ClassificationOverrides

pub struct ClassificationOverrides

Overrides for classification behavior.

Fields

• pub top_k: Option<usize>,: Return only top K results (default: all).
• pub threshold: Option<f32>,: Minimum confidence threshold (0.0-1.0). Results below this threshold are filtered out.
• pub return_logits: bool,: Return raw logits instead of probabilities.
• pub max_length: Option<usize>,: Maximum sequence length (truncates input).
• pub batch_size: Option<usize>,: Batch size for inference (memory vs speed tradeoff).

top_1

pub fn top_1() -> Self

Create overrides that return only the top result.

with_threshold

pub fn with_threshold(threshold: f32) -> Self

Create overrides with a confidence threshold.

multi_label

pub fn multi_label(threshold: f32) -> Self

Create overrides for multi-label with threshold.

ClassificationResult

pub struct ClassificationResult

Result of classifying a single text.

Fields

• pub label: String,: The predicted label (highest score).
• pub score: f32,: Confidence score for the predicted label (0.0 - 1.0).
• pub all_scores: Vec<(String, f32)>,: All labels with their scores, sorted by score descending.
• pub label_index: usize,: Index of the predicted label in the original label list.

from_scores

pub fn from_scores(mut scores: Vec<(String, f32)>) -> Option<Self>

Create from a list of (label, score) pairs.

from_scores_with_labels

pub fn from_scores_with_labels(scores: &[f32], labels: &[String]) -> Option<Self>

Create from scores with explicit labels.

top_k

pub fn top_k(&self, k: usize) -> Vec<(String, f32)>

Get the top K predictions.

is_confident

pub fn is_confident(&self, threshold: f32) -> bool

Check if the top prediction exceeds a confidence threshold.

above_threshold

pub fn above_threshold(&self, threshold: f32) -> Vec<(String, f32)>

Get predictions above a threshold (for multi-label scenarios).

Classifier

pub struct Classifier

High-level text classifier.

Wraps a SequenceClassifier with a simpler API and sensible defaults.

builder

pub fn builder(model: impl Into<String>) -> ClassifierBuilder

Create a builder for a model.

from_preset

pub fn from_preset(preset: &ClassifierPreset) -> ClassifierBuilder

Create a builder from a preset.

new

pub async fn new(model: &str) -> ClassifierResult<Self>

Create a Classifier with default settings.

Uses CPU, downloads model if needed.

from_path

pub fn from_path(path: impl Into<std::path::PathBuf>) -> ClassifierBuilder

Load a classifier from a local path.

Example

let classifier = Classifier::from_path("/models/icebert")
    .labels(vec!["neikvætt", "jákvætt"])
    .build()
    .await?;

classify

pub async fn classify(&self, text: &str) -> ClassifierResult<ClassificationResult>

Classify a single text.

classify_with_config

pub async fn classify_with_config(&self, text: &str, overrides: &ClassificationOverrides) -> ClassifierResult<ClassificationResult>

Classify with custom overrides.

classify_batch

pub async fn classify_batch(&self, texts: &[&str]) -> ClassifierResult<Vec<ClassificationResult>>

Classify multiple texts.

classify_batch_with_config

pub async fn classify_batch_with_config(&self, texts: &[&str], overrides: &ClassificationOverrides) -> ClassifierResult<Vec<ClassificationResult>>

Classify multiple texts with custom overrides. Returns one result per text, in order, each the same as classifying that text alone.

The texts go through the model together, and the scores go through the same post-processing as a single text's, so a text with nothing above the threshold still keeps its place in the results.

classify_scores

pub async fn classify_scores(&self, text: &str) -> ClassifierResult<Vec<f32>>

Get raw classification scores without labels.

model_id

pub fn model_id(&self) -> &str

Get the model identifier.

model_type

pub fn model_type(&self) -> Option<ModelType>

Get the model type (None if loaded from path).

model_name

pub fn model_name(&self) -> &str

Get the model's CLI name (if from registry).

architecture

pub fn architecture(&self) -> &str

device

pub fn device(&self) -> Device

Get the device.

labels

pub fn labels(&self) -> Option<Vec<String>>

Get the label names.

num_labels

pub fn num_labels(&self) -> usize

Get the number of labels.

max_seq_length

pub fn max_seq_length(&self) -> usize

Get maximum sequence length.

mode

pub fn mode(&self) -> ClassificationMode

Get classification mode.

has_custom_labels

pub fn has_custom_labels(&self) -> bool

Check if using custom labels.

ClassifierBuilder

pub struct ClassifierBuilder

Builder for configuring and constructing a Classifier.

Example

// From registry
let classifier = Classifier::builder("sentiment-model")
    .gpu()
    .top_k(3)
    .build()
    .await?;

// From local path with custom labels
let classifier = Classifier::builder("icebert")
    .model_path("/path/to/icebert")
    .labels(vec!["neikvætt", "jákvætt"])
    .build()
    .await?;

new

pub fn new(model: impl Into<String>) -> Self

Create a new builder for the specified model.

The model can be a registry name (e.g., "minilm-l6-v2-cross-encoder") or a path hint when combined with model_path().

from_preset

pub fn from_preset(preset: &ClassifierPreset) -> Self

Create a builder from a preset.

cpu

pub fn cpu(mut self) -> Self

Run on CPU

gpu

pub fn gpu(mut self) -> Self

Run on GPU.

auto_device

pub fn auto_device(mut self) -> Self

Automatically select best device.

with_context

pub fn with_context(mut self, context: Arc<WgpuContext>) -> Self

Provide a pre-created WgpuContext.

cache_dir

pub fn cache_dir(mut self, path: impl Into<PathBuf>) -> Self

Set custom cache directory for registry models.

model_path

pub fn model_path(mut self, path: impl Into<PathBuf>) -> Self

Load model from a local path instead of registry

load_config

pub fn load_config(mut self, config: LoadConfig) -> Self

Set model loading configuration.

with_load_config

pub fn with_load_config<F>(mut self, f: F) -> Self where F: FnOnce(LoadConfigBuilder) -> LoadConfigBuilder,

Configure loading with a builder.

dtype

pub fn dtype(mut self, dtype: DType) -> Self

Set target data type for model weights.

f16

pub fn f16(mut self) -> Self

Use float16 precision.

bf16

pub fn bf16(mut self) -> Self

Use bfloat16 precision.

download_policy

pub fn download_policy(mut self, policy: DownloadPolicy) -> Self

Set download policy.

offline

pub fn offline(mut self) -> Self

Never download models.

labels

pub fn labels<S: Into<String>>(mut self, labels: Vec<S>) -> Self

Set custom labels for the model.

Labels must be in the same order as the model's output indices.

labels_str

pub fn labels_str(mut self, labels: &str) -> Self

Set labels from a comma-separated string.

label_config

pub fn label_config(mut self, config: LabelConfig) -> Self

Set a full label configuration.

sentiment_labels

pub fn sentiment_labels(mut self) -> Self

Use standard binary sentiment labels.

sentiment_3class_labels

pub fn sentiment_3class_labels(mut self) -> Self

Use standard 3-class sentiment labels.

mode

pub fn mode(mut self, mode: ClassificationMode) -> Self

Set classification mode.

single_label

pub fn single_label(mut self) -> Self

Use single-label classification (softmax, default).

multi_label

pub fn multi_label(mut self) -> Self

Use multi-label classification (sigmoid).

Each label is predicted independently.

top_k

pub fn top_k(mut self, k: usize) -> Self

Set default top_k for results.

threshold

pub fn threshold(mut self, threshold: f32) -> Self

Set default confidence threshold.

return_logits

pub fn return_logits(mut self, return_logits: bool) -> Self

Return raw logits instead of probabilities.

max_length

pub fn max_length(mut self, max_length: usize) -> Self

Set maximum sequence length (truncation).

batch_size

pub fn batch_size(mut self, batch_size: usize) -> Self

Set batch size for inference.

overrides

pub fn overrides(mut self, overrides: ClassificationOverrides) -> Self

Apply full overrides.

quiet

pub fn quiet(mut self, quiet: bool) -> Self

Suppress non-error output.

build

pub async fn build(self) -> ClassifierResult<Classifier>

Build the Classifier.

ClassifierPreset

pub struct ClassifierPreset

A classification model preset.

Fields

• pub name: &'static str,: Preset name.
• pub model: &'static str,: CLI model name.
• pub architecture: &'static str,: Architecture type (roberta)
• pub task: ClassificationTask,: Classification task type.
• pub labels: Option<&'static [&'static str]>,: Expected label names (if known).
• pub recommended_device: KjarniDevice,: Recommended device.
• pub memory_mb: usize,: Approximate memory usage in MB.
• pub description: &'static str,: Description.

ClassifierError

pub enum ClassifierError

Errors specific to classification.

Variants

• UnknownModel(String),: Model not found in registry.
• IncompatibleModel: Model cannot perform classification.
• ModelNotDownloaded(String),: Model not downloaded.
• ModelPathNotFound(String),: Model path not found.
• DownloadFailed: Download failed.
• LoadFailed: Load failed.
• ClassificationFailed(#[from] anyhow::Error),: Classification failed.
• GpuUnavailable,: GPU unavailable.
• NoLabels,: No labels configured.
• InvalidLabels(String),: Invalid label configuration.
• InvalidConfig(String),: Invalid configuration.

ClassifierResult

pub type ClassifierResult<T> = Result<T, ClassifierError>

Result type for classifier operations.

ClassifierTier

pub enum ClassifierTier

General classifier tier (for when task is unknown). Defaults to sentiment as the most common use case.

Variants

• Fast,: Fastest model
• Balanced,: Balanced speed/accuracy

resolve

pub fn resolve(&self) -> &'static ClassifierPreset

Resolve tier to default preset (defaults to sentiment).

available_models

pub fn available_models() -> Vec<&'static str>

List all available classifier models.

classify

pub async fn classify(model: &str, text: &str) -> ClassifierResult<ClassificationResult>

Classify a single text using the specified model.

Example

let result = kjarni::classifier::classify("sentiment-model", "I love this!").await?;
println!("{}: {:.2}%", result.label, result.score * 100.0);

classify_preset

pub async fn classify_preset(preset: &ClassifierPreset, text: &str) -> ClassifierResult<ClassificationResult>

Classify with a preset.

is_classifier_model

pub fn is_classifier_model(model: &str) -> ClassifierResult<()>

Check if a model is valid for classification.

classifier::presets

Versioned presets for classification models.

ALL_V1_PRESETS

pub const ALL_V1_PRESETS: &[&ClassifierPreset] = &[ // Sentiment &SENTIMENT_BINARY_V1, &SENTIMENT_3CLASS_V1, &SENTIMENT_5STAR_V1, // Emotion &EMOTION_V1, &EMOTION_DETAILED_V1, // Toxicity &TOXICITY_V1, ]

All V1 presets.

ClassificationTask

pub enum ClassificationTask

Type of classification task.

Variants

• Sentiment,
• Emotion,
• Toxicity,

EMOTION_DETAILED_V1

pub const EMOTION_DETAILED_V1: ClassifierPreset = ClassifierPreset

28 fine-grained emotions (multi-label)

EMOTION_V1

pub const EMOTION_V1: ClassifierPreset = ClassifierPreset

7 basic emotions

EmotionTier

pub enum EmotionTier

Tier-based preset selection for emotion detection.

Variants

• Basic,: 7 basic emotions
• Detailed,: 28 fine-grained emotions

resolve

pub fn resolve(&self) -> &'static ClassifierPreset

Resolve tier to default preset.

SENTIMENT_3CLASS_V1

pub const SENTIMENT_3CLASS_V1: ClassifierPreset = ClassifierPreset

3-class sentiment (negative/neutral/positive)

SENTIMENT_5STAR_V1

pub const SENTIMENT_5STAR_V1: ClassifierPreset = ClassifierPreset

5-star sentiment (multilingual)

SENTIMENT_BINARY_V1

pub const SENTIMENT_BINARY_V1: ClassifierPreset = ClassifierPreset

Binary sentiment (positive/negative) - fastest

SentimentTier

pub enum SentimentTier

Tier-based preset selection for sentiment analysis.

Variants

• Fast,: Fastest, binary (positive/negative)
• Balanced,: Balanced, 3-class (negative/neutral/positive)
• Detailed,: Most detailed, 5-star multilingual

resolve

pub fn resolve(&self) -> &'static ClassifierPreset

Resolve tier to default preset.

TOXICITY_V1

pub const TOXICITY_V1: ClassifierPreset = ClassifierPreset

Toxicity detection (multi-label)

find_preset

pub fn find_preset(name: &str) -> Option<&'static ClassifierPreset>

Find a preset by name.