Updates

2026-05-20 21:02:45 -04:00
parent 1f3f4b24a2
commit 14d0980b4f
734 changed files with 682 additions and 746 deletions
@@ -0,0 +1,112 @@
+# API: hyper-p2p-semantic-vector-index
+
+**Protocol:** `hyper-p2p-semantic-vector-index/v1`
+
+**Export:** `HyperP2PSemanticVectorIndex`
+
+## Overview
+
+HyperP2PSemanticVectorIndex Novel, production-grade semantic vector indexing and similarity search primitive for Bare/Pear P2P applications. Features:
+
+## Constructor
+
+```js
+const mod = new HyperP2PSemanticVectorIndex(opts)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
+| `keyPair` | KeyPair | random | Ed25519 key pair |
+
+## Methods
+
+### `insert(vector, metadata = {})`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `search(queryVector, k = 10, options = {})`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `findByTags(tags, options = {})`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `pruneExpired(—)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `createP2PTopic(namespace = 'default')`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `receiveGossip(payload)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `open(—)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `getStats(—)`
+
+- **Returns:** `object`
+- **Throws:** — (none documented in method body)
+
+### `close(—)`
+
+- **Returns:** `Promise<void>`
+- **Throws:** — (none documented in method body)
+
+### `getMetrics(—)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `getVector(id, verify = false)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `close` | no payload |
+| `error` | e |
+| `gossip` | type |
+| `gossip-received` | source |
+| `insert` | metadata, timestamp, similarity |
+| `open` | total |
+| `prune` | count, remaining |
+| `search` | queryDim, results, filtered |
+| `update` | type, count |
+
+## getStats()
+
+Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
+Library-only modules may include `mode: 'local'`.
+
+## Errors
+
+Stable message substrings: see [`../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
+
+## P2P
+
+When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `hyper-p2p-semantic-vector-index/v1`.
+
+## Testing
+
+```bash
+npm install && npm test
+```
+
+Integration: [`../../real_tests/integration/semantic-vector-index-two-node.js`](../../../real_tests/integration/semantic-vector-index-two-node.js)