@falkordb/text-to-cypher 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.10] - 2026-01-12
+
+### Added
+- Model discovery functionality with two new methods:
+  - `listModels()` - Lists all available AI models across all providers
+  - `listModelsByProvider(provider)` - Lists models from a specific provider (OpenAI, Anthropic, Gemini, Ollama)
+- Comprehensive model list covering:
+  - OpenAI models (GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo, etc.)
+  - Anthropic Claude models (Claude 3.5 Sonnet, Claude 3 Opus, etc.)
+  - Google Gemini models (Gemini 2.0 Flash, Gemini 1.5 Pro, etc.)
+  - Ollama models (Llama 2, Llama 3, Mixtral, Phi-3)
+- New example file `examples/list-models.js` demonstrating model discovery
+- Documentation section in README.md for Model Discovery API
+- Test coverage for model listing functionality
+
 ## [0.1.0] - 2025-12-23
 
 ### Added

package/README.md

@@ -136,6 +136,63 @@ console.log('Nodes:', schemaObj.nodes);
 console.log('Relationships:', schemaObj.relationships);
 ```
 
+## Model Discovery
+
+### `listModels()`
+
+Lists all available AI models across all supported providers.
+
+**Returns:** `Promise<string[]>`
+
+**Example:**
+```javascript
+const models = await client.listModels();
+console.log('Available models:', models);
+// Output: ['gpt-4o-mini', 'gpt-4o', 'anthropic:claude-3-5-sonnet-20241022', ...]
+```
+
+### `listModelsByProvider(provider)`
+
+Lists available AI models from a specific provider.
+
+**Parameters:**
+- `provider` (string): Provider name - `'openai'`, `'anthropic'`, `'gemini'`, or `'ollama'`
+
+**Returns:** `Promise<string[]>`
+
+**Example:**
+```javascript
+// List OpenAI models
+const openaiModels = await client.listModelsByProvider('openai');
+console.log('OpenAI models:', openaiModels);
+// Output: ['gpt-4o-mini', 'gpt-4o', 'gpt-4-turbo', 'gpt-4', 'gpt-3.5-turbo']
+
+// List Anthropic models
+const anthropicModels = await client.listModelsByProvider('anthropic');
+console.log('Anthropic models:', anthropicModels);
+
+// List Gemini models
+const geminiModels = await client.listModelsByProvider('gemini');
+console.log('Gemini models:', geminiModels);
+
+// List Ollama models
+const ollamaModels = await client.listModelsByProvider('ollama');
+console.log('Ollama models:', ollamaModels);
+```
+
+### Supported Providers
+
+- **`openai`** - OpenAI models (GPT-4, GPT-3.5, etc.)
+  - Models can be used directly: `'gpt-4o-mini'`
+- **`anthropic`** - Anthropic models (Claude variants)
+  - Models require prefix: `'anthropic:claude-3-5-sonnet-20241022'`
+- **`gemini`** - Google Gemini models
+  - Models require prefix: `'gemini:gemini-2.0-flash-exp'`
+- **`ollama`** - Local Ollama models (if configured)
+  - Models require prefix: `'ollama:llama3'`
+
+See the [examples/list-models.js](examples/list-models.js) file for a complete working example.
+
 ## Types
 
 ### TextToCypherResponse

package/examples/list-models.js

@@ -0,0 +1,99 @@
+/**
+ * Model Discovery Example for @falkordb/text-to-cypher
+ * 
+ * This example demonstrates how to:
+ * 1. List all available AI models across all providers
+ * 2. List models from specific providers (OpenAI, Anthropic, Gemini, Ollama)
+ * 3. Handle provider-specific model naming conventions
+ */
+
+const { TextToCypher } = require('../index');
+
+async function main() {
+  // Create a client with your configuration
+  // Note: Replace placeholder values with your actual credentials
+  const client = new TextToCypher({
+    model: 'gpt-4o-mini',
+    // API key for your AI provider (e.g., OpenAI API key starting with 'sk-...')
+    apiKey: process.env.OPENAI_API_KEY || 'REPLACE_WITH_YOUR_API_KEY',
+    // FalkorDB connection string in the format: falkor://host:port
+    // For local development, typically: falkor://localhost:6379
+    falkordbConnection: process.env.FALKORDB_CONNECTION || 'falkor://localhost:6379'
+  });
+
+  console.log('=== Model Discovery Example ===\n');
+
+  try {
+    // Example 1: List all available models
+    console.log('1. Listing all available models across all providers...');
+    const allModels = await client.listModels();
+    console.log('\nAll available models:');
+    allModels.forEach((model, index) => {
+      console.log(`  ${index + 1}. ${model}`);
+    });
+    console.log(`\nTotal: ${allModels.length} models\n`);
+
+    console.log('---\n');
+
+    // Example 2: List models by provider
+    console.log('2. Listing models by provider...\n');
+    
+    const providers = ['openai', 'anthropic', 'gemini', 'ollama'];
+    
+    for (const provider of providers) {
+      try {
+        const models = await client.listModelsByProvider(provider);
+        console.log(`${provider.toUpperCase()} models (${models.length}):`);
+        models.forEach(model => {
+          console.log(`  - ${model}`);
+        });
+        console.log();
+      } catch (error) {
+        console.log(`${provider.toUpperCase()}: ${error.message}\n`);
+      }
+    }
+
+    console.log('---\n');
+
+    // Example 3: Try an invalid provider
+    console.log('3. Testing error handling with invalid provider...');
+    try {
+      await client.listModelsByProvider('invalid-provider');
+    } catch (error) {
+      console.log(`Error (expected): ${error.message}\n`);
+    }
+
+    console.log('---\n');
+
+    // Example 4: Demonstrate usage pattern
+    console.log('4. Usage pattern - selecting a model from the list...');
+    const openaiModels = await client.listModelsByProvider('openai');
+    console.log('\nYou can use these models when creating a client:');
+    console.log('\nExample:');
+    console.log('```javascript');
+    console.log('const client = new TextToCypher({');
+    console.log(`  model: '${openaiModels[0]}',  // or any other model from the list`);
+    console.log('  apiKey: process.env.OPENAI_API_KEY,');
+    console.log('  falkordbConnection: \'falkor://localhost:6379\'');
+    console.log('});');
+    console.log('```\n');
+
+    console.log('---\n');
+
+    // Example 5: Provider-specific naming conventions
+    console.log('5. Note on provider-specific naming conventions:');
+    console.log('\nOpenAI models can be used directly:');
+    console.log('  model: \'gpt-4o-mini\'');
+    console.log('\nOther providers require a prefix:');
+    console.log('  model: \'anthropic:claude-3-5-sonnet-20241022\'');
+    console.log('  model: \'gemini:gemini-2.0-flash-exp\'');
+    console.log('  model: \'ollama:llama3\'\n');
+
+  } catch (error) {
+    console.error('Error:', error.message);
+    console.error(error.stack);
+  }
+}
+
+// Run the example
+main().catch(console.error);

package/index.d.ts

@@ -171,4 +171,52 @@ export declare class TextToCypher {
    * ```
    */
   discoverSchema(graphName: string): Promise<string>
+  /**
+   * Lists all available AI models across all supported providers
+   *
+   * Returns a list of commonly available models from OpenAI, Anthropic, Gemini, and Ollama.
+   *
+   * # Note
+   *
+   * This method returns a curated list of well-known models. The actual availability
+   * of models depends on your API credentials and the current offerings from each provider.
+   *
+   * # Returns
+   *
+   * A promise that resolves to an array of model names
+   *
+   * # Example
+   *
+   * ```javascript
+   * const models = await client.listModels();
+   * console.log('Available models:', models);
+   * // Output: ['gpt-4o-mini', 'gpt-4o', 'claude-3-5-sonnet-20241022', ...]
+   * ```
+   */
+  listModels(): Promise<Array<string>>
+  /**
+   * Lists available AI models from a specific provider
+   *
+   * # Arguments
+   *
+   * * `provider` - Provider name: "openai", "anthropic", "gemini", or "ollama" (case-insensitive)
+   *
+   * # Note
+   *
+   * This method returns a curated list of well-known models. The actual availability
+   * of models depends on your API credentials and the current offerings from each provider.
+   *
+   * # Returns
+   *
+   * A promise that resolves to an array of model names for the specified provider
+   *
+   * # Example
+   *
+   * ```javascript
+   * const openaiModels = await client.listModelsByProvider('openai');
+   * console.log('OpenAI models:', openaiModels);
+   * // Output: ['gpt-4o-mini', 'gpt-4o', 'gpt-4-turbo', ...]
+   * ```
+   */
+  listModelsByProvider(provider: string): Promise<Array<string>>
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkordb/text-to-cypher",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Node.js bindings for FalkorDB text-to-cypher library - Convert natural language to Cypher queries",
   "main": "index.js",
   "types": "index.d.ts",
@@ -58,7 +58,7 @@
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.0",
-    "@types/node": "^20.11.0",
+    "@types/node": "^25.0.3",
     "@vitest/coverage-v8": "^1.2.0",
     "prettier": "^3.2.0",
     "typescript": "^5.3.3",