AI advisor plugins

Your file type / metadata editor
    └── @GuiToolbarElement  /  @GuiContextAction
            └── builds AiAdvisorOpenRequest
                    location, areaLabel, artifact, preferFloatingWindow
            └── HopGui.openAiAdvisorSession(request)
                    └── extension point HopGuiAiAdvisorOpenSession
                            └── hop-tech-ai workbench (no-op if the plugin is absent)

Your IAiAdvisor  (@AiAdvisorPlugin)            // omit classLoaderGroup
    └── locations = { "data-vault-graph" }     // same string
    └── buildPrompt(AiAdvisorRequest)          // cast artifact, honour inclusions
    └── optional parseResponse / previewProposal / validate / apply / afterApply / summarizeApplied

@GuiPlugin
public class VaultAiGuiPlugin {

  public static final String LOCATION = "data-vault-graph";

  @GuiToolbarElement(
      root = HopGuiVaultGraph.GUI_PLUGIN_TOOLBAR_PARENT_ID,
      id = "HopGuiVaultGraph-ToolBar-10048-ai-help",
      toolTip = "i18n::HopGuiVaultGraph.Toolbar.AiHelp.Tooltip",
      image = "ai-provider.svg")
  public void openFromToolbar() {
    HopGuiVaultGraph graph = /* active vault graph */;
    if (graph == null || graph.getModel() == null) {
      return;
    }
    open(graph, graph.getModel(), null);
  }

  @GuiContextAction(
      id = "vault-graph-ai-help",
      parentId = HopGuiVaultContext.CONTEXT_ID,
      type = GuiActionType.Modify,
      name = "i18n::HopGuiVaultGraph.AiHelp.Name",
      tooltip = "i18n::HopGuiVaultGraph.AiHelp.Tooltip",
      image = "ai-provider.svg",
      category = "Help",
      categoryOrder = "1")
  public void openFromCanvas(HopGuiVaultContext context) {
    if (context.getVaultGraph() != null) {
      open(context.getVaultGraph(), context.getVaultGraph().getModel(), null);
    }
  }

  private static void open(HopGuiVaultGraph graph, Object model, String focusName) {
    AiAdvisorOpenRequest request = new AiAdvisorOpenRequest();
    request.setAdvisorPluginId("data-vault-advisor");
    request.setLocation(LOCATION);
    request.setAreaLabel("Data Vault");
    request.setPreferFloatingWindow(true);
    request.setArtifact(model);
    request.setArtifactName(model.toString()); // a stable display name
    request.setArtifactKind("data-vault");
    request.setTitle(model.toString());
    request.setFocusNodeName(focusName);
    try {
      graph.getHopGui().openAiAdvisorSession(request);
    } catch (HopException e) {
      // log; the extension point is absent when hop-tech-ai is not installed
    }
  }
}

@AiAdvisorPlugin(
    id = "data-vault-advisor",
    name = "i18n::DataVaultAiAdvisor.Name",
    description = "i18n::DataVaultAiAdvisor.Description",
    image = "ai-provider.svg",
    locations = {"data-vault-graph"})
public class DataVaultAiAdvisor implements IAiAdvisor {

  public static final String ID = "data-vault-advisor";

  @Override
  public String getId() {
    return ID;
  }

  @Override
  public String getName() {
    return BaseMessages.getString(PKG, "DataVaultAiAdvisor.Name");
  }

  @Override
  public String[] getLocations() {
    return new String[] {"data-vault-graph"};
  }

  @Override
  public List<AiAdvisorScenario> listScenarios() {
    return List.of(
        new AiAdvisorScenario("dv-general", "General", "Questions about this vault model"),
        new AiAdvisorScenario("dv-hub", "Hub design", "Business keys and hub grain"));
  }

  @Override
  public List<String> listBaselineSharing() {
    return List.of("model outline");
  }

  @Override
  public List<AiAdvisorInclusion> listInclusions() {
    return List.of(
        new AiAdvisorInclusion(
            "checks",
            "Include model check results",
            false,
            "Validation messages for this model",
            "check results"),
        catalogInclusion(),
        new AiAdvisorInclusion(
            "metadata",
            "Include selected metadata",
            false,
            "JSON of metadata objects the user picks",
            "metadata"));
  }

  private static AiAdvisorInclusion catalogInclusion() {
    AiAdvisorInclusion inclusion =
        new AiAdvisorInclusion(
            "catalog",
            "Include catalog sources",
            false,
            "Record definitions the user picks",
            "catalog sources");
    inclusion.setPicker(true);
    inclusion.setMultiSelect(true);
    return inclusion;
  }

  @Override
  public List<AiAdvisorInclusionChoice> listInclusionChoices(
      String inclusionId, AiAdvisorRequest request) {
    if (!"catalog".equals(inclusionId)) {
      return List.of();
    }
    return List.of(
        new AiAdvisorInclusionChoice("SRC_ORDERS", "Orders"),
        new AiAdvisorInclusionChoice("SRC_CUSTOMER", "Customer"));
  }

  @Override
  public AiAdvisorPrompt buildPrompt(AiAdvisorRequest request) throws HopException {
    if (!(request.getArtifact() instanceof MyVaultModel model)) {
      throw new HopException("No Data Vault model is bound to this session.");
    }
    String system = loadPreambleAndScenario(request.getScenarioId());
    // Context goes in tagged blocks, the question last. The preamble tells the model the blocks
    // are data gathered by Hop, not instructions, and not to mention them in its answer.
    StringBuilder user = new StringBuilder();
    section(user, "model_structure", serializeStructure(model));
    if (request.inclusionEnabled("checks")) {
      section(user, "check_results", serializeChecks(model, request));
    }
    if (request.inclusionEnabled("catalog")) {
      section(user, "catalog_sources", String.valueOf(request.selectedInclusionIds("catalog")));
    }
    // Workbench appends selected metadata when inclusion id is "metadata".
    section(user, "question", request.getUserPrompt());
    return new AiAdvisorPrompt(system, user.toString());
  }

  private static void section(StringBuilder prompt, String tag, String content) {
    prompt.append('<').append(tag).append(">\n").append(content).append("\n</").append(tag);
    prompt.append(">\n\n");
  }
}