Skip to content

Commit 8b470d6

Browse files
authored
feat: add binder integration to form ai controller (#9308)
## Description This PR: - Adds a `FormAIController(container, Binder<?>)` overload. - Property-named bindings (`bind("name")`, `bindInstanceFields(this)`, `@PropertyId(...)`) contribute the bean property name as a default for the field's description — surfaced to the LLM alongside the field's label and helper text. The field's tool-call id stays an opaque UUID assigned at discovery time; the property name is description-side metadata only. - Seeding only fills nulls: an explicit `describe(field, "...")` always wins. Lambda-bound bindings and unbound fields contribute no default. - Adds a package-private `findBinding(field)` returning the live binding for any field on the supplied binder, or an empty optional for unbound fields and for controllers constructed without a binder. Fixes https://github.com/orgs/vaadin/projects/103/views/1?filterQuery=&pane=issue&itemId=186542732 ## Type of change - [ ] Bugfix - [x] Feature ## Checklist - [x] I have read the contribution guide: https://vaadin.com/docs/latest/contributing/overview - [x] I have added a description following the guideline. - [x] The issue is created in the corresponding repository and I have referenced it. - [x] I have added tests to ensure my change is effective and works as intended. - [x] New and existing tests are passing locally with my change. - [x] I have performed self-review and corrected misspellings. - [x] Enhancement / new feature was discussed in a corresponding GitHub issue and Acceptance Criteria were created.
1 parent daf779d commit 8b470d6

4 files changed

Lines changed: 486 additions & 2 deletions

File tree

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
/*
2+
* Copyright 2000-2026 Vaadin Ltd.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
5+
* use this file except in compliance with the License. You may obtain a copy of
6+
* the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12+
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13+
* License for the specific language governing permissions and limitations under
14+
* the License.
15+
*/
16+
package com.vaadin.flow.component.ai.form;
17+
18+
import java.lang.reflect.Field;
19+
import java.util.Collections;
20+
import java.util.LinkedHashMap;
21+
import java.util.Map;
22+
import java.util.stream.Collectors;
23+
24+
import org.slf4j.Logger;
25+
import org.slf4j.LoggerFactory;
26+
27+
import com.vaadin.flow.component.HasValue;
28+
import com.vaadin.flow.data.binder.Binder;
29+
import com.vaadin.flow.data.binder.Binder.Binding;
30+
31+
/**
32+
* Reflection access to {@link Binder} internals.
33+
* <p>
34+
* {@link FormAIController} needs the property name supplied when a binding was
35+
* created, which {@link Binder} does not expose publicly. The property names
36+
* live in a private {@code boundProperties} field; this class reads it
37+
* reflectively and caches the {@link Field} reference at static init. If a
38+
* future {@code Binder} renames or removes the field, the helper logs a warning
39+
* and returns an empty map so callers degrade to the non-binder code path
40+
* rather than throwing.
41+
* </p>
42+
*/
43+
final class BinderReflection {
44+
45+
private static final Logger LOGGER = LoggerFactory
46+
.getLogger(BinderReflection.class);
47+
48+
private static final Field BOUND_PROPERTIES_FIELD = getBoundPropertiesField();
49+
50+
private BinderReflection() {
51+
}
52+
53+
/**
54+
* Builds a {@code HasValue → propertyName} map of every binding that
55+
* carries a property name. Lambda-bound bindings are excluded because the
56+
* binder records no name for them.
57+
*
58+
* @param binder
59+
* the binder, not {@code null}
60+
* @return the map, never {@code null}; empty if reflection is unavailable
61+
*/
62+
@SuppressWarnings("unchecked")
63+
static Map<HasValue<?, ?>, String> collectPropertyNames(Binder<?> binder) {
64+
try {
65+
return ((Map<String, Binding<?, ?>>) BOUND_PROPERTIES_FIELD
66+
.get(binder))
67+
.entrySet().stream()
68+
.collect(Collectors.toMap(e -> e.getValue().getField(),
69+
Map.Entry::getKey, (x, y) -> y,
70+
LinkedHashMap::new));
71+
} catch (Exception ex) {
72+
LOGGER.warn("Could not extract property names from Binder.", ex);
73+
}
74+
return Collections.emptyMap();
75+
}
76+
77+
private static Field getBoundPropertiesField() {
78+
try {
79+
var field = Binder.class.getDeclaredField("boundProperties");
80+
field.setAccessible(true);
81+
return field;
82+
} catch (Exception e) {
83+
LOGGER.warn("Could not access Binder.boundProperties; bound "
84+
+ "fields will not seed the LLM-facing description from "
85+
+ "their bean property name.", e);
86+
}
87+
return null;
88+
}
89+
}

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/FormAIController.java‎

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
import com.vaadin.flow.component.ai.orchestrator.AIController;
3434
import com.vaadin.flow.component.ai.orchestrator.AIOrchestrator;
3535
import com.vaadin.flow.component.ai.provider.LLMProvider;
36+
import com.vaadin.flow.data.binder.Binder;
3637

3738
/**
3839
* Populates a layout's fields with values an LLM extracts from a user prompt or
@@ -48,6 +49,26 @@
4849
* </p>
4950
*
5051
* <p>
52+
* <b>Field identifiers:</b> the controller assigns an opaque UUID to each field
53+
* at discovery time and uses that UUID as the field's id in every tool call the
54+
* LLM makes. Developers never see UUIDs; the LLM never sees field labels in the
55+
* id slot. Semantic meaning travels through each field's <i>description</i> —
56+
* the field's label, helper text, and the {@link #describe(HasValue, String)}
57+
* hint.
58+
* </p>
59+
*
60+
* <p>
61+
* <b>Binder integration:</b> the two-argument constructor accepts a
62+
* {@link Binder}. For every named binding ({@code bind("propertyName")},
63+
* {@code bindInstanceFields(this)}, or {@code @PropertyId}) the property name
64+
* is used as a default field description so the LLM can refer to the field by
65+
* its bean-side name. The default only applies when no explicit
66+
* {@link #describe(HasValue, String)} has been registered; calling
67+
* {@code describe(...)} always wins. Lambda-bound bindings carry no property
68+
* name and contribute no default.
69+
* </p>
70+
*
71+
* <p>
5172
* <b>Field locking:</b> while a fill is in progress, every non-ignored field
5273
* that wasn't already read-only is set to read-only so the user cannot type
5374
* into a field the AI is about to overwrite. Locks are released when the turn
@@ -60,7 +81,8 @@
6081
*
6182
* <p>
6283
* <b>Serialization:</b> the controller is not serialized with the orchestrator.
63-
* After deserialization, create a new controller against the same form and call
84+
* After deserialization, create a new controller against the same form (and
85+
* binder, if any) and call
6486
* {@code orchestrator.reconnect(provider).withController(controller).apply()}.
6587
* </p>
6688
*
@@ -76,6 +98,7 @@ public class FormAIController implements AIController {
7698
static final String FIELD_ID_KEY = "vaadin.ai.form.fieldId";
7799

78100
private final Component form;
101+
private final Binder<?> binder;
79102
private final Map<String, FormFieldHints> hintsById = new HashMap<>();
80103
private final List<HasValue<?, ?>> lockedFields = new ArrayList<>();
81104

@@ -94,6 +117,37 @@ public class FormAIController implements AIController {
94117
public <T extends Component & HasComponents> FormAIController(T form) {
95118
Objects.requireNonNull(form, "Form must not be null");
96119
this.form = form;
120+
this.binder = null;
121+
}
122+
123+
/**
124+
* Creates a new form AI controller for the given container and binder. For
125+
* every named binding on the binder, the bean property name is used as a
126+
* default {@link #describe(HasValue, String) description} when the
127+
* developer has not registered one explicitly; the controller itself still
128+
* uses an opaque UUID as the field's tool-call id. Lambda-bound bindings
129+
* carry no property name and contribute no default. A field that is part of
130+
* the layout but not bound to the supplied binder behaves the same as in
131+
* the no-binder constructor.
132+
*
133+
* @param form
134+
* the container whose fields the LLM may populate, not
135+
* {@code null}
136+
* @param binder
137+
* the binder whose property names default the field
138+
* descriptions, not {@code null}; use the single-argument
139+
* constructor for the no-binder case
140+
* @param <T>
141+
* the container type
142+
* @throws NullPointerException
143+
* if {@code form} or {@code binder} is {@code null}
144+
*/
145+
public <T extends Component & HasComponents> FormAIController(T form,
146+
Binder<?> binder) {
147+
Objects.requireNonNull(form, "Form must not be null");
148+
Objects.requireNonNull(binder, "Binder must not be null");
149+
this.form = form;
150+
this.binder = binder;
97151
}
98152

99153
/**
@@ -241,6 +295,7 @@ public void onRequestStart() {
241295
// Refresh the field set so fields added or removed between turns
242296
// are picked up.
243297
attachIds();
298+
seedDescriptionsFromBinder();
244299
lockFields();
245300
}
246301

@@ -254,6 +309,27 @@ public void onResponseFailed(Throwable error) {
254309
unlockFields();
255310
}
256311

312+
/**
313+
* Walks the binder's property names and defaults {@code hints.description}
314+
* for any bound field that does not already have an explicit description.
315+
* Called at the start of every turn so bindings added or removed between
316+
* turns are reflected; an explicit {@link #describe(HasValue, String)}
317+
* always wins because the seeding only fills in nulls.
318+
*/
319+
private void seedDescriptionsFromBinder() {
320+
var propertyNames = BinderReflection.collectPropertyNames(binder);
321+
for (var entry : propertyNames.entrySet()) {
322+
var field = entry.getKey();
323+
if (!(field instanceof Component)) {
324+
continue;
325+
}
326+
var hints = hintsFor(field);
327+
if (hints.description == null) {
328+
hints.description = entry.getValue();
329+
}
330+
}
331+
}
332+
257333
/**
258334
* Puts every discovered, non-ignored, currently editable field into
259335
* read-only state so the user cannot type into a field the AI is about to

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/test/java/com/vaadin/flow/component/ai/AIComponentsSerializableTest.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,8 @@ protected Stream<String> getExcludedPatterns() {
8585
"com\\.vaadin\\.flow\\.component\\.ai\\.form\\.FormFieldHints.*",
8686
"com\\.vaadin\\.flow\\.component\\.ai\\.form\\.FormFieldSchema.*",
8787
"com\\.vaadin\\.flow\\.component\\.ai\\.form\\.FormFieldType.*",
88-
"com\\.vaadin\\.flow\\.component\\.ai\\.form\\.FormValueConverter.*"));
88+
"com\\.vaadin\\.flow\\.component\\.ai\\.form\\.FormValueConverter.*",
89+
"com\\.vaadin\\.flow\\.component\\.ai\\.form\\.BinderReflection(\\$\\d+)?"));
8990
}
9091

9192
@BeforeEach

0 commit comments

Comments
 (0)