Package com.vaadin.flow.component.ai.form

Class FormAIController

java.lang.Object
com.vaadin.flow.component.ai.form.FormAIController
All Implemented Interfaces:
AIController
public class FormAIController extends Object implements AIController
Populates a layout's fields with values an LLM extracts from a user prompt or attached files. Attach it to an AIOrchestrator via withController(...).

The controller accepts any HasComponents container. It discovers fields by walking the container's component tree and collecting every component that implements HasValue. The walk recurses into nested HasComponents children so layouts containing layouts are handled.

Field identifiers: the controller assigns an opaque UUID to each field at discovery time and uses that UUID as the field's id in every tool call the LLM makes. Developers never see UUIDs; the LLM never sees field labels in the id slot. Semantic meaning travels through each field's description — the field's label, helper text, and the describe(HasValue, String) hint.

Binder integration: the two-argument constructor accepts a Binder. For every named binding (bind("propertyName"), bindInstanceFields(this), or @PropertyId) the property name is used as a default field description so the LLM can refer to the field by its bean-side name. The default only applies when no explicit describe(HasValue, String) has been registered; calling describe(...) always wins. Lambda-bound bindings carry no property name and contribute no default.

Field locking: while a fill is in progress, every non-ignored field that wasn't already read-only is set to read-only so the user cannot type into a field the AI is about to overwrite. Locks are released when the turn ends, successfully or otherwise. Application code that changes a field's read-only state mid-turn (e.g. from a value-change listener reacting to the LLM's writes) will be overridden when the controller releases its own locks at turn end — applications should avoid toggling read-only state during a fill turn, or reapply it after the turn completes.

Serialization: the controller is not serialized with the orchestrator. After deserialization, create a new controller against the same form (and binder, if any) and call orchestrator.reconnect(provider).withController(controller).apply().

Author:
Vaadin Ltd

  • Constructor Details

    • FormAIController

      public FormAIController(T form)
      Creates a new form AI controller for the given container. Fields are discovered by walking the container's component tree each time the controller is asked for tools, so fields added or removed between turns are picked up automatically.
      Type Parameters:
      T - the container type
      Parameters:
      form - the container whose fields the LLM may populate, not null

    • FormAIController

      public FormAIController(T form, Binder<?> binder)
      Creates a new form AI controller for the given container and binder. For every named binding on the binder, the bean property name is used as a default description when the developer has not registered one explicitly; the controller itself still uses an opaque UUID as the field's tool-call id. Lambda-bound bindings carry no property name and contribute no default. A field that is part of the layout but not bound to the supplied binder behaves the same as in the no-binder constructor.
      Type Parameters:
      T - the container type
      Parameters:
      form - the container whose fields the LLM may populate, not null
      binder - the binder whose property names default the field descriptions, not null; use the single-argument constructor for the no-binder case
      Throws:
      NullPointerException - if form or binder is null

  • Method Details

    • describe

      public FormAIController describe(HasValue<?,?> field, String description)
      Adds a free-form description that the LLM sees alongside the field when deciding what to fill in. Use it to add business semantics that are not implied by the field's label, helper text, or component type (for example clarifying that a numeric field expects a percentage rather than an absolute amount). Later calls for the same field overwrite earlier ones.
      Parameters:
      field - the field to describe, not null
      description - the description text, not null
      Returns:
      this controller, for chaining

    • valueOptions

      public <T> FormAIController valueOptions(HasValue<?,T> field, BiFunction<String,Integer,List<String>> query, Function<String,T> toValue)
      Declares the set of values the LLM may pick for the field. The query callback receives a filter string and a limit and returns matching options as the labels the LLM should see; the toValue function converts a chosen label back to the field's value type. Later calls for the same field overwrite earlier ones.
      Type Parameters:
      T - the field's value type
      Parameters:
      field - the field whose options the LLM may query, not null
      query - the filter callback returning labels for the LLM, not null
      toValue - converts a chosen label to the field's value type, not null
      Returns:
      this controller, for chaining

    • valueOptions

      public FormAIController valueOptions(HasValue<?,String> field, BiFunction<String,Integer,List<String>> query)
      Declares the set of values the LLM may pick for a String-typed field. The query callback receives a filter string and a limit and returns matching options; each label is used as the field value as-is. Later calls for the same field overwrite earlier ones.
      Parameters:
      field - the field whose options the LLM may query, not null
      query - the filter callback returning labels for the LLM, not null
      Returns:
      this controller, for chaining

    • valueOptions

      public <T> FormAIController valueOptions(HasValue<?,T> field, Collection<String> options, Function<String,T> toValue)
      Declares a fixed set of labels the LLM may pick for the field. The toValue function converts a chosen label back to the field's value type. Later calls for the same field overwrite earlier ones.
      Type Parameters:
      T - the field's value type
      Parameters:
      field - the field whose options the LLM may pick from, not null
      options - the labels the LLM may pick from, not null; a defensive copy is taken
      toValue - converts a chosen label to the field's value type, not null
      Returns:
      this controller, for chaining

    • valueOptions

      public FormAIController valueOptions(HasValue<?,String> field, Collection<String> options)
      Declares a fixed set of labels the LLM may pick for a String-typed field. Each chosen label is used as the field value as-is. Later calls for the same field overwrite earlier ones.
      Parameters:
      field - the field whose options the LLM may pick from, not null
      options - the labels the LLM may pick from, not null; a defensive copy is taken
      Returns:
      this controller, for chaining

    • ignore

      public FormAIController ignore(HasValue<?,?> field)
      Hides the given field from the LLM. The field is excluded from the tool surface and is not locked during a fill. Use this for fields the AI must not read or write (password fields, internal IDs, PII).
      Parameters:
      field - the field to hide, not null
      Returns:
      this controller, for chaining

    • getTools

      public List<LLMProvider.ToolSpec> getTools()
      Description copied from interface: AIController
      Returns the tools this controller exposes to the LLM.
      Specified by:
      getTools in interface AIController
      Returns:
      list of tools, or empty list if controller provides no tools

    • onRequestStart

      public void onRequestStart()
      Description copied from interface: AIController
      Called synchronously on the UI thread just before the LLM stream opens. By the time this method fires, the user message and an empty assistant placeholder are already in the message list; the turn is committed to the conversation history and the attachment-submit listener only after this method returns successfully. Implementations can prepare for the turn — locking UI surfaces, snapshotting state the tool definitions depend on, and so on.

      The default does nothing. Throwing from this method aborts the turn before the commit step: the conversation history is unchanged, the attachment-submit listener is not notified, the LLM stream is not opened, the assistant placeholder is updated to a generic error message, AIController.onResponseFailed(Throwable) fires with the thrown exception so per-turn state captured before the throw can still be released, and the exception propagates back to the caller of the prompt entry point.

      Specified by:
      onRequestStart in interface AIController

    • onResponseComplete

      public void onResponseComplete()
      Description copied from interface: AIController
      Called on the UI thread under the session lock when the LLM stream completes successfully — after all tool calls for the turn have run and the LLM has produced its final response. Use it for deferred UI updates or to commit staged state.

      Mutually exclusive with AIController.onResponseFailed(Throwable): every turn fires exactly one of the two. Exceptions thrown from the hook are caught and the user sees a generic error message; Errors propagate.

      Specified by:
      onResponseComplete in interface AIController

    • onResponseFailed

      public void onResponseFailed(Throwable error)
      Description copied from interface: AIController
      Called on the UI thread under the session lock when an LLM turn fails — stream error, timeout, or any throw between AIController.onRequestStart() and the start of the stream. Implementations should release per-turn state captured in onRequestStart (locks, pending writes, snapshots).

      Mutually exclusive with AIController.onResponseComplete(): every turn fires exactly one of the two. The default does nothing. Exceptions thrown from the hook are caught and logged; Errors propagate.

      Specified by:
      onResponseFailed in interface AIController
      Parameters:
      error - the cause of the failure (Exception or Error), never null