dlspit 2.2.0__tar.gz → 2.3.0__tar.gz

{dlspit-2.2.0 → dlspit-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dlspit
-Version: 2.2.0
+Version: 2.3.0
 Summary: A multi-domain experiment package: Deep Learning (MLP, CNN, ResNet, RNN, LSTM, Transformer, GAN, VAE), ML ESE Lab (regression, SVM, decision tree, random forest, XGBoost, k-means) Generative AI from scratch in NumPy (VAE, GAN, mini GPT, text-to-image, face swap, music, CycleGAN, chatbot, diffusion) and Explainable AI from scratch (SHAP, PDP, ICE, LIME, Grad-CAM, XRAI-style, Gradient x Input, LRP).
 Project-URL: Repository, https://github.com/PrathamShid07/DL_Expts
 Project-URL: Issues, https://github.com/PrathamShid07/DL_Expts/issues
@@ -43,7 +43,7 @@ Provides-Extra: xai
 Requires-Dist: matplotlib>=3.6; extra == 'xai'
 Description-Content-Type: text/markdown
 
-# dlspit v2.2.0 — Multi-Domain Experiment Package
+# dlspit v2.3.0 — Multi-Domain Experiment Package
 
 A pip-installable multi-domain experiment viewer and runner covering:
 
@@ -135,6 +135,52 @@ python -m dl_experiments ML-ESE --run random_forest
 
 ---
 
+## Read an experiment in Google Colab / Jupyter
+
+Install the package in a notebook and call one function. The cell output shows the experiment's **existing theory**
+followed by its **complete Python source code** (syntax-highlighted), exactly as stored in the package. Nothing is executed
+and nothing is rewritten: the theory is the module docstring of the experiment's `.py` file (GenAI, XAI) or its leading
+`# THEORY` comment block (DL, ML-ESE), and the code is the file itself.
+
+```python
+!pip install dlspit
+
+from dl_experiments import show_experiment
+
+show_experiment("genai", "chatbot")          # theory + full source of the chatbot experiment
+show_experiment("xai", "shap")               # domains: "genai", "xai", "dl", "ml-ese"
+show_experiment("dl", "4CNN")
+show_experiment("ml-ese", "decision_tree")
+```
+
+Useful options:
+
+```python
+show_experiment("xai", "grad-cam", code=False)     # theory only
+show_experiment("xai", "grad-cam", theory=False)   # code only
+show_experiment("genai", "vae", helpers=True)      # also the supporting modules it imports (e.g. the NumPy toolkit _nn.py)
+show_experiment("xai", "lrp", output="text")       # force plain text (default: HTML in a notebook, text in a terminal)
+```
+
+The valid names are listed by `dl_experiments.genai.list_experiments()`, `dl_experiments.xai.list_experiments()`,
+`dl_experiments.dl.list_experiments()` and `dl_experiments.ml_ese.list_experiments()`; the same aliases as the command line work
+(`"gradcam"`, `"text_to_image"`, ...). An invalid name raises an error that lists the valid ones.
+
+To get the text itself (for example to copy it into a journal, or to print it):
+
+```python
+from dl_experiments import get_theory, get_source
+
+print(get_theory("genai", "chatbot"))        # the explanation only
+print(get_source("genai", "chatbot"))        # the complete file
+```
+
+Syntax highlighting uses Pygments, which Colab and Jupyter already include (without it the code is shown as plain monospaced
+text); no extra package is required. To *run* an experiment instead of reading it, use `dlspit genai chatbot` or
+`from dl_experiments.genai.chatbot import run_experiment`.
+
+---
+
 ## DL Experiment Index
 
 | Key                  | Description                                         |

{dlspit-2.2.0 → dlspit-2.3.0}/README.md

@@ -1,4 +1,4 @@
-# dlspit v2.2.0 — Multi-Domain Experiment Package
+# dlspit v2.3.0 — Multi-Domain Experiment Package
 
 A pip-installable multi-domain experiment viewer and runner covering:
 
@@ -90,6 +90,52 @@ python -m dl_experiments ML-ESE --run random_forest
 
 ---
 
+## Read an experiment in Google Colab / Jupyter
+
+Install the package in a notebook and call one function. The cell output shows the experiment's **existing theory**
+followed by its **complete Python source code** (syntax-highlighted), exactly as stored in the package. Nothing is executed
+and nothing is rewritten: the theory is the module docstring of the experiment's `.py` file (GenAI, XAI) or its leading
+`# THEORY` comment block (DL, ML-ESE), and the code is the file itself.
+
+```python
+!pip install dlspit
+
+from dl_experiments import show_experiment
+
+show_experiment("genai", "chatbot")          # theory + full source of the chatbot experiment
+show_experiment("xai", "shap")               # domains: "genai", "xai", "dl", "ml-ese"
+show_experiment("dl", "4CNN")
+show_experiment("ml-ese", "decision_tree")
+```
+
+Useful options:
+
+```python
+show_experiment("xai", "grad-cam", code=False)     # theory only
+show_experiment("xai", "grad-cam", theory=False)   # code only
+show_experiment("genai", "vae", helpers=True)      # also the supporting modules it imports (e.g. the NumPy toolkit _nn.py)
+show_experiment("xai", "lrp", output="text")       # force plain text (default: HTML in a notebook, text in a terminal)
+```
+
+The valid names are listed by `dl_experiments.genai.list_experiments()`, `dl_experiments.xai.list_experiments()`,
+`dl_experiments.dl.list_experiments()` and `dl_experiments.ml_ese.list_experiments()`; the same aliases as the command line work
+(`"gradcam"`, `"text_to_image"`, ...). An invalid name raises an error that lists the valid ones.
+
+To get the text itself (for example to copy it into a journal, or to print it):
+
+```python
+from dl_experiments import get_theory, get_source
+
+print(get_theory("genai", "chatbot"))        # the explanation only
+print(get_source("genai", "chatbot"))        # the complete file
+```
+
+Syntax highlighting uses Pygments, which Colab and Jupyter already include (without it the code is shown as plain monospaced
+text); no extra package is required. To *run* an experiment instead of reading it, use `dlspit genai chatbot` or
+`from dl_experiments.genai.chatbot import run_experiment`.
+
+---
+
 ## DL Experiment Index
 
 | Key                  | Description                                         |

{dlspit-2.2.0 → dlspit-2.3.0}/dl_experiments/__init__.py

@@ -1,5 +1,5 @@
 """
-dl_experiments v2.2.0
+dl_experiments v2.3.0
 =====================
 A pip-installable multi-domain experiment package covering:
 
@@ -37,6 +37,12 @@ Quick start
     dlspit DL --list            # show DL experiments
     dlspit ML-ESE --list        # show ML-ESE experiments
 
+Notebook / Colab: read the theory and the full code of any experiment
+--------------------------------------------------------------------
+    from dl_experiments import show_experiment
+    show_experiment("genai", "chatbot")     # theory, then the complete Python source (highlighted)
+    show_experiment("xai", "shap")          # also "dl" and "ml-ese"; nothing is executed
+
 Python API
 ----------
     from dl_experiments.dl import list_experiments, show_source, run_experiment
@@ -74,7 +80,7 @@ ML-ESE Experiment keys
     kmeans_clustering  K-Means Clustering — customer segmentation
 """
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 __author__  = "Pratham"
 
 from .dl.registry import (
@@ -99,6 +105,8 @@ from .xai.registry import (
     show_source      as xai_show_source,
 )
 
+from .display import get_source, get_theory, show_experiment
+
 __all__ = [
     "__version__",
     "__author__",
@@ -114,4 +122,7 @@ __all__ = [
     "xai_list_experiments",
     "xai_run_experiment",
     "xai_show_source",
+    "show_experiment",
+    "get_theory",
+    "get_source",
 ]

{dlspit-2.2.0 → dlspit-2.3.0}/dl_experiments/__main__.py

@@ -116,7 +116,7 @@ def cli() -> None:
     parser = argparse.ArgumentParser(
         prog="dlspit",
         description=(
-            "dlspit v2.2.0 — Multi-Domain Experiment Viewer & Runner\n\n"
+            "dlspit v2.3.0 — Multi-Domain Experiment Viewer & Runner\n\n"
             "Domains:\n"
             "  DL      Deep Learning (MLP, CNN, ResNet, RNN, LSTM, GAN, VAE …)\n"
             "  ML-ESE  Machine Learning ESE Lab (regression, SVM, trees, clustering …)\n"

dlspit-2.3.0/dl_experiments/display.py

@@ -0,0 +1,229 @@
+"""
+Show an experiment's THEORY and its complete SOURCE CODE - in Google Colab, Jupyter, or a terminal.
+
+    from dl_experiments import show_experiment
+
+    show_experiment("genai", "chatbot")      # theory, then the full Python source, highlighted
+    show_experiment("xai", "shap")
+    show_experiment("dl", "4CNN")
+    show_experiment("ml-ese", "decision_tree")
+
+Nothing is written or generated here: the text comes from the experiment's own ``.py`` file
+- the module docstring for GenAI / XAI, the leading ``# THEORY`` comment block for DL / ML-ESE -
+and the code is the file itself, character for character.  The experiment is NOT imported or
+executed (the file is only read and parsed), so showing it is instant and has no side effects.
+
+In a notebook the output is syntax-highlighted HTML (Pygments, which Jupyter and Colab already
+include; without it the code is shown as plain monospaced text).  Elsewhere it is printed as text.
+
+Public API
+----------
+    show_experiment(domain, name, theory=True, code=True, helpers=False, output="auto")
+    get_theory(domain, name)               -> str   (the explanation text)
+    get_source(domain, name, helpers=...)  -> str   (the file, or the file + supporting modules)
+"""
+
+import ast
+import html as _html
+import re
+from pathlib import Path
+
+_DOMAIN_ALIASES = {
+    "genai": "genai", "gen-ai": "genai", "gen_ai": "genai", "generative": "genai",
+    "xai": "xai", "explainable": "xai",
+    "dl": "dl", "deep": "dl",
+    "ml-ese": "ml-ese", "ml_ese": "ml-ese", "mlese": "ml-ese", "ml": "ml-ese",
+}
+DOMAINS = ("genai", "xai", "dl", "ml-ese")
+
+
+# ── Locating an experiment ───────────────────────────────────────────────────
+
+def _resolve(domain, name):
+    """Return (canonical domain, canonical key, Path of the experiment's .py file)."""
+    canonical = _DOMAIN_ALIASES.get(str(domain).strip().lower())
+    if canonical is None:
+        raise ValueError(f"Invalid domain: {domain!r}. Valid domains: {', '.join(DOMAINS)}.")
+    if canonical == "genai":
+        from .genai import registry
+    elif canonical == "xai":
+        from .xai import registry
+    elif canonical == "dl":
+        from .dl import registry
+    else:
+        from .ml_ese import registry
+
+    if canonical in ("genai", "xai"):
+        key = registry.normalize_key(name)                     # accepts aliases such as "gradcam" or "text_to_image"
+        return canonical, key, registry.source_path(key)
+    files = registry._SOURCE_FILES                              # DL / ML-ESE registries keep a key -> file table
+    matches = [k for k in files if k.lower() == str(name).strip().lower()]
+    if not matches:
+        raise registry._invalid_key_error(str(name))
+    return canonical, matches[0], (registry._EXPERIMENTS_DIR / files[matches[0]]).resolve()
+
+
+# ── Extracting the existing theory ───────────────────────────────────────────
+
+def _leading_comment_block(source):
+    """Theory of DL / ML-ESE files: the first block of consecutive '#' lines (banner lines of '=' dropped)."""
+    block, started = [], False
+    for line in source.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            started = True
+            text = stripped[1:]
+            text = text[1:] if text.startswith(" ") else text
+            if not re.fullmatch(r"=+", text.strip()):
+                block.append(text.rstrip())
+        elif started:
+            break
+    return "\n".join(block).strip()
+
+
+def _theory_from_source(source):
+    docstring = ast.get_docstring(ast.parse(source), clean=True)
+    return docstring if docstring else _leading_comment_block(source)
+
+
+def _title_from_theory(theory, key):
+    """First non-empty line: the docstring's title line, or the 'EXPERIMENT n: ...' line of a comment block."""
+    return next((line.strip() for line in theory.splitlines() if line.strip()), key)
+
+
+def get_theory(domain, name):
+    """The existing theory / explanation text of an experiment (module docstring or leading comment block)."""
+    _, _, path = _resolve(domain, name)
+    return _theory_from_source(path.read_text(encoding="utf-8"))
+
+
+# ── Extracting the code (optionally with the modules it depends on) ──────────
+
+def _local_imports(path):
+    """Files of this package that ``path`` imports with relative imports (``from ._nn import ...``)."""
+    found = []
+    for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
+        if isinstance(node, ast.ImportFrom) and node.level > 0:
+            base = path.parent
+            for _ in range(node.level - 1):
+                base = base.parent
+            parts = node.module.split(".") if node.module else []
+            targets = [parts] if parts else [[alias.name] for alias in node.names]      # "from . import _plot"
+            for target in targets:
+                candidate = base.joinpath(*target).with_suffix(".py")
+                if candidate.is_file() and candidate.name not in ("registry.py", "__init__.py"):
+                    found.append(candidate.resolve())
+    return found
+
+
+def _supporting_files(path):
+    """Every supporting module the experiment needs, in the order they are first imported (no duplicates)."""
+    ordered, queue = [], _local_imports(path)
+    while queue:
+        current = queue.pop(0)
+        if current != path and current not in ordered:
+            ordered.append(current)
+            queue.extend(_local_imports(current))
+    return ordered
+
+
+def _code_files(domain, name, helpers):
+    _, _, path = _resolve(domain, name)
+    return [path] + (_supporting_files(path) if helpers else [])
+
+
+def get_source(domain, name, helpers=False):
+    """The experiment's source file, exactly as stored in the package.
+
+    helpers=True appends the supporting modules it imports (for example the NumPy neural-network
+    toolkit ``_nn.py``), each preceded by a comment line naming the file.
+    """
+    files = _code_files(domain, name, helpers)
+    parts = [files[0].read_text(encoding="utf-8")]
+    for extra in files[1:]:
+        parts.append(f"# {'=' * 70}\n# Supporting module: {extra.name}\n# {'=' * 70}\n" + extra.read_text(encoding="utf-8"))
+    return "\n\n".join(parts)
+
+
+# ── Rendering ────────────────────────────────────────────────────────────────
+
+_BOX = ("background:#f6f8fa;color:#24292f;padding:10px 14px;border:1px solid #d0d7de;border-radius:6px;"
+        "overflow:auto;font-size:13px;line-height:1.45;")
+
+
+def _highlight_html(code):
+    """Syntax-highlighted HTML with inline styles (no CSS dependencies); plain <pre> without Pygments."""
+    try:
+        from pygments import highlight
+        from pygments.formatters import HtmlFormatter
+        from pygments.lexers import PythonLexer
+        return highlight(code, PythonLexer(), HtmlFormatter(noclasses=True, style="default", cssstyles=_BOX))
+    except ImportError:
+        return f'<pre style="{_BOX}">{_html.escape(code)}</pre>'
+
+
+def _build_html(title, theory, code_files, show_theory, show_code):
+    out = [f'<div style="font-family:system-ui,sans-serif"><h2 style="margin-bottom:4px">{_html.escape(title)}</h2>']
+    if show_theory:
+        out.append('<h3>Theory and Underlying Concepts</h3>'
+                   f'<pre style="{_BOX}white-space:pre-wrap">{_html.escape(theory)}</pre>')
+    if show_code:
+        out.append("<h3>Python Implementation</h3>")
+        for path, source in code_files:
+            out.append(f'<div style="margin:6px 0 2px;color:#57606a;font-size:12px">{_html.escape(path.name)}</div>'
+                       + _highlight_html(source))
+    out.append("</div>")
+    return "".join(out)
+
+
+def _display_html(markup):
+    """Send HTML to the notebook front-end (separate function so tests can intercept it)."""
+    from IPython.display import HTML, display
+    display(HTML(markup))
+
+
+def _in_notebook():
+    """True inside Jupyter, Colab or VS Code notebooks (an IPython kernel), False in a terminal / script."""
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return False
+    shell = get_ipython()
+    return shell is not None and hasattr(shell, "kernel")
+
+
+def show_experiment(domain, name, theory=True, code=True, helpers=False, output="auto"):
+    """Display an experiment's existing theory and its complete source code.  Nothing is executed.
+
+    Parameters
+    ----------
+    domain  : "genai", "xai", "dl" or "ml-ese"
+    name    : experiment key, e.g. "chatbot", "shap", "grad-cam", "4CNN", "decision_tree"
+              (``dl_experiments.genai.list_experiments()`` etc. list the valid names)
+    theory  : show the "Theory and Underlying Concepts" section
+    code    : show the "Python Implementation" section
+    helpers : also show the supporting modules the experiment imports (e.g. the ``_nn.py`` toolkit)
+    output  : "auto" (HTML in a notebook, text elsewhere), "html" or "text"
+    """
+    if not theory and not code:
+        raise ValueError("Nothing to show: at least one of theory / code must be True.")
+    if output not in ("auto", "html", "text"):
+        raise ValueError("output must be 'auto', 'html' or 'text'.")
+    _, key, path = _resolve(domain, name)
+    files = _code_files(domain, name, helpers)
+    sources = [(f, f.read_text(encoding="utf-8")) for f in files]
+    theory_text = _theory_from_source(sources[0][1])
+    title = _title_from_theory(theory_text, key)
+
+    use_html = output == "html" or (output == "auto" and _in_notebook())
+    if use_html:
+        _display_html(_build_html(title, theory_text, sources, theory, code))
+        return None
+    bar = "=" * 72
+    print(f"{bar}\n{title}\n{bar}")
+    if theory:
+        print(f"\n--- Theory and Underlying Concepts {'-' * 38}\n\n{theory_text}\n")
+    if code:
+        for f, source in sources:
+            print(f"\n--- Python Implementation: {f.name} {'-' * max(3, 46 - len(f.name))}\n\n{source.rstrip()}\n")
+    return None

{dlspit-2.2.0 → dlspit-2.3.0}/dl_experiments/genai/registry.py

@@ -90,6 +90,11 @@ def run_experiment(key, **options):
     return function(**options)
 
 
+def source_path(key):
+    """Path of the .py file that implements ``key`` (used by ``dl_experiments.show_experiment``)."""
+    return (_EXPERIMENTS_DIR / f"{_EXPERIMENTS[normalize_key(key)][1]}.py").resolve()
+
+
 def show_source(key):
     """Print the source file of an experiment (the code is not executed)."""
     key = normalize_key(key)

{dlspit-2.2.0 → dlspit-2.3.0}/dl_experiments/xai/registry.py

@@ -88,6 +88,11 @@ def run_experiment(key, **options):
     return function(**options)
 
 
+def source_path(key):
+    """Path of the .py file that implements ``key`` (used by ``dl_experiments.show_experiment``)."""
+    return (_EXPERIMENTS_DIR / f"{_EXPERIMENTS[normalize_key(key)][1]}.py").resolve()
+
+
 def show_source(key):
     """Print the source file of an experiment (the code is not executed)."""
     key = normalize_key(key)

{dlspit-2.2.0 → dlspit-2.3.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 # ── Project metadata ────────────────────────────────────────────────────────
 [project]
 name            = "dlspit"    # UNIQUE name on PyPI
-version         = "2.2.0"
+version         = "2.3.0"
 description     = "A multi-domain experiment package: Deep Learning (MLP, CNN, ResNet, RNN, LSTM, Transformer, GAN, VAE), ML ESE Lab (regression, SVM, decision tree, random forest, XGBoost, k-means) Generative AI from scratch in NumPy (VAE, GAN, mini GPT, text-to-image, face swap, music, CycleGAN, chatbot, diffusion) and Explainable AI from scratch (SHAP, PDP, ICE, LIME, Grad-CAM, XRAI-style, Gradient x Input, LRP)."
 readme          = "README.md"
 license         = { text = "MIT" }

dlspit-2.3.0/tests/test_display.py

@@ -0,0 +1,245 @@
+"""Tests for ``show_experiment`` / ``get_theory`` / ``get_source`` (theory + code display for notebooks)."""
+
+import ast
+import html
+import importlib.util
+import re
+import subprocess
+import sys
+import types
+
+import pytest
+
+import dl_experiments
+from conftest import subprocess_env
+from dl_experiments import display, get_source, get_theory, show_experiment
+from dl_experiments.dl import registry as dl_registry
+from dl_experiments.genai import registry as genai_registry
+from dl_experiments.ml_ese import registry as ml_registry
+from dl_experiments.xai import registry as xai_registry
+
+ALL = ([("genai", k, genai_registry.source_path(k)) for k in genai_registry.list_experiments()]
+       + [("xai", k, xai_registry.source_path(k)) for k in xai_registry.list_experiments()]
+       + [("dl", k, dl_registry._EXPERIMENTS_DIR / f) for k, f in dl_registry._SOURCE_FILES.items()]
+       + [("ml-ese", k, ml_registry._EXPERIMENTS_DIR / f) for k, f in ml_registry._SOURCE_FILES.items()])
+has_pygments = importlib.util.find_spec("pygments") is not None
+
+
+def strip_markup(markup):
+    """Visible text of an HTML fragment (tags removed, entities decoded)."""
+    return html.unescape(re.sub(r"<[^>]+>", "", markup))
+
+
+@pytest.fixture
+def captured(monkeypatch):
+    """Intercept what would be sent to the notebook front-end."""
+    shown = []
+    monkeypatch.setattr(display, "_display_html", shown.append)
+    return shown
+
+
+# ── theory extraction ────────────────────────────────────────────────────────
+
+def test_every_experiment_has_theory_and_source():
+    assert len(ALL) == 9 + 10 + 13 + 8
+    for domain, key, path in ALL:
+        assert get_theory(domain, key).strip(), (domain, key)
+        assert get_source(domain, key) == path.read_text(encoding="utf-8"), (domain, key)     # verbatim file content
+
+
+@pytest.mark.parametrize("domain,key,path", [a for a in ALL if a[0] in ("genai", "xai")])
+def test_genai_and_xai_theory_is_the_module_docstring(domain, key, path):
+    assert get_theory(domain, key) == ast.get_docstring(ast.parse(path.read_text(encoding="utf-8")), clean=True)
+
+
+def test_dl_and_mlese_theory_is_the_leading_comment_block():
+    text = get_theory("dl", "4CNN")
+    assert text.startswith("EXPERIMENT 4: Convolutional Neural Network (CNN) on MNIST") and "THEORY:" in text
+    assert "=====" not in text and not text.startswith("#")                       # banner and '# ' prefixes removed
+    assert "Decision Tree" in get_theory("ml-ese", "decision_tree").splitlines()[0]
+
+
+def test_theory_text_is_the_real_existing_explanation():
+    chatbot = get_theory("genai", "chatbot")
+    assert "this is NOT a generative LLM" in chatbot and "bag-of-words" in chatbot
+    shap = get_theory("xai", "shap")
+    assert "phi_i" in shap and "Limitations" in shap and "background" in shap
+    assert get_theory("xai", "lrp") == get_theory("XAI", "LRP")                    # domain / name are case-insensitive
+
+
+@pytest.mark.parametrize("domain,name,expected_file", [("GenAI", "text_to_image", "text_to_image.py"), ("xai", "gradcam", "grad_cam.py"),
+                                                       ("xai", "7", "grad_cam.py"), ("genai", "jukebox", "music_generation.py"),
+                                                       ("DL", "4cnn", "exp4_cnn.py"), ("ml_ese", "SVM_Classifier", "svm_classifier.py")])
+def test_aliases_resolve_to_the_right_file(domain, name, expected_file):
+    assert display._resolve(domain, name)[2].name == expected_file
+
+
+# ── invalid input ────────────────────────────────────────────────────────────
+
+def test_invalid_domain_and_experiment_names():
+    with pytest.raises(ValueError, match="Invalid domain"):
+        show_experiment("nlp", "bert")
+    with pytest.raises(ValueError, match="Did you mean"):
+        show_experiment("xai", "shapp")
+    with pytest.raises(ValueError, match="Invalid XAI"):
+        get_theory("xai", "vae")                                                  # a GenAI name is not an XAI name
+    with pytest.raises(ValueError, match="Invalid experiment key"):
+        get_source("dl", "99Nothing")
+    with pytest.raises(ValueError, match="Invalid experiment key"):
+        get_theory("ml-ese", "unknown_model")
+
+
+def test_invalid_options():
+    with pytest.raises(ValueError, match="at least one"):
+        show_experiment("xai", "pdp", theory=False, code=False)
+    with pytest.raises(ValueError, match="output"):
+        show_experiment("xai", "pdp", output="pdf")
+
+
+# ── text output (terminal / script) ──────────────────────────────────────────
+
+def test_text_output_has_title_then_theory_then_the_complete_source(capsys):
+    show_experiment("genai", "diffusion", output="text")
+    out = capsys.readouterr().out
+    source = get_source("genai", "diffusion")
+    theory = get_theory("genai", "diffusion")
+    assert out.index("Theory and Underlying Concepts") < out.index("Python Implementation")
+    assert theory in out and source.rstrip() in out                               # the complete file, unchanged
+    assert out.startswith("=" * 72 + "\nGenAI Experiment 9 - Denoising Diffusion")
+
+
+def test_theory_only_and_code_only(capsys):
+    show_experiment("xai", "ice", code=False, output="text")
+    only_theory = capsys.readouterr().out
+    assert "Theory and Underlying Concepts" in only_theory and "Python Implementation" not in only_theory
+    assert "def calculate_ice" not in only_theory
+    show_experiment("xai", "ice", theory=False, output="text")
+    only_code = capsys.readouterr().out
+    assert "def calculate_ice" in only_code and "Theory and Underlying Concepts" not in only_code
+
+
+def test_auto_mode_prints_text_outside_a_notebook(capsys, captured):
+    assert show_experiment("xai", "lime") is None                                  # returns nothing (no double display)
+    assert "Python Implementation" in capsys.readouterr().out and captured == []
+
+
+def test_works_without_ipython_and_pygments_installed():
+    code = ("import sys\nsys.modules['IPython'] = None\nsys.modules['pygments'] = None\n"
+            "from dl_experiments import show_experiment\n"
+            "show_experiment('xai', 'pdp', output='text')\n"
+            "import dl_experiments.display as d\nd._display_html = lambda m: print('HTML-LEN', len(m), '<pre' in m)\n"
+            "show_experiment('xai', 'pdp', output='html')\n")
+    r = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, env=subprocess_env(), timeout=60)
+    assert r.returncode == 0, r.stderr
+    assert "def calculate_pdp" in r.stdout and "HTML-LEN" in r.stdout and "True" in r.stdout        # plain <pre> fallback
+
+
+# ── HTML output (notebook / Colab) ───────────────────────────────────────────
+
+def test_html_output_contains_title_theory_and_the_unchanged_source(captured):
+    show_experiment("xai", "shap", output="html")
+    assert len(captured) == 1
+    markup = captured[0]
+    visible = strip_markup(markup)
+    assert "Theory and Underlying Concepts" in markup and "Python Implementation" in markup
+    assert markup.index("Theory and Underlying Concepts") < markup.index("Python Implementation")
+    assert get_theory("xai", "shap") in visible                                    # theory shown unchanged
+    assert get_source("xai", "shap").rstrip("\n") in visible                       # the source, character for character
+    assert "<h2" in markup and "XAI Experiment 3" in visible
+
+
+@pytest.mark.skipif(not has_pygments, reason="pygments not installed")
+def test_html_code_is_syntax_highlighted_with_inline_styles(captured):
+    show_experiment("genai", "gan", output="html")
+    markup = captured[0]
+    assert re.search(r'<span style="[^"]*font-weight: bold[^"]*">def</span>', markup)          # keyword styled
+    assert re.search(r'<span style="[^"]*font-style: italic[^"]*"># ', markup)                  # comment styled
+    assert "<style" not in markup and "<link" not in markup and "<script" not in markup         # inline styles only
+    assert display._highlight_html("x = 1 < 2\n").count("&lt;") == 1
+
+
+def test_html_is_escaped_so_code_cannot_break_the_page(captured):
+    show_experiment("genai", "vae", output="html")                                 # source contains '<', '>' and '&' characters
+    markup = captured[0]
+    assert "<script" not in markup.lower()
+    assert "&lt;" in markup or "&gt;" in markup
+    assert strip_markup(markup).count("def ") >= get_source("genai", "vae").count("def ")
+
+
+def test_html_shows_only_what_was_requested(captured):
+    show_experiment("dl", "4CNN", code=False, output="html")
+    assert "Theory and Underlying Concepts" in captured[0] and "Python Implementation" not in captured[0]
+    show_experiment("dl", "4CNN", theory=False, output="html")
+    assert "Python Implementation" in captured[1] and "Theory and Underlying Concepts" not in captured[1]
+
+
+def test_notebook_is_detected_and_ipython_display_is_used(monkeypatch):
+    shown = []
+    ipython = types.ModuleType("IPython")
+    ipython.get_ipython = lambda: types.SimpleNamespace(kernel=object())          # what Jupyter / Colab provide
+    display_mod = types.ModuleType("IPython.display")
+    display_mod.HTML = lambda markup: ("HTML", markup)
+    display_mod.display = shown.append
+    monkeypatch.setitem(sys.modules, "IPython", ipython)
+    monkeypatch.setitem(sys.modules, "IPython.display", display_mod)
+    assert display._in_notebook() is True
+    show_experiment("xai", "regression")                                           # output="auto" -> HTML in a notebook
+    assert len(shown) == 1 and shown[0][0] == "HTML" and "Theory and Underlying Concepts" in shown[0][1]
+    ipython.get_ipython = lambda: types.SimpleNamespace()                          # a terminal IPython has no kernel
+    assert display._in_notebook() is False
+
+
+# ── helpers (supporting modules) ─────────────────────────────────────────────
+
+def test_supporting_modules_are_optional_and_resolved_from_the_real_imports():
+    plain = get_source("xai", "ice")
+    with_helpers = get_source("xai", "ice", helpers=True)
+    assert with_helpers.startswith(plain) and len(with_helpers) > len(plain)
+    names = re.findall(r"# Supporting module: (\S+)", with_helpers)
+    assert names[:1] == ["_nn.py"] and {"_common.py", "pdp.py"} <= set(names) and len(names) == len(set(names))
+    assert "Supporting module" not in plain and "class Dense" not in plain and "class Dense" in with_helpers
+    assert "run_experiment" in with_helpers and with_helpers.count("def calculate_pdp") == 1
+
+
+def test_helpers_for_experiments_without_dependencies(capsys):
+    assert get_source("dl", "4CNN", helpers=True) == get_source("dl", "4CNN")      # DL files import nothing local
+    show_experiment("genai", "vae", theory=False, helpers=True, output="text")
+    out = capsys.readouterr().out
+    assert "Python Implementation: vae.py" in out and "Python Implementation: _nn.py" in out and "Python Implementation: _viz.py" in out
+
+
+# ── showing an experiment never runs it ──────────────────────────────────────
+
+def test_showing_does_not_import_or_execute_the_experiment():
+    code = ("import sys, time\nfrom dl_experiments import show_experiment\n"
+            "t = time.time()\n"
+            "for d, n in (('genai','diffusion'), ('genai','cyclegan'), ('xai','grad-cam'), ('xai','lrp')):\n"
+            "    show_experiment(d, n, output='text')\n"
+            "bad = [m for m in ('dl_experiments.genai.diffusion','dl_experiments.genai.cyclegan','dl_experiments.xai.grad_cam','dl_experiments.xai.lrp') if m in sys.modules]\n"
+            "print('IMPORTED:', bad, 'SECONDS<2:', time.time() - t < 2)\n")
+    r = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, env=subprocess_env(), timeout=60)
+    assert r.returncode == 0, r.stderr
+    assert "IMPORTED: [] SECONDS<2: True" in r.stdout
+    assert "Chamfer distance to real data: 0." not in r.stdout                      # no experiment output appeared
+
+
+def test_public_names_are_exported():
+    for name in ("show_experiment", "get_theory", "get_source"):
+        assert name in dl_experiments.__all__ and callable(getattr(dl_experiments, name))
+
+
+# ── a real Jupyter kernel (only when nbclient + ipykernel are installed) ─────
+
+@pytest.mark.skipif(any(importlib.util.find_spec(m) is None for m in ("nbclient", "nbformat", "ipykernel")),
+                    reason="needs nbclient, nbformat and ipykernel")
+def test_real_notebook_cell_renders_theory_and_code_as_html(tmp_path):
+    import nbformat
+    from nbclient import NotebookClient
+    nb = nbformat.v4.new_notebook(cells=[nbformat.v4.new_code_cell(
+        "from dl_experiments import show_experiment\nshow_experiment('genai', 'chatbot')")])
+    NotebookClient(nb, timeout=120, kernel_name="python3", resources={"metadata": {"path": str(tmp_path)}}).execute()
+    outputs = nb.cells[0].outputs
+    assert len(outputs) == 1 and outputs[0].output_type == "display_data" and "text/html" in outputs[0].data
+    visible = strip_markup(outputs[0].data["text/html"])
+    assert "Theory and Underlying Concepts" in visible and get_source("genai", "chatbot").rstrip("\n") in visible
+    assert "text/plain" in outputs[0].data