@usex/ternava 0.0.0-stage → 0.1.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/src/index.mjs ADDED
@@ -0,0 +1,80 @@
1
+ // ternava — public ESM entry. Wraps the WASM engine.
2
+ //
3
+ // The compiled engine lives in ../pkg-node/ as wasm-pack's nodejs-target output
4
+ // (CommonJS). We bridge to it via createRequire — this keeps a single WASM
5
+ // artifact and exposes both CJS (src/index.js) and ESM (this file) consumers
6
+ // from the same package, routed via the "exports" field in package.json.
7
+
8
+ import { createRequire } from 'node:module';
9
+
10
+ const require = createRequire(import.meta.url);
11
+ const { embed: _embed, config_summary } = require('../pkg-node/tern_engine.js');
12
+
13
+ export class TernError extends Error {
14
+ constructor(message, code) {
15
+ super(message);
16
+ this.name = 'TernError';
17
+ this.code = code;
18
+ }
19
+ }
20
+
21
+ /**
22
+ * Embed text → 384-dim L2-normalized Float32Array.
23
+ * Pure CPU inference via WASM. Synchronous. No network calls.
24
+ *
25
+ * Input is tokenized via BERT WordPiece and truncated to 128 tokens
26
+ * (~95 English words). Longer text is silently truncated.
27
+ */
28
+ export function embed(text) {
29
+ if (typeof text !== 'string') {
30
+ throw new TernError(
31
+ 'embed(text): text must be a string',
32
+ 'INVALID_INPUT',
33
+ );
34
+ }
35
+ return _embed(text);
36
+ }
37
+
38
+ /**
39
+ * Cosine similarity between two embeddings.
40
+ *
41
+ * Since ternava embeddings are L2-normalized, this reduces to a dot product
42
+ * — no per-call sqrt or division.
43
+ */
44
+ export function cosineSim(a, b) {
45
+ if (a.length !== b.length) {
46
+ throw new TernError(
47
+ `vector length mismatch: ${a.length} vs ${b.length}`,
48
+ 'DIM_MISMATCH',
49
+ );
50
+ }
51
+ let dot = 0;
52
+ const len = a.length;
53
+ for (let i = 0; i < len; i++) dot += a[i] * b[i];
54
+ return dot;
55
+ }
56
+
57
+ /**
58
+ * Convenience: embed query + each corpus item, return top-K matches sorted
59
+ * descending by similarity.
60
+ *
61
+ * For repeated searches over the same corpus, embed it once upfront and call
62
+ * cosineSim() yourself — see the README "Reuse embeddings" pattern.
63
+ */
64
+ export function similar(query, corpus, opts = {}) {
65
+ const topK = opts.topK ?? 5;
66
+ const q = embed(query);
67
+ return corpus
68
+ .map((text) => ({ text, sim: cosineSim(q, embed(text)) }))
69
+ .sort((a, b) => b.sim - a.sim)
70
+ .slice(0, topK);
71
+ }
72
+
73
+ /**
74
+ * Debug helper: returns a string describing the loaded engine's configuration
75
+ * (format version, embedding format, dimensions, vocab size). Useful for
76
+ * confirming which build of the engine is actually loaded.
77
+ */
78
+ export function engineInfo() {
79
+ return config_summary();
80
+ }