Add optional model doc slug field

[mdeyell-valid-mind]

Pull Request Description

What and why?

We need to allow users to specify which document they want to interact with.
I updated the existing notebooks to specify a document slug.

https://app.shortcut.com/validmind/story/14764/update-library-to-include-model-document-slug-field

How to test

I ran this locally and verified that X-DOCUMENT-TYPE is received and processed by the backend.

To test full integration, this backend pr needs to be checked out https://github.com/validmind/backend/pull/2677
along with this frontend pr https://github.com/validmind/frontend/pull/2222

What needs special review?

Dependencies, breaking changes, and deployment notes

Release notes

init() now supports an optional document parameter that is used to specify which document we would like to connect the library to. In a future release, this field will become required.

The document parameter is determined by the url
model-inventory/cmkel544f00ef8mk318l3j533/documents/new-validation-report/overview
For instance in this url, the document parameter is new-documentation-report

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)

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cachafla]

@mdeyell-valid-mind there are some "ghost" changes on some notebooks?

[mdeyell-valid-mind]

@mdeyell-valid-mind there are some "ghost" changes on some notebooks?

I had to run make copyright in order for the linter to pass

[cachafla]

Plan of action recommended

• We need a deprecation notice when a user does not pass a model_document argument. It should be added to this PR or a follow up, but we shouldn't release a new PyPI version without this
  • Existing notebooks should be updated to pass either documentation, validation-report or monitoring (we have a variety of use case)
  • Outdated notebooks, a.k.a notebooks that customers are already using should see the deprecation notice when they upgrade to the latest version of validmind
  • ⚠️ if a user sees this notice they will want to know how to do it properly, the UI change below is a necessary follow-on
  • I suggest coordinating the deprecation documentation with @nrichers and @validbeck
• I suggest a minor version increase for this change
• Test that you can create a random doc for a doc type such as code-analysis and you can log results for it

Post-merge

• We need a change in the UI to the Getting Started screen that gives you the snippet. It needs be document aware now, i.e. allow you to pick a document to populate the model_document argument in the snippet
• We can deprecate the legacy behavior on the API when we can confirm all customers have updated their notebooks (relatively easy to confirm)

Additional context: after all of this is done, there is another major task we'll work on:

• Ability to omit model_document if desired. A user will be able to send results for a model but not assign them to a document just yet.

[cachafla]

Looking good!

For the deprecation message I'd tag @validbeck @nrichers for suggestions:

2026-02-20 15:47:09,780 - ERROR(validmind.api_client): Not providing `model_document` to `vm.init()` is deprecated and will become required in a future release.

@mdeyell-valid-mind doing some tests, I'm unable to send data for custom docs.

I'm sending:

model_document="my-custom-doc",

For a new doc I created. The library sees:

APIRequestError: User does not have permission to access document 'my-custom-doc'.

The backend prints:

has_permission: False 
required_permission: update_dt_my-custom-doc
user_model_roles: [Role:ABC Banking:Model Owner, Role:ABC Banking:Model Developer]

Then, I looked into the role permissions and saw this:

Permission:ABC Banking:Model Owner:read_dt_cybersecurity-assessment,
 Permission:ABC Banking:Model Owner:update_dt_cybersecurity-assessment,

Ok, this makes perfect sense:

• The user has write permissions over cybersecurity-assessment docs

However, note that document slugs != document type slugs. It's possible that a user can create more than one document for type (slug) documentation. When this is the case we create unique slugs for every new doc and this is automatically handled by the UI:

What this means is that the library is doing things correctly, but the backend should retrieve the document type for the given document slug, and then check if the role permissions exists for that document type.

In my case the single document slug is my-custom-doc but it is a document of type cyber security assessment:

[mdeyell-valid-mind]

the backend should retrieve the document type for the given document slug, and then check if the role permissions exists for that document type.

Good point, i will update the backend on monday

[cachafla]

@mdeyell-valid-mind late request: I realized that we should rename the parameter to document instead of model_document. As we continue working on the AI governance roadmap (and introduce primary records as a general container of documents) we can't assume that all records are Models.

[mdeyell-valid-mind]

Got it, I will update the library and frontend

…

On Feb 23, 2026, at 08:54, Andres Rodriguez ***@***.***> wrote: cachafla left a comment (validmind/validmind-library#479) <#479 (comment)> @mdeyell-valid-mind <https://github.com/mdeyell-valid-mind> late request: I realized that we should rename the parameter to document instead of model_document. As we continue working on the AI governance roadmap (and introduce primary records as a general container of documents) we can't assume that all records are Models. — Reply to this email directly, view it on GitHub <#479 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BRP3CIEJMSYECVP6ZIEJM634NMWFZAVCNFSM6AAAAACVOXFGVCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSNBVHE4TCOJZGI>. You are receiving this because you were mentioned.

[github-actions]

PR Summary

This PR augments the ValidMind codebase by introducing a new, optional parameter named document across numerous notebooks, integration tests, and the core API client. The primary purpose of this change is to allow users to specify the documentation type (e.g., documentation, monitoring, or validation-report) when initializing the ValidMind Library.

Key changes include:

• In various notebooks (e.g., quickstart, tutorials, and use cases) the vm.init(...) call is now updated to include the document parameter. For instance, many notebooks now pass document="documentation" or document="monitoring" in order to tag the resulting output under the correct document category.

• In the API client (in the file validmind/api_client.py), a new global variable _document is added. The helper function _get_api_headers() now appends an X-DOCUMENT-TYPE header if a value for _document is provided.

• The init function in the API client is updated to accept the new document parameter. If the parameter is not provided, a warning is logged via logger.error, indicating that future releases will require it.

• Additional unit tests in tests/test_api_client.py validate that the appropriate header is set when document is provided and that a warning is logged when it is missing.

Overall, these changes aim to make the documentation type more explicit and configurable, improving flexibility and future compatibility with upcoming releases of the ValidMind Library.

Test Suggestions

• Run the new tests in tests/test_api_client.py to confirm that a warning is logged when document is not provided.
• Execute the notebooks to verify that passing document in vm.init() correctly sets the header (check network requests or logs).
• Perform integration tests simulating both scenarios (with and without the document parameter) and check that the header X-DOCUMENT-TYPE is present or absent accordingly.

[cachafla]

Great 👍