@framers/agentos 0.1.116 → 0.1.117

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.
Files changed (5) hide show
  1. package/dist/rag/utils/vectorMath.d.ts +92 -0
  2. package/dist/rag/utils/vectorMath.d.ts.map +1 -0
  3. package/dist/rag/utils/vectorMath.js +146 -0
  4. package/dist/rag/utils/vectorMath.js.map +1 -0
  5. package/package.json +1 -1
package/dist/rag/utils/vectorMath.d.ts ADDED
@@ -0,0 +1,92 @@
1
+ /**
2
+ * @fileoverview Shared vector distance and similarity functions.
3
+ * @module rag/utils/vectorMath
4
+ *
5
+ * Single source of truth for vector math across the entire AgentOS codebase.
6
+ * Replaces 6+ duplicate implementations scattered across SqlVectorStore,
7
+ * InMemoryVectorStore, KnowledgeGraph, SqliteKnowledgeGraph,
8
+ * ConsolidationLoop, ProspectiveMemoryManager, and ChunkingEngine.
9
+ *
10
+ * Optimized for hot-loop performance:
11
+ * - Single-pass accumulation (dot, normA, normB computed together)
12
+ * - Early bail on dimension mismatch or zero-length
13
+ * - Accepts both number[] and Float32Array for zero-copy interop with binary blobs
14
+ */
15
+ /** Accepts standard arrays or typed arrays for zero-copy binary blob interop. */
16
+ export type VectorLike = number[] | Float32Array | Float64Array;
17
+ /**
18
+ * Compute cosine similarity between two vectors.
19
+ *
20
+ * Returns a value in [-1, 1]:
21
+ * - `1.0` = identical direction
22
+ * - `0.0` = orthogonal (no linear similarity)
23
+ * - `-1.0` = opposite direction
24
+ *
25
+ * Returns `0` for empty arrays, mismatched dimensions, or zero-magnitude vectors.
26
+ *
27
+ * @param a - First vector.
28
+ * @param b - Second vector (must have same length as `a`).
29
+ * @returns Cosine similarity in [-1, 1].
30
+ */
31
+ export declare function cosineSimilarity(a: VectorLike, b: VectorLike): number;
32
+ /**
33
+ * Compute the dot product (inner product) of two vectors.
34
+ *
35
+ * Higher values indicate more similar vectors (for normalized vectors,
36
+ * dot product equals cosine similarity).
37
+ *
38
+ * Returns `0` for empty arrays or mismatched dimensions.
39
+ *
40
+ * @param a - First vector.
41
+ * @param b - Second vector (must have same length as `a`).
42
+ * @returns The scalar dot product.
43
+ */
44
+ export declare function dotProduct(a: VectorLike, b: VectorLike): number;
45
+ /**
46
+ * Compute the Euclidean (L2) distance between two vectors.
47
+ *
48
+ * Lower values indicate more similar vectors:
49
+ * - `0.0` = identical vectors
50
+ * - Increases with divergence
51
+ *
52
+ * Returns `0` for empty arrays or mismatched dimensions.
53
+ *
54
+ * @param a - First vector.
55
+ * @param b - Second vector (must have same length as `a`).
56
+ * @returns Non-negative L2 distance.
57
+ */
58
+ export declare function euclideanDistance(a: VectorLike, b: VectorLike): number;
59
+ /**
60
+ * Serialize a number[] embedding to a compact Float32Array Buffer.
61
+ * ~50% smaller than JSON.stringify and avoids JSON.parse on read.
62
+ *
63
+ * @param embedding - The embedding vector.
64
+ * @returns Buffer containing raw float32 bytes.
65
+ */
66
+ export declare function embeddingToBlob(embedding: number[]): Buffer;
67
+ /**
68
+ * Deserialize a Buffer back to number[].
69
+ * Creates a Float32Array view over the buffer without copying.
70
+ *
71
+ * @param blob - Buffer containing raw float32 bytes.
72
+ * @returns The embedding as a number array.
73
+ */
74
+ export declare function blobToEmbedding(blob: Buffer): number[];
75
+ /**
76
+ * Create a Float32Array view over a Buffer without copying.
77
+ * Use this when you want to pass directly to distance functions
78
+ * without converting to number[] first (avoids allocation).
79
+ *
80
+ * @param blob - Buffer containing raw float32 bytes.
81
+ * @returns Float32Array view.
82
+ */
83
+ export declare function blobToFloat32(blob: Buffer): Float32Array;
84
+ /**
85
+ * Detect whether a stored blob is legacy JSON text or binary format.
86
+ * JSON blobs start with `[` (0x5B); binary blobs start with raw float bytes.
87
+ *
88
+ * @param blob - The stored embedding data.
89
+ * @returns True if the blob is legacy JSON-encoded text.
90
+ */
91
+ export declare function isLegacyJsonBlob(blob: Buffer | string): boolean;
92
+ //# sourceMappingURL=vectorMath.d.ts.map
package/dist/rag/utils/vectorMath.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vectorMath.d.ts","sourceRoot":"","sources":["../../../src/rag/utils/vectorMath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY,CAAC;AAMhE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAiBrE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAQ/D;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAStE;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOtD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAMxD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAG/D"}
package/dist/rag/utils/vectorMath.js ADDED
@@ -0,0 +1,146 @@
1
+ /**
2
+ * @fileoverview Shared vector distance and similarity functions.
3
+ * @module rag/utils/vectorMath
4
+ *
5
+ * Single source of truth for vector math across the entire AgentOS codebase.
6
+ * Replaces 6+ duplicate implementations scattered across SqlVectorStore,
7
+ * InMemoryVectorStore, KnowledgeGraph, SqliteKnowledgeGraph,
8
+ * ConsolidationLoop, ProspectiveMemoryManager, and ChunkingEngine.
9
+ *
10
+ * Optimized for hot-loop performance:
11
+ * - Single-pass accumulation (dot, normA, normB computed together)
12
+ * - Early bail on dimension mismatch or zero-length
13
+ * - Accepts both number[] and Float32Array for zero-copy interop with binary blobs
14
+ */
15
+ // ---------------------------------------------------------------------------
16
+ // Cosine Similarity
17
+ // ---------------------------------------------------------------------------
18
+ /**
19
+ * Compute cosine similarity between two vectors.
20
+ *
21
+ * Returns a value in [-1, 1]:
22
+ * - `1.0` = identical direction
23
+ * - `0.0` = orthogonal (no linear similarity)
24
+ * - `-1.0` = opposite direction
25
+ *
26
+ * Returns `0` for empty arrays, mismatched dimensions, or zero-magnitude vectors.
27
+ *
28
+ * @param a - First vector.
29
+ * @param b - Second vector (must have same length as `a`).
30
+ * @returns Cosine similarity in [-1, 1].
31
+ */
32
+ export function cosineSimilarity(a, b) {
33
+ if (a.length !== b.length || a.length === 0)
34
+ return 0;
35
+ let dot = 0;
36
+ let normA = 0;
37
+ let normB = 0;
38
+ for (let i = 0; i < a.length; i++) {
39
+ const ai = a[i];
40
+ const bi = b[i];
41
+ dot += ai * bi;
42
+ normA += ai * ai;
43
+ normB += bi * bi;
44
+ }
45
+ if (normA === 0 || normB === 0)
46
+ return 0;
47
+ return dot / (Math.sqrt(normA) * Math.sqrt(normB));
48
+ }
49
+ // ---------------------------------------------------------------------------
50
+ // Dot Product
51
+ // ---------------------------------------------------------------------------
52
+ /**
53
+ * Compute the dot product (inner product) of two vectors.
54
+ *
55
+ * Higher values indicate more similar vectors (for normalized vectors,
56
+ * dot product equals cosine similarity).
57
+ *
58
+ * Returns `0` for empty arrays or mismatched dimensions.
59
+ *
60
+ * @param a - First vector.
61
+ * @param b - Second vector (must have same length as `a`).
62
+ * @returns The scalar dot product.
63
+ */
64
+ export function dotProduct(a, b) {
65
+ if (a.length !== b.length || a.length === 0)
66
+ return 0;
67
+ let sum = 0;
68
+ for (let i = 0; i < a.length; i++) {
69
+ sum += a[i] * b[i];
70
+ }
71
+ return sum;
72
+ }
73
+ // ---------------------------------------------------------------------------
74
+ // Euclidean Distance
75
+ // ---------------------------------------------------------------------------
76
+ /**
77
+ * Compute the Euclidean (L2) distance between two vectors.
78
+ *
79
+ * Lower values indicate more similar vectors:
80
+ * - `0.0` = identical vectors
81
+ * - Increases with divergence
82
+ *
83
+ * Returns `0` for empty arrays or mismatched dimensions.
84
+ *
85
+ * @param a - First vector.
86
+ * @param b - Second vector (must have same length as `a`).
87
+ * @returns Non-negative L2 distance.
88
+ */
89
+ export function euclideanDistance(a, b) {
90
+ if (a.length !== b.length || a.length === 0)
91
+ return 0;
92
+ let sum = 0;
93
+ for (let i = 0; i < a.length; i++) {
94
+ const diff = a[i] - b[i];
95
+ sum += diff * diff;
96
+ }
97
+ return Math.sqrt(sum);
98
+ }
99
+ // ---------------------------------------------------------------------------
100
+ // Binary blob helpers
101
+ // ---------------------------------------------------------------------------
102
+ /**
103
+ * Serialize a number[] embedding to a compact Float32Array Buffer.
104
+ * ~50% smaller than JSON.stringify and avoids JSON.parse on read.
105
+ *
106
+ * @param embedding - The embedding vector.
107
+ * @returns Buffer containing raw float32 bytes.
108
+ */
109
+ export function embeddingToBlob(embedding) {
110
+ return Buffer.from(new Float32Array(embedding).buffer);
111
+ }
112
+ /**
113
+ * Deserialize a Buffer back to number[].
114
+ * Creates a Float32Array view over the buffer without copying.
115
+ *
116
+ * @param blob - Buffer containing raw float32 bytes.
117
+ * @returns The embedding as a number array.
118
+ */
119
+ export function blobToEmbedding(blob) {
120
+ const f32 = new Float32Array(blob.buffer, blob.byteOffset, blob.byteLength / 4);
121
+ return Array.from(f32);
122
+ }
123
+ /**
124
+ * Create a Float32Array view over a Buffer without copying.
125
+ * Use this when you want to pass directly to distance functions
126
+ * without converting to number[] first (avoids allocation).
127
+ *
128
+ * @param blob - Buffer containing raw float32 bytes.
129
+ * @returns Float32Array view.
130
+ */
131
+ export function blobToFloat32(blob) {
132
+ return new Float32Array(blob.buffer, blob.byteOffset, blob.byteLength / 4);
133
+ }
134
+ /**
135
+ * Detect whether a stored blob is legacy JSON text or binary format.
136
+ * JSON blobs start with `[` (0x5B); binary blobs start with raw float bytes.
137
+ *
138
+ * @param blob - The stored embedding data.
139
+ * @returns True if the blob is legacy JSON-encoded text.
140
+ */
141
+ export function isLegacyJsonBlob(blob) {
142
+ if (typeof blob === 'string')
143
+ return true;
144
+ return blob.length > 0 && blob[0] === 0x5B; // '[' character
145
+ }
146
+ //# sourceMappingURL=vectorMath.js.map
package/dist/rag/utils/vectorMath.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vectorMath.js","sourceRoot":"","sources":["../../../src/rag/utils/vectorMath.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@framers/agentos",
3
- "version": "0.1.116",
3
+ "version": "0.1.117",
4
4
  "description": "Modular AgentOS orchestration library",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",