Vyntri

Classify images without training. Extract features from a pretrained backbone, project them analytically, and classify -- all in 4 lines of Python.

from vyntri import Vyntri
from vyntri.data import split

s = split("./my-dataset", train=0.7, test=0.2, seed=42)
model = Vyntri()
model.fit(train=s.train, val=s.val)
model.predict("./image.jpg")  # Prediction(label=cat, confidence=0.94)

No GPU required. No training loops. Useful defaults require little or no tuning.

Table of Contents

• Why Vyntri?
• Quick Start
• How It Works
• After Fitting
• Configuration
• Custom Backbones
• Fine-Tuning
• API Reference
• Examples
• Installation

Why Vyntri?

Vyntri replaces the training loop with analytic (closed-form) projection and classification. The result is fast to fit, resistant to overfitting (no gradient loops to memorize noise), and works on small datasets where traditional training fails.

Quick Start

1. Prepare your dataset

Organize images into folders by class name:

my-dataset/
  cats/
    cat_001.jpg
    cat_002.jpg
  dogs/
    dog_001.jpg
  birds/
    bird_001.jpg

Recommended: At least 10 images per class for good results.

2. Split, fit, and predict

from vyntri import Vyntri
from vyntri.data import split

# Create an explicit train/val/test split (no files copied)
s = split("./my-dataset", train=0.7, test=0.2, seed=42)

model = Vyntri()
model.fit(train=s.train, val=s.val)

result = model.predict("./test-photo.jpg")
print(result.label)       # cats
print(result.confidence)  # 0.94

3. Evaluate on the held-out test set

result = model.evaluate(s.test)
print(result.accuracy)    # 0.91
print(result.macro_f1)    # Per-class F1 (macro-averaged)
print(result.per_class)   # Per-class precision/recall/F1

4. Save and reload

model.save("./my-model.vyntri")
model = Vyntri.load("./my-model.vyntri")
model.predict("./new-image.jpg")

How It Works

Image
  |
Pretrained backbone (frozen)    <- extracts features, no training
  |
Analytic projection              <- closed-form dim reduction
  |
Shrinkage estimation             <- stabilizes covariance
  |
Analytic Ridge classifier        <- closed-form weights
  |
Prediction

Every step is analytic -- mathematically derived, not learned through gradient descent:

• Low overfitting risk -- analytic fitting avoids iterative gradient-based optimization
• No GPU needed -- CPU matrix ops are fast enough
• Sensible defaults -- few or no parameters to tune for common workflows
• Designed for determinism -- analytic fitting on fixed data and config produces consistent results

The pretrained backbone provides general visual features. Vyntri never modifies it -- it only learns the projection and classifier on top.

After Fitting

Model info

model.classes_           # ["cats", "dogs", "birds"]
model.class_to_idx_      # {"cats": 0, "dogs": 1, "birds": 2}
model.feature_dim_       # 576 (backbone feature dimension)
model.state              # "fitted", "fine_tuned", etc.

Predictions

result = model.predict("./image.jpg")
result.label            # cats
result.confidence       # 0.94

Batch predictions

results = model.predict_batch(["./img1.jpg", "./img2.jpg", "./img3.jpg"])
for path, label, conf in zip(results.paths, results.labels, results.confidences):
    print(f"{label}: {conf:.1%}")

Inspect internals

model.config             # Current configuration
model.fitted_config      # Config that produced this fit
model.projection_        # Learned projection matrix
model.classifier_        # Learned classifier weights
model.validation_accuracy_

Configuration

from vyntri import Vyntri
from vyntri.data import split

# All parameters can be passed directly as kwargs
model = Vyntri(
    backbone="auto",
    adaptation="fk",
    shrinkage="diagonal",
    cache_dir="./vyntri-cache",
)

s = split("./dataset", train=0.7, test=0.2, seed=42)
model.fit(train=s.train, val=s.val)

Config.describe()  # Returns structured docs for all parameters

Key configuration groups

Custom Backbones

from vyntri import Vyntri
from vyntri.data import split

# Use a larger backbone by name
s = split("./dataset", train=0.7, test=0.2, seed=42)
model = Vyntri(backbone="resnet50")
model.fit(s)

Fine-Tuning

For the highest accuracy on your specific domain:

from vyntri.data import split

s = split("./dataset", train=0.7, test=0.2, seed=42)
model.fit(train=s.train, val=s.val)
model.fine_tune(s, epochs=10, lr=1e-3, scope="last_layer")

Note: Fine-tuning requires a GPU for reasonable speed.

API Reference

Examples

Image classification

from vyntri import Vyntri
from vyntri.data import split

s = split("./flowers", train=0.7, test=0.2, seed=42)
model = Vyntri()
model.fit(train=s.train, val=s.val)
print(model.classes_)  # ["daisy", "rose", "sunflower", "tulip"]

result = model.predict("./test-rose.jpg")
print(result.label, result.confidence)

Incremental learning

from vyntri import Vyntri
from vyntri.data import split
from vyntri.data.dataset import FolderDataset

s = split("./dataset-v1", train=0.7, test=0.2, seed=42)
model = Vyntri()
model.fit(train=s.train, val=s.val)

# update() accepts FolderDataset, Path, or string
new_data = FolderDataset("./dataset-v2")
model.update(new_data)  # Adds new data without forgetting

Comparing backbones

from vyntri import Vyntri
from vyntri.data import split

s = split("./dataset", train=0.7, test=0.2, seed=42)
for name, bb in [("mobile", "mobilenet_v3_small"), ("resnet", "resnet50")]:
    model = Vyntri(backbone=bb)
    model.fit(train=s.train, val=s.val)
    print(name, model.validation_accuracy_)

Installation

pip install vyntri

Requirements: Python 3.9+, PyTorch, torchvision

Optional for fine-tuning: CUDA-capable GPU

Migrating from v1.1.x

v1.4.0: Explicit dataset roles and adaptation

fit() now requires explicit train= and optional val= parameters. SplitResult is no longer accepted directly — use s.train and s.val explicitly. adaptation= replaces whitening= as the canonical config name (old name still works with deprecation warning).

# v1.3.x (deprecated)
s = split("./my-dataset", train=0.7, test=0.2, seed=42)
model = Vyntri(whitening="fk")
model.fit(s)

# v1.4.0 (recommended)
s = split("./my-dataset", train=0.7, test=0.2, seed=42)
model = Vyntri(adaptation="fk")
model.fit(train=s.train, val=s.val)

v1.2.0: Explicit dataset splitting

vyntri.data.split() replaces implicit automatic splitting.

v1.3.0: API consistency and stability

• update(), fine_tune(), and analyze() accept FolderDataset, Path, or strings.
• save()/load() preserves training history and class registry.
• loaded.state reflects the pre-save state ("fitted", "updated", or "fine_tuned").
• Scheduled fit with no validation set no longer crashes.
• Corrupt images raise DatasetError instead of raw PIL tracebacks.

Vyntri -- classify images without training.