Phase 4: Elimination logic bug fix + intelligent test suite

Bug Fix: mustBeInChapter precedence
- Fixed critical bug where codes in correct chapter were excluded
- "instant coffee" now correctly returns Ch.21 codes (2101.xx)
- Root cause: description exclusions applied even to correct-chapter codes
- Solution: mustBeInChapter takes precedence over description patterns
- Added safety fallback to prevent all-candidates-eliminated scenarios

Intelligent Test Suite:
- Added 51 comprehensive test cases
- Categories: critical regression, real-world, adversarial, typo handling
- Test runner with detailed analysis and recommendations
- Results tracking in JSON format

Diagnostic Scripts:
- diagnose-instant-coffee.ts: Debug instant coffee classification
- trace-classification.ts: Trace full classification flow
- test-instant-coffee-fix.ts: Verify elimination fix

Test Results After Fix:
- "instant coffee" → 2101.11.20 (Ch.21) ✅
- "roasted coffee beans" → 0901.21 (Ch.09) ✅
- "brake pads for cars" → 8708.30.00 (Ch.87) ✅

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

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

Author: AryanBV

CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+HS Code Classifier - AI-powered export documentation assistant that classifies products into Harmonized System (HS) codes using a hybrid approach combining keyword matching, decision trees, and LLM reasoning. Targets Indian SME exporters, reducing classification time from 30 minutes to under 2 minutes.
+
+## Build & Development Commands
+
+### Backend (Express.js + TypeScript + Prisma)
+```bash
+cd backend
+npm install                   # Install dependencies
+npm run dev                   # Start dev server with hot reload (port 3001)
+npm run build                 # Compile TypeScript to dist/
+npm start                     # Run production build
+
+# Database (Prisma + PostgreSQL/Supabase)
+npm run prisma:generate       # Generate Prisma client after schema changes
+npm run prisma:push           # Push schema changes to DB (development)
+npm run prisma:migrate        # Run migrations (production)
+npm run prisma:studio         # Open Prisma Studio GUI
+npm run prisma:seed           # Seed database with HS codes
+```
+
+### Frontend (Next.js 14 + React 18)
+```bash
+cd frontend
+npm install                   # Install dependencies
+npm run dev                   # Start dev server (port 3000)
+npm run build                 # Production build
+npm run lint                  # ESLint
+npm run type-check            # TypeScript validation (tsc --noEmit)
+```
+
+## Architecture
+
+### Monorepo Structure
+- `backend/` - Express.js REST API with Prisma ORM
+- `frontend/` - Next.js 14 App Router with Tailwind/Shadcn UI
+- Separate package.json files; no root package manager
+
+### Classification Pipeline
+The system uses a hybrid AI approach through multiple classification routes:
+1. **Keyword-based** (`/api/classify`) - PostgreSQL FTS + fuzzy matching
+2. **LLM-first** (`/api/classify-llm`) - GPT-4o primary classification
+3. **Conversational** (`/api/classify-conversational`) - Multi-turn Q&A refinement
+4. **Vector search** (`/api/vector-search`) - Semantic similarity matching
+
+### Backend Service Layer (`backend/src/services/`)
+Core classification orchestration:
+- `ultimate-classifier.service.ts` - Main classifier entry point
+- `llm-first-classifier.service.ts` - LLM-driven classification
+- `llm-conversational-classifier.service.ts` - Multi-turn conversations
+- `conversational-classifier.service.ts` - Question flow management
+
+Supporting services:
+- `keyword-matcher.service.ts` - Fuzzy keyword matching
+- `hierarchy-analyzer.service.ts` - HS code hierarchy traversal
+- `candidate-filter.service.ts` - Filters classification candidates
+- `decision-tree.service.ts` - Rule-based classification
+- `dynamic-question.service.ts` - Generates clarifying questions
+- `exclusion-classifier.service.ts` - Handles "Other" codes classification
+- `chapter-notes.service.ts` - Legal classification rules
+
+### Database Schema (Prisma)
+Key models in `backend/prisma/schema.prisma`:
+- **HsCode** - Master codes with keywords, synonyms, descriptions
+- **HsCodeHierarchy** - Parent/child relationships for code tree
+- **ClassificationConversation** / **ConversationTurn** - Multi-turn state
+- **ClassificationFeedback** - User feedback for accuracy improvement
+
+### Frontend Structure
+- `src/app/` - Next.js App Router pages
+- `src/components/classify/` - Chat interface, confidence meters, reasoning panels
+- `src/lib/api-client.ts` - Axios client for backend communication
+
+## Environment Variables
+
+### Backend (`backend/.env`)
+```
+DATABASE_URL=postgresql://...        # Supabase PostgreSQL connection
+OPENAI_API_KEY=sk-proj-...          # OpenAI API key for GPT-4o
+PORT=3001
+NODE_ENV=development
+FRONTEND_URL=http://localhost:3000   # CORS origin
+```
+
+### Frontend (`frontend/.env.local`)
+```
+NEXT_PUBLIC_API_URL=http://localhost:3001
+```
+
+## TypeScript Configuration
+Both projects use strict mode with `strictNullChecks`, `noImplicitAny`, and `strictFunctionTypes` enabled. Path alias `@/*` maps to `./src/*`.
+
+## Deployment
+Production deployment configured for Railway.app. Backend serves API, frontend as separate service.

backend/package.json

@@ -12,7 +12,8 @@
     "prisma:studio": "prisma studio",
     "prisma:push": "prisma db push",
     "prisma:seed": "ts-node prisma/seed.ts",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "test:intelligent": "npx ts-node src/tests/intelligent-test-suite/test-runner.ts"
   },
   "keywords": [
     "hs-code",

backend/scripts/diagnose-instant-coffee.ts

@@ -0,0 +1,74 @@
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+async function diagnose() {
+  console.log('=== DIAGNOSTIC: Instant Coffee Classification ===\n');
+
+  // 1. Check if Ch.21 codes exist
+  console.log('1. Checking Chapter 21 codes in database...');
+  const ch21Codes: any[] = await prisma.$queryRaw`
+    SELECT code, description FROM "HsCode" WHERE code LIKE '21%' LIMIT 20
+  `;
+  console.log(`   Found ${ch21Codes.length} Ch.21 codes`);
+  if (ch21Codes.length > 0) {
+    console.log('   Sample codes:');
+    ch21Codes.slice(0, 5).forEach(c => console.log(`     ${c.code}: ${c.description?.substring(0, 50)}...`));
+  }
+
+  // 2. Check specifically for 2101 codes
+  console.log('\n2. Checking for 2101.xx (coffee extracts) codes...');
+  const coffeeExtractCodes: any[] = await prisma.$queryRaw`
+    SELECT code, description, keywords FROM "HsCode" WHERE code LIKE '2101%'
+  `;
+  console.log(`   Found ${coffeeExtractCodes.length} codes under 2101`);
+  coffeeExtractCodes.forEach(c => {
+    console.log(`     ${c.code}: ${c.description}`);
+    console.log(`       Keywords: ${JSON.stringify(c.keywords) || 'NONE'}`);
+  });
+
+  // 3. Search for "instant" keyword anywhere
+  console.log('\n3. Searching for codes with "instant" in description or keywords...');
+  const instantCodes: any[] = await prisma.$queryRaw`
+    SELECT code, description FROM "HsCode"
+    WHERE description ILIKE '%instant%'
+       OR 'instant' = ANY(keywords)
+  `;
+  console.log(`   Found ${instantCodes.length} codes with "instant"`);
+  instantCodes.forEach(c => console.log(`     ${c.code}: ${c.description?.substring(0, 60)}`));
+
+  // 4. Check for "coffee" in Ch.21
+  console.log('\n4. Searching for "coffee" in Chapter 21...');
+  const ch21Coffee: any[] = await prisma.$queryRaw`
+    SELECT code, description FROM "HsCode"
+    WHERE code LIKE '21%'
+      AND (description ILIKE '%coffee%' OR 'coffee' = ANY(keywords))
+  `;
+  console.log(`   Found ${ch21Coffee.length} codes`);
+  ch21Coffee.forEach(c => console.log(`     ${c.code}: ${c.description}`));
+
+  // 5. Check for "coffee" anywhere in database
+  console.log('\n5. Searching for ALL codes with "coffee"...');
+  const allCoffee: any[] = await prisma.$queryRaw`
+    SELECT code, description FROM "HsCode"
+    WHERE description ILIKE '%coffee%' OR 'coffee' = ANY(keywords)
+    LIMIT 20
+  `;
+  console.log(`   Found ${allCoffee.length} codes with "coffee"`);
+  allCoffee.slice(0, 15).forEach(c => console.log(`     ${c.code}: ${c.description?.substring(0, 60)}`));
+
+  // 6. Total database count
+  console.log('\n6. Database statistics...');
+  const totalCodes: any[] = await prisma.$queryRaw`SELECT COUNT(*) as count FROM "HsCode"`;
+  console.log(`   Total HS codes in database: ${totalCodes[0].count}`);
+
+  const ch09Count: any[] = await prisma.$queryRaw`SELECT COUNT(*) as count FROM "HsCode" WHERE code LIKE '09%'`;
+  console.log(`   Chapter 09 codes: ${ch09Count[0].count}`);
+
+  const ch21Count: any[] = await prisma.$queryRaw`SELECT COUNT(*) as count FROM "HsCode" WHERE code LIKE '21%'`;
+  console.log(`   Chapter 21 codes: ${ch21Count[0].count}`);
+
+  await prisma.$disconnect();
+}
+
+diagnose().catch(console.error);