native-vector-store 0.3.4 → 0.3.6

package/README.md

@@ -33,6 +33,8 @@ This design eliminates complex state management, ensures consistent performance,
 - **Scalability**: Designed for focused corpora (<100k documents optimal, <1M maximum)
 - **Throughput**: 178k+ documents per second with parallel loading
 
+📊 **[Production Case Study](docs/PRODUCTION_CASE_STUDY.md)**: Real-world deployment with 65k documents (1.5GB) on AWS Lambda achieving 15-20s cold start and 40-45ms search latency.
+
 ## Installation
 
 ```bash
@@ -49,7 +51,7 @@ npm install native-vector-store
   - **Windows**: Included with Visual C++ runtime
 
 Prebuilt binaries are included for:
-- Linux (x64, arm64, musl/Alpine)
+- Linux (x64, arm64, musl/Alpine) - x64 builds are AWS Lambda compatible (no AVX-512)
 - macOS (x64, arm64/Apple Silicon)
 - Windows (x64)
 
@@ -86,7 +88,23 @@ store.finalize(); // Must call before searching!
 const queryEmbedding = new Float32Array(1536);
 const results = store.search(queryEmbedding, 5); // Top 5 results
 
-console.log(results[0]); // { score: 0.95, id: 'doc-1', text: '...', metadata_json: '...' }
+// Results format - array of SearchResult objects, sorted by score (highest first):
+console.log(results);
+// [
+//   {
+//     score: 0.987654,            // Similarity score (0-1, higher = more similar)
+//     id: "doc-1",                // Your document ID
+//     text: "Example document...", // Full document text
+//     metadata_json: "{\"embedding\":[0.1,0.2,...],\"category\":\"example\"}"  // JSON string
+//   },
+//   { score: 0.943210, id: "doc-7", text: "Another doc...", metadata_json: "..." },
+//   // ... up to 5 results
+// ]
+
+// Parse metadata from the top result
+const topResult = results[0];
+const metadata = JSON.parse(topResult.metadata_json);
+console.log(metadata.category); // "example"
 ```
 
 ## Usage Patterns
@@ -314,15 +332,32 @@ interface Document {
 ```
 
 ##### `search(query: Float32Array, k: number, normalizeQuery?: boolean): SearchResult[]`
-Search for k most similar documents.
+Search for k most similar documents. Returns an array sorted by score (highest first).
 
 ```typescript
 interface SearchResult {
-  score: number;
-  id: string;
-  text: string;
-  metadata_json: string;
+  score: number;        // Cosine similarity (0-1, higher = more similar)
+  id: string;           // Document ID
+  text: string;         // Document text content
+  metadata_json: string; // JSON string with all metadata including embedding
 }
+
+// Example return value:
+[
+  {
+    score: 0.98765,
+    id: "doc-123", 
+    text: "Introduction to machine learning...",
+    metadata_json: "{\"embedding\":[0.1,0.2,...],\"author\":\"Jane Doe\",\"tags\":[\"ML\",\"intro\"]}"
+  },
+  {
+    score: 0.94321,
+    id: "doc-456",
+    text: "Deep learning fundamentals...", 
+    metadata_json: "{\"embedding\":[0.3,0.4,...],\"difficulty\":\"intermediate\"}"
+  }
+  // ... more results
+]
 ```
 
 ##### `finalize(): void`
@@ -356,7 +391,9 @@ Performance on typical hardware (M1 MacBook Pro):
 | Operation | Documents | Time | Throughput |
 |-----------|-----------|------|------------|
 | Loading (from disk) | 100,000 | ~560ms | 178k docs/sec |
+| Loading (production) | 65,000 | 15-20s | 3.2-4.3k docs/sec |
 | Search (k=10) | 10,000 corpus | 1-2ms | 500-1000 queries/sec |
+| Search (k=10) | 65,000 corpus | 40-45ms | 20-25 queries/sec |
 | Search (k=100) | 100,000 corpus | 8-12ms | 80-125 queries/sec |
 | Normalization | 100,000 | <100ms | 1M+ docs/sec |
 

package/binding.gyp

@@ -13,7 +13,6 @@
       "cflags_cc": [
         "-std=c++17",
         "-O3",
-        "-march=native",
         "-fno-exceptions"
       ],
       "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"],
@@ -37,7 +36,16 @@
           ]
         }],
         ["OS=='linux'", {
-          "cflags_cc": ["-fopenmp"],
+          "cflags_cc": [
+            "-fopenmp",
+            # AWS Lambda compatibility: target x86-64-v3 (up to AVX2) but no AVX-512
+            "-march=x86-64-v3",
+            "-mno-avx512f",
+            "-mno-avx512cd",
+            "-mno-avx512bw", 
+            "-mno-avx512dq",
+            "-mno-avx512vl"
+          ],
           "libraries": ["-lgomp"]
         }],
         ["OS=='win'", {

package/docs/index.html

@@ -73,6 +73,7 @@
 <li><strong>Scalability</strong>: Designed for focused corpora (&lt;100k documents optimal, &lt;1M maximum)</li>
 <li><strong>Throughput</strong>: 178k+ documents per second with parallel loading</li>
 </ul>
+<p>📊 <strong><a href="docs/PRODUCTION_CASE_STUDY.md">Production Case Study</a></strong>: Real-world deployment with 65k documents (1.5GB) on AWS Lambda achieving 15-20s cold start and 40-45ms search latency.</p>
 <h2 id="installation">Installation</h2>
 <pre class="prettyprint source lang-bash"><code>npm install native-vector-store
 </code></pre>
@@ -90,7 +91,7 @@
 </ul>
 <p>Prebuilt binaries are included for:</p>
 <ul>
-<li>Linux (x64, arm64, musl/Alpine)</li>
+<li>Linux (x64, arm64, musl/Alpine) - x64 builds are AWS Lambda compatible (no AVX-512)</li>
 <li>macOS (x64, arm64/Apple Silicon)</li>
 <li>Windows (x64)</li>
 </ul>
@@ -126,7 +127,23 @@ store.finalize(); // Must call before searching!
 const queryEmbedding = new Float32Array(1536);
 const results = store.search(queryEmbedding, 5); // Top 5 results
 
-console.log(results[0]); // { score: 0.95, id: 'doc-1', text: '...', metadata_json: '...' }
+// Results format - array of SearchResult objects, sorted by score (highest first):
+console.log(results);
+// [
+//   {
+//     score: 0.987654,            // Similarity score (0-1, higher = more similar)
+//     id: &quot;doc-1&quot;,                // Your document ID
+//     text: &quot;Example document...&quot;, // Full document text
+//     metadata_json: &quot;{\&quot;embedding\&quot;:[0.1,0.2,...],\&quot;category\&quot;:\&quot;example\&quot;}&quot;  // JSON string
+//   },
+//   { score: 0.943210, id: &quot;doc-7&quot;, text: &quot;Another doc...&quot;, metadata_json: &quot;...&quot; },
+//   // ... up to 5 results
+// ]
+
+// Parse metadata from the top result
+const topResult = results[0];
+const metadata = JSON.parse(topResult.metadata_json);
+console.log(metadata.category); // &quot;example&quot;
 </code></pre>
 <h2 id="usage-patterns">Usage Patterns</h2>
 <h3 id="serverless-deployment-(aws-lambda%2C-vercel)">Serverless Deployment (AWS Lambda, Vercel)</h3>
@@ -309,13 +326,30 @@ const response = await server.handleMCPRequest('vector_search', {
 }
 </code></pre>
 <h5 id="search(query%3A-float32array%2C-k%3A-number%2C-normalizequery%3F%3A-boolean)%3A-searchresult%5B%5D"><code>search(query: Float32Array, k: number, normalizeQuery?: boolean): SearchResult[]</code></h5>
-<p>Search for k most similar documents.</p>
+<p>Search for k most similar documents. Returns an array sorted by score (highest first).</p>
 <pre class="prettyprint source lang-typescript"><code>interface SearchResult {
-  score: number;
-  id: string;
-  text: string;
-  metadata_json: string;
+  score: number;        // Cosine similarity (0-1, higher = more similar)
+  id: string;           // Document ID
+  text: string;         // Document text content
+  metadata_json: string; // JSON string with all metadata including embedding
 }
+
+// Example return value:
+[
+  {
+    score: 0.98765,
+    id: &quot;doc-123&quot;, 
+    text: &quot;Introduction to machine learning...&quot;,
+    metadata_json: &quot;{\&quot;embedding\&quot;:[0.1,0.2,...],\&quot;author\&quot;:\&quot;Jane Doe\&quot;,\&quot;tags\&quot;:[\&quot;ML\&quot;,\&quot;intro\&quot;]}&quot;
+  },
+  {
+    score: 0.94321,
+    id: &quot;doc-456&quot;,
+    text: &quot;Deep learning fundamentals...&quot;, 
+    metadata_json: &quot;{\&quot;embedding\&quot;:[0.3,0.4,...],\&quot;difficulty\&quot;:\&quot;intermediate\&quot;}&quot;
+  }
+  // ... more results
+]
 </code></pre>
 <h5 id="finalize()%3A-void"><code>finalize(): void</code></h5>
 <p>Finalize the store: normalize all embeddings and switch to serving mode. After this, no more documents can be added but searches become available. This is automatically called by <code>loadDir()</code>.</p>
@@ -354,12 +388,24 @@ const response = await server.handleMCPRequest('vector_search', {
 <td>178k docs/sec</td>
 </tr>
 <tr>
+<td>Loading (production)</td>
+<td>65,000</td>
+<td>15-20s</td>
+<td>3.2-4.3k docs/sec</td>
+</tr>
+<tr>
 <td>Search (k=10)</td>
 <td>10,000 corpus</td>
 <td>1-2ms</td>
 <td>500-1000 queries/sec</td>
 </tr>
 <tr>
+<td>Search (k=10)</td>
+<td>65,000 corpus</td>
+<td>40-45ms</td>
+<td>20-25 queries/sec</td>
+</tr>
+<tr>
 <td>Search (k=100)</td>
 <td>100,000 corpus</td>
 <td>8-12ms</td>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-vector-store",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "High-performance local vector store with SIMD optimization for MCP servers",
   "main": "index.js",
   "types": "lib/index.d.ts",