Matching Engine — Implementation Plan (pipeline)

import { describe, it, expect } from 'vitest'
import type { ParsedJD, JDParseMetadata } from '@/lib/jd-parser/types'
import type { ConfidenceField } from '@/lib/cv-parser/types'
 
describe('ParsedJD types', () => {
  it('JDParseMetadata has the required fields', () => {
    const meta: JDParseMetadata = {
      source_file: 'JD for LNG.pdf',
      vertical_hint: 'Energy',
      parse_status: 'success',
      overall_confidence: 0.92,
      parsed_at: '2026-05-23T00:00:00.000Z',
    }
    expect(meta.parse_status).toBe('success')
  })
 
  it('ParsedJD has role + requirements blocks', () => {
    const partial: Pick<ParsedJD, 'role'> = {
      role: {
        raw_title: { value: 'Cargo Operator (LNG)', confidence: 0.95 },
        job_summary: { value: 'Manage LNG vessel ops.', confidence: 0.9 },
        key_objectives: { value: ['Ensure smooth execution'], confidence: 0.9 },
      },
    }
    expect(partial.role.raw_title.value).toBe('Cargo Operator (LNG)')
  })
})

cd "G:/My Drive/BL Dev work/Calibre/calibre-app"
npm test tests/lib/jd-parser/parser.test.ts

import type { ConfidenceField, ParseStatus } from '@/lib/cv-parser/types'
 
export interface JDResponsibility {
  category: string
  description: string
  confidence: number
}
 
export interface JDEducation {
  qualification: ConfidenceField<string>
  field: ConfidenceField<string>
  required: ConfidenceField<boolean>
}
 
export interface JDRequirements {
  min_years_experience: ConfidenceField<number | null>
  experience_description: ConfidenceField<string>
  must_have_skills: ConfidenceField<string[]>
  nice_to_have_skills: ConfidenceField<string[]>
  technical_knowledge: ConfidenceField<string[]>
  education: JDEducation[]
  certifications: ConfidenceField<string[]>
  tools_and_systems: ConfidenceField<string[]>
  languages: ConfidenceField<string[]>
  hsse_compliance: ConfidenceField<boolean>
  shift_or_24_7: ConfidenceField<boolean>
}
 
export interface JDParseMetadata {
  source_file: string
  vertical_hint: string
  parse_status: ParseStatus
  overall_confidence: number
  parsed_at: string
}
 
export interface ParsedJD {
  role: {
    raw_title: ConfidenceField<string>
    job_summary: ConfidenceField<string>
    key_objectives: ConfidenceField<string[]>
  }
  responsibilities: JDResponsibility[]
  requirements: JDRequirements
  parse_metadata: JDParseMetadata
}

npm test tests/lib/jd-parser/parser.test.ts

git add src/lib/jd-parser/types.ts tests/lib/jd-parser/parser.test.ts
git commit -m "feat(jd-parser): add ParsedJD TypeScript types"

import { parseJDText } from '@/lib/jd-parser/parser'
 
const SAMPLE_JD_TEXT = `
Job Summary
Key Objectives:
- Ensure smooth execution of cargo operations.
- Manage voyage execution for time-chartered and spot LNG vessels.
- Ensure strict compliance with HSSE standards.
 
Key Responsibilities:
- Voyage & Cargo Operations: Plan and execute LNG vessel scheduling.
- Stakeholder Liaison: Primary contact between trading desks, shipowners, terminal operators.
- Documentation & Reporting: Manage bills of lading, certificates, Trinity updates.
 
Requirements:
- Experience: Previous experience in LNG commercial cargo operations.
- Technical Knowledge: Strong understanding of LNG cargo handling, charter party agreements.
- Education: Degree or Diploma in Maritime Studies.
- Flexibility: Availability to handle 24/7 trading activities.
`
 
describe('parseJDText', () => {
  it('returns role with a raw_title', async () => {
    const result = await parseJDText(SAMPLE_JD_TEXT, 'JD for Cargo Operator (LNG).pdf', 'Energy')
    expect(result.role.raw_title.value).toBeTruthy()
    expect(result.role.raw_title.confidence).toBeGreaterThan(0)
  })
 
  it('extracts at least one responsibility', async () => {
    const result = await parseJDText(SAMPLE_JD_TEXT, 'JD for Cargo Operator (LNG).pdf', 'Energy')
    expect(result.responsibilities.length).toBeGreaterThan(0)
  })
 
  it('detects 24/7 / shift requirement', async () => {
    const result = await parseJDText(SAMPLE_JD_TEXT, 'JD for Cargo Operator (LNG).pdf', 'Energy')
    expect(result.requirements.shift_or_24_7.value).toBe(true)
  })
 
  it('detects HSSE compliance', async () => {
    const result = await parseJDText(SAMPLE_JD_TEXT, 'JD for Cargo Operator (LNG).pdf', 'Energy')
    expect(result.requirements.hsse_compliance.value).toBe(true)
  })
 
  it('parse_metadata reflects the vertical hint', async () => {
    const result = await parseJDText(SAMPLE_JD_TEXT, 'JD for Cargo Operator (LNG).pdf', 'Energy')
    expect(result.parse_metadata.vertical_hint).toBe('Energy')
    expect(result.parse_metadata.source_file).toBe('JD for Cargo Operator (LNG).pdf')
  })
})

npm test tests/lib/jd-parser/parser.test.ts

import Anthropic from '@anthropic-ai/sdk'
import type { ParsedJD, JDParseMetadata } from './types'
import type { ParseStatus, ConfidenceField } from '@/lib/cv-parser/types'
 
const client = new Anthropic()
 
const JD_EXTRACTION_TOOL: Anthropic.Tool = {
  name: 'extract_jd_data',
  description: 'Extract structured data from a Job Description text. Assign a confidence score (0.0–1.0) to every field. Use null when a field is absent.',
  input_schema: {
    type: 'object' as const,
    required: ['role', 'responsibilities', 'requirements'],
    properties: {
      role: {
        type: 'object',
        required: ['raw_title', 'job_summary', 'key_objectives'],
        properties: {
          raw_title: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'string' }, confidence: { type: 'number' } } },
          job_summary: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'string' }, confidence: { type: 'number' } } },
          key_objectives: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'array', items: { type: 'string' } }, confidence: { type: 'number' } } },
        },
      },
      responsibilities: {
        type: 'array',
        items: {
          type: 'object',
          required: ['category', 'description', 'confidence'],
          properties: {
            category: { type: 'string' },
            description: { type: 'string' },
            confidence: { type: 'number' },
          },
        },
      },
      requirements: {
        type: 'object',
        required: [
          'min_years_experience', 'experience_description',
          'must_have_skills', 'nice_to_have_skills',
          'technical_knowledge', 'education', 'certifications',
          'tools_and_systems', 'languages', 'hsse_compliance', 'shift_or_24_7',
        ],
        properties: {
          min_years_experience: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: ['number', 'null'] }, confidence: { type: 'number' } } },
          experience_description: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'string' }, confidence: { type: 'number' } } },
          must_have_skills: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'array', items: { type: 'string' } }, confidence: { type: 'number' } } },
          nice_to_have_skills: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'array', items: { type: 'string' } }, confidence: { type: 'number' } } },
          technical_knowledge: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'array', items: { type: 'string' } }, confidence: { type: 'number' } } },
          education: {
            type: 'array',
            items: {
              type: 'object',
              required: ['qualification', 'field', 'required'],
              properties: {
                qualification: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'string' }, confidence: { type: 'number' } } },
                field: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'string' }, confidence: { type: 'number' } } },
                required: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'boolean' }, confidence: { type: 'number' } } },
              },
            },
          },
          certifications: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'array', items: { type: 'string' } }, confidence: { type: 'number' } } },
          tools_and_systems: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'array', items: { type: 'string' } }, confidence: { type: 'number' } } },
          languages: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'array', items: { type: 'string' } }, confidence: { type: 'number' } } },
          hsse_compliance: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'boolean' }, confidence: { type: 'number' } } },
          shift_or_24_7: { type: 'object', required: ['value', 'confidence'], properties: { value: { type: 'boolean' }, confidence: { type: 'number' } } },
        },
      },
    },
  },
}
 
function computeOverallConfidence(jd: Omit<ParsedJD, 'parse_metadata'>): number {
  const scores: number[] = []
  const walk = (obj: unknown) => {
    if (!obj || typeof obj !== 'object') return
    const o = obj as Record<string, unknown>
    if ('confidence' in o && typeof o.confidence === 'number') {
      scores.push(o.confidence)
      return
    }
    for (const v of Object.values(o)) {
      if (Array.isArray(v)) v.forEach(walk)
      else walk(v)
    }
  }
  walk(jd)
  if (scores.length === 0) return 0
  return Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 100) / 100
}
 
function deriveParseStatus(jd: Omit<ParsedJD, 'parse_metadata'>, overall: number): ParseStatus {
  const required: ConfidenceField<unknown>[] = [
    jd.role.raw_title,
    jd.role.job_summary,
    jd.requirements.experience_description,
  ]
  const lowConf = required.some(f => f.confidence === null || (f.confidence as number) < 0.6)
  if (lowConf || overall < 0.7) return 'partial'
  return 'success'
}
 
export async function parseJDText(rawText: string, sourceFile: string, verticalHint: string): Promise<ParsedJD> {
  const response = await client.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 4096,
    tools: [JD_EXTRACTION_TOOL],
    tool_choice: { type: 'tool', name: 'extract_jd_data' },
    messages: [
      {
        role: 'user',
        content: `You are a specialist recruitment data extraction system for the commodities, maritime, energy, and finance sectors.
 
Extract all structured data from the following Job Description. For every field:
- Assign confidence 0.0 (uncertain) to 1.0 (unambiguous).
- For min_years_experience: extract the numeric floor if the JD says "X+ years" or "minimum X years". Use null when not specified.
- For must_have_skills: skills/experiences phrased as required ("must have", "required", "essential").
- For nice_to_have_skills: skills phrased as preferred ("preferred", "ideally", "bonus").
- For technical_knowledge: domain-specific knowledge (HSSE, charter party agreements, ISDA, financial modelling, etc.).
- For tools_and_systems: named software/platforms (Trinity, Bloomberg, SAP, etc.).
- For hsse_compliance: true if HSSE / safety / health / environment compliance is mentioned as a requirement.
- For shift_or_24_7: true if the JD mentions 24/7 coverage, shift work, or out-of-hours operational responsibility.
 
JD TEXT:
---
${rawText}
---`,
      },
    ],
  })
 
  const toolUse = response.content.find(b => b.type === 'tool_use')
  if (!toolUse || toolUse.type !== 'tool_use') {
    throw new Error('Claude did not return a tool_use block')
  }
  const extracted = toolUse.input as Omit<ParsedJD, 'parse_metadata'>
  const overall = computeOverallConfidence(extracted)
  const parse_metadata: JDParseMetadata = {
    source_file: sourceFile,
    vertical_hint: verticalHint,
    parse_status: deriveParseStatus(extracted, overall),
    overall_confidence: overall,
    parsed_at: new Date().toISOString(),
  }
  return { ...extracted, parse_metadata }
}

npm test tests/lib/jd-parser/parser.test.ts

git add src/lib/jd-parser/parser.ts tests/lib/jd-parser/parser.test.ts
git commit -m "feat(jd-parser): add Claude-powered JD parser with tool_use structured output"

import { parseJD } from '@/lib/jd-parser'
import path from 'path'
 
describe('parseJD (public API)', () => {
  it('parses a real JD PDF end-to-end', async () => {
    const filePath = path.resolve(
      __dirname,
      '../../../../../reference/JD/Operations- cargo, commodities brokerage/Energy/JD for Cargo Operator (LNG).pdf'
    )
    const result = await parseJD(filePath)
    expect(result.parse_metadata.parse_status).not.toBe('failed')
    expect(result.role.raw_title.value.toLowerCase()).toContain('lng')
    expect(result.parse_metadata.vertical_hint).toBe('Energy')
  })
})

npm test tests/lib/jd-parser/parser.test.ts

import path from 'path'
import { extractText } from '@/lib/cv-parser/extractor'
import { parseJDText } from './parser'
import type { ParsedJD } from './types'
 
export type { ParsedJD } from './types'
 
function deriveVerticalHint(filePath: string): string {
  const parts = filePath.replace(/\\/g, '/').split('/')
  const jdIdx = parts.findIndex(p => p === 'JD')
  if (jdIdx === -1 || jdIdx === parts.length - 1) return 'Unknown'
  const tail = parts.slice(jdIdx + 1, -1)
  return tail.length > 0 ? tail[tail.length - 1] : 'Unknown'
}
 
export async function parseJD(filePath: string): Promise<ParsedJD> {
  const sourceFile = path.basename(filePath)
  const verticalHint = deriveVerticalHint(filePath)
  const extraction = await extractText(filePath)
 
  if (extraction.status === 'failed') {
    throw new Error(`Extraction failed for ${sourceFile}: ${extraction.reason ?? 'unknown'}`)
  }
  return parseJDText(extraction.text, sourceFile, verticalHint)
}

npm test tests/lib/jd-parser/parser.test.ts

git add src/lib/jd-parser/index.ts
git commit -m "feat(jd-parser): add parseJD public API + vertical-hint derivation from path"

import fs from 'fs'
import path from 'path'
import { parseJD } from '../src/lib/jd-parser'
 
const JD_ROOT = path.resolve(__dirname, '../../reference/JD')
const OUTPUT_DIR = path.resolve(__dirname, '../outputs/parsed-jds')
 
function walkPdfs(dir: string): string[] {
  const out: string[] = []
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const full = path.join(dir, entry.name)
    if (entry.isDirectory()) out.push(...walkPdfs(full))
    else if (path.extname(entry.name).toLowerCase() === '.pdf') out.push(full)
  }
  return out
}
 
async function main() {
  fs.mkdirSync(OUTPUT_DIR, { recursive: true })
  const files = walkPdfs(JD_ROOT)
  console.log(`Found ${files.length} JD PDFs.`)
 
  const results = { success: 0, partial: 0, failed: 0 }
 
  for (const filePath of files) {
    const fileName = path.basename(filePath)
    const outFile = path.join(OUTPUT_DIR, `${path.basename(fileName, '.pdf')}.json`)
    process.stdout.write(`  Parsing: ${fileName} ... `)
    try {
      const parsed = await parseJD(filePath)
      fs.writeFileSync(outFile, JSON.stringify(parsed, null, 2))
      const status = parsed.parse_metadata.parse_status
      console.log(`${status} (confidence: ${parsed.parse_metadata.overall_confidence.toFixed(2)})`)
      results[status]++
    } catch (err) {
      console.log(`ERROR: ${err instanceof Error ? err.message : err}`)
      results.failed++
    }
    await new Promise(r => setTimeout(r, 500))
  }
 
  console.log('\n─────────────────────────────')
  console.log(`✅ success: ${results.success}`)
  console.log(`⚠️  partial: ${results.partial}`)
  console.log(`❌ failed:  ${results.failed}`)
  console.log(`Output: ${OUTPUT_DIR}`)
}
 
main().catch(console.error)

"batch-parse-jds": "tsx scripts/batch-parse-jds.ts"

mkdir -p outputs/parsed-jds
touch outputs/parsed-jds/.gitkeep
echo "outputs/parsed-jds/" >> .gitignore

npm run batch-parse-jds

cat "outputs/parsed-jds/JD for Cargo Operator (LNG).json"
cat "outputs/parsed-jds/JD for Portfolio Manager.json"
cat "outputs/parsed-jds/JD for Credit Risk.json"

git add scripts/batch-parse-jds.ts outputs/parsed-jds/.gitkeep package.json .gitignore
git commit -m "feat(jd-parser): add batch JD parsing script + ignore parsed-jds output"

import { describe, it, expect } from 'vitest'
import { TAXONOMY, SUB_FUNCTIONS, isValidTag } from '@/lib/jd-normaliser/taxonomy'
 
describe('taxonomy', () => {
  it('exports the five sub-functions', () => {
    expect(SUB_FUNCTIONS).toEqual([
      'cargo-ops', 'ship-ops', 'risk-analytics', 'finance-fo', 'ops-back-office',
    ])
  })
 
  it('cargo-ops tags include energy:lng and agri:grains', () => {
    expect(TAXONOMY['cargo-ops']).toContain('energy:lng')
    expect(TAXONOMY['cargo-ops']).toContain('agri:grains')
  })
 
  it('finance-fo has expected tags', () => {
    expect(TAXONOMY['finance-fo']).toContain('finance:portfolio-management')
    expect(TAXONOMY['finance-fo']).toContain('finance:institutional-sales')
  })
 
  it('ops-back-office has expected tags', () => {
    expect(TAXONOMY['ops-back-office']).toContain('ops:aml')
    expect(TAXONOMY['ops-back-office']).toContain('ops:compliance')
  })
 
  it('isValidTag accepts known tags and rejects unknown', () => {
    expect(isValidTag('energy:lng')).toBe(true)
    expect(isValidTag('bogus:tag')).toBe(false)
  })
})

npm test tests/lib/jd-normaliser/taxonomy.test.ts

export const SUB_FUNCTIONS = [
  'cargo-ops',
  'ship-ops',
  'risk-analytics',
  'finance-fo',
  'ops-back-office',
] as const
 
export type SubFunction = typeof SUB_FUNCTIONS[number]
 
export const SUB_FUNCTION_DISPLAY: Record<SubFunction, string> = {
  'cargo-ops':       'Operations - cargo, commodities brokerage',
  'ship-ops':        'Operations - ship, shipping brokerage',
  'risk-analytics':  'Risk - Analytics',
  'finance-fo':      'Finance - RM, wealth management, FA, institutional sales',
  'ops-back-office': 'Operations - banks, finance brokerage, funds, asset management',
}
 
export const TAXONOMY: Record<SubFunction, string[]> = {
  'cargo-ops': [
    'energy:oil', 'energy:coal', 'energy:lng', 'energy:lpg',
    'energy:petrochemicals', 'energy:light-ends', 'energy:middle-distillates',
    'metals:base', 'metals:ferrous', 'metals:precious',
    'agri:grains', 'agri:edible-oils', 'agri:veg-oils',
    'agri:cocoa', 'agri:coffee', 'agri:sugar', 'agri:rice',
    'agri:fertilizers', 'agri:biofuels', 'agri:oleochemicals',
    'agri:edible-nuts',
  ],
  'ship-ops': [
    'vessel:tanker', 'vessel:chemical-tanker', 'vessel:lng-carrier',
    'vessel:lpg-carrier', 'vessel:drybulk', 'vessel:container',
    'vessel:offshore-support',
  ],
  'risk-analytics': [
    'risk:market', 'risk:credit', 'risk:operational',
    'risk:analytics', 'risk:controlling', 'risk:product-control',
  ],
  'finance-fo': [
    'finance:portfolio-management',
    'finance:relationship-management',
    'finance:wealth-management',
    'finance:financial-trading',
    'finance:institutional-sales',
    'finance:private-wealth-sales',
  ],
  'ops-back-office': [
    'ops:aml', 'ops:compliance', 'ops:assistant-rm', 'ops:finance-operations',
  ],
}
 
const ALL_TAGS = new Set<string>(
  Object.values(TAXONOMY).flat()
)
 
export function isValidTag(tag: string): boolean {
  return ALL_TAGS.has(tag)
}
 
export function tagsForSubFunction(sf: SubFunction): string[] {
  return TAXONOMY[sf]
}

npm test tests/lib/jd-normaliser/taxonomy.test.ts

git add src/lib/jd-normaliser/taxonomy.ts tests/lib/jd-normaliser/taxonomy.test.ts
git commit -m "feat(jd-normaliser): add taxonomy with cargo/ship/risk/finance/ops-back-office sub-functions"

import type { SubFunction } from './taxonomy'
 
export type SeniorityTier = 'Junior' | 'Mid' | 'Senior' | 'Lead' | 'Head'
 
export interface NormalisedJD {
  sub_function: SubFunction
  sub_function_display: string
  tags: string[]
  normalised_title: string
  seniority_tier: SeniorityTier
  min_years: number | null
  must_have_tags: string[]
  nice_to_have_tags: string[]
  confidence: number
}

import { describe, it, expect } from 'vitest'
import fs from 'fs'
import path from 'path'
import { normaliseJD } from '@/lib/jd-normaliser'
import type { ParsedJD } from '@/lib/jd-parser/types'
import { isValidTag } from '@/lib/jd-normaliser/taxonomy'
 
function loadParsedJD(name: string): ParsedJD {
  const filePath = path.resolve(__dirname, '../../../outputs/parsed-jds', name)
  return JSON.parse(fs.readFileSync(filePath, 'utf-8'))
}
 
describe('normaliseJD', () => {
  it('classifies an LNG cargo JD as cargo-ops with energy:lng tag', async () => {
    const parsed = loadParsedJD('JD for Cargo Operator (LNG).json')
    const result = await normaliseJD(parsed)
    expect(result.sub_function).toBe('cargo-ops')
    expect(result.must_have_tags).toContain('energy:lng')
  })
 
  it('classifies a Portfolio Manager JD as finance-fo', async () => {
    const parsed = loadParsedJD('JD for Portfolio Manager.json')
    const result = await normaliseJD(parsed)
    expect(result.sub_function).toBe('finance-fo')
    expect(result.must_have_tags).toContain('finance:portfolio-management')
  })
 
  it('classifies a Credit Risk JD as risk-analytics with risk:credit', async () => {
    const parsed = loadParsedJD('JD for Credit Risk.json')
    const result = await normaliseJD(parsed)
    expect(result.sub_function).toBe('risk-analytics')
    expect(result.must_have_tags).toContain('risk:credit')
  })
 
  it('all output tags are valid taxonomy entries', async () => {
    const parsed = loadParsedJD('JD for Cargo Operator (LNG).json')
    const result = await normaliseJD(parsed)
    for (const tag of [...result.tags, ...result.must_have_tags, ...result.nice_to_have_tags]) {
      expect(isValidTag(tag)).toBe(true)
    }
  })
})

npm test tests/lib/jd-normaliser/normaliser.test.ts

import Anthropic from '@anthropic-ai/sdk'
import type { ParsedJD } from '@/lib/jd-parser/types'
import type { NormalisedJD } from './types'
import {
  TAXONOMY, SUB_FUNCTIONS, SUB_FUNCTION_DISPLAY,
  isValidTag, type SubFunction,
} from './taxonomy'
 
const client = new Anthropic()
 
const NORMALISE_TOOL: Anthropic.Tool = {
  name: 'normalise_jd',
  description: 'Classify a parsed JD against the Calibre taxonomy.',
  input_schema: {
    type: 'object' as const,
    required: ['sub_function', 'tags', 'must_have_tags', 'nice_to_have_tags', 'normalised_title', 'seniority_tier', 'min_years', 'confidence'],
    properties: {
      sub_function:    { type: 'string', enum: [...SUB_FUNCTIONS] },
      tags:            { type: 'array', items: { type: 'string' } },
      must_have_tags:  { type: 'array', items: { type: 'string' } },
      nice_to_have_tags: { type: 'array', items: { type: 'string' } },
      normalised_title: { type: 'string' },
      seniority_tier:  { type: 'string', enum: ['Junior', 'Mid', 'Senior', 'Lead', 'Head'] },
      min_years:       { type: ['number', 'null'] },
      confidence:      { type: 'number' },
    },
  },
}
 
export async function normaliseJD(jd: ParsedJD): Promise<NormalisedJD> {
  const taxonomyJson = JSON.stringify(TAXONOMY, null, 2)
 
  const response = await client.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 2048,
    tools: [NORMALISE_TOOL],
    tool_choice: { type: 'tool', name: 'normalise_jd' },
    messages: [
      {
        role: 'user',
        content: `You are classifying a Job Description against Calibre's recruitment taxonomy.
 
CONTROLLED VOCABULARY (only return tags from this list):
${taxonomyJson}
 
Rules:
- sub_function: pick the single best fit.
- tags: ALL applicable tags from the chosen sub_function's tag list.
- must_have_tags: subset of tags that the JD explicitly requires.
- nice_to_have_tags: tags that are preferred / nice-to-have / adjacent.
- normalised_title: standardised title (e.g. "Cargo Operations Executive - LNG").
- seniority_tier: Junior 0-2y, Mid 3-5y, Senior 6-10y, Lead 10-15y, Head 15+y. Cross-check title + JD min_years.
- min_years: copy from JD if specified; null otherwise.
- confidence: 0.0-1.0, your overall certainty in this classification.
 
PARSED JD:
${JSON.stringify(jd, null, 2)}`,
      },
    ],
  })
 
  const toolUse = response.content.find(b => b.type === 'tool_use')
  if (!toolUse || toolUse.type !== 'tool_use') {
    throw new Error('Claude did not return a tool_use block for JD normalisation')
  }
  const out = toolUse.input as Omit<NormalisedJD, 'sub_function_display'>
 
  const sf = out.sub_function as SubFunction
  const cleanTags = (arr: string[]) => arr.filter(isValidTag)
 
  return {
    sub_function: sf,
    sub_function_display: SUB_FUNCTION_DISPLAY[sf],
    tags: cleanTags(out.tags ?? []),
    must_have_tags: cleanTags(out.must_have_tags ?? []),
    nice_to_have_tags: cleanTags(out.nice_to_have_tags ?? []),
    normalised_title: out.normalised_title,
    seniority_tier: out.seniority_tier,
    min_years: out.min_years,
    confidence: out.confidence,
  }
}

export { normaliseJD } from './normaliser'
export type { NormalisedJD, SeniorityTier } from './types'
export {
  SUB_FUNCTIONS, SUB_FUNCTION_DISPLAY, TAXONOMY,
  isValidTag, tagsForSubFunction,
} from './taxonomy'
export type { SubFunction } from './taxonomy'

npm test tests/lib/jd-normaliser/normaliser.test.ts

git add src/lib/jd-normaliser/ tests/lib/jd-normaliser/normaliser.test.ts
git commit -m "feat(jd-normaliser): classify JDs against controlled tag taxonomy via Claude"

import fs from 'fs'
import path from 'path'
import { normaliseJD } from '../src/lib/jd-normaliser'
import type { ParsedJD } from '../src/lib/jd-parser/types'
 
const PARSED_DIR = path.resolve(__dirname, '../outputs/parsed-jds')
const OUTPUT_DIR = path.resolve(__dirname, '../outputs/normalised-jds')
 
interface ValidationFailure {
  file: string
  reason: string
}
 
async function main() {
  fs.mkdirSync(OUTPUT_DIR, { recursive: true })
 
  const files = fs.readdirSync(PARSED_DIR).filter(f => f.endsWith('.json'))
  const failures: ValidationFailure[] = []
  const subFunctionCounts: Record<string, number> = {}
 
  for (const file of files) {
    const parsedPath = path.join(PARSED_DIR, file)
    const parsed: ParsedJD = JSON.parse(fs.readFileSync(parsedPath, 'utf-8'))
 
    process.stdout.write(`  Normalising: ${file} ... `)
    try {
      const normalised = await normaliseJD(parsed)
      fs.writeFileSync(
        path.join(OUTPUT_DIR, file),
        JSON.stringify(normalised, null, 2)
      )
      subFunctionCounts[normalised.sub_function] =
        (subFunctionCounts[normalised.sub_function] ?? 0) + 1
      console.log(`${normalised.sub_function} / ${normalised.seniority_tier} (conf ${normalised.confidence.toFixed(2)})`)
    } catch (err) {
      failures.push({ file, reason: err instanceof Error ? err.message : String(err) })
      console.log(`ERROR`)
    }
    await new Promise(r => setTimeout(r, 500))
  }
 
  console.log('\nSub-function distribution:')
  for (const [sf, count] of Object.entries(subFunctionCounts)) {
    console.log(`  ${sf}: ${count}`)
  }
 
  if (failures.length) {
    console.log('\nFailures:')
    for (const f of failures) console.log(`  ${f.file} — ${f.reason}`)
    process.exit(1)
  }
}
 
main().catch(err => { console.error(err); process.exit(1) })

"batch-normalise-jds": "tsx scripts/batch-normalise-jds.ts"

echo "outputs/normalised-jds/" >> .gitignore

npm run batch-normalise-jds

Sub-function distribution:
  cargo-ops: 19
  ship-ops: 8
  risk-analytics: 5
  finance-fo: 5
  ops-back-office: 4

git add scripts/batch-normalise-jds.ts package.json .gitignore
git commit -m "feat(jd-normaliser): batch-normalise all 41 JDs into NormalisedJD records"

import { describe, it, expect } from 'vitest'
import type {
  Layer1Result, Layer2Result, Layer3Verdict,
  AdjacentMatchEvidence, MatchRecord,
} from '@/lib/matching/types'
 
describe('matching types', () => {
  it('Layer1Result composite is a number and passes is boolean', () => {
    const r: Layer1Result = {
      jd_id: 'JD for Cargo Operator (LNG)',
      cv_id: 'Adrian Tan (Risk, Oil)',
      scores: { sub_function: 5, tag_overlap: 4, seniority: 5, years: 5, red_flag_penalty: 0 },
      composite: 4.6,
      passes: true,
    }
    expect(r.composite).toBeCloseTo(4.6)
    expect(r.passes).toBe(true)
  })
 
  it('Layer3Verdict is one of four bands', () => {
    const verdicts: Layer3Verdict['band'][] = ['Strong yes', 'Soft yes', 'Soft no', 'Strong no']
    expect(verdicts.length).toBe(4)
  })
})

npm test tests/lib/matching/types.test.ts

import type { NormalisedJD } from '@/lib/jd-normaliser'
 
export interface Layer1Scores {
  sub_function: number
  tag_overlap: number
  seniority: number
  years: number
  red_flag_penalty: number
}
 
export interface Layer1Result {
  jd_id: string
  cv_id: string
  scores: Layer1Scores
  composite: number
  passes: boolean
  drop_reason?: 'sub_function_mismatch' | 'composite_below_4' | 'hard_gate'
  adjacent_match?: AdjacentMatchEvidence
}
 
export interface AdjacentMatchEvidence {
  proposed_adjacency: { from: string; to: string }
  weight: number
  reasoning: string
  cv_evidence: string
  jd_evidence: string
  recommend_ratification: boolean
  status: 'live_inference' | 'ratified_config'
}
 
export interface Layer2DimensionScore {
  score: 1 | 2 | 3 | 4 | 5
  evidence: string[]
  notes: string
  low_evidence?: boolean
}
 
export interface Layer2RedFlagOrStrength {
  signal: string
  evidence: string
}
 
export interface Layer2Result {
  jd_id: string
  cv_id: string
  executive_summary: string
  dimensions: {
    experience_alignment: Layer2DimensionScore
    skills_adjacency: Layer2DimensionScore | null
    technical_knowledge: Layer2DimensionScore
    tools_and_systems: Layer2DimensionScore
    education_certifications: Layer2DimensionScore
    red_flags: { items: Layer2RedFlagOrStrength[] }
    strengths: { items: Layer2RedFlagOrStrength[] }
  }
  composite_l2_score: number
  confidence: number
}
 
export interface Layer3Verdict {
  band: 'Strong yes' | 'Soft yes' | 'Soft no' | 'Strong no'
  rationale: string
}
 
export interface MatchRecord {
  jd_id: string
  cv_id: string
  jd_snapshot: NormalisedJD
  layer1: Layer1Result
  layer2: Layer2Result | null
  layer3: Layer3Verdict
  generated_at: string
}

npm test tests/lib/matching/types.test.ts

git add src/lib/matching/types.ts tests/lib/matching/types.test.ts
git commit -m "feat(matching): add Layer1/Layer2/Layer3 + MatchRecord types"

import { describe, it, expect } from 'vitest'
import {
  scoreSubFunction, scoreTagOverlap, scoreSeniority, scoreYears,
  scoreRedFlagPenalty, computeLayer1,
} from '@/lib/matching/layer1-hard-fit'
import type { NormalisedJD } from '@/lib/jd-normaliser'
import type { NormalisedCV } from '@/lib/cv-normaliser'
import type { ParsedCV } from '@/lib/cv-parser/types'
 
const jd: NormalisedJD = {
  sub_function: 'cargo-ops',
  sub_function_display: 'Operations - cargo, commodities brokerage',
  tags: ['energy:lng'],
  must_have_tags: ['energy:lng'],
  nice_to_have_tags: ['vessel:lng-carrier'],
  normalised_title: 'Cargo Operations Executive - LNG',
  seniority_tier: 'Mid',
  min_years: 3,
  confidence: 0.9,
}
 
const cvLngMid: NormalisedCV = {
  sub_function: 'cargo-ops',
  sub_function_display: 'Operations - cargo, commodities brokerage',
  tags: ['energy:lng', 'energy:lpg'],
  normalised_title: 'LNG Cargo Operations Executive',
  seniority_tier: 'Mid',
  search_queries: [],
  confidence: 0.9,
}
 
const parsedCvClean: Partial<ParsedCV> = {
  signals: {
    total_years_experience: { value: 4, confidence: 0.9 },
    career_gaps: { value: [], confidence: 0.9 },
    short_tenures: { value: [], confidence: 0.9 },
  } as ParsedCV['signals'],
  parse_metadata: {
    source_file: '', file_type: 'pdf', parse_status: 'success',
    unreadable_reason: null, overall_confidence: 0.9,
    parsed_at: '', ungrounded_items: [], stale_cv: false, last_role_end: null,
  },
}
 
describe('scoreSubFunction', () => {
  it('exact match scores 5', () => {
    expect(scoreSubFunction(jd, cvLngMid)).toBe(5)
  })
  it('mismatch scores 0', () => {
    expect(scoreSubFunction(jd, { ...cvLngMid, sub_function: 'risk-analytics' })).toBe(0)
  })
})
 
describe('scoreTagOverlap', () => {
  it('full must-have overlap scores 5', () => {
    expect(scoreTagOverlap(jd, cvLngMid)).toBe(5)
  })
  it('zero overlap scores 0', () => {
    const cvNoLng = { ...cvLngMid, tags: ['energy:oil'] }
    expect(scoreTagOverlap(jd, cvNoLng)).toBe(0)
  })
  it('half overlap on two must-haves scores 2.5', () => {
    const jdTwo = { ...jd, must_have_tags: ['energy:lng', 'vessel:lng-carrier'] }
    expect(scoreTagOverlap(jdTwo, cvLngMid)).toBeCloseTo(2.5)
  })
})
 
describe('scoreSeniority', () => {
  it('exact tier scores 5', () => {
    expect(scoreSeniority(jd, cvLngMid)).toBe(5)
  })
  it('off-by-one tier scores 3', () => {
    expect(scoreSeniority(jd, { ...cvLngMid, seniority_tier: 'Senior' })).toBe(3)
  })
  it('off-by-two tier scores 1', () => {
    expect(scoreSeniority(jd, { ...cvLngMid, seniority_tier: 'Lead' })).toBe(1)
  })
  it('off-by-three+ scores 0', () => {
    expect(scoreSeniority(jd, { ...cvLngMid, seniority_tier: 'Head' })).toBe(0)
  })
})
 
describe('scoreYears', () => {
  it('above floor scores 5', () => {
    expect(scoreYears(jd, parsedCvClean as ParsedCV)).toBe(5)
  })
  it('within 80% of floor scores 3', () => {
    const cv = { ...parsedCvClean, signals: { ...parsedCvClean.signals!, total_years_experience: { value: 2.5, confidence: 0.9 } } } as ParsedCV
    expect(scoreYears(jd, cv)).toBe(3)
  })
  it('below 80% of floor scores 0', () => {
    const cv = { ...parsedCvClean, signals: { ...parsedCvClean.signals!, total_years_experience: { value: 1, confidence: 0.9 } } } as ParsedCV
    expect(scoreYears(jd, cv)).toBe(0)
  })
  it('null floor scores 5', () => {
    expect(scoreYears({ ...jd, min_years: null }, parsedCvClean as ParsedCV)).toBe(5)
  })
})
 
describe('scoreRedFlagPenalty', () => {
  it('clean CV has 0 penalty', () => {
    expect(scoreRedFlagPenalty(parsedCvClean as ParsedCV)).toBe(0)
  })
  it('stale CV penalises -2', () => {
    const cv = { ...parsedCvClean, parse_metadata: { ...parsedCvClean.parse_metadata!, stale_cv: true } } as ParsedCV
    expect(scoreRedFlagPenalty(cv)).toBe(-2)
  })
  it('one career gap penalises -1', () => {
    const cv = { ...parsedCvClean, signals: { ...parsedCvClean.signals!, career_gaps: { value: [{ from: '2022-01', to: '2022-08', months: 7 }], confidence: 0.9 } } } as ParsedCV
    expect(scoreRedFlagPenalty(cv)).toBe(-1)
  })
})
 
describe('computeLayer1', () => {
  it('strong match passes with composite >= 4', () => {
    const r = computeLayer1(jd, cvLngMid, parsedCvClean as ParsedCV, 'jd-1', 'cv-1')
    expect(r.passes).toBe(true)
    expect(r.composite).toBeGreaterThanOrEqual(4)
  })
  it('sub-function mismatch drops with reason', () => {
    const r = computeLayer1(jd, { ...cvLngMid, sub_function: 'risk-analytics' }, parsedCvClean as ParsedCV, 'jd-1', 'cv-2')
    expect(r.passes).toBe(false)
    expect(r.drop_reason).toBe('sub_function_mismatch')
  })
  it('composite < 4 drops with composite_below_4', () => {
    const cv = { ...cvLngMid, tags: ['energy:oil'], seniority_tier: 'Junior' as const }
    const parsedThin = { ...parsedCvClean, signals: { ...parsedCvClean.signals!, total_years_experience: { value: 1, confidence: 0.9 } } } as ParsedCV
    const r = computeLayer1(jd, cv, parsedThin, 'jd-1', 'cv-3')
    expect(r.passes).toBe(false)
    expect(r.drop_reason).toBe('composite_below_4')
  })
})

npm test tests/lib/matching/layer1-hard-fit.test.ts

import type { NormalisedJD, SeniorityTier } from '@/lib/jd-normaliser'
import type { NormalisedCV } from '@/lib/cv-normaliser'
import type { ParsedCV } from '@/lib/cv-parser/types'
import type { Layer1Result, Layer1Scores } from './types'
 
const TIERS: SeniorityTier[] = ['Junior', 'Mid', 'Senior', 'Lead', 'Head']
 
export function scoreSubFunction(jd: NormalisedJD, cv: NormalisedCV): number {
  return jd.sub_function === cv.sub_function ? 5 : 0
}
 
export function scoreTagOverlap(jd: NormalisedJD, cv: NormalisedCV): number {
  if (jd.must_have_tags.length === 0) return 5
  const cvTagSet = new Set(cv.tags)
  const overlap = jd.must_have_tags.filter(t => cvTagSet.has(t)).length
  return Math.round((5 * overlap / jd.must_have_tags.length) * 100) / 100
}
 
export function scoreSeniority(jd: NormalisedJD, cv: NormalisedCV): number {
  const delta = Math.abs(TIERS.indexOf(jd.seniority_tier) - TIERS.indexOf(cv.seniority_tier))
  if (delta === 0) return 5
  if (delta === 1) return 3
  if (delta === 2) return 1
  return 0
}
 
export function scoreYears(jd: NormalisedJD, parsedCv: ParsedCV): number {
  if (jd.min_years === null) return 5
  const years = parsedCv.signals.total_years_experience.value
  if (years >= jd.min_years) return 5
  if (years >= jd.min_years * 0.8) return 3
  return 0
}
 
export function scoreRedFlagPenalty(parsedCv: ParsedCV): number {
  let penalty = 0
  if (parsedCv.parse_metadata.stale_cv) penalty -= 2
  const gaps = parsedCv.signals.career_gaps.value.filter(g => g.months > 6).length
  penalty -= gaps
  const shortTenureClusters = parsedCv.signals.short_tenures.value.length >= 2 ? 1 : 0
  penalty -= shortTenureClusters
  return penalty
}
 
export function computeLayer1(
  jd: NormalisedJD,
  cv: NormalisedCV,
  parsedCv: ParsedCV,
  jd_id: string,
  cv_id: string,
): Layer1Result {
  const scores: Layer1Scores = {
    sub_function:     scoreSubFunction(jd, cv),
    tag_overlap:      scoreTagOverlap(jd, cv),
    seniority:        scoreSeniority(jd, cv),
    years:            scoreYears(jd, parsedCv),
    red_flag_penalty: scoreRedFlagPenalty(parsedCv),
  }
  const composite = Math.round(
    ((scores.sub_function + scores.tag_overlap + scores.seniority + scores.years) / 4
      + scores.red_flag_penalty) * 100,
  ) / 100
 
  if (scores.sub_function === 0) {
    return { jd_id, cv_id, scores, composite, passes: false, drop_reason: 'sub_function_mismatch' }
  }
  if (composite < 4) {
    return { jd_id, cv_id, scores, composite, passes: false, drop_reason: 'composite_below_4' }
  }
  return { jd_id, cv_id, scores, composite, passes: true }
}

npm test tests/lib/matching/layer1-hard-fit.test.ts

git add src/lib/matching/layer1-hard-fit.ts tests/lib/matching/layer1-hard-fit.test.ts
git commit -m "feat(matching): add Layer 1 deterministic hard-fit scoring"

{
  "adjacencies": [],
  "deny_list": []
}

import { describe, it, expect, beforeEach } from 'vitest'
import fs from 'fs'
import path from 'path'
import {
  loadAdjacencyConfig, lookupAdjacency, isDenied,
  appendRatified, appendDenied,
} from '@/lib/matching/adjacency/config'
 
const CONFIG_PATH = path.resolve(__dirname, '../../../../config/adjacency-ratified.json')
 
describe('adjacency config', () => {
  beforeEach(() => {
    fs.writeFileSync(CONFIG_PATH, JSON.stringify({ adjacencies: [], deny_list: [] }, null, 2))
  })
 
  it('loadAdjacencyConfig returns empty defaults', () => {
    const cfg = loadAdjacencyConfig()
    expect(cfg.adjacencies).toEqual([])
    expect(cfg.deny_list).toEqual([])
  })
 
  it('appendRatified persists a new pair', () => {
    appendRatified({ from: 'vessel:tanker', to: 'energy:lng', weight: 0.8, rationale: 'LNG carriers are tankers.', ratified_by: 'team@calibre.sg' })
    const cfg = loadAdjacencyConfig()
    expect(cfg.adjacencies).toHaveLength(1)
    expect(cfg.adjacencies[0].weight).toBe(0.8)
  })
 
  it('lookupAdjacency finds a ratified pair', () => {
    appendRatified({ from: 'vessel:tanker', to: 'energy:lng', weight: 0.8, rationale: '...', ratified_by: 'team@calibre.sg' })
    const hit = lookupAdjacency('vessel:tanker', 'energy:lng')
    expect(hit?.weight).toBe(0.8)
  })
 
  it('appendDenied adds to deny_list and isDenied returns true', () => {
    appendDenied({ from: 'vessel:container', to: 'energy:lng', rationale: 'Box ship ops does not transfer.', rejected_by: 'team@calibre.sg' })
    expect(isDenied('vessel:container', 'energy:lng')).toBe(true)
  })
})

npm test tests/lib/matching/adjacency/config.test.ts

import fs from 'fs'
import path from 'path'
 
const CONFIG_PATH = path.resolve(process.cwd(), 'config/adjacency-ratified.json')
 
export interface RatifiedAdjacency {
  from: string
  to: string
  weight: number
  rationale: string
  ratified_by: string
  ratified_at?: string
}
 
export interface DenyEntry {
  from: string
  to: string
  rationale: string
  rejected_by: string
  rejected_at?: string
}
 
export interface AdjacencyConfig {
  adjacencies: RatifiedAdjacency[]
  deny_list: DenyEntry[]
}
 
export function loadAdjacencyConfig(): AdjacencyConfig {
  if (!fs.existsSync(CONFIG_PATH)) {
    return { adjacencies: [], deny_list: [] }
  }
  const raw = fs.readFileSync(CONFIG_PATH, 'utf-8')
  return JSON.parse(raw) as AdjacencyConfig
}
 
function saveAdjacencyConfig(cfg: AdjacencyConfig): void {
  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true })
  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2))
}
 
function pairMatches(from: string, to: string, a: { from: string; to: string }): boolean {
  return (a.from === from && a.to === to) || (a.from === to && a.to === from)
}
 
export function lookupAdjacency(from: string, to: string): RatifiedAdjacency | null {
  const cfg = loadAdjacencyConfig()
  return cfg.adjacencies.find(a => pairMatches(from, to, a)) ?? null
}
 
export function isDenied(from: string, to: string): boolean {
  const cfg = loadAdjacencyConfig()
  return cfg.deny_list.some(d => pairMatches(from, to, d))
}
 
export function appendRatified(entry: Omit<RatifiedAdjacency, 'ratified_at'> & { ratified_at?: string }): void {
  const cfg = loadAdjacencyConfig()
  cfg.adjacencies.push({ ...entry, ratified_at: entry.ratified_at ?? new Date().toISOString() })
  saveAdjacencyConfig(cfg)
}
 
export function appendDenied(entry: Omit<DenyEntry, 'rejected_at'> & { rejected_at?: string }): void {
  const cfg = loadAdjacencyConfig()
  cfg.deny_list.push({ ...entry, rejected_at: entry.rejected_at ?? new Date().toISOString() })
  saveAdjacencyConfig(cfg)
}

npm test tests/lib/matching/adjacency/config.test.ts

git add config/adjacency-ratified.json src/lib/matching/adjacency/config.ts tests/lib/matching/adjacency/config.test.ts
git commit -m "feat(matching): add adjacency config loader (ratified + deny-list)"

import { describe, it, expect } from 'vitest'
import fs from 'fs'
import path from 'path'
import { proposeAdjacency } from '@/lib/matching/adjacency/live-inference'
import type { ParsedCV } from '@/lib/cv-parser/types'
import type { NormalisedJD } from '@/lib/jd-normaliser'
 
function loadJSON<T>(rel: string): T {
  return JSON.parse(fs.readFileSync(path.resolve(__dirname, rel), 'utf-8'))
}
 
describe('proposeAdjacency', () => {
  it('proposes vessel:tanker → energy:lng for a Tanker CV against an LNG JD', async () => {
    const jd = loadJSON<NormalisedJD>('../../../../outputs/normalised-jds/JD for Cargo Operator (LNG).json')
    const cv = loadJSON<ParsedCV>('../../../../outputs/parsed-cvs/Amardeep Singh (Ship Ops, Tanker).json')
    const proposal = await proposeAdjacency({
      jd,
      cv,
      cvTags: ['vessel:tanker'],
    })
    expect(proposal).not.toBeNull()
    expect(proposal!.proposed_adjacency.to).toBe('energy:lng')
    expect(proposal!.weight).toBeGreaterThan(0)
    expect(proposal!.cv_evidence.length).toBeGreaterThan(0)
  }, 60000)
})

npm test tests/lib/matching/adjacency/live-inference.test.ts

import Anthropic from '@anthropic-ai/sdk'
import type { ParsedCV } from '@/lib/cv-parser/types'
import type { NormalisedJD } from '@/lib/jd-normaliser'
import type { AdjacentMatchEvidence } from '../types'
import { loadAdjacencyConfig } from './config'
 
const client = new Anthropic()
 
const ADJACENCY_TOOL: Anthropic.Tool = {
  name: 'propose_adjacency',
  description: 'Propose a skills-adjacency pair between a CV tag and a JD must-have tag, with verbatim evidence.',
  input_schema: {
    type: 'object' as const,
    required: ['proposed_adjacency', 'weight', 'reasoning', 'cv_evidence', 'jd_evidence', 'recommend_ratification'],
    properties: {
      proposed_adjacency: {
        type: 'object',
        required: ['from', 'to'],
        properties: { from: { type: 'string' }, to: { type: 'string' } },
      },
      weight: { type: 'number', minimum: 0, maximum: 1 },
      reasoning: { type: 'string' },
      cv_evidence: { type: 'string' },
      jd_evidence: { type: 'string' },
      recommend_ratification: { type: 'boolean' },
    },
  },
}
 
interface ProposeArgs {
  jd: NormalisedJD
  cv: ParsedCV
  cvTags: string[]
}
 
export async function proposeAdjacency({ jd, cv, cvTags }: ProposeArgs): Promise<AdjacentMatchEvidence | null> {
  const ratified = loadAdjacencyConfig().adjacencies
 
  const cvEmployment = cv.employment_history.map(e => ({
    title: e.raw_title.value,
    employer: e.employer.value,
    description: e.description_summary.value,
  }))
 
  const response = await client.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    tools: [ADJACENCY_TOOL],
    tool_choice: { type: 'tool', name: 'propose_adjacency' },
    messages: [
      {
        role: 'user',
        content: `You are evaluating whether a candidate's experience transfers to a Job Description's required tags.
 
The candidate's tags do NOT directly intersect the JD's must-have tags. Your job is to propose ONE adjacency pair if a transferable skill exists, with verbatim evidence from BOTH the CV and the JD.
 
JD must-have tags: ${JSON.stringify(jd.must_have_tags)}
JD normalised title: ${jd.normalised_title}
 
CV tags: ${JSON.stringify(cvTags)}
CV employment history (titles + summaries):
${JSON.stringify(cvEmployment, null, 2)}
 
Existing ratified adjacencies (use these as the pattern for what counts as valid transfer):
${JSON.stringify(ratified, null, 2)}
 
Rules:
- Pick exactly ONE proposed_adjacency: from = a CV tag, to = a JD must-have tag.
- weight = 0.0 (no transfer) to 1.0 (perfect transfer). Be conservative — 0.5-0.8 is typical for genuine adjacency.
- cv_evidence MUST be a verbatim quote from the CV employment history above.
- jd_evidence MUST be the JD must-have tag string itself.
- recommend_ratification = true ONLY if the adjacency is clear and would generalise to other candidates.`,
      },
    ],
  })
 
  const toolUse = response.content.find(b => b.type === 'tool_use')
  if (!toolUse || toolUse.type !== 'tool_use') return null
 
  const out = toolUse.input as Omit<AdjacentMatchEvidence, 'status'>
  return { ...out, status: 'live_inference' }
}

npm test tests/lib/matching/adjacency/live-inference.test.ts

git add src/lib/matching/adjacency/live-inference.ts tests/lib/matching/adjacency/live-inference.test.ts
git commit -m "feat(matching): add live-inference adjacency proposal via Claude"

import { describe, it, expect, beforeEach } from 'vitest'
import fs from 'fs'
import path from 'path'
import { resolveAdjacency, applyAdjacencyBoost } from '@/lib/matching/adjacency/resolver'
import type { NormalisedJD } from '@/lib/jd-normaliser'
import type { NormalisedCV } from '@/lib/cv-normaliser'
import type { ParsedCV } from '@/lib/cv-parser/types'
 
const CONFIG_PATH = path.resolve(__dirname, '../../../../config/adjacency-ratified.json')
 
const jd: NormalisedJD = {
  sub_function: 'cargo-ops',
  sub_function_display: '...',
  tags: ['energy:lng'],
  must_have_tags: ['energy:lng'],
  nice_to_have_tags: [],
  normalised_title: 'LNG Cargo Ops',
  seniority_tier: 'Mid',
  min_years: 3,
  confidence: 0.9,
}
 
const cvTanker: NormalisedCV = {
  sub_function: 'ship-ops',
  sub_function_display: '...',
  tags: ['vessel:tanker'],
  normalised_title: 'Tanker Ops',
  seniority_tier: 'Mid',
  search_queries: [],
  confidence: 0.9,
}
 
const minimalParsedCv: Partial<ParsedCV> = {
  employment_history: [{
    raw_title: { value: 'Tanker Operator', confidence: 0.9 },
    employer: { value: 'BW Maritime', confidence: 0.9 },
    start_date: { value: '2020-01', confidence: 0.9 },
    end_date: { value: null, confidence: null },
    description_summary: { value: 'Handled chemical tankers across SE Asia routes.', confidence: 0.9 },
  }],
}
 
describe('resolveAdjacency', () => {
  beforeEach(() => {
    fs.writeFileSync(CONFIG_PATH, JSON.stringify({ adjacencies: [], deny_list: [] }, null, 2))
  })
 
  it('returns null when CV tags fully intersect JD must-haves', async () => {
    const cvLng: NormalisedCV = { ...cvTanker, tags: ['energy:lng'], sub_function: 'cargo-ops' }
    const r = await resolveAdjacency(jd, cvLng, minimalParsedCv as ParsedCV)
    expect(r).toBeNull()
  })
 
  it('uses ratified config when a matching entry exists', async () => {
    fs.writeFileSync(CONFIG_PATH, JSON.stringify({
      adjacencies: [{ from: 'vessel:tanker', to: 'energy:lng', weight: 0.8, rationale: 'LNG carriers are tankers.', ratified_by: 'team@calibre.sg' }],
      deny_list: [],
    }, null, 2))
    const r = await resolveAdjacency(jd, cvTanker, minimalParsedCv as ParsedCV)
    expect(r?.status).toBe('ratified_config')
    expect(r?.weight).toBe(0.8)
  })
 
  it('returns null when pair is in deny_list (no live inference)', async () => {
    fs.writeFileSync(CONFIG_PATH, JSON.stringify({
      adjacencies: [],
      deny_list: [{ from: 'vessel:tanker', to: 'energy:lng', rationale: 'rejected', rejected_by: 'team@calibre.sg' }],
    }, null, 2))
    const r = await resolveAdjacency(jd, cvTanker, minimalParsedCv as ParsedCV)
    expect(r).toBeNull()
  })
})
 
describe('applyAdjacencyBoost', () => {
  it('boosts tag_overlap by weight when adjacency hits a must-have', () => {
    const original = { tag_overlap: 0 }
    const boosted = applyAdjacencyBoost(original, jd, {
      proposed_adjacency: { from: 'vessel:tanker', to: 'energy:lng' },
      weight: 0.8,
      reasoning: '...', cv_evidence: '...', jd_evidence: 'energy:lng',
      recommend_ratification: true, status: 'ratified_config',
    })
    expect(boosted.tag_overlap).toBe(4) // 0.8 * 5
  })
 
  it('does not boost when adjacency target is not in must_have_tags', () => {
    const r = applyAdjacencyBoost({ tag_overlap: 1 }, jd, {
      proposed_adjacency: { from: 'vessel:tanker', to: 'energy:oil' },
      weight: 0.8, reasoning: '...', cv_evidence: '...', jd_evidence: 'energy:oil',
      recommend_ratification: true, status: 'ratified_config',
    })
    expect(r.tag_overlap).toBe(1)
  })
})