noteconnection 1.8.0 → 1.9.0

package/dist/src/learning/graphAnswerCoverage.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reviewGraphAnswerCoverage = reviewGraphAnswerCoverage;
+const graphClaimMatcher_1 = require("./graphClaimMatcher");
+function reviewGraphAnswerCoverage(answer, plan) {
+    const requiredClaims = (plan?.claims || []).filter((claim) => claim.required);
+    if (requiredClaims.length === 0) {
+        return {
+            passed: true,
+            applicable: false,
+            requiredClaimIds: [],
+            coveredClaimIds: [],
+            missingRequiredClaimIds: [],
+            coverageScore: 1,
+        };
+    }
+    const coveredClaimIds = requiredClaims
+        .filter((claim) => {
+        const answerKey = String(answer || '').replace(/\s+/gu, '');
+        const statementKey = String(claim.statement || '').replace(/\s+/gu, '');
+        return Boolean(statementKey && answerKey.includes(statementKey))
+            || (0, graphClaimMatcher_1.matchGraphAnswerClaim)(answer, claim.statement).covered;
+    })
+        .map((claim) => claim.claimId);
+    const covered = new Set(coveredClaimIds);
+    const missingRequiredClaimIds = requiredClaims
+        .filter((claim) => !covered.has(claim.claimId))
+        .map((claim) => claim.claimId);
+    return {
+        passed: missingRequiredClaimIds.length === 0,
+        applicable: true,
+        requiredClaimIds: requiredClaims.map((claim) => claim.claimId),
+        coveredClaimIds,
+        missingRequiredClaimIds,
+        coverageScore: Number((coveredClaimIds.length / requiredClaims.length).toFixed(4)),
+    };
+}

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const graphAnswerCoverage_1 = require("./graphAnswerCoverage");
+const plan = {
+    intent: 'definition',
+    depth: 'standard',
+    anchorAtomId: 'water_glass',
+    leadClaimId: 'definition',
+    requiredRoles: ['definition', 'boundary', 'mechanism'],
+    omittedCandidates: [],
+    claims: [
+        {
+            claimId: 'definition',
+            role: 'definition',
+            required: true,
+            priority: 100,
+            statement: 'A water glass is a transparent drinking vessel containing water.',
+            subjectAtomId: 'water_glass',
+            supportingAtomIds: [],
+            supportingEdgeIds: [],
+            evidenceRefs: [],
+            confidence: 0.98,
+        },
+        {
+            claimId: 'boundary',
+            role: 'boundary',
+            required: true,
+            priority: 84,
+            statement: 'The solid wall forms a material boundary between the liquid and the environment.',
+            subjectAtomId: 'water_glass',
+            supportingAtomIds: ['material_boundary'],
+            supportingEdgeIds: [],
+            evidenceRefs: [],
+            confidence: 0.91,
+        },
+        {
+            claimId: 'mechanism',
+            role: 'mechanism',
+            required: true,
+            priority: 82,
+            statement: 'Heat moves through the glass wall and its thickness affects thermal exchange.',
+            subjectAtomId: 'water_glass',
+            supportingAtomIds: ['thermal_exchange'],
+            supportingEdgeIds: ['edge_heat'],
+            evidenceRefs: [],
+            confidence: 0.9,
+        },
+    ],
+};
+describe('reviewGraphAnswerCoverage', () => {
+    test('passes when every required graph claim is represented with natural paraphrasing', () => {
+        const review = (0, graphAnswerCoverage_1.reviewGraphAnswerCoverage)('A water glass is a transparent vessel for water. Its solid wall separates the liquid from the surrounding environment. Heat passes through that glass wall, and wall thickness changes the rate of thermal exchange.', plan);
+        expect(review.passed).toBe(true);
+        expect(review.missingRequiredClaimIds).toEqual([]);
+        expect(review.coverageScore).toBe(1);
+    });
+    test('fails when a high-confidence mechanism claim is dropped from the public answer', () => {
+        const review = (0, graphAnswerCoverage_1.reviewGraphAnswerCoverage)('A water glass is a transparent drinking vessel containing water. Its solid wall forms a material boundary between the liquid and the environment.', plan);
+        expect(review.passed).toBe(false);
+        expect(review.missingRequiredClaimIds).toEqual(['mechanism']);
+        expect(review.coverageScore).toBeCloseTo(2 / 3, 4);
+    });
+    test('does not count a negated paraphrase as coverage', () => {
+        const review = (0, graphAnswerCoverage_1.reviewGraphAnswerCoverage)('A water glass is a transparent drinking vessel containing water. Its wall does not separate the liquid from the environment. Heat does not move through the glass wall and thickness has no effect on thermal exchange.', plan);
+        expect(review.coveredClaimIds).toEqual(['definition']);
+        expect(review.missingRequiredClaimIds).toEqual(['boundary', 'mechanism']);
+    });
+    test('covers conservative Chinese paraphrases without requiring exact source wording', () => {
+        const chinesePlan = {
+            ...plan,
+            claims: [
+                {
+                    ...plan.claims[0],
+                    claimId: 'definition_zh',
+                    statement: '水杯是用于盛水的透明饮用容器。',
+                },
+                {
+                    ...plan.claims[1],
+                    claimId: 'boundary_zh',
+                    statement: '坚固杯壁在液体和外部环境之间形成材料边界。',
+                },
+                {
+                    ...plan.claims[2],
+                    claimId: 'mechanism_zh',
+                    statement: '热量会穿过杯壁，杯壁厚度会影响热交换。',
+                },
+            ],
+        };
+        const review = (0, graphAnswerCoverage_1.reviewGraphAnswerCoverage)('水杯是一种透明的盛水容器。它的实体杯壁把液体与周围环境隔开；热可以经由玻璃壁传递，而壁厚会改变换热速度。', chinesePlan);
+        expect(review.passed).toBe(true);
+        expect(review.coveredClaimIds).toEqual(['definition_zh', 'boundary_zh', 'mechanism_zh']);
+    });
+});

package/dist/src/learning/graphAnswerCoverageCalibration.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRAPH_ANSWER_COVERAGE_CALIBRATION_CASES = void 0;
+exports.evaluateGraphAnswerCoverageCalibration = evaluateGraphAnswerCoverageCalibration;
+const graphClaimMatcher_1 = require("./graphClaimMatcher");
+exports.DEFAULT_GRAPH_ANSWER_COVERAGE_CALIBRATION_CASES = [
+    { caseId: 'definition_en_positive', statement: 'A water glass is a transparent container for water.', answer: 'A water glass is a transparent vessel used to hold water.', expectedCovered: true },
+    { caseId: 'definition_en_negative', statement: 'A water glass is a transparent container for water.', answer: 'A water glass is not a transparent container for water.', expectedCovered: false },
+    { caseId: 'definition_zh_positive', statement: '水杯是用于盛水的透明容器。', answer: '水杯是一种透明的盛水器皿。', expectedCovered: true },
+    { caseId: 'definition_zh_negative', statement: '水杯是用于盛水的透明容器。', answer: '水杯并不是用于盛水的透明容器。', expectedCovered: false },
+    { caseId: 'causal_en_positive', statement: 'Heating the sealed glass causes pressure to rise.', answer: 'Pressure rises because heat enters the sealed glass.', expectedCovered: true },
+    { caseId: 'causal_en_negative', statement: 'Heating the sealed glass causes pressure to rise.', answer: 'Heating the sealed glass does not cause pressure to rise.', expectedCovered: false },
+    { caseId: 'causal_zh_positive', statement: '加热密闭玻璃容器会导致压力上升。', answer: '密闭玻璃容器受热后会造成压力升高。', expectedCovered: true },
+    { caseId: 'causal_zh_negative', statement: '加热密闭玻璃容器会导致压力上升。', answer: '加热密闭玻璃容器不会导致压力上升。', expectedCovered: false },
+    { caseId: 'compare_en_positive', statement: 'Glass conducts heat better than plastic.', answer: 'Compared with plastic, glass conducts heat better.', expectedCovered: true },
+    { caseId: 'compare_en_negative', statement: 'Glass conducts heat better than plastic.', answer: 'Glass does not conduct heat better than plastic.', expectedCovered: false },
+    { caseId: 'compare_zh_positive', statement: '玻璃比塑料导热更快。', answer: '与塑料相比，玻璃导热更快。', expectedCovered: true },
+    { caseId: 'compare_zh_negative', statement: '玻璃比塑料导热更快。', answer: '玻璃并不比塑料导热更快。', expectedCovered: false },
+    { caseId: 'procedure_en_positive', statement: 'Rinse the glass before drying it.', answer: 'Before drying the glass, rinse it thoroughly.', expectedCovered: true },
+    { caseId: 'procedure_en_negative', statement: 'Rinse the glass before drying it.', answer: 'Do not rinse the glass before drying it.', expectedCovered: false },
+    { caseId: 'procedure_zh_positive', statement: '先冲洗杯子，再将它晾干。', answer: '杯子需要先冲洗，之后再晾干。', expectedCovered: true },
+    { caseId: 'procedure_zh_negative', statement: '先冲洗杯子，再将它晾干。', answer: '不要先冲洗杯子再晾干。', expectedCovered: false },
+    { caseId: 'temporal_en_positive', statement: 'This guidance applies after 2025.', answer: 'After 2025, this guidance applies.', expectedCovered: true },
+    { caseId: 'temporal_en_negative', statement: 'This guidance applies after 2025.', answer: 'This guidance does not apply after 2025.', expectedCovered: false },
+    { caseId: 'temporal_zh_positive', statement: '该规则在2025年之后生效。', answer: '2025年以后，该规则开始生效。', expectedCovered: true },
+    { caseId: 'temporal_zh_negative', statement: '该规则在2025年之后生效。', answer: '该规则在2025年之后不会生效。', expectedCovered: false },
+    { caseId: 'weak_evidence_en_positive', statement: 'Heat passing through the wall raises the liquid temperature.', answer: 'The liquid temperature rises as heat passes through the wall.', expectedCovered: true },
+    { caseId: 'weak_evidence_en_negative', statement: 'Heat passing through the wall raises the liquid temperature.', answer: 'The graph contains a node titled Liquid Temperature.', expectedCovered: false },
+    { caseId: 'weak_evidence_zh_positive', statement: '热量穿过杯壁会使液体温度上升。', answer: '液体温度会随着热量经杯壁传递而升高。', expectedCovered: true },
+    { caseId: 'weak_evidence_zh_negative', statement: '热量穿过杯壁会使液体温度上升。', answer: '图中存在一个名为“液体温度”的节点。', expectedCovered: false },
+];
+function evaluateGraphAnswerCoverageCalibration(cases) {
+    const falsePositiveCaseIds = [];
+    const falseNegativeCaseIds = [];
+    let truePositiveCount = 0;
+    let trueNegativeCount = 0;
+    cases.forEach((item) => {
+        const covered = (0, graphClaimMatcher_1.matchGraphAnswerClaim)(item.answer, item.statement).covered;
+        if (covered && item.expectedCovered)
+            truePositiveCount += 1;
+        else if (!covered && !item.expectedCovered)
+            trueNegativeCount += 1;
+        else if (covered)
+            falsePositiveCaseIds.push(item.caseId);
+        else
+            falseNegativeCaseIds.push(item.caseId);
+    });
+    const precisionDenominator = truePositiveCount + falsePositiveCaseIds.length;
+    const recallDenominator = truePositiveCount + falseNegativeCaseIds.length;
+    return {
+        sampleCount: cases.length,
+        truePositiveCount,
+        trueNegativeCount,
+        falsePositiveCaseIds,
+        falseNegativeCaseIds,
+        precision: precisionDenominator > 0 ? Number((truePositiveCount / precisionDenominator).toFixed(4)) : 1,
+        recall: recallDenominator > 0 ? Number((truePositiveCount / recallDenominator).toFixed(4)) : 1,
+    };
+}

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const graphAnswerCoverageCalibration_1 = require("./graphAnswerCoverageCalibration");
+describe('evaluateGraphAnswerCoverageCalibration', () => {
+    test('reports false positives and false negatives separately', () => {
+        const report = (0, graphAnswerCoverageCalibration_1.evaluateGraphAnswerCoverageCalibration)([
+            {
+                caseId: 'positive_en',
+                statement: 'Heat moves through the glass wall.',
+                answer: 'Thermal energy passes through the glass wall.',
+                expectedCovered: true,
+            },
+            {
+                caseId: 'negative_en',
+                statement: 'Heat moves through the glass wall.',
+                answer: 'Heat does not move through the glass wall.',
+                expectedCovered: false,
+            },
+            {
+                caseId: 'positive_zh',
+                statement: '杯壁把液体与环境隔开。',
+                answer: '实体杯壁将杯中液体和外部环境分隔开。',
+                expectedCovered: true,
+            },
+            {
+                caseId: 'negative_zh',
+                statement: '杯壁把液体与环境隔开。',
+                answer: '杯壁并不能把液体与外部环境隔开。',
+                expectedCovered: false,
+            },
+        ]);
+        expect(report.sampleCount).toBe(4);
+        expect(report.falsePositiveCaseIds).toEqual([]);
+        expect(report.falseNegativeCaseIds).toEqual([]);
+        expect(report.precision).toBe(1);
+        expect(report.recall).toBe(1);
+    });
+    test('meets the release floor across the versioned multilingual intent corpus', () => {
+        const report = (0, graphAnswerCoverageCalibration_1.evaluateGraphAnswerCoverageCalibration)(graphAnswerCoverageCalibration_1.DEFAULT_GRAPH_ANSWER_COVERAGE_CALIBRATION_CASES);
+        expect(report.sampleCount).toBeGreaterThanOrEqual(24);
+        expect(report.falsePositiveCaseIds).toEqual([]);
+        expect(report.falseNegativeCaseIds).toEqual([]);
+        expect(report.precision).toBeGreaterThanOrEqual(0.95);
+        expect(report.recall).toBeGreaterThanOrEqual(0.95);
+    });
+});

package/dist/src/learning/graphAnswerFacts.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatGraphAnswerProfileSentence = formatGraphAnswerProfileSentence;
+exports.collectGraphAnswerWindowTitles = collectGraphAnswerWindowTitles;
+exports.collectGraphAnswerFacts = collectGraphAnswerFacts;
+function formatGraphAnswerProfileSentence(facts, useChinese) {
+    const { anchorTitle, predecessorTitles, successorTitles } = facts;
+    const degreeParts = [];
+    if (facts.inDegree !== null) {
+        degreeParts.push(useChinese ? `入度为 ${facts.inDegree}` : `${facts.inDegree} incoming`);
+    }
+    if (facts.outDegree !== null) {
+        degreeParts.push(useChinese ? `出度为 ${facts.outDegree}` : `${facts.outDegree} outgoing`);
+    }
+    if (degreeParts.length <= 0 && predecessorTitles.length <= 0 && successorTitles.length <= 0) {
+        return '';
+    }
+    if (useChinese) {
+        const fragments = [];
+        if (degreeParts.length > 0) {
+            fragments.push(`${anchorTitle || '当前锚点'}在当前图中的${degreeParts.join('，')}`);
+        }
+        if (predecessorTitles.length > 0) {
+            fragments.push(`紧邻前置节点包括 ${predecessorTitles.join('、')}`);
+        }
+        if (successorTitles.length > 0) {
+            fragments.push(`后续分支包括 ${successorTitles.join('、')}`);
+        }
+        return fragments.join('，');
+    }
+    const fragments = [];
+    if (degreeParts.length > 0) {
+        fragments.push(`${anchorTitle || 'The current anchor'} has ${degreeParts.join(' and ')} links in the current graph`);
+    }
+    if (predecessorTitles.length > 0 && successorTitles.length > 0) {
+        fragments.push(`The graph connects this topic to upstream evidence from ${predecessorTitles.join(', ')} and downstream evidence from ${successorTitles.join(', ')}`);
+    }
+    else if (predecessorTitles.length > 0) {
+        fragments.push(`The graph connects this topic to upstream evidence from ${predecessorTitles.join(', ')}`);
+    }
+    else if (successorTitles.length > 0) {
+        fragments.push(`The graph connects this topic to downstream evidence from ${successorTitles.join(', ')}`);
+    }
+    return fragments.join('; ');
+}
+function normalizeAtomId(value) {
+    return String(value || '').trim();
+}
+function normalizeComparableTitle(value) {
+    return value.toLowerCase();
+}
+function collectGraphAnswerWindowTitles(graphContext, windowKey, selection, limit) {
+    const anchorAtomId = normalizeAtomId(selection.anchorAtomId);
+    const anchorTitle = normalizeComparableTitle(selection.normalizeTitle(selection.anchorTitle));
+    const seen = new Set();
+    const titles = [];
+    for (const node of graphContext[windowKey] || []) {
+        const atomId = normalizeAtomId(node && node.atomId);
+        const title = selection.normalizeTitle(node && node.title);
+        const comparableTitle = normalizeComparableTitle(title);
+        if (!title || (atomId && atomId === anchorAtomId) || (comparableTitle && comparableTitle === anchorTitle)) {
+            continue;
+        }
+        const key = comparableTitle || atomId;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        titles.push(title);
+        if (titles.length >= limit) {
+            break;
+        }
+    }
+    return titles;
+}
+function finiteNumber(value) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : null;
+}
+function collectGraphAnswerFacts(graphContext, selection, windowLimit = 2) {
+    if (!graphContext) {
+        return null;
+    }
+    const anchorProfile = graphContext.anchorGraphProfile && typeof graphContext.anchorGraphProfile === 'object'
+        ? graphContext.anchorGraphProfile
+        : null;
+    return {
+        anchorTitle: selection.normalizeTitle(selection.anchorTitle),
+        inDegree: finiteNumber(anchorProfile?.inDegree),
+        outDegree: finiteNumber(anchorProfile?.outDegree),
+        predecessorTitles: collectGraphAnswerWindowTitles(graphContext, 'predecessorWindow', selection, windowLimit),
+        successorTitles: collectGraphAnswerWindowTitles(graphContext, 'successorWindow', selection, windowLimit),
+    };
+}

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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const graphAnswerFacts_1 = require("./graphAnswerFacts");
+function makeGraphContext() {
+    return {
+        anchorAtomId: 'anchor',
+        anchorTitle: 'Anchor',
+        anchorGraphProfile: { atomId: 'anchor', title: 'Anchor', inDegree: 2, outDegree: 3 },
+        predecessorWindow: [
+            { atomId: 'anchor', title: 'Anchor' },
+            { atomId: 'predecessor', title: 'Upstream Node' },
+            { atomId: 'duplicate', title: 'upstream node' },
+        ],
+        successorWindow: [{ atomId: 'successor', title: 'Downstream Node' }],
+    };
+}
+describe('collectGraphAnswerFacts', () => {
+    test('deduplicates windows and excludes the anchor by atom or title', () => {
+        const facts = (0, graphAnswerFacts_1.collectGraphAnswerFacts)(makeGraphContext(), {
+            anchorAtomId: 'anchor',
+            anchorTitle: 'Anchor',
+            normalizeTitle: (value) => String(value || '').trim(),
+        });
+        expect(facts).toEqual({
+            anchorTitle: 'Anchor',
+            inDegree: 2,
+            outDegree: 3,
+            predecessorTitles: ['Upstream Node'],
+            successorTitles: ['Downstream Node'],
+        });
+    });
+    test('returns no facts when graph context is unavailable', () => {
+        expect((0, graphAnswerFacts_1.collectGraphAnswerFacts)(null, {
+            anchorAtomId: '',
+            anchorTitle: '',
+            normalizeTitle: (value) => String(value || '').trim(),
+        })).toBeNull();
+    });
+});