Add more contextual information to Jupyter notebooks

[nrichers]

Internal Notes for Reviewers

This PR makes a number of improvements to our most visible notebooks to make them easier to consume and more standalone:

• Title edits
  • Start notebooks about running tests with similar action words
  • Use sentence-style casing as per our style guide
  • Edit titles for consistency and to fix minor issues, e.g. remove : at the end of a title
  • Rename some files to match titles
• Intro edits
  • Start with consistent short descriptions <250 chars
  • Include longer intro with more contextual info
  • Where available, include “This interactive notebook ...” summary
  • Apply terminology fixes, e.g. clarify "test" vs "metric"
• New table of contents
  • Add generated table of contents that works in Jupyter Hub, VS Code, and docs site
    (Uses the Jupyter TOC VS Code extension, Apache 2.0 license)
• Reworked "About ValidMind" section
  • Combine existing elevator pitch & CTA to sign up
  • Add new "Key concepts" subsection
• Next steps improvements
  • Better pointer to working with model documentation in the Platform UI
  • New links to more learning resources

Output examples

A version of these edits is already live, as they were required for the reworked developer framework getting started:

• https://docs.validmind.ai/guide/get-started-developer-framework.html
• https://docs.validmind.ai/guide/testing-overview.html
• https://docs.validmind.ai/guide/samples-jupyter-notebooks.html

New notebook structure

An example that shows the improved intro, new table of concepts, "About ValidMind" section with key concepts, and next steps that point to more learning resources.

How notebooks appear in our developer docs

An example of why consistent short descriptions matter:

Fine print, read carefully

• Not all code samples have been edited to include the new standard sections (e.g. table of contents, conceptual info, etc.)
• No notebooks in notebooks/code_sharing/ have been edited
• The generated table of contents currently require a fix to some anchors to work in consistently in Jupyter Hub/VS Code/docs site
• The signup CTA callout never rendered correctly in Jupyter Hub — I have a fix that changes the callou to <div class="alert alert-block alert-info">CTA</div> but haven't applied the changes yet

External Release Notes

Many of our Jupyter notebooks have received improvements to make them easier to consume and more standalone:

• Introductions now include more contextual information
• A new table of contents makes notebooks easier to navigate
• Key concepts are explained in the context where you might need that information
• Next steps make it easier to find additional learning resources

[cachafla]

Looks great 👏. I left a small comment: the "how to run a test" notebook has been replaced by a new one.

[validbeck]

• Thank you for explaining the embedded vs sidebar ToC to me!
• I like the new more imperative titles, very clear and simple
• The new intro / CTAs are great too!
• For the individual notebooks I just left suggestions in them. :)

Weirdness

notebooks/code_samples/nlp_and_llm/foundation_models_integration_demo.ipynb

• For some reason it wouldn't let me leave comments or suggestions on lines 20-300ish.
• I wanted to add the exclamation mark at the end of "Sign up now"

notebooks/code_samples/nlp_and_llm/foundation_models_summarization_demo.ipynb

• Same here as above, huh.

notebooks/code_samples/nlp_and_llm/hugging_face_integration_demo.ipynb

• ... and here...

notebooks/code_samples/nlp_and_llm/hugging_face_summarization_demo.ipynb

• ... aaaaand here...

notebooks/code_samples/nlp_and_llm/llm_summarization_demo.ipynb

• ... nth verse, same as the 1st...
• Can't change the better way to an m-dash either, but that's just a style quibble of mine.

notebooks/code_samples/quickstart_customer_churn_full_suite.ipynb

• Just the better-way m-dash for this notebook

notebooks/code_samples/regression/quickstart_regression_full_suite.ipynb

• Both the signup! and the better way-- here

notebooks/code_samples/time_series/tutorial_time_series_forecasting.ipynb

• Wanted to adjust the "ValidMind is a platform for [...]" here, couldn't
• Wanted to adjust the "Get started with the ValidMind Developer Framework" blurb, couldn't
• Wanted to adjust the "Sign up now," couldn't
• Wanted to adjust the "better way," couldn't...

notebooks/code_sharing/llm/foundation_models_summarization_high_code.ipynb

• Exact same as above, ehehehe...
• Except I notice there isn't a CTA to review the results in the UI... is this on purpose?

notebooks/how_to/configure_dataset_features.ipynb

• Couldn't adjust the "Sign up now"
• Couldn't adjust the "better way"

notebooks/how_to/configure_test_parameters.ipynb

• Couldn't adjust the "better way"

notebooks/how_to/load_datasets_predictions.ipynb

• Wanted to adjust the "ValidMind is a platform for [...]" here, couldn't
• Wanted to adjust the "Get started with the ValidMind Developer Framework" blurb, couldn't
• Wanted to adjust the "Sign up now," couldn't
• Wanted to adjust the "better way," couldn't...

notebooks/how_to/run_a_test.ipynb

• Looks like this notebook will be replaced?

notebooks/how_to/run_unit_metrics.ipynb

• Couldn't adjust the "better way" here

I'm sure I missed something... either way, just minor formatting/semantic quibbles! Looking much better. :)

[nrichers]

notebooks/code_sharing/llm/foundation_models_summarization_high_code.ipynb

• Exact same as above, ehehehe...
• Except I notice there isn't a CTA to review the results in the UI... is this on purpose?

@validbeck anything in code_sharing is outside the scope of what we include in our docs site or publish on Jupyter Hub. These are notebooks that are in varying states of completion.

[validbeck]

anything in code_sharing is outside the scope of what we include in our docs site or publish on Jupyter Hub. These are notebooks that are in varying states of completion.

Oh right, yes, I totally forgot that (didn't realise what folder that was in). All good!

[github-actions]

Pull requests must include at least one of the required labels: internal, highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[github-actions]

Pull requests must include a description in the release notes section.

[nrichers]

@cachafla I might need your help with the make ensure-clean-notebooks CI check failure. I get the same when running the check locally, but only the very last failure seems notebook related, except I can't tell which file this is referring to.

❯ make ensure-clean-notebooks
poetry run python scripts/ensure_clean_notebooks.py
Traceback (most recent call last):
  File "/Users/nrichers/Library/Caches/pypoetry/virtualenvs/validmind-Tie81wAs-py3.9/lib/python3.9/site-packages/nbformat/reader.py", line 20, in parse_json
    nb_dict = json.loads(s, **kwargs)
  File "/opt/homebrew/anaconda3/lib/python3.9/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
  File "/opt/homebrew/anaconda3/lib/python3.9/json/decoder.py", line 337, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
  File "/opt/homebrew/anaconda3/lib/python3.9/json/decoder.py", line 353, in raw_decode
    obj, end = self.scan_once(s, idx)
json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 417 column 3 (char 21189)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/nrichers/GitHub/validmind/developer-framework/scripts/ensure_clean_notebooks.py", line 72, in <module>
    notebook_error = check_notebook(
  File "/Users/nrichers/GitHub/validmind/developer-framework/scripts/ensure_clean_notebooks.py", line 30, in check_notebook
    nb = nbformat.read(f, as_version=nbformat.NO_CONVERT)
  File "/Users/nrichers/Library/Caches/pypoetry/virtualenvs/validmind-Tie81wAs-py3.9/lib/python3.9/site-packages/nbformat/__init__.py", line 171, in read
    return reads(buf, as_version, capture_validation_error, **kwargs)
  File "/Users/nrichers/Library/Caches/pypoetry/virtualenvs/validmind-Tie81wAs-py3.9/lib/python3.9/site-packages/nbformat/__init__.py", line 89, in reads
    nb = reader.reads(s, **kwargs)
  File "/Users/nrichers/Library/Caches/pypoetry/virtualenvs/validmind-Tie81wAs-py3.9/lib/python3.9/site-packages/nbformat/reader.py", line 73, in reads
    nb_dict = parse_json(s, **kwargs)
  File "/Users/nrichers/Library/Caches/pypoetry/virtualenvs/validmind-Tie81wAs-py3.9/lib/python3.9/site-packages/nbformat/reader.py", line 23, in parse_json
    raise NotJSONError(("Notebook does not appear to be JSON: %r" % s)[:77] + "...") from e
nbformat.reader.NotJSONError: Notebook does not appear to be JSON: '{\n  "cells": [\n    {\n      "cell_typ...
make: *** [ensure-clean-notebooks] Error 1