From be3c214ab67304c164ea4992959d3929089497d4 Mon Sep 17 00:00:00 2001
From: Rafael Vasquez <rafvasq21@gmail.com>
Date: Tue, 20 Oct 2026 13:50:06 -0400
Subject: [PATCH 1/6] docs(examples): standardize sampling and agents READMEs
 and update catalog

- Add navigation README for docs/examples/sampling/
- Standardize header docstrings in sampling and agent scripts
- Index react_using_mellea.py in docs/examples/agents/README.md
- Register sampling/, requirements/, and audio_text_models/ in docs/docs/examples/index.md

Assisted-by: IBM Bob
Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
---
 docs/docs/examples/index.md                   |  3 ++
 docs/examples/agents/README.md                | 42 ++++---------------
 .../agents/react/react_from_scratch/react.py  |  8 ++++
 .../react_from_scratch/react_instruct.py      |  8 ++++
 .../agents/react/react_using_mellea.py        |  8 +++-
 docs/examples/sampling/README.md              | 10 +++++
 .../sampling/python_code_generation_preset.py | 19 ++++-----
 .../sampling/python_plotting_preset.py        | 25 ++++-------
 8 files changed, 58 insertions(+), 65 deletions(-)
 create mode 100644 docs/examples/sampling/README.md

diff --git a/docs/docs/examples/index.md b/docs/docs/examples/index.md
index d640ef2a5b..f49ac75534 100644
--- a/docs/docs/examples/index.md
+++ b/docs/docs/examples/index.md
@@ -62,6 +62,7 @@ to run.
 | Category | What it shows |
 | -------- | ------------- |
 | `intrinsics/` | [Guardian adapter functions](../how-to/safety-guardrails.md): `guardian_check()` for harm, jailbreak, social bias, groundedness; `policy_guardrails()`; `factuality_detection()` / `factuality_correction()` |
+| `requirements/` | Validating code generation and plotting with execution tiers and security policies |
 | `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
@@ -81,12 +82,14 @@ to run.
 | `aLora/` | Training aLoRA adapters for fast constraint checking; performance optimisation |
 | `intrinsics/` | *(Non-Guardian)* Answer relevance, hallucination detection, citation validation — specialised adapter-backed checks. For Guardian safety functions see [Safety and validation](#safety-and-validation) above |
 | `granite-switch/` | Running adapter functions via OpenAI backend with Granite Switch embedded adapters |
+| `sampling/` | Pre-configured sampling presets for Python code generation and data plotting |
 | `sofai/` | Two-tier sampling: fast-model iteration with escalation to a slow model; cost optimisation |
 
 ### Multimodal
 
 | Category | What it shows |
 | -------- | ------------- |
+| `audio_text_models/` | Audio-text-to-text models with `AudioBlock` and llama-server |
 | `image_text_models/` | Vision-language models, `ImageBlock`, multimodal prompting, backend support matrix |
 
 ### Observability
diff --git a/docs/examples/agents/README.md b/docs/examples/agents/README.md
index e105b96437..80720e22b6 100644
--- a/docs/examples/agents/README.md
+++ b/docs/examples/agents/README.md
@@ -1,39 +1,11 @@
 # Agent Examples
 
-This directory contains examples of implementing agent patterns with Mellea, specifically the ReACT (Reasoning and Acting) pattern.
+Examples demonstrating agent architectures and the ReACT (Reasoning and Acting) loop in Mellea.
 
-## Files
+## Examples
 
-### [react.py](./react/react_from_scratch/react.py)
-A complete implementation of the ReACT agent pattern that combines reasoning and action in an iterative loop. The agent:
-- Thinks about what to do next
-- Selects an appropriate tool/action
-- Generates arguments for the tool
-- Observes the result
-- Determines if the goal is achieved
-
-**Key Features:**
-- Custom `ReactTool` and `ReactToolbox` classes for tool management
-- Dynamic tool selection using Pydantic schemas
-- Iterative thought-action-observation loop
-- Example with weather lookup tools
-
-**Usage:**
-```python
-python docs/examples/agents/react/react_from_scratch/react.py
-```
-
-### [react_instruct.py](./react/react_from_scratch/react_instruct.py)
-An alternative implementation of the ReACT pattern using Mellea's instruct-validate-repair paradigm.
-
-## Concepts Demonstrated
-
-- **Tool Management**: Creating and organizing tools for agent use
-- **Dynamic Prompting**: Building system prompts with tool descriptions
-- **Chat Context**: Using `ChatContext` for multi-turn conversations
-- **Structured Output**: Using Pydantic models for type-safe responses
-- **Iterative Reasoning**: Implementing thought-action-observation loops
-
-## Related Documentation
-
-- See `mellea/stdlib/requirements/tool_reqs.py` for tool requirements
\ No newline at end of file
+| File | Description |
+| :--- | :--- |
+| [`react/react_using_mellea.py`](./react/react_using_mellea.py) | ReACT agent using Mellea's stdlib `react()` framework with LangChain tool integration. |
+| [`react/react_from_scratch/react.py`](./react/react_from_scratch/react.py) | ReACT loop built from scratch using custom tool abstractions and Pydantic schemas. |
+| [`react/react_from_scratch/react_instruct.py`](./react/react_from_scratch/react_instruct.py) | ReACT loop implemented using Mellea's instruct-validate-repair paradigm. |
diff --git a/docs/examples/agents/react/react_from_scratch/react.py b/docs/examples/agents/react/react_from_scratch/react.py
index b42e798ab3..40117e0ce1 100644
--- a/docs/examples/agents/react/react_from_scratch/react.py
+++ b/docs/examples/agents/react/react_from_scratch/react.py
@@ -1,4 +1,12 @@
 # pytest: ollama, e2e, qualitative
+"""ReACT agent implementation built from scratch.
+
+Demonstrates implementing the ReACT (Reasoning and Acting) loop from first
+principles, combining tool selection, argument generation, and observation.
+
+Usage:
+    uv run python docs/examples/agents/react/react_from_scratch/react.py
+"""
 
 import datetime
 import inspect
diff --git a/docs/examples/agents/react/react_from_scratch/react_instruct.py b/docs/examples/agents/react/react_from_scratch/react_instruct.py
index 694d998c53..efb68f02d3 100644
--- a/docs/examples/agents/react/react_from_scratch/react_instruct.py
+++ b/docs/examples/agents/react/react_from_scratch/react_instruct.py
@@ -1,4 +1,12 @@
 # pytest: ollama, e2e, qualitative
+"""ReACT agent using instruct-validate-repair.
+
+Demonstrates implementing the ReACT (Reasoning and Acting) loop using Mellea's
+instruct-validate-repair paradigm for robust tool calling and reasoning.
+
+Usage:
+    uv run python docs/examples/agents/react/react_from_scratch/react_instruct.py
+"""
 
 import datetime
 import inspect
diff --git a/docs/examples/agents/react/react_using_mellea.py b/docs/examples/agents/react/react_using_mellea.py
index 422e8f3e54..b31e952dd6 100644
--- a/docs/examples/agents/react/react_using_mellea.py
+++ b/docs/examples/agents/react/react_using_mellea.py
@@ -1,6 +1,12 @@
 # pytest: ollama, e2e, qualitative, slow
+"""ReACT agent using Mellea's built-in react() framework.
 
-"""React examples using the Mellea library's framework."""
+Demonstrates the ReACT (Reasoning and Acting) loop with tool integration,
+using Mellea's stdlib react() function and LangChain tool interoperability.
+
+Usage:
+    uv run python docs/examples/agents/react/react_using_mellea.py
+"""
 
 import asyncio
 
diff --git a/docs/examples/sampling/README.md b/docs/examples/sampling/README.md
new file mode 100644
index 0000000000..d81eb454f8
--- /dev/null
+++ b/docs/examples/sampling/README.md
@@ -0,0 +1,10 @@
+# Sampling Examples
+
+Pre-configured sampling presets and strategies for constrained generation tasks such as Python code generation and data plotting.
+
+## Examples
+
+| File | Description |
+| :--- | :--- |
+| [`python_code_generation_preset.py`](./python_code_generation_preset.py) | Python code generation preset bundling extraction, syntax, and execution requirements with automatic repair feedback. |
+| [`python_plotting_preset.py`](./python_plotting_preset.py) | Matplotlib plotting preset bundling headless backend setup, plot file output validation, and sandbox execution. |
diff --git a/docs/examples/sampling/python_code_generation_preset.py b/docs/examples/sampling/python_code_generation_preset.py
index 1b2296abcf..4a867fbdcb 100644
--- a/docs/examples/sampling/python_code_generation_preset.py
+++ b/docs/examples/sampling/python_code_generation_preset.py
@@ -1,16 +1,11 @@
 # pytest: e2e, qualitative, ollama
-"""Example demonstrating python_code_generation_sampling() preset.
-
-Shows how the preset bundles requirements and feedback into a reusable
-configuration for Python code generation tasks, with automatic repair on failure.
-
-The preset handles:
-1. Code extraction validation
-2. Syntax validation
-3. Execution validation with optional sandbox isolation
-4. Import restrictions (optional allowlist)
-5. Output size limits
-6. Model-friendly repair feedback for each failure type
+"""Python code generation sampling preset with automatic repair.
+
+Demonstrates python_code_generation_sampling(), which bundles extraction, syntax,
+and execution requirements with repair feedback into a reusable configuration.
+
+Usage:
+    uv run python docs/examples/sampling/python_code_generation_preset.py
 """
 
 import mellea
diff --git a/docs/examples/sampling/python_plotting_preset.py b/docs/examples/sampling/python_plotting_preset.py
index 72c9e6dbc5..502ee6c462 100644
--- a/docs/examples/sampling/python_plotting_preset.py
+++ b/docs/examples/sampling/python_plotting_preset.py
@@ -1,21 +1,12 @@
 # pytest: e2e, qualitative, ollama
-"""Example demonstrating python_plotting_sampling() preset.
-
-Shows how the plotting preset bundles Python code generation requirements with
-matplotlib-specific constraints for headless rendering and file output validation.
-
-The preset validates:
-1. Python code extraction and syntax
-2. Matplotlib headless backend configuration (matplotlib.use('Agg'))
-3. Plot file output (savefig() call with expected path)
-4. Code execution with sandbox isolation (enabled by default)
-5. Import restrictions and output size limits
-
-Plotting typically requires more repair iterations and stricter sandboxing than
-general code generation, which this preset reflects in its defaults:
-- loop_budget=3 (vs. 2 for code generation)
-- use_sandbox=True (vs. False for code generation)
-- timeout_seconds=10 (vs. 5 for code generation)
+"""Matplotlib plotting sampling preset with headless validation.
+
+Demonstrates python_plotting_sampling(), which bundles Python code generation
+requirements with headless matplotlib backend configuration, savefig() output
+validation, and execution sandboxing.
+
+Usage:
+    uv run python docs/examples/sampling/python_plotting_preset.py
 """
 
 import tempfile

From d2af76a5fa31df207c10c1a929dd1f3a389700c0 Mon Sep 17 00:00:00 2001
From: Rafael Vasquez <rafvasq21@gmail.com>
Date: Mon, 26 Oct 2026 11:32:19 -0400
Subject: [PATCH 2/6] docs(examples): address review comments on sampling
 README and docstrings Assisted-by: IBM Bob

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
---
 docs/examples/requirements/README.md          |  3 +++
 docs/examples/sampling/README.md              | 10 +++++---
 .../sampling/python_code_generation_preset.py | 13 +++++++++--
 .../sampling/python_plotting_preset.py        | 23 +++++++++++++++++--
 4 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/docs/examples/requirements/README.md b/docs/examples/requirements/README.md
index 9444a9b54b..4697acd0fa 100644
--- a/docs/examples/requirements/README.md
+++ b/docs/examples/requirements/README.md
@@ -1,5 +1,8 @@
 # Requirements Examples
 
+For a higher-level interface that bundles these requirements into ready-to-use presets,
+see [`sampling/`](../sampling/README.md).
+
 This directory contains examples for using Mellea's requirement validation system,
 including specialized requirements for RAG (Retrieval-Augmented Generation) workflows
 and code generation tasks like plotting.
diff --git a/docs/examples/sampling/README.md b/docs/examples/sampling/README.md
index d81eb454f8..fa4ea47802 100644
--- a/docs/examples/sampling/README.md
+++ b/docs/examples/sampling/README.md
@@ -1,10 +1,14 @@
 # Sampling Examples
 
-Pre-configured sampling presets and strategies for constrained generation tasks such as Python code generation and data plotting.
+Pre-configured sampling presets for constrained generation tasks. A preset bundles
+a set of requirements with a repair strategy so a common task works in one call —
+as an alternative to assembling requirements individually. See
+[`requirements/`](../requirements/README.md) for the lower-level building blocks
+these presets wrap.
 
 ## Examples
 
 | File | Description |
 | :--- | :--- |
-| [`python_code_generation_preset.py`](./python_code_generation_preset.py) | Python code generation preset bundling extraction, syntax, and execution requirements with automatic repair feedback. |
-| [`python_plotting_preset.py`](./python_plotting_preset.py) | Matplotlib plotting preset bundling headless backend setup, plot file output validation, and sandbox execution. |
+| [`python_code_generation_preset.py`](./python_code_generation_preset.py) | Python code generation preset bundling extraction, syntax, and import-check requirements with automatic repair feedback. By default (`use_sandbox=False`) generated code is validated statically — pass `use_sandbox=True` to run it in Docker. |
+| [`python_plotting_preset.py`](./python_plotting_preset.py) | Matplotlib plotting preset bundling headless backend configuration and savefig() output validation. Most examples in this file override the default to `use_sandbox=False` (static validation); `example_without_output_path` uses the sandbox default and requires Docker. |
diff --git a/docs/examples/sampling/python_code_generation_preset.py b/docs/examples/sampling/python_code_generation_preset.py
index 4a867fbdcb..b6d5e3b209 100644
--- a/docs/examples/sampling/python_code_generation_preset.py
+++ b/docs/examples/sampling/python_code_generation_preset.py
@@ -1,8 +1,17 @@
 # pytest: e2e, qualitative, ollama
 """Python code generation sampling preset with automatic repair.
 
-Demonstrates python_code_generation_sampling(), which bundles extraction, syntax,
-and execution requirements with repair feedback into a reusable configuration.
+Demonstrates python_code_generation_sampling(), which bundles code extraction,
+syntax checking, and import validation into a reusable configuration with
+automatic repair feedback.
+
+By default (`use_sandbox=False`) generated code is validated statically — the
+preset parses and import-checks the code but does not execute it. Pass
+`use_sandbox=True` to run the code in a Docker sandbox instead.
+
+Prerequisites:
+    ollama pull granite4.2:3b
+    ollama serve
 
 Usage:
     uv run python docs/examples/sampling/python_code_generation_preset.py
diff --git a/docs/examples/sampling/python_plotting_preset.py b/docs/examples/sampling/python_plotting_preset.py
index 502ee6c462..5ddb04e687 100644
--- a/docs/examples/sampling/python_plotting_preset.py
+++ b/docs/examples/sampling/python_plotting_preset.py
@@ -2,8 +2,19 @@
 """Matplotlib plotting sampling preset with headless validation.
 
 Demonstrates python_plotting_sampling(), which bundles Python code generation
-requirements with headless matplotlib backend configuration, savefig() output
-validation, and execution sandboxing.
+requirements with headless matplotlib backend configuration and savefig() output
+validation.
+
+The plotting preset defaults to `use_sandbox=True`, but most examples in this
+file override that with `use_sandbox=False` so they run as static validation
+(parse and import-check only, no code execution). The exception is
+`example_without_output_path`, which uses the sandbox default and therefore
+requires Docker — see the function docstring for details.
+
+Prerequisites:
+    pip install matplotlib numpy
+    ollama pull granite4.2:3b
+    ollama serve
 
 Usage:
     uv run python docs/examples/sampling/python_plotting_preset.py
@@ -82,6 +93,14 @@ def example_without_output_path():
     Demonstrates using the preset when you don't care about a specific output path.
     The preset validates that matplotlib dependencies are available but doesn't
     enforce a specific savefig() call.
+
+    Note: this is the only function in this file that uses the plotting preset's
+    sandbox default (`use_sandbox=True`). It requires a running Docker daemon and
+    `mellea[sandbox]` installed (`uv sync --extra sandbox`). If Docker is
+    unavailable the sandbox requirement fails silently — the run reports
+    ``Valid: X/Y`` with the unmet requirement listed as "sandbox execution with
+    policy", and the script still prints "✓ completed" because it does not check
+    the sampling result.
     """
     session = mellea.start_session()
 

From b59b7d01da7f74ab65191344eb361d5a32397e87 Mon Sep 17 00:00:00 2001
From: Rafael Vasquez <rafvasq21@gmail.com>
Date: Mon, 26 Oct 2026 13:00:11 -0400
Subject: [PATCH 3/6] docs(examples): fix RST double backticks in plotting
 preset docstring

Assisted-by: IBM Bob
Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
---
 docs/examples/sampling/python_plotting_preset.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/examples/sampling/python_plotting_preset.py b/docs/examples/sampling/python_plotting_preset.py
index 5ddb04e687..ec96570cb2 100644
--- a/docs/examples/sampling/python_plotting_preset.py
+++ b/docs/examples/sampling/python_plotting_preset.py
@@ -98,7 +98,7 @@ def example_without_output_path():
     sandbox default (`use_sandbox=True`). It requires a running Docker daemon and
     `mellea[sandbox]` installed (`uv sync --extra sandbox`). If Docker is
     unavailable the sandbox requirement fails silently — the run reports
-    ``Valid: X/Y`` with the unmet requirement listed as "sandbox execution with
+    `Valid: X/Y` with the unmet requirement listed as "sandbox execution with
     policy", and the script still prints "✓ completed" because it does not check
     the sampling result.
     """

From ef5bf3e7051be0a29bde650323bc606854cc825e Mon Sep 17 00:00:00 2001
From: Rafael Vasquez <rafvasq21@gmail.com>
Date: Wed, 28 Oct 2026 16:32:54 -0400
Subject: [PATCH 4/6] Address review feedback and restore original wording

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
---
 docs/examples/agents/README.md                |  9 ++--
 .../agents/react/react_from_scratch/react.py  |  4 ++
 .../react_from_scratch/react_instruct.py      |  4 ++
 .../agents/react/react_using_mellea.py        |  7 ++-
 docs/examples/sampling/README.md              |  2 +-
 .../sampling/python_code_generation_preset.py | 21 +++++---
 .../sampling/python_plotting_preset.py        | 50 ++++++++++++-------
 7 files changed, 66 insertions(+), 31 deletions(-)

diff --git a/docs/examples/agents/README.md b/docs/examples/agents/README.md
index 80720e22b6..034e685b37 100644
--- a/docs/examples/agents/README.md
+++ b/docs/examples/agents/README.md
@@ -2,10 +2,13 @@
 
 Examples demonstrating agent architectures and the ReACT (Reasoning and Acting) loop in Mellea.
 
+Start with `react_using_mellea.py` for the shortest path; the `react_from_scratch/`
+examples build the same loop by hand to show what the framework does for you.
+
 ## Examples
 
 | File | Description |
 | :--- | :--- |
-| [`react/react_using_mellea.py`](./react/react_using_mellea.py) | ReACT agent using Mellea's stdlib `react()` framework with LangChain tool integration. |
-| [`react/react_from_scratch/react.py`](./react/react_from_scratch/react.py) | ReACT loop built from scratch using custom tool abstractions and Pydantic schemas. |
-| [`react/react_from_scratch/react_instruct.py`](./react/react_from_scratch/react_instruct.py) | ReACT loop implemented using Mellea's instruct-validate-repair paradigm. |
+| [`react/react_using_mellea.py`](./react/react_using_mellea.py) | ReACT agent using Mellea's stdlib `react()` framework with LangChain tool integration. Needs `langchain-community` and `ddgs`. |
+| [`react/react_from_scratch/react.py`](./react/react_from_scratch/react.py) | A complete implementation of the ReACT agent pattern that combines reasoning and action in an iterative loop. |
+| [`react/react_from_scratch/react_instruct.py`](./react/react_from_scratch/react_instruct.py) | An alternative implementation of the ReACT pattern using Mellea's instruct-validate-repair paradigm. |
diff --git a/docs/examples/agents/react/react_from_scratch/react.py b/docs/examples/agents/react/react_from_scratch/react.py
index 40117e0ce1..476fc8686f 100644
--- a/docs/examples/agents/react/react_from_scratch/react.py
+++ b/docs/examples/agents/react/react_from_scratch/react.py
@@ -4,6 +4,10 @@
 Demonstrates implementing the ReACT (Reasoning and Acting) loop from first
 principles, combining tool selection, argument generation, and observation.
 
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
 Usage:
     uv run python docs/examples/agents/react/react_from_scratch/react.py
 """
diff --git a/docs/examples/agents/react/react_from_scratch/react_instruct.py b/docs/examples/agents/react/react_from_scratch/react_instruct.py
index efb68f02d3..bcee399267 100644
--- a/docs/examples/agents/react/react_from_scratch/react_instruct.py
+++ b/docs/examples/agents/react/react_from_scratch/react_instruct.py
@@ -4,6 +4,10 @@
 Demonstrates implementing the ReACT (Reasoning and Acting) loop using Mellea's
 instruct-validate-repair paradigm for robust tool calling and reasoning.
 
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
 Usage:
     uv run python docs/examples/agents/react/react_from_scratch/react_instruct.py
 """
diff --git a/docs/examples/agents/react/react_using_mellea.py b/docs/examples/agents/react/react_using_mellea.py
index b31e952dd6..cbb6b16096 100644
--- a/docs/examples/agents/react/react_using_mellea.py
+++ b/docs/examples/agents/react/react_using_mellea.py
@@ -1,9 +1,14 @@
 # pytest: ollama, e2e, qualitative, slow
-"""ReACT agent using Mellea's built-in react() framework.
+"""React examples using the Mellea library's framework.
 
 Demonstrates the ReACT (Reasoning and Acting) loop with tool integration,
 using Mellea's stdlib react() function and LangChain tool interoperability.
 
+Prerequisites:
+    uv pip install langchain-community ddgs
+    ollama serve
+    ollama pull granite4.2:3b
+
 Usage:
     uv run python docs/examples/agents/react/react_using_mellea.py
 """
diff --git a/docs/examples/sampling/README.md b/docs/examples/sampling/README.md
index fa4ea47802..c29f85db9c 100644
--- a/docs/examples/sampling/README.md
+++ b/docs/examples/sampling/README.md
@@ -10,5 +10,5 @@ these presets wrap.
 
 | File | Description |
 | :--- | :--- |
-| [`python_code_generation_preset.py`](./python_code_generation_preset.py) | Python code generation preset bundling extraction, syntax, and import-check requirements with automatic repair feedback. By default (`use_sandbox=False`) generated code is validated statically — pass `use_sandbox=True` to run it in Docker. |
+| [`python_code_generation_preset.py`](./python_code_generation_preset.py) | Python code generation preset bundling extraction, syntax, and import requirements with automatic repair feedback. By default (`use_sandbox=False`) generated code is parsed but not executed, and imports are checked only when `allowed_imports` is set. Pass `use_sandbox=True` to run it in Docker. |
 | [`python_plotting_preset.py`](./python_plotting_preset.py) | Matplotlib plotting preset bundling headless backend configuration and savefig() output validation. Most examples in this file override the default to `use_sandbox=False` (static validation); `example_without_output_path` uses the sandbox default and requires Docker. |
diff --git a/docs/examples/sampling/python_code_generation_preset.py b/docs/examples/sampling/python_code_generation_preset.py
index b6d5e3b209..1732ccf3f2 100644
--- a/docs/examples/sampling/python_code_generation_preset.py
+++ b/docs/examples/sampling/python_code_generation_preset.py
@@ -1,17 +1,24 @@
 # pytest: e2e, qualitative, ollama
-"""Python code generation sampling preset with automatic repair.
+"""Example demonstrating python_code_generation_sampling() preset.
 
-Demonstrates python_code_generation_sampling(), which bundles code extraction,
-syntax checking, and import validation into a reusable configuration with
-automatic repair feedback.
+Shows how the preset bundles requirements and feedback into a reusable
+configuration for Python code generation tasks, with automatic repair on failure.
 
-By default (`use_sandbox=False`) generated code is validated statically — the
-preset parses and import-checks the code but does not execute it. Pass
+The preset handles:
+1. Code extraction validation
+2. Syntax validation
+3. Execution validation with optional sandbox isolation
+4. Import restrictions (optional allowlist)
+5. Output size limits
+6. Model-friendly repair feedback for each failure type
+
+By default (`use_sandbox=False`) the generated code is parsed but not executed,
+and imports are checked only when `allowed_imports` is set. Pass
 `use_sandbox=True` to run the code in a Docker sandbox instead.
 
 Prerequisites:
-    ollama pull granite4.2:3b
     ollama serve
+    ollama pull granite4.2:3b
 
 Usage:
     uv run python docs/examples/sampling/python_code_generation_preset.py
diff --git a/docs/examples/sampling/python_plotting_preset.py b/docs/examples/sampling/python_plotting_preset.py
index ec96570cb2..bd0524a774 100644
--- a/docs/examples/sampling/python_plotting_preset.py
+++ b/docs/examples/sampling/python_plotting_preset.py
@@ -1,20 +1,33 @@
 # pytest: e2e, qualitative, ollama
-"""Matplotlib plotting sampling preset with headless validation.
-
-Demonstrates python_plotting_sampling(), which bundles Python code generation
-requirements with headless matplotlib backend configuration and savefig() output
-validation.
-
-The plotting preset defaults to `use_sandbox=True`, but most examples in this
-file override that with `use_sandbox=False` so they run as static validation
-(parse and import-check only, no code execution). The exception is
-`example_without_output_path`, which uses the sandbox default and therefore
-requires Docker — see the function docstring for details.
+"""Example demonstrating python_plotting_sampling() preset.
+
+Shows how the plotting preset bundles Python code generation requirements with
+matplotlib-specific constraints for headless rendering and file output validation.
+
+The preset validates:
+1. Python code extraction and syntax
+2. Matplotlib headless backend configuration (matplotlib.use('Agg'))
+3. Plot file output (savefig() call with expected path)
+4. Code execution with sandbox isolation (enabled by default)
+5. Import restrictions and output size limits
+
+Plotting typically requires more repair iterations and stricter sandboxing than
+general code generation, which this preset reflects in its defaults:
+- loop_budget=3 (vs. 2 for code generation)
+- use_sandbox=True (vs. False for code generation)
+- timeout_seconds=10 (vs. 5 for code generation)
+
+Most examples in this file override the default with `use_sandbox=False`, so the
+generated code is parsed but not executed, and imports are checked only when
+`allowed_imports` is set. The exception is `example_without_output_path`, which
+keeps the sandbox default and needs a running Docker daemon. The default
+llm-sandbox image is amd64-only, so that example may not pass on Apple Silicon.
 
 Prerequisites:
-    pip install matplotlib numpy
-    ollama pull granite4.2:3b
+    uv sync --extra sandbox
+    uv pip install matplotlib numpy
     ollama serve
+    ollama pull granite4.2:3b
 
 Usage:
     uv run python docs/examples/sampling/python_plotting_preset.py
@@ -35,7 +48,7 @@ def example_scatter_plot():
     The preset ensures:
     1. matplotlib.use('Agg') is called for headless rendering
     2. plt.savefig(output_path) is called with the specified path
-    3. Code executes without errors in isolated sandbox
+    3. Code parses without errors (static validation, since `use_sandbox=False`)
     """
     session = mellea.start_session()
 
@@ -97,10 +110,9 @@ def example_without_output_path():
     Note: this is the only function in this file that uses the plotting preset's
     sandbox default (`use_sandbox=True`). It requires a running Docker daemon and
     `mellea[sandbox]` installed (`uv sync --extra sandbox`). If Docker is
-    unavailable the sandbox requirement fails silently — the run reports
-    `Valid: X/Y` with the unmet requirement listed as "sandbox execution with
-    policy", and the script still prints "✓ completed" because it does not check
-    the sampling result.
+    unavailable, the run reports `Valid: X/Y` with the unmet requirement listed as
+    "sandbox execution with policy", and the script still prints "✓ completed"
+    because it does not check the sampling result.
     """
     session = mellea.start_session()
 
@@ -163,7 +175,7 @@ def example_with_custom_parameters():
     Demonstrates fine-tuning the preset's parameters:
     - loop_budget: More repair attempts for complex plots
     - timeout_seconds: Longer timeout for rendering-heavy plots
-    - use_sandbox: Keep sandbox enabled for security
+    - use_sandbox: Disabled here so the example runs without Docker
     """
     session = mellea.start_session()
 

From ec853a74b134a2cbdc8faa3187796c168a12e09a Mon Sep 17 00:00:00 2001
From: Rafael Vasquez <rafvasq21@gmail.com>
Date: Thu, 29 Oct 2026 14:26:45 -0400
Subject: [PATCH 5/6] Fix duplicated requirement row

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
---
 docs/docs/examples/index.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/docs/examples/index.md b/docs/docs/examples/index.md
index 44f3ec27dc..0015ed7b7a 100644
--- a/docs/docs/examples/index.md
+++ b/docs/docs/examples/index.md
@@ -62,9 +62,8 @@ to run.
 
 | Category | What it shows |
 | -------- | ------------- |
-| `requirements/` | String and functional validation requirements, custom predicate functions, and validation repair |
+| `requirements/` | String and functional validation requirements, custom predicate functions, and validation repair; validating code generation and plotting with execution tiers and security policies |
 | `intrinsics/` | [Guardian adapter functions](../how-to/safety-guardrails.md): `guardian_check()` for harm, jailbreak, social bias, groundedness; `policy_guardrails()`; `factuality_detection()` / `factuality_correction()` |
-| `requirements/` | Validating code generation and plotting with execution tiers and security policies |
 | `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

From 20fd9479dcc2cde70977c3f914740cbab4b6e409 Mon Sep 17 00:00:00 2001
From: Rafael Vasquez <rafvasq21@gmail.com>
Date: Fri, 30 Oct 2026 15:01:00 -0400
Subject: [PATCH 6/6] docs(examples): fix granite model tag, dedup sampling
 row, clarify sandbox image

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
Assisted-by: IBM Bob
---
 docs/docs/examples/index.md                      |  3 +--
 docs/examples/requirements/README.md             | 10 +++++-----
 docs/examples/sampling/python_plotting_preset.py | 11 +++++++----
 3 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/docs/docs/examples/index.md b/docs/docs/examples/index.md
index 0015ed7b7a..ffa7fdc05c 100644
--- a/docs/docs/examples/index.md
+++ b/docs/docs/examples/index.md
@@ -80,11 +80,10 @@ to run.
 
 | Category | What it shows |
 | -------- | ------------- |
-| `sampling/` | Pre-packaged sampling presets and custom rejection sampling configurations |
+| `sampling/` | Pre-configured sampling presets for Python code generation and data plotting |
 | `aLora/` | Training aLoRA adapters for fast constraint checking; performance optimisation |
 | `intrinsics/` | *(Non-Guardian)* Answer relevance, hallucination detection, citation validation — specialised adapter-backed checks. For Guardian safety functions see [Safety and validation](#safety-and-validation) above |
 | `granite-switch/` | Running adapter functions via OpenAI backend with Granite Switch embedded adapters |
-| `sampling/` | Pre-configured sampling presets for Python code generation and data plotting |
 | `sofai/` | Two-tier sampling: fast-model iteration with escalation to a slow model; cost optimisation |
 
 ### Multimodal
diff --git a/docs/examples/requirements/README.md b/docs/examples/requirements/README.md
index 4697acd0fa..990a149186 100644
--- a/docs/examples/requirements/README.md
+++ b/docs/examples/requirements/README.md
@@ -28,10 +28,10 @@ commands via Python control flow.
 
 Before running this example, ensure you have:
 
-1. Ollama running with the granite4.1:3b model:
+1. Ollama running with the granite4.2:3b model:
    ```bash
    ollama serve  # in one terminal
-   ollama pull granite4.1:3b  # in another terminal (if not already downloaded)
+   ollama pull granite4.2:3b  # in another terminal (if not already downloaded)
    ```
 
 2. Required dependencies installed:
@@ -141,10 +141,10 @@ For production with untrusted code, use `execution_tier="docker"`. See file docs
 
 Before running this example, ensure you have:
 
-1. Ollama running with the granite4.1:3b model:
+1. Ollama running with the granite4.2:3b model:
    ```bash
    ollama serve  # in one terminal
-   ollama pull granite4.1:3b  # in another terminal (if not already downloaded)
+   ollama pull granite4.2:3b  # in another terminal (if not already downloaded)
    ```
 
 2. Required dependencies installed:
@@ -414,6 +414,6 @@ Extract employee distribution across work locations and create a pie chart
 
 ### code_generation_and_execution.py
 
-- Ollama backend with granite4.1:3b model running (`ollama serve`)
+- Ollama backend with granite4.2:3b model running (`ollama serve`)
 - matplotlib and numpy installed (required for executing generated code)
 - Python subprocess execution support (provided by `PythonExecutionReq`)
diff --git a/docs/examples/sampling/python_plotting_preset.py b/docs/examples/sampling/python_plotting_preset.py
index bd0524a774..dbdb6a10fa 100644
--- a/docs/examples/sampling/python_plotting_preset.py
+++ b/docs/examples/sampling/python_plotting_preset.py
@@ -109,10 +109,13 @@ def example_without_output_path():
 
     Note: this is the only function in this file that uses the plotting preset's
     sandbox default (`use_sandbox=True`). It requires a running Docker daemon and
-    `mellea[sandbox]` installed (`uv sync --extra sandbox`). If Docker is
-    unavailable, the run reports `Valid: X/Y` with the unmet requirement listed as
-    "sandbox execution with policy", and the script still prints "✓ completed"
-    because it does not check the sampling result.
+    `mellea[sandbox]` installed (`uv sync --extra sandbox`). The default sandbox
+    image (`ghcr.io/vndee/sandbox-python-311-bullseye`) ships matplotlib, so the
+    example can pass as shipped — provided Docker is available and the image runs
+    on your architecture (the image is amd64-only). If Docker is unavailable, the
+    run reports `Valid: X/Y` with the unmet requirement listed as "sandbox
+    execution with policy", and the script still prints "✓ completed" because it
+    does not check the sampling result.
     """
     session = mellea.start_session()