Designing AI you can defend: explainability and fairness in AuraHire

AuraHire produces two kinds of score. The Profile Score rates a candidate's resume on its own merits — how strong is this resume? The Match Score rates a candidate against a specific job — how well does this person fit this role? Both are composed from weighted components, and both are computed server-side by OpenAI calls that are forbidden from returning free text. Every call uses OpenAI structured outputs derived from a Zod schema, so the model returns a validated JSON document the system can trust rather than prose it has to guess at.

That "no prompt without a JSON schema" rule is the foundation everything else rests on. A score isn't a sentence the model wrote; it's a structured object with components, sub-scores, weights, bands, and evidence — each field validated before it ever touches the database. If the model returns something off-shape, the call fails loudly instead of silently corrupting a candidate's record.

The governing rule is "no score without evidence." A numeric component never renders as a naked figure. It renders with its score, its max, its weight, a plain-language explanation, and one to three verbatim evidence excerpts pulled straight from the resume — each tagged positive, negative, or neutral, with a signed point contribution that explains how it moved the number.

I made that mechanically honest rather than decorative. The scoring prompts require that the sum of a component's evidence contributions equals the component score — and the engine recomputes the score from the sum and clamps it to the valid range, so any mismatch is overwritten. The explanation can't drift from the math. When a component scores below its max, the prompt forces at least one negative evidence item that names the specific gap (a missing required skill, no quantified outcomes, an education shortfall) rather than padding with generic praise.

There's a second explainability concern most tools ignore: who is allowed to read the evidence, and when. Verbatim resume quotes can leak the very identifiers redaction tries to hide. So every evidence row stores two variants — the full excerpt_text for the candidate's and admin's eyes, and a deterministically scrubbed excerpt_redacted that nulls names, emails, phones, and company tokens. Recruiters reading a breakdown before an interview see only the skills-anchored variant, so they evaluate the work, not the person.

That last point is what makes the system examinable end to end. The thesis appendix is literally reconstructed from this audit trail: pick any score, read the prompt version and weights it used, read the evidence it cited, and replay the decision. Explainability isn't a UI flourish bolted on at the end — it's a property of how every score is stored.

My strongest design decision on fairness is that it's enforced upstream, before scoring, rather than measured after the fact. The cleanest way to stop a model from discriminating on a name, a gender marker, or an address is to make sure it never sees them. So before any scoring engine runs, a resume passes through the hybrid PII redaction engine: a rule-based stage nulls contact.full_name, contact.email, contact.phone, and the LinkedIn/portfolio URLs, and an LLM-assisted stage scrubs residual identifiers — names, pronouns, age and gender markers — out of free-text summaries and responsibilities.

Redaction has a subtle trap I had to design around: if you simply delete a field, the model can't tell "absent" from "withheld," and a candidate gets silently penalized on Completeness for the redaction itself. So redacted content is replaced with a [REDACTED] sentinel, and the scoring prompts are written to treat it as a present-but-withheld field — equivalent to a real value being there — never as a gap. The redacted_fields array is persisted on every score row, so an admin can prove redaction happened for any decision after the fact.

On the job side, descriptions are scanned for biased language across four categories — gendered (rockstar, ninja, salesman), age-coded (young, energetic, digital native), ableist (must lift, stand all day, high-energy), and exclusionary ("culture fit" as a gate, available 24/7) — plus admin-defined custom terms. Flags surface inline in the editor, and publishing a job with unresolved flags requires an explicit written override reason that lands in both the bias_flags record and the append-only audit log. A flag moves through flagged → resolved | overridden, and the schema makes the override reason mandatory — you cannot override silently.

There's one more guardrail around the act of re-tuning itself. When an admin changes weights or band thresholds, a Preview Impact pass projects how the change would have moved recent applications against the current production weights — before anything is saved. Re-tuning the algorithm becomes a deliberate, inspectable act with a visible before/after, not a quiet edit that silently reshuffles every candidate's standing.

Explainability and fairness are only as trustworthy as the data layer underneath them. If a recruiter at company A could read company B's candidates, or a candidate could read another candidate's evidence, the whole defense collapses. So AuraHire treats the database as the last line of defense, not the first. Authorization is layered — frontend middleware, CORS, a Supabase JWT guard, then role and active-company guards in NestJS — and behind all of it, Row-Level Security on every user-data table in Postgres.

The 22 tables span identity, recruitment, candidate data, AI/scoring, notifications, and audit. The sensitive scoring tables — profile_scores, match_scores, evidence_excerpts, bias_flags — all carry RLS so that even if every application-layer check were bypassed, Postgres itself would refuse to hand a row to the wrong user. The policies are written by hand and kept reviewable independently of the schema, because an examiner should be able to read the access rules as plain SQL.

-- Defense in depth: even if every app-layer guard is bypassed,-- Postgres refuses to return a score row to the wrong user.ALTER TABLE public.match_scores ENABLE ROW LEVEL SECURITY; -- A candidate may read only their own match scores.CREATE POLICY "match_scores_candidate_select" ON public.match_scores  FOR SELECT USING (auth.uid() = candidate_id); -- A recruiter may read scores only for jobs they own.CREATE POLICY "match_scores_recruiter_select" ON public.match_scores  FOR SELECT USING (    EXISTS (      SELECT 1 FROM public.jobs      WHERE jobs.id = match_scores.job_id        AND jobs.recruiter_id = auth.uid()    )  ); -- Admins may read everything (for the fairness monitor + audit).CREATE POLICY "match_scores_admin_all" ON public.match_scores  FOR ALL USING (    EXISTS (      SELECT 1 FROM public.profiles      WHERE id = auth.uid() AND role = 'admin'    )  );

The same pattern repeats per table with the right ownership predicate: candidates own their resumes and applications, recruiters reach a candidate's record only through an application to a job they own, and admins see across tenants for oversight. The audit_logs table is the strict case — it has a read policy for admins and deliberately no insert, update, or delete policy from any user role. Writes happen only through the backend service role, and there is no path for application code to ever update or delete an audit row. Append-only by construction, not by convention.

AuraHire is a thesis system, but the constraints that shaped it generalize to any AI that makes a consequential decision about a person. If I had to compress it into rules I'd hand to anyone building in this space:

• Never let a prompt return free text. Use structured outputs validated by a schema. A score should be an object with components, weights, bands, and evidence — not a sentence you have to parse and trust.
• Never show a score without its evidence. Make the explanation mechanically equal to the math — sum the evidence contributions back to the score — so the "why" can't drift from the "what."
• Enforce fairness upstream, not in a dashboard. Redact identifiers before the model sees them, and flag biased job language before publish. A disparate-impact chart only tells you the harm already happened.
• Don't collect demographics to prove fairness. It contradicts redaction and creates a sensitive dataset you didn't need. Surface aggregate signals (flag counts, override rate) instead.
• Treat redaction as a present-but-withheld signal, never as missing data, or redaction itself becomes a scoring bug.
• Store reproducibility on every decision row — prompt version, model, weights snapshot, raw output — so a historical score stays interpretable after you re-tune the algorithm.
• Make the database the last line of defense. Row-Level Security on every user-data table, and an append-only audit log with no user-facing write path. Don't rely on the application layer alone.
• Make re-tuning a deliberate, inspectable act. Preview the impact of a weight change before saving, and require a written reason for every override. Quiet edits to a scoring algorithm are how bias creeps back in.

None of this makes an AI hiring decision perfect — no system can promise that. What it does is make the decision defensible: every score shows its work, every resume is scrubbed before a model judges it, and every consequential action leaves a trail you can replay. For something as consequential as deciding who gets a shot at a job, that's the floor, not the ceiling.