Improve and align tutorials

[yairallouche]

Summary

Improve the quality, consistency, and completeness of the tutorials directory.

Tasks

David review comments

• Verify that all links work properly (some README links were broken after the tutorial renaming) (Alon)
• Rename adapter → adapter function where it makes sense (Yair).
• Rename pipeline → add_conversation_turn (Yair).
• Rename bring your own adapter → build your own adapter (Yair).
• Update hello Mellea to run on T4 GPUs - fix comment (Ofer)
• Validate rag 101 tutorial from the main branch on T4 (Yair).
• Validate full rag tutorial from the main branch on T4 (Ofer).
• Validate full rag tutorial from the main branch on A100 (Yair).
• Validate HF tutorials from the main branch on T4 (Alon).

1. Clean up tutorial 02 (RAG pipeline)

• Fix broken import path (govt_data_loader vs scripts/govt_data_loader)
• Fix threshold inconsistency between show_intermediates (0.4) and run_pipeline (0.5)
• Remove unused ANSWERABILITY_THRESHOLD constant
• Consolidate scattered imports
• Refactor large function cell into smaller, focused cells
• Add explanatory comments for non-obvious design choices (TOP_K, temperature, pipeline ordering)
• Improve govt_data_loader.py error handling and progress feedback
• Add diagram showing the 7-step pipeline flow, including the three exit points (blocked, unanswerable, needs clarification)

2. Align format across all tutorials

• Convert the hello-adapter to a notebook
• Standardize heading hierarchy (H1 title, H2 numbered sections)
• Standardize template (intro -> prerequisite -> content -> next steps )
• Add time estimates and prerequisites links to all tutorials
• Add "Next Steps" sections linking to related tutorials
• Consolidate imports in notebooks (not scattered across cells)
• Replace ANSI color codes with display(Markdown()) in notebook 01
• Use Rich Markdown rendering for the printing method (see RAG tutorial)
• Add "What you will learn" to each notebook
• Improve prose clarity across all tutorials
• Validate clear text in all notebooks
• Add missing context if needed (e.g., aLoRA vs LoRA explanation, attribution instruction context)
• Provide a one-line explanation on each adapter before usage
• Validate all links

3. Consider adding new tutorials

• Evaluate a simpler RAG tutorial (inline docs, no vector DB) as a stepping stone
• Evaluate a complex RAG tutorial with loop between answerability rewriting

[noaakl]

1. Notebooks

• Make sure that LoRA vs LoRA Race matches the Notebook Template.
• Organize and clean up the Next Steps section.

2. RAG

• Move all imports to the top of the file.
• Move the show script into utils.
• Add the following sentence:
  “The benchmark uses the government-services corpus from IBM mt-rag-benchmark as its retrieval dataset.”
• merge the vector DB init with Luis scripts in LoRA vs aLoRA
• address David's comment about the conversation class
• Add the missing actual query rewrite step in 5b; then consider renaming the current 5b to 5c.
• Review whether ModelOption.TEMPERATURE: 0.0 is needed in the mfuncs.act(...) call, or whether temperature should rely on the setting already defined in io.yaml.

3. Colab

• Verify that everything runs properly on Google Colab (similar to LoRA vs LoRA Race).
• Check how many documents are returned in RAG and limit it to 5 so it can run smoothly, while ensuring performance is not affected.

4. README

• Add Google Colab links to the notebooks table in the README.
• Update the following sentence:
  “The HuggingFace examples demonstrate how adapters are activated via control tokens. While this is helpful for understanding the underlying mechanics, for actual inference you should use Mellea (Path 2), which provides constrained decoding, prompt formatting, and proper input/output processing.”
• Add links to the scripts.

5. General

• Remove the Quickstart section.
• Rename 04_alora_vs_lora_race.ipynb to 05_alora_vs_lora_race.ipynb
• Verify that all links are correct and up to date.
• Remove the compose script from the notebooks and add a reference to the compose notebook instead.
• Align duration

[yairallouche]

--- Read me (Yair)

• Unify the current readme to 3 paths:

1. Inference with Mellea (recommended)
2. Real-World Pipelines (usability)
3. Bring Your Own Adapter (+ HF low level notebook + Mellea based new adapter)

--- RAG Document Structure

• Replace/add simpler "RAG 101" tutorial first: just corpus building plus a basic answerability check (Noaa)
• Remove Conversation class and use Mellea components (Noaa)
• Verify there is no misbehavior (Noaa)
• Fix Next Steps (Noaa)

---Issues
------- Minor (Yair)

• Rename "Government Services RAG Pipeline" to something like "Sample RAG Pipeline"; mention the corpus as an inline note rather than headlining it
• Change the "Launched … on :8000" message to say "launching" first, then confirm once it's up
• Make the mermaid diagram render at cell run time, not pre-rendered
• Globally replace the "Why vLLM: the mellea intrinsics API currently supports vLLM only" comment with: "Why vLLM: much faster inference in production environments; HF support for Granite Switch in mellea coming."

------ Major

• Verify that everything runs properly on Google Colab on T4 (Bar)
• Check how many documents are returned in RAG and limit it to 5 so it can run smoothly, while ensuring performance is not affected. (Ofer)
• Filter out irrelevant documents from vector DB (assuring no change in the notebook flow) (Ofer)
• Revise examples Q1–Q5: Q2 should trigger clarification, Q3 should actually perform query rewrite; report any adapter misbehavior (Noaa)
• Enable running scripts on the same runtime (Bar)
• Simplift HF scripts (Alon)
• Rewrite the "next steps" section since answerability and clarification are already in this notebook (Noaa)

---- Mellea

• Fix the BYOA doc in tutorials/guides/bring_your_own_adapter.md: remove the "Mellea only supports official IBM Granite Library adapters" claim (Yair)
• Confirm with Jake Lorocco that custom adapters with a proper io.yaml do work through Mellea's lower-level interface (Yair)
• Add a tutorial showing how to make a custom adapter work in Mellea, including how to write the io.yaml (Yair)

-- Enhancement

• Follow up with Paul Schwartz on whether a voice agent tutorial can fit into a notebook environment (Yair)

[barvhaim]

@yairallouche

For "Enable running scripts on the same runtime":
Google Colab handles architecture differently under the hood. When you open a notebook, Google assigns you a completely isolated, ephemeral virtual machine (VM) in the cloud.

If you open two separate Colab tabs with different notebooks:

• Tab 1 gets VM Alpha (with its own RAM, CPU/GPU, and local disk space).
• Tab 2 gets VM Beta (with a completely separate pool of RAM, CPU/GPU, and local disk space).

Because they are literally running on separate computers in Google's data centers, Notebook B cannot "see" or attach itself to the kernel running in Notebook A.

Suggested practice:
Share data using user's Google Drive.

However, when you use Google Drive as your cache layer, every file you save, whether it's raw text, model checkpoints, or a ChromaDB index, directly consumes storage space from your personal Google Drive quota (which is capped at 15 GB on the free tier)

Code samples:
pre-reqs-notebook

import os
import chromadb
from google.colab import drive

drive.mount('/content/drive')
DB_PATH = "/content/drive/MyDrive/my_chroma_cache"

client = chromadb.PersistentClient(path=DB_PATH)
collection = client.get_or_create_collection(name="my_collection")

# CRITICAL FOR FREE TIER: Check if data is already there
if collection.count() > 0:
    print(f"🎯 Found {collection.count()} vectors. Skipping indexing!")
else:
    print("🚀 Cache miss. Processing data and building index...")
    # ... your embedding/indexing code here ...

runner-notebook

# Cell 1: Mount Drive
from google.colab import drive
drive.mount('/content/drive')

# Cell 2: Run Notebook 1 (Downloads data & builds ChromaDB cache on Drive)
%run "/content/drive/MyDrive/Colab_Project/01_Index_Data.ipynb"

# Cell 3: Run Notebook 2 (Loads the cached ChromaDB from Drive and tests queries)
%run "/content/drive/MyDrive/Colab_Project/02_Evaluate_Search.ipynb"

# Cell 4: Run Notebook 3 (Passes context to your LLM / Agent loop)
%run "/content/drive/MyDrive/Colab_Project/03_Agent_Pipeline.ipynb"

P.S, When your notebooks live on GitHub, using the %run command requires a slightly different approach. You cannot directly %run a URL pointing to GitHub, because the %run magic command expects a local file path on the machine's hard drive.

To make %run work seamlessly with GitHub hosted notebooks, you just need to pull the files from GitHub onto Colab's temporary local drive first.

For example:

import os

# 1. Clone your GitHub repository into the local Colab space
REPO_NAME = "your-repo-name"
REPO_URL = f"https://github.com/your-github-username/{REPO_NAME}.git"

if not os.path.exists(f'/content/{REPO_NAME}'):
    !git clone {REPO_URL}

# 2. Mount Google Drive so the notebooks can still read/write the ChromaDB cache
from google.colab import drive
drive.mount('/content/drive')

# 3. Use %run pointing to the locally cloned files
%run "/content/{REPO_NAME}/01_Index_Data.ipynb"
%run "/content/{REPO_NAME}/02_Evaluate_Search.ipynb"

[lastras]

It's unclear that just returning 5 documents would show query clarification meaningfully - note that it triggers whenever it detects ambiguity which is in turn dependent on different interpretations given by different retrieved options.