christian/grant-outreach-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0ee478ec3d622d40e496178fccae7553892b10b1
grant-outreach-engine/docs/features/scoring.md
Croissant Le Doux 0ee478ec3d feat(scoring): match-generation workflow — scoring engine v1 (Stage 2, step 2) 
matchGrants (nightly 05:15): per candidate org (NH + good standing +
primary ICP) ensure a v0 NTEE-derived profile embedding (RETRIEVAL_QUERY,
confidence 0.2 stub the Stage 4 profiler upgrades in place), retrieve
top-50 open grants by pgvector cosine with SQL-enforced cheap gates
(deadline >=21d, ceiling >=10K), run entity/geography gates in TS,
score deterministically, upsert pair-keyed matches, reassign hero.

Scoring: pure scoreMatch (mission fit 30 / capacity 15 / competition 15
/ effort 10 / runway 5; precedent's 25 reserved until the 990-PF index;
easy win >= 50/75). Eligibility gate now pattern-matches Grants.gov
applicantTypes prose, conservatively (ambiguous entries do not admit).
application_form_supported ignored for pass/fail per the manual-first
decision, still recorded in rationale.

Schema: unique (org_id, grant_id) on matches; unique org_id on
org_profiles (latest-profile semantics). Review queue query now ordered
hero > easy-win > score and capped at 100.

Live run: 64 orgs -> 3,200 matches in 28s, 0 easy wins / max 39 — the
honest result of an NIH-heavy 200-grant corpus vs NH service nonprofits;
engine mechanics verified, corpus breadth is the next lever.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-16 16:55:10 -04:00

2.3 KiB
Raw Blame History

Scoring engine v1 (Stage 2)

Nightly matchGrants workflow (05:15 UTC, after embeddings) — the plan's "SQL gates, vectors rank" hybrid.

Flow, per candidate org (NH + good standing + primary ICP)

  1. Profile embedding — v0 stub: NTEE-derived mission text (buildOrgMissionText) embedded as RETRIEVAL_QUERY, stored in org_profiles at confidence 0.2. The Stage 4 research profiler upgrades the row in place; this workflow doesn't change.
  2. Retrieval — serverListEligibleGrantsForOrg: one SQL statement enforcing the cheap hard gates (status open, embedded, deadline ≥ 21 days, ceiling ≥ $10K) with pgvector cosine ranking; top 50 per org.
  3. Remaining gates in TS — entity eligibility (entryAdmitsEntity: conservative pattern matching over Grants.gov applicantTypes prose; ambiguous entries do NOT admit) and geography (word-boundary state code + full state name). application_form_supported is deliberately ignored for pass/fail (2026-07-16 manual-first decision — draftability verified by hand for top leads); its failure still lands in rationale.gateFailures. Failed pairs are not stored.
  4. Deterministic subscores (scoreMatch, pure, tested): mission fit 30 (similarity 0.45–0.75 → 0–30) · capacity 15 (award 10–75% of revenue = sweet spot) · competition 15 (state-restricted ≫ national) · effort 10 · runway 5 (3–10 weeks ideal). Funder precedent (25) not yet awarded — achievable max is 75 until the 990-PF index lands; subscores jsonb keeps the full breakdown for reweighting. Easy win = total ≥ 50.
  5. Upsert + hero — pair-keyed upsert that never touches review fields (a human's reject stands even when scores move); serverAssignHeroMatch marks the org's top non-rejected gate-passing match.

First live run (2026-07-16)

64 orgs × top-50 grants → 3,200 matches, 0 gate failures (corpus was pre-filtered to nonprofit-eligible, federal = geography-unrestricted), 0 easy wins, max 39/75. That's the system being honest: the current corpus is 200 NIH-dominated federal research grants — wrong pond for $100K–$5M NH service nonprofits (similarity ceiling ~0.58). The engine's next real gains are corpus-side: NH state agency sources, 990-PF foundation ingestion, full Grants.gov detail backlog, real effort estimates.