Polish evaluator API: public stubs, docstrings, AD-missing hints

- Mark generate_testcases / run_testcases as public (1.11+) so downstream
  AD-backend packages can reuse the conformance suite without reaching
  into private API.
- Note in the Prepared docstring that the two-arg constructor is for
  backends that allocate fresh storage per call.
- Expand the _ad_output_arity error message to call out matrix/tuple
  outputs explicitly and recommend flattening.
- Add a MethodError hint on value_and_gradient!! / value_and_jacobian!!
  that fires when no AD backend extension is loaded — also surfaces
  through LogDensityProblems.logdensity_and_gradient, which delegates
  to value_and_gradient!!. Suppressed once any backend registers a
  method, where the standard candidate list is more informative.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: yebai

src/AbstractPPL.jl

@@ -12,14 +12,21 @@ include("abstractprobprog.jl")
 include("evaluate.jl")
 include("evaluators/Evaluators.jl")
 using .Evaluators: prepare, value_and_gradient!!, value_and_jacobian!!
-@static if VERSION >= v"1.11.0"
-    eval(Meta.parse("public prepare, value_and_gradient!!, value_and_jacobian!!"))
-end
 
-# Stubs implemented by `AbstractPPLTestExt` (loaded with `Test`).
+# Stubs implemented by `AbstractPPLTestExt` (loaded with `Test`). Part of the
+# public API for downstream AD-backend packages that want to reuse the shared
+# conformance suite in their own test setups.
 function generate_testcases end
 function run_testcases end
 
+@static if VERSION >= v"1.11.0"
+    eval(
+        Meta.parse(
+            "public prepare, value_and_gradient!!, value_and_jacobian!!, generate_testcases, run_testcases",
+        ),
+    )
+end
+
 include("varname/optic.jl")
 include("varname/varname.jl")
 include("varname/subsumes.jl")

src/evaluators/Evaluators.jl

@@ -16,7 +16,8 @@ AD-prepared evaluator parameterised by backend type `AD`.
   `NamedTupleEvaluator`); forwarded on `p(x)`.
 - `cache` — backend-specific pre-allocated state (ForwardDiff configs, Mooncake
   caches, DifferentiationInterface preps, etc.). `Nothing` when the backend requires
-  no cached state.
+  no cached state. The two-argument constructor is for backends that allocate
+  fresh storage on every `value_and_gradient!!` call.
 
 Extension packages implement `value_and_gradient!!` (and optionally
 `value_and_jacobian!!`) by specialising on the `cache` type:
@@ -219,7 +220,7 @@ function _ad_output_arity(y)
     y isa AbstractVector && return :vector
     throw(
         ArgumentError(
-            "A prepared AD evaluator must return a scalar or AbstractVector; got $(typeof(y)).",
+            "A prepared AD evaluator must return a scalar (`Number`) or `AbstractVector`; got $(typeof(y)). Matrix- or tuple-valued outputs are not supported — flatten into a vector before returning.",
         ),
     )
 end
@@ -272,6 +273,19 @@ function __init__()
             "\nCalling `prepare` with an AD backend requires loading the corresponding extension (e.g., `using DifferentiationInterface`).",
         )
     end
+    # `value_and_gradient!!` / `value_and_jacobian!!` are stubs until an AD
+    # backend extension adds methods. Suppress the hint once any backend is
+    # loaded — the standard `MethodError` candidate list is then more useful
+    # than a generic "load an extension" message. Also fires when reached via
+    # `LogDensityProblems.logdensity_and_gradient`, which delegates here.
+    Base.Experimental.register_error_hint(MethodError) do io, exc, args, kwargs
+        exc.f === value_and_gradient!! || exc.f === value_and_jacobian!! || return nothing
+        isempty(methods(exc.f)) || return nothing
+        print(
+            io,
+            "\nNo AD backend extension is loaded. Load `DifferentiationInterface` (with a backend like `ForwardDiff`) or `Mooncake` to enable gradient/jacobian computation.",
+        )
+    end
 end
 
 end # module