Add subtle see also graph behaviours

Author: adewale

docs/example-graph-score-impact.md

@@ -0,0 +1,32 @@
+# See also graph score impact
+
+The `see_also` implementation adds subtle graph behavior on top of the linear previous/next tour:
+
+- edge labels such as `contrast`, `prerequisite`, `alternative`, `builds on`, `shared mechanism`, and `next depth`
+- validation with `scripts/audit_example_graph.py --check`
+- lightweight recommendations on unknown `/examples/{slug}` pages
+- a graph-aware score component in `scripts/score_examples.py`
+
+The score comparison below uses the same loaded catalog and the graph-aware scorer. “Before” subtracts the new graph component; “After” includes it.
+
+| Cohort | Count | Before avg | After avg | Delta |
+|---|---:|---:|---:|---:|
+| All examples | 69 | 9.37 | 9.44 | +0.07 |
+| Examples with `see_also` | 17 | 9.31 | 9.61 | +0.30 |
+
+Lowest linked examples before/after:
+
+| Example | Before | After | Delta |
+|---|---:|---:|---:|
+| `import-aliases` | 8.56 | 8.86 | +0.30 |
+| `metaclasses` | 8.89 | 9.19 | +0.30 |
+| `async-iteration-and-context` | 9.08 | 9.38 | +0.30 |
+| `assignment-expressions` | 9.34 | 9.64 | +0.30 |
+| `break-and-continue` | 9.34 | 9.64 | +0.30 |
+| `loop-else` | 9.34 | 9.64 | +0.30 |
+| `positional-only-parameters` | 9.34 | 9.64 | +0.30 |
+| `inheritance-and-super` | 9.34 | 9.64 | +0.30 |
+| `exception-chaining` | 9.34 | 9.64 | +0.30 |
+| `exception-groups` | 9.34 | 9.64 | +0.30 |
+
+Interpretation: the graph does not make weak prose strong by itself. It gives a modest rubric gain where links clarify alternatives, prerequisites, or next-depth concepts. The main catalog average moves only slightly because most examples intentionally remain unlinked unless there is a meaningful conceptual edge.

public/site.css

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Audit see_also links as a lightweight example graph."""
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from src.examples import EXAMPLES  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--check", action="store_true", help="fail on invalid graph links")
+    parser.add_argument("--max-out-degree", type=int, default=4)
+    args = parser.parse_args()
+
+    slugs = {example["slug"] for example in EXAMPLES}
+    incoming: Counter[str] = Counter()
+    outgoing: dict[str, list[str]] = {}
+    errors: list[str] = []
+
+    for example in EXAMPLES:
+        slug = example["slug"]
+        links = list(example.get("see_also", []))
+        outgoing[slug] = links
+        if len(links) > args.max_out_degree:
+            errors.append(f"{slug}: too many see_also links ({len(links)} > {args.max_out_degree})")
+        if slug in links:
+            errors.append(f"{slug}: self-link")
+        for target in links:
+            if target not in slugs:
+                errors.append(f"{slug}: missing target {target}")
+            else:
+                incoming[target] += 1
+
+    linked = [slug for slug, links in outgoing.items() if links]
+    orphaned = sorted(slug for slug in slugs if not outgoing[slug] and incoming[slug] == 0)
+    high_in_degree = incoming.most_common(10)
+    reciprocal = []
+    for source, links in outgoing.items():
+        for target in links:
+            if source in outgoing.get(target, []):
+                reciprocal.append(tuple(sorted((source, target))))
+    reciprocal = sorted(set(reciprocal))
+
+    print(f"examples={len(EXAMPLES)}")
+    print(f"linked_sources={len(linked)}")
+    print(f"edges={sum(len(links) for links in outgoing.values())}")
+    print(f"orphaned={len(orphaned)}")
+    if orphaned:
+        print("orphaned_slugs=" + ", ".join(orphaned[:25]) + (" ..." if len(orphaned) > 25 else ""))
+    if high_in_degree:
+        print("top_in_degree=" + ", ".join(f"{slug}:{count}" for slug, count in high_in_degree))
+    if reciprocal:
+        print("reciprocal_edges=" + ", ".join(f"{a}<->{b}" for a, b in reciprocal[:20]))
+
+    if errors:
+        for error in errors:
+            print(error, file=sys.stderr)
+        return 1
+    return 0 if not args.check else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

public/site.dc51488c4ed9.css public/site.dfa9bd8042a1.csspublic/site.dc51488c4ed9.css renamed to public/site.dfa9bd8042a1.css

@@ -35,6 +35,7 @@ class Score:
     literate: float
     output: float
     navigation: float
+    graph: float
     layout: float
 
 
@@ -87,19 +88,21 @@ def score_python_example(example: dict) -> Score:
 
     output = 1.0 if example.get("expected_output") is not None and "white-space: pre-wrap" in PROJECT_SURFACE and "overflow-wrap: anywhere" in PROJECT_SURFACE else 0.4
     navigation = 1.0 if "rel=\"prev\"" in PROJECT_SURFACE and "rel=\"next\"" in PROJECT_SURFACE and "docs.python.org/3.13/" in example.get("doc_url", "") else 0.5
+    see_also = example.get("see_also", [])
+    graph = 0.3 if see_also and "see-also-label" in PROJECT_SURFACE else 0.0
     layout = 1.0
     if "class=\"pill\"" in PROJECT_SURFACE or "corner" in PROJECT_SURFACE or "border-radius: 999px; color: inherit" in PROJECT_SURFACE:
         layout -= 0.4
     if "nav a { color: inherit; text-decoration: underline" not in PROJECT_SURFACE:
         layout -= 0.2
-    total = round(max(0, payoff + deterministic + idiom + literate + output + navigation + layout), 2)
-    return Score(example["slug"], total, payoff, deterministic, idiom, literate, output, navigation, max(0, layout))
+    total = round(max(0, payoff + deterministic + idiom + literate + output + navigation + graph + layout), 2)
+    return Score(example["slug"], total, payoff, deterministic, idiom, literate, output, navigation, graph, max(0, layout))
 
 
 def score_external_literate_page(name: str, url: str, language_markers: tuple[str, ...], reference_label: str) -> Score:
     text = _fetch_text(url)
     if not text:
-        return Score(name, 0, 0, 0, 0, 0, 0, 0, 0)
+        return Score(name, 0, 0, 0, 0, 0, 0, 0, 0, 0)
     words = text.split()
     payoff = 1.8 if len(words) > 220 else 1.5
     deterministic = 1.1 if any(marker in text for marker in ["Run", "Playground", "$ go run", "go run"]) else 0.8
@@ -110,7 +113,7 @@ def score_external_literate_page(name: str, url: str, language_markers: tuple[st
     navigation = 0.8 if any(marker in text for marker in ["Next", "Previous", "Rust By Example", "Go by Example"]) else 0.4
     layout = 1.0
     total = round(payoff + deterministic + idiom + literate + output + navigation + layout, 2)
-    return Score(name, total, payoff, deterministic, idiom, literate, output, navigation, layout)
+    return Score(name, total, payoff, deterministic, idiom, literate, output, navigation, 0.0, layout)
 
 
 def score_gobyexample_page(slug: str) -> Score:
@@ -123,9 +126,9 @@ def score_rust_by_example_page(slug: str) -> Score:
 
 def print_table(title: str, scores: list[Score]) -> None:
     print(f"\n{title}")
-    print("name,total,payoff,deterministic,idiom,literate,output,navigation,layout")
+    print("name,total,payoff,deterministic,idiom,literate,output,navigation,graph,layout")
     for s in scores:
-        print(f"{s.name},{s.total:.2f},{s.payoff:.1f},{s.deterministic:.1f},{s.idiom:.1f},{s.literate:.1f},{s.output:.1f},{s.navigation:.1f},{s.layout:.1f}")
+        print(f"{s.name},{s.total:.2f},{s.payoff:.1f},{s.deterministic:.1f},{s.idiom:.1f},{s.literate:.1f},{s.output:.1f},{s.navigation:.1f},{s.graph:.1f},{s.layout:.1f}")
     print(f"average,{mean(s.total for s in scores):.2f}")
 
 

scripts/audit_example_graph.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import contextlib
+import difflib
 import html
 import io
 import json
@@ -29,6 +30,36 @@ def get_example(slug):
     return EXAMPLES_BY_SLUG.get(slug)
 
 
+def _example_index(slug):
+    for index, example in enumerate(EXAMPLES):
+        if example["slug"] == slug:
+            return index
+    return -1
+
+
+def _see_also_label(source_slug, target_slug):
+    explicit = SEE_ALSO_EDGE_LABELS.get((source_slug, target_slug))
+    if explicit:
+        return explicit
+    source = get_example(source_slug)
+    target = get_example(target_slug)
+    if source and target and source.get("section") == target.get("section"):
+        return "related"
+    source_index = _example_index(source_slug)
+    target_index = _example_index(target_slug)
+    if target_index >= 0 and source_index >= 0 and target_index < source_index:
+        return "prerequisite"
+    return "next depth"
+
+
+def _recommended_examples(slug, limit=4):
+    matches = difflib.get_close_matches(slug, [example["slug"] for example in EXAMPLES], n=limit, cutoff=0.2)
+    recommendations = [get_example(match) for match in matches]
+    if not recommendations:
+        recommendations = EXAMPLES[:limit]
+    return [example for example in recommendations if example is not None][:limit]
+
+
 def build_dynamic_worker_code(example_code: str) -> str:
     """Build a Python Dynamic Worker module that executes one example.
 
@@ -60,6 +91,21 @@ async def fetch(self, request):
 _TEMPLATE_CACHE = {}
 SITE_URL = "https://www.pythonbyexample.dev"
 
+SEE_ALSO_EDGE_LABELS = {
+    ("break-and-continue", "loop-else"): "contrast",
+    ("assignment-expressions", "conditionals"): "contrast",
+    ("yield-from", "generators"): "prerequisite",
+    ("async-iteration-and-context", "async-await"): "prerequisite",
+    ("delete-statements", "mutability"): "shared mechanism",
+    ("positional-only-parameters", "keyword-only-arguments"): "contrast",
+    ("assertions", "exceptions"): "alternative",
+    ("exception-chaining", "exceptions"): "builds on",
+    ("exception-groups", "exceptions"): "alternative",
+    ("operators-and-literals", "numbers"): "related syntax",
+    ("operators-and-literals", "strings"): "related syntax",
+    ("operators-and-literals", "sets"): "related syntax",
+}
+
 
 FAVICON_SVG = '''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Python By Example">
   <rect width="64" height="64" rx="14" fill="#F5F1EB"/>
@@ -305,7 +351,7 @@ def render_example_page(example, output=None, code=None, execution_time_ms=None)
     notes_html = "".join(f"<li>{note}</li>" for note in notes)
     see_also_examples = [get_example(slug) for slug in example.get("see_also", [])]
     see_also_links = "".join(
-        f'<li><a class="text-link" href="/examples/{html.escape(item["slug"])}">{html.escape(item["title"])}</a></li>'
+        f'<li><span class="see-also-label">{html.escape(_see_also_label(example["slug"], item["slug"]))}</span> <a class="text-link" href="/examples/{html.escape(item["slug"])}">{html.escape(item["title"])}</a></li>'
         for item in see_also_examples
         if item is not None
     )
@@ -364,7 +410,12 @@ def route(url: str, method: str = "GET") -> AppResponse:
         slug = path.split("/", 2)[2]
         example = get_example(slug)
         if example is None:
-            return AppResponse(_layout("Not Found", "<h1>Example not found</h1>"), status=404)
+            recommendations = "".join(
+                f'<li><a class="text-link" href="/examples/{html.escape(item["slug"])}">{html.escape(item["title"])}</a></li>'
+                for item in _recommended_examples(slug)
+            )
+            body = f'<h1>Example not found</h1><p class="meta">Try one of these nearby examples.</p><section class="see-also"><h2>Recommended examples</h2><ul>{recommendations}</ul></section>'
+            return AppResponse(_layout("Not Found", body), status=404)
         return AppResponse(
             render_example_page(example), headers={"Content-Type": "text/html; charset=utf-8"}
         )

scripts/score_examples.py

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
-ASSET_PATHS = {'SITE_CSS': '/site.dc51488c4ed9.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = '4f2e027de304'
+ASSET_PATHS = {'SITE_CSS': '/site.dfa9bd8042a1.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
+HTML_CACHE_VERSION = '37b3e0c8e92b'

src/app.py

@@ -195,7 +195,11 @@ def test_see_also_links_form_valid_example_graph(self):
                 self.assertTrue(set(example["see_also"]).issubset(slugs), set(example["see_also"]) - slugs)
         html = render_example_page(get_example("break-and-continue"))
         self.assertIn("See also", html)
+        self.assertIn("contrast", html)
         self.assertIn('/examples/loop-else', html)
+        missing = route("https://example.com/examples/break-continue")
+        self.assertEqual(missing.status, 404)
+        self.assertIn("Recommended examples", missing.body)
 
     def test_examples_are_in_learning_order_and_link_supported_python_docs(self):
         examples = list_examples()