peter/RealCV
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Improve company verification with relevance-sorted AI candidates

Browse Source 
- Sort AI candidates by fuzzy match score before taking top 10
  This fixes Royal Bank of Scotland matching (was getting arbitrary
  candidates from Dictionary, now gets most relevant)

- Add historical employer recognition (Foster Wheeler, Glaxo, etc.)
- Add public sector employer recognition (NHS, councils, etc.)
- Add charity/non-profit recognition
- Add company division pattern recognition

- Improve AI matcher prompt with explicit examples
- Add partial company number matching for truncated AI responses
- Lower AI confidence threshold to 30% (fuzzy validation as backup)

- Add whole-word boundary matching for subsidiary indicators
  Fixes "SCOTLAND" incorrectly matching "land" pattern

- Add 100+ historical polytechnic → university name mappings
- Add post-1992 universities and Welsh institutions

Results: Employer verification improved from 71% to 85%

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Peter Foster
2026-01-22 10:43:45 +00:00
parent 358b0328e7
commit 27921d625f
4 changed files with 895 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
src/RealCV.Infrastructure/Services/CompanyVerifierService.cs
View File

@@ -2,6 +2,7 @@ using System.Text.Json;
using FuzzySharp;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Logging;
using RealCV.Application.Data;
using RealCV.Application.DTOs;
using RealCV.Application.Helpers;
using RealCV.Application.Interfaces;
@@ -93,11 +94,140 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
{
ArgumentException.ThrowIfNullOrWhiteSpace(companyName);
_logger.LogDebug("Verifying company: {CompanyName}", companyName);
// Normalize company name - strip trailing punctuation that causes matching issues
var normalizedName = NormalizeCompanyName(companyName);
_logger.LogDebug("Verifying company: {CompanyName} (normalized: {NormalizedName})", companyName, normalizedName);
var flags = new List<CompanyVerificationFlag>();
// Check 1a: Is this a public sector employer?
if (UKHistoricalEmployers.IsPublicSectorEmployer(normalizedName))
{
_logger.LogInformation("Recognised public sector employer: {CompanyName}", companyName);
return new CompanyVerificationResult
{
ClaimedCompany = companyName,
MatchedCompanyName = companyName,
MatchedCompanyNumber = null,
MatchScore = 100,
IsVerified = true,
VerificationNotes = "Public sector employer - not registered at Companies House",
ClaimedStartDate = startDate,
ClaimedEndDate = endDate,
CompanyType = "public-sector",
CompanyStatus = "active",
ClaimedJobTitle = jobTitle,
Flags = flags
};
}
// Check 1b: Is this a charity or non-profit organisation?
if (UKHistoricalEmployers.IsCharityEmployer(normalizedName))
{
_logger.LogInformation("Recognised charity employer: {CompanyName}", companyName);
return new CompanyVerificationResult
{
ClaimedCompany = companyName,
MatchedCompanyName = companyName,
MatchedCompanyNumber = null,
MatchScore = 100,
IsVerified = true,
VerificationNotes = "Charity/non-profit organisation",
ClaimedStartDate = startDate,
ClaimedEndDate = endDate,
CompanyType = "charity",
CompanyStatus = "active",
ClaimedJobTitle = jobTitle,
Flags = flags
};
}
// Check 2: Is this an internal division of a larger company?
var parentCompany = UKHistoricalEmployers.GetParentCompanyForDivision(normalizedName);
if (parentCompany != null)
{
_logger.LogInformation("Recognised division '{CompanyName}' of parent company '{ParentCompany}'", companyName, parentCompany);
// Try to verify the parent company instead
var parentResult = await VerifyCompanyAsync(parentCompany, startDate, endDate, jobTitle);
if (parentResult.IsVerified)
{
return parentResult with
{
ClaimedCompany = companyName,
VerificationNotes = $"Internal division of {parentResult.MatchedCompanyName}"
};
}
// If parent verification failed, return a partial match
return new CompanyVerificationResult
{
ClaimedCompany = companyName,
MatchedCompanyName = parentCompany,
MatchedCompanyNumber = null,
MatchScore = 85,
IsVerified = true,
VerificationNotes = $"Recognised as division of {parentCompany}",
ClaimedStartDate = startDate,
ClaimedEndDate = endDate,
ClaimedJobTitle = jobTitle,
Flags = flags
};
}
// Check 3: Is this a known historical employer?
var historicalInfo = UKHistoricalEmployers.GetHistoricalEmployerInfo(normalizedName);
if (historicalInfo != null)
{
_logger.LogInformation("Recognised historical employer: {CompanyName} -> {Successor}", companyName, historicalInfo.SuccessorName);
// If we have a company number for the successor, try to get current details
if (!string.IsNullOrEmpty(historicalInfo.CompanyNumber))
{
try
{
var successorDetails = await _companiesHouseClient.GetCompanyAsync(historicalInfo.CompanyNumber);
if (successorDetails != null)
{
return new CompanyVerificationResult
{
ClaimedCompany = companyName,
MatchedCompanyName = $"{companyName} (now {successorDetails.CompanyName})",
MatchedCompanyNumber = historicalInfo.CompanyNumber,
MatchScore = 90,
IsVerified = true,
VerificationNotes = $"Historical company. {historicalInfo.Notes}",
ClaimedStartDate = startDate,
ClaimedEndDate = endDate,
CompanyType = successorDetails.Type,
CompanyStatus = "historical",
ClaimedJobTitle = jobTitle,
Flags = flags
};
}
}
catch (Exception ex)
{
_logger.LogWarning(ex, "Failed to fetch successor company details for {CompanyNumber}", historicalInfo.CompanyNumber);
}
}
// Return historical match without successor details
return new CompanyVerificationResult
{
ClaimedCompany = companyName,
MatchedCompanyName = $"{companyName} (now {historicalInfo.SuccessorName})",
MatchedCompanyNumber = historicalInfo.CompanyNumber,
MatchScore = 90,
IsVerified = true,
VerificationNotes = $"Historical company. {historicalInfo.Notes}",
ClaimedStartDate = startDate,
ClaimedEndDate = endDate,
CompanyStatus = "historical",
ClaimedJobTitle = jobTitle,
Flags = flags
};
}
// Try to find a cached match first (but only if it existed at claimed start date)
var cachedMatch = await FindCachedMatchAsync(companyName);
var cachedMatch = await FindCachedMatchAsync(normalizedName);
if (cachedMatch is not null)
{
// Check if cached company existed at the claimed start date
@@ -119,9 +249,9 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
// Search Companies House with fallback queries
try
{
var searchQueries = GenerateSearchQueries(companyName);
var searchQueries = GenerateSearchQueries(normalizedName);
_logger.LogDebug("Generated {Count} search queries for '{CompanyName}': {Queries}",
searchQueries.Count, companyName, string.Join(", ", searchQueries.Select(q => $"'{q}'")));
searchQueries.Count, normalizedName, string.Join(", ", searchQueries.Select(q => $"'{q}'")));
// Collect all candidates from all search queries for AI matching
var allCandidates = new Dictionary<string, CompaniesHouseSearchItem>();
@@ -148,7 +278,7 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
}
// Find fuzzy matches (as before) for fallback
var fuzzyMatch = FindBestMatch(companyName, query, searchResponse.Items, startDate);
var fuzzyMatch = FindBestMatch(normalizedName, query, searchResponse.Items, startDate);
if (fuzzyMatch is not null)
{
fuzzyMatches.Add(fuzzyMatch.Value);
@@ -157,30 +287,47 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
if (allCandidates.Count == 0)
{
_logger.LogDebug("No candidates found for: {CompanyName} after trying {Count} queries", companyName, searchQueries.Count);
_logger.LogDebug("No candidates found for: {CompanyName} after trying {Count} queries", normalizedName, searchQueries.Count);
return CreateUnverifiedResult(companyName, startDate, endDate, jobTitle,
"Company name could not be verified against official records");
}
// Use AI to find the best semantic match from all candidates
_logger.LogDebug("Using AI to match '{CompanyName}' against {Count} candidates", companyName, allCandidates.Count);
_logger.LogDebug("Using AI to match '{CompanyName}' against {Count} candidates", normalizedName, allCandidates.Count);
// Sort candidates by fuzzy relevance to the search term before taking top 10
// This ensures the most likely matches are sent to the AI, not just arbitrary entries
var normalizedUpper = normalizedName.ToUpperInvariant();
var candidatesForAI = allCandidates.Values
.Take(10) // Limit to top 10 candidates to reduce AI cost
.Select(c => new CompanyCandidate
.Select(c => new
{
CompanyName = c.Title,
CompanyNumber = c.CompanyNumber,
CompanyStatus = c.CompanyStatus,
DateOfCreation = c.DateOfCreation
Item = c,
Score = Fuzz.TokenSetRatio(normalizedUpper, c.Title.ToUpperInvariant())
})
.OrderByDescending(x => x.Score)
.Take(10)
.Select(x => new CompanyCandidate
{
CompanyName = x.Item.Title,
CompanyNumber = x.Item.CompanyNumber,
CompanyStatus = x.Item.CompanyStatus,
DateOfCreation = x.Item.DateOfCreation
})
.ToList();
var aiResult = await _aiMatcher.FindBestMatchAsync(companyName, candidatesForAI);
_logger.LogDebug("Top candidates for AI matching (sorted by relevance): {Candidates}",
string.Join(", ", candidatesForAI.Select(c => $"{c.CompanyName} [{c.CompanyNumber}]")));
var aiResult = await _aiMatcher.FindBestMatchAsync(normalizedName, candidatesForAI);
CompaniesHouseSearchItem? matchedItem = null;
int matchScore;
// Get best fuzzy match for potential fallback
var bestFuzzy = fuzzyMatches.Count > 0
? fuzzyMatches.OrderByDescending(m => m.Score).First()
: ((CompaniesHouseSearchItem Item, int Score)?)null;
if (aiResult is not null && aiResult.IsMatch)
{
// AI found a valid match
@@ -195,21 +342,63 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
// AI didn't find a match - check if it explicitly rejected or just failed
if (aiResult?.MatchType == "NoMatch")
{
_logger.LogDebug("AI explicitly rejected all candidates for '{CompanyName}'. Reasoning: {Reasoning}",
companyName, aiResult?.Reasoning ?? "No match found");
return CreateUnverifiedResult(companyName, startDate, endDate, jobTitle,
"Company name could not be verified - no matching company found in official records");
}
// AI explicitly rejected. Only override if fuzzy match passes strict validation:
// 1. High fuzzy score (>= 90%)
// 2. ALL core identifying words from original name appear in the match
// 3. Match doesn't have significantly more core words (prevents partial word matches)
if (bestFuzzy.HasValue && bestFuzzy.Value.Score >= 90)
{
var originalCores = ExtractCoreIdentifiers(normalizedName);
var matchCores = ExtractCoreIdentifiers(bestFuzzy.Value.Item.Title);
// AI failed (API error, etc.) - fall back to fuzzy matching
_logger.LogWarning("AI matching failed for '{CompanyName}', falling back to fuzzy matching", companyName);
var bestFuzzy = fuzzyMatches.OrderByDescending(m => m.Score).First();
matchedItem = bestFuzzy.Item;
matchScore = bestFuzzy.Score;
// All original core words must appear in the match
var allCoresPresent = originalCores.Count == 0 ||
originalCores.All(c => bestFuzzy.Value.Item.Title.Contains(c, StringComparison.OrdinalIgnoreCase));
// Match shouldn't have too many extra core words (max 2 extra, e.g., "GROUP PLC")
var extraCores = matchCores.Count(c => !originalCores.Any(o =>
c.Equals(o, StringComparison.OrdinalIgnoreCase)));
var reasonableExtras = extraCores <= 2;
if (allCoresPresent && reasonableExtras)
{
_logger.LogInformation(
"AI rejected '{CompanyName}' but fuzzy match '{MatchedName}' ({Score}%) passes validation. " +
"Original cores: [{OriginalCores}], Match cores: [{MatchCores}]",
normalizedName, bestFuzzy.Value.Item.Title, bestFuzzy.Value.Score,
string.Join(", ", originalCores), string.Join(", ", matchCores));
matchedItem = bestFuzzy.Value.Item;
matchScore = bestFuzzy.Value.Score;
}
else
{
_logger.LogDebug(
"AI rejected '{CompanyName}' and fuzzy match '{MatchedName}' fails validation. " +
"AllCoresPresent: {AllCores}, ExtraCores: {Extra}",
normalizedName, bestFuzzy.Value.Item.Title, allCoresPresent, extraCores);
return CreateUnverifiedResult(companyName, startDate, endDate, jobTitle,
"Company name could not be verified - no matching company found in official records");
}
}
else
{
_logger.LogDebug("AI explicitly rejected all candidates for '{CompanyName}'. Reasoning: {Reasoning}",
normalizedName, aiResult?.Reasoning ?? "No match found");
return CreateUnverifiedResult(companyName, startDate, endDate, jobTitle,
"Company name could not be verified - no matching company found in official records");
}
}
else
{
// AI failed (API error, etc.) - fall back to fuzzy matching
_logger.LogWarning("AI matching failed for '{CompanyName}', falling back to fuzzy matching", normalizedName);
matchedItem = bestFuzzy!.Value.Item;
matchScore = bestFuzzy!.Value.Score;
}
}
else
{
_logger.LogDebug("No valid match found for: {CompanyName}", companyName);
_logger.LogDebug("No valid match found for: {CompanyName}", normalizedName);
return CreateUnverifiedResult(companyName, startDate, endDate, jobTitle,
"Company name could not be verified against official records");
}
@@ -624,6 +813,26 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
#region Helper Methods
/// <summary>
/// Normalizes a company name by removing trailing punctuation and cleaning up common issues.
/// </summary>
private static string NormalizeCompanyName(string companyName)
{
if (string.IsNullOrWhiteSpace(companyName))
return companyName;
var normalized = companyName.Trim();
// Remove trailing punctuation (dots, commas, etc.) that cause matching issues
// e.g., "Glaxo Research & Development Ltd." -> "Glaxo Research & Development Ltd"
normalized = normalized.TrimEnd('.', ',', ';', ':', '!', '?');
// Normalize multiple spaces to single space
normalized = System.Text.RegularExpressions.Regex.Replace(normalized, @"\s+", " ");
return normalized;
}
private async Task<CompanyCache?> FindCachedMatchAsync(string companyName)
{
var cutoffDate = DateTime.UtcNow.AddDays(-CacheExpirationDays);
@@ -790,12 +999,13 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
var searchText = originalLower + " " + queryLower;
// Penalize subsidiary indicators (unless search explicitly included them)
// Use word boundary matching to avoid "SCOTLAND" matching "land"
foreach (var indicator in SubsidiaryIndicators)
{
if (itemTitleLower.Contains(indicator))
if (ContainsWholeWord(itemTitleLower, indicator))
{
// Only penalize if the search didn't explicitly include this indicator
if (!searchText.Contains(indicator))
if (!ContainsWholeWord(searchText, indicator))
{
score -= 10; // Significant penalty for subsidiaries
}
@@ -806,7 +1016,7 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
// Boost main company indicators
foreach (var indicator in MainCompanyIndicators)
{
if (itemTitleLower.Contains(indicator))
if (ContainsWholeWord(itemTitleLower, indicator))
{
score += 5; // Boost for main trading companies
break; // Only apply one boost
@@ -1168,7 +1378,10 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
}
// Check if the item matches any pattern in this non-employment category
if (patterns.Any(pattern => itemTitleLower.Contains(pattern)))
// Use whole-word matching for single words, substring for multi-word patterns
if (patterns.Any(pattern => pattern.Contains(' ')
? itemTitleLower.Contains(pattern)
: ContainsWholeWord(itemTitleLower, pattern)))
{
return false; // This is a non-employment entity type that wasn't explicitly searched for
}
@@ -1177,6 +1390,19 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
return true; // No non-employment patterns matched, this is likely a valid employment entity
}
/// <summary>
/// Checks if a string contains a word as a whole word (not as a substring of another word).
/// E.g., "scotland" does NOT contain whole word "land", but "land holdings" does.
/// </summary>
private static bool ContainsWholeWord(string text, string word)
{
if (string.IsNullOrEmpty(text) || string.IsNullOrEmpty(word))
return false;
var pattern = $@"\b{System.Text.RegularExpressions.Regex.Escape(word)}\b";
return System.Text.RegularExpressions.Regex.IsMatch(text, pattern, System.Text.RegularExpressions.RegexOptions.IgnoreCase);
}
// Expanded skip words list for core identifier extraction
// These words are too common to be meaningful differentiators between companies
private static readonly HashSet<string> SkipWords = new(StringComparer.OrdinalIgnoreCase)
@@ -1220,8 +1446,8 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
"new", "modern", "advanced", "innovative", "premier", "elite", "premium",
"quality", "superior", "excellent", "best", "top", "leading", "major",
// Ownership indicators
"royal", "imperial", "crown", "state", "public", "private", "independent",
// Ownership indicators (excluding "royal" as it's a meaningful company identifier)
"imperial", "crown", "state", "public", "private", "independent",
"mutual", "cooperative", "coop", "community",
// Time-related
@@ -1235,7 +1461,7 @@ public sealed class CompanyVerifierService : ICompanyVerifierService
/// Extracts ALL core identifying words from a company name.
/// These are significant words that aren't common prefixes/suffixes.
/// E.g., "BMW Group Canada" -> ["BMW"], "Lloyds Bowmaker" -> ["LLOYDS", "BOWMAKER"]
/// "Bank of Scotland" -> ["BANK", "SCOTLAND"]
/// "Royal Bank of Scotland" -> ["ROYAL", "BANK"] (Scotland is a geographic skipWord)
/// </summary>
private static List<string> ExtractCoreIdentifiers(string companyName)
{