Epic: Fix Adapter Function Lifecycle & Consistency in Mellea

[jakelorocco]

Resolve systemic issues with how adapter functions are loaded, invoked, and configured across backends. We should finalize a design for the below points and then create issues for that finalized implementation.

Initial implementation of EmbeddedIntrinsicAdapters in: #881
Initial removal of OpenAI adapters: #543

1. Adapter Loading & Unloading
   a. Clean up divergent control flow between EmbeddedAdapters and regular adapter function loading.
   b. Fix bug where obtain_lora is always called during call_intrinsic when embedded_adapters=False, which masks the real error from users and conflicts with different loading methods.
   c. Address that adapter loading/unloading is both backend-specific and adapter-type-specific — design a coherent abstraction for this.

2. Model Option Handling
   a. Fix adapter function rewriters overwriting model options unconditionally.
   b. Decide and document how adapter functions should interact with model options.
   c. There's a larger question of hierarchy with model options as well. Model options can technically be defined in all the following places: hf base model defaults in generation_config.json, adapter defaults in generation_config.json, io.yaml defaults, io.yaml values specified in the Mellea adapter function, mellea model options.

3. Naming Consistency
   a. Resolve whether adapter name must equal adapter.intrinsic_name or can differ (open issue).
   b. Standardize usage of "adapter name", "adapter function name", and "qualified name" across the codebase.
   c. refactor(intrinsics): decouple capability registry from catalog entry names (Epic #929 Phase 0) #1186 Decouple the capability registry from catalog entry names — Phase 0 follow-up. The role→capability rename is merged in feat(intrinsics): introduce Adapter/Identity/IOContract/WeightsBinding scaffolding (Epic #929 Phase 0) #1134 (PR feat(intrinsics): introduce Adapter/Identity/IOContract/WeightsBinding scaffolding (Epic #929 Phase 0) #1158); the catalog-side decoupling is next in sequence once fix(intrinsics): pin catalogue entries to HF revision SHAs + deduplicate requirement_check (#1135) #1157 (fix(intrinsics): pin catalogue entries to HF revision SHAs + deduplicate requirement_check entries (Epic #929 Phase 0) #1135) and feat(intrinsics): introduce Adapter/Identity/IOContract/WeightsBinding scaffolding (Epic #929 Phase 0) #1158 (feat(intrinsics): introduce Adapter/Identity/IOContract/WeightsBinding scaffolding (Epic #929 Phase 0) #1134) merge.
   d. fix(adapters): correct IntriniscsCatalogEntry class name typo (Epic #929 Naming) #1268 Fix IntriniscsCatalogEntry class name misspelling (Intriniscs → Intrinsics) — mechanical rename across 5 files; do after chore(terminology): adopt agreed Granite Switch / Mellea glossary (#1192) #1256 and refactor(adapters): decouple KNOWN_CAPABILITIES from catalog entry names (#1186) #1266 merge.

4. Output Parsing & Generic Adapter Function Contracts
   a. Address the problem where top-level call_intrinsics helpers assume a single output structure (e.g., result_json["answerability"] vs result_json["answerability_likelihood"]). We likely need to work with the Granite Switch team here to set common assumptions.
   b. Determine whether all adapters of a given type must conform to a standard output schema (e.g., a single output field, required keys) or whether parsing should be adapter-specific.
   c. This also encompasses "versioning" of adapter functions. The same adapter function may be updated / changed to have a different expected output format and our top-level call_intrinsic functions only allow one version.

5. OpenAI Backend Support
   a. Add OpenAIAdapters back — requires discussion on the logic for pulling/registering these. EmbeddedIntrinsicAdapters should technically inherit from these.

6. Cleanup
   a. Remove or repurpose the catalog. We shouldn't mandate all adapter functions be part of the known catalog.

Settled design decisions

• Adapter API: one lifecycle, or two shapes? #1486 — "Adapter API: one lifecycle, or two shapes?" (closed as resolved
  2026-08-11). Outcome: neither. One shape, two jobs, varying on different axes —
  request reformatting comes from io_contract (varies by capability, identical
  across backends), activation goes on the binding as apply_activation (varies by
  deployment). Adapter keeps its three fields; nothing new is added.
  render_controls and set_request_adapter have no job left and are removed in
  feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142. Discharged into refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516 (contract axis) and a rescoped feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142
  (activation axis) — independent axes, so both can proceed in parallel. add support for granite-switch / embedded adapters on our huggingface backend #1018 is
  the acceptance test. This supersedes item 5a's "EmbeddedIntrinsicAdapters should
  technically inherit from these" — the answer is composition plus one binding per
  deployment, not an inheritance chain.
• Span and metric naming is fixed and not up for reinvention. adapter_function
  parent, adapter_function.<phase> children, mellea.adapter_function.* attributes
  and instruments, content gated on MELLEA_TRACES_CONTENT. Established by refactor(backends): AdapterMixin verb rename/narrow + resolve_model_options + IntrinsicMetricsPlugin (Epic #929 Phase 2) #1140 /
  PR refactor(backends)!: narrow AdapterMixin verbs, centralize option resolution, add AdapterFunctionMetricsPlugin skeleton #1422, documented in docs/dev/adapter_observability.md. Several issues in this
  epic previously specified an invented intrinsic.* / MELLEA_TRACE_CONTENT scheme
  that never existed in the codebase; corrected across feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141, feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142, refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4) #1144 and feat(telemetry): emit adapter-function spans from a tracing plugin (Epic #929 Phase 2) #1466
  on 2026-08-11.
• Spans are produced by plugins, never inline in mellea/backends/. The source
  guidance is sufficient; docs(telemetry): document the hook/plugin span-production rule and enforce it (Epic #929) #1464 was intentionally closed after PR docs(telemetry): document hook/plugin span-production rule and enforce it #1545 review rather
  than adding a standalone import guard. feat(telemetry): emit adapter-function spans from a tracing plugin (Epic #929 Phase 2) #1466 rebuilds the adapter-function spans
  through the plugin pattern.

Phase Tracker

Phase	Issue	Title	Status	Depends on
0	#1186	Decouple KNOWN_CAPABILITIES from catalog names	✅ Merged	—
0	#1135	Catalogue revision pinning + deduplication	✅ Merged	—
0	#1134	Scaffolding: Adapter / Identity / IOContract / WeightsBinding	✅ Merged	—
0	#1192	Terminology sweep (docs/docs + backends)	✅ Merged	—
1	#1136	Internal shims + call_intrinsic rewrite	✅ Merged (PR #1269)	—
1	#1137	rag.py whole-file migration	✅ Merged (PR #1321)	#1136
1	#1138	requirement_check migration	✅ Merged (PR #1320)	#1136
1	#1139	guardian.py migration (behavioural)	✅ Merged (PR #1323)	#1136
1	#1332	guardian.py IOContract subclasses + Adapter constants	✅ Merged (PR #1357)	#1139, #1137
2	#1140	AdapterMixin verb narrow + resolve_model_options + AdapterFunctionMetricsPlugin	✅ Merged (PR #1422)	Phase 1
2	#1141	LocalFileBinding verbs (PEFT / aLoRA path) + from_catalog()	✅ Merged (PR #1454, 2026-08-17)	#1140
2	#1142	EmbeddedBinding implements apply_activation; remove render_controls + set_request_adapter	🔄 In progress — branch issue-1142 started 2026-08-18, draft PR pending	#1140
2	#1516	Resolve the output contract from the adapter, not a parallel argument	🔄 In progress — branch issue-1516 started 2026-08-18, draft PR pending	—
2	#1465	Route intrinsic generation through adapter_scope; fix lock reentrancy	🔄 In progress — branch issue-1465 started 2026-08-18, draft PR pending	#1141
2	#1466	Emit adapter-function spans from a tracing plugin	🔄 In progress — branch issue-1466 started 2026-08-18, scoped to lifecycle (prepare/activate/deactivate) spans only, draft PR pending	#1465 (generate/parse spans only, not started)
cross-cutting	#1464	Document + enforce the hook/plugin span-production rule	✅ Closed — intentionally dropped after PR #1545 review; source guidance is sufficient	—
2	#1528	release() leaves the adapter registered — and is a binding reusable after release() at all?	🔄 In progress — branch issue-1528 started 2026-08-18, draft PR pending	—
2+	#1018	EmbeddedBinding × LocalHFBackend — acceptance test for #1486's shape	⬜ Open, unclaimed — waiting on #1142 to merge	#1140, #1142
cleanup	#1268	Fix IntriniscsCatalogEntry class name typo	✅ Merged (PR #1370)	—
cleanup	#1279	Terminology prose sweep (docs/examples/ + docstrings)	✅ Merged (PR #1322)	—
cleanup	#385	Fix broken aLora example	🔄 In progress — branch issue-385 started 2026-08-18, draft PR pending	#1141
cleanup	#1338	Remove deprecated check_context_relevance and its adapter	⬜ Pending — next minor release	—
cleanup	#1412	Promote _DictContract to shared adapters module; collapse guardian.py's duplicate factuality contracts	✅ Merged (PR #1428)	—
cleanup	#1413	Document policy_guardrails exception-type change (ValueError → AdapterSchemaMismatchError)	✅ Merged (PR #1427)	—
4	#1144	Remove deprecation shims + rewrite tutorials	⬜ Pending — last in the chain	All of Phase 2: #1141, #1142, #1516, #1465, #1466, #1018
deferred	#1111	Adapter output-schema versioning design	⬜ Needs design discussion first	#1134
deferred	#1358	validate() should surface parse errors as a third outcome, not raise	⬜ Open — author's own proposal defers this until Phase 2/IOContract consolidation is further along	#1516

Statuses and the "Depends on" column were reconciled against issue state and the formal
GitHub dependency graph on 2026-08-18 (PR #1454 merged, #1141 closed, on 2026-08-17).
"⬜ Open, unclaimed" means no PR exists yet, not that the issue is unassigned.

Current batch (started 2026-08-18)

#1142, #1516, #1465, #385, #1528, and the lifecycle-span slice of #1466 are being
worked in parallel right now, each on its own branch (issue-<N>), targeting a draft PR
per issue. This is the batch we're trying to close out before moving to the next one.
See the outcome comment on this issue for the full note.

Suggested order

1. feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141 / PR feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1454 — merged 2026-08-17.
2. refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516, feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142, refactor(backends): route intrinsic generation through adapter_scope (Epic #929 Phase 2) #1465, bug: broken aLora example after intrinsics refactor #385, refactor(backends): release() leaves the adapter registered; is a binding reusable after release? (Epic #929) #1528, feat(telemetry): emit adapter-function spans from a tracing plugin (Epic #929 Phase 2) #1466 (lifecycle spans only) — in progress,
   see "Current batch" above. Independent axes, proceeding fully in parallel.
   feat(telemetry): emit adapter-function spans from a tracing plugin (Epic #929 Phase 2) #1466's generate/parse spans still wait on refactor(backends): route intrinsic generation through adapter_scope (Epic #929 Phase 2) #1465 and are explicitly out of
   scope for this batch.
3. add support for granite-switch / embedded adapters on our huggingface backend #1018 — the acceptance test that Adapter API: one lifecycle, or two shapes? #1486's shape actually holds. Blocked until
   feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142 merges (not just opens as a PR).
4. validate should surface parse errors as a third outcome rather than propagating exceptions #1358 — blocked until refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516 merges.
5. refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4) #1144 last (needs all of Phase 2 merged: feat(backends): LocalFileBinding implements verbs (PEFT/aLoRA path) + from_catalog() (Epic #929 Phase 2) #1141 ✅, feat(backends): EmbeddedBinding implements apply_activation (Granite Switch path); remove render_controls + set_request_adapter (Epic #929 Phase 2) #1142, refactor(intrinsics): resolve the adapter's output contract from the adapter, not a parallel argument (Epic #929 Phase 2) #1516, refactor(backends): route intrinsic generation through adapter_scope (Epic #929 Phase 2) #1465,
   feat(telemetry): emit adapter-function spans from a tracing plugin (Epic #929 Phase 2) #1466 in full, add support for granite-switch / embedded adapters on our huggingface backend #1018).
6. Remove deprecated check_context_relevance and context_relevance adapter #1338 — separate next-minor cleanup, not part of this push.

[jakelorocco]

7. Additionally, we found several issues due to hard-coded requirement_check adapters in our code for automatically utilizing requirement check adapters when present for requirements. The new design should account for this (and perhaps allow the intrinsic that ultimately gets used to be configurable). The changes from this PR should include all the spots that are necessary to evaluate these hard-coded values: https://github.com/generative-computing/mellea/pull/1008/changes.

[planetf1]

Note from PR #1028 review: PR #1028 (normalize intrinsics interfaces) adds a new context-mutation path in the guardian intrinsics — both factuality_detection and factuality_correction now rewind and re-attach documents to the last assistant message before calling call_intrinsic. This path will need to be accounted for in the lifecycle refactor here; specifically, the rewind logic operates on context.previous_node and re-wraps the last turn, which could interact with any changes to how turns are structured during adapter loading/unloading.

[planetf1]

Aiming to summarise / explain the current setup, issues, and what we want to achieve

Early version -> https://github.com/planetf1/mellea/blob/docs/issue-929-adapter-design-proposal/docs/dev/issue-929-adapter-design-proposal.md -- still checking for correctness. Hoping to get this right up-front, then the implementation should be easy ;-)

Ok to check in as a PR if useful