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

[juanmleng]

Pull Request Description

What and why?

How to test

What needs special review?

Dependencies, breaking changes, and deployment notes

Release notes

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]

PR Summary

This pull request introduces significant functional improvements for the qualitative text generation and logging capabilities in the ValidMind library. The changes include:

1. A new Jupyter notebook that demonstrates how to generate qualitative documentation content using the ValidMind API. The notebook guides users through installing the library, initializing the environment, training a sample model, and logging both manually provided and AI-generated text with different prompts and contexts.

2. Enhancements in the API client and client modules:

   • Improved handling of text logging through the introduction of functions that validate inputs and manage normalization from Markdown to HTML when necessary.
   • New support for asynchronous logging (alog_text) alongside synchronous methods. This ensures that text generation and logging operations can be performed reliably in async contexts.
   • Introduction of robust validation for the log_text function to prevent conflict between manually provided text and prompt/context arguments. Specifically, errors are raised if incompatible combinations are detected (e.g., providing both text and a prompt).
   • New utility functions such as get_content_ids and changes in template processing to better extract and order content IDs from documentation templates.
   • Updates to unit tests in several test files (e.g., test_api_client.py, test_client.py, test_results.py) to ensure that the validations, asynchronous operations, and new functionalities (like custom prompt processing and context validation) are thoroughly covered.

3. Additional improvements include:

   • Detailed error messaging to guide users regarding the proper usage of API logging parameters.
   • Minor consolidation of import statements and better organization of code, which contributes to overall maintainability and readability.

Overall, the PR significantly enhances the interaction between the client and the backend text generation API, making the qualitative logging process more flexible, robust, and user-friendly.

Test Suggestions

• Write integration tests to verify the complete flow from generating text via the API to logging the result in both async and sync modes.
• Add unit tests for input validation logic, specifically for checking that errors are thrown when both text and prompt/context are provided.
• Test the get_content_ids function with various configurations of section identifiers to ensure that the correct ordering of content IDs is maintained.
• Simulate API failures (e.g., non-200 responses) and check how the error handling behaves in functions like generate_qualitative_text.
• Ensure that the Markdown-to-HTML conversion works correctly in edge cases when the input text contains unusual markdown or HTML fragments.