@falkordb/text-to-cypher 0.1.0

package/README.md

@@ -0,0 +1,294 @@
+# @falkordb/text-to-cypher-node
+
+Node.js bindings for the [FalkorDB text-to-cypher](https://github.com/FalkorDB/text-to-cypher) library - Convert natural language to Cypher queries using AI.
+
+[![npm version](https://img.shields.io/npm/v/@falkordb/text-to-cypher-node.svg)](https://www.npmjs.com/package/@falkordb/text-to-cypher-node)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🤖 **AI-Powered**: Convert natural language questions to Cypher queries using GPT-4, Claude, Gemini, and other AI models
+- 🔍 **Schema Discovery**: Automatically discovers and analyzes graph database schemas
+- ✅ **Query Validation**: Built-in validation to catch syntax errors before execution
+- 🚀 **High Performance**: Native Rust implementation with Node.js bindings via NAPI-RS
+- 🌍 **Cross-Platform**: Pre-built binaries for Linux, macOS, and Windows
+- 📦 **Zero Dependencies**: No runtime dependencies required
+
+## Installation
+
+```bash
+npm install @falkordb/text-to-cypher-node
+```
+
+**📚 New to this library? Check out the [Quick Start Guide](QUICKSTART.md) for a 5-minute introduction!**
+
+## Quick Start
+
+```javascript
+const { TextToCypher } = require('@falkordb/text-to-cypher-node');
+
+// Create a client
+const client = new TextToCypher({
+  model: 'gpt-4o-mini',
+  apiKey: process.env.OPENAI_API_KEY,
+  falkordbConnection: 'falkor://localhost:6379'
+});
+
+// Convert text to Cypher and execute
+async function main() {
+  const response = await client.textToCypher(
+    'movies',
+    'Find all actors who appeared in movies released after 2020'
+  );
+
+  console.log('Generated Query:', response.cypherQuery);
+  console.log('Result:', response.cypherResult);
+  console.log('Answer:', response.answer);
+}
+
+main().catch(console.error);
+```
+
+## API Reference
+
+### `new TextToCypher(options)`
+
+Creates a new text-to-cypher client.
+
+**Parameters:**
+- `options.model` (string): AI model to use (e.g., `'gpt-4o-mini'`, `'anthropic:claude-3'`, `'gemini:gemini-2.0-flash-exp'`)
+- `options.apiKey` (string): API key for the AI service
+- `options.falkordbConnection` (string): FalkorDB connection string (e.g., `'falkor://localhost:6379'`)
+
+**Example:**
+```javascript
+const client = new TextToCypher({
+  model: 'gpt-4o-mini',
+  apiKey: 'sk-...',
+  falkordbConnection: 'falkor://localhost:6379'
+});
+```
+
+### `textToCypher(graphName, question)`
+
+Converts natural language to Cypher, executes the query, and generates a natural language answer.
+
+**Parameters:**
+- `graphName` (string): Name of the graph to query
+- `question` (string): Natural language question
+
+**Returns:** `Promise<TextToCypherResponse>`
+
+**Example:**
+```javascript
+const response = await client.textToCypher('movies', 'Who directed The Matrix?');
+console.log(response.answer); // "The Matrix was directed by..."
+```
+
+### `textToCypherWithMessages(graphName, messages)`
+
+Same as `textToCypher` but accepts multiple messages for conversation context.
+
+**Parameters:**
+- `graphName` (string): Name of the graph to query
+- `messages` (Array<Message>): Array of conversation messages
+
+**Example:**
+```javascript
+const response = await client.textToCypherWithMessages('movies', [
+  { role: 'user', content: 'Show me actors' },
+  { role: 'assistant', content: 'Here are some actors...' },
+  { role: 'user', content: 'Filter those who acted after 2020' }
+]);
+```
+
+### `cypherOnly(graphName, question)`
+
+Generates a Cypher query without executing it.
+
+**Parameters:**
+- `graphName` (string): Name of the graph
+- `question` (string): Natural language question
+
+**Returns:** `Promise<TextToCypherResponse>` (with only `schema` and `cypherQuery` populated)
+
+**Example:**
+```javascript
+const response = await client.cypherOnly('movies', 'Find all actors');
+console.log('Generated query:', response.cypherQuery);
+// Use the query however you want
+```
+
+### `discoverSchema(graphName)`
+
+Discovers and returns the schema of a graph as JSON.
+
+**Parameters:**
+- `graphName` (string): Name of the graph
+
+**Returns:** `Promise<string>` (JSON string)
+
+**Example:**
+```javascript
+const schema = await client.discoverSchema('movies');
+const schemaObj = JSON.parse(schema);
+console.log('Nodes:', schemaObj.nodes);
+console.log('Relationships:', schemaObj.relationships);
+```
+
+## Types
+
+### TextToCypherResponse
+
+```typescript
+interface TextToCypherResponse {
+  status: string;           // "success" or "error"
+  schema?: string;          // JSON schema of the graph
+  cypherQuery?: string;     // Generated Cypher query
+  cypherResult?: string;    // Query execution result
+  answer?: string;          // Natural language answer
+  error?: string;           // Error message if status is "error"
+}
+```
+
+### Message
+
+```typescript
+interface Message {
+  role: string;    // "user", "assistant", or "system"
+  content: string; // Message content
+}
+```
+
+## Supported AI Models
+
+This library uses the [genai](https://crates.io/crates/genai) crate and supports:
+
+- **OpenAI**: `gpt-4o-mini`, `gpt-4o`, `gpt-4-turbo`, etc.
+- **Anthropic**: `anthropic:claude-3-5-sonnet-20241022`, `anthropic:claude-3-opus-20240229`
+- **Google Gemini**: `gemini:gemini-2.0-flash-exp`, `gemini:gemini-1.5-pro`
+
+See [genai documentation](https://docs.rs/genai/latest/genai/) for a complete list.
+
+## Examples
+
+### Using with FalkorDB Browser
+
+```javascript
+const { TextToCypher } = require('@falkordb/text-to-cypher-node');
+
+// In your Express.js or other Node.js server
+app.post('/api/text-to-cypher', async (req, res) => {
+  const { graphName, question } = req.body;
+
+  try {
+    const client = new TextToCypher({
+      model: 'gpt-4o-mini',
+      apiKey: process.env.OPENAI_API_KEY,
+      falkordbConnection: process.env.FALKORDB_CONNECTION
+    });
+
+    const response = await client.textToCypher(graphName, question);
+    res.json(response);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+### TypeScript Usage
+
+```typescript
+import { TextToCypher, ClientOptions, TextToCypherResponse } from '@falkordb/text-to-cypher-node';
+
+const options: ClientOptions = {
+  model: 'gpt-4o-mini',
+  apiKey: process.env.OPENAI_API_KEY!,
+  falkordbConnection: 'falkor://localhost:6379'
+};
+
+const client = new TextToCypher(options);
+
+const response: TextToCypherResponse = await client.textToCypher(
+  'movies',
+  'Find top 10 highest rated movies'
+);
+
+console.log(response.answer);
+```
+
+### Error Handling
+
+```javascript
+try {
+  const response = await client.textToCypher('movies', 'Find all actors');
+  
+  if (response.status === 'error') {
+    console.error('Error:', response.error);
+  } else {
+    console.log('Success:', response.answer);
+  }
+} catch (error) {
+  console.error('Exception:', error.message);
+}
+```
+
+## Requirements
+
+- Node.js >= 10
+- FalkorDB instance running and accessible
+- API key for your chosen AI provider (OpenAI, Anthropic, etc.)
+
+## Development
+
+### Building from Source
+
+```bash
+# Install dependencies
+npm install
+
+# Build the native module
+npm run build
+
+# Run tests
+npm test
+```
+
+### Prerequisites for Building
+
+- Rust toolchain (install from [rustup.rs](https://rustup.rs/))
+- Node.js >= 10
+- C++ compiler (platform-specific)
+
+## Platform Support
+
+Pre-built binaries are available for:
+
+- Linux x64 (glibc and musl)
+- Linux ARM64 (glibc and musl)
+- macOS x64 (Intel)
+- macOS ARM64 (Apple Silicon)
+- Windows x64
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Related Projects
+
+- [text-to-cypher](https://github.com/FalkorDB/text-to-cypher) - The underlying Rust library
+- [falkordb-browser](https://github.com/FalkorDB/falkordb-browser) - FalkorDB web interface
+- [FalkorDB](https://github.com/FalkorDB/FalkorDB) - Graph database
+
+## Support
+
+- [GitHub Issues](https://github.com/FalkorDB/text-to-cypher-node/issues)
+- [FalkorDB Discord](https://discord.gg/falkordb)
+
+## Acknowledgments
+
+Built with [NAPI-RS](https://napi.rs/) - A framework for building compiled Node.js add-ons in Rust. 

package/examples/README.md

@@ -0,0 +1,50 @@
+# Examples
+
+This directory contains example code demonstrating how to use `@falkordb/text-to-cypher-node`.
+
+## Running Examples
+
+### JavaScript Example
+
+```bash
+# Set environment variables
+export OPENAI_API_KEY="your-api-key"
+export FALKORDB_CONNECTION="falkor://localhost:6379"
+
+# Run the example
+node examples/basic-usage.js
+```
+
+### TypeScript Example
+
+```bash
+# Install TypeScript if needed
+npm install -g typescript ts-node
+
+# Run the TypeScript example
+ts-node examples/typescript-usage.ts
+```
+
+## Examples Included
+
+1. **basic-usage.js** - Comprehensive JavaScript example showing all major features
+2. **typescript-usage.ts** - TypeScript example with type safety
+
+## Prerequisites
+
+- FalkorDB instance running on `localhost:6379` (or set `FALKORDB_CONNECTION`)
+- Valid OpenAI API key (or API key for your chosen AI provider)
+- Sample graph data loaded in FalkorDB
+
+## Creating Sample Data
+
+If you need sample data for testing, you can use FalkorDB's movie graph:
+
+```bash
+# Connect to FalkorDB
+redis-cli
+
+# Create sample movie graph
+GRAPH.QUERY movies "CREATE (:Actor {name: 'Tom Hanks'})-[:ACTED_IN]->(:Movie {title: 'Forrest Gump', year: 1994})"
+GRAPH.QUERY movies "CREATE (:Actor {name: 'Robin Williams'})-[:ACTED_IN]->(:Movie {title: 'Good Will Hunting', year: 1997})"
+```

package/examples/basic-usage.js

@@ -0,0 +1,94 @@
+/**
+ * Basic usage example for text-to-cypher-node
+ * 
+ * This example demonstrates how to:
+ * 1. Create a TextToCypher client
+ * 2. Convert natural language to Cypher and execute queries
+ * 3. Generate queries without execution
+ * 4. Discover graph schema
+ */
+
+const { TextToCypher } = require('../index');
+
+async function main() {
+  // Create a client with your configuration
+  const client = new TextToCypher({
+    model: 'gpt-4o-mini',
+    apiKey: process.env.OPENAI_API_KEY || 'your-api-key-here',
+    falkordbConnection: process.env.FALKORDB_CONNECTION || 'falkor://localhost:6379'
+  });
+
+  const graphName = 'movies';
+
+  console.log('=== Text-to-Cypher Node.js Example ===\n');
+
+  // Example 1: Discover Schema
+  console.log('1. Discovering graph schema...');
+  try {
+    const schema = await client.discoverSchema(graphName);
+    const schemaObj = JSON.parse(schema);
+    console.log('Schema discovered:');
+    console.log(JSON.stringify(schemaObj, null, 2));
+  } catch (error) {
+    console.error('Error discovering schema:', error.message);
+  }
+
+  console.log('\n---\n');
+
+  // Example 2: Generate Cypher Query Only
+  console.log('2. Generating Cypher query (without execution)...');
+  try {
+    const response = await client.cypherOnly(
+      graphName,
+      'Find all actors who appeared in movies released after 2020'
+    );
+    console.log('Generated query:', response.cypherQuery);
+  } catch (error) {
+    console.error('Error generating query:', error.message);
+  }
+
+  console.log('\n---\n');
+
+  // Example 3: Full Text-to-Cypher with Execution
+  console.log('3. Converting text to Cypher and executing...');
+  try {
+    const response = await client.textToCypher(
+      graphName,
+      'Show me the top 5 highest rated movies'
+    );
+    
+    if (response.status === 'success') {
+      console.log('Query:', response.cypherQuery);
+      console.log('Result:', response.cypherResult);
+      console.log('Answer:', response.answer);
+    } else {
+      console.error('Error:', response.error);
+    }
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+
+  console.log('\n---\n');
+
+  // Example 4: Using Conversation History
+  console.log('4. Using conversation with multiple messages...');
+  try {
+    const response = await client.textToCypherWithMessages(graphName, [
+      { role: 'user', content: 'Show me actors' },
+      { role: 'assistant', content: 'Here are some actors from the graph' },
+      { role: 'user', content: 'Now show me only those who acted in movies after 2020' }
+    ]);
+    
+    if (response.status === 'success') {
+      console.log('Query:', response.cypherQuery);
+      console.log('Answer:', response.answer);
+    } else {
+      console.error('Error:', response.error);
+    }
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+// Run the examples
+main().catch(console.error);

package/examples/typescript-usage.ts

@@ -0,0 +1,52 @@
+/**
+ * TypeScript example for text-to-cypher-node
+ */
+
+import { TextToCypher, ClientOptions, TextToCypherResponse } from '../index';
+
+async function main(): Promise<void> {
+  // Create client with type safety
+  const options: ClientOptions = {
+    model: 'gpt-4o-mini',
+    apiKey: process.env.OPENAI_API_KEY || 'your-api-key-here',
+    falkordbConnection: process.env.FALKORDB_CONNECTION || 'falkor://localhost:6379'
+  };
+
+  const client = new TextToCypher(options);
+  const graphName = 'movies';
+
+  console.log('=== TypeScript Text-to-Cypher Example ===\n');
+
+  // Type-safe query execution
+  try {
+    const response: TextToCypherResponse = await client.textToCypher(
+      graphName,
+      'Find actors who worked with Tom Hanks'
+    );
+
+    if (response.status === 'success') {
+      console.log('Generated Query:', response.cypherQuery);
+      console.log('Result:', response.cypherResult);
+      console.log('Answer:', response.answer);
+    } else {
+      console.error('Error:', response.error);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Exception:', error.message);
+    }
+  }
+
+  // Schema discovery with type safety
+  try {
+    const schemaJson: string = await client.discoverSchema(graphName);
+    const schema = JSON.parse(schemaJson);
+    console.log('\nSchema:', schema);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Schema discovery failed:', error.message);
+    }
+  }
+}
+
+main().catch(console.error);

package/index.d.ts

@@ -0,0 +1,174 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Options for creating a TextToCypher client */
+export interface ClientOptions {
+  /** The AI model to use (e.g., "gpt-4o-mini", "anthropic:claude-3") */
+  model: string
+  /** API key for the AI service */
+  apiKey: string
+  /** FalkorDB connection string (e.g., "falkor://localhost:6379") */
+  falkordbConnection: string
+}
+/** A chat message in the conversation */
+export interface Message {
+  /** Role of the message sender: "user", "assistant", or "system" */
+  role: string
+  /** Content of the message */
+  content: string
+}
+/** Response from text-to-cypher operations */
+export interface TextToCypherResponse {
+  /** Status of the operation: "success" or "error" */
+  status: string
+  /** The discovered graph schema (JSON string) */
+  schema?: string
+  /** The generated Cypher query */
+  cypherQuery?: string
+  /** The result from executing the Cypher query */
+  cypherResult?: string
+  /** Natural language answer generated from the results */
+  answer?: string
+  /** Error message if status is "error" */
+  error?: string
+}
+/**
+ * Node.js wrapper for the text-to-cypher Rust library
+ *
+ * This class provides methods to convert natural language text to Cypher queries
+ * and execute them against a FalkorDB instance.
+ *
+ * # Example
+ *
+ * ```javascript
+ * const { TextToCypher } = require('@falkordb/text-to-cypher-node');
+ *
+ * const client = new TextToCypher({
+ *   model: 'gpt-4o-mini',
+ *   apiKey: 'your-api-key',
+ *   falkordbConnection: 'falkor://localhost:6379'
+ * });
+ *
+ * const response = await client.textToCypher('movies', 'Find all actors');
+ * console.log(response.answer);
+ * ```
+ */
+export declare class TextToCypher {
+  /**
+   * Creates a new TextToCypher client
+   *
+   * # Arguments
+   *
+   * * `options` - Client configuration including model, API key, and FalkorDB connection
+   *
+   * # Example
+   *
+   * ```javascript
+   * const client = new TextToCypher({
+   *   model: 'gpt-4o-mini',
+   *   apiKey: 'your-api-key',
+   *   falkordbConnection: 'falkor://localhost:6379'
+   * });
+   * ```
+   */
+  constructor(options: ClientOptions)
+  /**
+   * Converts natural language text to Cypher and executes the query
+   *
+   * This method:
+   * 1. Discovers the graph schema
+   * 2. Generates a Cypher query using AI
+   * 3. Executes the query
+   * 4. Generates a natural language answer
+   *
+   * # Arguments
+   *
+   * * `graph_name` - Name of the graph to query
+   * * `question` - Natural language question or request
+   *
+   * # Returns
+   *
+   * A promise that resolves to a TextToCypherResponse containing the query, result, and answer
+   *
+   * # Example
+   *
+   * ```javascript
+   * const response = await client.textToCypher(
+   *   'movies',
+   *   'Find all actors who appeared in movies released after 2020'
+   * );
+   * console.log('Query:', response.cypherQuery);
+   * console.log('Answer:', response.answer);
+   * ```
+   */
+  textToCypher(graphName: string, question: string): Promise<TextToCypherResponse>
+  /**
+   * Converts natural language text to Cypher and executes the query with multiple messages
+   *
+   * This method allows for conversation history by accepting multiple messages.
+   *
+   * # Arguments
+   *
+   * * `graph_name` - Name of the graph to query
+   * * `messages` - Array of conversation messages
+   *
+   * # Returns
+   *
+   * A promise that resolves to a TextToCypherResponse
+   *
+   * # Example
+   *
+   * ```javascript
+   * const response = await client.textToCypherWithMessages('movies', [
+   *   { role: 'user', content: 'Show me actors' },
+   *   { role: 'assistant', content: 'Here are the actors...' },
+   *   { role: 'user', content: 'Filter those who acted after 2020' }
+   * ]);
+   * ```
+   */
+  textToCypherWithMessages(graphName: string, messages: Array<Message>): Promise<TextToCypherResponse>
+  /**
+   * Generates a Cypher query without executing it
+   *
+   * Use this when you only want to generate the query for inspection or manual execution.
+   *
+   * # Arguments
+   *
+   * * `graph_name` - Name of the graph to generate query for
+   * * `question` - Natural language question or request
+   *
+   * # Returns
+   *
+   * A promise that resolves to a TextToCypherResponse with only the schema and query
+   *
+   * # Example
+   *
+   * ```javascript
+   * const response = await client.cypherOnly('movies', 'Find all actors');
+   * console.log('Generated query:', response.cypherQuery);
+   * // You can now review, modify, or execute the query yourself
+   * ```
+   */
+  cypherOnly(graphName: string, question: string): Promise<TextToCypherResponse>
+  /**
+   * Discovers and returns the schema of a graph
+   *
+   * # Arguments
+   *
+   * * `graph_name` - Name of the graph to discover schema for
+   *
+   * # Returns
+   *
+   * A promise that resolves to a JSON string representing the graph schema
+   *
+   * # Example
+   *
+   * ```javascript
+   * const schema = await client.discoverSchema('movies');
+   * console.log('Schema:', JSON.parse(schema));
+   * ```
+   */
+  discoverSchema(graphName: string): Promise<string>
+}