diff --git a/docs/examples/README.md b/docs/examples/README.md
index 51e4a00f..aafa3708 100644
--- a/docs/examples/README.md
+++ b/docs/examples/README.md
@@ -1 +1,242 @@
-This is a place for us to store interesting examples. These should be incorporated into documentation and tutorials prior to release.
\ No newline at end of file
+# Mellea Examples
+
+This directory contains comprehensive examples demonstrating Mellea's features and capabilities. Examples are organized by topic and complexity level.
+
+## 🚀 Getting Started
+
+**New to Mellea?** Start here:
+1. [tutorial/simple_email.py](tutorial/) - Your first Mellea program
+2. [instruct_validate_repair/](instruct_validate_repair/) - Core paradigm
+3. [generative_slots/](generative_slots/) - Type-safe LLM functions
+4. [notebooks/](notebooks/) - Interactive tutorials
+
+## 📚 Example Categories
+
+### Core Concepts
+
+**[instruct_validate_repair/](instruct_validate_repair/)**
+Learn Mellea's core instruct-validate-repair paradigm for reliable LLM outputs.
+- Basic instruction without requirements
+- Adding validation constraints
+- Automatic repair on validation failure
+- Custom validation functions
+
+**[generative_slots/](generative_slots/)**
+Type-safe, composable LLM functions using the `@generative` decorator.
+- Sentiment classification
+- Text summarization
+- Function composition
+- Type-constrained outputs
+
+**[context/](context/)**
+Understanding and working with Mellea's context system.
+- Context inspection
+- Sampling with contexts
+- Context trees and navigation
+
+**[sessions/](sessions/)**
+Creating and customizing Mellea sessions.
+- Session configuration
+- Custom session types
+- Backend selection
+
+### Advanced Features
+
+**[aLora/](aLora/)**
+Adaptive Low-Rank Adaptation for fast constraint checking.
+- Training custom aLoRA adapters
+- Performance optimization
+- Constraint validation speedup
+
+**[intrinsics/](intrinsics/)**
+Specialized model capabilities through adapters.
+- Answer relevance checking
+- Hallucination detection
+- Citation validation
+- Context relevance assessment
+
+**[sofai/](sofai/)**
+Two-tier sampling with fast and slow models.
+- Cost optimization
+- Iterative refinement with fast models
+- Escalation to slow models
+- Constraint satisfaction problems
+
+### Data & Documents
+
+**[information_extraction/](information_extraction/)**
+Extracting structured information from unstructured text.
+- Named entity recognition
+- Type-safe extraction
+- Structured output generation
+
+**[mobject/](mobject/)**
+Working with structured data types (tables, documents).
+- Table queries and transformations
+- Document processing
+- Structured data operations
+
+**[mify/](mify/)**
+Making custom Python objects work with LLMs.
+- Object integration with `@mify`
+- Custom string representations
+- Template integration
+- Tool generation from methods
+
+**[rag/](rag/)**
+Retrieval-Augmented Generation pipelines.
+- Vector search with FAISS
+- Relevance filtering
+- Grounded answer generation
+- Multi-stage RAG pipelines
+
+### Agents & Tools
+
+**[agents/](agents/)**
+Implementing agent patterns (ReACT).
+- Reasoning and acting loops
+- Tool selection and execution
+- Multi-turn agent workflows
+
+**[tools/](tools/)**
+Tool calling and code execution.
+- Code interpreter integration
+- Custom tool definition
+- Tool argument validation
+- Safe code execution
+
+### Safety & Validation
+
+**[safety/](safety/)**
+Content safety with Granite Guardian models.
+- Harm detection
+- Jailbreak prevention
+- Bias checking
+- Groundedness validation
+- Function call hallucination detection
+
+### Integration & Deployment
+
+**[m_serve/](m_serve/)**
+Deploying Mellea programs as REST APIs.
+- API service creation
+- Production deployment patterns
+- Client integration
+
+**[library_interop/](library_interop/)**
+Integrating with other LLM libraries.
+- LangChain message conversion
+- OpenAI format compatibility
+- Cross-library workflows
+
+**[mcp/](mcp/)**
+Model Context Protocol integration.
+- MCP tool creation
+- Claude Desktop integration
+- Langflow integration
+
+### Multimodal
+
+**[image_text_models/](image_text_models/)**
+Working with vision-language models.
+- Image understanding
+- Multimodal prompting
+- Vision model backends
+
+### Complete Applications
+
+**[mini_researcher/](mini_researcher/)**
+Full-featured research assistant with RAG and validation.
+- Multi-model architecture
+- Document retrieval
+- Safety checks
+- Custom validation pipeline
+
+### Interactive Learning
+
+**[notebooks/](notebooks/)**
+Jupyter notebooks for interactive exploration.
+- Step-by-step tutorials
+- Immediate feedback
+- Visualization of results
+
+**[tutorial/](tutorial/)**
+Python script versions of tutorials.
+- Non-interactive examples
+- Easy to run and modify
+- Version control friendly
+
+### Experimental
+
+**[melp/](melp/)**
+⚠️ Experimental lazy evaluation system.
+- Lazy computation
+- Thunks and deferred execution
+- Advanced control flow
+
+### Utilities
+
+**[helper/](helper/)**
+Utility functions used across examples.
+- Text formatting helpers
+- Common utilities
+
+## 🎯 Examples by Use Case
+
+### Text Generation
+- [instruct_validate_repair/](instruct_validate_repair/) - Email generation
+- [generative_slots/](generative_slots/) - Summarization
+- [tutorial/sentiment_classifier.py](tutorial/) - Classification
+
+### Data Processing
+- [information_extraction/](information_extraction/) - Entity extraction
+- [mobject/](mobject/) - Table operations
+- [rag/](rag/) - Document retrieval
+
+### Agent Systems
+- [agents/](agents/) - ReACT agents
+- [tools/](tools/) - Tool-using agents
+- [mini_researcher/](mini_researcher/) - Research assistant
+
+### Production Deployment
+- [m_serve/](m_serve/) - API services
+- [safety/](safety/) - Content moderation
+- [library_interop/](library_interop/) - Integration
+
+### Performance Optimization
+- [aLora/](aLora/) - Fast validation
+- [sofai/](sofai/) - Cost optimization
+- [intrinsics/](intrinsics/) - Specialized tasks
+
+## 📖 Documentation
+
+- **Main README**: [../../README.md](../../README.md)
+- **Agent Guidelines**: [../../AGENTS.md](../../AGENTS.md)
+- **Dev Docs**: [../dev/](../dev/)
+
+## 🏃 Running Examples
+
+```bash
+# Run any Python example
+python docs/examples/tutorial/simple_email.py
+
+# Or with uv
+uv run docs/examples/tutorial/simple_email.py
+
+# Run notebooks
+jupyter notebook docs/examples/notebooks/
+
+# Run tests
+uv run pytest test/
+```
+
+## 💡 Tips
+
+- Start with [tutorial/](tutorial/) for basics
+- Check [notebooks/](notebooks/) for interactive learning
+- See [mini_researcher/](mini_researcher/) for complete application patterns
+- Refer to individual README.md files in each directory for details
+
+## 🤝 Contributing
+
+Found a bug or have an improvement? See [../../AGENTS.md](../../AGENTS.md) for contribution guidelines.
\ No newline at end of file
diff --git a/docs/examples/aLora/README.md b/docs/examples/aLora/README.md
new file mode 100644
index 00000000..7ecb550b
--- /dev/null
+++ b/docs/examples/aLora/README.md
@@ -0,0 +1,48 @@
+# aLoRA Examples
+
+This directory contains examples demonstrating Adaptive Low-Rank Adaptation (aLoRA) for efficient constraint checking and requirement validation.
+
+## Files
+
+### 101_example.py
+A comprehensive example showing how to use aLoRA adapters for fast constraint checking with Granite models.
+
+**Key Features:**
+- Loading and using custom aLoRA adapters for constraint checking
+- Comparing validation speed with and without aLoRA
+- Using `ALoraRequirement` for efficient requirement validation
+- Demonstrates significant speedup when using aLoRA adapters
+
+**Usage:**
+```bash
+python docs/examples/aLora/101_example.py
+```
+
+### Supporting Files
+
+- **prompt_config.json**: Configuration for training aLoRA adapters
+- **stembolt_failure_dataset.jsonl**: Training dataset for the failure mode constraint
+- **checkpoints/alora_adapter/**: Pre-trained aLoRA adapter checkpoint
+
+## Concepts Demonstrated
+
+- **aLoRA Adapters**: Using specialized adapters for constraint checking
+- **Constraint Validation**: Fast requirement checking with aLoRA
+- **Performance Optimization**: Comparing validation times with/without aLoRA
+- **Custom Requirements**: Creating domain-specific validation requirements
+- **Backend Integration**: Adding aLoRA adapters to HuggingFace backends
+
+## Training Your Own aLoRA
+
+To train custom aLoRA adapters for your constraints:
+
+```bash
+m alora train --config docs/examples/aLora/prompt_config.json
+```
+
+See `cli/alora/` for more details on training aLoRA adapters.
+
+## Related Documentation
+
+- See `docs/dev/requirement_aLoRA_rerouting.md` for aLoRA architecture details
+- See `mellea/backends/adapters/` for adapter implementation
\ No newline at end of file
diff --git a/docs/examples/agents/README.md b/docs/examples/agents/README.md
new file mode 100644
index 00000000..86954099
--- /dev/null
+++ b/docs/examples/agents/README.md
@@ -0,0 +1,40 @@
+# Agent Examples
+
+This directory contains examples of implementing agent patterns with Mellea, specifically the ReACT (Reasoning and Acting) pattern.
+
+## Files
+
+### 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.py
+```
+
+### 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 `docs/dev/tool_calling.md` for more on tool integration
+- See `mellea/stdlib/requirements/tool_reqs.py` for tool requirements
\ No newline at end of file
diff --git a/docs/examples/context/README.md b/docs/examples/context/README.md
new file mode 100644
index 00000000..dde027bc
--- /dev/null
+++ b/docs/examples/context/README.md
@@ -0,0 +1,55 @@
+# Context Examples
+
+This directory contains examples demonstrating how to work with Mellea's context system, particularly when using sampling strategies and validation.
+
+## Files
+
+### contexts_with_sampling.py
+Shows how to retrieve and inspect context information when using sampling strategies and validation.
+
+**Key Features:**
+- Using `RejectionSamplingStrategy` with requirements
+- Accessing `SamplingResult` objects to inspect generation attempts
+- Retrieving context for different generation attempts
+- Examining validation contexts for each requirement
+- Understanding the context tree structure
+
+**Usage:**
+```bash
+python docs/examples/context/contexts_with_sampling.py
+```
+
+## Concepts Demonstrated
+
+- **Sampling Results**: Working with `SamplingResult` objects
+- **Context Inspection**: Accessing generation and validation contexts
+- **Multiple Attempts**: Examining different generation attempts
+- **Context Trees**: Understanding how contexts link together
+- **Validation Context**: Inspecting how requirements were evaluated
+
+## Key APIs
+
+```python
+# Get sampling result with full context information
+res = m.instruct(
+    "Write a sentence.",
+    requirements=[...],
+    strategy=RejectionSamplingStrategy(loop_budget=3),
+    return_sampling_results=True
+)
+
+# Access different generation attempts
+res.sample_generations[index]
+res.sample_contexts[index]
+res.sample_validations[index]
+
+# Navigate context tree
+gen_ctx.previous_node.node_data
+val_ctx.node_data
+```
+
+## Related Documentation
+
+- See `mellea/stdlib/context.py` for context implementation
+- See `mellea/stdlib/sampling/` for sampling strategies
+- See `docs/dev/spans.md` for context architecture details
\ No newline at end of file
diff --git a/docs/examples/generative_slots/README.md b/docs/examples/generative_slots/README.md
new file mode 100644
index 00000000..1e00d493
--- /dev/null
+++ b/docs/examples/generative_slots/README.md
@@ -0,0 +1,61 @@
+# Generative Slots Examples
+
+This directory contains examples demonstrating the `@generative` decorator for creating type-safe, composable LLM functions.
+
+## Files
+
+### generative_slots.py
+Basic introduction to generative slots with sentiment classification and text summarization.
+
+**Key Features:**
+- Using `@generative` decorator for type-safe LLM functions
+- Literal types for constrained outputs
+- Docstrings as prompts for the LLM
+- Simple function composition
+
+### generate_with_context.py
+Shows how to use generative slots with custom context and grounding information.
+
+### generative_gsm8k.py
+Demonstrates using generative slots for mathematical reasoning tasks (GSM8K dataset).
+
+### generative_slots_with_requirements.py
+Combines generative slots with requirements for validated outputs.
+
+### investment_advice.py
+A more complex example using generative slots for financial analysis.
+
+### inter_module_composition/
+Subdirectory with examples of composing multiple generative functions together.
+
+## Concepts Demonstrated
+
+- **Type Safety**: Using Python type hints for structured outputs
+- **Docstring Prompts**: Leveraging docstrings as instructions to the LLM
+- **Composition**: Building complex workflows from simple generative functions
+- **Requirements**: Adding validation to generative functions
+- **Context Management**: Using grounding context with generative slots
+
+## Basic Usage
+
+```python
+from mellea import generative, start_session
+from typing import Literal
+
+@generative
+def classify_sentiment(text: str) -> Literal["positive", "negative"]:
+    """Classify the sentiment of the given text."""
+
+@generative
+def generate_summary(text: str) -> str:
+    """Generate a concise summary under 20 words."""
+
+with start_session() as m:
+    sentiment = classify_sentiment(m, text="I love this!")
+    summary = generate_summary(m, text="Long document...")
+```
+
+## Related Documentation
+
+- See `mellea/stdlib/components/genslot.py` for implementation
+- See `docs/dev/mellea_library.md` for design philosophy
\ No newline at end of file
diff --git a/docs/examples/generative_slots/inter_module_composition/README.md b/docs/examples/generative_slots/inter_module_composition/README.md
new file mode 100644
index 00000000..7ce7639a
--- /dev/null
+++ b/docs/examples/generative_slots/inter_module_composition/README.md
@@ -0,0 +1,47 @@
+# Inter-Module Composition Examples
+
+This subdirectory demonstrates how to compose multiple generative functions together to build complex workflows.
+
+## Files
+
+### summarizers.py
+Defines reusable summarization functions that can be composed with other modules.
+
+### decision_aides.py
+Implements decision-making functions that can work with summarized content.
+
+### summarize_and_decide.py
+Shows how to compose summarizers and decision aides into a complete workflow.
+
+## Concepts Demonstrated
+
+- **Module Composition**: Building complex workflows from simple functions
+- **Reusability**: Creating reusable generative components
+- **Pipeline Design**: Chaining multiple LLM operations
+- **Separation of Concerns**: Keeping different functionalities in separate modules
+
+## Pattern
+
+```python
+# Module 1: summarizers.py
+@generative
+def summarize_text(text: str) -> str:
+    """Summarize the given text."""
+
+# Module 2: decision_aides.py
+@generative
+def make_decision(summary: str) -> str:
+    """Make a decision based on the summary."""
+
+# Composition: summarize_and_decide.py
+with start_session() as m:
+    summary = summarize_text(m, text=long_document)
+    decision = make_decision(m, summary=summary)
+```
+
+## Benefits
+
+- **Modularity**: Each function has a single responsibility
+- **Testability**: Individual components can be tested separately
+- **Maintainability**: Changes to one module don't affect others
+- **Composability**: Mix and match functions for different workflows
\ No newline at end of file
diff --git a/docs/examples/helper/README.md b/docs/examples/helper/README.md
new file mode 100644
index 00000000..b93428b3
--- /dev/null
+++ b/docs/examples/helper/README.md
@@ -0,0 +1,25 @@
+# Helper Utilities
+
+This directory contains helper functions and utilities used across multiple examples.
+
+## Files
+
+### helpers.py
+Common utility functions used by example scripts.
+
+**Key Functions:**
+- `w()`: Text wrapping function for pretty-printing long outputs
+- Other formatting and display utilities
+
+## Usage
+
+```python
+from docs.examples.helper import w
+
+# Wrap long text for display
+print(w(long_text))
+```
+
+## Note
+
+This is a utility directory to support other examples. The helpers are not part of the core Mellea API but are useful for demonstration purposes.
\ No newline at end of file
diff --git a/docs/examples/image_text_models/README.md b/docs/examples/image_text_models/README.md
new file mode 100644
index 00000000..e84b4ad8
--- /dev/null
+++ b/docs/examples/image_text_models/README.md
@@ -0,0 +1,65 @@
+# Vision/Multimodal Examples
+
+This directory contains examples for working with vision-language models that can process both images and text.
+
+## Files
+
+### vision_ollama_chat.py
+Demonstrates using vision models through Ollama backend with chat interface.
+
+**Key Features:**
+- Loading and processing images
+- Using vision models for image understanding
+- Chat-based interaction with images
+
+### vision_openai_examples.py
+Shows how to use OpenAI-compatible vision models (including local VLLM servers).
+
+### vision_litellm_backend.py
+Examples using LiteLLM backend for vision model access.
+
+## Supporting Files
+
+### pointing_up.jpg
+Sample image used in the examples for testing vision capabilities.
+
+## Concepts Demonstrated
+
+- **Multimodal Input**: Combining text and images in prompts
+- **Vision Understanding**: Asking questions about image content
+- **Backend Flexibility**: Using different backends (Ollama, OpenAI, LiteLLM) for vision
+- **Image Processing**: Loading and formatting images for LLM consumption
+
+## Basic Usage
+
+```python
+from mellea import start_session
+from mellea.stdlib.components import Message
+
+# Load image
+with open("pointing_up.jpg", "rb") as f:
+    image_data = f.read()
+
+# Create session with vision model
+m = start_session(model_id="llava:7b")
+
+# Ask about the image
+response = m.chat(
+    Message(
+        role="user",
+        content="What do you see in this image?",
+        images=[image_data]
+    )
+)
+```
+
+## Supported Models
+
+- **Ollama**: llava, bakllava, llava-phi3, moondream
+- **OpenAI**: gpt-4-vision-preview, gpt-4o
+- **LiteLLM**: Various vision models through unified interface
+
+## Related Documentation
+
+- See `test/backends/test_vision_*.py` for more examples
+- See `mellea/stdlib/components/chat.py` for Message API
\ No newline at end of file
diff --git a/docs/examples/information_extraction/README.md b/docs/examples/information_extraction/README.md
new file mode 100644
index 00000000..5c36ee53
--- /dev/null
+++ b/docs/examples/information_extraction/README.md
@@ -0,0 +1,53 @@
+# Information Extraction Examples
+
+This directory contains examples for extracting structured information from unstructured text using Mellea.
+
+## Files
+
+### 101_with_gen_slots.py
+Basic information extraction using generative slots to extract person names from text.
+
+**Key Features:**
+- Using `@generative` decorator for extraction tasks
+- Type-safe extraction with `list[str]` return type
+- Simple, declarative approach to information extraction
+- Example with NYTimes article text
+
+### advanced_with_m_instruct.py
+More advanced extraction patterns using `m.instruct()` with structured outputs.
+
+## Concepts Demonstrated
+
+- **Named Entity Recognition**: Extracting person names, locations, etc.
+- **Structured Extraction**: Getting typed, structured data from text
+- **Type Safety**: Using Python types to constrain extraction format
+- **Declarative Extraction**: Describing what to extract in docstrings
+
+## Basic Usage
+
+```python
+from mellea import generative, start_session
+
+@generative
+def extract_all_person_names(doc: str) -> list[str]:
+    """
+    Given a document, extract names of ALL mentioned persons.
+    Return these names as list of strings.
+    """
+
+m = start_session()
+names = extract_all_person_names(m, doc=article_text)
+print(names)  # ['President Obama', 'Angela Merkel']
+```
+
+## Use Cases
+
+- **Document Processing**: Extract key information from documents
+- **Data Mining**: Pull structured data from unstructured sources
+- **Content Analysis**: Identify entities, relationships, and facts
+- **Metadata Generation**: Create structured metadata from text
+
+## Related Documentation
+
+- See `generative_slots/` for more on the `@generative` decorator
+- See `mellea/stdlib/components/genslot.py` for implementation details
\ No newline at end of file
diff --git a/docs/examples/instruct_validate_repair/README.md b/docs/examples/instruct_validate_repair/README.md
new file mode 100644
index 00000000..77e4661c
--- /dev/null
+++ b/docs/examples/instruct_validate_repair/README.md
@@ -0,0 +1,93 @@
+# Instruct-Validate-Repair Examples
+
+This directory demonstrates Mellea's core instruct-validate-repair paradigm for reliable LLM outputs.
+
+## Files
+
+### 101_email.py
+The simplest example - using `m.instruct()` to generate an email.
+
+**Key Features:**
+- Basic session creation with `start_session()`
+- Simple instruction without requirements
+- Accessing the last prompt with `m.last_prompt()`
+
+### 101_email_with_requirements.py
+Adds requirements to constrain the output.
+
+**Key Features:**
+- Using string-based requirements
+- Automatic validation and repair
+- Ensuring output meets specified criteria
+
+### 101_email_with_validate.py
+Explicitly demonstrates the validation step.
+
+**Key Features:**
+- Separating generation and validation
+- Using `m.validate()` to check requirements
+- Understanding validation results
+
+### 101_email_comparison.py
+Compares outputs with and without requirements.
+
+### advanced_email_with_validate_function.py
+Shows how to use custom validation functions for complex requirements.
+
+**Key Features:**
+- Creating custom validation functions
+- Using `simple_validate()` helper
+- Combining multiple validation strategies
+
+## Concepts Demonstrated
+
+- **Instruct**: Generating outputs with natural language instructions
+- **Validate**: Checking outputs against requirements
+- **Repair**: Automatically fixing outputs that fail validation
+- **Requirements**: Constraining outputs with natural language or functions
+- **Sampling Strategies**: Using rejection sampling for reliable outputs
+
+## Basic Pattern
+
+```python
+from mellea import start_session
+
+# 1. Instruct
+m = start_session()
+result = m.instruct(
+    "Write an email to invite interns to the office party.",
+    requirements=[
+        "Keep it under 50 words",
+        "Include a date and time",
+        "Be professional"
+    ]
+)
+
+# 2. Validate (automatic with requirements)
+# 3. Repair (automatic if validation fails)
+print(result)
+```
+
+## Advanced Pattern
+
+```python
+from mellea.stdlib.requirements import simple_validate, req
+from mellea.stdlib.sampling import RejectionSamplingStrategy
+
+def check_length(text: str) -> bool:
+    return len(text.split()) < 50
+
+result = m.instruct(
+    "Write an email...",
+    requirements=[
+        req("Under 50 words", validation_fn=simple_validate(check_length))
+    ],
+    strategy=RejectionSamplingStrategy(loop_budget=3)
+)
+```
+
+## Related Documentation
+
+- See `mellea/stdlib/requirements/` for requirement types
+- See `mellea/stdlib/sampling/` for sampling strategies
+- See `docs/dev/mellea_library.md` for design philosophy
\ No newline at end of file
diff --git a/docs/examples/intrinsics/README.md b/docs/examples/intrinsics/README.md
new file mode 100644
index 00000000..5df00691
--- /dev/null
+++ b/docs/examples/intrinsics/README.md
@@ -0,0 +1,79 @@
+# Intrinsics Examples
+
+This directory contains examples for using Mellea's intrinsic functions - specialized model capabilities accessed through adapters.
+
+## Files
+
+### intrinsics.py
+Core example showing how to directly use intrinsics with adapters.
+
+**Key Features:**
+- Creating and adding adapters to backends
+- Using `Intrinsic` component for specialized tasks
+- Working with Granite Common adapters (aLoRA-based)
+- Understanding adapter output formats
+
+### answer_relevance.py
+Evaluates whether an answer is relevant to a question.
+
+### answerability.py
+Checks if a question can be answered given the context.
+
+### citations.py
+Validates and extracts citations from generated text.
+
+### context_relevance.py
+Assesses if retrieved context is relevant to a query.
+
+### hallucination_detection.py
+Detects when model outputs contain hallucinated information.
+
+### query_rewrite.py
+Rewrites queries for better retrieval or understanding.
+
+## Concepts Demonstrated
+
+- **Intrinsic Functions**: Specialized model capabilities beyond text generation
+- **Adapter System**: Using LoRA/aLoRA adapters for specific tasks
+- **RAG Evaluation**: Assessing retrieval-augmented generation quality
+- **Quality Metrics**: Measuring relevance, groundedness, and accuracy
+- **Backend Integration**: Adding adapters to different backend types
+
+## Basic Usage
+
+```python
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.backends.adapters.adapter import GraniteCommonAdapter
+from mellea.stdlib.components import Intrinsic
+import mellea.stdlib.functional as mfuncs
+
+# Create backend and adapter
+backend = LocalHFBackend(model_id="ibm-granite/granite-3.3-8b-instruct")
+adapter = GraniteCommonAdapter("requirement_check", 
+                               base_model_name=backend.base_model_name)
+backend.add_adapter(adapter)
+
+# Use intrinsic
+out, new_ctx = mfuncs.act(
+    Intrinsic("requirement_check",
+              intrinsic_kwargs={"requirement": "The assistant is helpful."}),
+    ctx,
+    backend
+)
+```
+
+## Available Intrinsics
+
+- **requirement_check**: Validate requirements (used by ALoraRequirement)
+- **answer_relevance**: Check answer-question relevance
+- **answerability**: Determine if question is answerable
+- **citations**: Extract and validate citations
+- **context_relevance**: Assess context-query relevance
+- **hallucination_detection**: Detect hallucinated content
+- **query_rewrite**: Improve query formulation
+
+## Related Documentation
+
+- See `mellea/stdlib/components/intrinsic/` for intrinsic implementations
+- See `mellea/backends/adapters/` for adapter system
+- See `docs/dev/intrinsics_and_adapters.md` for architecture details
\ No newline at end of file
diff --git a/docs/examples/library_interop/README.md b/docs/examples/library_interop/README.md
new file mode 100644
index 00000000..f9c51c6e
--- /dev/null
+++ b/docs/examples/library_interop/README.md
@@ -0,0 +1,71 @@
+# Library Interoperability Examples
+
+This directory demonstrates how to integrate Mellea with other LLM libraries and frameworks.
+
+## Files
+
+### langchain_messages.py
+Shows how to convert LangChain messages to Mellea format and use them in a session.
+
+**Key Features:**
+- Converting LangChain messages to Mellea messages
+- Using OpenAI-formatted messages as an intermediate format
+- Building Mellea contexts from external message formats
+- Maintaining conversation history across libraries
+
+## Concepts Demonstrated
+
+- **Message Conversion**: Translating between different message formats
+- **Context Building**: Creating Mellea contexts from external data
+- **Library Integration**: Using Mellea alongside other frameworks
+- **Format Compatibility**: Working with OpenAI-compatible message formats
+
+## Basic Pattern
+
+```python
+from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
+from langchain_core.messages import convert_to_openai_messages
+from mellea.stdlib.components import Message
+from mellea.stdlib.context import ChatContext
+from mellea import start_session
+
+# 1. Get messages from another library
+messages = [
+    SystemMessage(content="You are a helpful assistant"),
+    HumanMessage(content="Hello!"),
+    AIMessage(content="Hi there!")
+]
+
+# 2. Convert to OpenAI format (if needed)
+messages = convert_to_openai_messages(messages=messages)
+
+# 3. Build Mellea context
+ctx = ChatContext()
+for msg in messages:
+    ctx = ctx.add(Message(role=msg["role"], content=msg["content"]))
+
+# 4. Use in Mellea session
+m = start_session(ctx=ctx)
+response = m.chat("What was the last assistant message?")
+```
+
+## Integration Tips
+
+- **OpenAI Format**: Many libraries support OpenAI message format as a common interchange
+- **Explicit Contexts**: Mellea uses explicit context objects - build them from external messages
+- **Additional Data**: If messages contain images, documents, or other data, extract those fields explicitly
+- **Bidirectional**: You can also convert Mellea messages back to other formats
+
+## Supported Libraries
+
+This pattern works with any library that can export to OpenAI-compatible format:
+- LangChain
+- LlamaIndex
+- Haystack
+- Semantic Kernel
+- And many others
+
+## Related Documentation
+
+- See `mellea/stdlib/components/chat.py` for Message API
+- See `mellea/stdlib/context.py` for context management
\ No newline at end of file
diff --git a/docs/examples/m_serve/README.md b/docs/examples/m_serve/README.md
new file mode 100644
index 00000000..204a208f
--- /dev/null
+++ b/docs/examples/m_serve/README.md
@@ -0,0 +1,81 @@
+# M Serve Examples
+
+This directory contains examples for deploying Mellea programs as API services using the `m serve` CLI command.
+
+## Files
+
+### m_serve_example_simple.py
+A simple example showing how to structure a Mellea program for serving as an API.
+
+**Key Features:**
+- Defining a `serve()` function that takes input and returns output
+- Using requirements and sampling strategies in served programs
+- Custom validation functions for API constraints
+- Handling chat message inputs
+
+### pii_serve.py
+Example of serving a PII (Personally Identifiable Information) detection service.
+
+### client.py
+Client code for testing the served API endpoints.
+
+## Concepts Demonstrated
+
+- **API Deployment**: Exposing Mellea programs as REST APIs
+- **Input Handling**: Processing structured inputs (chat messages, requirements)
+- **Output Formatting**: Returning appropriate response types
+- **Validation in Production**: Using requirements in deployed services
+- **Model Options**: Passing model configuration through API
+
+## Basic Pattern
+
+```python
+from mellea import start_session
+from mellea.stdlib.sampling import RejectionSamplingStrategy
+from mellea.core import Requirement
+
+session = start_session()
+
+def serve(input: list[ChatMessage], 
+          requirements: list[str] | None = None,
+          model_options: dict | None = None):
+    """Main serving function - called by m serve."""
+    message = input[-1].content
+    
+    result = session.instruct(
+        description=message,
+        requirements=requirements or [],
+        strategy=RejectionSamplingStrategy(loop_budget=3),
+        model_options=model_options
+    )
+    return result
+```
+
+## Running the Server
+
+```bash
+# Start the server
+m serve docs/examples/m_serve/m_serve_example_simple.py
+
+# In another terminal, test with client
+python docs/examples/m_serve/client.py
+```
+
+## API Endpoints
+
+The `m serve` command automatically creates:
+- `POST /generate`: Main generation endpoint
+- `GET /health`: Health check endpoint
+- `GET /docs`: API documentation (Swagger UI)
+
+## Use Cases
+
+- **Production Deployment**: Deploy Mellea programs as microservices
+- **API Integration**: Integrate with existing systems via REST API
+- **Scalability**: Run multiple instances behind a load balancer
+- **Monitoring**: Add logging and metrics to served programs
+
+## Related Documentation
+
+- See `cli/serve/` for server implementation
+- See `mellea/stdlib/session.py` for session management
\ No newline at end of file
diff --git a/docs/examples/melp/README.md b/docs/examples/melp/README.md
new file mode 100644
index 00000000..7610b799
--- /dev/null
+++ b/docs/examples/melp/README.md
@@ -0,0 +1,58 @@
+# MELP (Mellea Language Programming) Examples
+
+This directory contains examples of MELP - an experimental lazy evaluation system for Mellea programs.
+
+## Files
+
+### simple_example.py
+Basic introduction to MELP's lazy evaluation concepts.
+
+### lazy.py
+Core lazy evaluation patterns and primitives.
+
+### lazy_fib.py
+Demonstrates lazy evaluation with Fibonacci sequence generation.
+
+### lazy_fib_sample.py
+Sampling and evaluation strategies with lazy computations.
+
+### states.py
+State management in lazy evaluation contexts.
+
+## Concepts Demonstrated
+
+- **Lazy Evaluation**: Deferring computation until results are needed
+- **Thunks**: Suspended computations that can be evaluated later
+- **State Management**: Handling state in lazy evaluation contexts
+- **Sampling Strategies**: Combining lazy evaluation with sampling
+- **Composability**: Building complex lazy programs from simple parts
+
+## What is MELP?
+
+MELP is an experimental feature that brings lazy evaluation to Mellea programs. It allows you to:
+- Define computations without immediately executing them
+- Compose complex workflows declaratively
+- Optimize execution by avoiding unnecessary computations
+- Implement advanced control flow patterns
+
+## Basic Pattern
+
+```python
+# Define lazy computations
+lazy_result = lazy_function(args)
+
+# Compose lazy computations
+composed = lazy_map(transform, lazy_result)
+
+# Force evaluation when needed
+actual_result = force(composed)
+```
+
+## Status
+
+⚠️ **Experimental**: MELP is an experimental feature and APIs may change. Use with caution in production code.
+
+## Related Documentation
+
+- See `mellea/stdlib/functional.py` for functional programming primitives
+- See `docs/dev/mellea_library.md` for design philosophy
\ No newline at end of file
diff --git a/docs/examples/mify/README.md b/docs/examples/mify/README.md
new file mode 100644
index 00000000..0c3f6b06
--- /dev/null
+++ b/docs/examples/mify/README.md
@@ -0,0 +1,97 @@
+# Mify Examples
+
+This directory demonstrates the `@mify` decorator for making custom Python objects work seamlessly with Mellea.
+
+## Files
+
+### mify.py
+Comprehensive examples of using `@mify` to integrate custom classes with Mellea.
+
+**Key Features:**
+- Basic class mification with `@mify` decorator
+- Ad-hoc object mification
+- Custom string representations with `stringify_func`
+- Template integration with `query_type` and `template_order`
+- Field selection with `fields_include`
+- Function exposure as tools with `funcs_include`
+
+### rich_document_advanced.py
+Advanced examples using mify with rich document types.
+
+### rich_table_execute_basic.py
+Examples of mifying table objects for data manipulation.
+
+## Concepts Demonstrated
+
+- **Object Integration**: Making custom objects LLM-compatible
+- **Template System**: Using Jinja2 templates for object rendering
+- **Tool Generation**: Automatically exposing methods as LLM tools
+- **Type Safety**: Maintaining Python type information
+- **Composability**: Using mified objects in Mellea operations
+
+## Basic Usage
+
+```python
+from mellea.stdlib.components.mify import mify
+from mellea import start_session
+
+# Mify a class
+@mify
+class Customer:
+    def __init__(self, name: str, last_purchase: str):
+        self.name = name
+        self.last_purchase = last_purchase
+
+# Use in Mellea
+customer = Customer("Jack", "Beans")
+m = start_session()
+m.act(customer)
+```
+
+## Advanced Usage
+
+```python
+# Custom string representation
+@mify(stringify_func=lambda x: f"Location: {x.location}")
+class Store:
+    def __init__(self, location: str):
+        self.location = location
+
+# Template integration
+@mify(query_type=TableQuery, template_order=["*", "Table"])
+class Database:
+    def to_markdown(self):
+        return self.table_data
+
+# Field selection
+@mify(fields_include={"name", "value"}, template="{{ name }}: {{ value }}")
+class Config:
+    name: str
+    value: str
+    internal_data: dict  # Not included
+
+# Function exposure
+@mify(funcs_include={"process", "validate"})
+class Processor:
+    def process(self, data: str) -> str:
+        """Process the data."""
+        return data.upper()
+    
+    def validate(self, data: str) -> bool:
+        """Validate the data."""
+        return len(data) > 0
+```
+
+## MifiedProtocol
+
+Objects decorated with `@mify` implement the `MifiedProtocol`, which provides:
+- `format_for_llm()`: Format object for LLM consumption
+- Template rendering support
+- Tool function exposure
+- Integration with Mellea operations
+
+## Related Documentation
+
+- See `mellea/stdlib/components/mify.py` for implementation
+- See `docs/dev/mify.md` for design details
+- See `mellea/templates/` for template system
\ No newline at end of file
diff --git a/docs/examples/mini_researcher/README.md b/docs/examples/mini_researcher/README.md
new file mode 100644
index 00000000..610ea6ce
--- /dev/null
+++ b/docs/examples/mini_researcher/README.md
@@ -0,0 +1,91 @@
+# Mini Researcher Example
+
+This directory contains a complete example application: a mini research assistant that uses RAG (Retrieval-Augmented Generation) with validation.
+
+## Files
+
+### researcher.py
+Main implementation of the research assistant with helper functions.
+
+**Key Features:**
+- Session management with caching
+- Guardian model integration for safety
+- Custom validation functions
+- Word count constraints
+- Subset validation for citations
+
+### context_docs.py
+Document context and RAG document definitions.
+
+### __init__.py
+Package initialization and exports.
+
+## Concepts Demonstrated
+
+- **Complete Application**: Full-featured research assistant
+- **RAG Integration**: Retrieval-augmented generation workflow
+- **Multi-Model Setup**: Using different models for different tasks
+- **Validation Pipeline**: Multiple validation requirements
+- **Safety Checks**: Guardian model for content safety
+- **Custom Requirements**: Domain-specific validation logic
+- **Caching**: Efficient session reuse with `@cache`
+
+## Architecture
+
+```
+User Query
+    ↓
+Document Retrieval (RAG)
+    ↓
+Generation with Context
+    ↓
+Validation:
+  - Word count check
+  - Citation validation
+  - Safety check (Guardian)
+    ↓
+Result
+```
+
+## Key Components
+
+### Session Management
+```python
+@cache
+def get_session():
+    """Get M session (change model here)."""
+    return MelleaSession(backend=OllamaModelBackend(model_ids.IBM_GRANITE_4_MICRO_3B))
+
+@cache
+def get_guardian_session():
+    """Get M session for the guardian model."""
+    return MelleaSession(backend=OllamaModelBackend(model_ids.IBM_GRANITE_GUARDIAN_3_0_2B))
+```
+
+### Custom Validation
+```python
+def create_check_word_count(max_words: int) -> Callable[[str], bool]:
+    """Generate a maximum-word-count validation function."""
+    def cc(s: str):
+        return len(s.split()) <= max_words
+    return cc
+
+def is_a_true_subset_of_b(a: list[str], b: list[str]) -> bool:
+    """Check if a is true subset of b."""
+    # Citation validation logic
+```
+
+## Usage Pattern
+
+This example demonstrates best practices for building production applications:
+1. **Separation of Concerns**: Different modules for different responsibilities
+2. **Reusable Components**: Helper functions that can be used across the app
+3. **Multi-Model Architecture**: Using specialized models for specific tasks
+4. **Comprehensive Validation**: Multiple layers of validation
+5. **Caching**: Performance optimization with session caching
+
+## Related Documentation
+
+- See `rag/` for RAG examples
+- See `safety/` for Guardian examples
+- See `mellea/stdlib/requirements/` for validation patterns
\ No newline at end of file
diff --git a/docs/examples/mobject/README.md b/docs/examples/mobject/README.md
new file mode 100644
index 00000000..e03f1858
--- /dev/null
+++ b/docs/examples/mobject/README.md
@@ -0,0 +1,78 @@
+# MObject Examples
+
+This directory contains examples of using MObjects (Mellea Objects) - structured data types that work seamlessly with LLMs.
+
+## Files
+
+### table.py
+Demonstrates using table MObjects for structured data manipulation.
+
+**Key Features:**
+- Creating and querying tables
+- Table transformations
+- Structured data operations
+- Type-safe table manipulation
+
+## Concepts Demonstrated
+
+- **Structured Data**: Working with tables and structured formats
+- **Query Operations**: Asking questions about data
+- **Transformations**: Modifying data based on instructions
+- **Type Safety**: Maintaining structure through operations
+- **LLM Integration**: Using LLMs to work with structured data
+
+## Basic Usage
+
+```python
+from mellea.stdlib.components import Table
+from mellea import start_session
+
+# Create a table
+table = Table(data=[
+    {"name": "Alice", "age": 30, "city": "NYC"},
+    {"name": "Bob", "age": 25, "city": "SF"},
+])
+
+m = start_session()
+
+# Query the table
+result = m.query(table, "What is the average age?")
+
+# Transform the table
+new_table = m.transform(table, "Add a column for country (USA)")
+```
+
+## MObject Types
+
+Mellea provides several MObject types:
+- **Table**: Tabular data with rows and columns
+- **Document**: Text documents with metadata
+- **RichDocument**: Documents with rich formatting
+- Custom MObjects via `@mify`
+
+## Operations
+
+### Query
+Ask questions about the data without modifying it:
+```python
+answer = m.query(mobject, "What is the total?")
+```
+
+### Transform
+Modify the data based on instructions:
+```python
+new_mobject = m.transform(mobject, "Sort by date descending")
+```
+
+### Execute
+Perform operations that may have side effects:
+```python
+result = m.execute(mobject, "Calculate statistics")
+```
+
+## Related Documentation
+
+- See `mellea/stdlib/components/mobject.py` for MObject base class
+- See `mellea/stdlib/components/docs/` for document MObjects
+- See `mify/` for creating custom MObjects
+- See `notebooks/table_mobject.ipynb` for interactive examples
\ No newline at end of file
diff --git a/docs/examples/notebooks/README.md b/docs/examples/notebooks/README.md
new file mode 100644
index 00000000..d3021870
--- /dev/null
+++ b/docs/examples/notebooks/README.md
@@ -0,0 +1,78 @@
+# Jupyter Notebook Examples
+
+This directory contains interactive Jupyter notebooks demonstrating various Mellea features.
+
+## Notebooks
+
+### example.ipynb
+General introduction to Mellea with basic examples.
+
+### compositionality_with_generative_slots.ipynb
+Interactive tutorial on composing generative functions.
+
+### context_example.ipynb
+Working with contexts and context management.
+
+### document_mobject.ipynb
+Using document MObjects for text processing.
+
+### georgia_tech.ipynb
+Domain-specific example (possibly academic/research use case).
+
+### instruct_validate_repair.ipynb
+Interactive walkthrough of the instruct-validate-repair paradigm.
+
+### m_serve_example.ipynb
+Deploying Mellea programs as services.
+
+### mcp_example.ipynb
+Model Context Protocol integration examples.
+
+### model_options_example.ipynb
+Configuring model options and parameters.
+
+### sentiment_classifier.ipynb
+Building a sentiment classification system.
+
+### simple_email.ipynb
+Email generation with requirements.
+
+### table_mobject.ipynb
+Working with table data structures.
+
+## Running the Notebooks
+
+```bash
+# Install Jupyter if needed
+uv pip install jupyter
+
+# Start Jupyter
+jupyter notebook docs/examples/notebooks/
+
+# Or use JupyterLab
+jupyter lab docs/examples/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 `tutorial/` for Python script versions
+- See individual example directories for more details on each topic
\ No newline at end of file
diff --git a/docs/examples/rag/README.md b/docs/examples/rag/README.md
new file mode 100644
index 00000000..eced0675
--- /dev/null
+++ b/docs/examples/rag/README.md
@@ -0,0 +1,103 @@
+# RAG (Retrieval-Augmented Generation) Examples
+
+This directory contains examples of implementing RAG systems with Mellea.
+
+## Files
+
+### simple_rag_with_filter.py
+A complete RAG pipeline with relevance filtering using generative slots.
+
+**Key Features:**
+- Vector embedding with FAISS index
+- Semantic search for document retrieval
+- LLM-based relevance filtering
+- Answer generation with grounded context
+- Using `@generative` for filtering logic
+
+### mellea_pdf.py
+RAG example specifically for PDF documents.
+
+## Concepts Demonstrated
+
+- **Vector Search**: Using embeddings for semantic retrieval
+- **Relevance Filtering**: Using LLMs to filter retrieved documents
+- **Grounded Generation**: Generating answers based on retrieved context
+- **Multi-Stage Pipeline**: Retrieval → Filtering → Generation
+- **Generative Slots**: Using `@generative` for RAG components
+
+## Pipeline Architecture
+
+```
+Query
+  ↓
+Embedding Model (sentence-transformers)
+  ↓
+Vector Search (FAISS)
+  ↓
+Retrieved Documents
+  ↓
+Relevance Filter (LLM)
+  ↓
+Relevant Documents
+  ↓
+Answer Generation (LLM with grounding_context)
+  ↓
+Final Answer
+```
+
+## Basic Usage
+
+```python
+from mellea import generative, start_session
+from sentence_transformers import SentenceTransformer
+from faiss import IndexFlatIP
+
+# 1. Create embeddings and index
+embedding_model = SentenceTransformer("all-MiniLM-L6-v2")
+embeddings = embedding_model.encode(documents)
+index = IndexFlatIP(dimension)
+index.add(embeddings)
+
+# 2. Retrieve documents
+query_embedding = embedding_model.encode([query])
+distances, indices = index.search(query_embedding, k=5)
+retrieved_docs = [documents[i] for i in indices[0]]
+
+# 3. Filter for relevance
+@generative
+def is_answer_relevant_to_question(answer: str, question: str) -> bool:
+    """Determine whether the answer is relevant to the question."""
+
+m = start_session()
+relevant_docs = [
+    doc for doc in retrieved_docs 
+    if is_answer_relevant_to_question(m, answer=doc, question=query)
+]
+
+# 4. Generate answer with grounding
+answer = m.instruct(
+    "Answer the question: {{query}}",
+    user_variables={"query": query},
+    grounding_context={f"doc{i}": doc for i, doc in enumerate(relevant_docs)}
+)
+```
+
+## Dependencies
+
+```bash
+# Install RAG dependencies
+uv pip install faiss-cpu sentence-transformers
+```
+
+## Key Techniques
+
+- **Semantic Search**: Finding relevant documents by meaning, not keywords
+- **Two-Stage Retrieval**: Broad retrieval followed by precise filtering
+- **Grounding Context**: Providing retrieved documents to the LLM
+- **Relevance Validation**: Using LLMs to validate retrieval quality
+
+## Related Documentation
+
+- See `intrinsics/` for RAG evaluation intrinsics
+- See `mini_researcher/` for a complete RAG application
+- See `mellea/stdlib/components/intrinsic/rag.py` for RAG helpers
\ No newline at end of file
diff --git a/docs/examples/safety/README.md b/docs/examples/safety/README.md
new file mode 100644
index 00000000..4e81bd62
--- /dev/null
+++ b/docs/examples/safety/README.md
@@ -0,0 +1,127 @@
+# Safety Examples
+
+This directory contains examples of using Granite Guardian models for content safety and validation.
+
+## Files
+
+### guardian.py
+Comprehensive examples of using the enhanced GuardianCheck requirement with Granite Guardian 3.3 8B.
+
+**Key Features:**
+- Multiple risk types (harm, jailbreak, social bias, etc.)
+- Thinking mode for detailed reasoning
+- Custom criteria for domain-specific safety
+- Groundedness detection
+- Function call hallucination detection
+- Multiple backend support (Ollama, HuggingFace)
+
+### guardian_huggingface.py
+Using Guardian models with HuggingFace backend.
+
+### repair_with_guardian.py
+Combining Guardian safety checks with automatic repair.
+
+## Concepts Demonstrated
+
+- **Content Safety**: Detecting harmful, biased, or inappropriate content
+- **Jailbreak Detection**: Identifying attempts to bypass safety measures
+- **Groundedness**: Ensuring responses are factually grounded
+- **Function Call Validation**: Detecting hallucinated tool calls
+- **Multi-Risk Assessment**: Checking multiple safety criteria
+- **Thinking Mode**: Getting detailed reasoning for safety decisions
+
+## Available Risk Types
+
+```python
+from mellea.stdlib.requirements.safety.guardian import GuardianRisk
+
+# Built-in risk types
+GuardianRisk.HARM              # Harmful content
+GuardianRisk.JAILBREAK         # Jailbreak attempts
+GuardianRisk.SOCIAL_BIAS       # Social bias
+GuardianRisk.GROUNDEDNESS      # Factual grounding
+GuardianRisk.FUNCTION_CALL     # Function call hallucination
+# ... and more
+```
+
+## Basic Usage
+
+```python
+from mellea import start_session
+from mellea.stdlib.requirements.safety.guardian import GuardianCheck, GuardianRisk
+
+# Create guardian with specific risk type
+guardian = GuardianCheck(GuardianRisk.HARM, thinking=True)
+
+# Use in validation
+m = start_session()
+m.chat("Write a professional email.")
+is_safe = m.validate([guardian])
+
+print(f"Content is safe: {is_safe[0]._result}")
+if is_safe[0]._reason:
+    print(f"Reasoning: {is_safe[0]._reason}")
+```
+
+## Advanced Usage
+
+### Custom Criteria
+```python
+custom_guardian = GuardianCheck(
+    custom_criteria="Check for inappropriate content in educational context"
+)
+```
+
+### Groundedness Detection
+```python
+groundedness_guardian = GuardianCheck(
+    GuardianRisk.GROUNDEDNESS,
+    thinking=True,
+    context_text="Reference text for grounding check..."
+)
+```
+
+### Function Call Validation
+```python
+function_guardian = GuardianCheck(
+    GuardianRisk.FUNCTION_CALL,
+    thinking=True,
+    tools=[tool_definition]
+)
+```
+
+### Multiple Guardians
+```python
+guardians = [
+    GuardianCheck(GuardianRisk.HARM),
+    GuardianCheck(GuardianRisk.JAILBREAK),
+    GuardianCheck(GuardianRisk.SOCIAL_BIAS),
+]
+results = m.validate(guardians)
+```
+
+## Thinking Mode
+
+Enable `thinking=True` to get detailed reasoning:
+```python
+guardian = GuardianCheck(GuardianRisk.HARM, thinking=True)
+result = m.validate([guardian])
+print(result[0]._reason)  # Detailed explanation
+```
+
+## Backend Support
+
+- **Ollama**: `backend_type="ollama"` (default)
+- **HuggingFace**: `backend_type="huggingface"`
+- **Custom**: Pass your own backend instance
+
+## Models
+
+- Granite Guardian 3.0 2B
+- Granite Guardian 3.3 8B (recommended)
+
+## Related Documentation
+
+- See `mellea/stdlib/requirements/safety/guardian.py` for implementation
+- See `test/stdlib/requirements/` for more examples
+- See IBM Granite Guardian documentation for model details
\ No newline at end of file
diff --git a/docs/examples/sessions/README.md b/docs/examples/sessions/README.md
new file mode 100644
index 00000000..127439f9
--- /dev/null
+++ b/docs/examples/sessions/README.md
@@ -0,0 +1,113 @@
+# Session Examples
+
+This directory contains examples of creating and customizing Mellea sessions.
+
+## Files
+
+### creating_a_new_type_of_session.py
+Demonstrates how to create custom session types with specialized behavior.
+
+**Key Features:**
+- Extending the base session class
+- Custom context types
+- Specialized session methods
+- Session configuration patterns
+
+## Concepts Demonstrated
+
+- **Session Customization**: Creating domain-specific session types
+- **Context Management**: Using different context types
+- **Backend Configuration**: Setting up backends for sessions
+- **Session Lifecycle**: Managing session state and resources
+
+## Basic Session Creation
+
+```python
+from mellea import start_session
+
+# Default session (Ollama backend, SimpleContext)
+m = start_session()
+
+# With specific model
+m = start_session(model_id="ibm-granite/granite-3.2-8b-instruct")
+
+# With chat context
+from mellea.stdlib.context import ChatContext
+m = start_session(ctx=ChatContext())
+
+# With model options
+from mellea.backends import ModelOption
+m = start_session(model_options={
+    ModelOption.MAX_NEW_TOKENS: 200,
+    ModelOption.TEMPERATURE: 0.7
+})
+```
+
+## Custom Session Pattern
+
+```python
+from mellea import MelleaSession
+from mellea.backends.ollama import OllamaModelBackend
+from mellea.stdlib.context import ChatContext
+
+class MyCustomSession(MelleaSession):
+    def __init__(self, **kwargs):
+        backend = OllamaModelBackend(
+            model_id="my-model",
+            **kwargs
+        )
+        super().__init__(backend=backend, ctx=ChatContext())
+    
+    def custom_method(self, prompt: str):
+        """Add custom functionality."""
+        # Your custom logic here
+        return self.instruct(prompt)
+
+# Use custom session
+m = MyCustomSession()
+result = m.custom_method("Hello!")
+```
+
+## Session Context Managers
+
+```python
+# Automatic cleanup with context manager
+with start_session() as m:
+    result = m.instruct("Generate text")
+    # Session automatically cleaned up
+```
+
+## Backend Options
+
+```python
+# Ollama (default)
+from mellea.backends.ollama import OllamaModelBackend
+backend = OllamaModelBackend(model_id="llama2")
+
+# OpenAI
+from mellea.backends.openai import OpenAIBackend
+backend = OpenAIBackend(model_id="gpt-4")
+
+# HuggingFace
+from mellea.backends.huggingface import LocalHFBackend
+backend = LocalHFBackend(model_id="ibm-granite/granite-3.2-8b-instruct")
+
+# LiteLLM
+from mellea.backends.litellm import LiteLLMBackend
+backend = LiteLLMBackend(model_id="claude-3-opus")
+
+# Create session with custom backend
+m = MelleaSession(backend=backend, ctx=ChatContext())
+```
+
+## Context Types
+
+- **SimpleContext**: Basic linear context
+- **ChatContext**: Multi-turn conversation context
+- **Custom**: Create your own context types
+
+## Related Documentation
+
+- See `mellea/stdlib/session.py` for session implementation
+- See `mellea/stdlib/context.py` for context types
+- See `mellea/backends/` for backend options
\ No newline at end of file
diff --git a/docs/examples/sofai/README.md b/docs/examples/sofai/README.md
new file mode 100644
index 00000000..693dbe90
--- /dev/null
+++ b/docs/examples/sofai/README.md
@@ -0,0 +1,124 @@
+# SOFAI (Slow and Fast AI) Examples
+
+This directory contains examples of the SOFAI sampling strategy - a two-tier approach using fast and slow models.
+
+## Files
+
+### sofai_graph_coloring.py
+Complete example using SOFAI for constraint satisfaction problems (graph coloring).
+
+**Key Features:**
+- Two-tier model architecture (fast S1, slow S2)
+- Iterative feedback loop with fast model
+- Escalation to slow model when needed
+- Custom validation with detailed feedback
+- Consumer-grade hardware friendly
+
+## Concepts Demonstrated
+
+- **Two-Tier Architecture**: Fast model for iteration, slow model for hard cases
+- **Escalation Strategy**: When to switch from fast to slow model
+- **Feedback Loops**: Providing validation feedback to guide generation
+- **Constraint Satisfaction**: Solving CSP problems with LLMs
+- **Cost Optimization**: Using expensive models only when necessary
+
+## SOFAI Architecture
+
+```
+User Request
+    ↓
+S1 (Fast Model) ←─────┐
+    ↓                  │
+Validation             │
+    ↓                  │
+Pass? ──No→ Feedback ──┘
+    │
+   Yes
+    ↓
+Success? ──No→ Escalate to S2 (Slow Model)
+    │              ↓
+   Yes         Validation
+    ↓              ↓
+  Result        Result
+```
+
+## Basic Usage
+
+```python
+from mellea import start_session
+from mellea.backends.ollama import OllamaModelBackend
+from mellea.stdlib.sampling import SOFAISamplingStrategy
+from mellea.stdlib.requirements import req
+
+# Create fast and slow backends
+s1_backend = OllamaModelBackend(model_id="phi:2.7b")
+s2_backend = OllamaModelBackend(model_id="qwen3-4b-thinking")
+
+# Create SOFAI strategy
+strategy = SOFAISamplingStrategy(
+    s1_backend=s1_backend,
+    s2_backend=s2_backend,
+    s1_loop_budget=3,  # Try fast model 3 times
+    escalate_on_failure=True
+)
+
+# Use with requirements
+m = start_session()
+result = m.instruct(
+    "Solve the problem...",
+    requirements=[req("Must satisfy constraint X")],
+    strategy=strategy
+)
+```
+
+## Configuration Options
+
+```python
+SOFAISamplingStrategy(
+    s1_backend=fast_backend,      # Fast model for iteration
+    s2_backend=slow_backend,       # Slow model for escalation
+    s1_loop_budget=3,              # Max attempts with fast model
+    escalate_on_failure=True,      # Use slow model if fast fails
+    feedback_strategy="all_errors" # How to provide feedback
+)
+```
+
+## Feedback Strategies
+
+- `"simple"`: Basic pass/fail feedback
+- `"first_error"`: Feedback on first failing requirement
+- `"all_errors"`: Detailed feedback on all failures
+
+## Use Cases
+
+- **Constraint Satisfaction**: Graph coloring, scheduling, planning
+- **Complex Reasoning**: Multi-step problems requiring iteration
+- **Cost Optimization**: Use expensive models only when needed
+- **Quality Assurance**: Fast iteration with slow model fallback
+
+## Model Selection
+
+### Fast Models (S1)
+- phi:2.7b
+- llama2:7b
+- mistral:7b
+- granite-3.2-8b-instruct
+
+### Slow Models (S2)
+- qwen3-4b-thinking
+- llama3:70b
+- mixtral:8x7b
+- granite-3.3-8b-instruct
+
+## Performance Tips
+
+1. **Choose appropriate S1 budget**: Balance speed vs. success rate
+2. **Use specific requirements**: Clear constraints help both models
+3. **Provide good feedback**: Detailed validation helps iteration
+4. **Profile your use case**: Measure when escalation is needed
+
+## Related Documentation
+
+- See `mellea/stdlib/sampling/sofai.py` for implementation
+- See `test/stdlib/sampling/test_sofai_*.py` for more examples
+- See `mellea/stdlib/sampling/` for other sampling strategies
\ No newline at end of file
diff --git a/docs/examples/tools/README.md b/docs/examples/tools/README.md
new file mode 100644
index 00000000..35fa9a31
--- /dev/null
+++ b/docs/examples/tools/README.md
@@ -0,0 +1,140 @@
+# Tool Calling Examples
+
+This directory contains examples of using tool calling (function calling) with Mellea.
+
+## Files
+
+### interpreter_example.py
+Comprehensive examples of using the code interpreter tool with LLMs.
+
+**Key Features:**
+- Direct code execution with `code_interpreter()`
+- Tool integration with `m.instruct()`
+- Forcing tool use with requirements
+- Validating tool arguments
+- Local vs. sandboxed execution
+
+## Concepts Demonstrated
+
+- **Tool Definition**: Creating tools for LLM use
+- **Tool Calling**: Having LLMs call functions
+- **Tool Requirements**: Forcing or validating tool use
+- **Argument Validation**: Ensuring correct tool arguments
+- **Code Execution**: Running generated code safely
+
+## Basic Usage
+
+### Direct Tool Use
+```python
+from mellea.stdlib.tools import code_interpreter
+
+# Execute code directly
+result = code_interpreter("print(1+1)")
+print(result)  # Output: 2
+```
+
+### Tool with LLM
+```python
+from mellea import start_session
+from mellea.backends import ModelOption
+from mellea.stdlib.tools import local_code_interpreter
+
+m = start_session()
+result = m.instruct(
+    "Make a plot of y=x^2",
+    model_options={ModelOption.TOOLS: [local_code_interpreter]}
+)
+```
+
+### Forcing Tool Use
+```python
+from mellea.stdlib.requirements import uses_tool
+
+result = m.instruct(
+    "Use the code interpreter to make a plot of y=x^2",
+    requirements=[uses_tool(local_code_interpreter)],
+    model_options={ModelOption.TOOLS: [local_code_interpreter]},
+    tool_calls=True
+)
+
+# Access the tool call
+code = result.tool_calls["local_code_interpreter"].args["code"]
+print(f"Generated code:\n{code}")
+
+# Execute the tool
+exec_result = result.tool_calls["local_code_interpreter"].call_func()
+```
+
+### Validating Tool Arguments
+```python
+from mellea.stdlib.requirements import tool_arg_validator
+
+result = m.instruct(
+    "Use the code interpreter to make a plot of y=x^2",
+    requirements=[
+        uses_tool(local_code_interpreter),
+        tool_arg_validator(
+            "The plot should be written to /tmp/output.png",
+            tool_name=local_code_interpreter,
+            arg_name="code",
+            validation_fn=lambda code: "/tmp/output.png" in code
+        )
+    ],
+    model_options={ModelOption.TOOLS: [local_code_interpreter]},
+    tool_calls=True
+)
+```
+
+## Available Tools
+
+### Code Interpreter
+- `code_interpreter`: Execute Python code (sandboxed)
+- `local_code_interpreter`: Execute Python code locally
+
+### Custom Tools
+
+Create custom tools by defining functions:
+```python
+def my_tool(arg1: str, arg2: int) -> str:
+    """Tool description for the LLM."""
+    return f"Processed {arg1} with {arg2}"
+
+# Use in model_options
+model_options={ModelOption.TOOLS: [my_tool]}
+```
+
+## Tool Requirements
+
+### uses_tool
+Ensures the LLM uses a specific tool:
+```python
+from mellea.stdlib.requirements import uses_tool
+requirements=[uses_tool(my_tool)]
+```
+
+### tool_arg_validator
+Validates tool arguments:
+```python
+from mellea.stdlib.requirements import tool_arg_validator
+
+tool_arg_validator(
+    description="Validation description",
+    tool_name=my_tool,
+    arg_name="arg1",
+    validation_fn=lambda x: len(x) > 5
+)
+```
+
+## Safety Considerations
+
+- **Sandboxing**: Use `code_interpreter` for untrusted code
+- **Validation**: Always validate tool arguments
+- **Permissions**: Be careful with file system access
+- **Resource Limits**: Set timeouts and memory limits
+
+## Related Documentation
+
+- See `mellea/stdlib/tools/interpreter.py` for interpreter implementation
+- See `mellea/stdlib/requirements/tool_reqs.py` for tool requirements
+- See `docs/dev/tool_calling.md` for architecture details
+- See `test/backends/test_tool_calls.py` for more examples
\ No newline at end of file
diff --git a/docs/examples/tutorial/README.md b/docs/examples/tutorial/README.md
new file mode 100644
index 00000000..14776d22
--- /dev/null
+++ b/docs/examples/tutorial/README.md
@@ -0,0 +1,104 @@
+# Tutorial Examples
+
+This directory contains Python script versions of the tutorial notebooks, suitable for running directly or studying the code.
+
+## Files
+
+### example.py
+General introduction to Mellea with basic examples.
+
+### simple_email.py
+Email generation example - the classic "Hello World" of Mellea.
+
+### instruct_validate_repair.py
+Walkthrough of the instruct-validate-repair paradigm.
+
+### compositionality_with_generative_slots.py
+Tutorial on composing generative functions.
+
+### context_example.py
+Working with contexts and context management.
+
+### document_mobject.py
+Using document MObjects for text processing.
+
+### table_mobject.py
+Working with table data structures.
+
+### model_options_example.py
+Configuring model options and parameters.
+
+### sentiment_classifier.py
+Building a sentiment classification system.
+
+### mcp_example.py
+Model Context Protocol integration examples.
+
+## 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
+```
+
+## Learning Path
+
+Recommended order for learning Mellea:
+
+1. **simple_email.py** - Start here for basic concepts
+2. **instruct_validate_repair.py** - Core paradigm
+3. **compositionality_with_generative_slots.py** - Building blocks
+4. **context_example.py** - Context management
+5. **model_options_example.py** - Configuration
+6. **sentiment_classifier.py** - Complete application
+7. **document_mobject.py** - Working with documents
+8. **table_mobject.py** - Working with structured data
+9. **mcp_example.py** - Advanced integration
+
+## 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 Slots**: 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:
+```bash
+# Install jupytext
+uv pip install jupytext
+
+# Convert
+jupytext --to notebook docs/examples/tutorial/simple_email.py
+```
+
+## Related Documentation
+
+- 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