@hajewski/latticedb 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.
- package/README.md +244 -46
- package/dist/embedding.d.ts +48 -0
- package/dist/embedding.d.ts.map +1 -0
- package/dist/embedding.js +74 -0
- package/dist/embedding.js.map +1 -0
- package/dist/ffi/bindings.d.ts +7 -0
- package/dist/ffi/bindings.d.ts.map +1 -1
- package/dist/ffi/bindings.js +59 -24
- package/dist/ffi/bindings.js.map +1 -1
- package/dist/ffi/index.d.ts +24 -2
- package/dist/ffi/index.d.ts.map +1 -1
- package/dist/ffi/index.js +56 -2
- package/dist/ffi/index.js.map +1 -1
- package/dist/ffi/types.d.ts +10 -0
- package/dist/ffi/types.d.ts.map +1 -1
- package/dist/ffi/types.js.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -2
- package/dist/index.js.map +1 -1
- package/include/lattice.h +586 -0
- package/lib/darwin-arm64/liblattice.dylib +0 -0
- package/lib/darwin-x64/liblattice.dylib +0 -0
- package/lib/linux-arm64/liblattice.so +0 -0
- package/lib/linux-x64/liblattice.so +0 -0
- package/package.json +4 -3
- package/dist/native.d.ts +0 -98
- package/dist/native.d.ts.map +0 -1
- package/dist/native.js +0 -52
- package/dist/native.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,43 +1,87 @@
|
|
|
1
1
|
# LatticeDB TypeScript Bindings
|
|
2
2
|
|
|
3
|
-
TypeScript/Node.js bindings for [LatticeDB](https://github.com/jeffhajewski/latticedb), an embedded knowledge graph database for AI
|
|
3
|
+
TypeScript/Node.js bindings for [LatticeDB](https://github.com/jeffhajewski/latticedb), an embedded knowledge graph database for AI/RAG applications.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
npm install
|
|
8
|
+
npm install @hajewski/latticedb
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
+
The native shared library (`liblattice.dylib` / `liblattice.so`) must be available on the system. Install it via the [install script](https://github.com/jeffhajewski/latticedb#installation) or build from source with `zig build shared`.
|
|
12
|
+
|
|
11
13
|
## Quick Start
|
|
12
14
|
|
|
13
15
|
```typescript
|
|
14
|
-
import { Database } from
|
|
16
|
+
import { Database } from "@hajewski/latticedb";
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
+
const db = new Database("knowledge.db", {
|
|
19
|
+
create: true,
|
|
20
|
+
enableVector: true,
|
|
21
|
+
vectorDimensions: 4,
|
|
22
|
+
});
|
|
18
23
|
await db.open();
|
|
19
24
|
|
|
20
|
-
// Create nodes and
|
|
25
|
+
// Create nodes, edges, and index content
|
|
21
26
|
await db.write(async (txn) => {
|
|
22
27
|
const alice = await txn.createNode({
|
|
23
|
-
labels: [
|
|
24
|
-
properties: { name:
|
|
28
|
+
labels: ["Person"],
|
|
29
|
+
properties: { name: "Alice", age: 30 },
|
|
25
30
|
});
|
|
26
31
|
|
|
27
32
|
const bob = await txn.createNode({
|
|
28
|
-
labels: [
|
|
29
|
-
properties: { name:
|
|
33
|
+
labels: ["Person"],
|
|
34
|
+
properties: { name: "Bob", age: 25 },
|
|
30
35
|
});
|
|
31
36
|
|
|
32
|
-
await txn.createEdge(alice.id, bob.id,
|
|
37
|
+
await txn.createEdge(alice.id, bob.id, "KNOWS");
|
|
38
|
+
|
|
39
|
+
// Index text for full-text search
|
|
40
|
+
await txn.ftsIndex(alice.id, "Alice works on machine learning research");
|
|
41
|
+
await txn.ftsIndex(bob.id, "Bob studies deep learning and neural networks");
|
|
42
|
+
|
|
43
|
+
// Store vector embeddings
|
|
44
|
+
await txn.setVector(
|
|
45
|
+
alice.id,
|
|
46
|
+
"embedding",
|
|
47
|
+
new Float32Array([1.0, 0.0, 0.0, 0.0])
|
|
48
|
+
);
|
|
49
|
+
await txn.setVector(
|
|
50
|
+
bob.id,
|
|
51
|
+
"embedding",
|
|
52
|
+
new Float32Array([0.0, 1.0, 0.0, 0.0])
|
|
53
|
+
);
|
|
33
54
|
});
|
|
34
55
|
|
|
35
56
|
// Query with Cypher
|
|
36
|
-
const result = await db.query(
|
|
57
|
+
const result = await db.query(
|
|
58
|
+
"MATCH (n:Person) WHERE n.age > 20 RETURN n.name, n.age"
|
|
59
|
+
);
|
|
37
60
|
for (const row of result.rows) {
|
|
38
61
|
console.log(row);
|
|
39
62
|
}
|
|
40
63
|
|
|
64
|
+
// Vector similarity search
|
|
65
|
+
const results = await db.vectorSearch(
|
|
66
|
+
new Float32Array([0.9, 0.1, 0.0, 0.0]),
|
|
67
|
+
{ k: 2 }
|
|
68
|
+
);
|
|
69
|
+
for (const r of results) {
|
|
70
|
+
console.log(`Node ${r.nodeId}: distance=${r.distance.toFixed(4)}`);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
// Full-text search
|
|
74
|
+
const ftsResults = await db.ftsSearch("machine learning");
|
|
75
|
+
for (const r of ftsResults) {
|
|
76
|
+
console.log(`Node ${r.nodeId}: score=${r.score.toFixed(4)}`);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// Fuzzy search (typo-tolerant)
|
|
80
|
+
const fuzzyResults = await db.ftsSearchFuzzy("machin lerning");
|
|
81
|
+
for (const r of fuzzyResults) {
|
|
82
|
+
console.log(`Node ${r.nodeId}: score=${r.score.toFixed(4)}`);
|
|
83
|
+
}
|
|
84
|
+
|
|
41
85
|
await db.close();
|
|
42
86
|
```
|
|
43
87
|
|
|
@@ -46,8 +90,12 @@ await db.close();
|
|
|
46
90
|
- **Property Graph** - Nodes and edges with labels and properties
|
|
47
91
|
- **Vector Search** - HNSW-based k-NN search for embeddings
|
|
48
92
|
- **Full-Text Search** - BM25-ranked search with tokenization
|
|
93
|
+
- **Fuzzy Search** - Typo-tolerant full-text search with configurable edit distance
|
|
94
|
+
- **Batch Insert** - Efficient bulk insertion of nodes with vectors
|
|
95
|
+
- **Embeddings** - Built-in hash embeddings and HTTP client for external services
|
|
49
96
|
- **Cypher Queries** - Pattern matching with `<=>` (vector) and `@@` (FTS) extensions
|
|
50
97
|
- **Transactions** - ACID-compliant read/write transactions
|
|
98
|
+
- **Query Cache** - Automatic caching of parsed queries
|
|
51
99
|
- **TypeScript** - Full type definitions included
|
|
52
100
|
|
|
53
101
|
## API Reference
|
|
@@ -58,10 +106,10 @@ await db.close();
|
|
|
58
106
|
const db = new Database(path: string, options?: DatabaseOptions);
|
|
59
107
|
|
|
60
108
|
interface DatabaseOptions {
|
|
61
|
-
create?: boolean;
|
|
62
|
-
readOnly?: boolean;
|
|
63
|
-
cacheSizeMb?: number;
|
|
64
|
-
enableVector?: boolean;
|
|
109
|
+
create?: boolean; // Create if not exists (default: false)
|
|
110
|
+
readOnly?: boolean; // Open read-only (default: false)
|
|
111
|
+
cacheSizeMb?: number; // Cache size in MB (default: 100)
|
|
112
|
+
enableVector?: boolean; // Enable vector storage (default: false)
|
|
65
113
|
vectorDimensions?: number; // Vector dimensions (default: 128)
|
|
66
114
|
}
|
|
67
115
|
```
|
|
@@ -75,70 +123,215 @@ interface DatabaseOptions {
|
|
|
75
123
|
- `await db.query(cypher, params?)` - Execute a Cypher query
|
|
76
124
|
- `await db.vectorSearch(vector, options?)` - k-NN vector search
|
|
77
125
|
- `await db.ftsSearch(query, options?)` - Full-text search
|
|
126
|
+
- `await db.ftsSearchFuzzy(query, options?)` - Fuzzy full-text search
|
|
127
|
+
- `await db.cacheClear()` - Clear the query cache
|
|
128
|
+
- `await db.cacheStats()` - Get cache hit/miss statistics
|
|
78
129
|
- `db.isOpen()` - Check if database is open
|
|
79
130
|
- `db.getPath()` - Get database file path
|
|
80
131
|
|
|
81
132
|
### Transaction
|
|
82
133
|
|
|
134
|
+
#### Read Operations
|
|
135
|
+
|
|
136
|
+
- `await txn.getNode(nodeId)` - Get a node by ID, returns `Node` or `null`
|
|
137
|
+
- `await txn.nodeExists(nodeId)` - Check if a node exists
|
|
138
|
+
- `await txn.getProperty(nodeId, key)` - Get a property value
|
|
139
|
+
- `await txn.getOutgoingEdges(nodeId)` - Get outgoing edges from a node
|
|
140
|
+
- `await txn.getIncomingEdges(nodeId)` - Get incoming edges to a node
|
|
141
|
+
- `txn.isReadOnly()` / `txn.isActive()` - Transaction state
|
|
142
|
+
|
|
143
|
+
#### Write Operations
|
|
144
|
+
|
|
145
|
+
- `await txn.createNode({ labels, properties })` - Create a node
|
|
146
|
+
- `await txn.deleteNode(nodeId)` - Delete a node
|
|
147
|
+
- `await txn.setProperty(nodeId, key, value)` - Set a property
|
|
148
|
+
- `await txn.setVector(nodeId, key, vector)` - Set a vector embedding
|
|
149
|
+
- `await txn.batchInsert(label, vectors)` - Batch insert nodes with vectors
|
|
150
|
+
- `await txn.ftsIndex(nodeId, text)` - Index text for full-text search
|
|
151
|
+
- `await txn.createEdge(sourceId, targetId, edgeType)` - Create an edge
|
|
152
|
+
- `await txn.deleteEdge(sourceId, targetId, edgeType)` - Delete an edge
|
|
153
|
+
- `txn.commit()` / `txn.rollback()` - Commit or rollback
|
|
154
|
+
|
|
155
|
+
### Batch Insert
|
|
156
|
+
|
|
157
|
+
Insert many nodes with vectors in a single efficient call:
|
|
158
|
+
|
|
83
159
|
```typescript
|
|
160
|
+
import { Database } from "@hajewski/latticedb";
|
|
161
|
+
|
|
162
|
+
const db = new Database("vectors.db", {
|
|
163
|
+
create: true,
|
|
164
|
+
enableVector: true,
|
|
165
|
+
vectorDimensions: 128,
|
|
166
|
+
});
|
|
167
|
+
await db.open();
|
|
168
|
+
|
|
84
169
|
await db.write(async (txn) => {
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
const
|
|
89
|
-
|
|
170
|
+
const vectors = Array.from({ length: 1000 }, () =>
|
|
171
|
+
Float32Array.from({ length: 128 }, () => Math.random())
|
|
172
|
+
);
|
|
173
|
+
const nodeIds = await txn.batchInsert("Document", vectors);
|
|
174
|
+
console.log(`Created ${nodeIds.length} nodes`);
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
await db.close();
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Full-Text Search
|
|
181
|
+
|
|
182
|
+
#### Exact Search
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
const results = await db.ftsSearch("machine learning", { limit: 10 });
|
|
186
|
+
for (const r of results) {
|
|
187
|
+
console.log(`Node ${r.nodeId}: score=${r.score.toFixed(4)}`);
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
#### Fuzzy Search (Typo-Tolerant)
|
|
192
|
+
|
|
193
|
+
```typescript
|
|
194
|
+
// Finds "machine learning" even with typos
|
|
195
|
+
const results = await db.ftsSearchFuzzy("machne lerning", { limit: 10 });
|
|
196
|
+
|
|
197
|
+
// Control fuzzy matching sensitivity
|
|
198
|
+
const precise = await db.ftsSearchFuzzy("machne", {
|
|
199
|
+
limit: 10,
|
|
200
|
+
maxDistance: 2, // Max edit distance (default: 0 = auto)
|
|
201
|
+
minTermLength: 4, // Min term length for fuzzy matching (default: 0 = auto)
|
|
202
|
+
});
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Embeddings
|
|
206
|
+
|
|
207
|
+
LatticeDB includes a built-in hash embedding function and an HTTP client for external embedding services.
|
|
208
|
+
|
|
209
|
+
#### Hash Embeddings (Built-in)
|
|
210
|
+
|
|
211
|
+
Deterministic, no external service needed. Useful for testing or simple keyword-based similarity:
|
|
90
212
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
213
|
+
```typescript
|
|
214
|
+
import { hashEmbed } from "@hajewski/latticedb";
|
|
215
|
+
|
|
216
|
+
const vec = hashEmbed("hello world", 128);
|
|
217
|
+
console.log(vec.length); // 128
|
|
218
|
+
```
|
|
94
219
|
|
|
95
|
-
|
|
96
|
-
await txn.setVector(nodeId, 'embedding', new Float32Array([...]));
|
|
220
|
+
#### HTTP Embedding Client
|
|
97
221
|
|
|
98
|
-
|
|
99
|
-
|
|
222
|
+
Connect to Ollama, OpenAI, or compatible APIs:
|
|
223
|
+
|
|
224
|
+
```typescript
|
|
225
|
+
import { EmbeddingClient, EmbeddingApiFormat } from "@hajewski/latticedb";
|
|
100
226
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
227
|
+
// Ollama (default)
|
|
228
|
+
const client = new EmbeddingClient({
|
|
229
|
+
endpoint: "http://localhost:11434",
|
|
230
|
+
});
|
|
231
|
+
const vec = client.embed("hello world");
|
|
232
|
+
client.close();
|
|
233
|
+
|
|
234
|
+
// OpenAI-compatible API
|
|
235
|
+
const openaiClient = new EmbeddingClient({
|
|
236
|
+
endpoint: "https://api.openai.com/v1",
|
|
237
|
+
model: "text-embedding-3-small",
|
|
238
|
+
apiFormat: EmbeddingApiFormat.OpenAI,
|
|
239
|
+
apiKey: "sk-...",
|
|
240
|
+
});
|
|
241
|
+
const embedding = openaiClient.embed("hello world");
|
|
242
|
+
openaiClient.close();
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### Edge Traversal
|
|
246
|
+
|
|
247
|
+
```typescript
|
|
248
|
+
await db.read(async (txn) => {
|
|
104
249
|
const outgoing = await txn.getOutgoingEdges(nodeId);
|
|
250
|
+
for (const edge of outgoing) {
|
|
251
|
+
console.log(`${edge.sourceId} --[${edge.type}]--> ${edge.targetId}`);
|
|
252
|
+
}
|
|
253
|
+
|
|
105
254
|
const incoming = await txn.getIncomingEdges(nodeId);
|
|
255
|
+
for (const edge of incoming) {
|
|
256
|
+
console.log(`${edge.sourceId} --[${edge.type}]--> ${edge.targetId}`);
|
|
257
|
+
}
|
|
106
258
|
});
|
|
107
259
|
```
|
|
108
260
|
|
|
109
|
-
###
|
|
261
|
+
### Cypher Queries
|
|
110
262
|
|
|
111
263
|
```typescript
|
|
112
|
-
//
|
|
113
|
-
const result = await db.query(
|
|
264
|
+
// Pattern matching
|
|
265
|
+
const result = await db.query("MATCH (n:Person) RETURN n.name");
|
|
114
266
|
|
|
115
267
|
// With parameters
|
|
116
268
|
const result = await db.query(
|
|
117
|
-
|
|
118
|
-
{ name:
|
|
269
|
+
"MATCH (n:Person) WHERE n.name = $name RETURN n",
|
|
270
|
+
{ name: "Alice" }
|
|
119
271
|
);
|
|
120
272
|
|
|
121
|
-
// Vector similarity
|
|
273
|
+
// Vector similarity in Cypher
|
|
122
274
|
const result = await db.query(
|
|
123
|
-
|
|
124
|
-
{
|
|
275
|
+
"MATCH (n:Document) WHERE n.embedding <=> $vec < 0.5 RETURN n.title",
|
|
276
|
+
{ vec: new Float32Array([0.1, 0.2, 0.3, 0.4]) }
|
|
125
277
|
);
|
|
126
278
|
|
|
127
|
-
// Full-text search
|
|
279
|
+
// Full-text search in Cypher
|
|
128
280
|
const result = await db.query(
|
|
129
281
|
'MATCH (n:Document) WHERE n.content @@ "machine learning" RETURN n.title'
|
|
130
282
|
);
|
|
131
283
|
|
|
132
284
|
// Data mutation
|
|
133
|
-
await db.query('CREATE (n:Person {name: "
|
|
134
|
-
await db.query('MATCH (n:Person {name: "
|
|
135
|
-
await db.query('MATCH (n:Person {name: "
|
|
136
|
-
|
|
285
|
+
await db.query('CREATE (n:Person {name: "Charlie", age: 35})');
|
|
286
|
+
await db.query('MATCH (n:Person {name: "Charlie"}) SET n.age = 36');
|
|
287
|
+
await db.query('MATCH (n:Person {name: "Charlie"}) DETACH DELETE n');
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
### Query Cache
|
|
291
|
+
|
|
292
|
+
```typescript
|
|
293
|
+
// Get cache statistics
|
|
294
|
+
const stats = await db.cacheStats();
|
|
295
|
+
console.log(
|
|
296
|
+
`Entries: ${stats.entries}, Hits: ${stats.hits}, Misses: ${stats.misses}`
|
|
297
|
+
);
|
|
298
|
+
|
|
299
|
+
// Clear the cache
|
|
300
|
+
await db.cacheClear();
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
## Supported Property Types
|
|
304
|
+
|
|
305
|
+
- `null` - Null value
|
|
306
|
+
- `boolean` - Boolean
|
|
307
|
+
- `number` - Integer or float
|
|
308
|
+
- `string` - UTF-8 string
|
|
309
|
+
- `Uint8Array` - Binary data
|
|
310
|
+
|
|
311
|
+
## Error Handling
|
|
312
|
+
|
|
313
|
+
```typescript
|
|
314
|
+
import { Database, isLibraryAvailable } from "@hajewski/latticedb";
|
|
315
|
+
|
|
316
|
+
// Check if native library is available
|
|
317
|
+
if (!isLibraryAvailable()) {
|
|
318
|
+
console.error("LatticeDB native library not found");
|
|
319
|
+
process.exit(1);
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
try {
|
|
323
|
+
const db = new Database("test.db", { create: true });
|
|
324
|
+
await db.open();
|
|
325
|
+
// ...
|
|
326
|
+
await db.close();
|
|
327
|
+
} catch (error) {
|
|
328
|
+
console.error("Database error:", error);
|
|
329
|
+
}
|
|
137
330
|
```
|
|
138
331
|
|
|
139
332
|
## Building from Source
|
|
140
333
|
|
|
141
|
-
Requires Node.js 18+ and the LatticeDB native library
|
|
334
|
+
Requires Node.js 18+ and the LatticeDB native library.
|
|
142
335
|
|
|
143
336
|
```bash
|
|
144
337
|
# From the latticedb root directory
|
|
@@ -147,12 +340,17 @@ zig build shared
|
|
|
147
340
|
# Build the TypeScript bindings
|
|
148
341
|
cd bindings/typescript
|
|
149
342
|
npm install
|
|
150
|
-
npm run build
|
|
343
|
+
npm run build
|
|
151
344
|
|
|
152
345
|
# Run tests
|
|
153
346
|
npm test
|
|
154
347
|
```
|
|
155
348
|
|
|
349
|
+
## Requirements
|
|
350
|
+
|
|
351
|
+
- Node.js 18+
|
|
352
|
+
- The native LatticeDB library (`liblattice.dylib` / `liblattice.so`)
|
|
353
|
+
|
|
156
354
|
## License
|
|
157
355
|
|
|
158
356
|
MIT
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* High-level embedding utilities for LatticeDB.
|
|
3
|
+
*
|
|
4
|
+
* Provides hash-based embeddings (built-in, no external service) and
|
|
5
|
+
* an HTTP embedding client for services like Ollama and OpenAI.
|
|
6
|
+
*/
|
|
7
|
+
import { EmbeddingConfig } from './types';
|
|
8
|
+
/**
|
|
9
|
+
* Generate a hash embedding for text (built-in, no external service).
|
|
10
|
+
*
|
|
11
|
+
* Deterministic and fast. Useful for testing or simple keyword-based similarity.
|
|
12
|
+
*
|
|
13
|
+
* @param text - The text to embed.
|
|
14
|
+
* @param dimensions - Number of embedding dimensions (default 128).
|
|
15
|
+
* @returns A Float32Array of the specified dimensions.
|
|
16
|
+
*/
|
|
17
|
+
export declare function hashEmbed(text: string, dimensions?: number): Float32Array;
|
|
18
|
+
/**
|
|
19
|
+
* HTTP embedding client for services like Ollama and OpenAI.
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```typescript
|
|
23
|
+
* const client = new EmbeddingClient({ endpoint: "http://localhost:11434" });
|
|
24
|
+
* const vec = client.embed("hello world");
|
|
25
|
+
* client.close();
|
|
26
|
+
* ```
|
|
27
|
+
*/
|
|
28
|
+
export declare class EmbeddingClient {
|
|
29
|
+
private handle;
|
|
30
|
+
/**
|
|
31
|
+
* Create an embedding client connected to an HTTP service.
|
|
32
|
+
*
|
|
33
|
+
* @param config - Embedding service configuration.
|
|
34
|
+
*/
|
|
35
|
+
constructor(config: EmbeddingConfig);
|
|
36
|
+
/**
|
|
37
|
+
* Generate an embedding for text via the HTTP service.
|
|
38
|
+
*
|
|
39
|
+
* @param text - The text to embed.
|
|
40
|
+
* @returns A Float32Array embedding vector.
|
|
41
|
+
*/
|
|
42
|
+
embed(text: string): Float32Array;
|
|
43
|
+
/**
|
|
44
|
+
* Free the underlying native client. Safe to call multiple times.
|
|
45
|
+
*/
|
|
46
|
+
close(): void;
|
|
47
|
+
}
|
|
48
|
+
//# sourceMappingURL=embedding.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../src/embedding.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY,GAAG,YAAY,CAE9E;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAA+B;IAE7C;;;;OAIG;gBACS,MAAM,EAAE,eAAe;IAWnC;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAOjC;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd"}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* High-level embedding utilities for LatticeDB.
|
|
4
|
+
*
|
|
5
|
+
* Provides hash-based embeddings (built-in, no external service) and
|
|
6
|
+
* an HTTP embedding client for services like Ollama and OpenAI.
|
|
7
|
+
*/
|
|
8
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
9
|
+
exports.EmbeddingClient = void 0;
|
|
10
|
+
exports.hashEmbed = hashEmbed;
|
|
11
|
+
const ffi_1 = require("./ffi");
|
|
12
|
+
/**
|
|
13
|
+
* Generate a hash embedding for text (built-in, no external service).
|
|
14
|
+
*
|
|
15
|
+
* Deterministic and fast. Useful for testing or simple keyword-based similarity.
|
|
16
|
+
*
|
|
17
|
+
* @param text - The text to embed.
|
|
18
|
+
* @param dimensions - Number of embedding dimensions (default 128).
|
|
19
|
+
* @returns A Float32Array of the specified dimensions.
|
|
20
|
+
*/
|
|
21
|
+
function hashEmbed(text, dimensions = 128) {
|
|
22
|
+
return (0, ffi_1.getFFI)().hashEmbed(text, dimensions);
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* HTTP embedding client for services like Ollama and OpenAI.
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```typescript
|
|
29
|
+
* const client = new EmbeddingClient({ endpoint: "http://localhost:11434" });
|
|
30
|
+
* const vec = client.embed("hello world");
|
|
31
|
+
* client.close();
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
class EmbeddingClient {
|
|
35
|
+
handle;
|
|
36
|
+
/**
|
|
37
|
+
* Create an embedding client connected to an HTTP service.
|
|
38
|
+
*
|
|
39
|
+
* @param config - Embedding service configuration.
|
|
40
|
+
*/
|
|
41
|
+
constructor(config) {
|
|
42
|
+
const ffi = (0, ffi_1.getFFI)();
|
|
43
|
+
this.handle = ffi.embeddingClientCreate({
|
|
44
|
+
endpoint: config.endpoint,
|
|
45
|
+
model: config.model,
|
|
46
|
+
apiFormat: config.apiFormat,
|
|
47
|
+
apiKey: config.apiKey,
|
|
48
|
+
timeoutMs: config.timeoutMs,
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Generate an embedding for text via the HTTP service.
|
|
53
|
+
*
|
|
54
|
+
* @param text - The text to embed.
|
|
55
|
+
* @returns A Float32Array embedding vector.
|
|
56
|
+
*/
|
|
57
|
+
embed(text) {
|
|
58
|
+
if (this.handle === null) {
|
|
59
|
+
throw new Error('EmbeddingClient has been closed');
|
|
60
|
+
}
|
|
61
|
+
return (0, ffi_1.getFFI)().embeddingClientEmbed(this.handle, text);
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Free the underlying native client. Safe to call multiple times.
|
|
65
|
+
*/
|
|
66
|
+
close() {
|
|
67
|
+
if (this.handle !== null) {
|
|
68
|
+
(0, ffi_1.getFFI)().embeddingClientFree(this.handle);
|
|
69
|
+
this.handle = null;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
exports.EmbeddingClient = EmbeddingClient;
|
|
74
|
+
//# sourceMappingURL=embedding.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../src/embedding.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAcH,8BAEC;AAdD,+BAAsD;AAGtD;;;;;;;;GAQG;AACH,SAAgB,SAAS,CAAC,IAAY,EAAE,aAAqB,GAAG;IAC9D,OAAO,IAAA,YAAM,GAAE,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAa,eAAe;IAClB,MAAM,CAA+B;IAE7C;;;;OAIG;IACH,YAAY,MAAuB;QACjC,MAAM,GAAG,GAAG,IAAA,YAAM,GAAE,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,qBAAqB,CAAC;YACtC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAY;QAChB,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,IAAA,YAAM,GAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACzB,IAAA,YAAM,GAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AAzCD,0CAyCC"}
|
package/dist/ffi/bindings.d.ts
CHANGED
|
@@ -40,6 +40,13 @@ export interface LatticeBindings {
|
|
|
40
40
|
lattice_query_bind: (query: unknown, name: string, value: unknown) => number;
|
|
41
41
|
lattice_query_bind_vector: (query: unknown, name: string, vector: Float32Array, dimensions: number) => number;
|
|
42
42
|
lattice_query_execute: (query: unknown, txn: unknown, result_out: unknown[]) => number;
|
|
43
|
+
lattice_query_last_error_stage: (query: unknown) => number;
|
|
44
|
+
lattice_query_last_error_message: (query: unknown) => string | null;
|
|
45
|
+
lattice_query_last_error_code: (query: unknown) => string | null;
|
|
46
|
+
lattice_query_last_error_has_location: (query: unknown) => boolean;
|
|
47
|
+
lattice_query_last_error_line: (query: unknown) => number;
|
|
48
|
+
lattice_query_last_error_column: (query: unknown) => number;
|
|
49
|
+
lattice_query_last_error_length: (query: unknown) => number;
|
|
43
50
|
lattice_query_free: (query: unknown) => void;
|
|
44
51
|
lattice_query_cache_clear: (db: unknown) => number;
|
|
45
52
|
lattice_query_cache_stats: (db: unknown, entries_out: Buffer, hits_out: Buffer, misses_out: Buffer) => number;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/ffi/bindings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;
|
|
1
|
+
{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/ffi/bindings.ts"],"names":[],"mappings":"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"}
|