Text2Cypher

Preamble¶

NOTE: The APOC core library must be installed in your Neo4j instance (Installation)

In [2]:

from ragsphere import RAG
from ragsphere.models import Text2CypherRetrieverConfig
from ragsphere.graphrag import Text2CypherRetriever

from ragsphere import RAG from ragsphere.models import Text2CypherRetrieverConfig from ragsphere.graphrag import Text2CypherRetriever

C:\ProgramData\mambaforge_24.3.0.0\envs\raglib\Lib\site-packages\tqdm\auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

Retrieval Configuration¶

In [3]:

# Option 1:
retriever_config_dict = {
    "examples": ["USER INPUT: 'Which actors starred in the Matrix?' QUERY: MATCH (p:Person)-[:ACTED_IN]->(m:Movie) WHERE m.title = 'The Matrix' RETURN p.name"]
}
retriever_config_class = Text2CypherRetrieverConfig(**retriever_config_dict)

# Option 2:
retriever_class_with_config_dict = Text2CypherRetriever(retriever_config_dict) # parameter=retriever_config_dict

# Option 3:
retriever_class_with_config_class = Text2CypherRetriever(config=retriever_config_class)

# Option 1: retriever_config_dict = { "examples": ["USER INPUT: 'Which actors starred in the Matrix?' QUERY: MATCH (p:Person)-[:ACTED_IN]->(m:Movie) WHERE m.title = 'The Matrix' RETURN p.name"] } retriever_config_class = Text2CypherRetrieverConfig(**retriever_config_dict) # Option 2: retriever_class_with_config_dict = Text2CypherRetriever(retriever_config_dict) # parameter=retriever_config_dict # Option 3: retriever_class_with_config_class = Text2CypherRetriever(config=retriever_config_class)

In [4]:

print(retriever_config_class)
print(retriever_class_with_config_dict.config)
print(retriever_class_with_config_class.config)

print(retriever_config_class) print(retriever_class_with_config_dict.config) print(retriever_class_with_config_class.config)

Text2CypherRetrieverConfig(top_k=0, examples=["USER INPUT: 'Which actors starred in the Matrix?' QUERY: MATCH (p:Person)-[:ACTED_IN]->(m:Movie) WHERE m.title = 'The Matrix' RETURN p.name"])
Text2CypherRetrieverConfig(top_k=0, examples=["USER INPUT: 'Which actors starred in the Matrix?' QUERY: MATCH (p:Person)-[:ACTED_IN]->(m:Movie) WHERE m.title = 'The Matrix' RETURN p.name"])
Text2CypherRetrieverConfig(top_k=0, examples=["USER INPUT: 'Which actors starred in the Matrix?' QUERY: MATCH (p:Person)-[:ACTED_IN]->(m:Movie) WHERE m.title = 'The Matrix' RETURN p.name"])

Instantiation¶

Default¶

In [5]:

rag = RAG(
    retriever = "text2cypher", 
    verbosity=1
)

rag = RAG( retriever = "text2cypher", verbosity=1 )

2026-02-09 23:00:39,480 - INFO - RAG initialized with verbosity 1
2026-02-09 23:00:39,493 - INFO - The retrieval technique is set to: 'text2cypher'

2026-02-09 23:00:39,493 - INFO - The document path has not been specified.
2026-02-09 23:00:39,494 - INFO - Using default path: '../db/data'

2026-02-09 23:00:39,495 - INFO - The graph database has not been specified.
2026-02-09 23:00:39,496 - INFO - Using default graph database: 'Neo4j'

2026-02-09 23:00:39,496 - INFO - The vector database has not been specified.
2026-02-09 23:00:39,498 - INFO - Using default vector database: 'Neo4j'

2026-02-09 23:00:39,499 - INFO - The indexing LLM has not been specified.
2026-02-09 23:00:39,500 - INFO - Using the default indexing LLM: 'gpt-oss:120b'

2026-02-09 23:00:39,501 - INFO - The query LLM has not been specified.
2026-02-09 23:00:39,501 - INFO - Using the default query LLM: 'gpt-oss:120b'

2026-02-09 23:00:39,503 - INFO - The embedding model has not been specified.
2026-02-09 23:00:39,503 - INFO - Using the default embedding model: 'all-MiniLM-L6-v2'
2026-02-09 23:00:39,504 - INFO - Successfully loaded

Custom¶

In [6]:

# Text2Cypher
rag = RAG(
    retriever="text2cypher", 
    retriever_config=retriever_config_dict,
    verbosity=1
)

# Text2Cypher rag = RAG( retriever="text2cypher", retriever_config=retriever_config_dict, verbosity=1 )

2026-02-09 23:01:41,491 - INFO - RAG initialized with verbosity 1
2026-02-09 23:01:41,493 - INFO - The retrieval technique is set to: 'text2cypher'

2026-02-09 23:01:41,493 - INFO - The document path has not been specified.
2026-02-09 23:01:41,494 - INFO - Using default path: '../db/data'

2026-02-09 23:01:41,494 - INFO - The graph database has not been specified.
2026-02-09 23:01:41,495 - INFO - Using default graph database: 'Neo4j'

2026-02-09 23:01:41,495 - INFO - The vector database has not been specified.
2026-02-09 23:01:41,496 - INFO - Using default vector database: 'Neo4j'

2026-02-09 23:01:41,497 - INFO - The indexing LLM has not been specified.
2026-02-09 23:01:41,498 - INFO - Using the default indexing LLM: 'gpt-oss:120b'

2026-02-09 23:01:41,498 - INFO - The query LLM has not been specified.
2026-02-09 23:01:41,499 - INFO - Using the default query LLM: 'gpt-oss:120b'

2026-02-09 23:01:41,499 - INFO - The embedding model has not been specified.
2026-02-09 23:01:41,500 - INFO - Using the default embedding model: 'all-MiniLM-L6-v2'
2026-02-09 23:01:41,500 - INFO - Successfully loaded

Retrieval¶

In [27]:

query_text = "List all anomaly report IDs"
#query_text = "What is the structure of the anomaly reports?"
retrieval_query = "MATCH (a:AnomalyReport) RETURN a.reportId"

response = rag.query(
    prompt=query_text, 
    #retrieval_query=retrieval_query, 
    verbosity=1
)

query_text = "List all anomaly report IDs" #query_text = "What is the structure of the anomaly reports?" retrieval_query = "MATCH (a:AnomalyReport) RETURN a.reportId" response = rag.query( prompt=query_text, #retrieval_query=retrieval_query, verbosity=1 )

2026-02-09 14:01:07,278 - INFO - DOING 'text2cypher' RETRIEVAL WITH Text2CypherRetrieverConfig(top_k=0, examples=["USER INPUT: 'Which actors starred in the Matrix?' QUERY: MATCH (p:Person)-[:ACTED_IN]->(m:Movie) WHERE m.title = 'The Matrix' RETURN p.name"])
2026-02-09 14:01:07,279 - INFO - USING THE FOLLOWING QUERY: 'List all anomaly report IDs'

Connection successful: True
{"temperature": 0}

2026-02-09 14:01:18,723 - INFO - HTTP Request: POST http://sc-030362l.intra.dlr.de:11434/api/chat "HTTP/1.1 200 OK"

In [31]:

response

response

Out[31]:

{'cypher': 'MATCH (a:AnomalyReport) RETURN a.reportId',
 'retriever_result': [RetrieverResultItem(content="<Record a.reportId='0.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='1.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='10.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='11.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='12.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='13.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='14.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='15.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='16.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='17.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='18.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='19.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='2.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='20.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='21.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='22.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='23.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='24.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='25.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='26.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='27.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='28.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='29.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='3.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='4.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='5.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='6.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='7.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='8.json'>", metadata=None),
  RetrieverResultItem(content="<Record a.reportId='9.json'>", metadata=None)]}

In [28]:

response["cypher"]

response["cypher"]

Out[28]:

'MATCH (a:AnomalyReport) RETURN a.reportId'

In [29]:

response["retriever_result"]

response["retriever_result"]

Out[29]:

[RetrieverResultItem(content="<Record a.reportId='0.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='1.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='10.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='11.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='12.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='13.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='14.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='15.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='16.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='17.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='18.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='19.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='2.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='20.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='21.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='22.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='23.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='24.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='25.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='26.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='27.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='28.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='29.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='3.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='4.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='5.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='6.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='7.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='8.json'>", metadata=None),
 RetrieverResultItem(content="<Record a.reportId='9.json'>", metadata=None)]