noteconnection 1.6.8 → 1.8.0

package/dist/src/learning/ragSufficiencyJudge.test.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ragSufficiencyJudge_1 = require("./ragSufficiencyJudge");
+function makeFragment(overrides = {}) {
+    const text = overrides.text || 'A water glass is a transparent drinking vessel that contains water.';
+    return {
+        fragmentId: overrides.fragmentId || `fragment_${overrides.role || 'direct_support'}`,
+        role: overrides.role || 'direct_support',
+        text,
+        atomId: overrides.atomId || 'atom_water_glass',
+        documentId: overrides.documentId || 'doc_water_glass',
+        sourcePath: overrides.sourcePath || 'Knowledge_Base/test/water-glass.md',
+        title: overrides.title || 'Water Glass',
+        headingPath: Array.isArray(overrides.headingPath) ? overrides.headingPath : ['Water Glass'],
+        startOffset: overrides.startOffset,
+        endOffset: overrides.endOffset,
+        startLine: overrides.startLine,
+        endLine: overrides.endLine,
+        charCount: text.length,
+        tokenEstimate: Math.ceil(text.length / 4),
+        truncated: overrides.truncated === true,
+        truncationReason: overrides.truncationReason,
+        citationIds: Array.isArray(overrides.citationIds) ? overrides.citationIds : ['evidence_water_glass'],
+        relationEdgeIds: Array.isArray(overrides.relationEdgeIds) ? overrides.relationEdgeIds : [],
+        score: Number.isFinite(overrides.score) ? Number(overrides.score) : 0.8,
+        sourceBoundary: overrides.sourceBoundary || 'direct_span_only',
+    };
+}
+function makePack(fragments) {
+    return {
+        query: 'what is water glass?',
+        generatedAt: '2026-07-05T00:00:00.000Z',
+        sourceBoundary: fragments.some((fragment) => fragment.sourceBoundary === 'full_document')
+            ? 'full_document'
+            : 'direct_span_only',
+        budget: {
+            maxFragments: 8,
+            maxCharsPerFragment: 800,
+            maxTotalChars: 2400,
+        },
+        fragments,
+        sourceDecisions: [],
+        totalCharCount: fragments.reduce((sum, fragment) => sum + fragment.charCount, 0),
+        tokenEstimate: fragments.reduce((sum, fragment) => sum + fragment.tokenEstimate, 0),
+    };
+}
+describe('reviewRagContextSufficiency', () => {
+    test('marks direct citation plus document augmentation as sufficient without using LLM review', async () => {
+        const llmJudge = jest.fn();
+        const review = await (0, ragSufficiencyJudge_1.reviewRagContextSufficiency)({
+            query: 'what is water glass?',
+            contextPack: makePack([
+                makeFragment({
+                    role: 'direct_support',
+                    text: 'A water glass is a transparent drinking vessel that contains water.',
+                }),
+                makeFragment({
+                    role: 'parent_context',
+                    text: '## Definition\n\nA water glass is a transparent drinking vessel that contains water.\n\nThe vessel boundary and water surface define the observed optical behavior.',
+                    sourceBoundary: 'full_document',
+                }),
+            ]),
+            llmJudge,
+        });
+        expect(review.status).toBe('sufficient');
+        expect(review.score).toBeGreaterThanOrEqual(0.75);
+        expect(review.deterministic).toBe(true);
+        expect(review.llmJudgeUsed).toBe(false);
+        expect(llmJudge).not.toHaveBeenCalled();
+    });
+    test('marks missing direct support as insufficient instead of allowing fluent overreach', async () => {
+        const review = await (0, ragSufficiencyJudge_1.reviewRagContextSufficiency)({
+            query: 'what is water glass?',
+            contextPack: makePack([
+                makeFragment({
+                    role: 'background',
+                    text: 'Background note about liquids and containers.',
+                    citationIds: [],
+                }),
+            ]),
+        });
+        expect(review.status).toBe('insufficient');
+        expect(review.degradationState).toBe('insufficient_evidence');
+        expect(review.reasons).toContain('missing_direct_support');
+    });
+    test('keeps direct-span-only answers borderline so callers can recover once', async () => {
+        const review = await (0, ragSufficiencyJudge_1.reviewRagContextSufficiency)({
+            query: 'what is water glass?',
+            contextPack: makePack([
+                makeFragment({
+                    role: 'direct_support',
+                    text: 'A water glass is a transparent drinking vessel that contains water.',
+                }),
+            ]),
+        });
+        expect(review.status).toBe('borderline');
+        expect(review.degradationState).toBe('partial_coverage');
+        expect(review.reasons).toEqual(expect.arrayContaining([
+            'document_augmentation_missing',
+        ]));
+    });
+    test('degrades graph evidence when graph-neighbor source windows are unavailable', async () => {
+        const pack = makePack([
+            makeFragment({
+                role: 'direct_support',
+                text: 'A brittle glass vessel is stiff and transparent but has low impact tolerance.',
+                documentId: 'doc_brittle_glass',
+                sourcePath: 'Knowledge_Base/test/brittle-glass.md',
+            }),
+            makeFragment({
+                role: 'parent_context',
+                text: '# Brittle Glass Vessel\n\nA brittle glass vessel is stiff and transparent but has low impact tolerance.',
+                documentId: 'doc_brittle_glass',
+                sourcePath: 'Knowledge_Base/test/brittle-glass.md',
+                sourceBoundary: 'full_document',
+            }),
+            makeFragment({
+                role: 'graph_neighbor_support',
+                text: 'Missing neighbor evidence should not be treated as complete graph evidence.',
+                atomId: 'atom_missing_neighbor',
+                documentId: 'doc_missing_neighbor',
+                sourcePath: 'Knowledge_Base/test/missing-neighbor.md',
+                title: 'Missing Neighbor Evidence',
+                sourceBoundary: 'direct_span_only',
+            }),
+        ]);
+        pack.sourceDecisions = [
+            {
+                documentId: 'doc_brittle_glass',
+                sourcePath: 'Knowledge_Base/test/brittle-glass.md',
+                sourceBoundary: 'full_document',
+                status: 'read',
+            },
+            {
+                documentId: 'doc_missing_neighbor',
+                sourcePath: 'Knowledge_Base/test/missing-neighbor.md',
+                sourceBoundary: 'direct_span_only',
+                status: 'source_window_unavailable',
+                reason: 'source_resolver_returned_no_content:graph_neighbor_support',
+            },
+        ];
+        const review = await (0, ragSufficiencyJudge_1.reviewRagContextSufficiency)({
+            query: 'compare brittle glass vessel with missing neighbor evidence',
+            contextPack: pack,
+            graphContext: {
+                anchorAtomId: 'atom_brittle_glass',
+                anchorTitle: 'Brittle Glass Vessel',
+                anchorDocumentId: 'doc_brittle_glass',
+                predecessorWindow: [],
+                successorWindow: [
+                    {
+                        atomId: 'atom_missing_neighbor',
+                        title: 'Missing Neighbor Evidence',
+                        relationKind: 'analogy',
+                        confidence: 0.91,
+                    },
+                ],
+                supportingAtomIds: ['atom_missing_neighbor'],
+                supportingTitles: ['Missing Neighbor Evidence'],
+                relationKinds: ['analogy'],
+                relationSummaries: [],
+                knowledgePointRelations: [],
+                temporalValidity: {
+                    checkedAt: '2026-07-05T00:00:00.000Z',
+                    allPointsValid: true,
+                    warningReasons: [],
+                    invalidKnowledgePointTitles: [],
+                    edgeKinds: [],
+                    details: [],
+                },
+            },
+        });
+        expect(review.status).toBe('borderline');
+        expect(review.degradationState).toBe('partial_coverage');
+        expect(review.reasons).toContain('graph_neighbor_evidence_missing');
+    });
+});

package/dist/src/learning/ragSufficiencyProviderJudge.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRagSufficiencyProviderJudgeReview = parseRagSufficiencyProviderJudgeReview;
+exports.createRagSufficiencyProviderJudge = createRagSufficiencyProviderJudge;
+const LlmProvider_1 = require("../notemd/LlmProvider");
+const RAG_SUFFICIENCY_TASK_KEY = 'ragSufficiencyJudge';
+const DEFAULT_TIMEOUT_MS = 4000;
+const DEFAULT_MAX_TOKENS = 320;
+const MIN_TIMEOUT_MS = 250;
+const MAX_TIMEOUT_MS = 20000;
+const MIN_MAX_TOKENS = 32;
+const MAX_MAX_TOKENS = 1200;
+const VALID_STATUSES = new Set([
+    'sufficient',
+    'borderline',
+    'insufficient',
+]);
+const VALID_DEGRADATION_STATES = new Set([
+    'none',
+    'partial_coverage',
+    'conflict',
+    'stale_evidence',
+    'insufficient_evidence',
+]);
+const DEFAULT_REVIEW_PROMPT = [
+    'You are a bounded RAG sufficiency reviewer.',
+    'Decide whether the supplied RAG context is sufficient to answer the user query without unsupported claims.',
+    'Use only the supplied context. Do not produce the final answer.',
+    'Return only one JSON object with keys: status, score, reasons, degradationState.',
+    'status must be one of: sufficient, borderline, insufficient.',
+    'score must be a number from 0 to 1.',
+    'reasons must be a short string array using stable snake_case reason codes.',
+    'degradationState must be one of: none, partial_coverage, conflict, stale_evidence, insufficient_evidence.',
+].join('\n');
+function clamp(value, min, max) {
+    if (!Number.isFinite(value)) {
+        return min;
+    }
+    return Math.max(min, Math.min(max, value));
+}
+function clampUnit(value) {
+    return Number(clamp(value, 0, 1).toFixed(4));
+}
+function resolveBoundedInteger(value, fallback, min, max) {
+    const normalized = Math.floor(Number(value));
+    if (!Number.isFinite(normalized)) {
+        return fallback;
+    }
+    return Math.floor(clamp(normalized, min, max));
+}
+function cleanReason(value) {
+    return String(value || '')
+        .trim()
+        .replace(/\s+/g, '_')
+        .replace(/[^a-zA-Z0-9_:-]/g, '')
+        .slice(0, 96);
+}
+function extractJsonObjectText(text) {
+    const trimmed = String(text || '').trim();
+    const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+    const candidate = fenced ? fenced[1].trim() : trimmed;
+    if (candidate.startsWith('{') && candidate.endsWith('}')) {
+        return candidate;
+    }
+    const startIndex = candidate.indexOf('{');
+    const endIndex = candidate.lastIndexOf('}');
+    if (startIndex >= 0 && endIndex > startIndex) {
+        return candidate.slice(startIndex, endIndex + 1);
+    }
+    return candidate;
+}
+function toRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function parseRagSufficiencyProviderJudgeReview(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(extractJsonObjectText(text));
+    }
+    catch {
+        return null;
+    }
+    const record = toRecord(parsed);
+    if (!record) {
+        return null;
+    }
+    const review = {};
+    if (VALID_STATUSES.has(record.status)) {
+        review.status = record.status;
+    }
+    if (Number.isFinite(Number(record.score))) {
+        review.score = clampUnit(Number(record.score));
+    }
+    if (Array.isArray(record.reasons)) {
+        const reasons = record.reasons
+            .map(cleanReason)
+            .filter(Boolean)
+            .slice(0, 8);
+        if (reasons.length > 0) {
+            review.reasons = reasons;
+        }
+    }
+    if (VALID_DEGRADATION_STATES.has(record.degradationState)) {
+        review.degradationState = record.degradationState;
+    }
+    return Object.keys(review).length > 0 ? review : null;
+}
+function buildFragmentPayload(fragment) {
+    return {
+        role: fragment.role,
+        title: fragment.title,
+        documentId: fragment.documentId,
+        sourcePath: fragment.sourcePath,
+        headingPath: fragment.headingPath,
+        sourceBoundary: fragment.sourceBoundary,
+        citationIds: fragment.citationIds,
+        relationEdgeIds: fragment.relationEdgeIds || [],
+        score: fragment.score,
+        truncated: fragment.truncated,
+        truncationReason: fragment.truncationReason,
+        text: fragment.text,
+    };
+}
+function buildGraphPayload(graphContext) {
+    if (!graphContext) {
+        return null;
+    }
+    return {
+        anchorAtomId: graphContext.anchorAtomId,
+        anchorTitle: graphContext.anchorTitle,
+        supportingAtomIds: graphContext.supportingAtomIds || [],
+        supportingTitles: graphContext.supportingTitles || [],
+        relationKinds: graphContext.relationKinds || [],
+        relationSummaries: graphContext.relationSummaries || [],
+        predecessorWindow: graphContext.predecessorWindow || [],
+        successorWindow: graphContext.successorWindow || [],
+        temporalValidity: graphContext.temporalValidity,
+    };
+}
+function buildReviewContent(input) {
+    const pack = input.contextPack;
+    return JSON.stringify({
+        query: input.query,
+        generatedAt: pack.generatedAt,
+        sourceBoundary: pack.sourceBoundary,
+        budget: pack.budget,
+        totalCharCount: pack.totalCharCount,
+        tokenEstimate: pack.tokenEstimate,
+        sourceDecisions: pack.sourceDecisions,
+        fragments: pack.fragments.map(buildFragmentPayload),
+        graphContext: buildGraphPayload(input.graphContext),
+    });
+}
+async function completeWithTimeout(params) {
+    const controller = new AbortController();
+    let didTimeout = false;
+    let timer = null;
+    const timeoutPromise = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            didTimeout = true;
+            controller.abort();
+            reject(new Error('RAG sufficiency judge timed out.'));
+        }, params.timeoutMs);
+        params.request.signal?.addEventListener('abort', () => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            controller.abort();
+            reject(new Error('RAG sufficiency judge cancelled.'));
+        }, { once: true });
+    });
+    try {
+        return await Promise.race([
+            params.client.complete({
+                ...params.request,
+                signal: controller.signal,
+            }),
+            timeoutPromise,
+        ]);
+    }
+    catch (error) {
+        if (didTimeout) {
+            throw new Error('RAG sufficiency judge timed out.');
+        }
+        throw error;
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+function createRagSufficiencyProviderJudge(options) {
+    const client = options.llmClient || new LlmProvider_1.LlmProviderClient();
+    const timeoutMs = resolveBoundedInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    const maxTokens = resolveBoundedInteger(options.maxTokens, DEFAULT_MAX_TOKENS, MIN_MAX_TOKENS, MAX_MAX_TOKENS);
+    return async (input) => {
+        const settings = await options.settingsProvider();
+        const provider = (0, LlmProvider_1.selectProviderForTask)(settings, RAG_SUFFICIENCY_TASK_KEY);
+        const model = (0, LlmProvider_1.selectModelForTask)(settings, RAG_SUFFICIENCY_TASK_KEY, provider);
+        const configuredPrompt = settings.enableGlobalCustomPrompts
+            ? String(settings.customPrompts?.[RAG_SUFFICIENCY_TASK_KEY] || '').trim()
+            : '';
+        const result = await completeWithTimeout({
+            client,
+            timeoutMs,
+            request: {
+                provider,
+                model,
+                prompt: configuredPrompt || DEFAULT_REVIEW_PROMPT,
+                content: buildReviewContent(input),
+                maxTokens,
+                maxRetries: 0,
+                retryDelayMs: 0,
+            },
+        });
+        const review = parseRagSufficiencyProviderJudgeReview(result.text);
+        if (!review) {
+            throw new Error('RAG sufficiency judge returned invalid JSON.');
+        }
+        return review;
+    };
+}

package/dist/src/learning/ragSufficiencyProviderJudge.test.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ragSufficiencyProviderJudge_1 = require("./ragSufficiencyProviderJudge");
+function makeSettings() {
+    return {
+        providers: [
+            {
+                name: 'OpenAI',
+                apiKey: 'test-key',
+                baseUrl: 'https://example.test/v1',
+                model: 'gpt-test',
+                temperature: 0,
+                enabled: true,
+            },
+        ],
+        activeProvider: 'OpenAI',
+        useMultiModelSettings: false,
+    };
+}
+function makeFragment(overrides = {}) {
+    const text = overrides.text || 'A water glass is a transparent drinking vessel that contains water.';
+    return {
+        fragmentId: overrides.fragmentId || 'fragment_direct',
+        role: overrides.role || 'direct_support',
+        text,
+        atomId: overrides.atomId || 'atom_water_glass',
+        documentId: overrides.documentId || 'doc_water_glass',
+        sourcePath: overrides.sourcePath || 'Knowledge_Base/waterglass/water-glass.md',
+        title: overrides.title || 'Water Glass',
+        headingPath: overrides.headingPath || ['Water Glass', 'Definition'],
+        startOffset: overrides.startOffset,
+        endOffset: overrides.endOffset,
+        startLine: overrides.startLine,
+        endLine: overrides.endLine,
+        charCount: text.length,
+        tokenEstimate: Math.ceil(text.length / 4),
+        truncated: overrides.truncated === true,
+        truncationReason: overrides.truncationReason,
+        citationIds: overrides.citationIds || ['evidence_water_glass'],
+        relationEdgeIds: overrides.relationEdgeIds || [],
+        score: overrides.score ?? 0.91,
+        sourceBoundary: overrides.sourceBoundary || 'direct_span_only',
+    };
+}
+function makePack() {
+    const fragments = [
+        makeFragment(),
+        makeFragment({
+            fragmentId: 'fragment_parent',
+            role: 'parent_context',
+            sourceBoundary: 'full_document',
+            text: '## Definition\n\nA water glass is a transparent drinking vessel that contains water.',
+        }),
+    ];
+    return {
+        query: 'what is water glass?',
+        generatedAt: '2026-07-05T00:00:00.000Z',
+        sourceBoundary: 'full_document',
+        budget: {
+            maxFragments: 8,
+            maxCharsPerFragment: 800,
+            maxTotalChars: 2400,
+        },
+        fragments,
+        sourceDecisions: [],
+        totalCharCount: fragments.reduce((sum, fragment) => sum + fragment.charCount, 0),
+        tokenEstimate: fragments.reduce((sum, fragment) => sum + fragment.tokenEstimate, 0),
+    };
+}
+describe('createRagSufficiencyProviderJudge', () => {
+    test('calls the configured NoteMD provider with bounded JSON-only review input', async () => {
+        const complete = jest.fn().mockResolvedValue({
+            text: '```json\n{"status":"sufficient","score":0.84,"reasons":["answerable_from_context"],"degradationState":"none"}\n```',
+            provider: 'OpenAI',
+            model: 'gpt-test',
+        });
+        const judge = (0, ragSufficiencyProviderJudge_1.createRagSufficiencyProviderJudge)({
+            settingsProvider: makeSettings,
+            llmClient: { complete },
+            timeoutMs: 250,
+            maxTokens: 96,
+        });
+        const review = await judge({
+            query: 'what is water glass?',
+            contextPack: makePack(),
+            graphContext: null,
+        });
+        expect(review).toEqual(expect.objectContaining({
+            status: 'sufficient',
+            score: 0.84,
+            reasons: ['answerable_from_context'],
+            degradationState: 'none',
+        }));
+        expect(complete).toHaveBeenCalledTimes(1);
+        expect(complete).toHaveBeenCalledWith(expect.objectContaining({
+            provider: expect.objectContaining({ name: 'OpenAI' }),
+            model: 'gpt-test',
+            maxTokens: 96,
+            maxRetries: 0,
+            retryDelayMs: 0,
+            signal: expect.any(Object),
+        }));
+        expect(String(complete.mock.calls[0]?.[0]?.content || '')).toContain('"role":"direct_support"');
+    });
+    test('rejects on timeout so the deterministic reviewer can record a fallback reason', async () => {
+        const complete = jest.fn((request) => new Promise((_resolve, reject) => {
+            request.signal.addEventListener('abort', () => {
+                reject(new Error('Operation cancelled.'));
+            }, { once: true });
+        }));
+        const judge = (0, ragSufficiencyProviderJudge_1.createRagSufficiencyProviderJudge)({
+            settingsProvider: makeSettings,
+            llmClient: { complete },
+            timeoutMs: 5,
+            maxTokens: 48,
+        });
+        await expect(judge({
+            query: 'what is water glass?',
+            contextPack: makePack(),
+            graphContext: null,
+        })).rejects.toThrow(/cancelled|timed out/i);
+    });
+    test('rejects malformed completion text so the deterministic reviewer can record a fallback reason', async () => {
+        const complete = jest.fn().mockResolvedValue({
+            text: 'not json',
+            provider: 'OpenAI',
+            model: 'gpt-test',
+        });
+        const judge = (0, ragSufficiencyProviderJudge_1.createRagSufficiencyProviderJudge)({
+            settingsProvider: makeSettings,
+            llmClient: { complete },
+            timeoutMs: 250,
+            maxTokens: 96,
+        });
+        await expect(judge({
+            query: 'what is water glass?',
+            contextPack: makePack(),
+            graphContext: null,
+        })).rejects.toThrow(/invalid json/i);
+    });
+});
+describe('parseRagSufficiencyProviderJudgeReview', () => {
+    test('parses fenced JSON and discards invalid review fields', () => {
+        expect((0, ragSufficiencyProviderJudge_1.parseRagSufficiencyProviderJudgeReview)([
+            '```json',
+            '{"status":"sufficient","score":1.2,"reasons":[" complete ",""],"degradationState":"none","deterministic":true}',
+            '```',
+        ].join('\n'))).toEqual({
+            status: 'sufficient',
+            score: 1,
+            reasons: ['complete'],
+            degradationState: 'none',
+        });
+        expect((0, ragSufficiencyProviderJudge_1.parseRagSufficiencyProviderJudgeReview)('not json')).toBeNull();
+    });
+});