From 7fbfbfd8af5691b0d7f14dcba25858dbeff269aa Mon Sep 17 00:00:00 2001
From: Rafael Vasquez <rafvasq21@gmail.com>
Date: Thu, 29 Oct 2026 11:56:35 -0400
Subject: [PATCH 1/2] docs(examples): standardize tutorial, notebooks, and root
 examples

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
Assisted-by: IBM Bob
---
 docs/examples/README.md                       | 16 +++-
 docs/examples/as_generic_chat_history.py      |  3 +
 .../groundedness_requirement_example.py       |  6 ++
 docs/examples/hello_world.py                  |  9 ++
 docs/examples/llamacpp_session.py             |  4 +-
 docs/examples/notebooks/README.md             | 74 ++++------------
 docs/examples/provider_fields.py              |  3 +
 docs/examples/structured_output_minimal.py    |  9 +-
 docs/examples/thinking_mode.py                |  9 +-
 docs/examples/tutorial/README.md              | 86 ++++---------------
 .../compositionality_with_generative_stubs.py |  9 ++
 docs/examples/tutorial/context_example.py     |  9 ++
 docs/examples/tutorial/document_mobject.py    | 11 ++-
 docs/examples/tutorial/example.py             |  9 ++
 .../tutorial/instruct_validate_repair.py      |  9 ++
 .../tutorial/model_options_example.py         |  9 ++
 .../examples/tutorial/sentiment_classifier.py |  9 ++
 docs/examples/tutorial/simple_email.py        |  9 ++
 docs/examples/tutorial/table_mobject.py       | 10 +++
 19 files changed, 169 insertions(+), 134 deletions(-)

diff --git a/docs/examples/README.md b/docs/examples/README.md
index f641f92c6a..a54f2c9c58 100644
--- a/docs/examples/README.md
+++ b/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
 
diff --git a/docs/examples/as_generic_chat_history.py b/docs/examples/as_generic_chat_history.py
index 12d731ca8d..25feb1256b 100644
--- a/docs/examples/as_generic_chat_history.py
+++ b/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
diff --git a/docs/examples/groundedness_requirement_example.py b/docs/examples/groundedness_requirement_example.py
index 21a890979f..3747825b22 100644
--- a/docs/examples/groundedness_requirement_example.py
+++ b/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
diff --git a/docs/examples/hello_world.py b/docs/examples/hello_world.py
index 46c27861d9..9eaaa76ae2 100644
--- a/docs/examples/hello_world.py
+++ b/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
 
diff --git a/docs/examples/llamacpp_session.py b/docs/examples/llamacpp_session.py
index 5be3f38084..8c79b49026 100644
--- a/docs/examples/llamacpp_session.py
+++ b/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
diff --git a/docs/examples/notebooks/README.md b/docs/examples/notebooks/README.md
index 7c806fe88d..03f19a17d0 100644
--- a/docs/examples/notebooks/README.md
+++ b/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
\ No newline at end of file
+- [`../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
diff --git a/docs/examples/provider_fields.py b/docs/examples/provider_fields.py
index f96d7c7d1a..bd6d2a1bf8 100644
--- a/docs/examples/provider_fields.py
+++ b/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
diff --git a/docs/examples/structured_output_minimal.py b/docs/examples/structured_output_minimal.py
index 1dab72d280..4c43ba2456 100644
--- a/docs/examples/structured_output_minimal.py
+++ b/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
 
diff --git a/docs/examples/thinking_mode.py b/docs/examples/thinking_mode.py
index 540fc68a26..cf05671133 100644
--- a/docs/examples/thinking_mode.py
+++ b/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
diff --git a/docs/examples/tutorial/README.md b/docs/examples/tutorial/README.md
index e1ce6ffa2d..f01b7a109b 100644
--- a/docs/examples/tutorial/README.md
+++ b/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
\ No newline at end of file
+- [`../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
diff --git a/docs/examples/tutorial/compositionality_with_generative_stubs.py b/docs/examples/tutorial/compositionality_with_generative_stubs.py
index 7d4e3650fd..1f49d39713 100644
--- a/docs/examples/tutorial/compositionality_with_generative_stubs.py
+++ b/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
 
diff --git a/docs/examples/tutorial/context_example.py b/docs/examples/tutorial/context_example.py
index 36a9dea379..ea422030eb 100644
--- a/docs/examples/tutorial/context_example.py
+++ b/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
diff --git a/docs/examples/tutorial/document_mobject.py b/docs/examples/tutorial/document_mobject.py
index f2d892ec70..56e986244f 100644
--- a/docs/examples/tutorial/document_mobject.py
+++ b/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")
diff --git a/docs/examples/tutorial/example.py b/docs/examples/tutorial/example.py
index 53094677a7..cedd60251b 100644
--- a/docs/examples/tutorial/example.py
+++ b/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
 
diff --git a/docs/examples/tutorial/instruct_validate_repair.py b/docs/examples/tutorial/instruct_validate_repair.py
index 73581a2c40..5a1fc1613c 100644
--- a/docs/examples/tutorial/instruct_validate_repair.py
+++ b/docs/examples/tutorial/instruct_validate_repair.py
@@ -1,4 +1,13 @@
 # pytest: ollama, e2e
+"""Walkthrough of the instruct-validate-repair paradigm.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/instruct_validate_repair.py
+"""
 
 from mellea.core import Requirement
 from mellea.stdlib.requirements import check, req, simple_validate
diff --git a/docs/examples/tutorial/model_options_example.py b/docs/examples/tutorial/model_options_example.py
index 5cafbc54f3..d43f334387 100644
--- a/docs/examples/tutorial/model_options_example.py
+++ b/docs/examples/tutorial/model_options_example.py
@@ -1,4 +1,13 @@
 # pytest: ollama, e2e
+"""Configuring model options and parameters.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/model_options_example.py
+"""
 
 import mellea
 from mellea.backends import ModelOption, model_ids
diff --git a/docs/examples/tutorial/sentiment_classifier.py b/docs/examples/tutorial/sentiment_classifier.py
index 6d1d3367ea..80bdbada18 100644
--- a/docs/examples/tutorial/sentiment_classifier.py
+++ b/docs/examples/tutorial/sentiment_classifier.py
@@ -1,4 +1,13 @@
 # pytest: ollama, e2e
+"""Building a sentiment classification system.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/sentiment_classifier.py
+"""
 
 from typing import Literal
 
diff --git a/docs/examples/tutorial/simple_email.py b/docs/examples/tutorial/simple_email.py
index f7d03f041e..71297c72da 100644
--- a/docs/examples/tutorial/simple_email.py
+++ b/docs/examples/tutorial/simple_email.py
@@ -1,4 +1,13 @@
 # pytest: ollama, e2e
+"""Email generation example - the classic "Hello World" of Mellea.
+
+Prerequisites:
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/simple_email.py
+"""
 
 import mellea
 
diff --git a/docs/examples/tutorial/table_mobject.py b/docs/examples/tutorial/table_mobject.py
index 1b79d69b77..0efdc45abc 100644
--- a/docs/examples/tutorial/table_mobject.py
+++ b/docs/examples/tutorial/table_mobject.py
@@ -1,4 +1,14 @@
 # pytest: ollama, e2e
+"""Working with table data structures.
+
+Prerequisites:
+    uv pip install pandas
+    ollama serve
+    ollama pull granite4.2:3b
+
+Usage:
+    uv run python docs/examples/tutorial/table_mobject.py
+"""
 
 from io import StringIO
 

From 156e064c5033890eef8d7cf8c9eaf940c336dea4 Mon Sep 17 00:00:00 2001
From: Rafael Vasquez <rafvasq21@gmail.com>
Date: Fri, 30 Oct 2026 14:47:54 -0400
Subject: [PATCH 2/2] docs(examples): address review feedback on tutorial and
 root README

Remove stale Granite 4 Micro download comment from simple_email.py and point the sentiment_classifier.py link at the script.

Assisted-by: IBM Bob
Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
---
 docs/examples/README.md                | 2 +-
 docs/examples/tutorial/simple_email.py | 1 -
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/examples/README.md b/docs/examples/README.md
index a54f2c9c58..c0ec97e8aa 100644
--- a/docs/examples/README.md
+++ b/docs/examples/README.md
@@ -242,7 +242,7 @@ Utility functions used across examples.
 ### Text Generation
 - [instruct_validate_repair/](instruct_validate_repair/) - Email generation
 - [generative_stubs/](generative_stubs/) - Summarization
-- [tutorial/sentiment_classifier.py](tutorial/) - Classification
+- [tutorial/sentiment_classifier.py](tutorial/sentiment_classifier.py) - Classification
 
 ### Audio & Multimodal
 - [audio_text_models/](audio_text_models/) - Audio understanding with `AudioBlock`
diff --git a/docs/examples/tutorial/simple_email.py b/docs/examples/tutorial/simple_email.py
index 71297c72da..4ed38d9059 100644
--- a/docs/examples/tutorial/simple_email.py
+++ b/docs/examples/tutorial/simple_email.py
@@ -11,7 +11,6 @@
 
 import mellea
 
-# INFO: this line will download IBM's Granite 4 Micro 3B model.
 m = mellea.start_session()
 
 print("Basic email:")