Package com.vaadin.flow.component.ai.chart

Class ChartAIController

java.lang.Object
com.vaadin.flow.component.ai.chart.ChartAIController
All Implemented Interfaces:
AIController
public class ChartAIController extends Object implements AIController
AI controller for creating interactive chart visualizations from database data.

This controller provides tools that allow the LLM to query database schemas and create or update chart visualizations based on natural language requests. Attach it to an AIOrchestrator via AIOrchestrator.Builder.withController(AIController) to expose its tools to the LLM. Workflow instructions are delivered through the description of the get_chart_instructions tool, which the LLM reads as part of the tool manifest. The controller's workflow tells the model that where an application's system prompt conflicts with it, the system prompt wins, so a step can be adjusted without subclassing. 

 var controller = new ChartAIController(chart, databaseProvider);
 AIOrchestrator orchestrator = AIOrchestrator
         .builder(llmProvider, systemPrompt).withController(controller)
         .withMessageList(messageList).build();

State changes requested by the LLM are deferred and applied in onResponse(ResponseListener.ResponseEvent) on the success path, avoiding partial state and multiple redraws during a multi-tool LLM turn. The chart state is stored directly on the Chart component, so it survives serialization.

If the LLM turn fails, onResponse(ResponseListener.ResponseEvent) fires with the cause ? pending changes are discarded and the chart keeps its last successfully-rendered state.

The controller sends the LLM nothing from the query results: when it reads the chart state, it gets the SQL queries and the configuration it has set itself, not the series, axis categories or other values the chart builds from the rows. Only the schema description your DatabaseProvider returns from DatabaseProvider.getSchema() and the message of a ToolException it throws reach the LLM as is, so keep row values out of both.

Data conversion from SQL query results to chart series is handled by a DataConverter. A default implementation is used unless overridden via setDataConverter(DataConverter).

Serialization: This controller is not serialized with the orchestrator. After deserialization, create a new controller and restore transient dependencies via reconnect(provider) .withController(controller).apply(). The chart data can be captured via getState() and re-applied via restoreState(ChartState): 

 var controller = new ChartAIController(chart, databaseProvider);
 orchestrator.reconnect(llmProvider).withController(controller).apply();
 if (savedState != null) {
     controller.restoreState(savedState);
 }

Register a listener via addStateChangeListener(SerializableConsumer) to be notified when the chart state changes, for example to persist getState() after each successful AI request.

Provider compatibility: The chart tools use optional properties in their parameter schemas, which are incompatible with OpenAI's strict tool-calling mode (strict mode requires every property listed under properties to also appear in required). Strict tool calling is off by default in both LangChain4J and Spring AI; only users who explicitly opt in (e.g. strictTools(true) on LangChain4J's OpenAiStreamingChatModel builder) are affected.

Since:
25.3
Author:
Vaadin Ltd
See Also:

  • Constructor Details

    • ChartAIController

      public ChartAIController(Chart chart, DatabaseProvider databaseProvider)
      Creates a new AI chart controller.
      Parameters:
      chart - the chart component to update, not null
      databaseProvider - the database provider for schema and query execution, not null

  • Method Details

    • setDataConverter

      public void setDataConverter(DataConverter dataConverter)
      Sets a custom data converter for transforming query results into chart series data. Replaces the default converter used to produce series points from the rows returned by the configured SQL queries.
      Parameters:
      dataConverter - the data converter to use, not null

    • 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

    • getState

      public ChartState getState()
      Returns the current chart state, including the SQL queries, the chart configuration and the part of it the LLM has set. Returns null if the chart has no data queries.
      Returns:
      the current state, or null

    • restoreState

      public void restoreState(ChartState state)
      Restores a previously saved chart state. Applies the configuration, sets the queries, and re-renders the chart.

      Does not fire state change listeners.

      Parameters:
      state - the state to restore, not null

    • addStateChangeListener

      public Registration addStateChangeListener(SerializableConsumer<ChartState> listener)
      Adds a listener that is notified when the chart state changes after an AI request completes successfully. This is typically used to persist the chart state ? for example by calling getState() and saving the result so that it can be reapplied with restoreState(ChartState) after deserialization.

      The listener is not fired by restoreState(ChartState).

      Parameters:
      listener - the listener, not null
      Returns:
      a registration for removing the listener

    • onResponse

      public void onResponse(ResponseListener.ResponseEvent event)
      Description copied from interface: AIController
      Called when the turn ends: normally when the LLM stream has completed, successfully or with an error, but also when the turn fails before a stream ever opens. The call runs through ui.access(), so the session lock is held and Vaadin thread locals are bound ? though not necessarily on a request thread.

      Fires at most once per prompt. A prompt rejected by the RequestInterceptor ends without firing it, as does a postponed prompt abandoned because its UI was detached. A turn whose UI is detached when it ends also skips the hook, which requires ui.access().

      On success ResponseListener.ResponseEvent.getError() is empty; use the call to commit staged state or run deferred UI updates. On failure it carries the cause (stream error, timeout, or any throw on the prompt path before the stream opens); release per-turn state captured in onRequest (locks, pending writes, snapshots) and discard the staged work. Note that a failure before AIController.onRequest(RequestListener.RequestEvent) ? for example a throwing RequestInterceptor ? also fires this method, so it can run without a preceding onRequest call.

      An error is not the only abnormal ending. A turn cut off at the model's output limit ends with no error at all, and ResponseListener.ResponseEvent.getMetadata() carries the finish reason that tells the two apart ? committing staged state on such a turn applies work the model never finished describing. The finish reason is the underlying framework's own word, so a controller that acts on it decides which values matter to it; see ResponseMetadata.

      The default does nothing. Exceptions thrown from the hook are caught and logged; Errors propagate.

      Specified by:
      onResponse in interface AIController
      Parameters:
      event - the outcome of the turn ? response text, error, and provider metadata ? never null