ds4-context-core 0.1.2 → 0.2.0-beta.2

package/dist/retrieval/semantic-index.js

@@ -0,0 +1,284 @@
+import { sha256 } from "../shared/hash.js";
+import { disabledSemanticQueryDiagnostics, embeddingProfileKey, validEmbeddingVector, } from "./embedding.js";
+function uniqueWarnings(values) {
+    return [...new Set(values)].slice(0, 20);
+}
+function identityFields(identity) {
+    return {
+        provider: identity.provider,
+        model: identity.model,
+        dimensions: identity.dimensions,
+        destination: identity.destination,
+    };
+}
+export class SemanticEmbeddingIndex {
+    repository;
+    port;
+    options;
+    gate;
+    now;
+    indexedAt;
+    queryCache = new Map();
+    syncByScope = new Map();
+    constructor(repository, port, options, gate = (text) => text, now = () => performance.now(), indexedAt = Date.now) {
+        this.repository = repository;
+        this.port = port;
+        this.options = options;
+        this.gate = gate;
+        this.now = now;
+        this.indexedAt = indexedAt;
+    }
+    get identity() {
+        return this.port.identity;
+    }
+    get sourceLimit() {
+        return this.options.maxSources;
+    }
+    syncSources(kind, scopeId, inputSources, complete) {
+        const startedAt = this.now();
+        const warnings = [];
+        const seen = new Set();
+        const sources = [];
+        for (const source of inputSources) {
+            if (source.kind !== kind || source.scopeId !== scopeId || !source.text.trim())
+                continue;
+            const key = `${source.sourceKey}\0${source.sourceHash}\0${source.chunkingVersion}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            sources.push(source);
+        }
+        sources.sort((left, right) => left.sourceKey.localeCompare(right.sourceKey)
+            || left.sourceHash.localeCompare(right.sourceHash)
+            || left.chunkingVersion.localeCompare(right.chunkingVersion));
+        const sourceLimitExceeded = sources.length > this.options.maxSources;
+        sources.splice(this.options.maxSources);
+        let cachedVectors = 0;
+        let indexedVectors = 0;
+        let skippedByPrivacy = 0;
+        let embeddingCalls = 0;
+        let corruptVectors = 0;
+        let failed = false;
+        let fallbackReason;
+        try {
+            if (complete && !sourceLimitExceeded) {
+                this.repository.pruneSources(kind, scopeId, sources);
+            }
+            const pending = [];
+            for (const source of sources) {
+                const existing = this.repository.getVector(kind, scopeId, source.sourceKey, source.sourceHash, source.chunkingVersion, this.port.identity);
+                if (existing) {
+                    cachedVectors++;
+                    continue;
+                }
+                const text = this.gate(source.text, {
+                    purpose: "source",
+                    kind,
+                    scopeId,
+                    sourceKey: source.sourceKey,
+                    destination: this.port.identity.destination,
+                    provider: this.port.identity.provider,
+                    model: this.port.identity.model,
+                });
+                if (text === undefined) {
+                    skippedByPrivacy++;
+                    continue;
+                }
+                pending.push({ source, text });
+            }
+            for (let offset = 0; offset < pending.length; offset += this.options.batchSize) {
+                const batch = pending.slice(offset, offset + this.options.batchSize);
+                const callStartedAt = this.now();
+                let vectors;
+                try {
+                    embeddingCalls++;
+                    vectors = this.port.embed(batch.map((item) => item.text));
+                }
+                catch (error) {
+                    failed = true;
+                    fallbackReason = `embedding provider failure: ${error instanceof Error ? error.message : String(error)}`;
+                    break;
+                }
+                const elapsed = Math.max(0, this.now() - callStartedAt);
+                if (elapsed > this.options.timeoutMs) {
+                    failed = true;
+                    fallbackReason = `embedding timeout after ${Math.round(elapsed)} ms`;
+                    break;
+                }
+                if (vectors.length !== batch.length) {
+                    failed = true;
+                    fallbackReason = "embedding provider returned an unexpected batch size";
+                    break;
+                }
+                const rows = [];
+                for (let index = 0; index < batch.length; index++) {
+                    const item = batch[index];
+                    const vector = vectors[index];
+                    if (!item || !vector || !validEmbeddingVector(vector, this.port.identity.dimensions)) {
+                        corruptVectors++;
+                        continue;
+                    }
+                    rows.push({
+                        sourceKind: kind,
+                        scopeId,
+                        sourceKey: item.source.sourceKey,
+                        sourceGroup: item.source.sourceGroup,
+                        sourceHash: item.source.sourceHash,
+                        chunkingVersion: item.source.chunkingVersion,
+                        provider: this.port.identity.provider,
+                        model: this.port.identity.model,
+                        dimensions: this.port.identity.dimensions,
+                        vector,
+                        indexedAt: this.indexedAt(),
+                    });
+                }
+                this.repository.upsert(rows);
+                indexedVectors += rows.length;
+            }
+        }
+        catch (error) {
+            failed = true;
+            fallbackReason = `embedding index failure: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        if (fallbackReason)
+            warnings.push(fallbackReason);
+        const diagnostics = {
+            enabled: true,
+            ...identityFields(this.port.identity),
+            sourceKind: kind,
+            scopeId,
+            sourceCount: sources.length,
+            cachedVectors,
+            indexedVectors,
+            skippedByPrivacy,
+            embeddingCalls,
+            corruptVectors,
+            indexFresh: complete && !failed && corruptVectors === 0,
+            durationMs: Math.max(0, this.now() - startedAt),
+            warnings: uniqueWarnings(warnings),
+            ...(fallbackReason ? { fallbackReason } : {}),
+        };
+        this.syncByScope.set(`${kind}\0${scopeId}`, diagnostics);
+        return diagnostics;
+    }
+    query(kind, scopeId, text, lexicalCandidates) {
+        const startedAt = this.now();
+        const sync = this.syncByScope.get(`${kind}\0${scopeId}`);
+        const base = {
+            ...disabledSemanticQueryDiagnostics(true),
+            ...identityFields(this.port.identity),
+            lexicalCandidates,
+            sourceEmbeddingCalls: sync?.embeddingCalls ?? 0,
+            indexedVectors: (sync?.cachedVectors ?? 0) + (sync?.indexedVectors ?? 0),
+            skippedByPrivacy: sync?.skippedByPrivacy ?? 0,
+            corruptVectors: sync?.corruptVectors ?? 0,
+            indexFresh: sync?.indexFresh ?? false,
+            warnings: [...(sync?.warnings ?? [])],
+        };
+        const prepared = this.gate(text, {
+            purpose: "query",
+            kind,
+            scopeId,
+            destination: this.port.identity.destination,
+            provider: this.port.identity.provider,
+            model: this.port.identity.model,
+        });
+        if (prepared === undefined) {
+            const fallbackReason = "embedding query excluded by privacy policy";
+            return {
+                hits: [],
+                diagnostics: {
+                    ...base,
+                    durationMs: Math.max(0, this.now() - startedAt),
+                    fallbackReason,
+                    warnings: uniqueWarnings([...base.warnings, fallbackReason]),
+                },
+            };
+        }
+        const cacheKey = sha256(`${embeddingProfileKey(this.port.identity)}\0${prepared}`);
+        let vector = this.queryCache.get(cacheKey);
+        let queryCacheHit = Boolean(vector);
+        let queryEmbeddingCalls = 0;
+        let fallbackReason;
+        if (!vector) {
+            const callStartedAt = this.now();
+            try {
+                queryEmbeddingCalls = 1;
+                const vectors = this.port.embed([prepared]);
+                const elapsed = Math.max(0, this.now() - callStartedAt);
+                if (elapsed > this.options.timeoutMs) {
+                    fallbackReason = `embedding timeout after ${Math.round(elapsed)} ms`;
+                }
+                else if (vectors.length !== 1 || !vectors[0]
+                    || !validEmbeddingVector(vectors[0], this.port.identity.dimensions)) {
+                    fallbackReason = "embedding provider returned a corrupt query vector";
+                }
+                else {
+                    vector = vectors[0];
+                    this.queryCache.set(cacheKey, vector);
+                    while (this.queryCache.size > this.options.queryCacheSize) {
+                        const oldest = this.queryCache.keys().next().value;
+                        if (!oldest)
+                            break;
+                        this.queryCache.delete(oldest);
+                    }
+                }
+            }
+            catch (error) {
+                fallbackReason = `embedding provider failure: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        if (!vector) {
+            return {
+                hits: [],
+                diagnostics: {
+                    ...base,
+                    queryCacheHit,
+                    queryEmbeddingCalls,
+                    durationMs: Math.max(0, this.now() - startedAt),
+                    ...(fallbackReason ? { fallbackReason } : {}),
+                    warnings: uniqueWarnings([...base.warnings, ...(fallbackReason ? [fallbackReason] : [])]),
+                },
+            };
+        }
+        try {
+            const searched = this.repository.searchSimilar(kind, scopeId, this.port.identity, vector, this.options.candidatePool, this.options.maxSources);
+            const minimumSimilarity = this.options.minimumSimilarity ?? 0.1;
+            const hits = searched.hits.filter((hit) => hit.similarity >= minimumSimilarity);
+            if (searched.corruptVectors > 0 && hits.length === 0) {
+                fallbackReason = "all matching embedding vectors were corrupt";
+            }
+            return {
+                hits,
+                diagnostics: {
+                    ...base,
+                    vectorCandidates: hits.length,
+                    queryCacheHit,
+                    queryEmbeddingCalls,
+                    corruptVectors: searched.corruptVectors,
+                    durationMs: Math.max(0, this.now() - startedAt),
+                    ...(fallbackReason ? { fallbackReason } : {}),
+                    warnings: uniqueWarnings([
+                        ...base.warnings,
+                        ...(searched.corruptVectors > 0 ? [`${searched.corruptVectors} corrupt embedding vector(s) ignored`] : []),
+                    ]),
+                },
+            };
+        }
+        catch (error) {
+            fallbackReason = `vector search failure: ${error instanceof Error ? error.message : String(error)}`;
+            return {
+                hits: [],
+                diagnostics: {
+                    ...base,
+                    queryCacheHit,
+                    queryEmbeddingCalls,
+                    durationMs: Math.max(0, this.now() - startedAt),
+                    fallbackReason,
+                    warnings: uniqueWarnings([...base.warnings, fallbackReason]),
+                },
+            };
+        }
+    }
+}
+//# sourceMappingURL=semantic-index.js.map

package/dist/retrieval/semantic-index.js.map

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

package/dist/retrieval/semantic-quality.d.ts

@@ -0,0 +1,52 @@
+import { type EmbeddingPort } from "./embedding.ts";
+export declare const HYBRID_RETRIEVAL_QUALITY_VERSION = "hybrid-retrieval-quality-v1";
+export interface SemanticQualityCandidate {
+    id: string;
+    text: string;
+    tokens: number;
+}
+export interface SemanticQualityFixture {
+    id: string;
+    query: string;
+    exactIdentifiers: string[];
+    expectedEvidenceIds: string[];
+    maxResults: number;
+    candidates: SemanticQualityCandidate[];
+}
+export interface SemanticQualityCorpus {
+    corpusVersion: string;
+    fixtures: SemanticQualityFixture[];
+}
+export interface SemanticStrategyQuality {
+    strategy: "lexical-only" | "hybrid";
+    evidenceRecall: number;
+    irrelevantTokenRatio: number;
+    selectedEvidenceIds: string[];
+    fallback: boolean;
+}
+export interface SemanticFixtureQuality {
+    fixtureId: string;
+    lexical: SemanticStrategyQuality;
+    hybrid: SemanticStrategyQuality;
+}
+export interface SemanticQualityReport {
+    metricsVersion: typeof HYBRID_RETRIEVAL_QUALITY_VERSION;
+    corpusVersion: string;
+    model: {
+        provider: string;
+        model: string;
+        dimensions: number;
+    };
+    fixtures: SemanticFixtureQuality[];
+    aggregate: {
+        lexicalEvidenceRecall: number;
+        hybridEvidenceRecall: number;
+        evidenceRecallDelta: number;
+        lexicalIrrelevantTokenRatio: number;
+        hybridIrrelevantTokenRatio: number;
+        irrelevantTokenRatioDelta: number;
+        fallbackCount: number;
+    };
+}
+export declare function compareHybridRetrievalCorpus(corpus: SemanticQualityCorpus, port: EmbeddingPort): SemanticQualityReport;
+//# sourceMappingURL=semantic-quality.d.ts.map

package/dist/retrieval/semantic-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-quality.d.ts","sourceRoot":"","sources":["../../src/retrieval/semantic-quality.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,gBAAgB,CAAC;AAExB,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAE9E,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,wBAAwB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,cAAc,GAAG,QAAQ,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,uBAAuB,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,OAAO,gCAAgC,CAAC;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IACnC,SAAS,EAAE;QACT,qBAAqB,EAAE,MAAM,CAAC;QAC9B,oBAAoB,EAAE,MAAM,CAAC;QAC7B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,2BAA2B,EAAE,MAAM,CAAC;QACpC,0BAA0B,EAAE,MAAM,CAAC;QACnC,yBAAyB,EAAE,MAAM,CAAC;QAClC,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AA8DD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,aAAa,GAClB,qBAAqB,CAyEvB"}

package/dist/retrieval/semantic-quality.js

@@ -0,0 +1,117 @@
+import { cosineSimilarity, reciprocalRankFusion, validEmbeddingVector, } from "./embedding.js";
+export const HYBRID_RETRIEVAL_QUALITY_VERSION = "hybrid-retrieval-quality-v1";
+function rounded(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+const QUALITY_STOPWORDS = new Set([
+    "and", "are", "before", "for", "from", "into", "local", "the", "this", "with",
+]);
+function terms(value) {
+    return new Set([...value.toLocaleLowerCase("en-US").matchAll(/[\p{L}\p{N}_-]{3,}/gu)]
+        .map((match) => match[0])
+        .filter((term) => !QUALITY_STOPWORDS.has(term)));
+}
+function exactPriority(fixture, candidate) {
+    const lower = candidate.text.toLocaleLowerCase("en-US");
+    return fixture.exactIdentifiers.some((identifier) => lower.includes(identifier.toLocaleLowerCase("en-US"))) ? 1 : 0;
+}
+function quality(fixture, strategy, selectedIds, fallback) {
+    const expected = new Set(fixture.expectedEvidenceIds);
+    const selected = new Set(selectedIds);
+    const recalled = fixture.expectedEvidenceIds.filter((id) => selected.has(id)).length;
+    const selectedCandidates = fixture.candidates.filter((candidate) => selected.has(candidate.id));
+    const selectedTokens = selectedCandidates.reduce((total, candidate) => total + candidate.tokens, 0);
+    const irrelevantTokens = selectedCandidates
+        .filter((candidate) => !expected.has(candidate.id))
+        .reduce((total, candidate) => total + candidate.tokens, 0);
+    return {
+        strategy,
+        evidenceRecall: expected.size > 0 ? rounded(recalled / expected.size) : 1,
+        irrelevantTokenRatio: selectedTokens > 0 ? rounded(irrelevantTokens / selectedTokens) : 0,
+        selectedEvidenceIds: [...selectedIds],
+        fallback,
+    };
+}
+function lexicalRanking(fixture) {
+    const queryTerms = terms(fixture.query);
+    return fixture.candidates.map((candidate) => {
+        const candidateTerms = terms(candidate.text);
+        const overlap = [...queryTerms].filter((term) => candidateTerms.has(term)).length;
+        return {
+            id: candidate.id,
+            score: exactPriority(fixture, candidate) * 1_000 + overlap,
+        };
+    }).filter((candidate) => candidate.score > 0).sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+}
+export function compareHybridRetrievalCorpus(corpus, port) {
+    const fixtures = corpus.fixtures.map((fixture) => {
+        const lexical = lexicalRanking(fixture);
+        const lexicalIds = lexical.slice(0, fixture.maxResults).map((candidate) => candidate.id);
+        let hybridIds = lexicalIds;
+        let fallback = false;
+        try {
+            const vectors = port.embed([fixture.query, ...fixture.candidates.map((candidate) => candidate.text)]);
+            const queryVector = vectors[0];
+            if (!queryVector || vectors.length !== fixture.candidates.length + 1
+                || !validEmbeddingVector(queryVector, port.identity.dimensions)) {
+                throw new Error("invalid embedding batch");
+            }
+            const lexicalOrder = new Map(lexical.map((candidate, rank) => [candidate.id, rank]));
+            const vectorCandidates = fixture.candidates.flatMap((candidate, index) => {
+                const vector = vectors[index + 1];
+                if (!vector || !validEmbeddingVector(vector, port.identity.dimensions))
+                    return [];
+                const similarity = cosineSimilarity(queryVector, vector);
+                return similarity === undefined || similarity < 0.1 ? [] : [{ candidate, similarity }];
+            }).sort((left, right) => right.similarity - left.similarity || left.candidate.id.localeCompare(right.candidate.id));
+            const vectorOrder = new Map(vectorCandidates.map((item, rank) => [item.candidate.id, rank]));
+            const similarityById = new Map(vectorCandidates.map((item) => [item.candidate.id, item.similarity]));
+            const hybrid = fixture.candidates.filter((candidate) => lexicalOrder.has(candidate.id) || vectorOrder.has(candidate.id)).map((candidate) => {
+                const similarity = similarityById.get(candidate.id) ?? 0;
+                const score = exactPriority(fixture, candidate) * 1_000_000
+                    + Math.max(0, similarity) * 80
+                    + reciprocalRankFusion([
+                        { rank: lexicalOrder.get(candidate.id), weight: 1 },
+                        { rank: vectorOrder.get(candidate.id), weight: 1 },
+                    ]) * 1_500;
+                return { id: candidate.id, score };
+            }).sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+            hybridIds = hybrid.slice(0, fixture.maxResults).map((candidate) => candidate.id);
+        }
+        catch {
+            fallback = true;
+        }
+        return {
+            fixtureId: fixture.id,
+            lexical: quality(fixture, "lexical-only", lexicalIds, false),
+            hybrid: quality(fixture, "hybrid", hybridIds, fallback),
+        };
+    });
+    const average = (values) => values.length > 0
+        ? rounded(values.reduce((total, value) => total + value, 0) / values.length)
+        : 0;
+    const lexicalEvidenceRecall = average(fixtures.map((fixture) => fixture.lexical.evidenceRecall));
+    const hybridEvidenceRecall = average(fixtures.map((fixture) => fixture.hybrid.evidenceRecall));
+    const lexicalIrrelevantTokenRatio = average(fixtures.map((fixture) => fixture.lexical.irrelevantTokenRatio));
+    const hybridIrrelevantTokenRatio = average(fixtures.map((fixture) => fixture.hybrid.irrelevantTokenRatio));
+    return {
+        metricsVersion: HYBRID_RETRIEVAL_QUALITY_VERSION,
+        corpusVersion: corpus.corpusVersion,
+        model: {
+            provider: port.identity.provider,
+            model: port.identity.model,
+            dimensions: port.identity.dimensions,
+        },
+        fixtures,
+        aggregate: {
+            lexicalEvidenceRecall,
+            hybridEvidenceRecall,
+            evidenceRecallDelta: rounded(hybridEvidenceRecall - lexicalEvidenceRecall),
+            lexicalIrrelevantTokenRatio,
+            hybridIrrelevantTokenRatio,
+            irrelevantTokenRatioDelta: rounded(hybridIrrelevantTokenRatio - lexicalIrrelevantTokenRatio),
+            fallbackCount: fixtures.filter((fixture) => fixture.hybrid.fallback).length,
+        },
+    };
+}
+//# sourceMappingURL=semantic-quality.js.map

package/dist/retrieval/semantic-quality.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-core",
-  "version": "0.1.2",
+  "version": "0.2.0-beta.2",
   "description": "Runtime-neutral context planning, retrieval, compaction, memory, and privacy for agent runtimes.",
   "type": "module",
   "license": "MIT",