Skip to main content

mellea.backends.adapters.adapter

Adapter classes for adding fine-tuned modules to inference backends.

Defines the abstract Adapter base class and its concrete subclasses LocalHFAdapter (for locally loaded HuggingFace models) and IntrinsicAdapter (for adapters whose metadata is stored in Mellea's intrinsic catalog). Also provides get_adapter_for_intrinsic for resolving the right adapter class given an intrinsic name, and AdapterMixin for backends that support runtime adapter loading and unloading.

Functions​

FUNC get_adapter_for_intrinsic ​

get_adapter_for_intrinsic(intrinsic_name: str, intrinsic_adapter_types: list[AdapterType] | tuple[AdapterType, ...], available_adapters: dict[str, T]) -> T | None

Find an adapter from a dict of available adapters based on the intrinsic name and its allowed adapter types.

Args:

  • intrinsic_name: The name of the intrinsic, e.g. "answerability".
  • intrinsic_adapter_types: The adapter types allowed for this intrinsic, e.g. [AdapterType.ALORA, AdapterType.LORA].
  • available_adapters: The available adapters to choose from; maps adapter.qualified_name to the adapter object.

Returns:

  • T | None: The first matching adapter found, or None if no match exists.

Classes​

CLASS Adapter ​

An adapter that can be added to a single backend.

An adapter can only be registered with one backend at a time. Use adapter.qualified_name when referencing the adapter after adding it.

Args:

  • name: Human-readable name of the adapter.
  • adapter_type: Enum describing the adapter type (e.g. AdapterType.LORA or AdapterType.ALORA).

Attributes:

  • qualified_name: Unique name used for loading and lookup; formed as "<name>_<adapter_type.value>".
  • backend: The backend this adapter has been added to, or None if not yet added.
  • path: Filesystem path to the adapter weights; set when the adapter is added to a backend.

CLASS LocalHFAdapter ​

Abstract adapter subclass for locally loaded HuggingFace model backends.

Subclasses must implement get_local_hf_path to return the filesystem path from which adapter weights should be loaded given a base model name.

Methods:

FUNC get_local_hf_path ​

get_local_hf_path(self, base_model_name: str) -> str

Return the local filesystem path from which adapter weights should be loaded.

Args:

  • base_model_name: The base model name; typically the last component of the HuggingFace model ID (e.g. "granite-4.0-micro").

Returns:

  • Filesystem path to the adapter weights directory.

CLASS IntrinsicAdapter ​

Base class for adapters that implement intrinsics.

Subtype of :class:Adapter for models that:

  • implement intrinsic functions
  • are packaged as LoRA or aLoRA adapters on top of a base model
  • use the shared model loading code in mellea.formatters.granite.intrinsics
  • use the shared input and output processing code in mellea.formatters.granite.intrinsics

Args:

  • intrinsic_name: Name of the intrinsic (e.g. "answerability"); the adapter's qualified_name will be derived from this.
  • adapter_type: Enum describing the adapter type; defaults to AdapterType.ALORA.
  • config_file: Path to a YAML config file defining the intrinsic's I/O transformations; mutually exclusive with config_dict.
  • config_dict: Dict defining the intrinsic's I/O transformations; mutually exclusive with config_file.
  • base_model_name: Base model name used to look up the I/O processing config when neither config_file nor config_dict are provided.

Attributes:

  • intrinsic_name: Name of the intrinsic this adapter implements.
  • intrinsic_metadata: Catalog metadata for the intrinsic.
  • base_model_name: Base model name provided at construction, if any.
  • adapter_type: The adapter type (LORA or ALORA).
  • config: Parsed I/O transformation configuration for the intrinsic.

Methods:

FUNC get_local_hf_path ​

get_local_hf_path(self, base_model_name: str) -> str

Return the local filesystem path from which adapter weights should be loaded.

Downloads the adapter weights if they are not already cached locally.

Args:

  • base_model_name: The base model name; typically the last component of the HuggingFace model ID (e.g. "granite-3.3-8b-instruct").

Returns:

  • Filesystem path to the downloaded adapter weights directory.

FUNC download_and_get_path ​

download_and_get_path(self, base_model_name: str) -> str

Downloads the required rag intrinsics files if necessary and returns the path to them.

Args:

  • base_model_name: the base model; typically the last part of the huggingface model id like "granite-3.3-8b-instruct"

Returns:

  • a path to the files

CLASS AdapterMixin ​

Mixin class for backends capable of utilizing adapters.

Attributes:

  • base_model_name: The short model name used to identify adapter variants (e.g. "granite-3.3-8b-instruct" for "ibm-granite/granite-3.3-8b-instruct").

Methods:

FUNC base_model_name ​

base_model_name(self) -> str

Return the short model name used for adapter variant lookup.

Returns:

  • The base model name (e.g. "granite-3.3-8b-instruct").

FUNC add_adapter ​

add_adapter(self, *args, **kwargs)

Register an adapter with this backend so it can be loaded later.

The adapter must not already have been added to a different backend.

Args:

  • args: Positional arguments forwarded to the concrete implementation.
  • kwargs: Keyword arguments forwarded to the concrete implementation.

FUNC load_adapter ​

load_adapter(self, adapter_qualified_name: str)

Load a previously registered adapter into the underlying model.

The adapter must have been registered via add_adapter before calling this method.

Args:

  • adapter_qualified_name: The adapter.qualified_name of the adapter to load.

FUNC unload_adapter ​

unload_adapter(self, adapter_qualified_name: str)

Unload a previously loaded adapter from the underlying model.

Args:

  • adapter_qualified_name: The adapter.qualified_name of the adapter to unload.

FUNC list_adapters ​

list_adapters(self) -> list[str]

Return the qualified names of all adapters currently loaded in this backend.

Returns:

  • list[str]: Qualified adapter names for all adapters that have been loaded via load_adapter.

Raises:

  • NotImplementedError: If the concrete backend subclass has not implemented this method.

CLASS EmbeddedIntrinsicAdapter ​

Adapter for intrinsics embedded in a Granite Switch model.

Unlike PEFT-based adapters that are loaded into the model at runtime, embedded adapters are already baked into the model weights and activated via control tokens injected by the model's chat template. Only the I/O transformation config (io.yaml) is needed; no adapter weights are downloaded or loaded.

Args:

  • intrinsic_name: Name of the intrinsic (e.g. "answerability").
  • config: Parsed I/O transformation configuration (from io.yaml).
  • technology: Adapter technology in the switch model — "lora" or "alora". Determines where the control token is placed in the chat template (beginning of sequence for LoRA, before generation prompt for aLoRA).

Attributes:

  • intrinsic_name: Name of the intrinsic this adapter implements.
  • config: Parsed I/O transformation configuration.
  • technology: "lora" or "alora".

Methods:

FUNC from_model_directory ​

from_model_directory(model_path: str | pathlib.Path, intrinsic_name: str | None = None) -> list['EmbeddedIntrinsicAdapter']

Load embedded adapters from a Granite Switch model directory.

Reads adapter_index.json and the corresponding io_configs/*/io.yaml files from the model directory.

Args:

  • model_path: Path to a Granite Switch model directory that contains adapter_index.json and io_configs/.
  • intrinsic_name: If provided, only load the adapter matching this intrinsic name. None loads all adapters.

Returns:

  • list[EmbeddedIntrinsicAdapter]: One adapter per entry in the index.

Raises:

  • FileNotFoundError: If adapter_index.json is missing.
  • ValueError: If an io.yaml file listed in the index cannot be found or if no adapters are found.

FUNC from_hub ​

from_hub(repo_id: str, revision: str = 'main', cache_dir: str | None = None, intrinsic_name: str | None = None) -> list['EmbeddedIntrinsicAdapter']

Load embedded adapters from a Granite Switch model on HuggingFace Hub.

Downloads adapter_index.json and the io_configs/ directory, then delegates to :meth:from_model_directory.

Args:

  • repo_id: HuggingFace Hub repository ID (e.g. "ibm-granite/granite-switch-micro").
  • revision: Git revision to download from.
  • cache_dir: Local cache directory; None for the default.
  • intrinsic_name: If provided, only load the adapter matching this intrinsic name. None loads all adapters.

Returns:

  • list[EmbeddedIntrinsicAdapter]: One adapter per entry in the index.

Raises:

  • ImportError: If huggingface_hub is not installed.
  • FileNotFoundError: If adapter_index.json is missing (delegated from :meth:from_model_directory).
  • ValueError: If no adapters are found (delegated from :meth:from_model_directory).

FUNC from_source ​

from_source(source: str, revision: str = 'main', cache_dir: str | None = None, intrinsic_name: str | None = None) -> list['EmbeddedIntrinsicAdapter']

Load embedded adapters from a local directory or HuggingFace Hub.

Automatically detects whether source is a local filesystem path or a HuggingFace Hub repo ID, and delegates accordingly.

Args:

  • source: Local path to a model directory, or a HuggingFace Hub repo ID (e.g. "ibm-granite/granite-switch-micro").
  • revision: Git revision (only used for Hub downloads).
  • cache_dir: Cache directory (only used for Hub downloads).
  • intrinsic_name: If provided, only load the adapter matching this intrinsic name. None loads all adapters.

Returns:

  • list[EmbeddedIntrinsicAdapter]: One adapter per entry in the index.

CLASS CustomIntrinsicAdapter ​

Special class for users to subclass when creating custom intrinsic adapters.

The documentation says that any developer who creates an intrinsic should create a subclass of this class. Creating a subclass of this class appears to be a cosmetic boilerplate development task that isn't actually necessary for any existing use case.

This class has the same functionality as IntrinsicAdapter, except that its constructor monkey-patches Mellea global variables to enable the backend to load the user's adapter. The code that performs this monkey-patching is marked as a temporary hack.

Args:

  • model_id: The HuggingFace model ID used for downloading model weights; expected format is "<user-id>/<repo-name>".
  • intrinsic_name: Catalog name for the intrinsic; defaults to the repository name portion of model_id if not provided.
  • base_model_name: The short name of the base model (NOT its repo ID).