### Frontend/Frontend Docs = LLM Knowledge Graph Builder Frontend == Objective This document provides a comprehensive guide for developers on how we build a React application integrated with Neo4j Aura for graph database functionalities. The application allows users to connect to a Neo4j Aura instance and we show you how to automatically create a graph from the unstructured text. We allow users to upload documents locally and from cloud buckets, YouTube videos, and Wikipedia pages, configure a graph schema, extract the lexical, entity and knowledge graph, visualize the extracted graph, ask questions and see the details that were used to generate the answers. == Architecture Structure * For Knowledge Graph builder App: ** React JS – Application logic. ** Axios – for network calls and handling responses ** Styled Components – To handle CSS in JS – Where we write all CSS ourselves, Or Tailwind CSS – 3rd party CSS classes to speed up development. ** LongPooling: Long polling can be conceptualized as the simplest way to maintain a steady connection between a client and a server.It holds the request for a period if it has no response to send it back.It regularly updates clients with new information like updating a status, processed chunks every minute with new data. ** SSEs are the best options when the server generates the data in a loop and sends multiple events to the clients and if we need real-time traffic from the server to the client. == Folders . ├── API ├── Assets ├── Components | ├─ ChatBot | | ├─ Chatbot | | ├─ ChatInfoModal | | ├─ ChatModesSwitch | | ├─ ChatModeToggle | | ├─ ChatOnlyComponent | | ├─ ChatInfo | | ├─ CommonChatActions | | ├─ CommunitiesInfo | | ├─ EntitiesInfo | | ├─ ExpandedChatButtonContainer | | ├─ MetricsCheckbox | | ├─ MetricsTab | | ├─ MultiModeMetrics | | ├─ SourcesInfo | ├─ Data Sources | | ├─ AWS | | ├─ GCS | | ├─ Local | | ├─ Web | | | ├─ WebButton | ├─ Graph | | ├─ CheckboxSelection | | ├─ GraphPropertiesPanel | | ├─ GraphPropertiesTable | | ├─ GraphViewButton | | ├─ GraphViewModal | | ├─ LegendsChip | | ├─ ResizePanel | | ├─ ResultOverview | ├─ Layout | | ├─ AlertIcon | | ├─ DrawerChatbot | | ├─ DrawerDropzone | | ├─ Header | | ├─ PageLayout | | ├─ SideNav | ├─ Popups | | ├─ ChunkPopUp | | ├─ ConnectionModal | | ├─ DeletePopup | | ├─ GraphEnhancementDialog | | ├─ LargeFilePopup | | ├─ RetryConfirmation | | ├─ Settings | ├─ UI | | ├─ Alert | | ├─ ButtonWithTooltip | | |─ BreakDownPopOver | | ├─ CustomButton | | ├─ CustomCheckBox | | ├─ CustomMenu | | ├─ CustomPopOver | | ├─ CustomProgressBar | | ├─ DatabaseIcon | | ├─ DatabaseStatusIcon | | ├─ Dropdown | | ├─ ErrorBoundary | | ├─ FallBackDialog | | ├─ HoverableLink | | ├─ IconButtonTooltip | | ├─ Legend | | ├─ ScienceMolecule | | ├─ ShowAll | | ├─ TipWrapper | ├─ Websources | | ├─ Web | | ├─ Wikipedia | | ├─ Youtube | | ├─ CustomSourceInput | | ├─ GenericSourceButton | | ├─ GenericSourceModal | ├─ Content | ├─ FileTable | ├─ QuickStarter ├── HOC | ├─ CustomModal | ├─ withVisibility ├── Assets | ├─ images | | ├─ Application Images | ├─ chatbotMessages.json | ├─ schema.json ├── Context | ├─ Alert | ├─ ThemeWrapper | ├─ UserCredentials | ├─ UserMessages | ├─ UserFiles ├── HOC | ├─ CustomModal | ├─ WithVisibility ├── Hooks | ├─ useSourceInput | ├─ useSpeech | ├─ useSSE ├── Services ├── Styling | ├─ info ├── Utils | ├─ constants | ├─ FileAPI | ├─ Loader | ├─ Queue | ├─ toats | ├─ utils ├── App ├── index ├── main ├── router ├── types └── README.md == Application == 1. Setup and Installation: Added Node.js with version v21.1.0 and npm on the development machine. Install necessary dependencies by running yarn install, such as axios for making HTTP requests and others to interact with the graph. == 2. Connect to the Neo4j Aura instance: Created a connection modal by adding details including protocol, URI, database name, username, and password. Added a submit button that triggers an API: ***/connect*** and accepts params like uri, password, username and database to establish a connection to the Neo4j Aura instance. Handled the authentication and error scenarios appropriately, by displaying relevant messages. To check whether the backend connection is up and working we hit the API: ***/health.*** The user can now access both AURA DS and AURA DB instances. * If GDS Connection is there icon is scientific molecule > Graph settings model > Post processing jobs > gives user the leverage to check and uncheck the communities checkbox. * If AURA DB > icon is database icon > Graph settings model > Post processing jobs > communities checkbox is disabled. image::images/ConnectionModal.jpg[NoConnection, 600] * ** Aura DS Connection ** image::images/GraphDBConnection.jpg[Connection, 600] * ** Aura DB connection ** image::images/AuraDBConnection.jpg[Connection, 600] * **ReadOnly User** image::images/ReadOnlyUser.jpg[ReadOnlyUser, 600] * **User not connected** image::images/NoConnection.jpg[User not Connection, 600] == 3. File Source integration: Implemented various file source integrations including drag-and-drop, web sources search that includes YouTube video, Wikipedia link, Amazon S3 file access, and Google Cloud Storage (GCS) file access. This allows users to upload PDF files from local storage or directly from the integrated sources. The Api’s are as follows: * ***/source_list:*** to fetch the list of files in the DB image::images/WithData.jpg[Connected, 600] * ***/upload:*** to upload files from Local image::images/UploadLocalFile.jpg[Local File, 600] * ***/url/scan:*** to scan the link or sources of YouTube, Wikipedia, and Web Sources image::images/WebSources.jpg[WebSources, 600] * ***/url/scan:*** to scan the files of S3 and GCS. 1) Add the respective Bucket URL, access key and secret key to access S3 files. image::images/S3BucketScan.jpg[S3 scan, 600] 2) Add the respective Project ID, Bucket name, and folder to access GCS files. image::images/GCSbucketFiles.jpg[GCS scan, 600] 3) User gets a redirect to the authentication page to authenticate their google account. image::images/Gcloud_auth.jpg[auth login scan, 600] == 4. File Source Extraction: * ***/extract*** to fetch the number of nodes and relationships created. *** During Extraction the selected files or all files in ‘New’ state go into ‘Processing’ state and then ‘Completed’ state if there are no failures. image::images/GenerateGraph.jpg[Generate Graph, 600] 1) A file with status Completed has an option to be Reprocess with the following options : image::images/CompletedReadyToReprocess.jpg[CompletedReadyToReprocess, 600] 2) A file with status Failed/ Cancelled has an option to be Reprocess with the following options : image::images/FailedReadyToReprocess.jpg[FailedReadyToReprocess, 600] == 5. Graph Generation: * ***/graph_query:*** *** Created a component for generating graphs based on the files in the table, to extract nodes and relationships. When the user clicks on the Preview Graph or on the Table View icon the user can see that the graph model holds three options for viewing: Lexical Graph, Entity Graph and Knowledge Graph. We utilized Neo4j's graph library to visualize the extracted nodes and relationships in the form of a graph query API: ***/graph_query***. There are options for customizing the graph visualization such as layout algorithms [zoom in, zoom out, fit, refresh], node styling, relationship types. * **Preview Graph** image::images/AllFilesGraph.jpg[AllFiles Graph, 600] * **File Graph** image::images/SingleFileQuery.jpg[Single File Graph, 600] * **Graph Types** 1) Document & Chunk image::images/DocChunkGraph.jpg[Knowledge Graph, 600] 2) Entities image::images/EntitiesGraph.jpg[Entity Graph, 600] 3) Communities image::images/CommunitiesGraph.jpg[Community Graph, 600] * ***/get_neighbours:*** ** This API is used to retrive the neighbor nodes of the given element id of the node. image::images/NeighbourNodeDisconnected.jpg[Neighbourhood Graph, 600] == 6. Chatbot: Created a Chatbot Component which has state variables to manage user input and chat messages. Once the user asks the question and clicks on the Ask button API: ***/chatbot*** is triggered to send user input to the backend and receive the response. The chat also has options for users to see more details about the chat, text to speech and copy the response. * **Chat Drawer View** image::images/ChatBotSideView.jpg[ChatBotSideView, 600] * **Chat Modal View** image::images/ChatBotModalView.jpg[ChatBotModalView, 600] * **Chat Pop out View** image::images/ChatBotNewURL.jpg[ChatBotNewURL, 600] * ***/clear_chat_bot:*** ** to clear the chat history which is saved in Neo4j DB. image::images/ClearChatHistory.jpg[ClearChatHistory, 600] * ***/chunk_entities:*** ** to fetch the number of sources, entities and chunks ***Sources*** image::images/Sources.jpg[Sources, 600] ***Entities*** image::images/EntitiesInfo.jpg[EntitiesInfo, 600] ***Chunks*** image::images/ChunksInfo.jpg[ChunksInfo, 600] * ***/metric:*** ** The API responsible for a evaluating chatbot responses on the basis of different metrics such as faithfulness and answer relevancy. This utilises RAGAS library to calculate these metrics. image::images/MetricEval.jpg[MetricEval, 600] * ***/additional_metrics:*** ** The API responsible for a evaluating chatbot responses on the basis of different metrics such as context entity recall, semantic score, rouge score. This reuqire additional ground truth to be supplied by user. This utilises RAGAS library to calculate these metrics. image::images/AdditionalMetricEval.jpg[AdditionalMetricEval, 600] ***Chat Modes*** * There are five modes ***Vector***, ***Fulltext***, ***Graph+Vector+Fulltext***, ***Entity search+Vector***, ***Graph+Vector+Fulltext*** that can be provided to the chat to retrieve the answers in ***Production*** environment. * There is one more mode ***Graph*** that can be provided to the chat to retrieve the answers in ***Development*** environment. * There is one more mode ***Global search+Vector+Fulltext*** that can be provided to the chat to retrieve the answers if aura instance is ***GDS***. 1) In Production Environment image::images/ChatModesProd.jpg[ChatModesProd, 600] 2) In Development Environment image::images/ChatModesDev.jpg[ChatModesDev, 600] == 7. Graph Settings: Users can now set their own Schema for nodes and relations or can already be an existing schema. * ***Entity Extraction Settings:*** image::images/GraphEnhancements.jpg[GraphEnhancements, 600] * ***/schema:*** ** to fetch the existing schema that already exists in the db. image::images/Schema.jpg[PredefinedSchema, 600] * ***/populate_graph_schema:*** ** to fetch the schema from user entered document text image::images/UserDefinedSchema.jpg[UserDefinedSchema, 600] * ***Processing Configuration:*** image::images/ProcessingConfiguration.jpg[ProcessingConfiguration, 600] * ***/change_embedding_model:*** **Displays the list of available embedding models for vector generation. image::images/EmbeddingModelDropdown.jpg[Embedding Model Dropdown, 600] * ***Apply Button with Updated Configuration:*** Saves the updated processing and embedding configuration. image::images/ProcessingConfigurationUpdated.jpg[Processing Configuration Updated, 600] * ***/delete_unconnected_nodes:*** ** to remove the lonely entities. image::images/DeleteOrphanNodes.jpg[DeleteOrphanNodes, 600] * ***/merge_duplicate_nodes:*** 1) to merge the duplicate entities. image::images/MergeDuplicateEntities.jpg[MergeDuplicateEntities, 600] 2) to get duplicate entities image::images/GetDuplicateNodes.jpg[GetDuplicateNodes, 600] * ***/post_processing :*** to fine-tune the knowledge graph for improved performance and deeper analysis 1) When GDS instance image::images/PostProcessingDB.jpg[PostProcessingDB, 600] 2) When Aura DB instance image::images/PostProcessingDB.jpg[PostProcessingDB, 600] == 8. Application Options: * ***LLM Model*** User can select desired LLM models image::images/Dropdown.jpg[Dropdown, 600] * ***Documentation***: User can navigate to the application overview : https://neo4j.com/labs/genai-ecosystem/llm-graph-builder/ image::images/LLMGraphBuilderDocumentation.jpg[LLMGraphBuilderDocumentation, 600] * ***GitHub Issues***: User can navigate to the gitHub issues which are in developers bucket list : https://github.com/neo4j-labs/llm-graph-builder/issues image::images/GitHubIssues.jpg[GitHubIssues, 600] * ***Dark/Light Mode***: User can choose the application view : both in dark and light mode 1) Dark image::images/DarkMode.jpg[DarkMode, 600] 2) Light image::images/LightMode.jpg[LightMode, 600] * ***Chat Only Mode*** User can also use the chat only feature by navigating to the url at: https://llm-graph-builder.neo4jlabs.com/chat-only to ask questions related to documents which have been completely processed. User is required to pass the login credentials to connect to the database. == 9. File Table Options: User can explore various features available for files in the table, including sorting, filtering, viewing as a graph, examining nodes and relationships, copying file details, and accessing chunks related to the file. ***File Status*** image::images/FileStatus.jpg[FileStatus, 600] ***File Nodes*** image::images/FileNodes.jpg[FileNodes, 600] ***File Relationships*** image::images/FileRelationships.jpg[FileRelationships, 600] ***File Actions*** ** ***Graph View*** image::images/GraphActions.jpg[GraphActions, 600] ** ***Copy File Data*** image::images/CopyFileData.jpg[CopyFileData, 600] ** ***Text Chunks*** image::images/TextChunks.jpg[TextChunks, 600] == 10. Interface Design: Designed a user-friendly interface that guides users through the process of connecting to Neo4j Aura, accessing file sources, uploading PDF files, and generating graphs. * ***Components:*** @neo4j-ndl/react * ***Icons:*** @neo4j-ndl/react/icons * ***Graph Visualization:*** @neo4j-nvl/react. * ***NVL:*** @neo4j-nvl/core * ***CSS:*** Inline styling, tailwind CSS == 11. Deployment: Followed best practices for optimizing performance and security of the deployed application. * ***Local Deployment:*** ** Running through docker-compose ** By default only OpenAI and Diffbot are enabled since Gemini requires extra GCP configurations. ** In your root folder, create a .env file with your OPENAI and DIFFBOT keys (if you want to use both), ** By default, the input sources will be: Local files, Youtube, Wikipedia ,AWS S3 and Webpages. As this default config is applied: ** By default,all of the chat modes will be available: vector, graph+vector and graph. If none of the mode is mentioned in the chat modes variable all modes will be available: ** You can then run Docker Compose to build and start all components: [source,indent=0] ---- * VITE_LLM_MODELS="" * VITE_REACT_APP_SOURCES="" * VITE_GOOGLE_CLIENT_ID="xxxx" [For Google GCS integration] * VITE_CHAT_MODES="" * VITE_CHUNK_SIZE=5242880 * VITE_TIME_PER_PAGE=50 * VITE_LARGE_FILE_SIZE=5242880 * VITE_ENV="PROD"/ ‘DEV’ * VITE_BACKEND_API_URL= * VITE_BLOOM_URL= * VITE_BACKEND_PROCESSING_URL= * VITE_LLM_MODELS_PROD="openai_gpt_5.4_mini,diffbot,gemini_3.5_flash,anthropic_claude_4.5_haiku" * VITE_BATCH_SIZE=2 ---- ** If you enable `fireworks_qwen3_6` in `VITE_LLM_MODELS`, configure the backend env key `LLM_MODEL_CONFIG_FIREWORKS_QWEN3_6` to use the Fireworks serverless slug `accounts/fireworks/models/qwen3p6-plus`. * ***Cloud Deployment:*** ** To deploy the app install the gcloud cli , run the following command in the terminal specifically from frontend root folder. *** gcloud run deploy *** source location current directory > Frontend *** region : 32 [us-central 1] *** Allow unauthenticated request : Yes == 12. API Reference === 1) Connection Modal ----- POST /connect ----- Neo4j database connection on frontend is done with this API. **API Parameters :** * `uri`= Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name === 2) Backend Database connection ---- POST /backend_connection_configuration ---- The API responsible for create the connection obj from Neo4j DB based on environment variable and return the status for show/hide login dialog on UI === 3) Get Token Limits ---- POST /get_token_limits ---- This API retrieves the token usage limits or quota available for the configured LLM provider. It is used by the frontend to determine remaining usage and adjust model availability or warnings. **API Parameters :** * `uri` = Neo4j URI *`userName` = Neo4j database username *`password` = Neo4j database password *`database` = Neo4j database name *`email` = (Optional) Registered email for the LLM provider account === 4) Fetch Embedding Models ---- POST /fetch_embedding_model ---- Retrieves the list of available embedding providers and embedding models that the user can select in the Processing Configuration panel. **API Parameters :** * `uri` = Neo4j URI * `userName` = Neo4j database username * `password` = Neo4j database password * `database` = Neo4j database name * `email` = User email for model permissions (optional) === 5) Upload Files from Local ---- POST /upload ---- The upload endpoint is designed to handle the uploading of large files by breaking them into smaller chunks. This method ensures that large files can be uploaded efficiently without overloading the server. **API Parameters :** * `file`=The file to be uploaded, received in chunks, * `chunkNumber`=The current chunk number being uploaded, * `totalChunks`=The total number of chunks the file is divided into (each chunk of 1Mb size), * `originalname`=The original name of the file, * `model`=The model associated with the file, * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name === 6) User Defined Schema ---- POST /schema ---- User can set schema for graph generation (i.e. Nodes and relationship labels) in settings panel or get existing db schema through this API. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name === 7) Graph schema from Input Text ---- POST /populate_graph_schema ---- The API is used to populate a graph schema based on the provided input text, model, and schema description flag. **API Parameters :** * `input_text`=The input text used to populate the graph schema. * `model`=The model to be used for populating the graph schema. * `is_schema_description_checked`=A flag indicating whether the schema description should be considered. === 8) Unstructured Sources ---- POST /url/scan ---- Create Document node for other sources - s3 bucket, gcs bucket, wikipedia, youtube url and web pages. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name * `model`= LLM model, * `source_url`= , * `aws_access_key_id`= AWS access key, * `aws_secret_access_key`= AWS secret key, * `wiki_query`= Wikipedia query sources, * `gcs_project_id`= GCS project id, * `gcs_bucket_name`= GCS bucket name, * `gcs_bucket_folder`= GCS bucket folder, * `source_type`= s3 bucket/ gcs bucket/ youtube/Wikipedia as source type * `gcs_project_id`=Form(None), * `access_token`=Form(None) === 9) Extration of Nodes and Relations from Data ---- POST /extract ---- This API is responsible for - ** Reading the content of source provided in the form of langchain Document object from respective langchain loaders ** Dividing the document into multiple chunks, and make below relations - *** PART_OF - relation from Document node to all chunk nodes *** FIRST_CHUNK - relation from document node to first chunk node *** NEXT_CHUNK - relation from a chunk pointing to next chunk of the document. *** HAS_ENTITY - relation between chunk node and entities extracted from LLM. ** Extracting nodes and relations in the form of GraphDocument from respective LLM. ** Update embedding of chunks and create vector index. ** Update K-Nearest Neighbors graph for similar chunks. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name * `model`= LLM model, * `file_name` = File uploaded from device * `source_url`= , * `aws_access_key_id`= AWS access key, * `aws_secret_access_key`= AWS secret key, * `wiki_query`= Wikipedia query sources, * `gcs_project_id`=GCS project id, * `gcs_bucket_name`= GCS bucket name, * `gcs_bucket_folder`= GCS bucket folder, * `gcs_blob_filename` = GCS file name, * `source_type`= local file/ s3 bucket/ gcs bucket/ youtube/ Wikipedia as source, allowedNodes=Node labels passed from settings panel, * `allowedRelationship`=Relationship labels passed from settings panel, * `language`=Language in which wikipedia content will be extracted === 10) Get list of sources ---- GET /sources_list ---- List all sources (Document nodes) present in Neo4j graph database. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name === 11) Post processing after graph generation ---- POST /post_processing : ---- This API is called at the end of processing of whole document to get create k-nearest neighbor relations between similar chunks of document based on KNN_MIN_SCORE which is 0.8 by default and to drop and create a full text index on db labels. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name * `tasks`= List of tasks to perform === 12) Chat with Data ---- POST /chat_bot ---- The API responsible for a chatbot system designed to leverage multiple AI models and a Neo4j graph database, providing answers to user queries. It interacts with AI models from OpenAI and Google's Vertex AI and utilizes embedding models to enhance the retrieval of relevant information. **Components :** ** Embedding Models - Includes OpenAI Embeddings, VertexAI Embeddings, BedrockEmbeddings and SentenceTransformer Embeddings(Default) to support vector-based query operations. ** Embedding Models - Includes OpenAI Embeddings, VertexAI Embeddings, and SentenceTransformer Embeddings to support vector-based query operations. ** AI Models - OpenAI GPT 5 mini, gemini_flash_latest, anthropic claude 4.5 haiku can be configured for the chatbot backend to generate responses and process natural language. ** Graph Database (Neo4jGraph) - Manages interactions with the Neo4j database, retrieving, and storing conversation histories. ** Response Generation - Utilizes Vector Embeddings from the Neo4j database, chat history, and the knowledge base of the LLM used. **API Parameters :** * `uri`= Neo4j uri * `userName`= Neo4j database username * `password`= Neo4j database password * `model`= LLM model * `question`= User query for the chatbot * `session_id`= Session ID used to maintain the history of chats during the user's connection === 13) Get entities from chunks ---- POST/chunk_entities ---- This API is used to get the entities and relations associated with a particular chunk and chunk metadata. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name * `chunk_ids` = Chunk ids of document === 14) Clear chat history ---- POST /clear_chat_bot ---- This API is used to clear the chat history which is saved in Neo4j DB. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `session_id` = User session id for QA chat === 15) View graph for a file ---- POST /graph_query ---- This API is used to view graph for a particular file. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `query_type`= Neo4j database name * `document_names` = File name for which user wants to view graph === 16) Get neighbour nodes ---- POST /get_neighbours ---- This API is used to retrive the neighbor nodes of the given element id of the node. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `elementId` = Element id of the node to retrive its neighbours === 17) SSE event to update processing status ---- GET /update_extract_status ---- The API provides a continuous update on the extraction status of a specified file. It uses Server-Sent Events (SSE) to stream updates to the client. **API Parameters :** * `file_name`=The name of the file whose extraction status is being tracked, * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name ---- GET /document_status ---- The API gives the extraction status of a specified file. It uses Server-Sent Events (SSE) to stream updates to the client. **API Parameters :** * `file_name`=The name of the file whose extraction status is being tracked, * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name === 18) Delete selected documents ---- POST /delete_document_and_entities ---- Deleteion of nodes and relations for multiple files is done through this API. User can choose multiple documents to be deleted, also user have option to delete only 'Document' and 'Chunk' nodes and keep the entities extracted from that document. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `filenames`= List of files to be deleted, * `source_types`= Document sources(Wikipedia, youtube, etc.), * `deleteEntities`= Boolean value to check entities deletion is requested or not === 19) Cancel processing job ---- POST/cancelled_job ---- This API is responsible for cancelling an in process job. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `filenames`= Name of the file whose processing need to be stopped, * `source_types`= Source of the file === 20) Deletion of orpahn nodes ---- POST /delete_unconnected_nodes ---- The API is used to delete unconnected entities from database. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `unconnected_entities_list`=selected entities list to delete of unconnected entities. === 21) Get the list of orphan nodes ---- POST /get_unconnected_nodes_list ---- The API retrieves a list of nodes in the graph database that are not connected to any other nodes. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name === 22) Get duplicate nodes ---- POST /get_duplicate_nodes ---- The API is used to fetch duplicate entities from database. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, === 23) Merge duplicate nodes ---- POST /merge_duplicate_nodes ---- The API is used to merge duplicate entities from database selected by user. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `duplicate_nodes_list`= selected entities list to merge of with similar entities. === 24) Change embedding model ---- POST /change_embedding_model ---- This API is used to change the embedding model and/or embedding provider in the backend. **API Parameters :** * `uri` = Neo4j URI, * `userName` = Neo4j db username, * `password` = Neo4j db password, * `database` = Neo4j db name, * `embedding_provider` = Selected embedding provider (e.g., openai, bedrock, vertexai, sentence_transformer), * `embedding_model` = Name of the selected embedding model, === 25) Drop and create vector index ---- POST /drop_create_vector_index ---- The API is used to drop and create the vector index when vector index dimesion are different. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `isVectorIndexExist`= True or False based on whether vector index exist in database, * `embedding_provider`= Embedding provider selected by user * `embedding_model`= Embedding model selected by user === 26) Reprocessing of sources ---- POST /retry_processing ---- This API is used to Ready to Reprocess cancelled, completed or failed file sources. Users have 3 options to Ready to Reprocess files: * Start from begnning - In this condition file will be processed from the begnning i.e. 1st chunk again. * Delete entities and start from begnning - If the file source is already processed and have any existing nodes and relations then those will be deleted and file will be reprocessed from the 1st chunk. * Start from last processed postion - Cancelled or failed files will be processed from the last successfully processed chunk position. This option is not available for completed files. Ones the status is set to 'Ready to Reprocess', user can again click on Generate graph to process the file for knowledge graph creation. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `file_name`= Name of the file which user want to Ready to Reprocess. * `retry_condition` = One of the above 3 conditions which is selected for reprocessing. == 13. Conclusion: In conclusion, this technical document outlines the process of building a React application with Neo4j Aura integration for graph database functionalities. == 14. Referral Links: * Dev env : https://dev-frontend-dcavk67s4a-uc.a.run.app/ * Staging env: https://staging-frontend-dcavk67s4a-uc.a.run.app/ * Prod env: https://prod-frontend-dcavk67s4a-uc.a.run.app/ --- ### Backend/Backend Docs = LLM Knowledge Graph Builder Backend == API Reference === Connect to Neo4j Graph Database ----- POST /connect ----- This API is used to authenticate and connect frontend to backend using NEO4j database credential. Based on the response from this API, the frontend UI displays the connection status and the database type icon, such as GDS DB or Aura DB. **API Parameters :** * `uri`= Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `email`= Logged in User Email **Response :** [source,json,indent=0] ---- { "status": "Success", "data": { "db_vector_dimension": 384, "application_dimension": 384, "message": "Connection Successful", "gds_status": true, "write_access": true, "elapsed_api_time": "1.52", "gcs_file_cache": "True" } } ---- === Get Token Limits ---- POST /get_token_limits ---- Fetches the token usage limits/quota for the configured LLM provider (OpenAI, Gemini, Anthropic, etc.) for the logged‑in user. **API Parameters :** * `uri` = Neo4j URI * `userName` = Neo4j database username * `password` = Neo4j database password * `database` = Neo4j database name * `email` = Logged in User Email **Response :** [source,json,indent=0] ---- { "status": "Success", "data": { "daily_remaining": 250000, "monthly_remaining": 815234, "daily_limit": 250000, "monthly_limit": 1000000, "daily_used": 0, "monthly_used": 184766 }, "message": "Token limits fetched successfully" } ---- === Fetch Embedding Models ---- POST /fetch_embedding_model ---- This API returns the currently selected embedding provider, embedding model, embedding dimension, and whether the vector index needs to be recreated. **API Parameters :** * `uri` = Neo4j URI * `userName` = Neo4j database username * `password` = Neo4j database password * `database` = Neo4j database name * `email` = Logged in User Email **Response :** [source,json,indent=0] ---- { "status": "Success", "data": [ "openai", "text-embedding-3-small", 1536, true ] } ---- === Upload Files from Local ---- POST /upload ---- This API handles the uploading of large files by breaking them into smaller chunks. This method ensures that large files can be uploaded efficiently without overloading the server. ***API Parameters*** * `file`=The file to be uploaded, received in chunks, * `chunkNumber`=The current chunk number being uploaded, * `totalChunks`=The total number of chunks the file is divided into (each chunk of 1Mb size), * `originalname`=The original name of the file, * `model`=The model associated with the file, * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "file_size": 393322, "file_name": "Untitled Diagram.png", "file_extension": "png", "message": "Chunk 1/1 saved" }, "message": "Source Node Created Successfully" } .... === User defined schema ---- POST /schema ---- This API gets the labels and relationships from existing Neo4j database data. Users can set the schema for graph generation (i.e., nodes and relationship labels) in the settings panel. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "triplets": [ "Location-HAS_DIPLOMATIC_MISSIONS->Entity", "Location-FORMED->Alliance", "Company-HAS_TECH_ROLE_COMPOSITION->Demographic", "Objective-INCLUDES->Feature", "Location-IS_LARGEST_URBAN_AREA_OF->Location", "Country-DECLARED_AS->Government Type", "Ecoregion-LOCATED_IN->Region", "Organization-SUFFERED_CASUALTIES->Number", "Company-HAS->Judicial System", "Organization-ELECTED_BY->Legislative Body", "Location-TOOK_IN->Population Group", "Location-NUMBER_OF->Count", "Organization-PROVIDES->Infrastructure", "Location-HAS->Team", "Country-FOCUSES_ON->Category" ] }, "message": "Total elapsed API time 1.56" } .... === Graph schema from input text ---- POST /populate_graph_schema ---- The API is used to populate a graph schema based on the provided input text, model, and schema description flag. **API Parameters :** * `input_text`=The input text used to populate the graph schema. * `model`=The model to be used for populating the graph schema. * `is_schema_description_checked`=A flag indicating whether the schema description should be considered. * `is_local_storage`= Generate the generalized graph schema based on input text if value is false * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "triplets": [ "User-PURCHASES->Product", "Product-SOLD_BY->Store", "Product-HAS->Warranty" ] } } .... === Unstructured sources scan other than local ---- POST /url/scan ---- This API creates Document source nodes for all supported sources, including S3 buckets, GCS buckets, Wikipedia, web pages, YouTube videos, and local files **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name * `model`= LLM model, * `source_url`= , * `aws_access_key_id`= AWS access key, * `aws_secret_access_key`= AWS secret key, * `wiki_query`= Wikipedia query sources, * `gcs_project_id`= GCS project id, * `gcs_bucket_name`= GCS bucket name, * `gcs_bucket_folder`= GCS bucket folder, * `source_type`= s3 bucket/ gcs bucket/ youtube/Wikipedia as source type * `gcs_project_id`=Form(None), * `access_token`=Form(None), * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "elapsed_api_time": "3.22" }, "success_count": 1, "failed_count": 0, "message": "Source Node created successfully for source type: Wikipedia and source: ", "file_name": [ { "fileName": "Google_DeepMind", "fileSize": 8074, "url": "https://en.wikipedia.org/wiki/Google_DeepMind", "language": "en", "status": "Success" } ] } .... === Extration of nodes and relations from content ---- POST /extract : ---- This API is responsible for - ** Reading the content of source provided in the form of langchain Document object from respective langchain loaders ** Dividing the document into multiple chunks, and make below relations - *** PART_OF - relation from Document node to all chunk nodes *** FIRST_CHUNK - relation from document node to first chunk node *** NEXT_CHUNK - relation from a chunk pointing to next chunk of the document. *** HAS_ENTITY - relation between chunk node and entities extracted from LLM. ** Extracting nodes and relations in the form of GraphDocument from respective LLM. ** Update embedding of chunks and create vector index. ** Update K-Nearest Neighbors graph for similar chunks. **Implementation :** ** For multiple sources of content - *** Local file - User can upload pdf file from their device. *** s3 bucket - User passes the bucket url and all the pdf files inside folders and subfolders will be listed. *** GCS bucket - User passes gcs project id, gcs bucket name and folder name, do google authentication to access all the pdf files under that folder and its subfolders and if folder name is not passed by user, all the pdf files under the bucket and its subfolders will be listed if user have read access of the bucket. *** Web Sources - **** Wikipedia - Wikipedia 1st page content is rendered url passed by user. **** Youtube - Youtube video transcript is processed and if no transcript is available then respective error is thrown. **** Web urls - Text Content from any web url is processed for generating graph. ** Langchain's LLMGraphTransformer library is used to get nodes and relations in the form of GraphDocument from LLMs. User and System prompts, LLM chain, graphDocument schema are defined in the library itself. ** SentenceTransformer embeddingds are used by default, also embeddings are made configurable to use either OpenAIEmbeddings or VertexAIEmbeddings. ** Vector index is created in database on embeddingds created for chunks. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name * `model`= LLM model, * `file_name` = File uploaded from device * `source_url`= , * `aws_access_key_id`= AWS access key, * `aws_secret_access_key`= AWS secret key, * `wiki_query`= Wikipedia query sources, * `gcs_project_id`=GCS project id, * `gcs_bucket_name`= GCS bucket name, * `gcs_bucket_folder`= GCS bucket folder, * `gcs_blob_filename` = GCS file name, * `source_type`= local file/ s3 bucket/ gcs bucket/ youtube/ Wikipedia as source, * `allowedNodes=Node labels passed from settings panel, * `allowedRelationship`=Relationship labels passed from settings panel, * `token_chunk_size`= chunk split size, * `chunk_overlap`= numric value of chunk overlap, * `chunks_to_combine`= value of combine chunks to process for extraction, * `language`=Language in which wikipedia content will be extracted, * `retry_condition`= re-process the file based on selection, * `additional_instructions`= additional instruction for LLM while extraction, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "fileName": "Untitled Diagram.png", "nodeCount": 19, "relationshipCount": 33, "total_processing_time": 15.91, "status": "Completed", "model": "openai_gpt_4.5", "success_count": 1, "chunkNodeCount": 5, "chunkRelCount": 23, "entityNodeCount": 14, "entityEntityRelCount": 10, "communityNodeCount": 0, "communityRelCount": 0, "db_url": "neo4j+s://demo.neo4jlabs.com:7687", "api_name": "extract", "source_url": null, "wiki_query": null, "source_type": "local file", "logging_time": "2025-04-10 17:06:17 UTC", "elapsed_api_time": "30.65", "userName": "persistent", "database": "persistent1", "aws_access_key_id": null, "gcs_bucket_name": null, "gcs_bucket_folder": null, "gcs_blob_filename": null, "gcs_project_id": null, "language": null, "retry_condition": "", "email": null, "create_connection": "0.29", "create_list_chunk_and_document": "1.75", "total_chunks": 5, "get_status_document_node": "0.06", "update_source_node": "0.50", "processed_combine_chunk_0-5": "12.85", "processed_chunk_detail_0-5": { "update_embedding": "0.74", "entity_extraction": "6.54", "save_graphDocuments": "4.81", "relationship_between_chunk_entity": "0.56" }, "Processed_source": "16.40", "Per_entity_latency": "0.8421052631578947/s" }, "file_source": "local file" } .... === Get list of sources ---- POST /sources_list ---- List all sources (Document nodes) present in Neo4j graph database. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": [ { "fileName": "About Amazon.pdf", "fileSize": 163931, "errorMessage": "", "fileSource": "local file", "nodeCount": 62, "model": "OpenAI GPT 4", "fileType": "pdf", "processingTime": 122.71, "relationshipCount": 187, "status": "Completed", "updatedAt": { "_DateTime__date": { "_Date__ordinal": 738993, "_Date__year": 2024, "_Date__month": 4, "_Date__day": 17 }, "_DateTime__time": { "_Time__ticks": 28640715768000, "_Time__hour": 7, "_Time__minute": 57, "_Time__second": 20, "_Time__nanosecond": 715768000, "_Time__tzinfo": null } } } ], "message": "Total elapsed API time 3.20" } .... === Post processing after graph generation ---- POST /post_processing : ---- This API is called at the end of document processing to create k-nearest neighbor relationships between similar chunks of documents based on KNN_MIN_SCORE, which is 0.8 by default, compute community clusters, generate community summaries, and recreate a full-text index on all labels in the database so Neo4j Bloom can make use of it. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name * `tasks`= List of tasks to perform, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": [ { "filename": "Google", "chunkNodeCount": 100, "chunkRelCount": 1310, "entityNodeCount": 670, "entityEntityRelCount": 775, "communityNodeCount": 289, "communityRelCount": 883, "nodeCount": 1059, "relationshipCount": 2968 }, { "filename": "Germany", "chunkNodeCount": 100, "chunkRelCount": 1402, "entityNodeCount": 780, "entityEntityRelCount": 813, "communityNodeCount": 422, "communityRelCount": 1079, "nodeCount": 1302, "relationshipCount": 3294 } ], "message": "All tasks completed successfully" } .... === Chat with Data ---- POST /chat_bot ---- The API responsible for a chatbot system designed to leverage multiple AI models and a Neo4j graph database, providing answers to user queries. It interacts with AI models from OpenAI and Google's Vertex AI etc and utilizes embedding models to enhance the retrieval of relevant information. It utilises different retrievers (Retrieval Detail) to extract relevant information to the user query and uses LLM to formulate the answer. If no relevant information found the chatbot gracefully conveys to user. **Components :** ** Embedding Models - Includes OpenAI Embeddings, VertexAI Embeddings, BedrockEmbeddings and SentenceTransformer Embeddings(Default) to support vector-based query operations. ** AI Models - OpenAI GPT 5 mini, gemini_flash_latest, anthropic claude 4.5 haiku can be configured for the chatbot backend to generate responses and process natural language. ** Graph Database (Neo4jGraph) - Manages interactions with the Neo4j database, retrieving, and storing conversation histories. ** Response Generation - Utilizes Vector Embeddings from the Neo4j database, chat history, and the knowledge base of the LLM used. ** Chat Modes - Vector , Graph, Vector + Graph, Fulltext, Vector + Graph+Fulltext, Entity Search + Vector, Global search Vector **API Parameters :** * `uri`= Neo4j uri * `userName`= Neo4j database username * `password`= Neo4j database password * `model`= LLM model * `question`= User query for the chatbot * `session_id`= Session ID used to maintain the history of chats during the user's connection * `mode` = chat mode to use * `document_names` = the names of documents to be filtered works for vector mode and vector+Graph mode, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "session_id": "f4e352bf-f57a-4a15-819e-68d2ffca82a2", "message": "Germany has sixteen constituent states, collectively referred to as Länder.", "info": { "sources": [ "https://en.wikipedia.org/wiki/Germany" ], "model": "gpt-4.5-preview", "nodedetails": { "chunkdetails": [ { "id": "0c92f93e837e6b31f8d2429dd76c3db4ab37ce14", "score": 1.0 }, { "id": "ac8c9c1e05c718cc612160d6580caf1af97dfb1f", "score": 0.9455 }, { "id": "b91415a3bbfb99d64b3a2aa8b1413bebd5b5650e", "score": 0.9307 } ], "entitydetails": [], "communitydetails": [] }, "total_tokens": 2493, "response_time": 5.53, "mode": "graph_vector_fulltext", "entities": { "entityids": [ "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8329", "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7783", "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8327", "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7780", "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8512", "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8157", "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8549", "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7823" ], "relationshipids": [ "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:146149", "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:145082", "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:146554", "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:140377" ] }, "metric_details": { "question": "how many states in germany", "contexts": "Document start\nThis Document belongs to the source https://en.wikipedia.org/wiki/Germany\nContent: Text Content:\nGermany, officially the Federal Republic of Germany, is a country in Central Europe. It lies between the Baltic Sea and the North Sea to the north and the Alps to the south. Its sixteen constituent states have a total population of over 82 million in an area of 357,596 km2 (138,069 sq mi), making it the most populous member state of the European Union. It borders Denmark to the north, Poland and the Czech Republic to the east, Austria and Switzerland to the south,\n----\n sixteen constituent states which are collectively referred to as Länder. Each state (Land) has its own constitution, and is largely autonomous in regard to its internal organisation. As of 2017, Germany is divided into 401 districts (Kreise) at a municipal level; these consist of 294 rural districts and 107 urban districts. === Law === Germany has a civil law system based on Roman law with some references to Germanic law. The Bundesverfassungsgericht (Federal\n----\n resort. == Demographics == With a population of 84.7 million according to the 2023 German census, Germany is the most populous member state of the European Union, the second-most populous country in Europe after Russia, and the nineteenth-most populous country in the world. Its population density stands at 236 inhabitants per square kilometre (610 inhabitants/sq mi). The fertility rate of 1.57 children born per woman (2022 estimates) is below the replacement rate of 2\n----\nEntities:\nAdministrative Division:107 urban districts\nAdministrative Division:294 rural districts\nAdministrative Division:401 districts\nAdministrative Division:sixteen constituent states\nArea:357,596 km2\nBody of Water:Baltic Sea\nBrand:Volkswagen\nCompany:Deutsche Telekom\nConcept:defence\nCountry:Austria\nCountry:Czech Republic\nCountry:Denmark\nCountry:Federal Republic of Germany\nCountry:Germany\nCountry:Hungary\nCountry:Poland\nCountry:Switzerland\nCountry:Ukraine\nCountry:United States\nCountry:West Germany\nEnergy Source:40% renewable sources\nGeographical Feature:Alps\nGeographical Feature:North Sea\nGroup:East Germans\nInitiative:Energiewende\nKingdom:East Francia\nLaw System:Germanic law\nLaw System:Roman law\nLaw System:civil law system\nLegal Domain:constitutional matters\nLegal Power:judicial review\nLocation:Berlin\nName:Länder\nOrganization Membership:founding member of the European Economic Community\nOrganization:Bundesverfassungsgericht\nOrganization:European Economic Community\nOrganization:European Union\nOrganization:Federal Constitutional Court\nOrganization:German Supreme Court\nOrganization:North German Confederation\nOrganization:Population Division of the United Nations Department of Economic and Social Affairs\nOrganization:coalition\nPercentage:11% between 1990 and 2015\nPercentage:65%\nPerson:Bismarck\nPopulation:over 82 million\nRank:14th highest emitting nation of greenhouse gases\nRanking:fourth globally in number of science and engineering research papers published\nRanking:fourth in research and development expenditure\nRanking:third in quality-adjusted Nature Index\nRegion:Central Europe\nResearch Institution:Fraunhofer Society\nResearch Institution:Helmholtz Association\nResearch Institution:Leibniz Association\nResearch Institution:Max Planck Society\nStatistic:percentage of migrants in population\nTerritory:Western sectors\n----\nRelationships:\nAdministrative Division:401 districts CONSISTS_OF Administrative Division:107 urban districts\nAdministrative Division:401 districts CONSISTS_OF Administrative Division:294 rural districts\nAdministrative Division:sixteen constituent states REFERRED_AS Name:Länder\nAdministrative Division:sixteen constituent states REFERRED_TO_AS Name:Länder\nCountry:Austria BORDERS Country:Germany\nCountry:Czech Republic BORDERS Country:Germany\nCountry:Federal Republic of Germany ALSO_KNOWN_AS Country:West Germany\nCountry:Federal Republic of Germany FOUNDING_MEMBER_OF Organization:European Economic Community\nCountry:Federal Republic of Germany FOUNDING_MEMBER_OF Organization:European Union\nCountry:Federal Republic of Germany HAS_STATUS Organization Membership:founding member of the European Economic Community\nCountry:Germany ANNEXED Country:Austria\nCountry:Germany BORDERED_BY Body of Water:Baltic Sea\nCountry:Germany BORDERED_BY Geographical Feature:North Sea\nCountry:Germany BORDERS Body of Water:Baltic Sea\nCountry:Germany BORDERS Country:Austria\nCountry:Germany BORDERS Country:Czech Republic\nCountry:Germany BORDERS Country:Denmark\nCountry:Germany BORDERS Country:Poland\nCountry:Germany BORDERS Country:Switzerland\nCountry:Germany BORDERS Geographical Feature:Alps\nCountry:Germany BORDERS Geographical Feature:North Sea\nCountry:Germany COMPRISES Administrative Division:sixteen constituent states\nCountry:Germany CONQUERED Country:Denmark\nCountry:Germany DIVIDED_INTO Administrative Division:401 districts\nCountry:Germany HAS_ADMINISTRATIVE_DIVISION Administrative Division:sixteen constituent states\nCountry:Germany HAS_AREA Area:357,596 km2\nCountry:Germany HAS_BRANDS Brand:Volkswagen\nCountry:Germany HAS_BRANDS Company:Deutsche Telekom\nCountry:Germany HAS_ENERGY_TRANSITION Initiative:Energiewende\nCountry:Germany HAS_FEATURE Geographical Feature:Alps\nCountry:Germany HAS_FEATURE Geographical Feature:North Sea\nCountry:Germany HAS_INSTITUTION Organization:Bundesverfassungsgericht\nCountry:Germany HAS_LAW_SYSTEM Law System:civil law system\nCountry:Germany HAS_PART Administrative Division:sixteen constituent states\nCountry:Germany HAS_POPULATION Population:over 82 million\nCountry:Germany HAS_RECYCLING_RATE Percentage:65%\nCountry:Germany HAS_RESEARCH_INSTITUTION Research Institution:Fraunhofer Society\nCountry:Germany HAS_RESEARCH_INSTITUTION Research Institution:Helmholtz Association\nCountry:Germany HAS_RESEARCH_INSTITUTION Research Institution:Leibniz Association\nCountry:Germany HAS_RESEARCH_INSTITUTION Research Institution:Max Planck Society\nCountry:Germany HAS_ROLE Organization:European Union\nCountry:Germany HAS_TERRITORY Area:357,596 km2\nCountry:Germany INVADED Country:Poland\nCountry:Germany LOCATED_IN Region:Central Europe\nCountry:Germany MEETS_POWER_DEMAND Energy Source:40% renewable sources\nCountry:Germany MEMBER_OF Organization:European Union\nCountry:Germany OFFICIALLY_KNOWN_AS Country:Federal Republic of Germany\nCountry:Germany ORGANIZED_INTO Country:Federal Republic of Germany\nCountry:Germany PLAYS_ROLE_IN Organization:European Union\nCountry:Germany RANKS_IN Ranking:fourth globally in number of science and engineering research papers published\nCountry:Germany RANKS_IN Ranking:fourth in research and development expenditure\nCountry:Germany RANKS_IN Ranking:third in quality-adjusted Nature Index\nCountry:Germany RANKS_SECOND_AFTER Country:United States\nCountry:Germany RANKS_SEVENTH_IN Statistic:percentage of migrants in population\nCountry:Germany RECEIVED_REFUGEES_FROM Country:Ukraine\nCountry:Germany REDUCED_ENERGY_CONSUMPTION Percentage:11% between 1990 and 2015\nCountry:Germany WAS_EMITTING_NATION Rank:14th highest emitting nation of greenhouse gases\nCountry:Hungary OPENED_BORDER_WITH Country:Austria\nCountry:Poland BORDERS Country:Germany\nCountry:Switzerland BORDERS Country:Germany\nGroup:East Germans EMIGRATED_VIA Country:Austria\nKingdom:East Francia STRETCHED_FROM Geographical Feature:North Sea\nKingdom:East Francia STRETCHED_TO Geographical Feature:Alps\nLaw System:civil law system BASED_ON Law System:Roman law\nLaw System:civil law system REFERENCES Law System:Germanic law\nLocation:Berlin IS_HUB Country:Germany\nOrganization:Bundesverfassungsgericht HAS_POWER Legal Power:judicial review\nOrganization:Bundesverfassungsgericht IS Organization:German Supreme Court\nOrganization:Bundesverfassungsgericht REFERRED_AS Organization:Federal Constitutional Court\nOrganization:Bundesverfassungsgericht RESPONSIBLE_FOR Legal Domain:constitutional matters\nOrganization:Federal Constitutional Court DEFINED_TERM Concept:defence\nOrganization:North German Confederation EXCLUDED Country:Austria\nOrganization:Population Division of the United Nations Department of Economic and Social Affairs LISTED_AS_HOST_TO Country:Germany\nOrganization:coalition OPERATES_IN Country:Switzerland\nPerson:Bismarck CONCLUDED_WAR Country:Denmark\nTerritory:Western sectors MERGED_TO_FORM Country:Federal Republic of Germany\nDocument end\n", "answer": "Germany has sixteen constituent states, collectively referred to as Länder." } }, "user": "chatbot" } } .... === Get entities from chunks ---- /chunk_entities ---- This API is used to get the entities and relations associated with a particular chunk and chunk metadata. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `nodedetails` = Node element id's to get information(chunks,entities,communities), * `entities` = entities received from the retriver for graph based modes, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "nodes": [ { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7787", "labels": [ "Country", "Location" ], "properties": { "id": "Germany", "description": null } }, { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7779", "labels": [ "Organization" ], "properties": { "id": "European Union", "description": null } }, { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:5977", "labels": [ "Organization" ], "properties": { "id": "coalition", "description": null } } ], "relationships": [ { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:146579", "type": "RANKS_SECOND_AFTER", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7787", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:5973" }, { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:145089", "type": "BORDERS", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7782", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7787" }, { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:146509", "type": "HAS_BRANDS", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7787", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8457" }, { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:146121", "type": "HAS_POWER", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8326", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8345" } ], "chunk_data": [ { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7678", "id": "0c92f93e837e6b31f8d2429dd76c3db4ab37ce14", "position": 1, "text": "Germany, officially the Federal Republic of Germany, is a country in Central Europe. It lies between the Baltic Sea and the North Sea to the north and the Alps to the south. Its sixteen constituent states have a total population of over 82 million in an area of 357,596 km2 (138,069 sq mi), making it the most populous member state of the European Union. It borders Denmark to the north, Poland and the Czech Republic to the east, Austria and Switzerland to the south,", "content_offset": 0, "fileName": "Germany", "length": 468, "embedding": null, "fileSource": "Wikipedia", "fileType": "text", "url": "https://en.wikipedia.org/wiki/Germany" }, { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7747", "id": "ac8c9c1e05c718cc612160d6580caf1af97dfb1f", "position": 70, "text": " sixteen constituent states which are collectively referred to as Länder. Each state (Land) has its own constitution, and is largely autonomous in regard to its internal organisation. As of 2017, Germany is divided into 401 districts (Kreise) at a municipal level; these consist of 294 rural districts and 107 urban districts. === Law === Germany has a civil law system based on Roman law with some references to Germanic law. The Bundesverfassungsgericht (Federal", "content_offset": 33460, "fileName": "Germany", "length": 467, "embedding": null, "fileSource": "Wikipedia", "fileType": "text", "url": "https://en.wikipedia.org/wiki/Germany" }, { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7773", "id": "b91415a3bbfb99d64b3a2aa8b1413bebd5b5650e", "position": 96, "text": " resort. == Demographics == With a population of 84.7 million according to the 2023 German census, Germany is the most populous member state of the European Union, the second-most populous country in Europe after Russia, and the nineteenth-most populous country in the world. Its population density stands at 236 inhabitants per square kilometre (610 inhabitants/sq mi). The fertility rate of 1.57 children born per woman (2022 estimates) is below the replacement rate of 2", "content_offset": 46388, "fileName": "Germany", "length": 476, "embedding": null, "fileSource": "Wikipedia", "fileType": "text", "url": "https://en.wikipedia.org/wiki/Germany" } ] }, "message": "Total elapsed API time 0.55" } .... === View graph for a file ---- POST /graph_query ---- This API is used to visualize graphs for a particular document or list of multiple documents; it will return documents, chunks, entities, relationships and communities to the front-end to be shown in a graph visualization. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `document_names` = File name for which user wants to view graph, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "nodes": [ { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10497", "labels": [ "Document" ], "properties": { "fileName": "Untitled Diagram.png", "communityNodeCount": 12, "errorMessage": "", "chunkRelCount": 28, "fileSource": "local file", "communityRelCount": 22, "total_chunks": 5, "processingTime": 15.91, "entityNodeCount": 14, "chunkNodeCount": 5, "createdAt": "2025-04-10T16:33:22.331776000", "entityEntityRelCount": 10, "fileSize": 393322, "model": "openai_gpt_4.5", "nodeCount": 31, "processed_chunk": 5, "is_cancelled": false, "relationshipCount": 60, "fileType": "png", "status": "Completed", "updatedAt": "2025-04-10T17:06:15.896962000" } }, { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10501", "labels": [ "Chunk" ], "properties": { "fileName": "Untitled Diagram.png", "content_offset": 9, "page_number": 1, "length": 21, "id": "e6200cc319ae833a42f3ea85bd3f48fe57f528ac", "position": 3 } }, { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10499", "labels": [ "Chunk" ], "properties": { "fileName": "Untitled Diagram.png", "content_offset": 0, "page_number": 1, "length": 1, "id": "091385be99b45f459a231582d583ec9f3fa3d194", "position": 1 } }, { "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10503", "labels": [ "Chunk" ], "properties": { "fileName": "Untitled Diagram.png", "content_offset": 113, "page_number": 1, "length": 14, "id": "2fe558452be341af4450be97b79ecdd8ea64b188", "position": 5 } } ], "relationships": [ { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:155207", "type": "IN_COMMUNITY", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10515", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10907" }, { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:155845", "type": "PARENT_COMMUNITY", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10907", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:11378" }, { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:155846", "type": "PARENT_COMMUNITY", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:11378", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:11379" }, { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:153551", "type": "HAS_ENTITY", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10503", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:10516" } ] }, "message": "Total elapsed API time 0.79" } .... === Get neighbour nodes ---- POST /get_neighbours ---- This API is used to get the nearby nodes and relationships based on the element id of the node for graph visualization of details of specific nodes. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `elementId` = Element id of the node to retrive its neighbours, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "nodes": [ { "summary": null, "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:11925", "id": "0-554", "text": null, "title": "Western Sectors Control,", "weight": 2, "level": 0, "labels": [ "__Community__" ], "properties": { "id": "0-554", "title": "Western Sectors Control," }, "embedding": null }, { "summary": null, "element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:5978", "id": "United Kingdom", "text": null, "communities": [ 554, 246, 16 ], "labels": [ "Country" ], "properties": { "id": "United Kingdom", "title": " " }, "embedding": null } ], "relationships": [ { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:145729", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:7792", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8154", "type": "CONTROLLED_BY" }, { "element_id": "5:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:145730", "end_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:5978", "start_node_element_id": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:8154", "type": "CONTROLLED_BY" } ] }, "message": "Total elapsed API time 0.43" } .... === Clear chat history ---- POST /clear_chat_bot ---- This API is used to clear the chat history which is saved in Neo4j DB. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `session_id` = User session id for QA chat, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "session_id": "f4e352bf-f57a-4a15-819e-68d2ffca82a2", "message": "The chat history has been cleared.", "user": "chatbot" } } .... === SSE event to update processing status ---- GET /update_extract_status ---- The API provides a continuous update on the extraction status of a specified file. It uses Server-Sent Events (SSE) to stream updates to the client. **API Parameters :** * `file_name`=The name of the file whose extraction status is being tracked, * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, **Response :** [source,json,indent=0] .... { "fileName": "testFile.pdf", "status": "Processing", "processingTime": 0, "nodeCount": 0, "relationshipCount": 0, "model": "OpenAI GPT 3.5", "total_chunks": 3, "fileSize": 92373, "processed_chunk": 0 } .... === Delete selected documents ---- POST /delete_document_and_entities ---- **Overview :** Deleteion of nodes and relations for multiple files is done through this API. User can choose multiple documents to be deleted, also user have option to delete only 'Document' and 'Chunk' nodes and keep the entities extracted from that document. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `filenames`= List of files to be deleted, * `source_types`= Document sources(Wikipedia, youtube, etc.), * `deleteEntities`= Boolean value to check entities deletion is requested or not, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... {"status":"Success","message":"Deleted 1 documents with entities from database"} .... === Cancel processing job ---- /cancelled_job ---- This API is responsible for cancelling an in process job. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `filenames`= Name of the file whose processing need to be stopped, * `source_types`= Source of the file, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "message":"Cancelled the processing job successfully" } .... === Get the list of orphan nodes ---- POST /get_unconnected_nodes_list ---- The API retrieves a list of nodes in the graph database that are not connected to any other entity nodes, and only to chunks that they were extracted from. So to say orphan nodes from an domain graph perspective. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": [ { "e": { "id": "46c949fb-b451-4b69-b3bd-87f26ac8f9e6", "elementId": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:5853", "labels": [ "Entity" ], "embedding": null }, "documents": [], "chunkConnections": 0 }, { "e": { "id": "f4e352bf-f57a-4a15-819e-68d2ffca82a2", "elementId": "4:8b7ad735-1828-4d80-b8c3-798dcbfdd95d:11380", "labels": [ "Entity" ], "embedding": null }, "documents": [], "chunkConnections": 0 } ], "message": { "total": 2 } } .... === Deletion of orpahn nodes ---- POST /delete_unconnected_nodes ---- The API is used to delete unconnected entities from the neo4j database with the input provided as selection from the user. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `unconnected_entities_list`=selected entities list to delete of unconnected entities, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": [], "message": "Unconnected entities delete successfully" } .... === Get duplicate nodes ---- POST /get_duplicate_nodes ---- The API is used to fetch duplicate entities from database. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": [ { "e": { "id": "13 September 2024", "elementId": "4:b104b2e7-e2ed-4902-b78b-7ad1518ca04f:14007", "communities": [ 2969, 383, 81 ], "labels": [ "__Entity__", "Date" ], "embedding": null }, "similar": [ { "id": "20 September 2024", "elementId": "4:b104b2e7-e2ed-4902-b78b-7ad1518ca04f:14153", "description": null, "labels": [ "__Entity__", "Date" ] } ], "documents": [], "chunkConnections": 0 } ], "message": { "total": 1 } } .... === Merge duplicate nodes ---- POST /merge_duplicate_nodes ---- The API is used to merge duplicate entities from database selected by user. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `duplicate_nodes_list`= selected entities list to merge of with similar entities, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": [ { "totalMerged": 2 } ], "message": "Duplicate entities merged successfully" } .... === Change Embedding Model ---- POST /change_embedding_model ---- This API updates the active embedding provider and embedding model for the backend. If the selected model has a different embedding dimension from the existing vector index, the backend automatically drops and recreates the vector index. **API Parameters :** * `uri` = Neo4j URI * `userName` = Neo4j database username * `password` = Neo4j database password * `database` = Neo4j database name * `embedding_provider` = Selected embedding provider (openai, gemini, vertexai, bedrock, sentence_transformer) * `embedding_model` = Embedding model chosen by the user * `email` = Logged in User Email **Response :** [source,json,indent=0] ---- { "status": "Success", "data": { "embedding_provider": "gemini", "embedding_model": "gemini-embedding-001", "embedding_dimension": 3072, "change_index": true }, "message": "Embedding model changed successfully. Vector index was dropped and recreated." } ---- === Drop and create vector index ---- POST /drop_create_vector_index ---- The API is used to drop and create the vector index when vector index dimesion are different. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `isVectorIndexExist`= True or False based on whether vector index exist in database, * `email`= Logged in User Email * `embedding_model`= Embedding model selected by user **Response :** [source,json,indent=0] .... { "status": "Success", "message": "Drop and Re-Create vector index succesfully" } .... === Reprocessing of sources ---- POST /retry_processing ---- This API is used to reprocess canceled, completed or failed file sources. Users have 3 options to reprocess files: * Start from beginning - In this condition file will be processed from the beginning i.e. 1st chunk again. * Delete entities and start from beginning - If the file source is already processed and has any existing nodes and relationships then those will be deleted and the file will be reprocessed from the 1st chunk. * Start from the last processed position - Canceled or failed files will be processed from the last successfully processed chunk position. This option is not available for completed files. * Once the status is set to 'Reprocess', users can again click on Generate Graph to process the file for knowledge graph creation. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `file_name`= Name of the file which user want to Ready to Reprocess. * `retry_condition` = One of the above 3 conditions which is selected for reprocessing. * `email`= Logged in User Email, **Response :** [source,json,indent=0] .... { "status": "Success", "message": "Status set to Ready to Reprocess for filename : $filename" } .... === Evaluate response ---- POST /metric ---- The API responsible for evaluating the chatbot response for the different retrievers on the basis of different metrics such as faithfulness and answer relevancy. This utilises the RAGAS library to calculate these metrics. **API Parameters :** * `question`= User query for the chatbot * `context`= context retrieved by retrieval mode used for answer generation * `answer`= answer generated by chatbot * `model`= LLM model * `mode`= Retrieval mode used for answer generationRetrieval mode used for answer generation **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "graph_vector_fulltext": { "faithfulness": 1.0, "answer_relevancy": 0.9118, "context_entity_recall": 0.6667 } } } .... === Evaluate response with ground truth ---- POST /additional_metrics ---- The API responsible for a evaluating chatbot responses on the basis of different metrics such as context entity recall, semantic score, rouge score. This reuqire additional ground truth to be supplied by user. This utilises RAGAS library to calculate these metrics. **API Parameters :** * `question`= User query for the chatbot * `context`= context retrieved by retrieval mode used for answer generation * `answer`= answer generated by chatbot * `reference`= ground truth/ expected answer provided by user * `model`= LLM model * `mode`= Retrieval mode used for answer generationRetrieval mode used for answer generation **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "graph_vector_fulltext": { "rouge_score": 1.0, "semantic_score": 0.9842 } } } .... === Fetch chunk text ---- POST /fetch_chunktext ---- The API responsible for a fetching text associated with a particular chunk and chunk metadata. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name * `document_name` = Name of document for which chunks needs to be fetched. * `page no` = page number for multipage * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "pageitems": [ { "text": "By T. Albert Illustrated by: maaillustrations.com Science has never been so much fun. Here is all that a child needs to know about water, rain, hail, sleet and water cycle. When Professor Mois Ture teaches- little readers read, learn and ask for more….. Published by Monkey Pen Ltd Dear Supporter, Thank you for downloading our childrens books. Monkey Pens Vision is to provide thousands of free childrens books to young readers around the globe. Please share our books with your friends and family to support our mission. Thank you Please make a donation on Patreon to support Monkey Pens Free Book Project: Hi, I am Professor Mois Ture and I will be telling you about water. You can call it RAIN. You can call it SNOW. You can call it SLEET. You can call it HAIL. But it’s WATER all the same. Did you ever wonder how", "position": 1, "pagenumber": 1 }, { "text": " it HAIL. But it’s WATER all the same. Did you ever wonder how old water is or where it comes from? The answers may surprise you. The next time you see a pond or even a glass of water, think about how old that water might be. Do you really want to know ? I thought you did. Did you brush your teeth this morning? Well, some of the water that you used could have fallen from the sky yesterday, or a week, or month ago. It’s pretty new. But, some part of that water is very old and was around during the time of the dinosaurs, or even longer. Or maybe it’s a little newer; like from the time when the Pharaohs were building pyramids. You see there is only a limited amount of water and it gets recycled. Yep! It keeps going round and round. We call it the “Water Cycle.” Yes – You", "position": 2, "pagenumber": 2 } ], "total_pages": 1 }, "message": "Total elapsed API time 0.48" } .... === Backend Database connection ---- POST /backend_connection_configuation ---- The API responsible for create the connection obj from Neo4j DB based on environment variable and return the status for show/hide login dialog on UI **Response :** [source,json,indent=0] .... { "status": "Success", "data": true, "message": "Backend connection successful" } .... === Visualize graph DB schema ---- POST /schema_visualization ---- User can visualize schema of the db through this API. **API Parameters :** * `uri`=Neo4j uri, * `userName`= Neo4j db username, * `password`= Neo4j db password, * `database`= Neo4j database name, * `email`= Logged in User Email **Response :** [source,json,indent=0] .... { "status": "Success", "data": { "nodes": [ { "element_id": "-5374", "labels": [ "Entity" ], "properties": { "name": "Entity", "indexes": [ "id,description" ], "constraints": [] } }, ], "relationships": [ { "element_id": "-44223", "end_node_element_id": "-5411", "start_node_element_id": "-5342", "properties": { "name": "OWNED" }, "type": "OWNED" }, ] }, "message": "Total elapsed API time 3.51" } .... --- ### Project Docs = LLM Knowledge Graph Builder == Introduction This document provides comprehensive documentation for the Neo4j llm-graph-builder Project, a Python web application built with the FastAPI framework. It covers various aspects of the project, including its features, architecture, usage, development, deployment, limitations and known issues. == Features * Upload unstructured data from multiple sources to generate structuted Neo4j knowledge graph. * Extraction of nodes and relations from multiple LLMs(OpenAI GPT-3.5, OpenAI GPT-4, Gemini 1.0-Pro and Diffbot). * View complete graph or only a particular element of graph(ex: Only chunks, only entities, document and entities, etc.) * Generate embedding of chunks created from unstructured content. * Generate k-nearest neighbors graph for similar chunks. * Chat with graph data using chat bot. == Local Setup and Execution Prerequisites: - Python 3.12 or higher - Node.js 20 or higher - Docker (optional, for containerized deployment) Run Docker Compose to build and start all components: .... docker-compose up --build .... Alternatively, run specific directories separately: ** For frontend .... cd frontend yarn yarn run dev .... ** For backend .... cd backend python3.12 -m venv venv source venv/bin/activate pip install -r requirements.txt uvicorn score:app --reload .... Set up environment variables .... OPENAI_API_KEY = "" DIFFBOT_API_KEY = "" NEO4J_URI = "" NEO4J_USERNAME = "" NEO4J_PASSWORD = "" NEO4J_DATABASE = "" IS_EMBEDDING = "TRUE" KNN_MIN_SCORE = "" .... == Architecture image::project architecture.png[Archirecture diagram, 600, align='left'] == Development ==== Backend link:backend/backend_docs.adoc[backend_docs.adoc] ==== Frontend link:frontend/frontend_docs.adoc[frontend_docs.adoc] == Deployment and Monitoring * The application is deployed on Google Cloud Platform. To deploy frontend .... gcloud run deploy source location current directory > Frontend region : 32 [us-central 1] Allow unauthenticated request : Yes .... To deploy backend .... gcloud run deploy --set-env-vars "OPENAI_API_KEY = " --set-env-vars "DIFFBOT_API_KEY = " --set-env-vars "NEO4J_URI = " --set-env-vars "NEO4J_PASSWORD = " --set-env-vars "NEO4J_USERNAME = " source location current directory > Backend region : 32 [us-central 1] Allow unauthenticated request : Yes .... * Langserve is used with FAST API to deploy Langchain runnables and chains as a REST API. * Langsmith is used to monitor and evaluate the application Developement url Production url == Appendix === Limitations ** Only pdf file uploaded from device or uploaded from s3 bucket or gcs bucket can be processed. ** GCS buckets present under 1051503595507@cloudbuild.gserviceaccount.com service account can only be accessed. ** Only 1st page of Wikipedia content is processed to generate graphDocument. === Known issues ** InactiveRpcError error with Gemini 1.0 Pro - grpc_status:13, grpc_message:"Internal error encountered." ** ResourceExhausted error with Gemini 1.5 Pro - 429 Quota exceeded for aiplatform.googleapis.com/generate_content_requests_per_minute_per_project_per_base_model with base model: gemini-1.5-pro ** Gemini response validation errors even after making safety_settings parameters to BLOCK_NONE. --- ### README # Knowledge Graph Builder Transform unstructured data (PDFs, DOCs, TXTs, YouTube videos, web pages, etc.) into a structured Knowledge Graph stored in Neo4j using the power of Large Language Models (LLMs) and the LangChain framework. This application allows you to upload files from various sources (local machine, GCS, S3 bucket, or web sources), choose your preferred LLM model, and generate a Knowledge Graph. ## Getting Started ### **Prerequisites** - **Python 3.12 or higher** (for local/separate backend deployment) - Neo4j Database **5.23 or later** with APOC installed. - Neo4j 5.23 is required because the backend uses the Cypher variable-scope subquery syntax (`CALL (variable) { ... }`), which is not supported by earlier Neo4j 5.x releases such as 5.20. - **Neo4j Aura** databases (including the free tier) are supported. - If using **Neo4j Desktop**, you will need to deploy the backend and frontend separately (docker-compose is not supported). #### **Backend Setup** 1. Create a `.env` file in the `backend` folder by copying `backend/example.env`. 2. Pre-configure user credentials in the `.env` file to bypass the login dialog: ```bash NEO4J_URI= NEO4J_USERNAME= NEO4J_PASSWORD= NEO4J_DATABASE= ``` 3. Run: ```bash cd backend python3.12 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt uvicorn score:app --reload ``` ## Key Features ### **Knowledge Graph Creation** - Seamlessly transform unstructured data into structured Knowledge Graphs using advanced LLMs. - Extract nodes, relationships, and their properties to create structured graphs. ### **Schema Support** - Use a custom schema or existing schemas configured in the settings to generate graphs. ### **Graph Visualization** - View graphs for specific or multiple data sources simultaneously in **Neo4j Bloom**. ### **Chat with Data** - Interact with your data in the Neo4j database through conversational queries. - Retrieve metadata about the source of responses to your queries. - For a dedicated chat interface, use the standalone chat application with the **[/chat-only](/chat-only) route.** ### **LLMs Supported** 1. OpenAI 2. Gemini 3. Diffbot 4. Azure OpenAI (dev deployed version) 5. Anthropic (dev deployed version) 6. Fireworks (dev deployed version) 7. Groq (dev deployed version) 8. Amazon Bedrock (dev deployed version) 9. Ollama (dev deployed version) 10. Deepseek (dev deployed version) 11. Other OpenAI-compatible base URL models (dev deployed version) ### **Token Usage Tracking** - Easily monitor and track your LLM token usage for each user and database connection. - Enable this feature by setting the `TRACK_USER_USAGE` environment variable to `true` in your backend configuration. - View your daily and monthly token consumption and limits, helping you manage usage and avoid overages. - You can check your remaining token limits at any time using the provided API endpoint. ### **Embedding Model Selection** - Choose from a variety of embedding models to generate vector embeddings for your data. This can be configured from the frontend in **Graph Settings > Processing Configuration > Select Embedding Model**. - Supported model providers include OpenAI, Gemini, Amazon Titan, and Sentence Transformers. - Your selected embedding model is saved to your user profile when `TRACK_USER_USAGE` is enabled. #### **Local Configuration** You have two ways to configure the embedding model locally: 1. **With User Tracking (`TRACK_USER_USAGE=true`):** - Set `TRACK_USER_USAGE` to `true` in your backend `.env` file. - Provide your token tracking database credentials (`TOKEN_TRACKER_DB_URI`, `TOKEN_TRACKER_DB_USERNAME`, etc.). - Select your desired embedding model from the frontend. Your selection will be saved and automatically used in subsequent sessions. 2. **Without User Tracking (`TRACK_USER_USAGE=false`):** - Set `TRACK_USER_USAGE` to `false`. - Specify the embedding model and provider directly in your backend `.env` file using `EMBEDDING_MODEL` and `EMBEDDING_PROVIDER`. - If these variables are not set, the application defaults to a Sentence Transformer model. - In this mode, the embedding model cannot be changed from the frontend. --- ## Getting Started ### **Prerequisites** - Neo4j Database **5.23 or later** with APOC installed. - Neo4j 5.23 is required because the backend uses the Cypher variable-scope subquery syntax (`CALL (variable) { ... }`), which is not supported by earlier Neo4j 5.x releases such as 5.20. - **Neo4j Aura** databases (including the free tier) are supported. - If using **Neo4j Desktop**, you will need to deploy the backend and frontend separately (docker-compose is not supported). --- ## Deployment Options ### **Local Deployment** #### Using Docker-Compose Run the application using the default `docker-compose` configuration. 1. **Supported LLM Models:** By default, only OpenAI and Diffbot are enabled. Gemini requires additional GCP configurations. Use the `VITE_LLM_MODELS_PROD` variable to configure the models you need. Example: ```bash VITE_LLM_MODELS_PROD="gemini_3.5_flash,openai_gpt_5.4_mini,diffbot,anthropic_claude_4.5_haiku" ``` 2. **Anthropic Models:** Use the latest Claude model in your config: ```bash LLM_MODEL_CONFIG_ANTHROPIC_CLAUDE_4_7_OPUS="claude-opus-4-7,anthropic_api_key" ``` 3. **Input Sources:** By default, the following sources are enabled: `local`, `YouTube`, `Wikipedia`, `AWS S3`, and `web`. To add Google Cloud Storage (GCS) integration, include `gcs` and your Google client ID: ```bash VITE_REACT_APP_SOURCES="local,youtube,wiki,s3,gcs,web" VITE_GOOGLE_CLIENT_ID="your-google-client-id" ``` #### Chat Modes Configure chat modes using the `VITE_CHAT_MODES` variable: - By default, all modes are enabled: `vector`, `graph_vector`, `graph`, `fulltext`, `graph_vector_fulltext`, `entity_vector`, and `global_vector`. - To specify specific modes, update the variable. For example: ```bash VITE_CHAT_MODES="vector,graph" ``` --- ### **Running Backend and Frontend Separately** For development, you can run the backend and frontend independently. #### **Frontend Setup** 1. Create a `.env` file in the `frontend` folder by copying `frontend/example.env`. 2. Update environment variables as needed. 3. Run: ```bash cd frontend yarn yarn run dev ``` #### **Backend Setup** 1. Create a `.env` file in the `backend` folder by copying `backend/example.env`. 2. Pre-configure user credentials in the `.env` file to bypass the login dialog: ```bash NEO4J_URI= NEO4J_USERNAME= NEO4J_PASSWORD= NEO4J_DATABASE= ``` 3. Run: ```bash cd backend python -m venv envName source envName/bin/activate pip install -r requirements.txt uvicorn score:app --reload ``` --- ### **Cloud Deployment** Deploy the application on **Google Cloud Platform** using the following commands: #### **Frontend Deployment** ```bash gcloud run deploy dev-frontend \ --source . \ --region us-central1 \ --allow-unauthenticated ``` #### **Backend Deployment** ```bash gcloud run deploy dev-backend \ --set-env-vars "OPENAI_API_KEY=" \ --set-env-vars "DIFFBOT_API_KEY=" \ --set-env-vars "NEO4J_URI=" \ --set-env-vars "NEO4J_USERNAME=" \ --set-env-vars "NEO4J_PASSWORD=" \ --source . \ --region us-central1 \ --allow-unauthenticated ``` --- ## For local llms (Ollama) 1. Pull the docker image of ollama ```bash docker pull ollama/ollama ``` 2. Run the ollama docker image ```bash docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama ``` 3. Execute any llm model, e.g., llama3 ```bash docker exec -it ollama ollama run llama3 ``` 4. Configure env variable in docker compose. ```env LLM_MODEL_CONFIG_ollama_ # example LLM_MODEL_CONFIG_ollama_llama3=${LLM_MODEL_CONFIG_ollama_llama3-llama3,http://host.docker.internal:11434} ``` 5. Configure the backend API url ```env VITE_BACKEND_API_URL=${VITE_BACKEND_API_URL-backendurl} ``` 6. Open the application in browser and select the ollama model for the extraction. 7. Enjoy Graph Building. --- ## Usage 1. Connect to a Neo4j Aura Instance, which can be either AURA DS or AURA DB, by passing the URI and password through the backend environment, filling in the login dialog, or dragging and dropping the Neo4j credentials file. 2. To differentiate, we have added different icons. For AURA DB, there is a database icon, and for AURA DS, there is a scientific molecule icon right under the Neo4j Connection details label. 3. Choose your source from a list of unstructured sources to create a graph. 4. Change the LLM (if required) from the dropdown, which will be used to generate the graph. 5. Optionally, define the schema (nodes and relationship labels) in the entity graph extraction settings. 6. Either select multiple files to 'Generate Graph', or all the files in 'New' status will be processed for graph creation. 7. View the graph for individual files using 'View' in the grid, or select one or more files and 'Preview Graph'. 8. Ask questions related to the processed/completed sources to the chatbot. Also, get detailed information about your answers generated by the LLM. --- ## [ENV][env-sheet] | Env Variable Name | Mandatory/Optional | Default Value | Description | |------------------------ |-------------------|---------------|--------------------------------------------------------------------------------------------------| | | | | | | **BACKEND ENV** | | | | | OPENAI_API_KEY | Optional | | An OpenAI Key is required to use OpenAI LLM model to authenticate and track requests | | DIFFBOT_API_KEY | Mandatory | | API key is required to use Diffbot's NLP service to extract entities and relationships from unstructured data | | BUCKET_UPLOAD_FILE | Optional | | Bucket name to store uploaded file on GCS | | BUCKET_FAILED_FILE | Optional | | Bucket name to store failed file on GCS while extraction | | USER_AGENT | Optional | llm-graph-builder | Name of the user agent to track Neo4j database activity | | ENABLE_USER_AGENT | Optional | true | Boolean value to enable/disable Neo4j user agent | | DUPLICATE_TEXT_DISTANCE | Optional | 5 | This value is used to find distance for all node pairs in the graph and is calculated based on node properties | | DUPLICATE_SCORE_VALUE | Optional | 0.97 | Node score value to match duplicate nodes | | EFFECTIVE_SEARCH_RATIO | Optional | 1 | Ratio used for effective search calculations | | GRAPH_CLEANUP_MODEL | Optional | openai_gpt_5_mini | Model name to clean up graph in post processing | | MAX_TOKEN_CHUNK_SIZE | Optional | 10000 | Maximum token size to process file content | | YOUTUBE_TRANSCRIPT_PROXY| Mandatory | | Proxy key to process YouTube videos for getting transcripts | | IS_EMBEDDING | Optional | true | Flag to enable text embedding | | KNN_MIN_SCORE | Optional | 0.8 | Minimum score for KNN algorithm | | GCP_LOG_METRICS_ENABLED| Optional | False | Flag to enable Google Cloud logs | | NEO4J_URI | Optional | neo4j://database:7687 | URI for Neo4j database | | NEO4J_USERNAME | Optional | neo4j | Username for Neo4j database | | NEO4J_PASSWORD | Optional | password | Password for Neo4j database | | | GCS_FILE_CACHE | Optional | False | If set to True, will save files to process into GCS. If False, will save files locally | | | ENTITY_EMBEDDING | Optional | False | If set to True, it will add embeddings for each entity in the database | | LLM_MODEL_CONFIG_ollama_ | Optional | | Set ollama config as model_name,model_local_url for local deployments | | | | | | | **FRONTEND ENV** | | | | | VITE_BLOOM_URL | Mandatory | [Bloom URL][bloom-url] | URL for Bloom visualization | | VITE_REACT_APP_SOURCES | Mandatory | local,youtube,wiki,s3 | List of input sources that will be available | | VITE_CHAT_MODES | Mandatory | vector,graph+vector,graph,hybrid | Chat modes available for Q&A | | VITE_ENV | Mandatory | DEV or PROD | Environment variable for the app | | VITE_LLM_MODELS | Optional | openai_gpt_5_mini,gemini_flash_latest,anthropic_claude_4.5_haiku | Supported models for the application | | VITE_BACKEND_API_URL | Optional | [localhost][backend-url] | URL for backend API | | VITE_TIME_PER_PAGE | Optional | 50 | Time per page for processing | | VITE_CHUNK_SIZE | Optional | 5242880 | Size of each chunk of file for upload | | VITE_GOOGLE_CLIENT_ID | Optional | | Client ID for Google authentication | | VITE_LLM_MODELS_PROD | Optional | openai_gpt_5_mini,gemini_flash_latest,anthropic_claude_4.5_haiku | To distinguish models based on environment (PROD or DEV) | | VITE_AUTH0_CLIENT_ID | Mandatory if you are enabling Authentication otherwise it is optional | | Okta OAuth Client ID for authentication | | VITE_AUTH0_DOMAIN | Mandatory if you are enabling Authentication otherwise it is optional | | Okta OAuth Client Domain | | VITE_SKIP_AUTH | Optional | true | Flag to skip authentication | | VITE_CHUNK_OVERLAP | Optional | 20 | Variable to configure chunk overlap | | VITE_TOKENS_PER_CHUNK | Optional | 100 | Variable to configure tokens count per chunk. This gives flexibility for users who may require different chunk sizes for various tokenization tasks | | VITE_CHUNK_TO_COMBINE | Optional | 1 | Variable to configure number of chunks to combine for parallel processing | ### Example Environment Files Refer to the example environment files for additional variables and configuration: - [Backend example.env](https://github.com/neo4j-labs/llm-graph-builder/blob/main/backend/example.env) - [Frontend example.env](https://github.com/neo4j-labs/llm-graph-builder/blob/main/frontend/example.env) --- ## Cloud Build Deployment You can deploy the backend and the frontend to Google Cloud Run using Cloud Build, either manually or via automated triggers. ### **Automated Deployment (Recommended)** 1. **Connect your repository to Google Cloud Build:** - In the Google Cloud Console, go to Cloud Build > Triggers. - Create a new trigger and select your repository. - Set the trigger to run on push to your desired branch (`main`, `staging`, or `dev`). - Cloud Build will automatically use the `cloudbuild.yaml` file in the root of your repository. 2. **Configure Substitutions and Secrets:** - In the trigger settings, add required substitutions (e.g., `_OPENAI_API_KEY`, `_DIFFBOT_API_KEY`, etc.) as environment variables or use Secret Manager for sensitive data. 3. **Push your code:** - When you push to the configured branch, Cloud Build will build and deploy your backend (and optionally frontend) to Cloud Run using the steps defined in `cloudbuild.yaml`. ### **Manual Deployment** 1. **Set up Google Cloud SDK and authenticate:** ```bash gcloud auth login gcloud config set project ``` 2. **Run Cloud Build manually:** ```bash gcloud builds submit --config cloudbuild.yaml \ --substitutions=_REGION=us-central1,_REPO=cloud-run-repo,_OPENAI_API_KEY=,_DIFFBOT_API_KEY=,_BUCKET_UPLOAD_FILE=,_BUCKET_FAILED_FILE=,_PROJECT_ID=,_GCS_FILE_CACHE=False,_TRACK_USER_USAGE=False,_TOKEN_TRACKER_DB_URI=...,_TOKEN_TRACKER_DB_USERNAME=...,_TOKEN_TRACKER_DB_PASSWORD=...,_TOKEN_TRACKER_DB_DATABASE=...,_DEFAULT_DIFFBOT_CHAT_MODEL=...,_YOUTUBE_TRANSCRIPT_PROXY=...,_EMBEDDING_MODEL=..., _EMBEDDING_PROVIDER=...,_BEDROCK_EMBEDDING_MODEL_KEY=...,_LLM_MODEL_CONFIG_OPENAI_GPT_5_2=...,_LLM_MODEL_CONFIG_OPENAI_GPT_5_MINI=...,_LLM_MODEL_CONFIG_GEMINI_2_5_FLASH=...,_LLM_MODEL_CONFIG_GEMINI_2_5_PRO=...,_LLM_MODEL_CONFIG_DIFFBOT=...,_LLM_MODEL_CONFIG_GROQ_LLAMA3_1_8B=...,_LLM_MODEL_CONFIG_ANTHROPIC_CLAUDE_4_5_SONNET=...,_LLM_MODEL_CONFIG_ANTHROPIC_CLAUDE_4_5_HAIKU=...,_LLM_MODEL_CONFIG_LLAMA4_MAVERICK=...,_LLM_MODEL_CONFIG_FIREWORKS_QWEN3_6=...,_LLM_MODEL_CONFIG_FIREWORKS_GPT_OSS=...,_LLM_MODEL_CONFIG_FIREWORKS_DEEPSEEK_V3=...,_LLM_MODEL_CONFIG_BEDROCK_NOVA_MICRO_V1=...,_LLM_MODEL_CONFIG_BEDROCK_NOVA_LITE_V1=...,_LLM_MODEL_CONFIG_BEDROCK_NOVA_PRO_V1=...,_LLM_MODEL_CONFIG_OLLAMA_LLAMA3=... ``` - Replace the values in angle brackets with your actual configuration and secrets. - `LLM_MODEL_CONFIG_FIREWORKS_QWEN3_6` is the app-facing config key for the `fireworks_qwen3_6` model option and should map to the Fireworks serverless slug `accounts/fireworks/models/qwen3p6-plus`. - You can omit or add substitutions as needed for your deployment. 3. **Monitor the build:** - The build and deployment process will be visible in the Cloud Build console. 4. **Access your deployed service:** - After deployment, your backend will be available at the Cloud Run service URL shown in the Cloud Console. --- **Note:** - The `cloudbuild.yaml` file supports multiple environments (`main`, `staging`, `dev`) based on the branch name. - The frontend build and deployment steps are commented out by default. Uncomment them in `cloudbuild.yaml` if you wish to deploy the frontend as well. For more details, see the comments in [`cloudbuild.yaml`](cloudbuild.yaml). --- ## Links [LLM Knowledge Graph Builder Application][app-link] [Neo4j Workspace][neo4j-workspace] ## Reference [Demo of application][demo-video] ## Contact For any inquiries or support, feel free to raise [GitHub Issues][github-issues] [backend-url]: http://localhost:8000 [env-sheet]: https://docs.google.com/spreadsheets/d/1DBg3m3hz0PCZNqIjyYJsYALzdWwMlLah706Xvxt62Tk/edit?gid=184339012#gid=184339012 [env-vars]: https://docs.google.com/spreadsheets/d/1DBg3m3hz0PCZNqIjyYJsYALzdWwMlLah706Xvxt62Tk/edit?gid=0#gid=0 [app-link]: https://llm-graph-builder.neo4jlabs.com/ [neo4j-workspace]: https://workspace-preview.neo4j.io/workspace/query [demo-video]: https://www.youtube.com/watch?v=LlNy5VmV290 [github-issues]: https://github.com/neo4j-labs/llm-graph-builder/issues [bloom-url]: https://workspace-preview.neo4j.io/workspace/explore?connectURL={CONNECT_URL}&search=Show+me+a+graph&featureGenAISuggestions=true&featureGenAISuggestionsInternal=true [langchain-endpoint]: https://api.smith.langchain.com ## Happy Graph Building! ---