chore(terminology): adopt agreed Granite Switch / Mellea glossary (#1192)

AGENTS.md

@@ -173,11 +173,11 @@ Found a bug, workaround, or pattern? Update the docs:
 - **Usage pattern?** → Add to [`docs/AGENTS_TEMPLATE.md`](docs/AGENTS_TEMPLATE.md)
 - **New pitfall?** → Add warning near relevant section
 
-## 13. Working with Intrinsics
+## 14. Working with Adapter Functions
 
-Intrinsics are specialized LoRA adapters that add task-specific capabilities (RAG evaluation, safety checks, calibration, etc.) to Granite models. Mellea handles adapter loading and input formatting automatically — you just call the right function.
+Adapter functions are specialized LoRA/aLoRA adapters that add task-specific capabilities (RAG evaluation, safety checks, calibration, etc.) to Granite models. Mellea handles adapter loading and input formatting automatically — you just call the right function.
 
-### Using Intrinsics in Mellea
+### Using Adapter Functions in Mellea
 
 **Prefer the high-level wrappers** in `mellea/stdlib/components/intrinsic/`. These handle adapter loading, context formatting, and output parsing for you:
 
@@ -212,28 +212,28 @@ For lower-level control (custom adapters, model options), use `mfuncs.act()` wit
 
 ### Project Resources
 
-- **Canonical catalog**: `mellea/backends/adapters/catalog.py` — source of truth for intrinsic names, HF repo IDs, and adapter types
-- **Usage examples**: `docs/examples/intrinsics/` — working code for every intrinsic
+- **Canonical catalog**: `mellea/backends/adapters/catalog.py` — source of truth for adapter function names, HF repo IDs, and adapter types
+- **Usage examples**: `docs/examples/intrinsics/` — working code for every adapter function
 - **Helper functions**: `mellea/stdlib/components/intrinsic/rag.py` and `core.py`
 
-### Adding New Intrinsics
+### Adding New Adapter Functions
 
-When adding support for a new intrinsic (not just using an existing one), fetch its README from Hugging Face first. Each README contains the authoritative spec for input/output format, intended use, and examples.
+When adding support for a new adapter function (not just using an existing one), fetch its README from Hugging Face first. Each README contains the authoritative spec for input/output format, intended use, and examples.
 
 **Writing examples?** The HF READMEs also document intended usage patterns and example inputs — useful reference when writing code in `docs/examples/intrinsics/`.
 
-| Repo | Purpose | Intrinsics |
+| Repo | Purpose | Adapter functions |
 |------|---------|------------|
 | [`ibm-granite/granitelib-rag-r1.0`](https://huggingface.co/ibm-granite/granitelib-rag-r1.0) | RAG pipeline | answerability, citations, context_relevance, hallucination_detection, query_rewrite, query_clarification |
 | [`ibm-granite/granitelib-core-r1.0`](https://huggingface.co/ibm-granite/granitelib-core-r1.0) | Core capabilities | context-attribution, requirement-check, uncertainty |
 | [`ibm-granite/granitelib-guardian-r1.0`](https://huggingface.co/ibm-granite/granitelib-guardian-r1.0) | Safety & compliance | guardian-core, policy-guardrails, factuality-detection, factuality-correction |
 
-**README URLs** — RAG intrinsics (no model subfolder):
+**README URLs** — RAG adapter functions (no model subfolder):
 ```
 https://huggingface.co/ibm-granite/granitelib-rag-r1.0/blob/main/{intrinsic_name}/README.md
 ```
 
-Core and Guardian intrinsics (include model subfolder):
+Core and Guardian adapter functions (include model subfolder):
 ```
 https://huggingface.co/ibm-granite/granitelib-{core,guardian,rag}-r1.0/blob/main/{intrinsic_name}/granite-4.1-{3b,8b,30b}/{lora,alora}/README.md
 ```

docs/docs/advanced/intrinsics.md

@@ -1,5 +1,5 @@
 ---
-title: "Intrinsics"
+title: "Adapter functions"
 description: "Adapter-accelerated RAG quality checks using LoRA/aLoRA adapters with Granite models."
 # diataxis: how-to
 ---
@@ -8,22 +8,22 @@ description: "Adapter-accelerated RAG quality checks using LoRA/aLoRA adapters w
 Silicon Mac recommended), or `pip install mellea` for OpenAIBackend with a
 [Granite Switch](/reference/glossary#granite-switch) model served via vLLM.
 
-Intrinsics are adapter-accelerated operations for RAG quality checks. They use
-LoRA/aLoRA adapters loaded directly into the HuggingFace backend — faster and more
+Adapter functions are adapter-accelerated operations for RAG quality checks. They use
+LoRA/aLoRA adapters loaded directly into the Hugging Face backend — faster and more
 reliable than prompting a general-purpose model for these specialized micro-tasks.
 
-> **Backend note:** Intrinsics work with two backends:
+> **Backend note:** Adapter functions work with two backends:
 >
 > - **LocalHFBackend** — loads LoRA/aLoRA adapters from the catalog at runtime.
->   All intrinsics are available. Requires a GPU or Apple Silicon Mac.
+>   All adapter functions are available. Requires a GPU or Apple Silicon Mac.
 > - **OpenAIBackend** — uses a Granite Switch model served via vLLM with
->   `load_embedded_adapters=True`. Only intrinsics embedded in the model are
+>   `load_embedded_adapters=True`. Only adapter functions embedded in the model are
 >   available — check the model's `adapter_index.json` for the list.
 >   See `docs/docs/examples/granite-switch/README.md`
 >
-> Intrinsics do not work with Ollama or other remote backends.
+> Adapter functions do not work with Ollama or other remote backends.
 
-Set up the backend once and reuse it across intrinsic calls:
+Set up the backend once and reuse it across adapter function calls:
 
 ```python
 # Requires: mellea[hf]
@@ -209,7 +209,7 @@ print(result)
 # Maps each response sentence to supporting document sentences
 ```
 
-## Direct intrinsic usage
+## Direct adapter function usage
 
 > **Advanced:** For custom adapter tasks, use the `Intrinsic` component and
 > `CustomIntrinsicAdapter` directly.
@@ -249,14 +249,14 @@ print(out)  # {"requirement_likelihood": 1.0}
 
 The `Intrinsic` component loads aLoRA adapters (falling back to LoRA) by task name.
 For OpenAI backends with Granite Switch, adapters are loaded from the model's
-HuggingFace repository configuration instead of the intrinsic catalog.
+Hugging Face repository configuration instead of the adapter function catalog.
 Output format is task-specific — `requirement-check` returns a likelihood score.
 
 ---
 
-## Guardian Intrinsics
+## Guardian adapter functions
 
-Safety and factuality checks use a separate set of Guardian-specific intrinsics:
+Safety and factuality checks use a separate set of Guardian-specific adapter functions:
 `guardian_check()`, `policy_guardrails()`, `factuality_detection()`, and
 `factuality_correction()`. These are documented in the
 [Safety Guardrails](../how-to/safety-guardrails) how-to guide.

docs/docs/advanced/lora-and-alora-adapters.md

@@ -18,9 +18,9 @@ Hugging Face account.
 > **Backend note:** Custom-trained adapters can only be loaded into `LocalHFBackend`.
 > They do not work with Ollama, OpenAI, or other remote backends.
 >
-> Granite Switch models ship with pre-trained intrinsic adapters embedded in the
+> Granite Switch models ship with pre-trained adapter functions embedded in the
 > model weights, which can be used via `OpenAIBackend` with
-> `load_embedded_adapters=True`. See [Intrinsics](./intrinsics) for details.
+> `load_embedded_adapters=True`. See [Adapter functions](./intrinsics.md) for details.
 
 ## LoRA vs aLoRA
 
@@ -104,7 +104,7 @@ weights. Requires `HF_TOKEN` set or a prior `huggingface-cli login`.
 > data includes proprietary, confidential, or personal information. Language models can
 > memorize details from small domain-specific datasets.
 
-If you intend to use the adapter as a Mellea intrinsic (so that it can be loaded by
+If you intend to use the adapter as a Mellea adapter function (so that it can be loaded by
 model ID rather than local path), pass `--intrinsic` and provide an `io.yaml` file:
 
 ```bash
@@ -160,7 +160,7 @@ backend.default_to_constraint_checking_alora = False
 Set it back to `True` to re-enable. This flag is per-backend instance and does not
 affect other sessions.
 
-**See also:** [Intrinsics](./intrinsics) |
+**See also:** [Adapter functions](./intrinsics.md) |
 [The Requirements System](../concepts/requirements-system) |
 [Write Custom Verifiers](../how-to/write-custom-verifiers) |
 [CLI Reference](../reference/cli)

docs/docs/advanced/prefix-caching-and-kv-blocks.md

@@ -131,6 +131,6 @@ Or pass `use_caches=False` at construction. The session behaviour is otherwise
 identical — disabling caching only affects whether prefill states are stored and
 reused.
 
-**See also:** [HuggingFace Transformers](../integrations/huggingface) |
-[Intrinsics](./intrinsics) |
-[LoRA and aLoRA Adapters](./lora-and-alora-adapters)
+**See also:** [Hugging Face Transformers](../integrations/huggingface.md) |
+[Adapter functions](./intrinsics.md) |
+[LoRA and aLoRA Adapters](./lora-and-alora-adapters.md)

docs/docs/concepts/architecture-vs-agents.md

@@ -135,7 +135,7 @@ orchestrator:
   with [`ChatContext`](../reference/glossary#chatcontext) and the `@tool` decorator. See
   [Tools and Agents](../how-to/tools-and-agents).
 - **Guarded agents** — combine the ReACT pattern with `requirements` and
-  [Guardian Intrinsics](../how-to/safety-guardrails) to enforce safety constraints
+  [Guardian adapter functions](../how-to/safety-guardrails.md) to enforce safety constraints
   at every step.
 - **Structured outputs** — use `@generative` with Pydantic models or `Literal` types
   to enforce type-safe structured output at each step. See

docs/docs/concepts/context-and-sessions.md

@@ -40,7 +40,7 @@ The backend is responsible for:
 - Making the network or process call to the LLM
 - Parsing the response into a typed representation where applicable
 
-Different backends — Ollama, OpenAI, HuggingFace, WatsonX — share the same
+Different backends — Ollama, OpenAI, Hugging Face, WatsonX — share the same
 component interface. A `Component` does not know which backend will render it.
 
 ### Contexts

docs/docs/examples/index.md

@@ -61,7 +61,7 @@ to run.
 
 | Category | What it shows |
 | -------- | ------------- |
-| `intrinsics/` | [Guardian Intrinsics](../how-to/safety-guardrails.md): `guardian_check()` for harm, jailbreak, social bias, groundedness; `policy_guardrails()`; `factuality_detection()` / `factuality_correction()` |
+| `intrinsics/` | [Guardian adapter functions](../how-to/safety-guardrails.md): `guardian_check()` for harm, jailbreak, social bias, groundedness; `policy_guardrails()`; `factuality_detection()` / `factuality_correction()` |
 | `safety/` | *(Examples removed — see [Guardian how-to guide](../how-to/safety-guardrails.md) for the current API. The `RepairTemplateStrategy` gap is tracked in [#1071](https://github.com/generative-computing/mellea/issues/1071).)* |
 
 ### Integration and deployment

docs/docs/getting-started/installation.md

@@ -27,7 +27,7 @@ Install extras for specific backends and features:
 
 ```bash
 pip install "mellea[litellm]"    # LiteLLM multi-provider (Anthropic, Bedrock, etc.)
-pip install "mellea[hf]"         # HuggingFace transformers for local inference
+pip install "mellea[hf]"         # Hugging Face Transformers for local inference
 pip install "mellea[watsonx]"    # IBM WatsonX
 pip install "mellea[tools]"      # Tool and agent dependencies (LangChain, smolagents)
 pip install "mellea[cli]"        # m serve, m alora, m decompose CLI commands
@@ -36,7 +36,7 @@ pip install "mellea[telemetry]"  # OpenTelemetry tracing and metrics
 
 ```bash
 uv add "mellea[litellm]"        # LiteLLM multi-provider (Anthropic, Bedrock, etc.)
-uv add "mellea[hf]"             # HuggingFace transformers for local inference
+uv add "mellea[hf]"             # Hugging Face Transformers for local inference
 uv add "mellea[watsonx]"        # IBM WatsonX
 uv add "mellea[tools]"          # Tool and agent dependencies (LangChain, smolagents)
 uv add "mellea[cli]"            # m serve, m alora, m decompose CLI commands

docs/docs/getting-started/quickstart.md

@@ -186,7 +186,7 @@ multi-turn conversations. Pass `ctx=ChatContext()` to `start_session()` for stat
 chat.
 
 **Backends** — Pluggable model providers. Ollama is the default. OpenAI, [LiteLLM](../reference/glossary#litellm--litellmbackend),
-HuggingFace, and WatsonX are also supported. See
+Hugging Face, and WatsonX are also supported. See
 [Backends and Configuration](../how-to/backends-and-configuration).
 
 ## Troubleshooting

docs/docs/how-to/backends-and-configuration.md

@@ -1,14 +1,14 @@
 ---
 title: "Backends and Configuration"
-description: "Configure Mellea to use Ollama, OpenAI, LiteLLM, HuggingFace, or WatsonX backends."
+description: "Configure Mellea to use Ollama, OpenAI, LiteLLM, Hugging Face, or WatsonX backends."
 # diataxis: how-to
 ---
 
 **Prerequisites:** `pip install mellea`, [Ollama](https://ollama.ai) for local inference
 or appropriate credentials for cloud backends.
 
 A backend is the engine that runs the LLM. Mellea ships with backends for Ollama,
-OpenAI-compatible APIs, LiteLLM, HuggingFace transformers, and IBM WatsonX. You
+OpenAI-compatible APIs, LiteLLM, Hugging Face Transformers, and IBM WatsonX. You
 configure the backend when you create a session.
 
 ## Default backend
@@ -128,13 +128,13 @@ print(str(result))
 # Output will vary — LLM responses depend on model and temperature.
 ```
 
-## HuggingFace backend
+## Hugging Face backend
 
 > **Backend note:** Requires `pip install "mellea[hf]"`. Models are downloaded from
-> HuggingFace Hub on first use. GPU recommended for reasonable inference speed.
-> Required for [Intrinsics](../advanced/intrinsics).
+> Hugging Face Hub on first use. GPU recommended for reasonable inference speed.
+> Required for [Adapter functions](../advanced/intrinsics.md).
 
-Run models locally using HuggingFace transformers:
+Run models locally using Hugging Face Transformers:
 
 ```python
 # Requires: mellea[hf]

docs/docs/how-to/safety-guardrails.md

@@ -1,18 +1,18 @@
 ---
 title: "Safety Guardrails"
-description: "Use Guardian Intrinsics to detect harmful, biased, ungrounded, or policy-violating content in LLM outputs."
+description: "Use Guardian adapter functions to detect harmful, biased, ungrounded, or policy-violating content in LLM outputs."
 # diataxis: how-to
 ---
 
 **Prerequisites:** `pip install "mellea[hf]"` for local inference; Apple Silicon or CUDA GPU recommended.
-Guardian Intrinsics work via `LocalHFBackend` (local HuggingFace inference) or `OpenAIBackend`
+Guardian adapter functions work via `LocalHFBackend` (local HuggingFace inference) or `OpenAIBackend`
 pointed at a Granite Switch endpoint.
 
-Guardian Intrinsics evaluate LLM outputs for safety and quality using LoRA adapters
-loaded directly into a HuggingFace backend — purpose-built for evaluation tasks, not
+Guardian adapter functions evaluate LLM outputs for safety and quality using LoRA adapters
+loaded directly into a Hugging Face backend — purpose-built for evaluation tasks, not
 general-purpose generation.
 
-> **Generation vs evaluation:** Guardian Intrinsics evaluate content; they do not
+> **Generation vs evaluation:** Guardian adapter functions evaluate content; they do not
 > generate responses. Your session's generation backend (Ollama, OpenAI, etc.) is
 > unchanged. A separate `LocalHFBackend` instance handles evaluation only.
 
@@ -316,7 +316,7 @@ else:
 
 ## Limitations
 
-Guardian Intrinsics return a numeric score (or label string) rather than a
+Guardian adapter functions return a numeric score (or label string) rather than a
 [`Requirement`](../reference/glossary#requirement) instance, so they cannot be
 passed to `m.validate()` or wired into `RepairTemplateStrategy` the way the
 deprecated `GuardianCheck` could. The practical workaround is to call
@@ -339,4 +339,4 @@ Guardian functions also do not emit `mellea.requirement` metrics — see
 > [`factuality_correction.py`](https://github.com/generative-computing/mellea/blob/main/docs/examples/intrinsics/factuality_correction.py),
 > and [`policy_guardrails.py`](https://github.com/generative-computing/mellea/blob/main/docs/examples/intrinsics/policy_guardrails.py).
 
-**See also:** [Intrinsics](../advanced/intrinsics) | [LoRA and aLoRA Adapters](../advanced/lora-and-alora-adapters) | [Tutorial: Making Agents Reliable](../tutorials/making-agents-reliable)
+**See also:** [Adapter functions](../advanced/intrinsics.md) | [LoRA and aLoRA Adapters](../advanced/lora-and-alora-adapters.md) | [Tutorial: Making Agents Reliable](../tutorials/04-making-agents-reliable.md)

docs/docs/how-to/use-context-and-sessions.md

@@ -100,7 +100,7 @@ while keeping the session's backend and other configuration intact.
 
 Subclass `MelleaSession` and override any method to inject custom behavior.
 The example below gates all incoming chat messages through
-[Guardian Intrinsics](../how-to/safety-guardrails) safety checks:
+[Guardian adapter functions](../how-to/safety-guardrails.md) safety checks:
 
 ```python
 from typing import Literal

docs/docs/integrations/huggingface.md

@@ -1,10 +1,10 @@
 ---
-title: "HuggingFace Transformers"
-description: "Run Mellea on local hardware with LocalHFBackend and HuggingFace Transformers."
+title: "Hugging Face Transformers"
+description: "Run Mellea on local hardware with LocalHFBackend and Hugging Face Transformers."
 # diataxis: how-to
 ---
 
-`LocalHFBackend` uses [HuggingFace Transformers](https://huggingface.co/docs/transformers)
+`LocalHFBackend` uses [Hugging Face Transformers](https://huggingface.co/docs/transformers)
 for local inference. It is designed for experimental Mellea features — aLoRA adapters,
 constrained decoding, and span-based context — that are not yet available on
 server-based backends.
@@ -83,13 +83,13 @@ See [Prefix Caching and KV Blocks](../advanced/prefix-caching-and-kv-blocks) for
 
 ## aLoRA adapters
 
-`LocalHFBackend` supports [Activated LoRA (aLoRA)](../advanced/lora-and-alora-adapters)
+`LocalHFBackend` supports [aLoRA](../advanced/lora-and-alora-adapters)
 adapters — lightweight domain-specific requirement validators that run on local GPU
 hardware. See the aLoRA guide for training and usage.
 
-> **Tip:** For intrinsics without local GPU requirements, Granite Switch models
+> **Tip:** For adapter functions without local GPU requirements, Granite Switch models
 > serve pre-embedded adapters via vLLM and the OpenAI backend. See
-> [Intrinsics](../advanced/intrinsics) for details.
+> [Adapter functions](../advanced/intrinsics.md) for details.
 
 ## Vision support
 

docs/docs/integrations/openai.md

@@ -258,10 +258,10 @@ m = MelleaSession(
 > LiteLLM provides a verified integration — see
 > [Backends and Configuration](../how-to/backends-and-configuration).
 
-## Intrinsics with Granite Switch
+## Adapter functions with Granite Switch
 
 Granite Switch models embed LoRA/aLoRA adapters directly in the model weights.
-When served via vLLM, these adapters enable intrinsic functions (RAG quality
+When served via vLLM, these adapters enable adapter functions (RAG quality
 checks, safety evaluation, requirement validation) through the OpenAI-compatible
 API without loading adapter weights at runtime.
 
@@ -290,13 +290,13 @@ backend = OpenAIBackend(
 )
 ```
 
-The high-level intrinsic wrappers (`rag.check_answerability`,
+The high-level adapter function wrappers (`rag.check_answerability`,
 `core.check_certainty`, etc.) work identically with this backend. See
-[Intrinsics](../advanced/intrinsics) for the full list of available intrinsics.
+[Adapter functions](../advanced/intrinsics.md) for the full list of available adapter functions.
 
 > **Note:** `load_embedded_adapters=True` downloads adapter I/O configurations
-> from the model's HuggingFace repository on first use. No adapter weights are
-> transferred — the adapters are already part of the model. Only intrinsics
+> from the model's Hugging Face repository on first use. No adapter weights are
+> transferred — the adapters are already part of the model. Only adapter functions
 > embedded in the model are available — check the model's `adapter_index.json`
 > for the list.
 
@@ -316,7 +316,7 @@ backend = OpenAIBackend(
     load_embedded_adapters=False,
 )
 
-# Load a single adapter from the model's HuggingFace repo
+# Load a single adapter from the model's Hugging Face repo
 adapters = EmbeddedIntrinsicAdapter.from_hub(
     IBM_GRANITE_SWITCH_4_1_3B_PREVIEW.hf_model_name,
     intrinsic_name="answerability",