docs(examples): standardize sampling and agents READMEs and docstrings

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

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
+| 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. |

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

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

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
 

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.

docs/examples/sampling/README.md

@@ -0,0 +1,14 @@
+# Sampling Examples
+
+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 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. |

docs/examples/sampling/python_code_generation_preset.py

@@ -1,16 +1,20 @@
 # 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 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
 """
 
 import mellea

docs/examples/sampling/python_plotting_preset.py

@@ -1,21 +1,23 @@
 # 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 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
 """
 
 import tempfile
@@ -91,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()