notebooks: Update templates & notebooks with 'document' parameter in vm.init()

[validbeck]

Pull Request Description

What and why?

sc-15077

It's now required in ValidMind Library versions >=2.12.0 that a document is selected when copying your code snippet in the ValidMind Platform. Notebooks and notebook templating updated to reflect this functionality:

Notebook templating

The templates in notebooks/templates have been updated to reflect the new UX, and the handy templating script updated with role-based / document-type aware mini-template insertion. Previously, the template generator used single, one-size-fits-all mini-templates for "about", "install", and "next steps" sections. Now, the content varies depending on the selected role and document type (Development, Validation, or Monitoring).

Role / document type selection flow (e2e_template.py)

• Added two new interactive selection functions:
  • select_document() — Prompts the user to pick a role/document type (Developer/Development, Validator/Validation, Developer/Monitoring) and stores it in a module-level _selected_document variable.
  • select_install() — Prompts the user to choose between "Installation Only" or "Both Install & Initialize", stored in _selected_install.

These selections drive which mini-template notebooks get appended downstream.

Mini-templates reorganized into subdirectories

The previously flat mini-template files have been moved into organized subdirectories, with role-specific variants added:

Section	Old (single file)	New (per-role subdirectory)
About	_about-validmind.ipynb	about-validmind/_about-validmind-developers.ipynb (renamed), _about-validmind-validators.ipynb (new)
Install	_install-initialize-validmind.ipynb	install-validmind/_install-initialize-with-development.ipynb (renamed), _install-initialize-with-validation.ipynb (new), _install-initialize-with-monitoring.ipynb (new), _install-only.ipynb (new)
Next Steps	_next-steps.ipynb	next-steps/_next-steps-development.ipynb (renamed), _next-steps-validation.ipynb (new), _next-steps-monitoring.ipynb (new)

Refactored append logic

• Extracted a shared _append_notebook(filepath, relative_path) helper to avoid duplicated notebook-appending code across add_about, add_install, and next_steps.
• add_about(), add_install(), and next_steps() now look up the correct mini-template based on the stored _selected_document and _selected_install values instead of hardcoding a single file.

Updated notebooks/templates/e2e-notebook.ipynb

• Added new cells for tm.select_document() and tm.select_install() in the interactive notebook workflow.
• Updated documentation to describe the new role-based template selection options with links to each variant.
• Added table of contents entry for "Set a role / document type".

Updated notebooks/templates/README.md

• References to the old flat mini-template files replaced with references to the new subdirectories (about-validmind/, install-validmind/, next-steps/).

Updated notebooks

Large-scale content update across ~60+ existing notebooks to standardize initialization instructions, terminology, and formatting

Standardized notebook content across the entire repo

The bulk of the changes (60+ notebooks across quickstart/, tutorials/, how_to/, use_cases/, and code_sharing/) apply consistent updates to the "install and initialize" boilerplate sections:

• Terminology update: "Documentation" → "Development" in the platform UI references (e.g., "click Documents and select Development" instead of "select Documentation").
• Revised code snippet instructions: Changed from a two-step instruction to a three-step instruction that now includes selecting the specific document type from a drop-down menu (e.g., "select Development from the DOCUMENT drop-down menu").
• Updated vm.init() code blocks: Replaced hardcoded placeholder credentials (api_host="https://api.prod.validmind.ai/...", api_key="...") with commented-out placeholders (# api_host="...", # api_key="..."), making it clearer these are meant to be filled in via .env files.
• Revised introductory text for the code snippet: Consolidated from two sentences into a single, more concise description explaining how the snippet connects test results to the right model and document.
• Template preview section: Moved the "template predefines sections..." explanation from the "Apply template" step to the "Preview template" step for better flow.
• Monitoring notebooks specifically: Updated "documentation template" → "monitoring report template", "model monitoring documentation" → "model monitoring report", corrected the template name to "Ongoing Monitoring for Classification Models", and added vm.preview_template() calls where missing.
• Next steps / wrap-up sections: Minor wording and formatting improvements to the "Work with your documentation/validation report" sections.

How to test

Spot check changed notebooks

Pick some notebooks included the diff to confirm that the new templating instructions reflect the new UX changes outlined in the detailed changelog above.

Run the notebook templating script

To test pull down this PR: gh pr checkout 486

Then run the notebook:

1. Open notebooks/templates/e2e-notebook.ipynb.
2. Run the notebook.
3. When prompted, select a role / document type and confirm that the generation gives you the correct versions for that selection.
4. Run the notebook again for the other 2 roles / try out some different selection options.

Or call the script that the notebook runs on:

1. In your terminal call: make notebook
2. When prompted, select a role / document type and confirm that the generation gives you the correct versions for that selection.
3. Run the command again for the other 2 roles / try out some different selection options.

What needs special review?

Important

Some vm.init() examples already had the document key inserted but commented out, which isn't correct as far as I understand — it needs to be included explicitly in the init call as it has no fallback in api_client.py:

validmind-library/validmind/api_client.py

Line 35 in ef050c0

_document = None

Someone should confirm that this is the case though, since the docs also tell you to include this explicitly instead of in the .env file. 😅

Dependencies, breaking changes, and deployment notes

Follow up to validmind/documentation#1211.

Note

Changes to notebooks will be pulled into the documentation side on the next release publication.

Release notes

Covered in #479.

Checklist

• What and why
• Screenshots or videos (Frontend)
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut
• Unit tests added (Backend)
• Tested locally
• Documentation updated (if required)
• Environment variable additions/changes documented (if required)

[github-actions]

PR Summary

This PR makes extensive updates across multiple Jupyter notebooks to improve the clarity, consistency, and user guidance in the ValidMind notebooks. The primary changes include:

• Updating textual instructions and UI labels by replacing references to Documentation with more specific terms such as Development, Validation, or Monitoring, depending on the context of the notebook.
• Adjusting prompts and code snippet guidance to instruct users to select the appropriate document type (e.g., when initializing the library, the guidance now instructs users to choose from a role/document type drop-down).
• Enhancing description text for previewing templates, making it clear that the preview function (vm.preview_template()) displays a pre-defined structured template for the corresponding use-case.
• Minor changes in markdown cell IDs and metadata have been made to ensure proper linking within the notebooks.

Overall, these updates aim to create a more uniform and intuitive user experience in setting up and documenting models with ValidMind, ensuring that the instructions match the latest UI terminology and workflow changes on the ValidMind Platform.

Test Suggestions

• Manually verify that all instances of 'Documentation' in instructional text are correctly updated to 'Development', 'Validation', or 'Monitoring' as appropriate.
• Run a diff or snapshot test on the rendered notebook output to ensure the new text and links are correct.
• Perform integration tests by loading the notebooks in a Jupyter environment and verifying that navigation links (TOCs) work with the new IDs.
• Check that the updated installation and initialization code cells execute correctly without errors.

[mdeyell-valid-mind]

Some vm.init() examples already had the document key inserted but commented out, which isn't correct as far as I understand — it needs to be included explicitly in the init call as it has no fallback in api_client.py:

When vm.init() is called without a document the backend uses the old (bad) behavior where it infers which document to connect to. At this time, we aren't blocking calls without a document specified. That being said, we should have all of our example code specify a document.

[mdeyell-valid-mind]

Some vm.init() examples already had the document key inserted but commented out, which isn't correct as far as I understand — it needs to be included explicitly in the init call as it has no fallback in api_client.py:

When vm.init() is called without a document the backend uses the old (bad) behavior where it infers which document to connect to. At this time, we aren't blocking calls without a document specified. That being said, we should have all of our example code specify a document.

At risk of oversharing this is the code that ends up getting hit when we don't have a document specified
https://github.com/validmind/backend/blob/main/src/backend/auth/auth.py#L1035-L1107

[validbeck]

When vm.init() is called without a document the backend uses the old (bad) behavior where it infers which document to connect to. At this time, we aren't blocking calls without a document specified. That being said, we should have all of our example code specify a document.

Awesome, that's how the notebooks are currently after my edit. Can you approve? 🙏🏻