feat(core,prompt): Simplified property value transformers for AI Prompt generation (v17)

[mattbrailsford]

Summary

v17 backport of #250. Fixes #249 — executing an AI Prompt against a rich-text (Umbraco.RichText / TipTap) property failed with an opaque HTTP 400 (invalid_json_schema) from strict providers like OpenAI. (Reported as "Block List/Grid", but the reporter's real case was RichText — whose write schema embeds the same block structure.)

The schema-driven wand constrains strict structured output to the target property's CMS write schema. RichText's blocks embeds an intentionally unconstrained values[].value node ({}, from CMS BlockJsonSchemaHelper), which has no faithful equivalent in OpenAI's strict subset → rejected before generation.

Note: the original commit on this branch took a fail-fast approach; after design review it evolved into the general transformer below. The AIPromptSchemaCompatibility guard from that commit is retained as a fallback.

Approach — simplified value transformers

New general server-side abstraction IAISimplifiedPropertyValueTransformer (Umbraco.AI.Core, discovered like IAIPropertyValueHandler): a per-editor simplified, strict-representable LLM schema plus a total/idempotent transform back to the editor's write value.

RichTextSimplifiedPropertyValueTransformer offers the LLM a plain markup string and wraps the result into { markup, blocks }, preserving existing inline blocks from the current value.

Consumer chooses the representation by capability (no regression):

Consumer	Schema presented
Prompt (one-shot, strict)	the simplified schema when a transformer is registered; else the write schema; else the string model
Agent (loose, iterative, add_item handlers)	unchanged — keeps the full write schema so block authoring is preserved

What AIPromptService now does

• Uses the simplified schema when a transformer exists, and runs the transform server-side so ValueChange.Value is the write shape, while DisplayValue stays the simplified (markup) value for the preview.
• Reads the current write-shape value from the serialized entity/element already in the runtime context to preserve existing blocks — no new request field / client plumbing.
• Runs the IsStrictRepresentable guard on whichever schema is used (incl. a simplified one); block editors (no transformer) still fail fast rather than 400.
• Runs plain-text output mode for DisplayMode == TipTapTool prompts (decided server-side), so the in-editor toolbar keeps receiving a string.
• Surfaces transform failures as a clean 400 and isolates per-option failures.
• Resolver: additive ResolvePropertyValueSchemaAsync; old ResolveValueSchemaAsync kept and marked [Obsolete("… Will be removed in v19")] (v17 line: current major + 2).

Frontend

applyValueChange (document/block/media adapters) resolves the editor alias from the data-type item repository when a field is empty, so preparers still run into empty fields.

Validation

• Builds green; unit tests pass (Umbraco.AI 936, Umbraco.AI.Prompt 84), incl. the RichText transformer suite (with a OpenAI structured output rejects Umbraco block editor prompt schemas #249 regression replaying a live request/response byte-for-byte) and resolver tests.
• End-to-end validated on v18 (feat(core,prompt): Simplified property value transformers for AI Prompt generation #250) against a real OpenAI key: RichText prompt → no 400, options generated, editor updated, { markup, blocks } with existing blocks preserved.

Not in scope (follow-ups)

• Agent adoption of the transform at the dispatcher SetValue leaf (additive).
• Moving DateTime normalisation server-side + preparer cleanup.
• "Proper" recursive block-content generation for the Prompt path (intractable strict schema).

🤖 Generated with Claude Code