christian/grant-outreach-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(scoring): 990-PF funder-precedent index — the 25-point subscore goes live

Browse Source 
New funders/funder_grants schema + ingest990pf monthly workflow: IRS BMF
state file discovers NH private foundations (747), e-file index CSVs
select their latest 990-PF filings, batch ZIPs stream through fflate
(4/run cap, most-hits-first, deferred logged), grants-paid rows land in
funder_grants, and funders with >=2 NH grants synthesize rolling grant
rows (source irs_990pf, funder_ein linked) that flow through the
existing embed+match pipeline.

Scoring v2: funderPrecedentSubscore tiers repeated in-state giving
(1/3/5/10 -> 8/15/20/25); easy win = >=65 total AND >=12 precedent
(plan's precedent floor); scale is the full 0-100. Rolling deadlines
pass the runway gate. Retrieval computes per-funder in-state counts and
exposes funder_ein.

Lead-quality gates from the first precedent run's failures: candidate
orgs exclude NTEE T* grantmakers; self-matches gated by EIN + normalized
name (NHDOJ registers foundations as charities, several without resolved
EINs — the first run's top 'leads' were foundations matched to
themselves).

Live: ~6.5GB of IRS batches processed, 2,766 grants-paid rows, 123
synthesized foundation grants, 89 easy wins across 27 orgs, credible
top-10 (AIDS Response-Seacoast -> Foundation for Seacoast Health, 25/25
precedent). 153 tests green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Croissant Le Doux
2026-07-16 18:17:28 -04:00
parent 0ee478ec3d
commit 63b58e514d
34 changed files with 3634 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
packages/outreach-core/src/matches/scoring.ts
View File

@@ -4,16 +4,15 @@
* the match workflow supplies the embedding similarity, everything else
* derives from columns.
*
* v1 weights (funder precedent's 25 points are NOT yet awarded — the
* 990-PF index is a later deliverable, so the achievable maximum is 75,
* not 100). `subscores` records each component so weights can be re-tuned
* from review/booking data without re-deriving inputs.
* `subscores` records each component so weights can be re-tuned from
* review/booking data without re-deriving inputs.
*
* mission fit 30 embedding cosine similarity, scaled
* capacity fit 15 award ceiling vs org revenue (sweet spot 10–75%)
* competition 15 state/NH-restricted pools beat national ones
* effort 10 LOI/short-form beat full federal
* runway 5 3–10 weeks to deadline is ideal
* mission fit 30 embedding cosine similarity, scaled
* funder precedent 25 historical giving into the org's state (990-PF)
* capacity fit 15 award ceiling vs org revenue (sweet spot 10–75%)
* competition 15 state/NH-restricted pools beat national ones
* effort 10 LOI/short-form beat full federal
* runway 5 3–10 weeks to deadline is ideal
*/
export interface MatchSubscores {
@@ -22,8 +21,7 @@ export interface MatchSubscores {
readonly competition: number;
readonly effort: number;
readonly runway: number;
/** Not yet computed — reserved so the jsonb shape is stable. */
readonly funderPrecedent: 0;
readonly funderPrecedent: number;
}
export interface ScoreMatchInput {
@@ -39,16 +37,25 @@ export interface ScoreMatchInput {
| 'unknown';
readonly closeDate: Date | null;
readonly now: Date;
/**
* Historical grants this funder has paid to recipients in the org's
* state (from the 990-PF index). Null = no precedent data for this
* grant's funder (e.g. federal agencies) — scores 0, not neutral: the
* plan weights precedent as the strongest single predictor, and absence
* of evidence should rank below presence.
*/
readonly funderStateGrantCount: number | null;
}
export const ACHIEVABLE_MAX_SCORE = 75;
export const ACHIEVABLE_MAX_SCORE = 100;
/**
* "Easy win" threshold, v1: two-thirds of the achievable maximum. The
* plan's full definition also requires a funder-precedent floor — that
* gate returns when the 990-PF index lands; thresholds re-tune on review
* and demo-booking data regardless.
* "Easy win" threshold. With the 990-PF precedent subscore live the scale
* is the plan's full 0–100; the plan's >=75 easy-win bar applies, plus its
* precedent floor (see scoreMatch). Thresholds re-tune on review and
* demo-booking data.
*/
export const EASY_WIN_THRESHOLD = 50;
export const EASY_WIN_THRESHOLD = 65;
export const EASY_WIN_MIN_PRECEDENT = 12;
/** Similarity below this scores 0 fit; above the ceiling scores full fit. */
const SIMILARITY_FLOOR = 0.45;
@@ -115,6 +122,22 @@ export function effortSubscore(
}
}
/**
* Funder precedent (25): "a foundation that gave to three NH orgs like
* this one is a near-certain match for a fourth" — the plan's strongest
* single predictor. v1 measures repeated giving into the org's state;
* NTEE-level matching arrives when recipient orgs get resolved to EINs.
*/
export function funderPrecedentSubscore(
funderStateGrantCount: number | null,
): number {
if (funderStateGrantCount == null || funderStateGrantCount <= 0) return 0;
if (funderStateGrantCount >= 10) return 25;
if (funderStateGrantCount >= 5) return 20;
if (funderStateGrantCount >= 3) return 15;
return 8;
}
const MS_PER_WEEK = 7 * 24 * 60 * 60 * 1000;
/** 3–10 weeks out is ideal: urgent enough to act on, long enough to apply. */
@@ -140,7 +163,7 @@ export function scoreMatch(input: ScoreMatchInput): ScoredMatch {
competition: competitionSubscore(input.geographicScope),
effort: effortSubscore(input.applicationEffortEstimate),
runway: runwaySubscore(input.closeDate, input.now),
funderPrecedent: 0,
funderPrecedent: funderPrecedentSubscore(input.funderStateGrantCount),
};
const totalScore =
@@ -148,11 +171,14 @@ export function scoreMatch(input: ScoreMatchInput): ScoredMatch {
subscores.capacityFit +
subscores.competition +
subscores.effort +
subscores.runway;
subscores.runway +
subscores.funderPrecedent;
return {
totalScore,
subscores,
easyWin: totalScore >= EASY_WIN_THRESHOLD,
easyWin:
totalScore >= EASY_WIN_THRESHOLD &&
subscores.funderPrecedent >= EASY_WIN_MIN_PRECEDENT,
};
}