docs(examples): standardize data, extraction, and RAG examples by rafvasq · Pull Request #1764 · generative-computing/mellea

rafvasq · 2026-10-26T20:00:14Z

Pull Request

Issue

Towards #1746

Description

Docstrings

Kept the original titles and descriptions. Added docstrings to scripts that had none.
Added Prerequisites: and Usage: blocks.

READMEs

Each is now a short description, links to the relevant docs, and includes a ## Examples table. Removed content was checked against the site docs first.

Other fixes

Removed unused model_ids imports in both information_extraction/ scripts.
ollama pull tags match each script's actual model.
Docling examples use uv sync --extra docling.
rich_document_advanced.py: added an MPS→CPU accelerator guard that RichDocument uses (fix: force cpu accelerator for docling on apple silicon mps #1417), so docling conversion completes on Apple Silicon.

Testing

Tests added to the respective file if code was changed
New code has 100% coverage if code was added
Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

AI coding assistants used

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

Component
Requirement
Sampling Strategy
Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.

…ed-by: IBM Bob Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>

planetf1

Overall this looks good, apart from the inline comments. I ran 101_with_gen_stubs.py, advanced_with_m_instruct.py, mify.py and table.py against granite4.2:3b and they run, and every ollama pull tag matches the model the script actually uses. The comments are mostly about link depth and install commands.

Separately, not for this PR: docs/docs/examples/data-extraction-pipeline.md mirrors 101_with_gen_stubs.py and still shows the model_ids import this PR removes, and it and legacy-code-integration.md tell readers to pull granite4.1:3b while the session default is granite4.2:3b. That page could do with its own pass.

planetf1 · 2026-10-28T09:52:43Z

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


The link resolves one directory too deep: from docs/examples/mify/, ../../docs/docs/... lands on docs/docs/docs/..., which doesn't exist. Dropping one docs/ segment fixes it and matches the form mcp/README.md and telemetry/README.md already use.

The concepts page covers fields_include and funcs_include but has nothing on stringify_func, query_type or template_order, which the old README's advanced section and mify.py both feature. That content lives in the legacy code integration example, so a second link covers it:

Suggested change

[MObjects and mify](../../docs/docs/concepts/mobjects-and-mify.md).

[MObjects and mify](../../docs/concepts/mobjects-and-mify.md) and

[Legacy Code Integration with @mify](../../docs/examples/legacy-code-integration.md).

planetf1 · 2026-10-28T09:52:43Z

+[MObjects and mify](../../docs/docs/concepts/mobjects-and-mify.md) and
+[Working with Data](../../docs/docs/how-to/working-with-data.md).


Same link-depth issue as the mify README, on both links:

Suggested change

[MObjects and mify](../../docs/docs/concepts/mobjects-and-mify.md) and

[Working with Data](../../docs/docs/how-to/working-with-data.md).

[MObjects and mify](../../docs/concepts/mobjects-and-mify.md) and

[Working with Data](../../docs/how-to/working-with-data.md).

Also, the old README pointed to notebooks/table_mobject.ipynb, which still exists and is the interactive version of this directory's only example. Dropping it is fine if deliberate, just confirming it was a choice; a one-line pointer would keep it discoverable.

I introduced a pointer to this link in the README table.

planetf1 · 2026-10-28T09:52:43Z

-This directory contains examples of implementing RAG systems with Mellea.
+Examples demonstrating Retrieval-Augmented Generation (RAG) patterns in Mellea.
+For a step-by-step guide to building a full pipeline, see the
+[Build a RAG Pipeline](../../docs/docs/how-to/build-a-rag-pipeline.md) how-to.


Same link-depth issue. This is the pointer a newcomer is most likely to follow, since the table rows assume the step-by-step guide:

Suggested change

[Build a RAG Pipeline](../../docs/docs/how-to/build-a-rag-pipeline.md) how-to.

[Build a RAG Pipeline](../../docs/how-to/build-a-rag-pipeline.md) how-to.

planetf1 · 2026-10-28T09:52:43Z

+| File | Description |
+| :--- | :--- |
+| [`simple_rag_with_filter.py`](./simple_rag_with_filter.py) | Two-stage pipeline: FAISS semantic search followed by a `@generative` relevance filter, then grounded answer generation with `grounding_context`. Requires `faiss-cpu` and `sentence-transformers`. |
+| [`mellea_pdf.py`](./mellea_pdf.py) | Loading a remote PDF into a `RichDocument` component and passing it as `grounding_context` for document-grounded question answering. |


Nit: the mellea_pdf.py row could say Requires docling like the mify rows, since the script's Prerequisites install it.

planetf1 · 2026-10-28T09:52:43Z

+Prerequisites:
+    ollama pull granite4.2:3b
+    ollama serve


The Prerequisites miss a hard dependency: line 18 imports TableQuery from mellea.stdlib.components.docs.richdocument, and that module raises ImportError on a base install (its message suggests pip install "mellea[docling]"). I checked by importing it with docling absent, and it fails before any mify code runs. uv sync --extra docling covers it, and the README row could say Requires docling like its siblings.

The ollama pull before ollama serve ordering is worth a tweak as well: pull needs the server up. Something like this covers the common setups, and would be worth applying across the other new blocks too:

Suggested change

Prerequisites:

ollama pull granite4.2:3b

ollama serve

Prerequisites:

uv sync --extra docling

Ollama running (service, desktop app, or `ollama serve`)

ollama pull granite4.2:3b

Fixed, but I kept the ollama serve command instead of the different options in the suggestion.

planetf1 · 2026-10-28T09:52:44Z

+    uv sync --extra backends
+    pip install docling


Same as the rich_table example: pip install docling lands outside the venv uv run uses, and the default Ollama backend means --extra backends isn't needed either:

Suggested change

uv sync --extra backends

pip install docling

uv sync --extra docling

planetf1 · 2026-10-28T09:52:44Z

+    uv sync --extra backends
+    pip install docling docling-core


This one does need --extra backends since it runs backend_name="hf", but the pip install line has the same venv problem as the other scripts. docling-core is also redundant in the list, since docling depends on it:

Suggested change

uv sync --extra backends

pip install docling docling-core

uv sync --extra backends --extra docling

Since this is the only HF-backend script in these directories, one line saying the model downloads on first run would also explain why there's no Ollama step.

Follow-up from validating the install commands by running this end to end: the script can't complete on Apple Silicon as written, regardless of install method. The layout model's position embedding is built in float64, which MPS doesn't support, and this example builds its own DocumentConverter, so it misses the CPU guard RichDocument gained in #1417 (that closed #1344 for the library paths; mellea_pdf.py runs fine through RichDocument). Root cause is upstream (huggingface/transformers#46159, tracked as docling-project/docling#3483); mellea's transformers>5.5.0,<6.0.0 override keeps 5.10.2, which still has it.

Adding the same guard here fixes it. I ran the patched script end to end on an M-series Mac and the full walkthrough completes:

from docling.datamodel.pipeline_options import ( AcceleratorDevice, AcceleratorOptions, PdfPipelineOptions, ) pipeline_options = PdfPipelineOptions(images_scale=2.0, generate_picture_images=True) pipeline_options.accelerator_options = AcceleratorOptions(device=AcceleratorDevice.CPU)

Happy for this to land here or as a tiny follow-up PR, whichever you prefer. If it goes in here, a one-line note in the description would cover it.

Included this patch in the script here.

planetf1 · 2026-10-28T09:52:44Z

+updating it with `m.transform()`.
+
+Prerequisites:
+    pip install pandas


The pandas prerequisite is right (pandas isn't a mellea dependency), but pip beside a uv run Usage line installs into a different environment than the one the script runs in. uv pip install pandas is the drop-in fix:

Suggested change

pip install pandas

uv pip install pandas

planetf1 · 2026-10-28T09:52:44Z

+Prerequisites:
+    ollama pull mistral:7b
+    ollama serve


The Prerequisites are right, but a reader who copies the uv run python ... pattern from the sibling examples gets ModuleNotFoundError: faiss, because this script's dependencies come from its PEP 723 header and only uv run (without python) resolves them. One sentence saves that trip:

Suggested change

Prerequisites:

ollama pull mistral:7b

ollama serve

Prerequisites:

ollama pull mistral:7b

ollama serve

faiss-cpu and sentence-transformers come from the PEP 723 header, so

`uv run` (without `python`) installs them automatically.

planetf1 · 2026-10-28T09:52:44Z

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


This is the only one of the four directories without a link to the site docs. The removed Basic Usage content lives in the Data Extraction Pipeline example, which also links back to 101_with_gen_stubs.py, so one link closes the loop:

Suggested change

Examples demonstrating structured information extraction from text using Mellea.

Examples demonstrating structured information extraction from text using Mellea.

For a walkthrough, see [Data Extraction Pipeline](../../docs/examples/data-extraction-pipeline.md).

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>

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

ed98bff

…ed-by: IBM Bob Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>

rafvasq requested a review from a team as a code owner October 26, 2026 20:00

rafvasq requested review from AngeloDanducci, markstur and planetf1 October 26, 2026 20:00

github-actions Bot added the documentation Improvements or additions to documentation label Oct 26, 2026

rafvasq mentioned this pull request Oct 27, 2026

docs(examples): Standardize structure and content across docs/examples/ #1746

Open

planetf1 reviewed Oct 28, 2026

View reviewed changes

Address review feedback and restore original wording

f07297d

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>

rafvasq requested a review from planetf1 October 28, 2026 20:09

	[MObjects and mify](../../docs/docs/concepts/mobjects-and-mify.md).
	[MObjects and mify](../../docs/concepts/mobjects-and-mify.md) and
	[Legacy Code Integration with @mify](../../docs/examples/legacy-code-integration.md).

		[MObjects and mify](../../docs/docs/concepts/mobjects-and-mify.md) and
		[Working with Data](../../docs/docs/how-to/working-with-data.md).

	[Build a RAG Pipeline](../../docs/docs/how-to/build-a-rag-pipeline.md) how-to.
	[Build a RAG Pipeline](../../docs/how-to/build-a-rag-pipeline.md) how-to.

	uv sync --extra backends
	pip install docling
	uv sync --extra docling

	uv sync --extra backends
	pip install docling docling-core
	uv sync --extra backends --extra docling

	Examples demonstrating structured information extraction from text using Mellea.
	Examples demonstrating structured information extraction from text using Mellea.
	For a walkthrough, see [Data Extraction Pipeline](../../docs/examples/data-extraction-pipeline.md).

Conversation

rafvasq commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

Issue

Description

Testing

Attribution

Adding a new component, requirement, sampling strategy, or tool?

Uh oh!

planetf1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rafvasq Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rafvasq commented Oct 26, 2026 •

edited

Loading

rafvasq Oct 28, 2026 •

edited

Loading