neuralex 0.1.0 → 0.2.0

package/README.md

@@ -2,6 +2,21 @@
 
 Official TypeScript/JavaScript client library for the [NeuraLex](https://neuralex.ca) API.
 
+## What is NeuraLex?
+
+NeuraLex is a next-generation embedding API that combines **semantic understanding** with **term-based precision** to deliver superior search and retrieval performance. Unlike traditional embedding models that rely solely on neural networks, NeuraLex uses a hybrid approach that preserves exact keyword matching while capturing semantic meaning.
+
+This hybrid architecture delivers:
+- ✅ **Better recall** - Captures both exact terms and semantic meaning
+- ✅ **Reduced false positives (disambiguation)** - Term-based component filters irrelevant semantic matches
+- ✅ **Configurable precision** - Adjust the balance for your use case
+
+### Learn More
+
+- 📄 [NeuraSearch Whitepaper](https://neuralex.ca/neurasearch-whitepaper) - Technical deep dive into the hybrid approach
+- 📊 [Performance Analysis](https://neuralex.ca/neurasearch-analysis) - Benchmark results and comparisons
+- 📖 [API Documentation](https://neuralex.ca/docs/api) - Complete API reference
+
 ## Installation
 
 ```bash
@@ -39,6 +54,7 @@ console.log(`First 5 values: ${embedding.slice(0, 5)}`);
 - ✅ Configurable semantic/term-based balance
 - ✅ Batch embedding support (up to 100 inputs)
 - ✅ Tree-shakeable ESM and CommonJS builds
+- ✅ BYOE (Bring Your Own Embedding) mode support
 
 ## Usage
 
@@ -92,6 +108,30 @@ const response = await client.embed('Python programming', {
 });
 ```
 
+### BYOE (Bring Your Own Embedding) Mode
+
+When the embed service is configured with `BYOE=true`, you can provide your own
+pre-computed embeddings instead of generating them server-side:
+
+```typescript
+import { NeuraLexClient, EmbeddingInputData } from 'neuralex';
+
+const client = new NeuraLexClient({ apiKey: 'nlx_your_api_key' });
+
+// Create inputs with optional pre-computed embeddings
+const inputs: EmbeddingInputData[] = [
+  // Provide your own embedding (must match server dimensions, typically 1024)
+  { text: 'hello world', embedding: new Array(1024).fill(0.1) },
+  // Or let the server compute the embedding
+  { text: 'server-computed text' },
+];
+
+const response = await client.embed(inputs);
+```
+
+**Note:** BYOE mode must be enabled on the server (`BYOE=true`). If BYOE is disabled,
+providing embeddings will result in an error.
+
 ### Error Handling
 
 ```typescript
@@ -160,7 +200,7 @@ Generate embeddings for text input(s).
 
 **Parameters:**
 
-- `inputs` (string | string[]): Text or array of texts to embed (max 100)
+- `inputs` (string | EmbeddingInputData | string[] | EmbeddingInputData[]): Text or array of texts/EmbeddingInputData to embed (max 100)
 - `options` (object, optional):
   - `model` (string): Model name (default: "public")
   - `language` (string): Language for lexeme extraction (default: "english")
@@ -170,6 +210,17 @@ Generate embeddings for text input(s).
 
 ### Types
 
+#### `EmbeddingInputData`
+
+```typescript
+interface EmbeddingInputData {
+  /** Text to embed (required) */
+  text: string;
+  /** Pre-computed embedding vector (optional, for BYOE mode) */
+  embedding?: number[];
+}
+```
+
 #### `EmbeddingResponse`
 
 ```typescript

package/dist/index.d.mts

@@ -1,5 +1,9 @@
+interface EmbeddingInputData {
+    text: string;
+    embedding?: number[];
+}
 interface EmbeddingRequest {
-    inputs: string[];
+    inputs: EmbeddingInputData[];
     model?: string;
     language?: string;
     semanticWeight?: number;
@@ -23,11 +27,12 @@ interface NeuraLexClientConfig {
     timeout?: number;
 }
 
+type EmbedInput = string | EmbeddingInputData | string[] | EmbeddingInputData[];
 declare class NeuraLexClient {
     private client;
     private apiKey;
     constructor(config: NeuraLexClientConfig);
-    embed(inputs: string | string[], options?: {
+    embed(inputs: EmbedInput, options?: {
         model?: string;
         language?: string;
         semanticWeight?: number;
@@ -49,4 +54,4 @@ declare class APIError extends NeuraLexError {
     constructor(message: string, statusCode: number, responseData?: any);
 }
 
-export { APIError, AuthenticationError, type EmbeddingData, type EmbeddingRequest, type EmbeddingResponse, NeuraLexClient, type NeuraLexClientConfig, NeuraLexError, RateLimitError, type Usage };
+export { APIError, AuthenticationError, type EmbeddingData, type EmbeddingInputData, type EmbeddingRequest, type EmbeddingResponse, NeuraLexClient, type NeuraLexClientConfig, NeuraLexError, RateLimitError, type Usage };

package/dist/index.d.ts

@@ -1,5 +1,9 @@
+interface EmbeddingInputData {
+    text: string;
+    embedding?: number[];
+}
 interface EmbeddingRequest {
-    inputs: string[];
+    inputs: EmbeddingInputData[];
     model?: string;
     language?: string;
     semanticWeight?: number;
@@ -23,11 +27,12 @@ interface NeuraLexClientConfig {
     timeout?: number;
 }
 
+type EmbedInput = string | EmbeddingInputData | string[] | EmbeddingInputData[];
 declare class NeuraLexClient {
     private client;
     private apiKey;
     constructor(config: NeuraLexClientConfig);
-    embed(inputs: string | string[], options?: {
+    embed(inputs: EmbedInput, options?: {
         model?: string;
         language?: string;
         semanticWeight?: number;
@@ -49,4 +54,4 @@ declare class APIError extends NeuraLexError {
     constructor(message: string, statusCode: number, responseData?: any);
 }
 
-export { APIError, AuthenticationError, type EmbeddingData, type EmbeddingRequest, type EmbeddingResponse, NeuraLexClient, type NeuraLexClientConfig, NeuraLexError, RateLimitError, type Usage };
+export { APIError, AuthenticationError, type EmbeddingData, type EmbeddingInputData, type EmbeddingRequest, type EmbeddingResponse, NeuraLexClient, type NeuraLexClientConfig, NeuraLexError, RateLimitError, type Usage };

package/dist/index.js

@@ -74,6 +74,20 @@ var APIError = class _APIError extends NeuraLexError {
 };
 
 // src/client.ts
+function normalizeInputs(inputs) {
+  if (typeof inputs === "string") {
+    return [{ text: inputs }];
+  }
+  if (!Array.isArray(inputs)) {
+    return [inputs];
+  }
+  return inputs.map((item) => {
+    if (typeof item === "string") {
+      return { text: item };
+    }
+    return item;
+  });
+}
 var NeuraLexClient = class {
   /**
    * Create a new NeuraLex client
@@ -104,7 +118,9 @@ var NeuraLexClient = class {
   /**
    * Generate embeddings for the provided input text(s)
    *
-   * @param inputs - Text string or array of text strings to embed (max 100)
+   * @param inputs - Text string, EmbeddingInputData, or array of either (max 100).
+   *                 For BYOE (Bring Your Own Embedding) mode, use EmbeddingInputData
+   *                 with the embedding field populated.
    * @param options - Optional parameters
    * @param options.model - Model name (default: "public")
    * @param options.language - Language for lexeme extraction (default: "english")
@@ -129,18 +145,24 @@ var NeuraLexClient = class {
    *   semanticWeight: 0.8,
    *   model: 'public'
    * });
+   *
+   * // BYOE mode with pre-computed embeddings
+   * const response = await client.embed([
+   *   { text: 'hello world', embedding: new Array(1024).fill(0.1) },
+   *   { text: 'server-computed text' }
+   * ]);
    * ```
    */
   async embed(inputs, options = {}) {
-    const inputArray = Array.isArray(inputs) ? inputs : [inputs];
-    if (inputArray.length === 0) {
+    const normalizedInputs = normalizeInputs(inputs);
+    if (normalizedInputs.length === 0) {
       throw new Error("At least one input is required");
     }
-    if (inputArray.length > 100) {
+    if (normalizedInputs.length > 100) {
       throw new Error("Maximum 100 inputs allowed per request");
     }
     const request = {
-      inputs: inputArray,
+      inputs: normalizedInputs,
       model: options.model ?? "public",
       language: options.language ?? "english",
       semanticWeight: options.semanticWeight ?? 0.5

package/dist/index.mjs

@@ -34,6 +34,20 @@ var APIError = class _APIError extends NeuraLexError {
 };
 
 // src/client.ts
+function normalizeInputs(inputs) {
+  if (typeof inputs === "string") {
+    return [{ text: inputs }];
+  }
+  if (!Array.isArray(inputs)) {
+    return [inputs];
+  }
+  return inputs.map((item) => {
+    if (typeof item === "string") {
+      return { text: item };
+    }
+    return item;
+  });
+}
 var NeuraLexClient = class {
   /**
    * Create a new NeuraLex client
@@ -64,7 +78,9 @@ var NeuraLexClient = class {
   /**
    * Generate embeddings for the provided input text(s)
    *
-   * @param inputs - Text string or array of text strings to embed (max 100)
+   * @param inputs - Text string, EmbeddingInputData, or array of either (max 100).
+   *                 For BYOE (Bring Your Own Embedding) mode, use EmbeddingInputData
+   *                 with the embedding field populated.
    * @param options - Optional parameters
    * @param options.model - Model name (default: "public")
    * @param options.language - Language for lexeme extraction (default: "english")
@@ -89,18 +105,24 @@ var NeuraLexClient = class {
    *   semanticWeight: 0.8,
    *   model: 'public'
    * });
+   *
+   * // BYOE mode with pre-computed embeddings
+   * const response = await client.embed([
+   *   { text: 'hello world', embedding: new Array(1024).fill(0.1) },
+   *   { text: 'server-computed text' }
+   * ]);
    * ```
    */
   async embed(inputs, options = {}) {
-    const inputArray = Array.isArray(inputs) ? inputs : [inputs];
-    if (inputArray.length === 0) {
+    const normalizedInputs = normalizeInputs(inputs);
+    if (normalizedInputs.length === 0) {
       throw new Error("At least one input is required");
     }
-    if (inputArray.length > 100) {
+    if (normalizedInputs.length > 100) {
       throw new Error("Maximum 100 inputs allowed per request");
     }
     const request = {
-      inputs: inputArray,
+      inputs: normalizedInputs,
       model: options.model ?? "public",
       language: options.language ?? "english",
       semanticWeight: options.semanticWeight ?? 0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neuralex",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official TS/JS client library for NeuraLex API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",