vyntri

Vyntri(**kwargs)

Main entry point. Validated defaults, configurable by design. Pass keyword arguments that override Config fields (e.g. Vyntri(backbone='auto'), Vyntri(adaptation='slce')).

Supported backbones

Automatic backbone selection with candidates

When backbone="auto", you can limit which backbones are evaluated:

model = Vyntri(
    backbone="auto",
    candidates=[
        "mobilenet_v3_small",
        "resnet18",
        "efficientnet_b0",
    ],
)
model.fit(train=s.train, val=s.val)

Only the specified candidates are evaluated. Invalid or duplicate candidates are rejected with a clear error. If backbone is not "auto", candidates must not be provided.

fit(train, *, val=None, target_accuracy=None, max_time_seconds=None, progress=True)

Fit the model on a dataset. train is required and specifies the training data. val is optional and specifies validation data.

Returns: Vyntri (self) for method chaining.

Examples:

# Training only — all images become training data
model.fit("./my_dataset")

# With validation
model.fit(train="./dataset/train", val="./dataset/val")

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

evaluate(test_dataset)

Evaluate model on a test dataset. Never changes model state.

Accepts a folder-per-class layout (evaluates all images) or a root with explicit test/ subfolder. Raises EvaluationError if an explicit layout has no test/ directory.

Returns: EvaluationResult with accuracy, macro_f1, weighted_f1, balanced_accuracy, confusion_matrix, per_class, n_samples, and timings.

predict(image)

Predict the class of a single image (path string, Path, or PIL Image).

Returns: PredictionResult with path, label, and confidence.

predict_batch(images, out_path=None)

Predict classes for a folder of images or a list of image paths. Preserves filenames; optionally writes CSV/JSON.

Returns: BatchPredictionResult with labels, confidences, CSV/JSON export.

update(dataset)

Add new training data (existing and/or new classes) analytically. Maintains sufficient statistics and re-solves — sequential matches joint refit. Accepts a FolderDataset, Path, or path string.

Returns: UpdateResult with new_classes.

fine_tune(dataset, *, scope="last_layer", epochs=3, lr=0.001, weight_decay=0.0001, batch_size=None, seed=None, progress=True)

Optional gradient fine-tuning (separate from analytic path). Replaces the analytic projection/classifier state; call fit() to restore analytic mode. Accepts a SplitResult (with validation for checkpoint selection), FolderDataset, Path, or path string.

save(path) → str

Persist the fitted model. Returns the path written.

Vyntri.load(path) → Vyntri

Class method. Load a model saved with save(). Reconstructs the backbone.

analyze(dataset) → AnalysisResult

Inspect a dataset folder without fitting (cheap, no extraction). Accepts a FolderDataset, Path, or path string. Returns class balance, resolution info, and PVI complexity scoring.

select_backbone(dataset, top_k=2) → SelectionResult

Score, rank, and select a backbone. Each candidate is scored with LogME on frozen features, top-k validated with the analytic pipeline. Does not fit the model.

__repr__() → str

Compact representation showing state, backbone, classes, and projection type. Example: Vyntri(state='fitted', backbone='mobilenet_v3_small', classes=3, projection=FKProjection)

summary() → str

Human-readable summary of configuration and fitted state.

clear_cache() → int

Delete all cached features for this model's cache directory. Returns count of deleted files.

Properties