@defai.digital/semantic-context 13.4.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/LICENSE +38 -0
- package/dist/embedding-service.d.ts +66 -0
- package/dist/embedding-service.d.ts.map +1 -0
- package/dist/embedding-service.js +265 -0
- package/dist/embedding-service.js.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +16 -0
- package/dist/index.js.map +1 -0
- package/dist/semantic-manager.d.ts +30 -0
- package/dist/semantic-manager.d.ts.map +1 -0
- package/dist/semantic-manager.js +186 -0
- package/dist/semantic-manager.js.map +1 -0
- package/dist/similarity.d.ts +89 -0
- package/dist/similarity.d.ts.map +1 -0
- package/dist/similarity.js +216 -0
- package/dist/similarity.js.map +1 -0
- package/dist/types.d.ts +236 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +258 -0
- package/dist/types.js.map +1 -0
- package/package.json +48 -0
- package/src/embedding-service.ts +323 -0
- package/src/index.ts +56 -0
- package/src/semantic-manager.ts +246 -0
- package/src/similarity.ts +265 -0
- package/src/types.ts +561 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
Business Source License 1.1
|
|
2
|
+
|
|
3
|
+
Parameters
|
|
4
|
+
|
|
5
|
+
Licensor: DEFAI Private Limited
|
|
6
|
+
Licensed Work: AutomatosX
|
|
7
|
+
The Licensed Work is (c) 2024-2025 DEFAI Private Limited
|
|
8
|
+
Additional Use Grant: You may make production use of the Licensed Work,
|
|
9
|
+
provided that your organization has less than US$2,000,000 in annual gross
|
|
10
|
+
revenue in the prior fiscal year. "Production use" means use in a live
|
|
11
|
+
production environment to support business or operational activities for end
|
|
12
|
+
users.
|
|
13
|
+
Change Date: Four years after the release date of the Licensed Work version
|
|
14
|
+
Change License: Apache License, Version 2.0
|
|
15
|
+
|
|
16
|
+
Terms
|
|
17
|
+
|
|
18
|
+
The Licensor hereby grants you the right to copy, modify, create derivative
|
|
19
|
+
works, redistribute, and make non-production use of the Licensed Work. The
|
|
20
|
+
Licensor may make an Additional Use Grant, above, permitting other uses of the
|
|
21
|
+
Licensed Work. The rights granted to you under this license are subject to the
|
|
22
|
+
following condition.
|
|
23
|
+
|
|
24
|
+
If you make any use of the Licensed Work, you must ensure that the Licensed
|
|
25
|
+
Work, or any modified version of it, carries prominent notices stating that
|
|
26
|
+
you have modified the Licensed Work.
|
|
27
|
+
|
|
28
|
+
This license does not grant permission to use the Licensor's trademarks.
|
|
29
|
+
|
|
30
|
+
The Licensed Work is provided "as is", without warranty of any kind, express
|
|
31
|
+
or implied, including but not limited to the warranties of merchantability,
|
|
32
|
+
fitness for a particular purpose and noninfringement. In no event shall the
|
|
33
|
+
Licensor be liable for any claim, damages or other liability, whether in an
|
|
34
|
+
action of contract, tort or otherwise, arising from, out of or in connection
|
|
35
|
+
with the Licensed Work or the use or other dealings in the Licensed Work.
|
|
36
|
+
|
|
37
|
+
On the Change Date, the Licensed Work will be made available under the Change
|
|
38
|
+
License.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Embedding Service
|
|
3
|
+
*
|
|
4
|
+
* Provides text embedding computation with a local TF-IDF fallback.
|
|
5
|
+
* Can be extended with external providers (OpenAI, Cohere, etc.)
|
|
6
|
+
*
|
|
7
|
+
* Invariants:
|
|
8
|
+
* - INV-SEM-001: Embeddings computed and cached
|
|
9
|
+
* - INV-SEM-200: Consistent dimension within namespace
|
|
10
|
+
*/
|
|
11
|
+
import type { EmbeddingPort, EmbeddingRequest, EmbeddingResult } from './types.js';
|
|
12
|
+
import type { EmbeddingConfig } from '@defai.digital/contracts';
|
|
13
|
+
/**
|
|
14
|
+
* Create TF-IDF based embedding
|
|
15
|
+
*
|
|
16
|
+
* This is a simple local embedding that:
|
|
17
|
+
* 1. Tokenizes text
|
|
18
|
+
* 2. Computes term frequency
|
|
19
|
+
* 3. Hashes terms to fixed dimension
|
|
20
|
+
* 4. Normalizes to unit vector
|
|
21
|
+
*/
|
|
22
|
+
export declare function createTFIDFEmbedding(text: string, dimension: number): number[];
|
|
23
|
+
/**
|
|
24
|
+
* Batch create TF-IDF embeddings with IDF computation
|
|
25
|
+
*/
|
|
26
|
+
export declare function createTFIDFEmbeddingBatch(texts: string[], dimension: number): number[][];
|
|
27
|
+
/**
|
|
28
|
+
* Local embedding provider using TF-IDF
|
|
29
|
+
*/
|
|
30
|
+
export declare class LocalEmbeddingProvider implements EmbeddingPort {
|
|
31
|
+
private config;
|
|
32
|
+
constructor(config?: Partial<EmbeddingConfig>);
|
|
33
|
+
embed(request: EmbeddingRequest): Promise<EmbeddingResult>;
|
|
34
|
+
embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
|
|
35
|
+
getConfig(): EmbeddingConfig;
|
|
36
|
+
isAvailable(): Promise<boolean>;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Create embedding provider based on configuration
|
|
40
|
+
*/
|
|
41
|
+
export declare function createEmbeddingProvider(config?: Partial<EmbeddingConfig>): EmbeddingPort;
|
|
42
|
+
/**
|
|
43
|
+
* Cached embedding provider wrapper
|
|
44
|
+
*/
|
|
45
|
+
export declare class CachedEmbeddingProvider implements EmbeddingPort {
|
|
46
|
+
private cache;
|
|
47
|
+
private delegate;
|
|
48
|
+
private maxCacheSize;
|
|
49
|
+
constructor(delegate: EmbeddingPort, maxCacheSize?: number);
|
|
50
|
+
embed(request: EmbeddingRequest): Promise<EmbeddingResult>;
|
|
51
|
+
embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
|
|
52
|
+
getConfig(): EmbeddingConfig;
|
|
53
|
+
isAvailable(): Promise<boolean>;
|
|
54
|
+
/**
|
|
55
|
+
* Clear the cache
|
|
56
|
+
*/
|
|
57
|
+
clearCache(): void;
|
|
58
|
+
/**
|
|
59
|
+
* Get cache statistics
|
|
60
|
+
*/
|
|
61
|
+
getCacheStats(): {
|
|
62
|
+
size: number;
|
|
63
|
+
maxSize: number;
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
//# sourceMappingURL=embedding-service.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"embedding-service.d.ts","sourceRoot":"","sources":["../src/embedding-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AA+ChE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAiB9E;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAuCxF;AAMD;;GAEG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAC1D,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IAWvC,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAgB1D,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAsB7D,SAAS,IAAI,eAAe;IAItB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAGtC;AAMD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,aAAa,CAexF;AAED;;GAEG;AACH,qBAAa,uBAAwB,YAAW,aAAa;IAC3D,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,YAAY,CAAS;gBAEjB,QAAQ,EAAE,aAAa,EAAE,YAAY,SAAQ;IAKnD,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAsB1D,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAoC7D,SAAS,IAAI,eAAe;IAItB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAMnD"}
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Embedding Service
|
|
3
|
+
*
|
|
4
|
+
* Provides text embedding computation with a local TF-IDF fallback.
|
|
5
|
+
* Can be extended with external providers (OpenAI, Cohere, etc.)
|
|
6
|
+
*
|
|
7
|
+
* Invariants:
|
|
8
|
+
* - INV-SEM-001: Embeddings computed and cached
|
|
9
|
+
* - INV-SEM-200: Consistent dimension within namespace
|
|
10
|
+
*/
|
|
11
|
+
import { normalizeVector } from './similarity.js';
|
|
12
|
+
// ============================================================================
|
|
13
|
+
// Local TF-IDF Embedding
|
|
14
|
+
// ============================================================================
|
|
15
|
+
/**
|
|
16
|
+
* Simple tokenizer that splits text into tokens
|
|
17
|
+
*/
|
|
18
|
+
function tokenize(text) {
|
|
19
|
+
return text
|
|
20
|
+
.toLowerCase()
|
|
21
|
+
.replace(/[^\w\s]/g, ' ')
|
|
22
|
+
.split(/\s+/)
|
|
23
|
+
.filter((t) => t.length > 1);
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Compute term frequency for tokens
|
|
27
|
+
*/
|
|
28
|
+
function computeTF(tokens) {
|
|
29
|
+
const tf = new Map();
|
|
30
|
+
for (const token of tokens) {
|
|
31
|
+
tf.set(token, (tf.get(token) ?? 0) + 1);
|
|
32
|
+
}
|
|
33
|
+
// Normalize by total tokens
|
|
34
|
+
const total = tokens.length;
|
|
35
|
+
for (const [term, count] of tf) {
|
|
36
|
+
tf.set(term, count / total);
|
|
37
|
+
}
|
|
38
|
+
return tf;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Simple hash function for consistent dimension mapping
|
|
42
|
+
*/
|
|
43
|
+
function hashString(str, maxDim) {
|
|
44
|
+
let hash = 0;
|
|
45
|
+
for (let i = 0; i < str.length; i++) {
|
|
46
|
+
const char = str.charCodeAt(i);
|
|
47
|
+
hash = ((hash << 5) - hash) + char;
|
|
48
|
+
hash = hash & hash; // Convert to 32bit integer
|
|
49
|
+
}
|
|
50
|
+
return Math.abs(hash) % maxDim;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Create TF-IDF based embedding
|
|
54
|
+
*
|
|
55
|
+
* This is a simple local embedding that:
|
|
56
|
+
* 1. Tokenizes text
|
|
57
|
+
* 2. Computes term frequency
|
|
58
|
+
* 3. Hashes terms to fixed dimension
|
|
59
|
+
* 4. Normalizes to unit vector
|
|
60
|
+
*/
|
|
61
|
+
export function createTFIDFEmbedding(text, dimension) {
|
|
62
|
+
const tokens = tokenize(text);
|
|
63
|
+
const tf = computeTF(tokens);
|
|
64
|
+
// Create sparse vector and hash to fixed dimension
|
|
65
|
+
const embedding = new Array(dimension).fill(0);
|
|
66
|
+
for (const [term, freq] of tf) {
|
|
67
|
+
// Hash term to dimension index
|
|
68
|
+
const index = hashString(term, dimension);
|
|
69
|
+
// Add frequency (with sign based on secondary hash for better distribution)
|
|
70
|
+
const sign = hashString(term + '_sign', 2) === 0 ? 1 : -1;
|
|
71
|
+
embedding[index] += freq * sign;
|
|
72
|
+
}
|
|
73
|
+
// Normalize to unit vector
|
|
74
|
+
return normalizeVector(embedding);
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Batch create TF-IDF embeddings with IDF computation
|
|
78
|
+
*/
|
|
79
|
+
export function createTFIDFEmbeddingBatch(texts, dimension) {
|
|
80
|
+
// Compute document frequency for IDF
|
|
81
|
+
const docFreq = new Map();
|
|
82
|
+
const allTokens = [];
|
|
83
|
+
for (const text of texts) {
|
|
84
|
+
const tokens = tokenize(text);
|
|
85
|
+
const uniqueTokens = new Set(tokens);
|
|
86
|
+
allTokens.push(tokens);
|
|
87
|
+
for (const token of uniqueTokens) {
|
|
88
|
+
docFreq.set(token, (docFreq.get(token) ?? 0) + 1);
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
const numDocs = texts.length;
|
|
92
|
+
const embeddings = [];
|
|
93
|
+
for (let i = 0; i < texts.length; i++) {
|
|
94
|
+
const tokens = allTokens[i];
|
|
95
|
+
const tf = computeTF(tokens);
|
|
96
|
+
const embedding = new Array(dimension).fill(0);
|
|
97
|
+
for (const [term, freq] of tf) {
|
|
98
|
+
// Compute IDF: log(N / df)
|
|
99
|
+
const df = docFreq.get(term) ?? 1;
|
|
100
|
+
const idf = Math.log(numDocs / df);
|
|
101
|
+
const tfidf = freq * idf;
|
|
102
|
+
// Hash to dimension
|
|
103
|
+
const index = hashString(term, dimension);
|
|
104
|
+
const sign = hashString(term + '_sign', 2) === 0 ? 1 : -1;
|
|
105
|
+
embedding[index] += tfidf * sign;
|
|
106
|
+
}
|
|
107
|
+
embeddings.push(normalizeVector(embedding));
|
|
108
|
+
}
|
|
109
|
+
return embeddings;
|
|
110
|
+
}
|
|
111
|
+
// ============================================================================
|
|
112
|
+
// Local Embedding Provider
|
|
113
|
+
// ============================================================================
|
|
114
|
+
/**
|
|
115
|
+
* Local embedding provider using TF-IDF
|
|
116
|
+
*/
|
|
117
|
+
export class LocalEmbeddingProvider {
|
|
118
|
+
config;
|
|
119
|
+
constructor(config) {
|
|
120
|
+
this.config = {
|
|
121
|
+
provider: 'local',
|
|
122
|
+
model: 'tfidf',
|
|
123
|
+
dimension: 384,
|
|
124
|
+
batchSize: 32,
|
|
125
|
+
cacheEnabled: true,
|
|
126
|
+
...config,
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
async embed(request) {
|
|
130
|
+
const startTime = Date.now();
|
|
131
|
+
const embedding = createTFIDFEmbedding(request.text, this.config.dimension);
|
|
132
|
+
return {
|
|
133
|
+
embedding,
|
|
134
|
+
model: request.model ?? this.config.model,
|
|
135
|
+
dimension: this.config.dimension,
|
|
136
|
+
durationMs: Date.now() - startTime,
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
async embedBatch(texts) {
|
|
140
|
+
const startTime = Date.now();
|
|
141
|
+
// Process in batches
|
|
142
|
+
const results = [];
|
|
143
|
+
for (let i = 0; i < texts.length; i += this.config.batchSize) {
|
|
144
|
+
const batch = texts.slice(i, i + this.config.batchSize);
|
|
145
|
+
const embeddings = createTFIDFEmbeddingBatch(batch, this.config.dimension);
|
|
146
|
+
for (const embedding of embeddings) {
|
|
147
|
+
results.push({
|
|
148
|
+
embedding,
|
|
149
|
+
model: this.config.model,
|
|
150
|
+
dimension: this.config.dimension,
|
|
151
|
+
durationMs: Date.now() - startTime,
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
return results;
|
|
156
|
+
}
|
|
157
|
+
getConfig() {
|
|
158
|
+
return { ...this.config };
|
|
159
|
+
}
|
|
160
|
+
async isAvailable() {
|
|
161
|
+
return true; // Local provider is always available
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
// ============================================================================
|
|
165
|
+
// Embedding Service Factory
|
|
166
|
+
// ============================================================================
|
|
167
|
+
/**
|
|
168
|
+
* Create embedding provider based on configuration
|
|
169
|
+
*/
|
|
170
|
+
export function createEmbeddingProvider(config) {
|
|
171
|
+
const provider = config?.provider ?? 'local';
|
|
172
|
+
switch (provider) {
|
|
173
|
+
case 'local':
|
|
174
|
+
return new LocalEmbeddingProvider(config);
|
|
175
|
+
// Future: Add OpenAI, Cohere, Voyage providers here
|
|
176
|
+
// case 'openai':
|
|
177
|
+
// return new OpenAIEmbeddingProvider(config);
|
|
178
|
+
default:
|
|
179
|
+
// Fall back to local
|
|
180
|
+
return new LocalEmbeddingProvider(config);
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Cached embedding provider wrapper
|
|
185
|
+
*/
|
|
186
|
+
export class CachedEmbeddingProvider {
|
|
187
|
+
cache = new Map();
|
|
188
|
+
delegate;
|
|
189
|
+
maxCacheSize;
|
|
190
|
+
constructor(delegate, maxCacheSize = 10000) {
|
|
191
|
+
this.delegate = delegate;
|
|
192
|
+
this.maxCacheSize = maxCacheSize;
|
|
193
|
+
}
|
|
194
|
+
async embed(request) {
|
|
195
|
+
const cacheKey = `${request.model ?? 'default'}:${request.text}`;
|
|
196
|
+
// Check cache
|
|
197
|
+
const cached = this.cache.get(cacheKey);
|
|
198
|
+
if (cached) {
|
|
199
|
+
return { ...cached, durationMs: 0 };
|
|
200
|
+
}
|
|
201
|
+
// Compute and cache
|
|
202
|
+
const result = await this.delegate.embed(request);
|
|
203
|
+
// Evict old entries if cache is full
|
|
204
|
+
if (this.cache.size >= this.maxCacheSize) {
|
|
205
|
+
const firstKey = this.cache.keys().next().value;
|
|
206
|
+
if (firstKey)
|
|
207
|
+
this.cache.delete(firstKey);
|
|
208
|
+
}
|
|
209
|
+
this.cache.set(cacheKey, result);
|
|
210
|
+
return result;
|
|
211
|
+
}
|
|
212
|
+
async embedBatch(texts) {
|
|
213
|
+
// Check which texts need computation
|
|
214
|
+
const model = this.getConfig().model;
|
|
215
|
+
const toCompute = [];
|
|
216
|
+
const results = new Array(texts.length).fill(null);
|
|
217
|
+
for (let i = 0; i < texts.length; i++) {
|
|
218
|
+
const cacheKey = `${model}:${texts[i]}`;
|
|
219
|
+
const cached = this.cache.get(cacheKey);
|
|
220
|
+
if (cached) {
|
|
221
|
+
results[i] = { ...cached, durationMs: 0 };
|
|
222
|
+
}
|
|
223
|
+
else {
|
|
224
|
+
toCompute.push({ index: i, text: texts[i] });
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
// Compute missing embeddings
|
|
228
|
+
if (toCompute.length > 0) {
|
|
229
|
+
const computed = await this.delegate.embedBatch(toCompute.map((t) => t.text));
|
|
230
|
+
for (let i = 0; i < toCompute.length; i++) {
|
|
231
|
+
const { index, text } = toCompute[i];
|
|
232
|
+
const result = computed[i];
|
|
233
|
+
results[index] = result;
|
|
234
|
+
// Cache
|
|
235
|
+
const cacheKey = `${model}:${text}`;
|
|
236
|
+
if (this.cache.size < this.maxCacheSize) {
|
|
237
|
+
this.cache.set(cacheKey, result);
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
return results;
|
|
242
|
+
}
|
|
243
|
+
getConfig() {
|
|
244
|
+
return this.delegate.getConfig();
|
|
245
|
+
}
|
|
246
|
+
async isAvailable() {
|
|
247
|
+
return this.delegate.isAvailable();
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Clear the cache
|
|
251
|
+
*/
|
|
252
|
+
clearCache() {
|
|
253
|
+
this.cache.clear();
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* Get cache statistics
|
|
257
|
+
*/
|
|
258
|
+
getCacheStats() {
|
|
259
|
+
return {
|
|
260
|
+
size: this.cache.size,
|
|
261
|
+
maxSize: this.maxCacheSize,
|
|
262
|
+
};
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
//# sourceMappingURL=embedding-service.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"embedding-service.js","sourceRoot":"","sources":["../src/embedding-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;GAEG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI;SACR,WAAW,EAAE;SACb,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,MAAgB;IACjC,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,4BAA4B;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/B,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,GAAW,EAAE,MAAc;IAC7C,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QACnC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,2BAA2B;IACjD,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,SAAiB;IAClE,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAE7B,mDAAmD;IACnD,MAAM,SAAS,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAE/C,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9B,+BAA+B;QAC/B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC1C,4EAA4E;QAC5E,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,SAAS,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,IAAI,CAAC;IAClC,CAAC;IAED,2BAA2B;IAC3B,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAe,EAAE,SAAiB;IAC1E,qCAAqC;IACrC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,SAAS,GAAe,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEvB,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC;IAC7B,MAAM,UAAU,GAAe,EAAE,CAAC;IAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QAC7B,MAAM,SAAS,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAE/C,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAC9B,2BAA2B;YAC3B,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;YACnC,MAAM,KAAK,GAAG,IAAI,GAAG,GAAG,CAAC;YAEzB,oBAAoB;YACpB,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAC1C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1D,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC;QACnC,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E;;GAEG;AACH,MAAM,OAAO,sBAAsB;IACzB,MAAM,CAAkB;IAEhC,YAAY,MAAiC;QAC3C,IAAI,CAAC,MAAM,GAAG;YACZ,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,OAAO;YACd,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,EAAE;YACb,YAAY,EAAE,IAAI;YAClB,GAAG,MAAM;SACV,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAyB;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,MAAM,SAAS,GAAG,oBAAoB,CACpC,OAAO,CAAC,IAAI,EACZ,IAAI,CAAC,MAAM,CAAC,SAAS,CACtB,CAAC;QAEF,OAAO;YACL,SAAS;YACT,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK;YACzC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;YAChC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SACnC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,qBAAqB;QACrB,MAAM,OAAO,GAAsB,EAAE,CAAC;QACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACxD,MAAM,UAAU,GAAG,yBAAyB,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAE3E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBACnC,OAAO,CAAC,IAAI,CAAC;oBACX,SAAS;oBACT,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;oBACxB,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;oBAChC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;iBACnC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,CAAC,CAAC,qCAAqC;IACpD,CAAC;CACF;AAED,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAiC;IACvE,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,OAAO,CAAC;IAE7C,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,OAAO;YACV,OAAO,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC;QAE5C,oDAAoD;QACpD,iBAAiB;QACjB,gDAAgD;QAEhD;YACE,qBAAqB;YACrB,OAAO,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,uBAAuB;IAC1B,KAAK,GAAiC,IAAI,GAAG,EAAE,CAAC;IAChD,QAAQ,CAAgB;IACxB,YAAY,CAAS;IAE7B,YAAY,QAAuB,EAAE,YAAY,GAAG,KAAK;QACvD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAyB;QACnC,MAAM,QAAQ,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAEjE,cAAc;QACd,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;QACtC,CAAC;QAED,oBAAoB;QACpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAElD,qCAAqC;QACrC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,QAAQ;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACjC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,qCAAqC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC;QACrC,MAAM,SAAS,GAAsC,EAAE,CAAC;QACxD,MAAM,OAAO,GAA+B,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE/E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,QAAQ,GAAG,GAAG,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxC,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;YAC5C,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QAED,6BAA6B;QAC7B,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAE9E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC1C,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,CAAC,CAAE,CAAC;gBACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;gBAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;gBAExB,QAAQ;gBACR,MAAM,QAAQ,GAAG,GAAG,KAAK,IAAI,IAAI,EAAE,CAAC;gBACpC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;oBACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,OAA4B,CAAC;IACtC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,OAAO,EAAE,IAAI,CAAC,YAAY;SAC3B,CAAC;IACJ,CAAC;CACF"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Semantic Context Domain
|
|
3
|
+
*
|
|
4
|
+
* Provides semantic search and vector-indexed storage.
|
|
5
|
+
*
|
|
6
|
+
* @packageDocumentation
|
|
7
|
+
*/
|
|
8
|
+
export type { EmbeddingPort, EmbeddingRequest, EmbeddingResult, SemanticStorePort, SemanticStoreStats, SemanticManager, SemanticManagerOptions, SimilarityMethod, SimilarityOptions, } from './types.js';
|
|
9
|
+
export { StubEmbeddingPort, InMemorySemanticStore } from './types.js';
|
|
10
|
+
export { cosineSimilarity, dotProductSimilarity, euclideanDistance, manhattanDistance, computeSimilarity, normalizeVector, vectorNorm, addVectors, subtractVectors, scaleVector, computeCentroid, findKNearest, filterByThreshold, DEFAULT_SIMILARITY_OPTIONS, } from './similarity.js';
|
|
11
|
+
export { LocalEmbeddingProvider, CachedEmbeddingProvider, createEmbeddingProvider, createTFIDFEmbedding, createTFIDFEmbeddingBatch, } from './embedding-service.js';
|
|
12
|
+
export { createSemanticManager, SemanticManagerError, } from './semantic-manager.js';
|
|
13
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGtE,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACX,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Semantic Context Domain
|
|
3
|
+
*
|
|
4
|
+
* Provides semantic search and vector-indexed storage.
|
|
5
|
+
*
|
|
6
|
+
* @packageDocumentation
|
|
7
|
+
*/
|
|
8
|
+
// Stub implementations for testing
|
|
9
|
+
export { StubEmbeddingPort, InMemorySemanticStore } from './types.js';
|
|
10
|
+
// Similarity utilities
|
|
11
|
+
export { cosineSimilarity, dotProductSimilarity, euclideanDistance, manhattanDistance, computeSimilarity, normalizeVector, vectorNorm, addVectors, subtractVectors, scaleVector, computeCentroid, findKNearest, filterByThreshold, DEFAULT_SIMILARITY_OPTIONS, } from './similarity.js';
|
|
12
|
+
// Embedding service
|
|
13
|
+
export { LocalEmbeddingProvider, CachedEmbeddingProvider, createEmbeddingProvider, createTFIDFEmbedding, createTFIDFEmbeddingBatch, } from './embedding-service.js';
|
|
14
|
+
// Semantic manager
|
|
15
|
+
export { createSemanticManager, SemanticManagerError, } from './semantic-manager.js';
|
|
16
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,mCAAmC;AACnC,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEtE,uBAAuB;AACvB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACX,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,oBAAoB;AACpB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAEhC,mBAAmB;AACnB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC"}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Semantic Manager
|
|
3
|
+
*
|
|
4
|
+
* High-level manager for semantic context storage and search.
|
|
5
|
+
* Combines embedding computation with storage.
|
|
6
|
+
*
|
|
7
|
+
* Invariants:
|
|
8
|
+
* - INV-SEM-001: Embeddings computed on store, cached until content changes
|
|
9
|
+
* - INV-SEM-002: Search results sorted by similarity descending
|
|
10
|
+
* - INV-SEM-003: Similarity scores normalized to [0, 1]
|
|
11
|
+
* - INV-SEM-004: Namespace isolation
|
|
12
|
+
*/
|
|
13
|
+
import type { SemanticManager, SemanticManagerOptions } from './types.js';
|
|
14
|
+
/**
|
|
15
|
+
* Error thrown by semantic manager
|
|
16
|
+
*/
|
|
17
|
+
export declare class SemanticManagerError extends Error {
|
|
18
|
+
readonly code: string;
|
|
19
|
+
readonly details?: Record<string, unknown> | undefined;
|
|
20
|
+
constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
|
|
21
|
+
static notFound(key: string, namespace: string): SemanticManagerError;
|
|
22
|
+
static embeddingFailed(message: string): SemanticManagerError;
|
|
23
|
+
static searchFailed(message: string): SemanticManagerError;
|
|
24
|
+
static dimensionMismatch(expected: number, actual: number): SemanticManagerError;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Creates a semantic manager
|
|
28
|
+
*/
|
|
29
|
+
export declare function createSemanticManager(options: SemanticManagerOptions): SemanticManager;
|
|
30
|
+
//# sourceMappingURL=semantic-manager.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"semantic-manager.d.ts","sourceRoot":"","sources":["../src/semantic-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,IAAI,EAAE,MAAM;aAEZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjC,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;IAMnD,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,oBAAoB;IAQrE,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB;IAO7D,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB;IAO1D,MAAM,CAAC,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,oBAAoB;CAOjF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAuKtF"}
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Semantic Manager
|
|
3
|
+
*
|
|
4
|
+
* High-level manager for semantic context storage and search.
|
|
5
|
+
* Combines embedding computation with storage.
|
|
6
|
+
*
|
|
7
|
+
* Invariants:
|
|
8
|
+
* - INV-SEM-001: Embeddings computed on store, cached until content changes
|
|
9
|
+
* - INV-SEM-002: Search results sorted by similarity descending
|
|
10
|
+
* - INV-SEM-003: Similarity scores normalized to [0, 1]
|
|
11
|
+
* - INV-SEM-004: Namespace isolation
|
|
12
|
+
*/
|
|
13
|
+
import { SemanticContextErrorCodes, computeContentHash } from '@defai.digital/contracts';
|
|
14
|
+
/**
|
|
15
|
+
* Error thrown by semantic manager
|
|
16
|
+
*/
|
|
17
|
+
export class SemanticManagerError extends Error {
|
|
18
|
+
code;
|
|
19
|
+
details;
|
|
20
|
+
constructor(code, message, details) {
|
|
21
|
+
super(message);
|
|
22
|
+
this.code = code;
|
|
23
|
+
this.details = details;
|
|
24
|
+
this.name = 'SemanticManagerError';
|
|
25
|
+
}
|
|
26
|
+
static notFound(key, namespace) {
|
|
27
|
+
return new SemanticManagerError(SemanticContextErrorCodes.NOT_FOUND, `Item not found: ${namespace}:${key}`, { key, namespace });
|
|
28
|
+
}
|
|
29
|
+
static embeddingFailed(message) {
|
|
30
|
+
return new SemanticManagerError(SemanticContextErrorCodes.EMBEDDING_FAILED, `Embedding computation failed: ${message}`);
|
|
31
|
+
}
|
|
32
|
+
static searchFailed(message) {
|
|
33
|
+
return new SemanticManagerError(SemanticContextErrorCodes.SEARCH_FAILED, `Search failed: ${message}`);
|
|
34
|
+
}
|
|
35
|
+
static dimensionMismatch(expected, actual) {
|
|
36
|
+
return new SemanticManagerError(SemanticContextErrorCodes.DIMENSION_MISMATCH, `Embedding dimension mismatch: expected ${expected}, got ${actual}`, { expected, actual });
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Creates a semantic manager
|
|
41
|
+
*/
|
|
42
|
+
export function createSemanticManager(options) {
|
|
43
|
+
const { embeddingPort, storePort, defaultNamespace = 'default', autoEmbed = true, } = options;
|
|
44
|
+
// Track namespace embedding dimensions for consistency (INV-SEM-200)
|
|
45
|
+
const namespaceDimensions = new Map();
|
|
46
|
+
/**
|
|
47
|
+
* Validate embedding dimension for namespace
|
|
48
|
+
*/
|
|
49
|
+
function validateDimension(namespace, dimension) {
|
|
50
|
+
const expected = namespaceDimensions.get(namespace);
|
|
51
|
+
if (expected !== undefined && expected !== dimension) {
|
|
52
|
+
throw SemanticManagerError.dimensionMismatch(expected, dimension);
|
|
53
|
+
}
|
|
54
|
+
if (expected === undefined) {
|
|
55
|
+
namespaceDimensions.set(namespace, dimension);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
return {
|
|
59
|
+
/**
|
|
60
|
+
* Store content with automatic embedding
|
|
61
|
+
* INV-SEM-001: Embeddings computed and cached
|
|
62
|
+
*/
|
|
63
|
+
async store(request) {
|
|
64
|
+
const namespace = request.namespace ?? defaultNamespace;
|
|
65
|
+
try {
|
|
66
|
+
// Check if content changed (for caching)
|
|
67
|
+
const contentHash = await computeContentHash(request.content);
|
|
68
|
+
const existing = await storePort.get(request.key, namespace);
|
|
69
|
+
// Determine if embedding needs computation
|
|
70
|
+
let embedding = request.embedding;
|
|
71
|
+
let embeddingComputed = false;
|
|
72
|
+
if (autoEmbed && !embedding) {
|
|
73
|
+
const needsEmbedding = !existing ||
|
|
74
|
+
existing.contentHash !== contentHash ||
|
|
75
|
+
request.forceRecompute;
|
|
76
|
+
if (needsEmbedding) {
|
|
77
|
+
const result = await embeddingPort.embed({ text: request.content });
|
|
78
|
+
embedding = result.embedding;
|
|
79
|
+
embeddingComputed = true;
|
|
80
|
+
// Validate dimension consistency (INV-SEM-200)
|
|
81
|
+
validateDimension(namespace, result.dimension);
|
|
82
|
+
}
|
|
83
|
+
else if (existing?.embedding) {
|
|
84
|
+
// Reuse existing embedding
|
|
85
|
+
embedding = existing.embedding;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
// Validate provided embedding dimension
|
|
89
|
+
if (embedding) {
|
|
90
|
+
const config = embeddingPort.getConfig();
|
|
91
|
+
if (embedding.length !== config.dimension) {
|
|
92
|
+
throw SemanticManagerError.dimensionMismatch(config.dimension, embedding.length);
|
|
93
|
+
}
|
|
94
|
+
validateDimension(namespace, embedding.length);
|
|
95
|
+
}
|
|
96
|
+
// Store with embedding
|
|
97
|
+
const result = await storePort.store({
|
|
98
|
+
...request,
|
|
99
|
+
namespace,
|
|
100
|
+
embedding,
|
|
101
|
+
});
|
|
102
|
+
return {
|
|
103
|
+
...result,
|
|
104
|
+
embeddingComputed,
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
catch (error) {
|
|
108
|
+
if (error instanceof SemanticManagerError)
|
|
109
|
+
throw error;
|
|
110
|
+
const message = error instanceof Error ? error.message : 'Unknown error';
|
|
111
|
+
throw SemanticManagerError.embeddingFailed(message);
|
|
112
|
+
}
|
|
113
|
+
},
|
|
114
|
+
/**
|
|
115
|
+
* Search by semantic similarity
|
|
116
|
+
* INV-SEM-002: Results sorted by similarity descending
|
|
117
|
+
* INV-SEM-003: Scores normalized to [0, 1]
|
|
118
|
+
* INV-SEM-004: Namespace isolation
|
|
119
|
+
*/
|
|
120
|
+
async search(request) {
|
|
121
|
+
const namespace = request.namespace;
|
|
122
|
+
try {
|
|
123
|
+
// Compute query embedding
|
|
124
|
+
const queryResult = await embeddingPort.embed({ text: request.query });
|
|
125
|
+
// Validate dimension if namespace has items
|
|
126
|
+
if (namespace) {
|
|
127
|
+
const stats = await storePort.getStats(namespace);
|
|
128
|
+
if (stats.embeddingDimension !== null) {
|
|
129
|
+
validateDimension(namespace, queryResult.dimension);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
// Delegate search to store
|
|
133
|
+
return await storePort.search(request);
|
|
134
|
+
}
|
|
135
|
+
catch (error) {
|
|
136
|
+
if (error instanceof SemanticManagerError)
|
|
137
|
+
throw error;
|
|
138
|
+
const message = error instanceof Error ? error.message : 'Unknown error';
|
|
139
|
+
throw SemanticManagerError.searchFailed(message);
|
|
140
|
+
}
|
|
141
|
+
},
|
|
142
|
+
/**
|
|
143
|
+
* Get item by key
|
|
144
|
+
*/
|
|
145
|
+
async get(key, namespace) {
|
|
146
|
+
return storePort.get(key, namespace ?? defaultNamespace);
|
|
147
|
+
},
|
|
148
|
+
/**
|
|
149
|
+
* List items
|
|
150
|
+
*/
|
|
151
|
+
async list(request) {
|
|
152
|
+
return storePort.list({
|
|
153
|
+
...request,
|
|
154
|
+
namespace: request.namespace ?? defaultNamespace,
|
|
155
|
+
});
|
|
156
|
+
},
|
|
157
|
+
/**
|
|
158
|
+
* Delete item
|
|
159
|
+
*/
|
|
160
|
+
async delete(key, namespace) {
|
|
161
|
+
return storePort.delete(key, namespace ?? defaultNamespace);
|
|
162
|
+
},
|
|
163
|
+
/**
|
|
164
|
+
* Get statistics
|
|
165
|
+
*/
|
|
166
|
+
async getStats(namespace) {
|
|
167
|
+
return storePort.getStats(namespace);
|
|
168
|
+
},
|
|
169
|
+
/**
|
|
170
|
+
* Clear namespace
|
|
171
|
+
*/
|
|
172
|
+
async clear(namespace) {
|
|
173
|
+
const ns = namespace ?? defaultNamespace;
|
|
174
|
+
// Reset dimension tracking for cleared namespace
|
|
175
|
+
namespaceDimensions.delete(ns);
|
|
176
|
+
return storePort.clear(ns);
|
|
177
|
+
},
|
|
178
|
+
/**
|
|
179
|
+
* Get embedding configuration
|
|
180
|
+
*/
|
|
181
|
+
getEmbeddingConfig() {
|
|
182
|
+
return embeddingPort.getConfig();
|
|
183
|
+
},
|
|
184
|
+
};
|
|
185
|
+
}
|
|
186
|
+
//# sourceMappingURL=semantic-manager.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"semantic-manager.js","sourceRoot":"","sources":["../src/semantic-manager.ts"],"names":[],"mappings":"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"}
|