[SC-15023] feat(figures): add title field for figures and route to caption registry

[johnwalz97]

What and why?

Adds a title field to Figure so test authors can caption charts/figures the same way they already can for tables. Closes the gap between regular text blocks (where CKEditor figures already support captions) and test-driven blocks (where the validmind library had no way to set one).

Test functions can now return {"My Chart Title": fig, ...} — mirroring the existing dict-of-tables convention — and the title flows through to the platform's document media registry as Figure N. <title>.

Also fixes a quiet bug for tables: ResultTable.title was serialized as metadata.title, but the backend caption registry reads metadata.caption. We now emit both keys, so table titles actually reach the registry.

Before: test-driven figures had no caption-registry entry; tables had a title but it was only rendered as an inline <h4> heading and never reached the "Table N. " auto-numbered caption.
After: both figures and tables flow titles into the registry and get auto-numbered captions in the doc.

No backend, frontend, or CKEditor changes are required — that plumbing already reads metadata.caption and renders captions via the existing DocumentMediaCaption component.

How to test

1. pytest tests/test_results.py — 4 new tests cover the new serialization + dict-of-figures handler (28/28 pass locally).
2. In a notebook, define a custom test that returns {"My Cool Chart": some_plotly_fig} and log the result against a model with the global_media_captions_enabled org setting on. The figure should render with Figure N. My Cool Chart underneath it.
3. The updated example in notebooks/how_to/tests/custom_tests/implement_custom_tests.ipynb (the ComplexOutput test) now showcases titled figures end-to-end.

What needs special review?

• ResultTable.serialize() now emits both title and caption in metadata. Worth confirming no downstream consumer (e.g. docs export, PDF generation) chokes on the extra key. None found in backend code search, but flagging for visibility.
• FigureOutputHandler.can_handle now claims dicts whose values are all figure-like. It's ordered before TableOutputHandler in the handler list, so dict-of-DataFrames continues to be handled by the table handler.

Dependencies, breaking changes, and deployment notes

• No breaking changes — title is a new optional field on Figure with a default; the dict-of-figures syntax is additive.
• No DB migrations.
• No backend/frontend deploys required to ship this; benefits appear automatically once tenants have global_media_captions_enabled.

Release notes

Custom tests can now title figures the same way they already title tables. Return {"My Chart Title": fig} from a test (or pass title="…" to Figure/ResultTable) and the title will be rendered as Figure N. My Chart Title in the document's caption registry.

Checklist

• What and why
• Screenshots or videos (Frontend) — N/A
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut (via sc-15023 branch prefix)
• Unit tests added
• Tested locally
• Documentation updated (docstrings + example notebook)
• Environment variable additions/changes documented — N/A

[github-actions]

PR Summary

This PR enhances the functionality for handling figure and table titles within the ValidMind platform. The changes focus on improving how titles are serialized into metadata as captions for both figures and tables, ensuring that they are properly rendered in the document media registry (e.g., 'Figure N. <title>' and 'Table N. <title>').

Key changes include:

• Updating the notebook documentation in notebooks/how_to/tests/custom_tests/implement_custom_tests.ipynb to clarify that returning dictionaries for figures and tables will use the dict keys as titles. The updates correct some formatting and unicode apostrophe issues.

• Adding several new unit tests in tests/test_results.py to verify that:

  • Figures with an explicit title have the title serialized as caption in the metadata.
  • Tables with titles are serialized with both title and caption in the metadata for backward compatibility.
  • The output handler correctly assigns titles from dictionary keys when figures are returned as a dict, and that explicit titles on pre-built figures are preserved.

• Enhancing the documentation in the decorator module (validmind/tests/decorator.py) with additional examples that explain how to return titled tables and figures.

• Refactoring the FigureOutputHandler in validmind/tests/output.py by introducing an internal helper to check if an item is a figure-like object and to handle the assignment of titles. This ensures consistent behavior when figures are either passed directly or via a dictionary where the key reflects the intended title.

• Updating the Figure and ResultTable classes in their respective modules to include an optional title field. The serialize methods now include logic to incorporate the title into the metadata as caption along with any backward-compatible keys.

These enhancements improve the clarity and utility of model documentation by providing clear, user-defined captions, and maintain backward compatibility with previous implementations.

Test Suggestions

• Run the updated notebook to verify that titles are rendered correctly in both tables and figures.
• Execute the newly added unit tests in tests/test_results.py to ensure proper metadata serialization for both titled and untitled figures/tables.
• Add negative tests with non-figure dictionary items to verify that the FigureOutputHandler does not incorrectly process them.
• Test the backward compatibility by creating figures and tables without explicit titles and confirming that the metadata is correctly omitted or defaults as expected.

[juanmleng]

Really cool @johnwalz97!