Documenting models

Published

September 23, 2024

Use the developer framework to generate model documentation, view the results and refine your documentation in the platform UI, and collaborate with your team to complete documentation and validation projects within the same interface.

How do I use the ValidMind Developer Framework?

A typical high-level workflow for model developers consists of four major steps:

graph LR
    A[Develop<br>model] --> B[Generate model<br>documentation]
    B --> C[Refine model<br>documentation]
    C --> D[Submit for review]
    C --> B


1. Develop your model1

In your existing developer environment, build one or more candidate models that need to be validated. This step includes all the usual activities you already follow as a model developer.

1 No available model?
You can still run tests and log documentation with ValidMind as long as you’re able to load the model predictions.

2. Generate model documentation

With the ValidMind Developer Framework, generate automated model documentation and run validation tests. This step includes making use of the automation and testing functionality provided by the developer framework and uploading the output to the platform UI. You can iteratively regenerate the documentation as you work though the next step of refining your documentation.

3. Refine model documentation

In the ValidMind Platform UI, review the generated documentation and test output. Iterate over the documentation and test output to refine your model documentation. Collaborate with other developers and model validators to finalize the model documentation and get it ready for review.

4. Submit for review

In the ValidMind Platform UI, you submit the model documentation for review which moves the documentation workflow moves to the next phase where a model validator will review it.

Before you can use the ValidMind Developer Framework, you need to verify that the current documentation template contains all the necessary tests for the model you are developing:

  • The template might already be sufficient and you only need to run the template within the developer framework to populate documentation.
  • Or, more likely, the template might need additional tests that you can add these tests via the developer framework.

How do I generate documentation?

This process of verifying the suitability of the the current documentation template and adding more tests to the template is an iterative process:

graph LR
    A[Verify template] --> B[Build template]
    B --> D[Add tests and<br>content blocks]
    D --> E[Add external<br>test providers]
    E --> C[Run template]
    C --> B


Build the template

When the documentation template requires more tests to be added, or if the documentation template does not include a specific content or test block you need:

Run the template

When you have registered all the required tests as content blocks in the documentation template, populate the necessary model documentation by adding this call to your model:

run_documentation_tests()
ValidMind may not support all potential use cases or provide a universally applicable documentation template.

Typically, you initiate the process of putting ValidMind into production by constructing a template specific for your own use case and then refine your the documentation project.

What’s next