Adapter Plugin Documentation

The Adapter Plugin lowers the barrier for integrating existing Python code into VIPR.

Instead of writing full Cement handler classes, users can register plain functions via decorators.

Overview

The adapter provides:

  • Function decorators for core inference components (data_loader, model_loader, predictor)

  • Function decorators for callbacks (preprocess_filter, postprocess_filter, hook)

  • Automatic wrapper-class generation so VIPR can use the functions through its handler system

  • A scaffold command to generate full workflow YAML from discovered adapter registrations

The inference workflow remains the standard 5-step pipeline:

  1. load_data

  2. load_model

  3. preprocess

  4. prediction

  5. postprocess

There is no separate normalize step in current VIPR workflow execution.

Quick Start

1. Implement adapter functions

import vipr.plugins.adapter as adapter
from vipr.plugins.inference.dataset import DataSet

@adapter.data_loader("my_csv")
def load_data(path: str, delimiter: str = ",") -> DataSet:
    ...

@adapter.model_loader("my_model")
def load_model(config_ref: str, device: str = "cpu"):
    ...

@adapter.predictor("my_predictor")
def predict(data: DataSet, model, batch_size: int = 1) -> dict:
    ...

@adapter.preprocess_filter(name="clip_negative", hook="INFERENCE_PREPROCESS_PRE_FILTER")
def clip_negative(data: DataSet, floor: float = 1e-10) -> DataSet:
    ...

load = adapter.plugin(__name__)

2. Expose entry point in pyproject.toml

[project.entry-points."vipr.plugins"]
my_experiment = "my_experiment:load"

3. Generate full workflow YAML scaffold

vipr adapter init-config --plugin my_experiment -o workflow.yaml

This command generates a normal vipr.inference config. You then fill required values and run:

vipr --config workflow.yaml inference run

Adapter CLI Command

vipr adapter init-config supports:

  • --plugin <entry-point-name> (required)

  • -o/--output <path>

  • --force

  • --data-loader <name>

  • --model-loader <name>

  • --predictor <name>

Notes:

  • --plugin uses the entry-point name from pyproject.toml, not the module name.

  • If multiple handlers of one type exist, select one with the corresponding flag.

  • Without -o, YAML is printed to stdout.

Runtime Model

The adapter keeps VIPR runtime behavior unchanged:

  • At import/decorator time, adapter metadata and wrapper classes are prepared.

  • At plugin load time (load(app)), wrappers are registered into VIPR handler and discovery systems.

  • Inference still runs through the same built-in pipeline and hooks/filters architecture.

Error Cases

Typical adapter errors include:

  • Plugin entry point not installed (--plugin not found)

  • Ambiguous handler selection (multiple data/model/predictor handlers)

  • Output file exists and --force is not set

  • Missing required YAML values after scaffold generation

See Also