add text2cypher component (#1319)

Signed-off-by: jeanyu-habana <[email protected]>

Author: jeanyu-habana

.github/workflows/docker/compose/text2cypher-compose.yaml

@@ -0,0 +1,9 @@
+# Copyright (C) 2024 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+# this file should be run in the root of the repo
+services:
+  text2cypher-gaudi:
+    build:
+      dockerfile: comps/text2cypher/src/Dockerfile.intel_hpu
+    image: ${REGISTRY:-opea}/text2cypher-gaudi:${TAG:-latest}

comps/cores/mega/constants.py

@@ -35,6 +35,7 @@ class ServiceType(Enum):
     IMAGE2IMAGE = 18
     TEXT2SQL = 19
     TEXT2GRAPH = 20
+    TEXT2CYPHER = 21
 
 
 class MegaServiceEndpoint(Enum):
@@ -54,6 +55,7 @@ class MegaServiceEndpoint(Enum):
     RETRIEVALTOOL = "/v1/retrievaltool"
     FAQ_GEN = "/v1/faqgen"
     GRAPH_RAG = "/v1/graphrag"
+    HYBRID_RAG = "/v1/hybridrag"
     # Follow OPENAI
     EMBEDDINGS = "/v1/embeddings"
     TTS = "/v1/audio/speech"

comps/text2cypher/deployment/docker_compose/README.md

@@ -0,0 +1,22 @@
+# Deploy text2cypher microservice using docker-compose
+
+## Deploy on Intel Gaudi
+
+```
+unset http_proxy
+service_name="neo4j-apoc text2cypher-gaudi"
+export ip_address=$(hostname -I | awk '{print $1}')
+export host_ip=${ip_address}
+export TAG="comps"
+export NEO4J_AUTH="neo4j/neo4jtest"
+export NEO4J_URL="bolt://${ip_address}:7687"
+export NEO4J_USERNAME="neo4j"
+export NEO4J_PASSWORD="neo4jtest"
+export NEO4J_apoc_export_file_enabled=true
+export NEO4J_apoc_import_file_use__neo4j__config=true
+export NEO4J_PLUGINS=\[\"apoc\"\]
+
+cd $WORKPATH/comps/text2cypher/deployment/docker_compose/
+docker compose up ${service_name} -d
+
+```

comps/text2cypher/deployment/docker_compose/compose.yaml

@@ -0,0 +1,50 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+include:
+  - ../../../third_parties/neo4j/deployment/docker_compose/compose.yaml
+
+services:
+  text2cypher:
+    image: opea/text2cypher:${TAG:-latest}
+    container_name: text2cypher-container
+    ports:
+      - ${TEXT2CYPHER_PORT:-9097}:9097
+    depends_on:
+      neo4j-apoc:
+        condition: service_healthy
+
+  text2cypher-gaudi:
+    image: opea/text2cypher-gaudi:${TAG:-latest}
+    #pull_policy: never
+    container_name: text2cypher-gaudi-container
+    ports:
+      - ${TEXT2CYPHER_PORT:-9097}:9097
+    depends_on:
+      neo4j-apoc:
+        condition: service_healthy
+    ipc: host
+    environment:
+      no_proxy: ${no_proxy}
+      http_proxy: ${http_proxy}
+      https_proxy: ${https_proxy}
+      INDEX_NAME: ${INDEX_NAME}
+      HUGGINGFACEHUB_API_TOKEN: ${HF_TOKEN}
+      HF_TOKEN: ${HF_TOKEN}
+      LOGFLAG: ${LOGFLAG:-False}
+      HABANA_VISIBLE_DEVICES: all
+      OMPI_MCA_btl_vader_single_copy_mechanism: none
+      TOKENIZERS_PARALLELISM: False
+      NEO4J_URI: ${NEO4J_URI}
+      NEO4J_URL: ${NEO4J_URI}
+      NEO4J_USERNAME: ${NEO4J_USERNAME}
+      NEO4J_PASSWORD: ${NEO4J_PASSWORD}
+      host_ip: ${host_ip}
+    runtime: habana
+    cap_add:
+      - SYS_NICE
+    restart: unless-stopped
+
+networks:
+  default:
+    driver: bridge

comps/text2cypher/src/Dockerfile.intel_hpu

@@ -0,0 +1,48 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+# HABANA environment
+FROM vault.habana.ai/gaudi-docker/1.19.0/ubuntu22.04/habanalabs/pytorch-installer-2.5.1 AS hpu
+
+ENV LANG=en_US.UTF-8
+ARG REPO=https://github.com/huggingface/optimum-habana.git
+ARG REPO_VER=v1.15.0
+
+RUN apt-get update && apt-get install -y --no-install-recommends --fix-missing \
+    git-lfs \
+    libgl1-mesa-glx \
+    libjemalloc-dev
+
+#RUN useradd -m -s /bin/bash user && \
+#    mkdir -p /home/user && \
+#    chown -R user /home/user/
+
+RUN git lfs install
+
+COPY comps /root/comps
+#RUN chown -R user /home/user/comps/text2cypher
+
+#RUN rm -rf /etc/ssh/ssh_host*
+
+RUN pip install --no-cache-dir --upgrade pip setuptools && \
+    pip install --no-cache-dir --upgrade-strategy eager optimum[habana] && \
+    pip install --no-cache-dir git+https://github.com/HabanaAI/[email protected]
+
+RUN git clone ${REPO} /root/optimum-habana && \
+    cd /root/optimum-habana && git checkout ${REPO_VER} && \
+    cd /root/comps/text2cypher/src && pip install --no-cache-dir -r requirements.txt && \
+    pip install --no-cache-dir --upgrade --force-reinstall pydantic numpy==1.26.3
+
+# Set environment variables
+ENV PYTHONPATH=/root:/usr/lib/habanalabs/:/root/optimum-habana
+ENV HABANA_VISIBLE_DEVICES=all
+ENV OMPI_MCA_btl_vader_single_copy_mechanism=none
+ENV DEBIAN_FRONTEND="noninteractive"  TZ=Etc/UTC
+
+#USER user
+WORKDIR /root/comps/text2cypher/src
+
+RUN echo python opea_text2cypher_microservice.py --device hpu --use_hpu_graphs --bf16 >> run.sh
+
+CMD bash run.sh
+

comps/text2cypher/src/README.md

@@ -0,0 +1,127 @@
+# 🛢 Text-to-Cypher Microservice
+
+The microservice enables a wide range of use cases, making it a versatile tool for businesses, researchers, and individuals alike. Users can generate queries based on natural language questions, enabling them to quickly retrieve relevant data from graph databases. This service executes locally on Intel Gaudi.
+
+---
+
+## 🛠️ Features
+
+**Implement Cypher Query based on input text**: Transform user-provided natural language into Cypher queries, subsequently executing them to retrieve data from Graph databases.
+
+---
+
+## ⚙️ Implementation
+
+The text-to-cypher microservice able to implement with various framework and support various types of Graph databases.
+
+### 🔗 Utilizing Text-to-Cypher with Langchain framework
+
+The follow guide provides set-up instructions and comprehensive details regarding the Text-to-Cypher microservices via LangChain. In this configuration, we will employ Neo4J DB as our example database to showcase this microservice.
+
+---
+
+### Start Neo4J Service
+
+### 🚀 Start Text2Cypher Microservice with Python（Option 1）
+
+#### Install Requirements
+
+```bash
+pip install -r requirements.txt
+```
+
+#### Start Text-to-Cypher Microservice with Python Script
+
+Start Text-to-Cypher microservice with below command.
+
+```bash
+python3 opea_text2cypher_microservice.py
+```
+
+---
+
+### 🚀 Start Microservice with Docker (Option 2)
+
+#### Build Docker Image
+
+```bash
+cd GenAIComps/
+docker build -t opea/text2cypher:latest -f comps/text2cypher/src/Dockerfile.intel_hpu .
+```
+
+#### Run Docker with CLI (Option A)
+
+```bash
+docker run  --name="comps-langchain-text2cypher"  -p 9097:8080 --ipc=host opea/text2cypher:latest
+```
+
+#### Run via docker compose (Option B)
+
+##### Setup Environment Variables.
+
+```bash
+ip_address=$(hostname -I | awk '{print $1}')
+export HF_TOKEN=${HUGGINGFACEHUB_API_TOKEN}
+export NEO4J_USER=neo4j
+export NEO4J_PASSWORD=neo4jtest
+export NEO4J_URL="bolt://${ip_address}:7687"
+export TEXT2CYPHER_PORT=11801
+```
+
+##### Start the services.
+
+- Gaudi2 HPU
+
+```bash
+cd comps/text2cypher/deployment/docker_compose
+docker compose -f compose.yaml up text2cypher-gaudi -d
+```
+
+---
+
+### ✅ Invoke the microservice.
+
+The Text-to-Cypher microservice exposes the following API endpoints:
+
+- Execute Cypher Query with Pre-seeded Data and Schema:
+
+  ```bash
+  curl http://${ip_address}:${TEXT2CYPHER_PORT}/v1/text2cypher\
+        -X POST \
+        -d '{"input_text": "what are the symptoms for Diabetes?","conn_str": {"user": "'${NEO4J_USERNAME}'","password": "'${NEO4J_PASSWPORD}'","url": "'${NEO4J_URL}'" }}' \
+        -H 'Content-Type: application/json'
+  ```
+
+- Execute Cypher Query with User Data and Schema:
+
+Define customized cypher_insert statements:
+
+```bash
+export cypher_insert='
+ LOAD CSV WITH HEADERS FROM "https://docs.google.com/spreadsheets/d/e/2PACX-1vQCEUxVlMZwwI2sn2T1aulBrRzJYVpsM9no8AEsYOOklCDTljoUIBHItGnqmAez62wwLpbvKMr7YoHI/pub?gid=0&single=true&output=csv" AS rows
+ MERGE (d:disease {name:rows.Disease})
+ MERGE (dt:diet {name:rows.Diet})
+ MERGE (d)-[:HOME_REMEDY]->(dt)
+
+ MERGE (m:medication {name:rows.Medication})
+ MERGE (d)-[:TREATMENT]->(m)
+
+ MERGE (s:symptoms {name:rows.Symptom})
+ MERGE (d)-[:MANIFESTATION]->(s)
+
+ MERGE (p:precaution {name:rows.Precaution})
+ MERGE (d)-[:PREVENTION]->(p)
+'
+```
+
+Pass the cypher_insert to the cypher2text service. The user can also specify whether to refresh the Neo4j database using the refresh_db option.
+
+```bash
+ curl http://${ip_address}:${TEXT2CYPHER_PORT}/v1/text2cypher \
+        -X POST \
+        -d '{"input_text": "what are the symptoms for Diabetes?", \
+             "conn_str": {"user": "'${NEO4J_USERNAME}'","password": "'${NEO4J_PASSWPORD}'","url": "'${NEO4J_URL}'" } \
+             "seeding": {"cypher_insert": "'${cypher_insert}'","refresh_db": "True" }}' \
+        -H 'Content-Type: application/json'
+
+```

comps/text2cypher/src/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0

comps/text2cypher/src/integrations/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0