npm - native-vector-store - Versions diffs - 0.1.0 → 0.3.0 - Mend

native-vector-store 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (53) hide show

package/README.md +242 -12
package/binding.gyp +22 -10
package/deps/simdjson/simdjson.cpp +56403 -0
package/deps/simdjson/simdjson.h +123534 -0
package/docs/PERFORMANCE_CASE_STUDY.md +130 -0
package/docs/PREBUILDS.md +69 -0
package/docs/VectorStore.html +180 -0
package/docs/VectorStoreWrapper.html +1356 -0
package/docs/fonts/OpenSans-Bold-webfont.eot +0 -0
package/docs/fonts/OpenSans-Bold-webfont.svg +1830 -0
package/docs/fonts/OpenSans-Bold-webfont.woff +0 -0
package/docs/fonts/OpenSans-BoldItalic-webfont.eot +0 -0
package/docs/fonts/OpenSans-BoldItalic-webfont.svg +1830 -0
package/docs/fonts/OpenSans-BoldItalic-webfont.woff +0 -0
package/docs/fonts/OpenSans-Italic-webfont.eot +0 -0
package/docs/fonts/OpenSans-Italic-webfont.svg +1830 -0
package/docs/fonts/OpenSans-Italic-webfont.woff +0 -0
package/docs/fonts/OpenSans-Light-webfont.eot +0 -0
package/docs/fonts/OpenSans-Light-webfont.svg +1831 -0
package/docs/fonts/OpenSans-Light-webfont.woff +0 -0
package/docs/fonts/OpenSans-LightItalic-webfont.eot +0 -0
package/docs/fonts/OpenSans-LightItalic-webfont.svg +1835 -0
package/docs/fonts/OpenSans-LightItalic-webfont.woff +0 -0
package/docs/fonts/OpenSans-Regular-webfont.eot +0 -0
package/docs/fonts/OpenSans-Regular-webfont.svg +1831 -0
package/docs/fonts/OpenSans-Regular-webfont.woff +0 -0
package/docs/global.html +561 -0
package/docs/index.html +570 -0
package/docs/scripts/linenumber.js +25 -0
package/docs/scripts/prettify/Apache-License-2.0.txt +202 -0
package/docs/scripts/prettify/lang-css.js +2 -0
package/docs/scripts/prettify/prettify.js +28 -0
package/docs/styles/jsdoc-default.css +358 -0
package/docs/styles/prettify-jsdoc.css +111 -0
package/docs/styles/prettify-tomorrow.css +132 -0
package/index.js +162 -0
package/package.json +30 -7
package/prebuilds/darwin-arm64/native-vector-store.node +0 -0
package/prebuilds/darwin-x64/native-vector-store.node +0 -0
package/prebuilds/linux-arm64/native-vector-store.node +0 -0
package/prebuilds/linux-x64/native-vector-store.node +0 -0
package/prebuilds/linux-x64-musl/napi-v9/native-vector-store.node +0 -0
package/prebuilds/linux-x64-musl/native-vector-store.node +0 -0
package/prebuilds/win32-x64/native-vector-store.node +0 -0
package/src/Makefile +87 -0
package/src/test_main.cpp +173 -0
package/src/test_stress.cpp +394 -0
package/src/vector_store.cpp +344 -0
package/src/vector_store.h +21 -323
package/native-vector-store-0.1.0.tgz +0 -0
package/scripts/build-prebuilds.sh +0 -23
/package/{src → deps/atomic_queue}/atomic_queue.h +0 -0
/package/{src → deps/atomic_queue}/defs.h +0 -0

package/docs/VectorStoreWrapper.html ADDED Viewed

@@ -0,0 +1,1356 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>JSDoc: Class: VectorStoreWrapper</title>
+    <script src="scripts/prettify/prettify.js"> </script>
+    <script src="scripts/prettify/lang-css.js"> </script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
+</head>
+<body>
+<div id="main">
+    <h1 class="page-title">Class: VectorStoreWrapper</h1>
+<section>
+<header>
+        <h2><span class="attribs"><span class="type-signature"></span></span>VectorStoreWrapper<span class="signature">(dimensions)</span><span class="type-signature"></span></h2>
+</header>
+<article>
+    <div class="container-overview">
+    <h4 class="name" id="VectorStoreWrapper"><span class="type-signature"></span>new VectorStoreWrapper<span class="signature">(dimensions)</span><span class="type-signature"></span></h4>
+<div class="description">
+    <p>Creates a new VectorStore instance</p>
+</div>
+    <h5>Parameters:</h5>
+<table class="params">
+    <thead>
+    <tr>
+        <th>Name</th>
+        <th>Type</th>
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+    <tbody>
+        <tr>
+                <td class="name"><code>dimensions</code></td>
+            <td class="type">
+<span class="param-type">number</span>
+            </td>
+            <td class="description last"><p>The dimensionality of embedding vectors (e.g., 1536 for OpenAI embeddings)</p></td>
+        </tr>
+    </tbody>
+</table>
+<dl class="details">
+</dl>
+<h5>Throws:</h5>
+<dl>
+    <dt>
+        <div class="param-desc">
+        <p>If dimensions is not a positive integer</p>
+        </div>
+    </dt>
+    <dd></dd>
+    <dt>
+        <dl>
+            <dt>
+                Type
+            </dt>
+            <dd>
+<span class="param-type">TypeError</span>
+            </dd>
+        </dl>
+    </dt>
+    <dd></dd>
+</dl>
+    </div>
+        <h3 class="subsection-title">Methods</h3>
+    <h4 class="name" id="addDocument"><span class="type-signature"></span>addDocument<span class="signature">(doc)</span><span class="type-signature"> &rarr; {void}</span></h4>
+<div class="description">
+    <p>Add a single document to the store. Only works before finalization.</p>
+</div>
+    <h5>Parameters:</h5>
+<table class="params">
+    <thead>
+    <tr>
+        <th>Name</th>
+        <th>Type</th>
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+    <tbody>
+        <tr>
+                <td class="name"><code>doc</code></td>
+            <td class="type">
+<span class="param-type"><a href="global.html#Document">Document</a></span>
+            </td>
+            <td class="description last"><p>Document object with embedding in metadata</p></td>
+        </tr>
+    </tbody>
+</table>
+<dl class="details">
+</dl>
+<h5>Throws:</h5>
+<dl>
+    <dt>
+        <div class="param-desc">
+        <p>If called after finalization or document format is invalid</p>
+        </div>
+    </dt>
+    <dd></dd>
+    <dt>
+        <dl>
+            <dt>
+                Type
+            </dt>
+            <dd>
+<span class="param-type">Error</span>
+            </dd>
+        </dl>
+    </dt>
+    <dd></dd>
+</dl>
+<h5>Returns:</h5>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+<span class="param-type">void</span>
+    </dd>
+</dl>
+    <h5>Example</h5>
+    <pre class="prettyprint"><code>store.addDocument({
+  id: 'doc-1',
+  text: 'Sample document',
+  metadata: {
+    embedding: new Array(1536).fill(0).map(() => Math.random())
+  }
+});</code></pre>
+    <h4 class="name" id="finalize"><span class="type-signature"></span>finalize<span class="signature">()</span><span class="type-signature"> &rarr; {void}</span></h4>
+<div class="description">
+    <p>Finalize the store: normalize all embeddings and switch to serving mode.
+After calling this, no more documents can be added but searches become available.
+This is automatically called by loadDir().</p>
+</div>
+<dl class="details">
+</dl>
+<h5>Returns:</h5>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+<span class="param-type">void</span>
+    </dd>
+</dl>
+    <h5>Example</h5>
+    <pre class="prettyprint"><code>// Manual finalization after adding documents
+store.addDocument(doc1);
+store.addDocument(doc2);
+store.finalize(); // Must call before searching</code></pre>
+    <h4 class="name" id="isFinalized"><span class="type-signature"></span>isFinalized<span class="signature">()</span><span class="type-signature"> &rarr; {boolean}</span></h4>
+<div class="description">
+    <p>Check if the store has been finalized and is ready for searching.</p>
+</div>
+<dl class="details">
+</dl>
+<h5>Returns:</h5>
+<div class="param-desc">
+    <p>True if finalized, false otherwise</p>
+</div>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+<span class="param-type">boolean</span>
+    </dd>
+</dl>
+    <h5>Example</h5>
+    <pre class="prettyprint"><code>if (store.isFinalized()) {
+  const results = store.search(query, 10);
+}</code></pre>
+    <h4 class="name" id="loadDir"><span class="type-signature"></span>loadDir<span class="signature">(path)</span><span class="type-signature"> &rarr; {void}</span></h4>
+<div class="description">
+    <p>Load all JSON documents from a directory and automatically finalize the store.
+Documents should contain embedding vectors in their metadata field.
+Supports both single documents and arrays of documents per file.</p>
+</div>
+    <h5>Parameters:</h5>
+<table class="params">
+    <thead>
+    <tr>
+        <th>Name</th>
+        <th>Type</th>
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+    <tbody>
+        <tr>
+                <td class="name"><code>path</code></td>
+            <td class="type">
+<span class="param-type">string</span>
+            </td>
+            <td class="description last"><p>Absolute or relative path to directory containing JSON files</p></td>
+        </tr>
+    </tbody>
+</table>
+<dl class="details">
+</dl>
+<h5>Throws:</h5>
+<dl>
+    <dt>
+        <div class="param-desc">
+        <p>If directory doesn't exist or contains invalid JSON</p>
+        </div>
+    </dt>
+    <dd></dd>
+    <dt>
+        <dl>
+            <dt>
+                Type
+            </dt>
+            <dd>
+<span class="param-type">Error</span>
+            </dd>
+        </dl>
+    </dt>
+    <dd></dd>
+</dl>
+<h5>Returns:</h5>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+<span class="param-type">void</span>
+    </dd>
+</dl>
+    <h5>Examples</h5>
+    <pre class="prettyprint"><code>// Load documents from a directory
+store.loadDir('./knowledge-base');
+// Store is automatically finalized and ready for searches</code></pre>
+    <pre class="prettyprint"><code>// Document format in JSON files
+{
+  "id": "doc-123",
+  "text": "Document content...",
+  "metadata": {
+    "embedding": [0.1, 0.2, ...],  // Required: embedding vector
+    "category": "product"           // Optional: additional metadata
+  }
+}</code></pre>
+    <h4 class="name" id="normalize"><span class="type-signature"></span>normalize<span class="signature">()</span><span class="type-signature"> &rarr; {void}</span></h4>
+<dl class="details">
+        <dt class="important tag-deprecated">Deprecated:</dt><dd><ul class="dummy"><li>Use finalize() instead</li></ul></dd>
+</dl>
+<h5>Returns:</h5>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+<span class="param-type">void</span>
+    </dd>
+</dl>
+    <h4 class="name" id="search"><span class="type-signature"></span>search<span class="signature">(query, k, normalizeQuery<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Array.&lt;<a href="global.html#SearchResult">SearchResult</a>>}</span></h4>
+<div class="description">
+    <p>Search for the k most similar documents to a query embedding.
+Uses SIMD-optimized cosine similarity for fast performance.</p>
+</div>
+    <h5>Parameters:</h5>
+<table class="params">
+    <thead>
+    <tr>
+        <th>Name</th>
+        <th>Type</th>
+        <th>Attributes</th>
+        <th>Default</th>
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+    <tbody>
+        <tr>
+                <td class="name"><code>query</code></td>
+            <td class="type">
+<span class="param-type">Float32Array</span>
+            </td>
+                <td class="attributes">
+                </td>
+                <td class="default">
+                </td>
+            <td class="description last"><p>Query embedding vector (must match store dimensions)</p></td>
+        </tr>
+        <tr>
+                <td class="name"><code>k</code></td>
+            <td class="type">
+<span class="param-type">number</span>
+            </td>
+                <td class="attributes">
+                </td>
+                <td class="default">
+                </td>
+            <td class="description last"><p>Number of results to return (top-k nearest neighbors)</p></td>
+        </tr>
+        <tr>
+                <td class="name"><code>normalizeQuery</code></td>
+            <td class="type">
+<span class="param-type">boolean</span>
+            </td>
+                <td class="attributes">
+                    &lt;optional><br>
+                </td>
+                <td class="default">
+                    true
+                </td>
+            <td class="description last"><p>Whether to L2-normalize the query vector</p></td>
+        </tr>
+    </tbody>
+</table>
+<dl class="details">
+</dl>
+<h5>Throws:</h5>
+<dl>
+    <dt>
+        <div class="param-desc">
+        <p>If store is not finalized or query dimensions don't match</p>
+        </div>
+    </dt>
+    <dd></dd>
+    <dt>
+        <dl>
+            <dt>
+                Type
+            </dt>
+            <dd>
+<span class="param-type">Error</span>
+            </dd>
+        </dl>
+    </dt>
+    <dd></dd>
+</dl>
+<h5>Returns:</h5>
+<div class="param-desc">
+    <p>Array of search results sorted by similarity (highest first)</p>
+</div>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+<span class="param-type">Array.&lt;<a href="global.html#SearchResult">SearchResult</a>></span>
+    </dd>
+</dl>
+    <h5>Examples</h5>
+    <pre class="prettyprint"><code>// Basic search
+const queryEmbedding = new Float32Array(1536);
+const results = store.search(queryEmbedding, 10);</code></pre>
+    <pre class="prettyprint"><code>// Search with pre-normalized query
+const normalized = normalizeVector(queryEmbedding);
+const results = store.search(normalized, 5, false);</code></pre>
+    <pre class="prettyprint"><code>// Filter results by score threshold
+const results = store.search(queryEmbedding, 20)
+  .filter(r => r.score > 0.7);</code></pre>
+    <h4 class="name" id="size"><span class="type-signature"></span>size<span class="signature">()</span><span class="type-signature"> &rarr; {number}</span></h4>
+<div class="description">
+    <p>Get the number of documents in the store.</p>
+</div>
+<dl class="details">
+</dl>
+<h5>Returns:</h5>
+<div class="param-desc">
+    <p>Number of documents loaded</p>
+</div>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+<span class="param-type">number</span>
+    </dd>
+</dl>
+    <h5>Example</h5>
+    <pre class="prettyprint"><code>console.log(`Loaded ${store.size()} documents`);</code></pre>
+</article>
+</section>
+</div>
+<nav>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="VectorStore.html">VectorStore</a></li><li><a href="VectorStoreWrapper.html">VectorStoreWrapper</a></li></ul><h3><a href="global.html">Global</a></h3>
+</nav>
+<br class="clear">
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.4</a>
+</footer>
+<script> prettyPrint(); </script>
+<script src="scripts/linenumber.js"> </script>
+</body>
+</html>