Phase 2: Chapter predictor with scoped semantic search - fixes brake pads issue

Root cause fix for "brake pads for cars" returning wrong heading (8701 Tractors
instead of 8708 Brakes).

Problem: Functional override correctly forced Ch.87, but hierarchical navigation
picked the FIRST heading instead of the semantically BEST heading.

Solution: Use scoped semantic search within the forced chapter to find the
correct heading based on query meaning.

New files:
- chapter-predictor.service.ts: Predicts chapters, handles functional overrides
  and ambiguous terms
- test-phase2.ts, test-root-fix.ts: Test scripts for validation

Key changes:
- multi-candidate-search.service.ts:
  - Added getScopedSemanticCandidates() for chapter-scoped search
  - Added getBestHeadingInChapter() using MAX score (not average)
  - Fixed aggregation to prioritize highest individual score

- llm-navigator.service.ts:
  - Updated functional override handling to use semantic search
  - Now finds 8708 (brakes) instead of 8701 (tractors)

- chapter-triggers.json:
  - Added more vehicle part keywords (shock absorber, steering, etc.)

Test results (6/7 passed):
- ✅ "brake pads for cars" → 8708.30.00
- ✅ "ceramic brake pads" → 8708
- ✅ "automotive brake disc" → 8708
- ✅ "car shock absorber" → 8708
- ✅ "wooden furniture" → 9403
- ✅ "stainless steel vacuum flask" → 9617

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: AryanBV

backend/scripts/test-phase2.ts

@@ -0,0 +1,264 @@
+/**
+ * PHASE 2: Chapter Predictor Test Script
+ *
+ * Tests the chapter predictor functionality including:
+ * - Functional overrides (brake pads, toys, furniture, vacuum flasks)
+ * - Ambiguous terms (coffee, tea)
+ * - Chapter predictions
+ *
+ * Run with: npx ts-node scripts/test-phase2.ts
+ */
+
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Import the chapter predictor functions
+import {
+  predictChapters,
+  checkFunctionalOverrides,
+  checkAmbiguousTerms,
+  explainChapterPredictions,
+  getPredictedChaptersArray
+} from '../src/services/chapter-predictor.service';
+
+// Import the multi-candidate search to test full flow
+import { semanticSearchMulti } from '../src/services/multi-candidate-search.service';
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m',
+};
+
+function log(msg: string, color = colors.reset) {
+  console.log(`${color}${msg}${colors.reset}`);
+}
+
+interface TestCase {
+  query: string;
+  expectedChapter: string;
+  testType: 'functional_override' | 'ambiguous' | 'prediction' | 'full_search';
+  description: string;
+}
+
+const testCases: TestCase[] = [
+  // CRITICAL: Functional override tests - these must pass
+  {
+    query: 'brake pads for cars',
+    expectedChapter: '87',
+    testType: 'functional_override',
+    description: 'Brake pads should go to Ch.87 (vehicle parts), NOT cosmetic pads'
+  },
+  {
+    query: 'ceramic brake pads',
+    expectedChapter: '87',
+    testType: 'functional_override',
+    description: 'Ceramic brake pads should go to Ch.87 (vehicle parts), NOT ceramics Ch.69'
+  },
+  {
+    query: 'automotive brake pads',
+    expectedChapter: '87',
+    testType: 'functional_override',
+    description: 'Automotive brake pads should go to Ch.87'
+  },
+  {
+    query: 'plastic toys',
+    expectedChapter: '95',
+    testType: 'functional_override',
+    description: 'Plastic toys should go to Ch.95 (toys), NOT plastics Ch.39'
+  },
+  {
+    query: 'wooden furniture',
+    expectedChapter: '94',
+    testType: 'functional_override',
+    description: 'Wooden furniture should go to Ch.94 (furniture), NOT wood Ch.44'
+  },
+  {
+    query: 'vacuum flask',
+    expectedChapter: '96',
+    testType: 'functional_override',
+    description: 'Vacuum flask should go to Ch.96 (miscellaneous)'
+  },
+
+  // Ambiguous term tests
+  {
+    query: 'coffee',
+    expectedChapter: '',  // Should ask for disambiguation
+    testType: 'ambiguous',
+    description: 'Generic "coffee" should trigger disambiguation question'
+  },
+
+  // Clear prediction tests (not ambiguous)
+  {
+    query: 'instant coffee',
+    expectedChapter: '21',
+    testType: 'prediction',
+    description: 'Instant coffee should predict Ch.21'
+  },
+  {
+    query: 'roasted coffee beans',
+    expectedChapter: '09',
+    testType: 'prediction',
+    description: 'Roasted coffee beans should predict Ch.09'
+  },
+
+  // Full search tests
+  {
+    query: 'brake pads for cars',
+    expectedChapter: '87',
+    testType: 'full_search',
+    description: 'Full search for brake pads should return 87xx codes'
+  },
+  {
+    query: 'ceramic brake pads',
+    expectedChapter: '87',
+    testType: 'full_search',
+    description: 'Full search for ceramic brake pads should return 87xx codes'
+  },
+];
+
+async function runTest(testCase: TestCase): Promise<boolean> {
+  log(`\n${'─'.repeat(80)}`, colors.cyan);
+  log(`Testing: "${testCase.query}"`, colors.bright);
+  log(`Expected: Ch.${testCase.expectedChapter || 'DISAMBIGUATION'}`, colors.blue);
+  log(`Type: ${testCase.testType}`, colors.yellow);
+  log(`${testCase.description}`, colors.reset);
+  log('', colors.reset);
+
+  let passed = false;
+
+  try {
+    switch (testCase.testType) {
+      case 'functional_override': {
+        const override = checkFunctionalOverrides(testCase.query);
+        if (override) {
+          log(`  Functional Override: Ch.${override.forceChapter}`, colors.green);
+          log(`  Reason: ${override.reason}`, colors.reset);
+          passed = override.forceChapter === testCase.expectedChapter;
+        } else {
+          log(`  No functional override found!`, colors.red);
+          passed = false;
+        }
+        break;
+      }
+
+      case 'ambiguous': {
+        const ambiguity = checkAmbiguousTerms(testCase.query);
+        if (ambiguity) {
+          log(`  Ambiguous term: "${ambiguity.term}"`, colors.yellow);
+          log(`  Question: ${ambiguity.info.disambiguationQuestion}`, colors.reset);
+          log(`  Options:`, colors.reset);
+          ambiguity.info.options.forEach(opt => {
+            log(`    - ${opt.label} → Ch.${opt.chapter}`, colors.reset);
+          });
+          passed = true; // We expected ambiguity
+        } else {
+          log(`  Not detected as ambiguous`, colors.red);
+          passed = false;
+        }
+        break;
+      }
+
+      case 'prediction': {
+        const result = predictChapters(testCase.query);
+        log(`  Predictions:`, colors.reset);
+        result.predictions.slice(0, 3).forEach((p, i) => {
+          const isExpected = p.chapter === testCase.expectedChapter;
+          const marker = isExpected ? '✓' : ' ';
+          const color = isExpected ? colors.green : colors.reset;
+          log(`  ${marker} ${i + 1}. Ch.${p.chapter} (${p.name}): ${(p.confidence * 100).toFixed(1)}%`, color);
+        });
+
+        if (result.functionalOverride) {
+          log(`  Functional Override: Ch.${result.functionalOverride.chapter}`, colors.magenta);
+          passed = result.functionalOverride.chapter === testCase.expectedChapter;
+        } else {
+          const topChapter = result.predictions[0]?.chapter;
+          passed = topChapter === testCase.expectedChapter;
+        }
+        break;
+      }
+
+      case 'full_search': {
+        log(`  Running full semantic search...`, colors.yellow);
+        const results = await semanticSearchMulti(testCase.query, 20);
+
+        // Check if majority of top 10 results are from expected chapter
+        const top10 = results.slice(0, 10);
+        const fromExpectedChapter = top10.filter(r => r.code.startsWith(testCase.expectedChapter));
+        const percentage = (fromExpectedChapter.length / top10.length) * 100;
+
+        log(`  Top 10 results:`, colors.reset);
+        top10.forEach((r, i) => {
+          const isExpected = r.code.startsWith(testCase.expectedChapter);
+          const color = isExpected ? colors.green : colors.red;
+          log(`    ${i + 1}. ${r.code}: ${r.description?.substring(0, 50)}... (score: ${r.score.toFixed(1)})`, color);
+        });
+
+        log(`  From Ch.${testCase.expectedChapter}: ${fromExpectedChapter.length}/10 (${percentage.toFixed(0)}%)`, colors.cyan);
+
+        // Pass if at least 70% are from expected chapter
+        passed = percentage >= 70;
+        break;
+      }
+    }
+  } catch (error) {
+    log(`  ERROR: ${error}`, colors.red);
+    passed = false;
+  }
+
+  if (passed) {
+    log(`  ✅ PASSED`, colors.green);
+  } else {
+    log(`  ❌ FAILED`, colors.red);
+  }
+
+  return passed;
+}
+
+async function main() {
+  console.log('\n');
+  log('╔═══════════════════════════════════════════════════════════════════════════╗', colors.magenta);
+  log('║                  PHASE 2: CHAPTER PREDICTOR TEST SUITE                     ║', colors.magenta);
+  log('╚═══════════════════════════════════════════════════════════════════════════╝', colors.magenta);
+
+  const results: { test: string; passed: boolean }[] = [];
+
+  for (const testCase of testCases) {
+    const passed = await runTest(testCase);
+    results.push({ test: testCase.query, passed });
+  }
+
+  // Summary
+  console.log('\n');
+  log('═'.repeat(80), colors.cyan);
+  log('                           TEST SUMMARY', colors.bright);
+  log('═'.repeat(80), colors.cyan);
+
+  const passedCount = results.filter(r => r.passed).length;
+  const failedCount = results.filter(r => !r.passed).length;
+
+  results.forEach(r => {
+    const status = r.passed ? '✅ PASS' : '❌ FAIL';
+    const color = r.passed ? colors.green : colors.red;
+    log(`  ${status}  ${r.test}`, color);
+  });
+
+  console.log('\n');
+  log(`  Total: ${results.length}  |  Passed: ${passedCount}  |  Failed: ${failedCount}`, colors.bright);
+
+  if (failedCount === 0) {
+    log('\n  🎉 ALL TESTS PASSED!', colors.green);
+  } else {
+    log(`\n  ⚠️  ${failedCount} TEST(S) FAILED`, colors.red);
+  }
+
+  process.exit(failedCount > 0 ? 1 : 0);
+}
+
+main().catch(console.error);

backend/scripts/test-root-fix.ts

@@ -0,0 +1,133 @@
+/**
+ * ROOT CAUSE FIX: Test Script
+ *
+ * Verifies that scoped semantic search correctly finds the best heading
+ * when functional override is active.
+ *
+ * Run with: npx ts-node scripts/test-root-fix.ts
+ */
+
+import { getBestHeadingInChapter, getScopedSemanticCandidates } from '../src/services/multi-candidate-search.service';
+import { checkFunctionalOverrides } from '../src/services/chapter-predictor.service';
+
+async function testRootCauseFix() {
+  console.log('='.repeat(80));
+  console.log('ROOT CAUSE FIX: Testing Scoped Semantic Search');
+  console.log('='.repeat(80));
+  console.log();
+
+  const testCases = [
+    {
+      query: 'brake pads for cars',
+      expectedChapter: '87',
+      expectedHeading: '8708', // Parts and accessories of vehicles
+      description: 'Should find 8708 (vehicle parts), NOT 8701 (tractors)'
+    },
+    {
+      query: 'ceramic brake pads',
+      expectedChapter: '87',
+      expectedHeading: '8708',
+      description: 'Should find 8708 (vehicle parts), NOT 69xx (ceramics)'
+    },
+    {
+      query: 'automotive brake disc',
+      expectedChapter: '87',
+      expectedHeading: '8708',
+      description: 'Should find 8708 (vehicle parts)'
+    },
+    {
+      query: 'car shock absorber',
+      expectedChapter: '87',
+      expectedHeading: '8708',
+      description: 'Should find 8708 (suspension parts)'
+    },
+    {
+      query: 'plastic toys for children',
+      expectedChapter: '95',
+      expectedHeading: '9503',
+      description: 'Should find 9503 (toys), NOT 39xx (plastics)'
+    },
+    {
+      query: 'wooden furniture',
+      expectedChapter: '94',
+      expectedHeading: '9403',
+      description: 'Should find 9403 (furniture), NOT 44xx (wood)'
+    },
+    {
+      query: 'stainless steel vacuum flask',
+      expectedChapter: '96',
+      expectedHeading: '9617',
+      description: 'Should find 9617 (vacuum flasks)'
+    }
+  ];
+
+  let passed = 0;
+  let failed = 0;
+
+  for (const test of testCases) {
+    console.log('-'.repeat(60));
+    console.log(`Test: "${test.query}"`);
+    console.log(`Expected: Ch.${test.expectedChapter}, Heading ${test.expectedHeading}`);
+    console.log(`Description: ${test.description}`);
+    console.log();
+
+    // Step 1: Check functional override
+    const override = checkFunctionalOverrides(test.query);
+    if (!override) {
+      console.log('  ❌ FAILED: No functional override detected');
+      failed++;
+      continue;
+    }
+
+    if (override.forceChapter !== test.expectedChapter) {
+      console.log(`  ❌ FAILED: Wrong chapter. Got ${override.forceChapter}, expected ${test.expectedChapter}`);
+      failed++;
+      continue;
+    }
+    console.log(`  ✓ Functional override: Ch.${override.forceChapter} (${override.reason})`);
+
+    // Step 2: Get best heading using scoped semantic search
+    const bestHeading = await getBestHeadingInChapter(test.query, test.expectedChapter);
+
+    if (!bestHeading) {
+      console.log('  ❌ FAILED: Could not find best heading');
+      failed++;
+      continue;
+    }
+
+    const gotHeading = bestHeading.code.substring(0, 4);
+    if (gotHeading === test.expectedHeading) {
+      console.log(`  ✓ Best heading: ${bestHeading.code} (score: ${bestHeading.score.toFixed(1)})`);
+      console.log(`    ${bestHeading.description.substring(0, 60)}...`);
+      console.log('  ✓ PASSED');
+      passed++;
+    } else {
+      console.log(`  ❌ FAILED: Wrong heading. Got ${gotHeading}, expected ${test.expectedHeading}`);
+      console.log(`    ${bestHeading.code}: ${bestHeading.description.substring(0, 60)}...`);
+      failed++;
+    }
+  }
+
+  console.log();
+  console.log('='.repeat(80));
+  console.log(`RESULTS: ${passed}/${testCases.length} passed, ${failed} failed`);
+  console.log('='.repeat(80));
+
+  // Additional test: Show top 5 candidates for "brake pads for cars"
+  console.log();
+  console.log('DETAILED TEST: Top candidates for "brake pads for cars" in Ch.87');
+  console.log('-'.repeat(60));
+
+  const candidates = await getScopedSemanticCandidates('brake pads for cars', '87', 10);
+  candidates.forEach((c, i) => {
+    console.log(`${i + 1}. ${c.code}: ${c.description?.substring(0, 50)}... (score: ${c.score.toFixed(1)})`);
+  });
+
+  // Exit
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+testRootCauseFix().catch(error => {
+  console.error('Test error:', error);
+  process.exit(1);
+});