@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.
@@ -0,0 +1,586 @@
1
+ /**
2
+ * Lattice: Embedded Knowledge Graph Database
3
+ *
4
+ * A single-file knowledge graph database for AI/RAG applications.
5
+ * Combines property graph storage, HNSW vector search, and BM25 full-text search.
6
+ *
7
+ * This is the stable C API. All language bindings wrap this interface.
8
+ */
9
+
10
+ #ifndef LATTICE_H
11
+ #define LATTICE_H
12
+
13
+ #include <stddef.h>
14
+ #include <stdint.h>
15
+ #include <stdbool.h>
16
+
17
+ #ifdef __cplusplus
18
+ extern "C" {
19
+ #endif
20
+
21
+ /* Version information */
22
+ #define LATTICE_VERSION "0.3.0"
23
+ #define LATTICE_VERSION_MAJOR 0
24
+ #define LATTICE_VERSION_MINOR 3
25
+ #define LATTICE_VERSION_PATCH 0
26
+
27
+ /* Opaque handle types */
28
+ typedef struct lattice_database lattice_database;
29
+ typedef struct lattice_txn lattice_txn;
30
+ typedef struct lattice_query lattice_query;
31
+ typedef struct lattice_result lattice_result;
32
+ typedef struct lattice_vector_result lattice_vector_result;
33
+ typedef struct lattice_fts_result lattice_fts_result;
34
+ typedef struct lattice_edge_result lattice_edge_result;
35
+
36
+ /* ID types */
37
+ typedef uint64_t lattice_node_id;
38
+ typedef uint64_t lattice_edge_id;
39
+
40
+ /* Error codes */
41
+ typedef enum {
42
+ LATTICE_OK = 0,
43
+ LATTICE_ERROR = -1,
44
+ LATTICE_ERROR_IO = -2,
45
+ LATTICE_ERROR_CORRUPTION = -3,
46
+ LATTICE_ERROR_NOT_FOUND = -4,
47
+ LATTICE_ERROR_ALREADY_EXISTS = -5,
48
+ LATTICE_ERROR_INVALID_ARG = -6,
49
+ LATTICE_ERROR_TXN_ABORTED = -7,
50
+ LATTICE_ERROR_LOCK_TIMEOUT = -8,
51
+ LATTICE_ERROR_READ_ONLY = -9,
52
+ LATTICE_ERROR_FULL = -10,
53
+ LATTICE_ERROR_VERSION_MISMATCH = -11,
54
+ LATTICE_ERROR_CHECKSUM = -12,
55
+ LATTICE_ERROR_OUT_OF_MEMORY = -13
56
+ } lattice_error;
57
+
58
+ /* Transaction modes */
59
+ typedef enum {
60
+ LATTICE_TXN_READ_ONLY = 0,
61
+ LATTICE_TXN_READ_WRITE = 1
62
+ } lattice_txn_mode;
63
+
64
+ /* Value types */
65
+ typedef enum {
66
+ LATTICE_VALUE_NULL = 0,
67
+ LATTICE_VALUE_BOOL = 1,
68
+ LATTICE_VALUE_INT = 2,
69
+ LATTICE_VALUE_FLOAT = 3,
70
+ LATTICE_VALUE_STRING = 4,
71
+ LATTICE_VALUE_BYTES = 5,
72
+ LATTICE_VALUE_VECTOR = 6,
73
+ LATTICE_VALUE_LIST = 7,
74
+ LATTICE_VALUE_MAP = 8
75
+ } lattice_value_type;
76
+
77
+ /* Property value */
78
+ typedef struct {
79
+ lattice_value_type type;
80
+ union {
81
+ bool bool_val;
82
+ int64_t int_val;
83
+ double float_val;
84
+ struct {
85
+ const char* ptr;
86
+ size_t len;
87
+ } string_val;
88
+ struct {
89
+ const uint8_t* ptr;
90
+ size_t len;
91
+ } bytes_val;
92
+ struct {
93
+ const float* ptr;
94
+ uint32_t dimensions;
95
+ } vector_val;
96
+ } data;
97
+ } lattice_value;
98
+
99
+ /* Open options */
100
+ typedef struct {
101
+ bool create; /* Create if not exists */
102
+ bool read_only; /* Open in read-only mode */
103
+ uint32_t cache_size_mb; /* Cache size in MB (default: 100) */
104
+ uint32_t page_size; /* Page size in bytes (default: 4096) */
105
+ bool enable_vector; /* Enable vector storage for embeddings */
106
+ uint16_t vector_dimensions; /* Vector dimensions (default: 128) */
107
+ } lattice_open_options;
108
+
109
+ /* Default open options */
110
+ #define LATTICE_OPEN_OPTIONS_DEFAULT { false, false, 100, 4096, false, 128 }
111
+
112
+ /*
113
+ * Database operations
114
+ */
115
+
116
+ /* Open a database file */
117
+ lattice_error lattice_open(
118
+ const char* path,
119
+ const lattice_open_options* options,
120
+ lattice_database** db_out
121
+ );
122
+
123
+ /* Close a database */
124
+ lattice_error lattice_close(lattice_database* db);
125
+
126
+ /*
127
+ * Transaction operations
128
+ */
129
+
130
+ /* Begin a transaction */
131
+ lattice_error lattice_begin(
132
+ lattice_database* db,
133
+ lattice_txn_mode mode,
134
+ lattice_txn** txn_out
135
+ );
136
+
137
+ /* Commit a transaction */
138
+ lattice_error lattice_commit(lattice_txn* txn);
139
+
140
+ /* Rollback a transaction */
141
+ lattice_error lattice_rollback(lattice_txn* txn);
142
+
143
+ /*
144
+ * Node operations
145
+ */
146
+
147
+ /* Create a node with a label */
148
+ lattice_error lattice_node_create(
149
+ lattice_txn* txn,
150
+ const char* label,
151
+ lattice_node_id* node_out
152
+ );
153
+
154
+ /* Delete a node */
155
+ lattice_error lattice_node_delete(
156
+ lattice_txn* txn,
157
+ lattice_node_id node_id
158
+ );
159
+
160
+ /* Set a property on a node */
161
+ lattice_error lattice_node_set_property(
162
+ lattice_txn* txn,
163
+ lattice_node_id node_id,
164
+ const char* key,
165
+ const lattice_value* value
166
+ );
167
+
168
+ /* Get a property from a node */
169
+ lattice_error lattice_node_get_property(
170
+ lattice_txn* txn,
171
+ lattice_node_id node_id,
172
+ const char* key,
173
+ lattice_value* value_out
174
+ );
175
+
176
+ /* Check if a node exists */
177
+ lattice_error lattice_node_exists(
178
+ lattice_txn* txn,
179
+ lattice_node_id node_id,
180
+ bool* exists_out
181
+ );
182
+
183
+ /* Get labels for a node (comma-separated string, caller must free) */
184
+ lattice_error lattice_node_get_labels(
185
+ lattice_txn* txn,
186
+ lattice_node_id node_id,
187
+ char** labels_out
188
+ );
189
+
190
+ /* Free a string allocated by lattice (e.g., from lattice_node_get_labels) */
191
+ void lattice_free_string(char* str);
192
+
193
+ /* Set a vector on a node */
194
+ lattice_error lattice_node_set_vector(
195
+ lattice_txn* txn,
196
+ lattice_node_id node_id,
197
+ const char* key,
198
+ const float* vector,
199
+ uint32_t dimensions
200
+ );
201
+
202
+ /*
203
+ * Batch insert operations
204
+ */
205
+
206
+ /* Node spec for batch insert: label + vector */
207
+ typedef struct {
208
+ const char* label;
209
+ const float* vector;
210
+ uint32_t dimensions;
211
+ } lattice_node_with_vector;
212
+
213
+ /* Create multiple nodes with vectors in a single call.
214
+ * On success, node_ids_out[0..count_out] contains created node IDs.
215
+ * On partial failure, count_out indicates how many succeeded;
216
+ * caller should rollback the transaction.
217
+ */
218
+ lattice_error lattice_batch_insert(
219
+ lattice_txn* txn,
220
+ const lattice_node_with_vector* nodes,
221
+ uint32_t count,
222
+ lattice_node_id* node_ids_out, /* caller-allocated, size count */
223
+ uint32_t* count_out /* nodes successfully created */
224
+ );
225
+
226
+ /*
227
+ * Vector search operations
228
+ *
229
+ * Search for similar vectors using HNSW index:
230
+ * 1. Call lattice_vector_search() with query vector
231
+ * 2. Get result count with lattice_vector_result_count()
232
+ * 3. Iterate results with lattice_vector_result_get()
233
+ * 4. Free with lattice_vector_result_free()
234
+ *
235
+ * Example:
236
+ * float query[128] = { ... };
237
+ * lattice_vector_result* results;
238
+ * lattice_vector_search(db, query, 128, 10, 64, &results);
239
+ * uint32_t count = lattice_vector_result_count(results);
240
+ * for (uint32_t i = 0; i < count; i++) {
241
+ * lattice_node_id node_id;
242
+ * float distance;
243
+ * lattice_vector_result_get(results, i, &node_id, &distance);
244
+ * }
245
+ * lattice_vector_result_free(results);
246
+ */
247
+
248
+ /* Search for similar vectors */
249
+ lattice_error lattice_vector_search(
250
+ lattice_database* db,
251
+ const float* vector,
252
+ uint32_t dimensions,
253
+ uint32_t k, /* Number of results to return */
254
+ uint16_t ef_search, /* HNSW ef parameter (0 for default) */
255
+ lattice_vector_result** result_out
256
+ );
257
+
258
+ /* Get the number of results */
259
+ uint32_t lattice_vector_result_count(lattice_vector_result* result);
260
+
261
+ /* Get a result by index */
262
+ lattice_error lattice_vector_result_get(
263
+ lattice_vector_result* result,
264
+ uint32_t index,
265
+ lattice_node_id* node_id_out,
266
+ float* distance_out
267
+ );
268
+
269
+ /* Free vector search results */
270
+ void lattice_vector_result_free(lattice_vector_result* result);
271
+
272
+ /*
273
+ * Full-text search operations
274
+ *
275
+ * BM25-scored full-text search:
276
+ * 1. Index documents with lattice_fts_index()
277
+ * 2. Search with lattice_fts_search()
278
+ * 3. Get result count with lattice_fts_result_count()
279
+ * 4. Iterate results with lattice_fts_result_get()
280
+ * 5. Free with lattice_fts_result_free()
281
+ *
282
+ * Example:
283
+ * // Index a document
284
+ * const char* text = "The quick brown fox jumps over the lazy dog";
285
+ * lattice_fts_index(txn, node_id, text, strlen(text));
286
+ *
287
+ * // Search
288
+ * lattice_fts_result* results;
289
+ * lattice_fts_search(db, "quick fox", 9, 10, &results);
290
+ * uint32_t count = lattice_fts_result_count(results);
291
+ * for (uint32_t i = 0; i < count; i++) {
292
+ * lattice_node_id node_id;
293
+ * float score;
294
+ * lattice_fts_result_get(results, i, &node_id, &score);
295
+ * }
296
+ * lattice_fts_result_free(results);
297
+ */
298
+
299
+ /* Index a text document for full-text search */
300
+ lattice_error lattice_fts_index(
301
+ lattice_txn* txn,
302
+ lattice_node_id node_id,
303
+ const char* text,
304
+ size_t text_len
305
+ );
306
+
307
+ /* Search for documents matching a text query */
308
+ lattice_error lattice_fts_search(
309
+ lattice_database* db,
310
+ const char* query,
311
+ size_t query_len,
312
+ uint32_t limit,
313
+ lattice_fts_result** result_out
314
+ );
315
+
316
+ /* Search with fuzzy matching (typo tolerance).
317
+ * max_distance: max Levenshtein edit distance (0 = default 2)
318
+ * min_term_length: min term length for fuzzy expansion (0 = default 4) */
319
+ lattice_error lattice_fts_search_fuzzy(
320
+ lattice_database* db,
321
+ const char* query,
322
+ size_t query_len,
323
+ uint32_t limit,
324
+ uint32_t max_distance,
325
+ uint32_t min_term_length,
326
+ lattice_fts_result** result_out
327
+ );
328
+
329
+ /* Get the number of FTS results */
330
+ uint32_t lattice_fts_result_count(lattice_fts_result* result);
331
+
332
+ /* Get a result by index (returns node_id and BM25 score) */
333
+ lattice_error lattice_fts_result_get(
334
+ lattice_fts_result* result,
335
+ uint32_t index,
336
+ lattice_node_id* node_id_out,
337
+ float* score_out
338
+ );
339
+
340
+ /* Free FTS search results */
341
+ void lattice_fts_result_free(lattice_fts_result* result);
342
+
343
+ /*
344
+ * Embedding operations
345
+ */
346
+
347
+ typedef struct lattice_embedding_client lattice_embedding_client;
348
+
349
+ typedef enum {
350
+ LATTICE_EMBEDDING_OLLAMA = 0,
351
+ LATTICE_EMBEDDING_OPENAI = 1
352
+ } lattice_embedding_api_format;
353
+
354
+ typedef struct {
355
+ const char* endpoint;
356
+ const char* model;
357
+ lattice_embedding_api_format api_format;
358
+ const char* api_key; /* NULL for no auth */
359
+ uint32_t timeout_ms; /* 0 = default 30s */
360
+ } lattice_embedding_config;
361
+
362
+ /* Generate a hash embedding (built-in, no external service).
363
+ * Caller must free with lattice_hash_embed_free(). */
364
+ lattice_error lattice_hash_embed(
365
+ const char* text, size_t text_len,
366
+ uint16_t dimensions,
367
+ float** vector_out, uint32_t* dims_out
368
+ );
369
+
370
+ /* Free a hash embedding vector */
371
+ void lattice_hash_embed_free(float* vector, uint32_t dimensions);
372
+
373
+ /* Create an HTTP embedding client */
374
+ lattice_error lattice_embedding_client_create(
375
+ const lattice_embedding_config* config,
376
+ lattice_embedding_client** client_out
377
+ );
378
+
379
+ /* Generate an embedding via HTTP.
380
+ * Caller must free with lattice_hash_embed_free(). */
381
+ lattice_error lattice_embedding_client_embed(
382
+ lattice_embedding_client* client,
383
+ const char* text, size_t text_len,
384
+ float** vector_out, uint32_t* dims_out
385
+ );
386
+
387
+ /* Free an HTTP embedding client */
388
+ void lattice_embedding_client_free(lattice_embedding_client* client);
389
+
390
+ /*
391
+ * Edge operations
392
+ */
393
+
394
+ /* Create an edge between two nodes */
395
+ lattice_error lattice_edge_create(
396
+ lattice_txn* txn,
397
+ lattice_node_id source,
398
+ lattice_node_id target,
399
+ const char* edge_type,
400
+ lattice_edge_id* edge_out
401
+ );
402
+
403
+ /* Delete an edge between two nodes */
404
+ lattice_error lattice_edge_delete(
405
+ lattice_txn* txn,
406
+ lattice_node_id source,
407
+ lattice_node_id target,
408
+ const char* edge_type
409
+ );
410
+
411
+ /*
412
+ * Edge traversal operations
413
+ *
414
+ * Get edges connected to a node:
415
+ * 1. Call lattice_edge_get_outgoing() or lattice_edge_get_incoming()
416
+ * 2. Get result count with lattice_edge_result_count()
417
+ * 3. Iterate results with lattice_edge_result_get()
418
+ * 4. Free with lattice_edge_result_free()
419
+ *
420
+ * Example:
421
+ * lattice_edge_result* edges;
422
+ * lattice_edge_get_outgoing(txn, node_id, &edges);
423
+ * uint32_t count = lattice_edge_result_count(edges);
424
+ * for (uint32_t i = 0; i < count; i++) {
425
+ * lattice_node_id source, target;
426
+ * const char* type;
427
+ * uint32_t type_len;
428
+ * lattice_edge_result_get(edges, i, &source, &target, &type, &type_len);
429
+ * }
430
+ * lattice_edge_result_free(edges);
431
+ */
432
+
433
+ /* Get all outgoing edges from a node */
434
+ lattice_error lattice_edge_get_outgoing(
435
+ lattice_txn* txn,
436
+ lattice_node_id node_id,
437
+ lattice_edge_result** result_out
438
+ );
439
+
440
+ /* Get all incoming edges to a node */
441
+ lattice_error lattice_edge_get_incoming(
442
+ lattice_txn* txn,
443
+ lattice_node_id node_id,
444
+ lattice_edge_result** result_out
445
+ );
446
+
447
+ /* Get the number of edges in a result set */
448
+ uint32_t lattice_edge_result_count(lattice_edge_result* result);
449
+
450
+ /* Get an edge from a result set by index */
451
+ lattice_error lattice_edge_result_get(
452
+ lattice_edge_result* result,
453
+ uint32_t index,
454
+ lattice_node_id* source_out,
455
+ lattice_node_id* target_out,
456
+ const char** edge_type_out,
457
+ uint32_t* edge_type_len_out
458
+ );
459
+
460
+ /* Free an edge result set */
461
+ void lattice_edge_result_free(lattice_edge_result* result);
462
+
463
+ /*
464
+ * Query operations
465
+ *
466
+ * Queries use a prepare/bind/execute pattern:
467
+ * 1. Prepare the query with lattice_query_prepare()
468
+ * 2. Bind parameters with lattice_query_bind() (optional)
469
+ * 3. Execute with lattice_query_execute()
470
+ * 4. Iterate results with lattice_result_next() / lattice_result_get()
471
+ * 5. Free resources with lattice_query_free() and lattice_result_free()
472
+ *
473
+ * Example:
474
+ * lattice_query* query;
475
+ * lattice_query_prepare(db, "MATCH (n) WHERE n.name = $name RETURN n", &query);
476
+ * lattice_value val = { .type = LATTICE_VALUE_STRING, .data.string_val = {"Alice", 5} };
477
+ * lattice_query_bind(query, "name", &val);
478
+ * lattice_query_execute(query, txn, &result);
479
+ */
480
+
481
+ /* Query diagnostic stage returned by lattice_query_last_error_stage() */
482
+ typedef enum {
483
+ LATTICE_QUERY_STAGE_NONE = 0,
484
+ LATTICE_QUERY_STAGE_PARSE = 1,
485
+ LATTICE_QUERY_STAGE_SEMANTIC = 2,
486
+ LATTICE_QUERY_STAGE_PLAN = 3,
487
+ LATTICE_QUERY_STAGE_EXECUTION = 4
488
+ } lattice_query_error_stage;
489
+
490
+ /* Prepare a Cypher query for execution */
491
+ lattice_error lattice_query_prepare(
492
+ lattice_database* db,
493
+ const char* cypher,
494
+ lattice_query** query_out
495
+ );
496
+
497
+ /* Bind a parameter to a prepared query (use $name in Cypher) */
498
+ lattice_error lattice_query_bind(
499
+ lattice_query* query,
500
+ const char* name, /* Parameter name without $ prefix */
501
+ const lattice_value* value
502
+ );
503
+
504
+ /* Bind a vector parameter to a prepared query */
505
+ lattice_error lattice_query_bind_vector(
506
+ lattice_query* query,
507
+ const char* name,
508
+ const float* vector,
509
+ uint32_t dimensions
510
+ );
511
+
512
+ /* Execute a prepared query and get results */
513
+ lattice_error lattice_query_execute(
514
+ lattice_query* query,
515
+ lattice_txn* txn,
516
+ lattice_result** result_out
517
+ );
518
+
519
+ /* Last query diagnostics for a prepared query handle.
520
+ * Populated when lattice_query_execute() fails.
521
+ * Cleared automatically before each execute call.
522
+ */
523
+ lattice_query_error_stage lattice_query_last_error_stage(lattice_query* query);
524
+ const char* lattice_query_last_error_message(lattice_query* query);
525
+ const char* lattice_query_last_error_code(lattice_query* query); /* nullable */
526
+ bool lattice_query_last_error_has_location(lattice_query* query);
527
+ uint32_t lattice_query_last_error_line(lattice_query* query); /* 1-based, 0 if unavailable */
528
+ uint32_t lattice_query_last_error_column(lattice_query* query); /* 1-based, 0 if unavailable */
529
+ uint32_t lattice_query_last_error_length(lattice_query* query); /* token span length, 0 if unavailable */
530
+
531
+ /* Free a prepared query (call after done with results) */
532
+ void lattice_query_free(lattice_query* query);
533
+
534
+ /*
535
+ * Result operations
536
+ */
537
+
538
+ /* Get next row from result set */
539
+ bool lattice_result_next(lattice_result* result);
540
+
541
+ /* Get column count */
542
+ uint32_t lattice_result_column_count(lattice_result* result);
543
+
544
+ /* Get column name */
545
+ const char* lattice_result_column_name(lattice_result* result, uint32_t index);
546
+
547
+ /* Get column value */
548
+ lattice_error lattice_result_get(
549
+ lattice_result* result,
550
+ uint32_t index,
551
+ lattice_value* value_out
552
+ );
553
+
554
+ /* Free a result set */
555
+ void lattice_result_free(lattice_result* result);
556
+
557
+ /*
558
+ * Query cache operations
559
+ */
560
+
561
+ /* Clear the query cache */
562
+ lattice_error lattice_query_cache_clear(lattice_database* db);
563
+
564
+ /* Get query cache statistics */
565
+ lattice_error lattice_query_cache_stats(
566
+ lattice_database* db,
567
+ uint32_t* entries_out,
568
+ uint64_t* hits_out,
569
+ uint64_t* misses_out
570
+ );
571
+
572
+ /*
573
+ * Utility functions
574
+ */
575
+
576
+ /* Get version string */
577
+ const char* lattice_version(void);
578
+
579
+ /* Get last error message */
580
+ const char* lattice_error_message(lattice_error code);
581
+
582
+ #ifdef __cplusplus
583
+ }
584
+ #endif
585
+
586
+ #endif /* LATTICE_H */
Binary file
Binary file
Binary file
package/package.json CHANGED
@@ -1,12 +1,13 @@
1
1
  {
2
2
  "name": "@hajewski/latticedb",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "TypeScript bindings for Lattice embedded knowledge graph database",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "scripts": {
8
8
  "build": "tsc",
9
9
  "test": "jest",
10
+ "test:coverage": "jest --coverage",
10
11
  "lint": "eslint src --ext .ts",
11
12
  "clean": "rm -rf dist",
12
13
  "prepare": "npm run build",
@@ -24,13 +25,13 @@
24
25
  "hnsw",
25
26
  "bm25"
26
27
  ],
27
- "author": "Jeff Hajewski <jeff@latticedb.dev>",
28
+ "author": "Jeff Hajewski <jeff.hajewski@gmail.com>",
28
29
  "license": "MIT",
29
30
  "repository": {
30
31
  "type": "git",
31
32
  "url": "https://github.com/jeffhajewski/latticedb"
32
33
  },
33
- "homepage": "https://github.com/jeffhajewski/latticedb#readme",
34
+ "homepage": "https://latticedb.org",
34
35
  "bugs": {
35
36
  "url": "https://github.com/jeffhajewski/latticedb/issues"
36
37
  },