Adapter API: one lifecycle, or two shapes?

[planetf1]

The problem

We pass adapters around as labels instead of as adapters. To load one, you glue its name and type into a label, hand the backend the label, and the backend looks that up in a dictionary to get the adapter back:

backend.load_peft_adapter("answerability_lora")   # today
backend.load_peft_adapter(adapter)                # proposed

We build that label in four separate places. Nothing checks they agree, and when they don't the lookup quietly returns nothing.

Every adapter has to pretend it has a lifecycle. Bindings must implement prepare → activate → deactivate → release. That fits an adapter whose weights are files we download and switch on. It means nothing for one already inside the model, where all you do is set a field on the outgoing request — and we ship one of those. Our two stub bindings satisfy the ABC by raising NotImplementedError eight times between them.

Both are cheap to fix now: from_catalog, bind_backend, prepare() and adapter_scope have zero callers in mellea/, so nothing depends on either yet. Once #1142 builds on them it's a migration.

The proposal

Two changes, independent of each other.

Verbs take the adapter

Every adapter verb takes adapter_qualified_name: str. Give them the object:

def resolve_adapter(self, name: str) -> Adapter: ...          # the one place a name comes in
def load_peft_adapter(self, adapter: Adapter) -> None: ...    # everywhere else, objects

One name-to-adapter lookup survives, because a name does arrive from outside — an Intrinsic knows it wants "answerability", not which object that is. Past that point, objects. Identity is already a frozen dataclass over three hashable fields, so it can be the dictionary key as-is.

This is also the answer to @jakelorocco's question on #1454 — why does LocalFileBinding carry adapter_type when Identity already has it? Because it needs name and type to build the label. Take the label away and the copy has nothing left to do.

Related: #1422 looked at a generic AdapterMixin[A], decided against it as too invasive, and recorded it as the direction for the later Adapter hierarchy consolidation. This arrives at roughly the same place from the verbs instead.

Two kinds of binding

WeightsBinding is an ABC with four abstract methods, so everything declares all four. But the API is already doing two jobs — lifecycle management for weights we load ourselves, and request formatting for weights already in the model. Make each verb set optional, so a binding declares which job it's in:

class LifecycleBinding(Protocol):     # weights we stage and switch on
    def prepare(self) -> None: ...
    def activate(self) -> None: ...
    def deactivate(self) -> None: ...
    def release(self) -> None: ...

class RequestBinding(Protocol):       # weights already there — we edit the request
    def transform(self, request: R) -> R: ...

A binding implements one. render_controls and set_request_adapter both become transform; for Granite Switch that body writes chat_template_kwargs["adapter_name"].

A runtime with nothing to do implements neither. Ollama fuses a LoRA into the model at build time — there's no adapter parameter on /api/generate or /api/chat; you pick an adapter by picking the model. Today that can only be written as four raises.

Why

• @jakelorocco wrote the conclusion in April. openai.py:607-608, from feat: add embedded adapters (granite switch) to openai backend #881: # TODO: OpenAIBackend only supports EmbeddedAdapters. It should be refactored into a specific adapter.transform() function.
• The verb we built for the per-request case does nothing. render_controls(name, active) -> None has nowhere to put a rendered control. On OpenAIBackend it's a debug log with zero production callers; the real activation is one line writing a template kwarg.
• The plan on #1018 already treats it as a request edit — "implement render_controls on LocalHFBackend to inject chat_template_kwargs["adapter_name"]".
• The label has already caused a bug. @AngeloDanducci spotted it on feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() + OTel spans (Epic #929 Phase 2) #1454: the label says answerability_lora while the identity says aLoRA. Two parts of one object disagree, and the test passes.
• The verbs already collide with feat(backends): EmbeddedBinding implements verbs (Granite Switch path) + OTel spans (Epic #929 Phase 2) #1142. Its design uses activate(ctx); the ABC declares activate(self). Whoever picks it up must either change the verbs feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() + OTel spans (Epic #929 Phase 2) #1454 just added or quietly diverge.

Verbs stop taking strings and two collapse into one. Four label-building sites go to none, and AdapterInput stops being a union of three types.

Happy to be wrong on any of this, especially the binding split — @jakelorocco you've had a clearer view since April, and if the answer is "just add transform and move on", that's much smaller than what I'm proposing. The other options I looked at are below.

---

The two kinds of binding, in detail

The useful question isn't "where do the weights live" but who works out the point at which the adapter turns on. Two answers ship today:

	Where the weights live	Who locates the activation point	Status
Lifecycle	files we download and load ourselves	PEFT, from the adapter config	LocalHFBackend — shipping
Per-request	server-side — baked into the served artifact, or loaded by the server at start-up	the server	OpenAIBackend (Granite Switch) — shipping. Also how llama-server exposes aLoRA (merged) — no Mellea backend for that one

The first is a real state toggle: stage it, switch on, switch off, take it away. The four verbs describe it exactly.

The second has no client-side state and nothing to toggle. Activation is an edit to the outgoing request, and only the field varies — chat_template_kwargs["adapter_name"] for Switch, lora: [{"id": 0, "scale": 1.0}] for llama-server.

Then the case with no verbs at all: Ollama, where the adapter is fused in when the model is built — the Modelfile ADAPTER directive, or adapters on POST /api/create. In the whole of docs/api.md, "adapter" appears once, on model creation. Nothing to stage, nothing to toggle, nothing to put on a request.

The two kinds are already close enough to confuse. LocalHFBackend._generate_from_intrinsic claims it "injects intrinsic_name into chat_template_kwargs so that the Granite Switch chat template activates the correct adapter" (huggingface.py:586). It doesn't — that's the only occurrence of chat_template_kwargs in the whole HF backend, it's inside the docstring, and it's copied word for word from openai.py:564-565 where it's true. The HF path goes through the PEFT lifecycle. Needs fixing whatever we decide.

Identity and types, in detail

The label is name + "_" + adapter_type.value, built at adapter.py:75, :338, :831 and _core.py:290. Nothing parses it — no split("_"), no endswith("_lora"), no regex anywhere in mellea/ or cli/. It's built, then used as an opaque dictionary key. So the risk isn't mis-parsing; it's the four builders drifting, and two lookups that disagree about which field identifies an adapter.

Path	How it finds an adapter	Trusts
Registration and all six verbs	_added_adapters[adapter.qualified_name], then .get(adapter_qualified_name) (huggingface.py:2047, 2087)	the binding's name and adapter_type
Resolution — resolve_adapter → _find_adapter (adapter.py:757)	scans .values() for a.identity.capability == capability, ignoring the key	the identity's capability

Nothing requires those two fields equal, and both lookups return None on a miss — so a drift surfaces as "adapter not found" a long way from the mistake. Nothing can be wrong at construction time.

The label also keeps the Phase 0 Adapter out of its own API: no qualified_name to be keyed by, frozen=True so the adapter.backend = self both backends do would raise, and excluded by both registry annotations (openai.py:224, huggingface.py:448). The add_adapter isinstance guards are the outermost of three walls, not a policy. Coming the other way, resolve_adapter is annotated -> _AdapterCore, the deprecated shim, because that's all _find_adapter can yield.

And it's why one fact has six spellings:

Location	Spelling
Identity.adapter_type	Literal["lora","alora"]
LocalFileBinding.adapter_type	AdapterType enum
Intrinsic.adapter_types	list[AdapterType], converted to a tuple of str at the call site
_find_adapter	bare string tuple
EmbeddedIntrinsicAdapter.technology	str, mapped onto AdapterType at adapter.py:825
EmbeddedBinding	no such field

EmbeddedBinding having no such field is the tell — it never builds a label, so it never needed one. LocalFileBinding genuinely needs both facts (get_local_hf_path passes self.name and alora=self.adapter_type is AdapterType.ALORA); it just shouldn't keep its own copy. Hand it the identity when the adapter is composed, or pass identity into each verb — either works, and Identity already validates itself in __post_init__.

EmbeddedIntrinsicAdapter.technology is the odd one out. Its only job is deciding where the control token goes — start of sequence for LoRA, before the generation prompt for aLoRA (adapter.py:788). A parameter of a request transform, on an adapter class, spelled differently from every other adapter-type field.

Deletable either way: get_adapter_for_intrinsic, exported and deprecated with zero call sites, rebuilds the label by interpolation and returns the first allowed adapter type — the same first-of-two rule behind the bug above.

Options I considered

Document it and move on. Write down that the four verbs are the file-based lifecycle and that per-request adapters use render_controls. Costs nothing now, and defers both problems into #1142 and #1018 where they become migrations.

Add a fifth verb. Bindings gain transform(request) -> request alongside the lifecycle four; per-request bindings no-op the four. Smallest diff that fixes the verb complaint. But five verbs of which you use one or four is the shape @jakelorocco already considered and didn't like, and the labels stay.

Cross-check only. Adapter.__post_init__ asserting identity.adapter_type == weights.adapter_type. Catches @AngeloDanducci's class of bug at construction time rather than on a silent lookup miss. I'd take it as a stopgap either way.

Both changes — what I'm proposing.

Rejected: putting the activation edit in the I/O contract, since IOContract.build_prompt() (_core.py:111-120) already owns input construction. The same contract — answerability, say — is valid for both kinds of binding, while the activation mechanism varies by target. build_prompt builds the semantic prompt; transform adapts it to the runtime.

Impact on work in flight

Sketch only — worth doing properly once we've agreed the shape.

• feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() + OTel spans (Epic #929 Phase 2) #1454 (open) — the four LocalFileBinding verbs stay; they're the lifecycle case and they're right. They lose their string parameter.
• feat(backends): EmbeddedBinding implements verbs (Granite Switch path) + OTel spans (Epic #929 Phase 2) #1142 (unblocked, unclaimed) — biggest impact, and the reason for the timing. EmbeddedBinding implements transform rather than routing activate through render_controls, and the activate(ctx) / activate(self) collision stops mattering.
• add support for granite-switch / embedded adapters on our huggingface backend #1018 (open, blocked on refactor(backends): AdapterMixin verb rename/narrow + resolve_model_options + IntrinsicMetricsPlugin (Epic #929 Phase 2) #1140 and feat(backends): EmbeddedBinding implements verbs (Granite Switch path) + OTel spans (Epic #929 Phase 2) #1142) — gets simpler, and makes LocalHFBackend the first backend holding both kinds at once. That's @jakelorocco's original question about one backend supporting several adapter types, arriving for real.
• Docs — huggingface.py:586 needs correcting either way.

Does the lifecycle hold up for aLoRA today?

Yes — because PEFT does the hard part.

An aLoRA has to start applying at a specific point in the input: its invocation tokens. We store those at training time in the adapter config (cli/alora/train.py:295-306), and PEFT reads them and scopes the adapter itself. At inference mellea/ has no invocation-token handling at all — zero references, in any form. All we do is switch the adapter on for the request, which the four verbs describe exactly.

But that's a division of labour, not a property of aLoRA. llama-server does the same job inside the server, exposing only a per-request lora field (tools/server/README.md); a Granite Switch server does it in its chat template. Same adapter concept, three different owners — so "aLoRA" tells you nothing about which shape you're in.

The risk is that the division moves again. Per-token scoping is still open upstream: llama.cpp#15327 notes under ## TODO that the correct approach is to "identify the invocation tokens within an input request and only use the adapter for tokens starting with the invocation sequence", needing "adapter scaling on a per-token basis rather than on a per computation basis." A whole-request on/off switch can't express "on from token N onward". We don't have to today because PEFT hides it — which is why the abstraction looks fine until a second runtime turns up. (That PR's own headline benefit is cache preservation, not per-token scoping.)

[psschwei]

What's the intended scope of the Adapters API? Is it lifecycle management, or are we also intending it to handle request formatting?

[psschwei]

To elaborate a bit, as I was working my way through the discussion here, this is how Claude summarized it:

---

There are actually two separable jobs the current Adapter object is doing at once, and Switch only needs one of them:

  ┌──────────────────────────────────────────────────────────────────┬────────────────────┬──────────────────────────────────────────┐
  │                               Job                                │ Needed for Switch? │               Who does it                │
  ├──────────────────────────────────────────────────────────────────┼────────────────────┼──────────────────────────────────────────┤
  │ Resolve/manage weights (download, load, toggle, release)         │ No                 │ binding lifecycle verbs                  │
  ├──────────────────────────────────────────────────────────────────┼────────────────────┼──────────────────────────────────────────┤
  │ Supply the I/O contract config (io.yaml) + activation field name │ Yes                │ adapter.config, then rewriter/IOContract │
  └──────────────────────────────────────────────────────────────────┴────────────────────┴──────────────────────────────────────────┘

The 1486 proposal's answer is "two shapes": file-based keeps the four verbs; embedded gets transform. Your sharper answer is: for Switch the "adapter" is only an I/O contract + a request field, so maybe it shouldn't be modeled as an adapter (a managed resource) at all, it should be modeled as a capability config lookup plus a request edit. That's arguably a cleaner cut than "two shapes of binding," because it says the embedded case was never a binding to begin with.

That distinction is worth raising in the discussion, and it's not clearly resolved there. The proposal frames the split as "two shapes of binding." You're questioning whether the embedded case is a binding at all, versus just config-resolution + a request field, in which case the answer to "settle the binding shape" is "the embedded case shouldn't route through the binding abstraction; it needs the IOContract, which is a different axis."

One caveat before you run with it: the registration step is also what makes resolve_adapter(name) able to find the config by capability name (and lazily fetch it). So "don't construct anything" isn't quite free, you still need a name → config resolution somewhere. The honest version of your point is: that resolution is I/O-contract resolution, not adapter/weight management, and conflating the two is what makes Switch look like it needs the lifecycle API when it doesn't.

---

Again, depends on how we're trying to scope the adapters API, but to me it seems like it makes sense to keep request config separate from weights management.

[planetf1]

Sorry — I posted a draft by mistake while still rewriting it, so what you replied to has changed.

Short answer: both. Right now we only have lifecycle, so request formatting has to fake it. prepare/activate/deactivate/release make sense for weights we load ourselves, but not for an adapter that's already in the model — there, turning it on is just a field on the request. Keep both, stop pretending they're the same shape.

Is that what you were getting at?

[jakelorocco]

Two things:

A. But our newly defined adapters have an IOContract field / piece. This field should be what defines the request reformatting (ie changing the model, adding tokens to the prompt, restructuring the prompt).

So our adapters (or backends) need to know how to process this information. I think this is actually a piece where it is consistent between backends (or at least everything goes through granite_io the same way, there might be some slight backend specific remapping).

B. I'm fine if we want to fake / no-op. In fact, it may eventually make sense to "overload" these actions in unique ways for different adapters. For instance, on an embedded / switch model, we may want to have prepare / activate raise an exception if the model doesn't actually contain that adapter type.

[psschwei]

our newly defined adapters have an IOContract field / piece. This field should be what defines the request reformatting

That's fair, and having reviewed the Adapter class again turns out I had actually forgotten that we were composing rather than inheriting, so no objection from me.