docs(examples): standardize data, extraction, and RAG examples

docs/examples/information_extraction/101_with_gen_stubs.py

@@ -1,9 +1,18 @@
 # pytest: ollama, e2e
+"""Named entity extraction with generative stubs.
 
-"""Simple Example of information extraction with Mellea using generative stubs."""
+Demonstrates using a `@generative` function with a `list[str]` return type to
+extract all person names from a text passage declaratively.
+
+Prerequisites:
+    ollama pull granite4.2:3b
+    ollama serve
+
+Usage:
+    uv run python docs/examples/information_extraction/101_with_gen_stubs.py
+"""
 
 from mellea import generative, start_session
-from mellea.backends import model_ids
 
 m = start_session()
 

docs/examples/information_extraction/README.md

@@ -1,53 +1,10 @@
 # Information Extraction Examples
 
-This directory contains examples for extracting structured information from unstructured text using Mellea.
+Examples demonstrating structured information extraction from text using Mellea.
 
-## Files
+## Examples
 
-### [101_with_gen_stubs.py](./101_with_gen_stubs.py)
-Basic information extraction using generative stubs 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](./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_stubs/` for more on the `@generative` decorator
-- See `mellea/stdlib/components/genstub.py` for implementation details
+| File | Description |
+| :--- | :--- |
+| [`101_with_gen_stubs.py`](./101_with_gen_stubs.py) | Declarative named entity extraction using a `@generative` function with a `list[str]` return type. |
+| [`advanced_with_m_instruct.py`](./advanced_with_m_instruct.py) | Constrained extraction using `m.instruct()` with a Pydantic `format` model, a custom predicate requirement, and `RejectionSamplingStrategy`. |

docs/examples/information_extraction/advanced_with_m_instruct.py

@@ -1,13 +1,23 @@
 # pytest: ollama, e2e
+"""Structured information extraction with Pydantic formatting and sampling requirements.
 
-"""Advanced Example of information extraction with Mellea using m.instruct() and constraints."""
+Demonstrates constrained extraction using `m.instruct()` with a Pydantic `format`
+model, a custom `at_least_n` predicate requirement, and `RejectionSamplingStrategy`
+to retry until the output contains enough extracted entities.
+
+Prerequisites:
+    ollama pull granite4.2:3b
+    ollama serve
+
+Usage:
+    uv run python docs/examples/information_extraction/advanced_with_m_instruct.py
+"""
 
 from collections.abc import Callable
 
 from pydantic import BaseModel, ValidationError
 
 from mellea import start_session
-from mellea.backends import model_ids
 from mellea.core import SamplingResult
 from mellea.stdlib.requirements import check, simple_validate
 from mellea.stdlib.sampling import RejectionSamplingStrategy

docs/examples/mify/README.md

@@ -1,96 +1,13 @@
 # Mify Examples
 
-This directory demonstrates the `@mify` decorator for making custom Python objects work seamlessly with Mellea.
+Examples demonstrating the `@mify` decorator for making custom Python objects
+LLM-compatible with Mellea. For a conceptual overview, see
+[MObjects and mify](../../docs/docs/concepts/mobjects-and-mify.md).
 
-## Files
+## Examples
 
-### [mify.py](./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](./rich_document_advanced.py)
-Advanced examples using mify with rich document types.
-
-### [rich_table_execute_basic.py](./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 `mellea/templates/` for template system
+| File | Description |
+| :--- | :--- |
+| [`mify.py`](./mify.py) | Core `@mify` patterns: class decoration, ad-hoc object mification, `stringify_func`, `query_type` and `template_order` for template integration, `fields_include` with inline templates, and `funcs_include` for tool exposure. |
+| [`rich_document_advanced.py`](./rich_document_advanced.py) | Progressive walkthrough of PDF document processing: raw markdown export, `RichDocument` wrapper, a custom `format_for_llm()` subclass with an inline Jinja2 template, and grounded generation. Requires `docling`. |
+| [`rich_table_execute_basic.py`](./rich_table_execute_basic.py) | Extracting a mified `Table` from a PDF with `RichDocument` and applying `m.transform()` with seed-based retries to add a derived column. Requires `docling`. |

docs/examples/mify/mify.py

@@ -1,4 +1,19 @@
 # pytest: ollama, e2e
+"""Making custom Python objects LLM-compatible with @mify.
+
+Demonstrates the `@mify` decorator for integrating custom classes and ad-hoc
+objects with Mellea, including class-level decoration, ad-hoc mification,
+`stringify_func` for custom string representations, `query_type` and
+`template_order` for template integration, `fields_include` with inline
+templates, and `funcs_include` for exposing class methods as tools.
+
+Prerequisites:
+    ollama pull granite4.2:3b
+    ollama serve
+
+Usage:
+    uv run python docs/examples/mify/mify.py
+"""
 
 from mellea.stdlib.components.docs.richdocument import TableQuery
 from mellea.stdlib.components.mify import MifiedProtocol, mify

docs/examples/mify/rich_document_advanced.py

@@ -2,8 +2,21 @@
 # SKIP REASON: CXXABI_1.3.15 not found - conda environment issue on HPC systems with old glibc
 
 # ruff: noqa E402
-# Example: Rich Documents and Templating
-# Lets look at how to pass documents to a model using `Mellea`.
+"""Rich document processing and custom template formatting with docling.
+
+Walks through passing PDF documents to a Mellea model in progressively richer ways:
+raw markdown export via `m.chat()`, the built-in `RichDocument` wrapper, a custom
+subclass that overrides `format_for_llm()` to expose only section titles via an
+inline Jinja2 template, and finally using a custom-formatted document as
+`grounding_context` in `m.instruct()`.
+
+Prerequisites:
+    uv sync --extra backends
+    pip install docling docling-core
+
+Usage:
+    uv run python docs/examples/mify/rich_document_advanced.py
+"""
 
 # 1. We'll start by initializing our `Mellea` session.
 from docling_core.types.doc.document import DoclingDocument

docs/examples/mify/rich_table_execute_basic.py

@@ -1,6 +1,23 @@
 # pytest: ollama, qualitative, e2e
+"""Extracting and transforming tables from a PDF with RichDocument.
+
+Demonstrates loading a remote PDF with `RichDocument`, extracting its first
+table as a mified `Table` object, and applying `m.transform()` to add a derived
+column — retrying with different seeds until the result is a valid `Table`.
+
+`RichDocument` and `Table` are internally mified wrappers around Docling
+documents. More about Docling: https://github.com/docling-project/docling
+
+Prerequisites:
+    uv sync --extra backends
+    pip install docling
+    ollama pull llama3.2:3b
+    ollama serve
+
+Usage:
+    uv run python docs/examples/mify/rich_table_execute_basic.py
+"""
 
-# This is an example of using the RichDocument class.
 import os
 
 from mellea import start_session
@@ -10,12 +27,6 @@
 
 MelleaLogger.get_logger().setLevel("ERROR")
 
-"""
-Here we demonstrate the use of the (internally m-ified) class
-RichDocument and Table that are wrappers around Docling documents.
-More about Docling here: https://github.com/docling-project/docling
-"""
-
 # Using a paper from arxive as source file
 source = "https://arxiv.org/pdf/1906.04043"
 

docs/examples/mobject/README.md

@@ -1,78 +1,12 @@
 # MObject Examples
 
-This directory contains examples of using MObjects (Mellea Objects) - structured data types that work seamlessly with LLMs.
+Examples demonstrating the MObject pattern — using `@mify` to make structured Python objects
+queryable and transformable by Mellea sessions. For a full explanation and more patterns, see
+[MObjects and mify](../../docs/docs/concepts/mobjects-and-mify.md) and
+[Working with Data](../../docs/docs/how-to/working-with-data.md).
 
-## Files
+## Examples
 
-### [table.py](./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
+| File | Description |
+| :--- | :--- |
+| [`table.py`](./table.py) | Querying and updating a markdown table via `m.query()` and `m.transform()`, using `@mify` with `fields_include` and a Jinja2 template. |