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() (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 apply_activation (Granite Switch path); remove render_controls + set_request_adapter (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() (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() (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 apply_activation (Granite Switch path); remove render_controls + set_request_adapter (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 apply_activation (Granite Switch path); remove render_controls + set_request_adapter (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.

[planetf1]

Answer: neither. One shape, two jobs — and they vary on different axes:

• Request reformatting — build the prompt and parameters from io.yaml. Varies by
  capability, and is identical for both backends. Goes on io_contract.
• Activation — tell the model which adapter to use. Varies by deployment. Goes on
  the binding, as apply_activation(request, identity).

That's @jakelorocco's A, and it's @psschwei's "capability config lookup plus a request
edit" — same two jobs from both directions, so I think we're already agreed on the shape.
Adapter keeps its three fields and nothing new is added.

What that gives us from outside:

• End users see no change. check_certainty(context, backend) and the other intrinsic
  helpers keep their signatures — no adapter, contract or binding type appears in any of
  them. All of this stays behind them.
• A new backend implements one binding. Reformatting comes from the capability
  contract, so it isn't written per backend. Today, adding a backend means copying the
  isinstance(adapter, EmbeddedIntrinsicAdapter) block at openai.py:699 — including the
  api_params.pop("model") — or embedded adapters quietly fail to activate. That block is
  the tell: activation has no home, so it got written into the backend.
• add support for granite-switch / embedded adapters on our huggingface backend #1018 is the test case. Embedded adapters on the HuggingFace backend is the same
  capability on a different deployment: EmbeddedBinding plus the existing contract, and
  no reformatting written twice.

One fix to today's code: the backend should resolve the adapter once and take the contract
off that object, rather than receiving it as a separate argument at ten call sites with
nothing tying it to the adapter that generated the output.

That leaves render_controls and set_request_adapter (#1422) with no job, so I'll remove
them — the two methods, the one no-op override in openai.py, their tests, and the entry
in docs/dev/adapter_observability.md. Nothing else refers to them, and no hooks do.
Deletable either way:

• Neither does anything today. set_request_adapter has no implementation and its
  docstring says it always raises; render_controls has one, an explicit no-op
  (openai.py:278).
• What actually activates an embedded adapter is the inline block above, bypassing both.
• Local-weights, embedded and server-mediated are already three binding classes. Keeping
  the verbs too means writing activation twice in Phase 2.
• load_peft_adapter and unload_peft_adapter stay as they are.

What I'll do, in order:

• feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141 / feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1454 — finish as it stands. LocalFileBinding keeps the four verbs; weights
  we load ourselves genuinely have a lifecycle.
• New issue — the io_contract change, plus resolving the adapter once.
• feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 — rescope, and it needs a new title: EmbeddedBinding gets apply_activation,
  not the four verbs. The two removals above go here.
• add support for granite-switch / embedded adapters on our huggingface backend #1018 — the acceptance test, once those are in.

#1465 is unaffected either way.

[psschwei]

If i'm understanding right, the new proposal is to have a helper function that creates the Adapter object, and then we can pass that around, instead of bundling it all into when we "load" the adapter. Is that more or less the idea?

[planetf1]

More or less, yes. The helper (resolve_adapter) stays — something has to turn a capability name into an object — but past that point the object travels, not the name. What changes is that every verb after resolution takes the Adapter (or Binding) directly rather than rebuilding the label each time.

The other half is pulling io_contract off the resolved Adapter inside the backend, once, instead of passing it in separately at each call site. Right now the contract arrives via a separate argument path (through _util.py) while the adapter travels a different one, and nothing in the type system enforces that they match. Once the backend holds the resolved object, it owns both and the split goes away.

[psschwei]

I think that approach makes sense

[jakelorocco]

Does this mean that we will have to specify the Adapter instead of the "role / capability" when invoking an adapter function? For instance, what would this change look like for the top level check_answerability, etc... functions?

[planetf1]

@jakelorocco No — check_answerability already hardcodes "answerability". Unchanged.

The real work:

• call_intrinsic resolves the adapter (_util.py:185) then ignores it, using a separate io_contract constant instead.
• Plan: read io_contract off the resolved adapter. But that's currently a placeholder raising NotImplementedError (adapter.py:257, :663) — not wired to real contracts yet.
• core.py's three helpers pass no contract today (json.loads only). They'd start validating once resolution supplies one.

[jakelorocco]

Okay, I'm still a bit iffy on what this would ultimately look like; but as long as we can still reference the functionality / role of an adapter (like answerability), I think I'm okay with this change.

[planetf1]

Written up, one issue per axis:

• refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516 — the contract half. Correction to my post above: I called this "one fix to today's code" and it isn't. resolve_adapter returns adapters whose io_contract is a placeholder that raises, so real contracts have to be wired into resolution before the parallel argument can go. refactor(intrinsics): rag.py whole-file migration to new Adapter types (Epic #929 Phase 1) #1137 built them as module-level constants and closed; the resolution path never got them.
• feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 — the activation half, rescoped to apply_activation and retitled. render_controls and set_request_adapter are removed there.

@jakelorocco on what it looks like concretely — #1142's Problem section has the before/after: the inline block at openai.py:699 becomes a binding method. Above call_intrinsic nothing moves, so check_answerability and the rest keep their signatures and you still reference adapters by role.

Independent axes, so both can proceed in parallel. #1141 / #1454 finishes as it stands, and #1018 is the acceptance test.

[planetf1]

Closing as settled.

One shape, two jobs, varying on different axes. Request reformatting comes from
io_contract — varies by capability, identical for both backends. Activation goes on
the binding as apply_activation — varies by deployment. Adapter keeps its three
fields and nothing new is added. render_controls and set_request_adapter have no
job left either way, so they go.

Where it now lives:

• refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516 — the contract half: resolve the output contract off the resolved adapter
  rather than passing it in alongside. Needs real contracts wired into resolution first,
  since resolve_adapter currently returns adapters whose io_contract raises.
• feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 — the activation half, rescoped and retitled. apply_activation replaces the
  four verbs for embedded adapters; the two removals above happen here.
• add support for granite-switch / embedded adapters on our huggingface backend #1018 — the acceptance test: same capability, different deployment, on a backend
  that then holds both kinds of binding at once.
• feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141 / feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1454 — finishes as it stands. Weights we load ourselves genuinely have a
  lifecycle, so LocalFileBinding keeps the four verbs.

#1516 and #1142 are independent axes, so they can proceed in parallel. #1465 is
unaffected.

Thanks @jakelorocco and @psschwei. The useful part was the two of you arriving at the
same two jobs from opposite ends — one from "the IOContract field is what defines the
reformatting", the other from "capability config lookup plus a request edit". That's what
persuaded me to stop trying to split the binding, which was the wrong cut.