@defai.digital/semantic-context 13.4.0

package/dist/types.js

@@ -0,0 +1,258 @@
+/**
+ * Semantic Context Types
+ *
+ * Port interfaces and type definitions for semantic context storage.
+ */
+// ============================================================================
+// Stub Implementations (for testing)
+// ============================================================================
+/**
+ * Stub embedding port for testing
+ */
+export class StubEmbeddingPort {
+    dimension;
+    model;
+    constructor(dimension = 384, model = 'stub') {
+        this.dimension = dimension;
+        this.model = model;
+    }
+    async embed(request) {
+        // Generate deterministic embedding based on text hash
+        const embedding = this.generateEmbedding(request.text);
+        return {
+            embedding,
+            model: request.model ?? this.model,
+            dimension: this.dimension,
+            durationMs: 10,
+        };
+    }
+    async embedBatch(texts) {
+        return Promise.all(texts.map((text) => this.embed({ text })));
+    }
+    getConfig() {
+        return {
+            provider: 'local',
+            model: this.model,
+            dimension: this.dimension,
+            batchSize: 32,
+            cacheEnabled: true,
+        };
+    }
+    async isAvailable() {
+        return true;
+    }
+    generateEmbedding(text) {
+        // Simple hash-based embedding for testing
+        const embedding = [];
+        for (let i = 0; i < this.dimension; i++) {
+            const charCode = text.charCodeAt(i % text.length) || 0;
+            embedding.push(Math.sin(charCode * (i + 1) * 0.1));
+        }
+        // Normalize
+        const norm = Math.sqrt(embedding.reduce((sum, v) => sum + v * v, 0));
+        return embedding.map((v) => v / (norm || 1));
+    }
+}
+/**
+ * In-memory semantic store for testing
+ */
+export class InMemorySemanticStore {
+    items = new Map();
+    embeddingPort;
+    constructor(embeddingPort) {
+        this.embeddingPort = embeddingPort ?? new StubEmbeddingPort();
+    }
+    makeKey(key, namespace) {
+        return `${namespace}:${key}`;
+    }
+    async store(request) {
+        const namespace = request.namespace ?? 'default';
+        const storageKey = this.makeKey(request.key, namespace);
+        const existing = this.items.get(storageKey);
+        // Compute content hash
+        const contentHash = await this.hashContent(request.content);
+        const needsEmbedding = !existing ||
+            existing.contentHash !== contentHash ||
+            request.forceRecompute;
+        let embedding = request.embedding;
+        let embeddingComputed = false;
+        if (needsEmbedding && !embedding) {
+            const result = await this.embeddingPort.embed({ text: request.content });
+            embedding = result.embedding;
+            embeddingComputed = true;
+        }
+        const item = {
+            key: request.key,
+            namespace,
+            content: request.content,
+            embedding,
+            embeddingDimension: embedding?.length,
+            embeddingModel: this.embeddingPort.getConfig().model,
+            metadata: request.metadata,
+            tags: request.tags,
+            contentHash,
+            createdAt: existing?.createdAt ?? new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+        this.items.set(storageKey, item);
+        // Omit embedding from the response item
+        const { embedding: _, ...itemWithoutEmbedding } = item;
+        return {
+            success: true,
+            item: itemWithoutEmbedding,
+            created: !existing,
+            embeddingComputed,
+        };
+    }
+    async search(request) {
+        const startTime = Date.now();
+        const namespace = request.namespace;
+        // Get query embedding
+        const queryResult = await this.embeddingPort.embed({ text: request.query });
+        const queryEmbedding = queryResult.embedding;
+        // Filter items
+        const candidates = Array.from(this.items.values()).filter((item) => {
+            if (namespace && item.namespace !== namespace)
+                return false;
+            if (!item.embedding)
+                return false;
+            if (request.filterTags) {
+                const itemTags = new Set(item.tags ?? []);
+                if (!request.filterTags.every((t) => itemTags.has(t)))
+                    return false;
+            }
+            return true;
+        });
+        // Compute similarities
+        const scored = candidates.map((item) => ({
+            item,
+            similarity: this.cosineSimilarity(queryEmbedding, item.embedding),
+        }));
+        // Filter by minSimilarity and sort (INV-SEM-002, INV-SEM-003)
+        const filtered = scored
+            .filter((s) => s.similarity >= (request.minSimilarity ?? 0.7))
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, request.topK ?? 10);
+        const results = filtered.map((s, index) => ({
+            item: request.includeEmbeddings
+                ? s.item
+                : { ...s.item, embedding: undefined },
+            similarity: s.similarity,
+            rank: index + 1,
+            snippet: s.item.content.slice(0, 200),
+        }));
+        return {
+            results,
+            totalMatches: filtered.length,
+            query: request.query,
+            namespace,
+            durationMs: Date.now() - startTime,
+            queryEmbedding: request.includeEmbeddings ? queryEmbedding : undefined,
+        };
+    }
+    async get(key, namespace = 'default') {
+        return this.items.get(this.makeKey(key, namespace)) ?? null;
+    }
+    async list(request) {
+        let items = Array.from(this.items.values());
+        // Filter by namespace
+        if (request.namespace) {
+            items = items.filter((i) => i.namespace === request.namespace);
+        }
+        // Filter by tags
+        if (request.filterTags) {
+            items = items.filter((item) => {
+                const itemTags = new Set(item.tags ?? []);
+                return request.filterTags.every((t) => itemTags.has(t));
+            });
+        }
+        // Filter by key prefix
+        if (request.keyPrefix) {
+            items = items.filter((i) => i.key.startsWith(request.keyPrefix));
+        }
+        // Sort
+        const sortDir = request.orderDir === 'asc' ? 1 : -1;
+        items.sort((a, b) => {
+            const aVal = a[request.orderBy ?? 'createdAt'] ?? '';
+            const bVal = b[request.orderBy ?? 'createdAt'] ?? '';
+            return aVal < bVal ? -sortDir : sortDir;
+        });
+        // Paginate
+        const offset = request.offset ?? 0;
+        const limit = request.limit ?? 10;
+        const paginated = items.slice(offset, offset + limit);
+        return {
+            items: paginated.map((i) => ({ ...i, embedding: undefined })),
+            total: items.length,
+            hasMore: offset + limit < items.length,
+            namespace: request.namespace,
+        };
+    }
+    async delete(key, namespace = 'default') {
+        const storageKey = this.makeKey(key, namespace);
+        const deleted = this.items.delete(storageKey);
+        return { deleted, key, namespace };
+    }
+    async exists(key, namespace = 'default') {
+        return this.items.has(this.makeKey(key, namespace));
+    }
+    async getStats(namespace) {
+        let items = Array.from(this.items.values());
+        if (namespace) {
+            items = items.filter((i) => i.namespace === namespace);
+        }
+        const withEmbeddings = items.filter((i) => i.embedding);
+        const allNamespaces = [...new Set(Array.from(this.items.values()).map((i) => i.namespace))];
+        const result = {
+            totalItems: items.length,
+            itemsWithEmbeddings: withEmbeddings.length,
+            embeddingDimension: withEmbeddings[0]?.embeddingDimension ?? null,
+            embeddingModel: withEmbeddings[0]?.embeddingModel ?? null,
+            namespace: namespace ?? null,
+        };
+        // Only include namespaces if no specific namespace was queried
+        if (!namespace) {
+            result.namespaces = allNamespaces;
+        }
+        return result;
+    }
+    async clear(namespace) {
+        if (namespace) {
+            const keysToDelete = Array.from(this.items.entries())
+                .filter(([_, item]) => item.namespace === namespace)
+                .map(([key]) => key);
+            keysToDelete.forEach((k) => this.items.delete(k));
+            return keysToDelete.length;
+        }
+        else {
+            const count = this.items.size;
+            this.items.clear();
+            return count;
+        }
+    }
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length)
+            return 0;
+        let dot = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denom = Math.sqrt(normA) * Math.sqrt(normB);
+        if (denom === 0)
+            return 0;
+        // Cosine similarity is in [-1, 1], normalize to [0, 1]
+        return (dot / denom + 1) / 2;
+    }
+    async hashContent(content) {
+        const encoder = new TextEncoder();
+        const data = encoder.encode(content);
+        const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@defai.digital/semantic-context",
+  "version": "13.4.0",
+  "type": "module",
+  "description": "Vector-indexed semantic search for AutomatosX",
+  "license": "BUSL-1.1",
+  "author": "DEFAI Private Limited",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/defai-digital/automatosx.git",
+    "directory": "packages/core/semantic-context"
+  },
+  "homepage": "https://github.com/defai-digital/automatosx#readme",
+  "bugs": {
+    "url": "https://github.com/defai-digital/automatosx/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@defai.digital/contracts": "13.4.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist"
+  }
+}

package/src/embedding-service.ts

@@ -0,0 +1,323 @@
+/**
+ * Embedding Service
+ *
+ * Provides text embedding computation with a local TF-IDF fallback.
+ * Can be extended with external providers (OpenAI, Cohere, etc.)
+ *
+ * Invariants:
+ * - INV-SEM-001: Embeddings computed and cached
+ * - INV-SEM-200: Consistent dimension within namespace
+ */
+
+import type {
+  EmbeddingPort,
+  EmbeddingRequest,
+  EmbeddingResult,
+} from './types.js';
+import type { EmbeddingConfig } from '@defai.digital/contracts';
+import { normalizeVector } from './similarity.js';
+
+// ============================================================================
+// Local TF-IDF Embedding
+// ============================================================================
+
+/**
+ * Simple tokenizer that splits text into tokens
+ */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter((t) => t.length > 1);
+}
+
+/**
+ * Compute term frequency for tokens
+ */
+function computeTF(tokens: string[]): Map<string, number> {
+  const tf = new Map<string, number>();
+  for (const token of tokens) {
+    tf.set(token, (tf.get(token) ?? 0) + 1);
+  }
+  // Normalize by total tokens
+  const total = tokens.length;
+  for (const [term, count] of tf) {
+    tf.set(term, count / total);
+  }
+  return tf;
+}
+
+/**
+ * Simple hash function for consistent dimension mapping
+ */
+function hashString(str: string, maxDim: number): number {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return Math.abs(hash) % maxDim;
+}
+
+/**
+ * Create TF-IDF based embedding
+ *
+ * This is a simple local embedding that:
+ * 1. Tokenizes text
+ * 2. Computes term frequency
+ * 3. Hashes terms to fixed dimension
+ * 4. Normalizes to unit vector
+ */
+export function createTFIDFEmbedding(text: string, dimension: number): number[] {
+  const tokens = tokenize(text);
+  const tf = computeTF(tokens);
+
+  // Create sparse vector and hash to fixed dimension
+  const embedding = new Array(dimension).fill(0);
+
+  for (const [term, freq] of tf) {
+    // Hash term to dimension index
+    const index = hashString(term, dimension);
+    // Add frequency (with sign based on secondary hash for better distribution)
+    const sign = hashString(term + '_sign', 2) === 0 ? 1 : -1;
+    embedding[index] += freq * sign;
+  }
+
+  // Normalize to unit vector
+  return normalizeVector(embedding);
+}
+
+/**
+ * Batch create TF-IDF embeddings with IDF computation
+ */
+export function createTFIDFEmbeddingBatch(texts: string[], dimension: number): number[][] {
+  // Compute document frequency for IDF
+  const docFreq = new Map<string, number>();
+  const allTokens: string[][] = [];
+
+  for (const text of texts) {
+    const tokens = tokenize(text);
+    const uniqueTokens = new Set(tokens);
+    allTokens.push(tokens);
+
+    for (const token of uniqueTokens) {
+      docFreq.set(token, (docFreq.get(token) ?? 0) + 1);
+    }
+  }
+
+  const numDocs = texts.length;
+  const embeddings: number[][] = [];
+
+  for (let i = 0; i < texts.length; i++) {
+    const tokens = allTokens[i]!;
+    const tf = computeTF(tokens);
+    const embedding = new Array(dimension).fill(0);
+
+    for (const [term, freq] of tf) {
+      // Compute IDF: log(N / df)
+      const df = docFreq.get(term) ?? 1;
+      const idf = Math.log(numDocs / df);
+      const tfidf = freq * idf;
+
+      // Hash to dimension
+      const index = hashString(term, dimension);
+      const sign = hashString(term + '_sign', 2) === 0 ? 1 : -1;
+      embedding[index] += tfidf * sign;
+    }
+
+    embeddings.push(normalizeVector(embedding));
+  }
+
+  return embeddings;
+}
+
+// ============================================================================
+// Local Embedding Provider
+// ============================================================================
+
+/**
+ * Local embedding provider using TF-IDF
+ */
+export class LocalEmbeddingProvider implements EmbeddingPort {
+  private config: EmbeddingConfig;
+
+  constructor(config?: Partial<EmbeddingConfig>) {
+    this.config = {
+      provider: 'local',
+      model: 'tfidf',
+      dimension: 384,
+      batchSize: 32,
+      cacheEnabled: true,
+      ...config,
+    };
+  }
+
+  async embed(request: EmbeddingRequest): Promise<EmbeddingResult> {
+    const startTime = Date.now();
+
+    const embedding = createTFIDFEmbedding(
+      request.text,
+      this.config.dimension
+    );
+
+    return {
+      embedding,
+      model: request.model ?? this.config.model,
+      dimension: this.config.dimension,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  async embedBatch(texts: string[]): Promise<EmbeddingResult[]> {
+    const startTime = Date.now();
+
+    // Process in batches
+    const results: EmbeddingResult[] = [];
+    for (let i = 0; i < texts.length; i += this.config.batchSize) {
+      const batch = texts.slice(i, i + this.config.batchSize);
+      const embeddings = createTFIDFEmbeddingBatch(batch, this.config.dimension);
+
+      for (const embedding of embeddings) {
+        results.push({
+          embedding,
+          model: this.config.model,
+          dimension: this.config.dimension,
+          durationMs: Date.now() - startTime,
+        });
+      }
+    }
+
+    return results;
+  }
+
+  getConfig(): EmbeddingConfig {
+    return { ...this.config };
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true; // Local provider is always available
+  }
+}
+
+// ============================================================================
+// Embedding Service Factory
+// ============================================================================
+
+/**
+ * Create embedding provider based on configuration
+ */
+export function createEmbeddingProvider(config?: Partial<EmbeddingConfig>): EmbeddingPort {
+  const provider = config?.provider ?? 'local';
+
+  switch (provider) {
+    case 'local':
+      return new LocalEmbeddingProvider(config);
+
+    // Future: Add OpenAI, Cohere, Voyage providers here
+    // case 'openai':
+    //   return new OpenAIEmbeddingProvider(config);
+
+    default:
+      // Fall back to local
+      return new LocalEmbeddingProvider(config);
+  }
+}
+
+/**
+ * Cached embedding provider wrapper
+ */
+export class CachedEmbeddingProvider implements EmbeddingPort {
+  private cache: Map<string, EmbeddingResult> = new Map();
+  private delegate: EmbeddingPort;
+  private maxCacheSize: number;
+
+  constructor(delegate: EmbeddingPort, maxCacheSize = 10000) {
+    this.delegate = delegate;
+    this.maxCacheSize = maxCacheSize;
+  }
+
+  async embed(request: EmbeddingRequest): Promise<EmbeddingResult> {
+    const cacheKey = `${request.model ?? 'default'}:${request.text}`;
+
+    // Check cache
+    const cached = this.cache.get(cacheKey);
+    if (cached) {
+      return { ...cached, durationMs: 0 };
+    }
+
+    // Compute and cache
+    const result = await this.delegate.embed(request);
+
+    // Evict old entries if cache is full
+    if (this.cache.size >= this.maxCacheSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) this.cache.delete(firstKey);
+    }
+
+    this.cache.set(cacheKey, result);
+    return result;
+  }
+
+  async embedBatch(texts: string[]): Promise<EmbeddingResult[]> {
+    // Check which texts need computation
+    const model = this.getConfig().model;
+    const toCompute: { index: number; text: string }[] = [];
+    const results: (EmbeddingResult | null)[] = new Array(texts.length).fill(null);
+
+    for (let i = 0; i < texts.length; i++) {
+      const cacheKey = `${model}:${texts[i]}`;
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        results[i] = { ...cached, durationMs: 0 };
+      } else {
+        toCompute.push({ index: i, text: texts[i]! });
+      }
+    }
+
+    // Compute missing embeddings
+    if (toCompute.length > 0) {
+      const computed = await this.delegate.embedBatch(toCompute.map((t) => t.text));
+
+      for (let i = 0; i < toCompute.length; i++) {
+        const { index, text } = toCompute[i]!;
+        const result = computed[i]!;
+        results[index] = result;
+
+        // Cache
+        const cacheKey = `${model}:${text}`;
+        if (this.cache.size < this.maxCacheSize) {
+          this.cache.set(cacheKey, result);
+        }
+      }
+    }
+
+    return results as EmbeddingResult[];
+  }
+
+  getConfig(): EmbeddingConfig {
+    return this.delegate.getConfig();
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.delegate.isAvailable();
+  }
+
+  /**
+   * Clear the cache
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getCacheStats(): { size: number; maxSize: number } {
+    return {
+      size: this.cache.size,
+      maxSize: this.maxCacheSize,
+    };
+  }
+}