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= <s3 bucket url or youtube 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= <s3 bucket url or youtube 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= <s3 bucket url or youtube 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= <s3 bucket url or youtube 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 nametasks
* = 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 uriuserName
* = Neo4j database usernamepassword
* = Neo4j database passwordmodel
* = LLM modelquestion
* = User query for the chatbotsession_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 URIuserName
* = Neo4j database usernamepassword
* = Neo4j database passworddatabase
* = Neo4j database nameembedding_provider
* = Selected embedding provider (openai, gemini, vertexai, bedrock, sentence_transformer)embedding_model
* = Embedding model chosen by the useremail
* = 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 Emailembedding_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 chatbotcontext
* = context retrieved by retrieval mode used for answer generationanswer
* = answer generated by chatbotmodel
* = LLM modelmode
* = 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 chatbotcontext
* = context retrieved by retrieval mode used for answer generationanswer
* = answer generated by chatbotreference
* = ground truth/ expected answer provided by usermodel
* = LLM modelmode
* = 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 namedocument_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 [email protected] 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:
bashNEO4J_URI=<your-neo4j-uri>
NEO4J_USERNAME=<your-username>
NEO4J_PASSWORD=<your-password>
NEO4J_DATABASE=<your-database-name>
3. Run:
bashcd 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 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:
bashVITE_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:
bashLLM_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:
bashVITE_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:
bashVITE_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:
bashcd 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:
bashNEO4J_URI=<your-neo4j-uri>
NEO4J_USERNAME=<your-username>
NEO4J_PASSWORD=<your-password>
NEO4J_DATABASE=<your-database-name>
3. Run:
bashcd 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
bashgcloud run deploy dev-frontend \
--source . \
--region us-central1 \
--allow-unauthenticated
#### Backend Deployment
bashgcloud run deploy dev-backend \
--set-env-vars "OPENAI_API_KEY=<your-openai-api-key>" \
--set-env-vars "DIFFBOT_API_KEY=<your-diffbot-api-key>" \
--set-env-vars "NEO4J_URI=<your-neo4j-uri>" \
--set-env-vars "NEO4J_USERNAME=<your-username>" \
--set-env-vars "NEO4J_PASSWORD=<your-password>" \
--source . \
--region us-central1 \
--allow-unauthenticated
---
For local llms (Ollama)
1. Pull the docker image of ollama
bashdocker pull ollama/ollama
2. Run the ollama docker image
bashdocker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
3. Execute any llm model, e.g., llama3
bashdocker exec -it ollama ollama run llama3
4. Configure env variable in docker compose.
envLLM_MODEL_CONFIG_ollama_<model_name>
# example
LLM_MODEL_CONFIG_ollama_llama3=${LLM_MODEL_CONFIG_ollama_llama3-llama3,http://host.docker.internal:11434}
5. Configure the backend API url
envVITE_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_<model_name> | 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
- 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:
bashgcloud auth login
gcloud config set project <YOUR_PROJECT_ID>
2. Run Cloud Build manually:
bashgcloud builds submit --config cloudbuild.yaml \
--substitutions=_REGION=us-central1,_REPO=cloud-run-repo,_OPENAI_API_KEY=<your-openai-key>,_DIFFBOT_API_KEY=<your-diffbot-key>,_BUCKET_UPLOAD_FILE=<your-bucket>,_BUCKET_FAILED_FILE=<your-bucket>,_PROJECT_ID=<your-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.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!
---