add support for granite-switch / embedded adapters on our huggingface backend

Parent epic: #929
Phase: 3 (scope research / acceptance criteria before implementation)
Depends on: #1142
Blocks: #1144

⚠️ Thinly specified — scope research required before starting.
The Granite Switch HF path has not been mapped against the new EmbeddedBinding API.
Scope research is now unblocked. Do not begin implementation until items 1–3 below are resolved and the implementer has read the
granite-switch HF examples
against the new binding interface.

Problem

EmbeddedBinding.apply_activation (implemented in #1142) teaches the OpenAI backend
how to activate an embedded adapter by writing chat_template_kwargs["adapter_name"]
into the outgoing request.

LocalHFBackend has no equivalent path. Loading and running a Granite Switch model
locally via the HF backend today requires the caller to replicate the activation logic
manually — nothing in LocalHFBackend knows how to route an EmbeddedBinding through
its generation path.

This means a user who has a Granite Switch checkpoint locally cannot use adapter functions
through the standard Adapter(weights=EmbeddedBinding.from_base_model(backend)) pattern —
the backend simply ignores the binding.

Scope

Teach LocalHFBackend to call binding.apply_activation(request, identity) on the
generation path when the active adapter's binding is an EmbeddedBinding.
Verify that the chat_template_kwargs / request-field mechanism that works for
OpenAIBackend (via the Granite Switch API) also works for HF local inference — or
document why it differs and what the HF-specific activation field is.
Add LocalHFBackend to the backend × reality matrix in
docs/docs/advanced/intrinsics.md (introduced by feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142) once the path is confirmed.

Out of scope

LocalFileBinding (PEFT path) — already handled by feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141.
Output-contract parsing — that is refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516.
ServerMediatedBinding (no backend currently targets this).
Training or uploading embedded adapters (m alora CLI).

Research required before writing acceptance criteria

Read granite-switch HF inference examples
and map the activation field against LocalHFBackend's generation entry point.
Confirm whether apply_activation as designed in feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 produces the right request
shape for HF local inference, or whether HF needs a different field name/location.
Determine whether the existing EmbeddedIntrinsicAdapter code path in the OpenAI
backend (pre-feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142) has any HF-equivalent that would need to be removed.

Once (1)–(3) are answered, replace this section with concrete acceptance criteria,
a test plan, and a breaking-changes note following the format of #1141 / #1142.

References

feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 — EmbeddedBinding.apply_activation; must merge first
refactor(backends): AdapterMixin verb rename/narrow + resolve_model_options + IntrinsicMetricsPlugin (Epic #929 Phase 2) #1140 — AdapterMixin verb set; merged
granite-switch repo — HF examples
PR feat: add embedded adapters (granite switch) to openai backend #881 — Reality B added to OpenAI backend; the original embedded adapter implementation

docs: second round review edits (generative-computing#929)

Closing as superseded by #1142 (feat(backends): EmbeddedBinding implements verbs — Granite Switch path + OTel spans), which is tracked as part of the adapter lifecycle epic #929. Will be addressed when Phase 2 of that epic lands.

@planetf1

@planetf1, the linked issue (#1142) explicitly lists this issue as out of scope. We should ensure that this work does get done (even if it happens after the epic / major refactor).

@jakelorocco

@jakelorocco — you're right. #1142 explicitly defers this; closing it as superseded was wrong. Reopening as a follow-on blocked on #1142.

Assessment: scope, sequencing, and what remains

Researched this against the current codebase and the granite-switch repo to clarify what work is actually needed here.

What Granite Switch embedded adapters are

Granite Switch composes multiple adapter functions (answerability, query-rewrite, hallucination detection, etc.) into a single HF-compatible checkpoint. Adapters are activated via control tokens injected by the model's own chat template — there is no separate PEFT file to load at runtime and no set_adapter() call. This is the EmbeddedBinding / "Reality B" path in Epic #929's design.

Current state

OpenAIBackend already supports this fully (PR #881): load_embedded_adapters=True, and _generate_from_intrinsic injects chat_template_kwargs["adapter_name"] to activate the control token.

LocalHFBackend does not. _generate_from_intrinsic (huggingface.py:594) raises:

TypeError("LocalHFBackend only supports IntrinsicAdapters")

There is no load_embedded_adapters flag, no chat_template_kwargs["adapter_name"] injection on the local generate path, and add_adapter is typed for LocalHFAdapter only.

Relationship to Phase 2 (#1140, #1142)

This issue is not covered by #1140 or #1142 — both explicitly list #1018 in their Out of scope sections. #1142 ports EmbeddedBinding through the new binding abstraction but only on the OpenAI path.

#1018 is the distinct follow-on: wiring the (refactored) EmbeddedBinding and render_controls verb into LocalHFBackend. It depends on #1140 and #1142 and should land after both merge, before docs consolidation (Phase 4 / #1144).

Scope of this issue

Add load_embedded_adapters=True support to LocalHFBackend — mirror the OpenAI registration path in mellea/backends/adapters/_util.py; reuse EmbeddedIntrinsicAdapter.from_source/from_hub.
Implement render_controls on LocalHFBackend: inject chat_template_kwargs["adapter_name"] into transformers.generate(); skip the PEFT load_adapter/set_adapter path and the obtain_lora call (Epic Epic: Fix Adapter Function Lifecycle & Consistency in Mellea #929 item 1.b).
Route _generate_from_intrinsic (or the post-feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 EmbeddedBinding.activate path) through this new path instead of raising TypeError.
Run the existing IntrinsicsRewriter / IntrinsicsResultProcessor I/O transform (already used by the OpenAI path).
Add a LocalHFBackend × EmbeddedBinding integration test (@integration, @hf, @slow) against a Granite Switch checkpoint.

Out of scope: the OpenAI embedded path (#1142), the local PEFT/aLoRA LocalFileBinding path (#1141).

Key files

File	Relevance
`mellea/backends/huggingface.py:509-594`	`_generate_from_intrinsic` — where the `TypeError` lives
`mellea/backends/huggingface.py:1800`	`add_adapter` — typed `LocalHFAdapter` only
`mellea/backends/openai.py:638-647`	Reference implementation for embedded path
`mellea/backends/adapters/adapter.py:311`	`EmbeddedIntrinsicAdapter` (already exists)
`mellea/backends/adapters/_core.py:195`	`EmbeddedBinding` stub
`mellea/stdlib/components/intrinsic/_util.py:122-128`	`_uses_embedded_adapters` registration hook to mirror

Acceptance criteria

LocalHFBackend(load_embedded_adapters=True) registers embedded adapters from a Granite Switch source
Intrinsic call activates the correct control token via chat_template_kwargs["adapter_name"]; no PEFT load / obtain_lora on this path
LocalHFBackend × EmbeddedBinding integration test passes
Output parsed through IntrinsicsResultProcessor (shared with OpenAI path)
ruff / mypy clean

Blocked by: #1140, #1142

refactor(backends): shrink _generate_with_adapter_lock to its standar…

docs(backends): frame apply_activation as generative-computing#1018/g…

fix(backends): route intrinsic generation through adapter_scope, fix …

fix(backends): serialize resolve_adapter() registration under the act…

feat(backends): reuse exact token id prefixes under intrinsics

Navigation Menu

Repository navigation

add support for granite-switch / embedded adapters on our huggingface backend #1018

Problem

Scope

Out of scope

Research required before writing acceptance criteria

References

Assessment: scope, sequencing, and what remains

What Granite Switch embedded adapters are

Current state

Relationship to Phase 2 (#1140, #1142)

Scope of this issue

Key files

Acceptance criteria

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

add support for granite-switch / embedded adapters on our huggingface backend #1018

Description

Problem

Scope

Out of scope

Research required before writing acceptance criteria

References

Activity

planetf1 commented on May 26, 2026

jakelorocco commented on May 26, 2026

planetf1 commented on May 26, 2026

planetf1 commented on Jun 19, 2026

Assessment: scope, sequencing, and what remains

What Granite Switch embedded adapters are

Current state

Relationship to Phase 2 (#1140, #1142)

Scope of this issue

Key files

Acceptance criteria

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions