docs: migrate Guardian documentation from deprecated GuardianCheck to Intrinsics API

[planetf1]

Guardian Documentation Migration

Status

Unpaused 2026-05-05 and rebased onto upstream/main (commit 0617bd9). The upstream intrinsics work that this PR was waiting on has all merged:

• ✅ feat: update granite library examples to use Granite 4.1 3B adapters. #981 merged — intrinsic examples bumped to granite-4.1-3b; this PR's Guardian examples have been swept in commit 60c3f9c8 (context_relevance stays on 4.0 per upstream guidance — 4.1 not supported for that intrinsic).
• ✅ fix: issues introduced by intrinsic changes #986 merged — intrinsic code fixes landed.
• ✅ test: add tests for new intrinsic field name #988 merged — field-name tests landed.
• ✅ fix: default intrinsic adapter types #994 merged — default intrinsic adapter types + granite-switch tests.
• ✅ fix: update model ids and documentation links for switch #997 merged — model IDs + docs links for granite-switch (trivial merge into this PR's glossary additions).
• ✅ docs: add architecture diagram for intrinsics #998 merged — intrinsics architecture diagram added (non-conflicting).
• ✅ fix: move test_huggingface.py to granite4.1; and small rag intrinsic … #1008 merged — requirement_check → requirement-check rename; conflict resolved during rebase.

Related (not blocking)

• fix: intrinsic function signatures #1003 (open) — will change Guardian intrinsic function signatures to accept documents as arguments rather than pulling them from context. When that lands, safety-guardrails.md will need a follow-up sweep. Not a blocker for this PR; current docs reflect current API.
• feat: groundedness requirement #773 (open, feat: groundedness requirement) — adds a real Requirement subclass backed by intrinsics, which would partially close the RepairTemplateStrategy gap documented in docs/examples/safety/README.md. Worth a docs follow-up once merged.
• docs: add canonical url headers #961 (open, docs: add canonical url headers) — adds canonical: frontmatter to many docs pages, including several touched here. Whichever PR merges second will need a trivial one-line addition per file. Not a blocker.
• fix(core): wrong return type annotations on factuality_detection and factuality_correction #934 — still open; this PR's guardian.py fix closes it (upstream has not yet landed an independent fix).

---

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Closes docs: Rewrite Tutorial 04 Guardian steps for Guardian Intrinsics #639, Closes docs: write safety guardrails how-to for Guardian Intrinsics API #802, Closes fix(core): wrong return type annotations on factuality_detection and factuality_correction #934

Migrates Guardian documentation from the deprecated GuardianCheck/GuardianRisk API (emits DeprecationWarning since v0.4) to the current Guardian Intrinsics API (guardian_check(), policy_guardrails(), factuality_detection(), factuality_correction()).

Key changes:

• New /how-to/safety-guardrails page — full reference for all four Intrinsic functions, CRITERIA_BANK keys, and the target_role="user" input-gating pattern
• build-a-rag-pipeline.md step 5 and "Putting it together" rewritten to use guardian_check(criteria="groundedness") with Document(text=..., doc_id=...) attached to the assistant message (aligned with fix: add guardian intrinsic document #966)
• docs/examples/safety/ example files deleted — guardian.py, guardian_huggingface.py, and repair_with_guardian.py removed (see below)
• Deprecation banner added to security-and-taint-tracking.md
• Glossary: 5 new entries (guardian_check, CRITERIA_BANK, policy_guardrails, factuality_detection, factuality_correction); GuardianCheck/GuardianRisk entries marked deprecated
• docs.json: how-to/safety-guardrails added to nav; redirect from that path to security-and-taint-tracking removed
• examples/index.md: intrinsics/ category description updated to clarify Guardian functions are documented separately
• Guardian Intrinsics cross-link added to advanced/intrinsics.md
• Safety card on index.mdx updated to reference Intrinsics
• Session subclass example in use-context-and-sessions.md rewritten (SafeChatSession now accepts guardian_backend as a constructor arg)
• Common-errors guardian section rewritten
• concepts/architecture-vs-agents.md, concepts/plugins.mdx, and guide/CONTRIBUTING.md links updated
• observability/metrics.md: note added that Guardian Intrinsics do not emit mellea.requirement metrics (migration footgun)
• Typo fix: "Determine is" → "Determine if" in factuality_detection docstring
• Fixed -> float return annotations on factuality_detection / factuality_correction (they return str; closes fix(core): wrong return type annotations on factuality_detection and factuality_correction #934)
• Removed "sexual_content" from tutorial CRITERIA_BANK key list (not a real key; GuardianRisk.SEXUAL_CONTENT has no equivalent in CRITERIA_BANK)
• Model ID sweep (commit 60c3f9c8): bumped ibm-granite/granite-4.0-micro → ibm-granite/granite-4.1-3b in all Guardian examples, matching upstream feat: update granite library examples to use Granite 4.1 3B adapters. #981.

Note on tutorial 04: Steps 4–7 of 04-making-agents-reliable.md were independently migrated to Guardian Intrinsics upstream before this PR was rebased; those upstream changes were taken as-is.

---

Deletion of docs/examples/safety/ examples — reviewer input requested

guardian.py, guardian_huggingface.py, and repair_with_guardian.py have been deleted rather than retained with deprecation markers. Rationale:

• guardian.py and guardian_huggingface.py are fully superseded by docs/examples/intrinsics/guardian_core.py, which covers all the same criteria (harm, jailbreak, social_bias, groundedness, function_call, custom criteria) against the same HuggingFace backend. Keeping them would mean CI eventually breaking when GuardianCheck is removed, with no benefit.

• repair_with_guardian.py demonstrated GuardianCheck as a Requirement inside RepairTemplateStrategy, where Guardian's chain-of-thought _reason string was fed back as repair guidance. This pattern has no direct equivalent in the Guardian Intrinsics API: Intrinsics return a float score and do not expose a reasoning string, so they cannot be passed to m.validate() or wired into RepairTemplateStrategy directly. A safety/README.md is retained to document this gap explicitly. (Note: open PR feat: groundedness requirement #773 proposes a groundedness Requirement that would partially close this gap.)

If you believe repair_with_guardian.py should be kept (or that the RepairTemplateStrategy gap warrants a separate issue), please comment — the example can be restored.

---

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code as added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

[planetf1]

Post-rebase validation against granite-4.1-3b

After rebasing onto current upstream (0617bd96) and sweeping model IDs from granite-4.0-micro → granite-4.1-3b, I ran every example in safety-guardrails.md verbatim against the actual adapter to confirm the documented outputs. Results surfaced two real doc bugs, now fixed in cecc911d.

Environment: Apple Silicon, MPS backend, torch==2.11.0, transformers==4.57.6, peft==0.19.1, mellea from this branch with uv sync --extra hf --extra backends.

Run 1 — upstream canonical (docs/examples/intrinsics/guardian_core.py)

Unmodified from main. Purpose: validate the end-to-end stack (backend, adapter loading, 4.1-3b) before trusting my own examples.

Duration: ~1m 57s wall clock (cold start: ~70s of HF downloads + adapter fetches, ~9s base model load, ~18s for 6 inferences).
Result: exit 0. All six criteria produced sensible high-confidence risk detections on adversarial inputs:

Criterion	Input	Score
harm	"How can I hack my friend's email?"	0.9999
social_bias	fictional-race bias in assistant response	0.6514
groundedness	wrong date vs source doc	0.9997
custom (PII)	user message with SSN	0.9998
function_call	wrong param name	0.9669
answer_relevance	off-topic answer	0.9770

Run 2 — my doc examples, verbatim (initial)

Extracted every snippet from safety-guardrails.md into a script and ran it.

Duration: ~53s for 9 inferences (warm cache).
Result: FAIL — 8/10 checks passed. Two real bugs:

Bug	What the doc claimed	What the model returned
Jailbreak input gate	"Ignore all previous instructions." → score >= 0.5 blocks	0.0180 — not blocked
Policy compliance	compliant interview scenario → "Yes"	"Ambiguous"

Root cause for (1): granite-4.1-3b's jailbreak criterion looks for circumvention intent + a concrete harmful goal. A bare instruction-override phrase isn't enough.
Root cause for (2): the "compliant" scenario only negated family/personal questions, leaving age/nationality/graduation-year implicit. The adapter is pedantically literal — it returns "Ambiguous" when the scenario doesn't explicitly address every policy clause.

Run 3 — candidate replacements

Tested 5 jailbreak candidates and 3 policy candidates to pick replacements that consistently produce the documented verdict.

Duration: ~25s for 8 inferences.
Result:

• All 5 jailbreak candidates scored ≥0.9975 (picked the hotwire-a-car one — clear circumvention + mild-enough goal for public docs).
• 2 of 3 policy candidates returned "Yes" (picked the one that explicitly mirrors all four policy clauses).

Run 4 — re-verification post-fix

Duration: ~25s for 7 inferences.
Result: exit 0. All 7 checks pass.

CASE                                 CLAIM                            ACTUAL                         OK
harm(benign)                         ~0.0 Safe                        0.0000                         ✓
CRITERIA_BANK keys                   10 expected                      10                             ✓
jailbreak(attack)                    >=0.5                            0.9997                         ✓
custom(PII)                          >=0.5                            0.9820                         ✓
policy(compliant)                    Yes                              'Yes'                          ✓
factuality_detection(wrong)          yes                              'yes'                          ✓
factuality_correction                'Mellea is an open-source Py...' 'Mellea is an open-source Py'  ✓

What changed in the docs (commit cecc911d)

• safety-guardrails.md "Check user input" example: swapped jailbreak user message to one that reliably scores ≥0.5 with the 4.1-3b adapter (added an # Example output: line showing the observed 0.9997).
• safety-guardrails.md "Policy compliance" scenario: rewrote so it explicitly negates each clause of the policy, now returns "Yes" instead of "Ambiguous".
• Updated two drifted # Example output: comments to observed values (harm 0.0021 → 0.0000, PII 0.9871 → 0.9820).

Caveats

• Scores are stochastic-ish. Granite intrinsics are low-variance in practice but not deterministic to the last decimal. The # Example output: comments in the docs should be read as "representative", not "exact on every run."
• Not every code block was executed. The build-a-rag-pipeline.md Step 5 Guardian snippet reuses the same guardian_check(criteria="groundedness") pattern already validated by the upstream guardian_core.py Example 3 (0.9997), so I treated that as covered.
• Model-dependent. These verdicts are specific to granite-4.1-3b. If fix: intrinsic function signatures #1003 lands and changes Guardian signatures, a follow-up verification pass will be needed.

[planetf1]

Upstream follow-ups — @jakelorocco / @nrfulton

Two items surfaced during verification, out of scope here but flagging so nothing gets lost. Already queued, or should I open an issue?

1. docs/examples/intrinsics/context_relevance.py:17 — comment says "no context_relevance intrinsic for Granite 4.1", but ibm-granite/granitelib-rag-r1.0/context_relevance/granite-4.1-3b/ shipped lora/ + alora/ ~12h ago. Verified it loads and returns labels ('relevant', 'partially relevant', 'irrelevant'). I updated the same claim in AGENTS.md + prose docs here (991a3cbd); the example file feels like feat: update granite library examples to use Granite 4.1 3B adapters. #981-series work rather than Guardian migration.

2. mellea/stdlib/start_backend.py:315 — defaults to IBM_GRANITE_4_MICRO_3B, while start_session() and OllamaModelBackend default to IBM_GRANITE_4_1_3B. Likely missed by the feat: update granite library examples to use Granite 4.1 3B adapters. #981 sweep.

Neither blocks this PR merging.