docs(examples): standardize tutorial, notebooks, and root examples

docs/examples/README.md

@@ -5,7 +5,7 @@ This directory contains comprehensive examples demonstrating Mellea's features a
 ## 🚀 Getting Started
 
 **New to Mellea?** Start here:
-1. [tutorial/simple_email.py](tutorial/) - Your first Mellea program
+1. [tutorial/simple_email.py](tutorial/simple_email.py) - Your first Mellea program
 2. [instruct_validate_repair/](instruct_validate_repair/) - Core paradigm
 3. [generative_stubs/](generative_stubs/) - Type-safe LLM functions
 4. [notebooks/](notebooks/) - Interactive tutorials
@@ -61,6 +61,12 @@ Two-tier sampling with fast and slow models.
 - Escalation to slow models
 - Constraint satisfaction problems
 
+**[sampling/](sampling/)**
+Pre-packaged sampling presets for constrained generation tasks.
+- Python code generation preset
+- Matplotlib plotting preset
+- Automated repair with feedback loops
+
 ### Data & Documents
 
 **[information_extraction/](information_extraction/)**
@@ -97,6 +103,12 @@ Implementing agent patterns (ReACT).
 - Tool selection and execution
 - Multi-turn agent workflows
 
+**[primitives/](primitives/)**
+Low-level functional primitives for manual tool execution and execution hooks.
+- Tool invocation without an agent loop
+- Tool call execution hooks
+- Raw tool response handling
+
 **[tools/](tools/)**
 Tool calling and code execution.
 - Code interpreter integration
@@ -243,6 +255,7 @@ Utility functions used across examples.
 
 ### Agent Systems
 - [agents/](agents/) - ReACT agents
+- [primitives/](primitives/) - Low-level tool primitives
 - [tools/](tools/) - Tool-using agents
 - [mini_researcher/](mini_researcher/) - Research assistant
 
@@ -253,6 +266,7 @@ Utility functions used across examples.
 
 ### Performance Optimization
 - [aLora/](aLora/) - Fast validation
+- [sampling/](sampling/) - Sampling presets
 - [sofai/](sofai/) - Cost optimization
 - [intrinsics/](intrinsics/) - Specialized tasks
 

docs/examples/as_generic_chat_history.py

@@ -5,6 +5,9 @@
 Messages, gracefully handling unknown component types by converting them to
 strings. This is useful for working with mixed-type contexts or when you need
 a more flexible interface than as_chat_history().
+
+Usage:
+    uv run python docs/examples/as_generic_chat_history.py
 """
 
 from mellea.core import CBlock, ModelOutputThunk

docs/examples/groundedness_requirement_example.py

@@ -13,6 +13,12 @@
 
 Note: This example requires Hugging Face backend with GPU (8GB+ VRAM recommended)
 and access to the ibm-granite/granite-4.0-micro model.
+
+Prerequisites:
+    uv sync --extra hf
+
+Usage:
+    uv run python docs/examples/groundedness_requirement_example.py
 """
 
 import asyncio

docs/examples/hello_world.py

@@ -1,4 +1,13 @@
 # pytest: ollama, e2e
+"""Minimal single-file starting point demonstrating email generation.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/hello_world.py
+"""
 
 import mellea
 

docs/examples/llamacpp_session.py

@@ -1,5 +1,4 @@
 # pytest: llamacpp, e2e
-
 """Example: run a Mellea session against a local llama.cpp server.
 
 llama-server speaks the OpenAI chat-completions API, so Mellea reaches it through
@@ -13,6 +12,9 @@
     That serves Granite 4.2 3b on http://127.0.0.1:8080 under the alias
     `ibm-granite/granite-4.2-3b`, which is the name `IBM_GRANITE_4_2_3B` resolves
     to for the openai backend. Set LLAMACPP_BASE_URL to point somewhere else.
+
+Usage:
+    uv run python docs/examples/llamacpp_session.py
 """
 
 import os

docs/examples/notebooks/README.md

@@ -4,41 +4,20 @@ This directory contains interactive Jupyter notebooks demonstrating various Mell
 
 ## Notebooks
 
-### [example.ipynb](./example.ipynb)
-General introduction to Mellea with basic examples.
-
-### [compositionality_with_generative_stubs.ipynb](./compositionality_with_generative_stubs.ipynb)
-Interactive tutorial on composing generative functions.
-
-### [context_example.ipynb](./context_example.ipynb)
-Working with contexts and context management.
-
-### [document_mobject.ipynb](./document_mobject.ipynb)
-Using document MObjects for text processing.
-
-### [georgia_tech.ipynb](./georgia_tech.ipynb)
-Domain-specific example (possibly academic/research use case).
-
-### [instruct_validate_repair.ipynb](./instruct_validate_repair.ipynb)
-Interactive walkthrough of the instruct-validate-repair paradigm.
-
-### [m_serve_example.ipynb](./m_serve_example.ipynb)
-Deploying Mellea programs as services.
-
-### [mcp_example.ipynb](./mcp_example.ipynb)
-Model Context Protocol integration examples.
-
-### [model_options_example.ipynb](./model_options_example.ipynb)
-Configuring model options and parameters.
-
-### [sentiment_classifier.ipynb](./sentiment_classifier.ipynb)
-Building a sentiment classification system.
-
-### [simple_email.ipynb](./simple_email.ipynb)
-Email generation with requirements.
-
-### [table_mobject.ipynb](./table_mobject.ipynb)
-Working with table data structures.
+| File | Description |
+| :--- | :--- |
+| [`example.ipynb`](./example.ipynb) | General introduction to Mellea with basic examples. |
+| [`simple_email.ipynb`](./simple_email.ipynb) | Email generation with requirements. |
+| [`instruct_validate_repair.ipynb`](./instruct_validate_repair.ipynb) | Interactive walkthrough of the instruct-validate-repair paradigm. |
+| [`compositionality_with_generative_stubs.ipynb`](./compositionality_with_generative_stubs.ipynb) | Interactive tutorial on composing generative functions. |
+| [`context_example.ipynb`](./context_example.ipynb) | Working with contexts and context management. |
+| [`document_mobject.ipynb`](./document_mobject.ipynb) | Using document MObjects for text processing. |
+| [`table_mobject.ipynb`](./table_mobject.ipynb) | Working with table data structures. |
+| [`model_options_example.ipynb`](./model_options_example.ipynb) | Configuring model options and parameters. |
+| [`sentiment_classifier.ipynb`](./sentiment_classifier.ipynb) | Building a sentiment classification system. |
+| [`georgia_tech.ipynb`](./georgia_tech.ipynb) | Domain-specific example (possibly academic/research use case). |
+| [`m_serve_example.ipynb`](./m_serve_example.ipynb) | Deploying Mellea programs as services. |
+| [`mcp_example.ipynb`](./mcp_example.ipynb) | Model Context Protocol integration examples. |
 
 ## Running the Notebooks
 
@@ -108,26 +87,7 @@ Three things to know before editing or adding one:
 
 Full detail: [test/README.md → Notebooks](../../../test/README.md#notebooks).
 
-## Benefits of Notebooks
-
-- **Interactive Learning**: Experiment with code in real-time
-- **Visualization**: See results immediately
-- **Documentation**: Combine code, output, and explanations
-- **Experimentation**: Try different parameters and approaches
-- **Sharing**: Easy to share complete examples with outputs
-
-## Corresponding Python Files
-
-Most notebooks have corresponding Python files in the `tutorial/` directory for non-interactive use.
-
-## Tips
-
-- Run cells in order for proper context building
-- Restart kernel if you encounter state issues
-- Use `Shift+Enter` to run cells
-- Check cell outputs for errors before proceeding
-
-## Related Documentation
+## See Also
 
-- See `tutorial/` for Python script versions
-- See individual example directories for more details on each topic
+- [`../tutorial/`](../tutorial/README.md) — Python script versions of the tutorial notebooks
+- [Tutorial: Your First Generative Program](../../docs/tutorials/01-your-first-generative-program.md) — Step-by-step written guide

docs/examples/provider_fields.py

@@ -8,6 +8,9 @@
 reaches raises a `ValueError` (add `"*"` to opt out of that check).
 
 See issue #1565 for the design.
+
+Usage:
+    uv run python docs/examples/provider_fields.py
 """
 
 import pytest

docs/examples/structured_output_minimal.py

@@ -1,6 +1,13 @@
 # pytest: ollama, e2e
+"""Minimal example: structured output via act(format=) with a Pydantic model.
 
-"""Minimal example: structured output via act(format=) with a Pydantic model."""
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/structured_output_minimal.py
+"""
 
 from pydantic import BaseModel
 

docs/examples/thinking_mode.py

@@ -1,9 +1,12 @@
 # pytest: ollama, e2e
-
 """Demonstrates ModelOption.THINKING against a local Ollama Granite model.
 
-Requires `ollama serve` running with `granite4.2:3b` pulled
-(`ollama pull granite4.2:3b`).
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/thinking_mode.py
 """
 
 import mellea

docs/examples/tutorial/README.md

@@ -2,52 +2,19 @@
 
 This directory contains Python script versions of the tutorial notebooks, suitable for running directly or studying the code.
 
-## Files
-
-### [example.py](./example.py)
-General introduction to Mellea with basic examples.
-
-### [simple_email.py](./simple_email.py)
-Email generation example - the classic "Hello World" of Mellea.
-
-### [instruct_validate_repair.py](./instruct_validate_repair.py)
-Walkthrough of the instruct-validate-repair paradigm.
-
-### [compositionality_with_generative_stubs.py](./compositionality_with_generative_stubs.py)
-Tutorial on composing generative functions.
-
-### [context_example.py](./context_example.py)
-Working with contexts and context management.
-
-### [document_mobject.py](./document_mobject.py)
-Using document MObjects for text processing.
-
-### [table_mobject.py](./table_mobject.py)
-Working with table data structures.
-
-### [model_options_example.py](./model_options_example.py)
-Configuring model options and parameters.
-
-### [sentiment_classifier.py](./sentiment_classifier.py)
-Building a sentiment classification system.
-
-## Relationship to Notebooks
-
-Each file in this directory corresponds to a Jupyter notebook in `notebooks/`:
-- `example.py` ↔ `example.ipynb`
-- `simple_email.py` ↔ `simple_email.ipynb`
-- `instruct_validate_repair.py` ↔ `instruct_validate_repair.ipynb`
-- etc.
-
-## Running the Examples
-
-```bash
-# Run any example directly
-python docs/examples/tutorial/simple_email.py
-
-# Or with uv
-uv run docs/examples/tutorial/simple_email.py
-```
+## Examples
+
+| File | Description |
+| :--- | :--- |
+| [`example.py`](./example.py) | General introduction to Mellea with basic examples. |
+| [`simple_email.py`](./simple_email.py) | Email generation example - the classic "Hello World" of Mellea. |
+| [`instruct_validate_repair.py`](./instruct_validate_repair.py) | Walkthrough of the instruct-validate-repair paradigm. |
+| [`compositionality_with_generative_stubs.py`](./compositionality_with_generative_stubs.py) | Tutorial on composing generative functions. |
+| [`context_example.py`](./context_example.py) | Working with contexts and context management. |
+| [`document_mobject.py`](./document_mobject.py) | Using document MObjects for text processing. |
+| [`table_mobject.py`](./table_mobject.py) | Working with table data structures. |
+| [`model_options_example.py`](./model_options_example.py) | Configuring model options and parameters. |
+| [`sentiment_classifier.py`](./sentiment_classifier.py) | Building a sentiment classification system. |
 
 ## Learning Path
 
@@ -62,26 +29,6 @@ Recommended order for learning Mellea:
 7. **[document_mobject.py](./document_mobject.py)** - Working with documents
 8. **[table_mobject.py](./table_mobject.py)** - Working with structured data
 
-## Key Concepts Covered
-
-- **Sessions**: Creating and managing Mellea sessions
-- **Instructions**: Generating text with natural language instructions
-- **Requirements**: Constraining outputs with validation
-- **Validation**: Checking outputs against requirements
-- **Repair**: Automatically fixing invalid outputs
-- **Generative Stubs**: Type-safe LLM functions
-- **Contexts**: Managing conversation and generation history
-- **Model Options**: Configuring model behavior
-- **MObjects**: Working with structured data types
-
-## Differences from Notebooks
-
-- **No Interactive Output**: Scripts don't show intermediate results
-- **Linear Execution**: Runs from top to bottom
-- **Easier to Version Control**: Plain Python files
-- **Better for CI/CD**: Can be run in automated pipelines
-- **Easier to Import**: Can import functions from these files
-
 ## Converting to Notebooks
 
 To convert a script to a notebook:
@@ -93,8 +40,7 @@ uv pip install jupytext
 jupytext --to notebook docs/examples/tutorial/simple_email.py
 ```
 
-## Related Documentation
+## See Also
 
-- See `notebooks/` for interactive Jupyter versions
-- See other example directories for specialized topics
-- See main README.md for getting started guide
+- [`../notebooks/`](../notebooks/README.md) — Interactive Jupyter notebook versions of these tutorials
+- [Tutorial: Your First Generative Program](../../docs/tutorials/01-your-first-generative-program.md) — Step-by-step written guide

docs/examples/tutorial/compositionality_with_generative_stubs.py

@@ -1,4 +1,13 @@
 # pytest: ollama, e2e
+"""Tutorial on composing generative functions.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/compositionality_with_generative_stubs.py
+"""
 
 from mellea import generative
 

docs/examples/tutorial/context_example.py

@@ -1,4 +1,13 @@
 # pytest: ollama, e2e
+"""Working with contexts and context management.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/context_example.py
+"""
 
 from mellea import start_session
 from mellea.stdlib.context import ChatContext

docs/examples/tutorial/document_mobject.py

@@ -1,7 +1,16 @@
 # pytest: ollama, qualitative, e2e
+"""Using document MObjects for text processing.
+
+Prerequisites:
+    uv sync --extra docling
+    ollama serve
+    ollama pull llama3.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/document_mobject.py
+"""
 
 from mellea.backends import model_ids
-from mellea.backends.model_ids import IBM_GRANITE_4_HYBRID_MICRO
 from mellea.stdlib.components.docs.richdocument import RichDocument
 
 rd = RichDocument.from_document_file("https://arxiv.org/pdf/1906.04043")

docs/examples/tutorial/example.py

@@ -1,4 +1,13 @@
 # pytest: ollama, e2e
+"""General introduction to Mellea with basic examples.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/example.py
+"""
 
 import mellea