Add evaluator API section to docs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: yebai

AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md
+
+AbstractPPL.jl is a Julia interface package for probabilistic programming. It is used by `DynamicPPL.jl` (`https://github.com/TuringLang/DynamicPPL.jl`) and `JuliaBUGS.jl` (`https://github.com/TuringLang/JuliaBUGS.jl`). Most of the package is contract surface: a small model API, a prepared-evaluator API, and a nontrivial `VarName`/optic subsystem used across the Turing ecosystem.
+
+## Conventions
+
+  - Make the smallest correct change.
+  - Treat exported behaviour, examples, and tests as the package contract.
+  - Keep source, tests, and docs aligned for public behaviour changes.
+  - Prefer narrow, explicit methods over broad signatures.
+  - Keep weakdep-specific behaviour in `ext/`.
+  - Prefer targeted fixes over broad refactors.
+  - Avoid new dependencies unless clearly justified.
+
+## Package-Specific Notes
+
+  - Preserve the model invariants documented in `src/abstractprobprog.jl`: `condition`/`decondition` and `fix`/`unfix` are intended to round-trip when supported.
+  - `rand(model)` and `predict(model, params)` have default RNG/type forwarding behaviour covered by tests; changes here should stay consistent with `AbstractMCMC` expectations.
+  - The evaluator API in `src/evaluator.jl` is structural. `prepare(..., prototype::NamedTuple)` fixes field structure, `capabilities` defaults conservatively to `DerivativeOrder{0}()`, and AD-aware prepared objects are expected to return gradients with the same named structure as inputs.
+  - `VarName` and optics are the main complexity in this repo. Preserve equality, hashing, pretty-printing, composition/decomposition, and type-stability behaviour.
+  - Dynamic indices (`begin`, `end`, expressions containing them) are intentionally deferred until `concretize`; do not silently erase that distinction.
+  - Unconcretized dynamic indices must not be serialised. If serialization changes, keep `varname_to_string` / `string_to_varname` round-tripping for supported index types.
+  - `@varname(..., true)` cannot auto-concretize when the top-level symbol is interpolated; preserve that error path unless the design is intentionally changed.
+  - `subsumes` is conservative by design. Do not broaden it casually for ambiguous indexing forms.
+  - `getvalue` / `hasvalue` on `AbstractDict{<:VarName}` intentionally prefer exact matches, then walk up to more general parents when possible.
+  - The Distributions extension exists to reconstruct structured values from elementwise `VarName` entries. Keep that logic in `ext/`, and prefer the simpler two-argument `getvalue` / `hasvalue` methods unless distribution-shaped reconstruction is actually needed.
+  - There is explicit code to keep optic equality JET-friendly and to work around Julia tuple-equality issues; changes around optic equality need extra care.
+
+## Testing
+
+  - Start with a minimal reproducer and run the smallest relevant test scope.
+  - Main test command: `julia --project=. -e 'using Pkg; Pkg.test()'`
+  - CI-style variants:
+    `GROUP=Tests julia --project=. -e 'using Pkg; Pkg.test()'`
+    `GROUP=Doctests julia --project=. -e 'using Pkg; Pkg.test()'`
+  - VarName or optic changes usually need coverage for equality/hash, concretization, `hasvalue`/`getvalue`, serialization, and JET-sensitive cases.
+  - Public API changes should keep Aqua and doctests passing.
+  - If a change may affect ecosystem compatibility, consider the downstream `DynamicPPL.jl` integration workflow as part of validation.
+  - Do not weaken tests just to make CI pass without explicit confirmation.
+
+## Docs
+
+  - Keep `docs/src/` aligned with public API and examples.
+  - `docs/src/interface.md` is explicitly marked outdated and aspirational; prefer current source, tests, and docstrings over that page when they conflict.
+  - Build docs with: `julia --project=docs -e 'using Pkg; Pkg.instantiate(); include("docs/make.jl")'`
+  - Follow `.JuliaFormatter.toml` when formatting is part of the task.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

docs/Project.toml

@@ -5,4 +5,4 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 
 [sources]
-AbstractPPL = {path = "../"}
+AbstractPPL = {path = ".."}

docs/src/interface.md

@@ -316,7 +316,7 @@ There are two things that make them more special, though:
     vi[@varname(x[1])] = 1
     vi[@varname(x[2])] = 2
     keys(vi) == [x[1], x[2]]
-    
+
     vi[@varname(x)] = [1, 2]
     keys(vi) == [x]
     ```

docs/src/pplapi.md

@@ -18,3 +18,13 @@ evaluate!!
 ```@docs
 AbstractModelTrace
 ```
+
+## Evaluator interface
+
+```@docs
+DerivativeOrder
+capabilities
+prepare
+value_and_gradient
+dimension
+```

src/varname/serialize.jl

@@ -182,5 +182,5 @@ Convert a string representation of a `VarName` back to a `VarName`. The string
 should have been generated by `varname_to_string`.
 """
 function string_to_varname(str::AbstractString)
-    dict_to_varname(JSON.parse(str; dicttype=OrderedDict{String,Any}))
+    return dict_to_varname(JSON.parse(str; dicttype=OrderedDict{String,Any}))
 end

test/ext/differentiation_interface/differentiation_interface.jl

@@ -40,9 +40,9 @@ const adtype = ADTypes.AutoFiniteDifferences(; fdm)
     @test prepared([3.0, 1.0, 2.0]) ≈ 14.0
 
     val, grad = AbstractPPL.value_and_gradient(prepared, values)
-    @test val ≈ 14.0 atol=1e-6
-    @test grad.x ≈ 6.0 atol=1e-6
-    @test grad.y ≈ [2.0, 4.0] atol=1e-6
+    @test val ≈ 14.0 atol = 1e-6
+    @test grad.x ≈ 6.0 atol = 1e-6
+    @test grad.y ≈ [2.0, 4.0] atol = 1e-6
     test_autograd(prepared, values; atol=1e-4, rtol=1e-4)
 
     # Overlong vector is rejected

test/test_utils.jl

@@ -10,9 +10,9 @@ function _fd_gradient(f, x::AbstractVector)
     h = cbrt(eps(T))
     grad = Vector{T}(undef, length(x))
     for i in eachindex(x)
-        xp = copy(x);
+        xp = copy(x)
         xp[i] += h
-        xm = copy(x);
+        xm = copy(x)
         xm[i] -= h
         grad[i] = (f(xp) - f(xm)) / (2h)
     end
@@ -34,6 +34,6 @@ function test_autograd(prepared, values::NamedTuple; atol=1e-5, rtol=1e-5)
     grad_fd_nt = AbstractPPL.unflatten_from_vec(values, _fd_gradient(f, x))
     @test val_ad ≈ f(x)
     for k in keys(values)
-        @test getfield(grad_ad, k) ≈ getfield(grad_fd_nt, k) atol=atol rtol=rtol
+        @test getfield(grad_ad, k) ≈ getfield(grad_fd_nt, k) atol = atol rtol = rtol
     end
 end

test/varname/hasvalue.jl

@@ -34,11 +34,11 @@ using Test
         @test canview(@opticof(_[1:2]), x)
         @test canview(@opticof(_[:]), x)
         @test !canview(@opticof(_[4]), x)
-        @test canview(@opticof(_[i = 1]), x)
+        @test canview(@opticof(_[i=1]), x)
         # For some weird reason DimData does not error on these two but just warns that
         # there's no index j!
-        @test canview(@opticof(_[j = 2]), x)
-        @test canview(@opticof(_[i = 1, j = 2]), x)
+        @test canview(@opticof(_[j=2]), x)
+        @test canview(@opticof(_[i=1, j=2]), x)
     end
 
     @testset "Dict" begin
@@ -246,14 +246,14 @@ end
         @test getvalue(x, @varname(a[1, 2])) == x.a[1, 2]
         @test hasvalue(x, @varname(a[:]))
         @test getvalue(x, @varname(a[:])) == x.a[:]
-        @test canview(@opticof(_[i = 1]), x.a)
-        @test hasvalue(x, @varname(a[i = 1]))
-        @test getvalue(x, @varname(a[i = 1])) == x.a[i = 1]
-        @test canview(@opticof(_[i = 1, j = 2]), x.a)
-        @test hasvalue(x, @varname(a[i = 1, j = 2]))
-        @test getvalue(x, @varname(a[i = 1, j = 2])) == x.a[i = 1, j = 2]
-        @test hasvalue(x, @varname(a[i = DD.Not(1)]))
-        @test getvalue(x, @varname(a[i = DD.Not(1)])) == x.a[i = DD.Not(1)]
+        @test canview(@opticof(_[i=1]), x.a)
+        @test hasvalue(x, @varname(a[i=1]))
+        @test getvalue(x, @varname(a[i=1])) == x.a[i=1]
+        @test canview(@opticof(_[i=1, j=2]), x.a)
+        @test hasvalue(x, @varname(a[i=1, j=2]))
+        @test getvalue(x, @varname(a[i=1, j=2])) == x.a[i=1, j=2]
+        @test hasvalue(x, @varname(a[i=DD.Not(1)]))
+        @test getvalue(x, @varname(a[i=DD.Not(1)])) == x.a[i=DD.Not(1)]
 
         y = (; b=DD.DimArray(randn(2, 3), (DD.X, DD.Y)))
         @test hasvalue(y, @varname(b))

test/varname/optic.jl

@@ -31,7 +31,7 @@ using AbstractPPL
             @opticof(_.a[2]),
             @opticof(_.a[1, :]),
             @opticof(_[1].a),
-            @opticof(_[1, x = 1].a),
+            @opticof(_[1, x=1].a),
         )
         for (i, optic1) in enumerate(optics)
             for (j, optic2) in enumerate(optics)
@@ -103,7 +103,7 @@ using AbstractPPL
                 @opticof(_.a),
                 @opticof(_.a.b),
                 @opticof(_[1].a),
-                @opticof(_[1, x = 1].a),
+                @opticof(_[1, x=1].a),
                 @opticof(_[].a[:]),
             )
             for optic in optics
@@ -196,8 +196,8 @@ using AbstractPPL
 
         @testset "keyword arguments to getindex" begin
             dimarray = DD.DimArray([0.0 1.0; 2.0 3.0], (:x, :y))
-            @test @opticof(_[x = 1])(dimarray) == dimarray[x = 1]
-            @test set(dimarray, @opticof(_[y = 2]), [9.0; 8.0]) ==
+            @test @opticof(_[x=1])(dimarray) == dimarray[x=1]
+            @test set(dimarray, @opticof(_[y=2]), [9.0; 8.0]) ==
                 DD.DimArray([0.0 9.0; 2.0 8.0], (:x, :y))
         end
 
@@ -288,10 +288,10 @@ using AbstractPPL
             @testset "keyword index" begin
                 x = DD.DimArray(zeros(2, 2), (:x, :y))
                 old_objid = objectid(x)
-                optic = with_mutation(@opticof(_[x = 1, y = 2]))
-                @test optic(x) === x[x = 1, y = 2]
+                optic = with_mutation(@opticof(_[x=1, y=2]))
+                @test optic(x) === x[x=1, y=2]
                 set(x, optic, 2.0)
-                @test x[x = 1, y = 2] == 2.0
+                @test x[x=1, y=2] == 2.0
                 @test collect(x) == [0.0 2.0; 0.0 0.0]
                 @test objectid(x) == old_objid
             end