From 3892c0aab3824baf94d3e0bdcda8832797cf8372 Mon Sep 17 00:00:00 2001 From: "Paul S. Schweigert" Date: Tue, 31 Mar 2026 17:40:39 -0400 Subject: [PATCH 1/2] chore: add info for working with intrinsics to AGENTS.md Signed-off-by: Paul S. Schweigert --- AGENTS.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3bb1fe75c..9a788d44c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -146,3 +146,37 @@ Found a bug, workaround, or pattern? Update the docs: - **Issue/workaround?** → Add to Section 7 (Common Issues) in this file - **Usage pattern?** → Add to [`docs/AGENTS_TEMPLATE.md`](docs/AGENTS_TEMPLATE.md) - **New pitfall?** → Add warning near relevant section + +## 13. Working with Intrinsics + +Intrinsics are specialized LoRA adapters hosted on Hugging Face that add task-specific capabilities (RAG evaluation, safety checks, calibration, etc.) to Granite models. + +**⚠️ Before writing code that uses an intrinsic, fetch its README from Hugging Face.** Each README contains the authoritative specification for input format, output format, intended use, and examples. Do not guess these details. + +### Hugging Face Repositories + +| Repo | Purpose | Intrinsics | +|------|---------|------------| +| [`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 + +Each intrinsic has a README at a predictable URL. The path depends on the repo: + +**RAG intrinsics** (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): +``` +https://huggingface.co/ibm-granite/granitelib-{core,guardian}-r1.0/blob/main/{intrinsic_name}/granite-4.0-micro/README.md +``` + +### 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 +- **Helper functions**: `mellea/stdlib/components/intrinsic/rag.py` and `core.py` — high-level wrappers like `check_answerability()`, `check_certainty()`, etc. From f5bf353864242d033912aa4d8407f08202e58400 Mon Sep 17 00:00:00 2001 From: "Paul S. Schweigert" Date: Fri, 3 Apr 2026 16:41:58 -0400 Subject: [PATCH 2/2] review comments: Signed-off-by: Paul S. Schweigert --- AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9a788d44c..ffd472ba0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -149,11 +149,52 @@ Found a bug, workaround, or pattern? Update the docs: ## 13. Working with Intrinsics -Intrinsics are specialized LoRA adapters hosted on Hugging Face that add task-specific capabilities (RAG evaluation, safety checks, calibration, etc.) to Granite models. +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. -**⚠️ Before writing code that uses an intrinsic, fetch its README from Hugging Face.** Each README contains the authoritative specification for input format, output format, intended use, and examples. Do not guess these details. +### Using Intrinsics in Mellea -### Hugging Face Repositories +**Prefer the high-level wrappers** in `mellea/stdlib/components/intrinsic/`. These handle adapter loading, context formatting, and output parsing for you: + +| Module | Function | Description | +|--------|----------|-------------| +| `core` | `check_certainty(context, backend)` | Model certainty about its last response (0–1) | +| `core` | `requirement_check(context, backend, requirement)` | Whether text meets a requirement (0–1) | +| `core` | `find_context_attributions(response, documents, context, backend)` | Sentences that influenced the response | +| `rag` | `check_answerability(question, documents, context, backend)` | Whether documents can answer a question (0–1) | +| `rag` | `rewrite_question(question, context, backend)` | Rewrite question into a retrieval query | +| `rag` | `clarify_query(question, documents, context, backend)` | Generate clarification or return "CLEAR" | +| `rag` | `find_citations(response, documents, context, backend)` | Document sentences supporting the response | +| `rag` | `check_context_relevance(question, document, context, backend)` | Whether a document is relevant (0–1) | +| `rag` | `flag_hallucinated_content(response, documents, context, backend)` | Flag potentially hallucinated sentences | + +```python +from mellea.backends.huggingface import LocalHFBackend +from mellea.stdlib.components import Message +from mellea.stdlib.components.intrinsic import core +from mellea.stdlib.context import ChatContext + +backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro") +context = ( + ChatContext() + .add(Message("user", "What is the square root of 4?")) + .add(Message("assistant", "The square root of 4 is 2.")) +) +score = core.check_certainty(context, backend) +``` + +For lower-level control (custom adapters, model options), use `mfuncs.act()` with `Intrinsic` directly — see examples in `docs/examples/intrinsics/`. + +### 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 +- **Helper functions**: `mellea/stdlib/components/intrinsic/rag.py` and `core.py` + +### Adding New Intrinsics + +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. + +**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 | |------|---------|------------| @@ -161,22 +202,12 @@ Intrinsics are specialized LoRA adapters hosted on Hugging Face that add task-sp | [`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 - -Each intrinsic has a README at a predictable URL. The path depends on the repo: - -**RAG intrinsics** (no model subfolder): +**README URLs** — RAG intrinsics (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 intrinsics (include model subfolder): ``` https://huggingface.co/ibm-granite/granitelib-{core,guardian}-r1.0/blob/main/{intrinsic_name}/granite-4.0-micro/README.md ``` - -### 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 -- **Helper functions**: `mellea/stdlib/components/intrinsic/rag.py` and `core.py` — high-level wrappers like `check_answerability()`, `check_certainty()`, etc.