# 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)