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

docs/docs/examples/index.md

@@ -62,7 +62,7 @@ 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()` |
 | `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).)* |
 
@@ -80,7 +80,7 @@ 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 |

docs/examples/agents/README.md

@@ -1,39 +1,14 @@
 # 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
+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.
 
-### [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
+## Examples
 
-**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. 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. |

docs/examples/agents/react/react_from_scratch/react.py

@@ -1,4 +1,16 @@
 # 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.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+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,16 @@
 # 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.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+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,17 @@
 # pytest: ollama, e2e, qualitative, slow
+"""React examples using the Mellea library's 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
+"""
 
 import asyncio
 

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

docs/examples/sampling/python_code_generation_preset.py

@@ -11,6 +11,17 @@
 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 serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/sampling/python_code_generation_preset.py
 """
 
 import mellea

docs/examples/sampling/python_plotting_preset.py

@@ -16,6 +16,21 @@
 - 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:
+    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
 """
 
 import tempfile
@@ -33,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()
 
@@ -91,6 +106,16 @@ 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`). 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()
 
@@ -153,7 +178,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()