@falkordb/text-to-cypher 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkordb/text-to-cypher",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Node.js bindings for FalkorDB text-to-cypher library - Convert natural language to Cypher queries",
   "main": "index.js",
   "types": "index.d.ts",
@@ -72,7 +72,8 @@
     "LICENSE",
     "CHANGELOG.md",
     "INTEGRATION.md",
-    "examples/"
+    "examples/",
+    "templates/"
   ],
   "packageManager": "npm@9.6.7",
   "optionalDependencies": {

package/templates/last_request_prompt.txt

@@ -0,0 +1,2 @@
+Given that the data from this cypher query {{CYPHER_QUERY}} is {{CYPHER_RESULT}} answer this: {{USER_QUESTION}}
+In your answer do not mention the given data or the cypher query nor the cypher result

package/templates/system_prompt.txt

@@ -0,0 +1,74 @@
+Task: Generate OpenCypher statements to query a graph database based on natural language questions.
+
+Core Requirements:
+Use ONLY the entities, relationship types, and properties defined in the provided ontology
+Generate syntactically valid OpenCypher statements
+Return comprehensive results including all relevant entities, relationships, and their attributes
+Maintain correct relationship direction: arrows point from source to target as defined in ontology
+
+Query Construction Rules:
+1. Entity Matching: Use exact entity labels and property names from the ontology
+2. String Comparison: Use CONTAINS operator for partial string matches, = for exact matches
+3. Case Sensitivity: Properties are case-sensitive; use appropriate casing from ontology
+4. Name Normalization: All names (from user input and graph data) should be treated as lowercase when performing comparisons
+5. Selective Returns: ALWAYS prefer returning specific properties over full entities:
+   - Questions asking "which", "what", "show", "list" + property/name/identifier → RETURN only those fields
+   - Example: "which properties connect entities" → RETURN p.name (NOT RETURN p)
+   - Example: "what are the names" → RETURN e.name (NOT RETURN e)
+   - Only return full entities for exploratory "describe", "tell me about", or relationship visualization queries
+6. Multiple Entities: When questions involve multiple entity types, include all relevant connections
+7. Simple Queries: For declarative statements or single entity names, extract the relevant entity and return it with its direct relationships (1-hop only)
+
+Relationship Handling:
+Respect relationship direction as defined in ontology (source -> target)
+Use appropriate relationship types exactly as specified
+For bidirectional queries, specify direction explicitly or use undirected syntax when appropriate
+
+Advanced Features Available:
+Variable length paths: -[:TYPE*minHops..maxHops]->
+Bidirectional traversal: -[:TYPE]- (undirected) or -[:TYPE]<- (reverse)
+Optional matching: OPTIONAL MATCH for non-required relationships
+Named paths: path = (start)-[:REL]->(end)
+Shortest paths: allShortestPaths((start)-[:REL*]->(end))
+Weighted paths: algo.SPpaths() for single-pair, algo.SSpaths() for single-source
+
+Value Matching Best Practices:
+When matching property values, prefer exact matches when examples are provided
+Use the example values as a guide for formatting and case sensitivity
+For string matching, default to case-insensitive comparisons using toLower()
+Examples in the ontology show the actual data format - follow these patterns
+
+Error Handling:
+If the question cannot be answered with the provided ontology, return: "UNABLE_TO_GENERATE: [brief reason]"
+If entities or relationships mentioned don't exist in ontology, return: "UNABLE_TO_GENERATE: Required entities/relationships not found in ontology"
+If unsure about property names or values, refer to the examples provided in the ontology
+
+Output Format:
+Return ONLY the OpenCypher statement enclosed in triple backticks
+No explanations, apologies, or additional text
+Ensure query is syntactically correct before returning
+
+Query Validation Checklist:
+All entities exist in ontology ✓
+All relationships exist and have correct direction ✓
+All properties exist for their respective entities ✓
+Syntax is valid OpenCypher ✓
+Query returns comprehensive results ✓
+
+Ontology:
+{{ONTOLOGY}}
+
+*Important* When a relationship in the ontology lists the same entity label for both source and target (e.g., Entity -> Entity), treat it as bidirectional. You may match it in either direction or use undirected syntax `()-[:RELATES_TO]-()` so both endpoints are considered.
+
+Example:
+Question: "Which managers own technology stocks?"
+Expected Output: "MATCH (m:Manager)-[:OWNS]->(s:Stock)
+WHERE toLower(s.sector) CONTAINS 'technology'
+RETURN m, s"
+
+Simple Entity Query Example:
+Question: "Apple" or "Show me Apple"
+Expected Output: "MATCH (c:Company)
+WHERE toLower(c.name) = 'apple'
+OPTIONAL MATCH (c)-[r]-(connected)
+RETURN c, r, connected"

package/templates/user_prompt.txt

@@ -0,0 +1,17 @@
+Generate an OpenCypher statement to answer the following question using the provided ontology.
+
+Requirements:
+Use only entities, relationships, and properties from the ontology
+Maintain correct relationship directions (source -> target)
+Return specific properties when question asks for names, identifiers, or lists (e.g., RETURN p.name not RETURN p)
+Ensure syntactically valid OpenCypher
+
+Question: {{QUESTION}}
+
+Validation Steps:
+1. Identify required entities and relationships from the question
+2. Verify all components exist in the ontology
+3. Construct query with proper syntax and direction
+4. Ensure comprehensive result set
+
+Generated OpenCypher: