[SC-15520] Expose qualitative text agent to vm library

[juanmleng]

Pull Request Description

What and why?

Implemented programmatic qualitative text generation in the ValidMind library so documentation text blocks can be generated and logged directly from Python instead of only through the UI. This adds support for single-block generation with vm.run_text_generation(), prompt customization, section-specific context, appending new text blocks to a section, and config-driven multi-block generation with vm.generate_documentation_text().

Before this change, users had to write text manually or trigger AI generation section by section in the UI. After this change, they can generate qualitative documentation in code alongside their quantitative test workflow, with notebook progress updates and a grouped summary of generated content.

How to test

• Run pytest tests/test_api_client.py tests/test_client.py tests/test_results.py.
• Open notebooks/how_to/qualitative_text/qualitative_text_generation.ipynb and run the notebook end to end against a model with the Binary classification template applied.
• Verify that vm.run_text_generation() works for a single text block with default behavior, with a custom prompt, and with section-specific context.
• Verify that generated text can be logged back to the document, including appending a new text block to a section.
• Verify that vm.generate_documentation_text(config=text_config) populates the configured qualitative sections, shows progress updates during execution, and renders the grouped notebook summary by top-level section.

What needs special review?

• Public API naming, especially vm.run_text_generation() and vm.generate_documentation_text(), to confirm the names are clear and consistent with the rest of the library.
• The decision to pass content_id and section_id as primary inputs to the generation call, rather than only at .log() time. This is intentional for text generation because both are placement inputs that also affect generation behavior: content_id identifies the block being generated, and section_id can influence the applied guidelines for new content.
• Notebook documentation content in notebooks/how_to/qualitative_text/qualitative_text_generation.ipynb, including whether the examples, wording, and level of detail are appropriate.
• Notebook placement and naming, to confirm notebooks/how_to/qualitative_text/qualitative_text_generation.ipynb is the right location and that the notebook title/name best matches how we want to present this feature.

Dependencies, breaking changes, and deployment notes

https://github.com/validmind/frontend/pull/2390
https://github.com/validmind/backend/pull/2925

Release notes

Added support for programmatic AI generation of qualitative documentation text through the ValidMind library. Users can now generate and log text for individual documentation blocks, customize output with prompts, control generation context with selected document content, append new text blocks to a section, and populate multiple qualitative sections directly from notebooks with a config-driven workflow.

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]

Pull requests must include at least one of the required labels: internal (no release notes required), 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 at least one of the required labels: internal (no release notes required), 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 at least one of the required labels: internal (no release notes required), 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 at least one of the required labels: internal (no release notes required), highlight, enhancement, bug, deprecation, documentation. Except for internal, pull requests must also include a description in the release notes section.

[johnwalz97]

this is sick!

[AnilSorathiya]

This is nice!

[cachafla]

Amazing!

[cachafla]

Can you bump to 2.13.0 before merging?

[github-actions]

PR Summary

This PR introduces major enhancements to the ValidMind library by adding and improving the qualitative text generation functionality. Key improvements include:

• A new notebook for demonstrating how to generate qualitative documentation content using functions like vm.run_text_generation() and vm.generate_documentation_text(). The notebook provides an end-to-end example that integrates test results with AI-generated qualitative text for populating model documentation.

• Updates to versioning (bumping from 2.12.5 to 2.13.0) accompany the new features. This update is reflected in both the Python package metadata and the R DESCRIPTION file.

• Enhancements to the API client to support additional parameters (e.g., section_id) for logging text metadata. This allows for appending text blocks to specific sections if the content does not already exist.

• New tests have been added and existing tests modified to validate the new behavior. These include unit tests to:

  • Ensure that log_text correctly handles the new section_id parameter.
  • Validate that context objects for AI text generation meet the required schema.
  • Confirm that both synchronous and asynchronous logging work as expected with proper error handling for unsupported parameter combinations.

• Code refactoring in areas such as the API client, client module, and template helper functions to support these changes. Enhancements in HTML rendering for progress bars and text summaries have also been incorporated to better integrate with the UI components provided by ValidMind.

Overall, these updates streamline the workflow for generating and logging qualitative text blocks while ensuring robust testing and improved error handling.

Test Suggestions

• Add tests to verify that providing mismatched parameters (such as both 'text' and 'prompt') in log_text raises the expected ValueError.
• Create new unit tests to simulate a scenario where a new content block is generated without a section_id to ensure the proper exception is raised.
• Test the end-to-end workflow in the notebook to simulate generating, logging, and rendering qualitative text output.
• Run integration tests to confirm that the updated API endpoints (including section_id handling) work with mocked API responses.
• Add tests to validate that the context object passed to text generation is correctly sanitized and validated.