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. The recommended system prompt is available from getSystemPrompt(). 

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

State changes requested by the LLM are deferred and applied in onRequestCompleted(), 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.

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.

Author:
Vaadin Ltd
See Also:

  • Constructor Details

    • ChartAIController

      public ChartAIController(com.vaadin.flow.component.charts.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

    • getSystemPrompt

      public static String getSystemPrompt()
      Returns the recommended system prompt for chart visualization capabilities. Pass this to AIOrchestrator.builder(LLMProvider, String) so the LLM follows the intended tool-calling workflow.
      Returns:
      the system prompt text

    • getTools

      public List<LLMProvider.ToolSpec> getTools()
      Description copied from interface: AIController
      Returns the tools this controller provides to the LLM.

      Tools are functions that the AI can call to perform actions. Each tool should have a clear name, description, and parameter schema.

      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 and configuration. 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 com.vaadin.flow.shared.Registration addStateChangeListener(com.vaadin.flow.function.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

    • onRequestCompleted

      public void onRequestCompleted()
      Description copied from interface: AIController
      Called by the orchestrator when an LLM request cycle has completed.

      This method is invoked after all tool executions for a given user request have finished and the LLM has generated its final response. Controllers can use this callback to perform deferred operations, such as rendering UI updates or committing state changes.

      Specified by:
      onRequestCompleted in interface AIController