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

[mattbrailsford]

Summary

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 (Responses API). (The issue was 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 the LLM's strict structured output to the target property's CMS write schema. RichText's schema is { markup, blocks: {…} }, and blocks embeds an intentionally unconstrained values[].value node ({} — "Any type - depends on property editor", from CMS BlockJsonSchemaHelper). That {} has no faithful equivalent in OpenAI's strict subset, so the request is 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, PropertyValueOperations/, discovered like IAIPropertyValueHandler): a per-editor simplified, strict-representable LLM schema plus a total/idempotent transform back to the editor's real write value.

RichTextSimplifiedPropertyValueTransformer offers the LLM a plain markup string ({ "type": "string" }) and wraps the result into { markup, blocks }, preserving any existing inline blocks from the property's 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 for the target editor, and runs the transform server-side so ValueChange.Value is the editor's 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 (the same source as the currentValue template variable) to preserve existing blocks — no new request field / client plumbing.
• Runs the IsStrictRepresentable guard on whichever schema is used (incl. a simplified one), so a mis-behaving transformer fails fast cleanly and block editors (no transformer) still fail fast rather than 400.
• Runs in plain-text output mode for DisplayMode == TipTapTool prompts (decided server-side from the persisted entity), 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 v20")].

Frontend

applyValueChange (document/block/media adapters) resolves the editor alias from the data-type item repository when a field is empty, so value 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.
• Manually validated end-to-end against a real OpenAI key: RichText summarize prompt → no 400, multiple options generated, editor updated; server response carries the { markup, blocks } write shape with the property's existing blocks preserved.

Not in scope (follow-ups)

• Agent adoption of the transform at the dispatcher SetValue leaf (additive, non-breaking).
• Moving DateTime normalisation server-side + preparer cleanup.
• "Proper" recursive block-content generation for the Prompt path (intractable strict schema — value is doubly-conditional on contentTypeKey+alias; strict mode bans if/then/allOf).

🤖 Generated with Claude Code