@defai.digital/semantic-context 13.4.0

package/dist/similarity.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Similarity Computation Utilities
+ *
+ * Provides various methods for computing vector similarity.
+ *
+ * Invariants:
+ * - INV-SEM-003: All scores normalized to [0, 1] range
+ */
+import type { SimilarityMethod, SimilarityOptions } from './types.js';
+/**
+ * Default similarity options
+ */
+export declare const DEFAULT_SIMILARITY_OPTIONS: SimilarityOptions;
+/**
+ * Compute cosine similarity between two vectors
+ * Returns value in [-1, 1] (or [0, 1] if normalized)
+ *
+ * INV-SEM-003: Normalized to [0, 1] when normalize=true
+ */
+export declare function cosineSimilarity(a: number[], b: number[], normalize?: boolean): number;
+/**
+ * Compute dot product similarity between two vectors
+ * Returns raw dot product (or normalized if requested)
+ *
+ * INV-SEM-003: When normalize=true, normalizes vectors first and maps to [0, 1]
+ */
+export declare function dotProductSimilarity(a: number[], b: number[], normalize?: boolean): number;
+/**
+ * Compute Euclidean distance between two vectors
+ * Returns distance (or similarity if normalize=true)
+ *
+ * INV-SEM-003: Converted to similarity via 1/(1+distance) when normalize=true
+ */
+export declare function euclideanDistance(a: number[], b: number[], normalize?: boolean): number;
+/**
+ * Compute Manhattan distance between two vectors
+ */
+export declare function manhattanDistance(a: number[], b: number[], normalize?: boolean): number;
+/**
+ * Compute similarity using specified method
+ */
+export declare function computeSimilarity(a: number[], b: number[], options?: Partial<SimilarityOptions>): number;
+/**
+ * Normalize a vector to unit length
+ */
+export declare function normalizeVector(v: number[]): number[];
+/**
+ * Compute vector norm (magnitude)
+ */
+export declare function vectorNorm(v: number[]): number;
+/**
+ * Add two vectors
+ */
+export declare function addVectors(a: number[], b: number[]): number[];
+/**
+ * Subtract vectors: a - b
+ */
+export declare function subtractVectors(a: number[], b: number[]): number[];
+/**
+ * Scale a vector by a scalar
+ */
+export declare function scaleVector(v: number[], scalar: number): number[];
+/**
+ * Compute centroid (average) of multiple vectors
+ */
+export declare function computeCentroid(vectors: number[][]): number[];
+/**
+ * Find k nearest neighbors from candidates
+ * INV-SEM-002: Results sorted by similarity descending
+ */
+export declare function findKNearest(query: number[], candidates: Array<{
+    id: string;
+    embedding: number[];
+}>, k: number, method?: SimilarityMethod): Array<{
+    id: string;
+    similarity: number;
+}>;
+/**
+ * Filter vectors by minimum similarity threshold
+ * INV-SEM-003: Threshold applied after normalization
+ */
+export declare function filterByThreshold(query: number[], candidates: Array<{
+    id: string;
+    embedding: number[];
+}>, minSimilarity: number, method?: SimilarityMethod): Array<{
+    id: string;
+    similarity: number;
+}>;
+//# sourceMappingURL=similarity.d.ts.map

package/dist/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../src/similarity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAGxC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,SAAS,UAAO,GAAG,MAAM,CAyBnF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,SAAS,UAAO,GAAG,MAAM,CAoCvF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,SAAS,UAAO,GAAG,MAAM,CAiBpF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,SAAS,UAAO,GAAG,MAAM,CAcpF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,MAAM,EAAE,EACX,CAAC,EAAE,MAAM,EAAE,EACX,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,GACvC,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAIrD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAK7D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAKlE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,CAgB7D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EACtD,CAAC,EAAE,MAAM,EACT,MAAM,GAAE,gBAA2B,GAClC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAU3C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EACtD,aAAa,EAAE,MAAM,EACrB,MAAM,GAAE,gBAA2B,GAClC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ3C"}

package/dist/similarity.js

@@ -0,0 +1,216 @@
+/**
+ * Similarity Computation Utilities
+ *
+ * Provides various methods for computing vector similarity.
+ *
+ * Invariants:
+ * - INV-SEM-003: All scores normalized to [0, 1] range
+ */
+/**
+ * Default similarity options
+ */
+export const DEFAULT_SIMILARITY_OPTIONS = {
+    method: 'cosine',
+    normalize: true,
+};
+/**
+ * Compute cosine similarity between two vectors
+ * Returns value in [-1, 1] (or [0, 1] if normalized)
+ *
+ * INV-SEM-003: Normalized to [0, 1] when normalize=true
+ */
+export function cosineSimilarity(a, b, normalize = true) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    if (a.length === 0)
+        return 0;
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denominator === 0)
+        return 0;
+    const similarity = dotProduct / denominator;
+    // Normalize from [-1, 1] to [0, 1]
+    return normalize ? (similarity + 1) / 2 : similarity;
+}
+/**
+ * Compute dot product similarity between two vectors
+ * Returns raw dot product (or normalized if requested)
+ *
+ * INV-SEM-003: When normalize=true, normalizes vectors first and maps to [0, 1]
+ */
+export function dotProductSimilarity(a, b, normalize = true) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    if (a.length === 0)
+        return 0;
+    if (!normalize) {
+        // Raw dot product
+        let dotProduct = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+        }
+        return dotProduct;
+    }
+    // Normalized: compute cosine similarity (dot product of unit vectors)
+    // This ensures result is in [-1, 1] range, then map to [0, 1]
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denominator === 0)
+        return 0;
+    const similarity = dotProduct / denominator;
+    // Map from [-1, 1] to [0, 1]
+    return (similarity + 1) / 2;
+}
+/**
+ * Compute Euclidean distance between two vectors
+ * Returns distance (or similarity if normalize=true)
+ *
+ * INV-SEM-003: Converted to similarity via 1/(1+distance) when normalize=true
+ */
+export function euclideanDistance(a, b, normalize = true) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    if (a.length === 0)
+        return 0;
+    let sumSquares = 0;
+    for (let i = 0; i < a.length; i++) {
+        const diff = a[i] - b[i];
+        sumSquares += diff * diff;
+    }
+    const distance = Math.sqrt(sumSquares);
+    // Convert distance to similarity: smaller distance = higher similarity
+    return normalize ? 1 / (1 + distance) : distance;
+}
+/**
+ * Compute Manhattan distance between two vectors
+ */
+export function manhattanDistance(a, b, normalize = true) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    if (a.length === 0)
+        return 0;
+    let distance = 0;
+    for (let i = 0; i < a.length; i++) {
+        distance += Math.abs(a[i] - b[i]);
+    }
+    // Convert to similarity
+    return normalize ? 1 / (1 + distance) : distance;
+}
+/**
+ * Compute similarity using specified method
+ */
+export function computeSimilarity(a, b, options = {}) {
+    const { method, normalize } = { ...DEFAULT_SIMILARITY_OPTIONS, ...options };
+    switch (method) {
+        case 'cosine':
+            return cosineSimilarity(a, b, normalize);
+        case 'dot':
+            return dotProductSimilarity(a, b, normalize);
+        case 'euclidean':
+            return euclideanDistance(a, b, normalize);
+        default:
+            throw new Error(`Unknown similarity method: ${method}`);
+    }
+}
+/**
+ * Normalize a vector to unit length
+ */
+export function normalizeVector(v) {
+    const norm = Math.sqrt(v.reduce((sum, x) => sum + x * x, 0));
+    if (norm === 0)
+        return v;
+    return v.map((x) => x / norm);
+}
+/**
+ * Compute vector norm (magnitude)
+ */
+export function vectorNorm(v) {
+    return Math.sqrt(v.reduce((sum, x) => sum + x * x, 0));
+}
+/**
+ * Add two vectors
+ */
+export function addVectors(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    return a.map((x, i) => x + b[i]);
+}
+/**
+ * Subtract vectors: a - b
+ */
+export function subtractVectors(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    return a.map((x, i) => x - b[i]);
+}
+/**
+ * Scale a vector by a scalar
+ */
+export function scaleVector(v, scalar) {
+    return v.map((x) => x * scalar);
+}
+/**
+ * Compute centroid (average) of multiple vectors
+ */
+export function computeCentroid(vectors) {
+    if (vectors.length === 0)
+        return [];
+    const dim = vectors[0].length;
+    const centroid = new Array(dim).fill(0);
+    for (const v of vectors) {
+        if (v.length !== dim) {
+            throw new Error(`Inconsistent vector dimensions`);
+        }
+        for (let i = 0; i < dim; i++) {
+            centroid[i] += v[i];
+        }
+    }
+    return centroid.map((x) => x / vectors.length);
+}
+/**
+ * Find k nearest neighbors from candidates
+ * INV-SEM-002: Results sorted by similarity descending
+ */
+export function findKNearest(query, candidates, k, method = 'cosine') {
+    const scored = candidates.map((c) => ({
+        id: c.id,
+        similarity: computeSimilarity(query, c.embedding, { method, normalize: true }),
+    }));
+    // Sort by similarity descending
+    scored.sort((a, b) => b.similarity - a.similarity);
+    return scored.slice(0, k);
+}
+/**
+ * Filter vectors by minimum similarity threshold
+ * INV-SEM-003: Threshold applied after normalization
+ */
+export function filterByThreshold(query, candidates, minSimilarity, method = 'cosine') {
+    return candidates
+        .map((c) => ({
+        id: c.id,
+        similarity: computeSimilarity(query, c.embedding, { method, normalize: true }),
+    }))
+        .filter((s) => s.similarity >= minSimilarity)
+        .sort((a, b) => b.similarity - a.similarity);
+}
+//# sourceMappingURL=similarity.js.map

package/dist/similarity.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Semantic Context Types
+ *
+ * Port interfaces and type definitions for semantic context storage.
+ */
+import type { SemanticItem, SemanticSearchRequest, SemanticSearchResponse, SemanticStoreRequest, SemanticStoreResponse, SemanticListRequest, SemanticListResponse, SemanticDeleteResponse, EmbeddingConfig } from '@defai.digital/contracts';
+/**
+ * Embedding request
+ */
+export interface EmbeddingRequest {
+    /**
+     * Text to embed
+     */
+    text: string;
+    /**
+     * Model to use (optional, uses config default)
+     */
+    model?: string;
+}
+/**
+ * Embedding result
+ */
+export interface EmbeddingResult {
+    /**
+     * The embedding vector
+     */
+    embedding: number[];
+    /**
+     * Model used
+     */
+    model: string;
+    /**
+     * Dimension of embedding
+     */
+    dimension: number;
+    /**
+     * Computation duration in ms
+     */
+    durationMs: number;
+}
+/**
+ * Port interface for embedding computation
+ * Implementations inject actual embedding provider at runtime
+ */
+export interface EmbeddingPort {
+    /**
+     * Compute embedding for text
+     */
+    embed(request: EmbeddingRequest): Promise<EmbeddingResult>;
+    /**
+     * Compute embeddings for multiple texts (batch)
+     */
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    /**
+     * Get embedding configuration
+     */
+    getConfig(): EmbeddingConfig;
+    /**
+     * Check if provider is available
+     */
+    isAvailable(): Promise<boolean>;
+}
+/**
+ * Port interface for semantic storage
+ * Implementations provide actual persistence (SQLite, etc.)
+ */
+export interface SemanticStorePort {
+    /**
+     * Store item with embedding
+     * INV-SEM-001: Embedding cached until content changes
+     */
+    store(request: SemanticStoreRequest): Promise<SemanticStoreResponse>;
+    /**
+     * Search by semantic similarity
+     * INV-SEM-002: Results sorted by similarity descending
+     * INV-SEM-003: Scores normalized to [0, 1]
+     * INV-SEM-004: Namespace isolation
+     */
+    search(request: SemanticSearchRequest): Promise<SemanticSearchResponse>;
+    /**
+     * Get item by key
+     */
+    get(key: string, namespace?: string): Promise<SemanticItem | null>;
+    /**
+     * List items
+     */
+    list(request: SemanticListRequest): Promise<SemanticListResponse>;
+    /**
+     * Delete item
+     */
+    delete(key: string, namespace?: string): Promise<SemanticDeleteResponse>;
+    /**
+     * Check if item exists
+     */
+    exists(key: string, namespace?: string): Promise<boolean>;
+    /**
+     * Get namespace statistics
+     */
+    getStats(namespace?: string): Promise<SemanticStoreStats>;
+    /**
+     * Clear namespace
+     */
+    clear(namespace?: string): Promise<number>;
+}
+/**
+ * Semantic store statistics
+ */
+export interface SemanticStoreStats {
+    /**
+     * Total items in namespace
+     */
+    totalItems: number;
+    /**
+     * Items with embeddings
+     */
+    itemsWithEmbeddings: number;
+    /**
+     * Embedding dimension used
+     */
+    embeddingDimension: number | null;
+    /**
+     * Embedding model used
+     */
+    embeddingModel: string | null;
+    /**
+     * Namespace queried
+     */
+    namespace: string | null;
+    /**
+     * All namespaces (if namespace not specified)
+     */
+    namespaces?: string[];
+}
+/**
+ * High-level semantic context manager
+ * Combines embedding and storage
+ */
+export interface SemanticManager {
+    /**
+     * Store content with automatic embedding
+     */
+    store(request: SemanticStoreRequest): Promise<SemanticStoreResponse>;
+    /**
+     * Search by semantic similarity
+     */
+    search(request: SemanticSearchRequest): Promise<SemanticSearchResponse>;
+    /**
+     * Get item by key
+     */
+    get(key: string, namespace?: string): Promise<SemanticItem | null>;
+    /**
+     * List items
+     */
+    list(request: SemanticListRequest): Promise<SemanticListResponse>;
+    /**
+     * Delete item
+     */
+    delete(key: string, namespace?: string): Promise<SemanticDeleteResponse>;
+    /**
+     * Get statistics
+     */
+    getStats(namespace?: string): Promise<SemanticStoreStats>;
+    /**
+     * Clear namespace
+     */
+    clear(namespace?: string): Promise<number>;
+    /**
+     * Get embedding configuration
+     */
+    getEmbeddingConfig(): EmbeddingConfig;
+}
+/**
+ * Options for creating semantic manager
+ */
+export interface SemanticManagerOptions {
+    /**
+     * Embedding provider port
+     */
+    embeddingPort: EmbeddingPort;
+    /**
+     * Storage port
+     */
+    storePort: SemanticStorePort;
+    /**
+     * Default namespace
+     */
+    defaultNamespace?: string;
+    /**
+     * Whether to auto-compute embeddings on store
+     */
+    autoEmbed?: boolean;
+}
+/**
+ * Similarity computation method
+ */
+export type SimilarityMethod = 'cosine' | 'dot' | 'euclidean';
+/**
+ * Similarity computation options
+ */
+export interface SimilarityOptions {
+    method: SimilarityMethod;
+    normalize: boolean;
+}
+/**
+ * Stub embedding port for testing
+ */
+export declare class StubEmbeddingPort implements EmbeddingPort {
+    private dimension;
+    private model;
+    constructor(dimension?: number, model?: string);
+    embed(request: EmbeddingRequest): Promise<EmbeddingResult>;
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    getConfig(): EmbeddingConfig;
+    isAvailable(): Promise<boolean>;
+    private generateEmbedding;
+}
+/**
+ * In-memory semantic store for testing
+ */
+export declare class InMemorySemanticStore implements SemanticStorePort {
+    private items;
+    private embeddingPort;
+    constructor(embeddingPort?: EmbeddingPort);
+    private makeKey;
+    store(request: SemanticStoreRequest): Promise<SemanticStoreResponse>;
+    search(request: SemanticSearchRequest): Promise<SemanticSearchResponse>;
+    get(key: string, namespace?: string): Promise<SemanticItem | null>;
+    list(request: SemanticListRequest): Promise<SemanticListResponse>;
+    delete(key: string, namespace?: string): Promise<SemanticDeleteResponse>;
+    exists(key: string, namespace?: string): Promise<boolean>;
+    getStats(namespace?: string): Promise<SemanticStoreStats>;
+    clear(namespace?: string): Promise<number>;
+    private cosineSimilarity;
+    private hashContent;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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