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

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

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