Adding in natural language queries extension

docs/modules/ROOT/nav.adoc

@@ -29,6 +29,7 @@
 *** xref:user-guide/extensions/advanced-visualizations.adoc[Advanced Visualizations]
 *** xref:user-guide/extensions/rule-based-styling.adoc[Rule-Based Styling]
 *** xref:user-guide/extensions/report-actions.adoc[Report Actions]
+*** xref:user-guide/extensions/natural-language-queries.adoc[Natural Language Queries]
 ** xref:user-guide/faq.adoc[FAQ]
 * xref:developer-guide/index.adoc[Developer Guide]
 ** xref:developer-guide/build-and-run.adoc[Build & Run]
@@ -39,6 +40,7 @@
 ** xref:developer-guide/design.adoc[Design]
 ** xref:developer-guide/adding-visualizations.adoc[Adding Visualizations]
 ** xref:developer-guide/state-management.adoc[State Management]
+** xref:developer-guide/session-storage.adoc[Session Storage]
 ** xref:developer-guide/testing.adoc[Testing]
 ** xref:developer-guide/contributing.adoc[Contributing]
 

docs/modules/ROOT/pages/developer-guide/session-storage.adoc

@@ -0,0 +1,5 @@
+= Session Storage
+
+This reducer serves only to store data that we want to reset at each new session.
+To connect to it, just define a key and use the predefined actions to set a new pair (key,value) inside of it. 
+Inside the actions there is also an action to delete all the keys that match a precise prefix, it can be useful, for example, to wipe the sessionStorage state for a certain extension, if it stores the data inside the sessionStorage using a prefix (for example look at the query-translator extension at getSessionStorageHistoryKey).

docs/modules/ROOT/pages/user-guide/extensions/index.adoc

@@ -16,7 +16,8 @@ The currently available extensions in NeoDash are:
 
 - link:advanced-visualizations[Advanced Visualizations]
 - link:rule-based-styling[Rule-based Styling]
-- link:report-actions[Report Actions (Pro)]
+- link:report-actions[Report Actions]
+- link:natural-language-queries[Natural Language Queries]
 
 == Types of Extensions
 

docs/modules/ROOT/pages/user-guide/extensions/natural-language-queries.adoc

@@ -0,0 +1,63 @@
+= Natural Language Query Generation in NeoDash!
+Use natural language to generate Cypher queries in NeoDash. Connect to an LLM through an API, and let NeoDash use your database schema + the report types to generate queries automatically.
+
+== Natural Language Queries
+Natural Language Queries feature allows users to interact with NeoDash using natural language to generate Cypher queries for querying Neo4j graph databases. 
+This integration leverages Language Models (LLMs) to interpret user inputs and generate Cypher queries based on the provided schema definition.
+
+== Configuration
+To enable Natural Language Queries in NeoDash, follow these configuration steps:
+
+1. Open NeoDash and navigate to the "Extensions" section in the left sidebar.
+2. Locate the "Natural Language Queries" extension and click on it to activate it.
+3. Once activated, a new button will appear in the sidebar(see image below). Click on the button to open the configuration window.
+4. In the configuration window, you will be prompted to provide the necessary information to connect to the Language Model (LLM). Enter the model provider, API key, and select the desired model to use.
+5. After providing the required information, click on the "Start Querying" button to finalize the configuration.
+
+image::extensionbutton.png[Extension Button enables Natural Language Queries button in the sidebar]
+
+image::llmconfiguration.png[Configuration settings for the Natural Language Queries extension]
+
+== Usage
+Once the Natural Language Queries extension is configured, you can start using it in your NeoDash reports. Here's how:
+
+1. Open the Report settings for the desired report.
+2. In the report settings, you will find a toggle switch located above the editor. This switch allows you to toggle between Cypher and English languages.
+3. Since you have enabled the extension and authenticated by providing your API key, you can switch to the English language mode.
+4. Start formulating your queries in plain English, using natural language expressions to describe the data you want to retrieve.
+5. After composing your query, you have two options for further actions:
+
+* Translate: By clicking the "Translate" button, your query will be translated into Cypher using the Language Model. The translated Cypher query will be displayed in the editor when you toggle to the Cypher view. 
+This allows you to review and modify the generated Cypher query before execution.
+* Run: If you wish to directly execute the query and view the results, click the "Run" button in the top right corner. The execution of the query will depend on the selected report type, and the results will be displayed accordingly.
+
+image::englisheditor.png[Example of the English editor in NeoDash]
+
+=== Here is how it works behind the scenes:
+* Retrieve the Schema: The system prompts at the beginning of the interaction to retrieve the database schema. This ensures that the generated queries adhere to the provided schema and available relationship types and properties.
+
+* Prompting in English: Once the schema is retrieved, you can start prompting your queries in plain English. NeoDash, powered by the LLM, will interpret your English query and generate the corresponding Cypher query based on the provided schema.
+
+* Automatic Query Generation: NeoDash automatically generates the Cypher queries for you, taking into account the report type you specified. Whether it's a table, graph, bar chart, line chart, or any other supported report type, the generated queries will retrieve the necessary data based on the report requirements.
+
+* Retry Logic: To enhance the reliability of the generated queries, we have implemented retry logic. If there is any issue or error during the query generation process, the system will attempt to retry three times as a maximum and provide a valid query to ensure smooth query execution.
+
+== Prompting Tips
+
+When using Natural Language Queries in NeoDash, keep the following tips in mind to enhance your experience:
+
+1. Be clear and specific in your queries: Provide detailed descriptions of the data you want to retrieve, including node labels, relationship types, and property values.
+2. Use keywords and phrases: Incorporate relevant keywords and phrases that are commonly used in the context of your data to improve query accuracy.
+3. Ask precise questions: Frame your queries as questions to obtain specific information. For example, instead of "Show me all customers," try "Which customers have made a purchase in the last month?"
+4. Experiment with different phrasings: If you're not getting the desired results, try rephrasing your query using synonyms or alternative expressions.
+5. Avoid ambiguous queries: Ambiguous or vague queries may yield unexpected results. Make sure to provide sufficient context and clarify any ambiguities.
+6. Validate and review generated queries: Always review the generated Cypher queries to ensure they accurately represent your intent and produce the expected results.
+
+
+== Important Considerations
+
+When using Natural Language Queries with Language Models, it's important to be aware of the following considerations:
+
+1. Multiple model providers: Depending on your configuration, your queries may be processed by different model providers. Take into account that this means your data is being sent to different providers.
+2. Non-deterministic nature: Language Models can produce non-deterministic outputs. The generated queries may vary between different runs, even with the same input prompt. Validate the generated queries and perform thorough testing to ensure correctness.
+3. Potential hallucination: Language Models can generate outputs that may not align with the specific schema or data constraints. Exercise caution and verify the results to prevent potential inaccuracies or hallucinations.

package.json

@@ -67,6 +67,7 @@
     "mui-color": "^2.0.0-beta.2",
     "mui-nested-menu": "^3.2.1",
     "neo4j-client-sso": "^1.2.2",
+    "openai": "^3.3.0",
     "postcss": "^8.4.21",
     "postcss-loader": "^7.2.4",
     "postcss-preset-env": "^8.3.0",

public/style.css

@@ -198,3 +198,20 @@
 .cm-tooltip-autocomplete {
   margin-top: 4px;
 }
+
+@keyframes pulse {
+	0% {
+		transform: scale(0.95);
+		box-shadow: 0 0 0 0 rgba(0, 0, 0, 0.7);
+	}
+
+	70% {
+		transform: scale(1);
+		box-shadow: 0 0 0 10px rgba(0, 0, 0, 0);
+	}
+
+	100% {
+		transform: scale(0.95);
+		box-shadow: 0 0 0 0 rgba(0, 0, 0, 0);
+	}
+}

src/application/Application.tsx

@@ -49,6 +49,7 @@ import NeoReportHelpModal from '../modal/ReportHelpModal';
 import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
 import { ThemeProvider } from '@mui/material/styles';
 import lightTheme from '../component/theme/Themes';
+import { resetSessionStorage } from '../sessionStorage/SessionStorageActions';
 
 /**
  * This is the main application component for NeoDash.
@@ -175,6 +176,7 @@ const mapStateToProps = (state) => ({
 const mapDispatchToProps = (dispatch) => ({
   createConnection: (protocol, url, port, database, username, password) => {
     dispatch(setConnected(false));
+    dispatch(resetSessionStorage());
     dispatch(createConnectionThunk(protocol, url, port, database, username, password));
   },
   createConnectionFromDesktopIntegration: () => {

src/card/Card.tsx

@@ -128,6 +128,7 @@ const NeoCard = ({
       <Collapse disablestrictmodecompat='true' in={!settingsOpen} timeout={collapseTimeout} style={{ height: '100%' }}>
         <Card ref={ref} style={{ height: '100%' }}>
           <NeoCardView
+            id={id}
             settingsOpen={settingsOpen}
             editable={editable}
             dashboardSettings={dashboardSettings}
@@ -165,6 +166,8 @@ const NeoCard = ({
       <Collapse disablestrictmodecompat='true' in={settingsOpen} timeout={collapseTimeout}>
         <Card style={{ height: '100%' }}>
           <NeoCardSettings
+            pagenumber={dashboardSettings.pagenumber}
+            reportId={id}
             settingsOpen={settingsOpen}
             query={report.query}
             database={database}

src/card/settings/CardSettings.tsx

@@ -8,6 +8,8 @@ import { CARD_HEADER_HEIGHT } from '../../config/CardConfig';
 
 const NeoCardSettings = ({
   settingsOpen,
+  pagenumber,
+  reportId,
   query,
   database, // Current database related to the report
   databaseList, // List of databases the user can choose from ('system' is filtered out)
@@ -53,6 +55,8 @@ const NeoCardSettings = ({
   // TODO - instead of hiding everything based on settingsopen, only hide the components that slow down render (cypher editor)
   const cardSettingsContent = settingsOpen ? (
     <NeoCardSettingsContent
+      pagenumber={pagenumber}
+      reportId={reportId}
       query={query}
       database={database}
       reportSettings={reportSettings}

src/card/settings/CardSettingsContent.tsx

@@ -2,11 +2,19 @@ import React, { useEffect } from 'react';
 import CardContent from '@mui/material/CardContent';
 import debounce from 'lodash/debounce';
 import { useCallback } from 'react';
-import NeoCodeEditorComponent from '../../component/editor/CodeEditorComponent';
+import NeoCodeEditorComponent, {
+  DEFAULT_CARD_SETTINGS_HELPER_TEXT_STYLE,
+} from '../../component/editor/CodeEditorComponent';
 import { getReportTypes } from '../../extensions/ExtensionUtils';
 import { Dropdown } from '@neo4j-ndl/react';
+import {
+  EXTENSIONS_CARD_SETTINGS_COMPONENT,
+  getExtensionCardSettingsComponents,
+} from '../../extensions/ExtensionConfig';
 
 const NeoCardSettingsContent = ({
+  pagenumber,
+  reportId,
   query,
   database, // Current report database
   databaseList, // List of databases the user can choose from ('system' is filtered out)
@@ -36,6 +44,57 @@ const NeoCardSettingsContent = ({
   const reportTypes = getReportTypes(extensions);
   const SettingsComponent = reportTypes[type] && reportTypes[type].settingsComponent;
 
+  function hasExtensionComponents() {
+    return (
+      Object.keys(EXTENSIONS_CARD_SETTINGS_COMPONENT).filter(
+        (name) => extensions[name] && EXTENSIONS_CARD_SETTINGS_COMPONENT[name]
+      ).length > 0
+    );
+  }
+
+  function updateCypherQuery(value) {
+    debouncedQueryUpdate(value);
+    setQueryText(value);
+  }
+
+  function renderExtensionsComponents() {
+    const res = (
+      <>
+        {Object.keys(EXTENSIONS_CARD_SETTINGS_COMPONENT).map((name) => {
+          const Component = extensions[name] ? EXTENSIONS_CARD_SETTINGS_COMPONENT[name] : '';
+          return Component ? (
+            <Component
+              pagenumber={pagenumber}
+              reportId={reportId}
+              reportType={type}
+              extensions={extensions}
+              cypherQuery={queryText}
+              updateCypherQuery={updateCypherQuery}
+            />
+          ) : (
+            <></>
+          );
+        })}
+      </>
+    );
+    return res;
+  }
+
+  const defaultQueryBoxComponent = (
+    <>
+      <NeoCodeEditorComponent
+        value={queryText}
+        editable={true}
+        language={reportTypes[type] && reportTypes[type].inputMode ? reportTypes[type].inputMode : 'cypher'}
+        onChange={(value) => {
+          updateCypherQuery(value);
+        }}
+        placeholder={`Enter Cypher here...`}
+      />
+      <div style={DEFAULT_CARD_SETTINGS_HELPER_TEXT_STYLE}>{reportTypes[type] && reportTypes[type].helperText}</div>
+    </>
+  );
+
   return (
     <CardContent style={{ paddingTop: '10px', paddingBottom: '10px' }}>
       <Dropdown
@@ -94,31 +153,7 @@ const NeoCardSettingsContent = ({
           onQueryUpdate={onQueryUpdate}
         />
       ) : (
-        <div>
-          <NeoCodeEditorComponent
-            value={queryText}
-            editable={true}
-            language={reportTypes[type] && reportTypes[type].inputMode ? reportTypes[type].inputMode : 'cypher'}
-            onChange={(value) => {
-              debouncedQueryUpdate(value);
-              setQueryText(value);
-            }}
-            placeholder={'Enter Cypher here...'}
-          />
-          <div
-            style={{
-              color: 'grey',
-              fontSize: 12,
-              paddingLeft: '5px',
-              borderBottom: '1px solid lightgrey',
-              borderLeft: '1px solid lightgrey',
-              borderRight: '1px solid lightgrey',
-              marginTop: '0px',
-            }}
-          >
-            {reportTypes[type] && reportTypes[type].helperText}
-          </div>
-        </div>
+        <div>{hasExtensionComponents() ? renderExtensionsComponents() : defaultQueryBoxComponent}</div>
       )}
     </CardContent>
   );

src/card/settings/CardSettingsHeader.tsx

@@ -59,7 +59,7 @@ const NeoCardSettingsHeader = ({
       action={
         <>
           {fullscreenEnabled ? expanded ? unMaximizeButton : maximizeButton : <></>}
-          <Tooltip title='Save' aria-label='save'>
+          <Tooltip title='Run' aria-label='run'>
             <IconButton
               aria-label='save'
               onClick={(e) => {

src/card/view/CardView.tsx

@@ -17,6 +17,7 @@ import { IconButton } from '@neo4j-ndl/react';
 import { PlayCircleIconSolid } from '@neo4j-ndl/react/icons';
 
 const NeoCardView = ({
+  id,
   title,
   database,
   query,
@@ -137,7 +138,7 @@ const NeoCardView = ({
   }, [JSON.stringify(localParameters)]);
 
   useEffect(() => {
-    if (!settingsOpen && selectorChange) {
+    if (!settingsOpen) {
       setLastRunTimestamp(Date.now());
     }
     setSelectorChange(false);
@@ -168,6 +169,7 @@ const NeoCardView = ({
     <CardContent ref={ref} style={cardContentStyle}>
       {active ? (
         <NeoReportWrapper
+          id={id}
           query={query}
           database={database}
           parameters={localParameters}

src/component/editor/CodeEditorComponent.tsx

@@ -3,6 +3,16 @@ import { CypherEditor, CypherEditorProps } from '@neo4j-cypher/react-codemirror'
 import { markdown, markdownLanguage } from '@codemirror/lang-markdown';
 // import { languages } from '@codemirror/language-data';
 
+export const DEFAULT_CARD_SETTINGS_HELPER_TEXT_STYLE = {
+  color: 'grey',
+  fontSize: 12,
+  paddingLeft: '5px',
+  borderBottom: '1px solid lightgrey',
+  borderLeft: '1px solid lightgrey',
+  borderRight: '1px solid lightgrey',
+  marginTop: '0px',
+};
+
 const markdownExtensions = [
   markdown({
     base: markdownLanguage, // Support GFM

src/component/field/Field.tsx

@@ -30,8 +30,8 @@ const NeoField = ({
           onChange: (newValue) => onChange(newValue.value),
           value: value != null ? { label: value, value: value } : { label: defaultValue, value: defaultValue },
           menuPlacement: 'auto',
+          isDisabled: disabled,
         }}
-        disabled={disabled}
         helpText={helperText}
         placeholder={placeholder}
         size={size}

src/dashboard/DashboardThunks.ts

@@ -323,6 +323,8 @@ export function upgradeDashboardVersion(dashboard: any, origin: string, target:
       styling: {
         active: true,
       },
+      active: true,
+      activeReducers: [],
     };
     dashboard.version = '2.3';
 

src/dashboard/drawer/DashboardDrawer.tsx

@@ -48,7 +48,7 @@ export const NeoDrawer = ({
    * are enabled and present a button (EX: node-sidebar)
    * @returns JSX element containing all the buttons related to their enabled extensions
    */
-  function renderDrawerExtensionsButton() {
+  function renderDrawerExtensionsButtons() {
     const res = (
       <>
         {Object.keys(EXTENSIONS_DRAWER_BUTTONS).map((name) => {
@@ -85,20 +85,22 @@ export const NeoDrawer = ({
             dashboardSettings={dashboardSettings}
             updateDashboardSetting={updateDashboardSetting}
             navItemClass={navItemClass}
+            extensions={extensions}
           ></NeoSettingsModal>
 
           <NeoSaveModal navItemClass={navItemClass}></NeoSaveModal>
           <NeoLoadModal navItemClass={navItemClass}></NeoLoadModal>
           <NeoShareModal navItemClass={navItemClass}></NeoShareModal>
           <NeoExtensionsModal navItemClass={navItemClass}></NeoExtensionsModal>
+          {renderDrawerExtensionsButtons()}
           <SideNavigationGroupHeader>Learn</SideNavigationGroupHeader>
           <NeoReportExamplesModal
             extensions={extensions}
             examples={getExampleReports(extensions)}
             database={connection.database}
             navItemClass={navItemClass}
           ></NeoReportExamplesModal>
-          {renderDrawerExtensionsButton()}
+
           <Tooltip title='Documentation' aria-label='documentation'>
             <SideNavigationItem
               href='https://neo4j.com/labs/neodash/2.3/user-guide/'