AI that checks its own blind spots.
FairLens is a multi-agent AI system that simulates a hiring panel and audits the panel's own reasoning for cognitive bias in real time. Three expert agents evaluate a candidate simultaneously. A fourth agent watches their reasoning and flags bias the moment it appears — inline, mid-sentence, before any verdict is reached. A fifth agent synthesizes a final debiased recommendation.
The gap between the raw panel verdict and the debiased verdict is the product.
Built for 5 Days of Gen AI — Google × Kaggle using Google ADK and Gemini 2.5 Flash.
🎥 YouTube Demo: (coming soon)
💻 GitHub Repository: https://github.com/PREMRAJESH/fairlens-verdict
🐳 Docker Deployment:
docker compose up --build-
Parallel hiring panel — Three LlmAgents run concurrently via ADK
ParallelAgent. Each agent forms an independent opinion with no shared context, making bias detection meaningful. -
Real-time bias auditing — A dedicated
BiasAuditoragent monitors all three transcripts and callsflag_bias()for every instance of cognitive bias detected. Eight bias types are flagged with severity ratings (LOW / MEDIUM / HIGH) and corrective reframes. -
Debiased verdict synthesis — The
VerdictSynthesizerreceives both the panel transcripts and the bias report, removes flagged reasoning, and produces two verdicts side by side: what the panel said, and what the evidence says. -
Live SSE streaming — Every token, every flag, every verdict streams from FastAPI to the React frontend in real time via Server-Sent Events. The bias flag card appears inline in the agent's transcript mid-sentence.
-
Google Search grounding — The Technical Interviewer uses ADK's built-in
google_searchtool autonomously. When a candidate claims a specific tech stack or project, the agent decides on its own to verify the claim against live web results. -
Triple provider fallback — Gemini 2.5 Flash is primary. If it hits a rate limit or fails, the pipeline automatically falls back to Grok (
grok-2-1212), then Groq (llama-3.3-70b-versatile). The frontend never sees an error — just a different provider chip. -
PDF resume parsing — Upload a resume PDF. PyMuPDF extracts the text server-side. Gemini structures it into the candidate JSON format. The user reviews and edits before running the panel.
| Bias Type | Description |
|---|---|
pedigree_bias |
Over-weighting school or company brand as a proxy for ability |
halo_effect |
One strong signal inflating evaluation of unrelated areas |
horn_effect |
One weak signal deflating evaluation of unrelated strengths |
anchoring |
First signal dominating all subsequent reasoning |
affinity_bias |
Favoring candidates who feel personally familiar |
attribution_bias |
Same behavior judged differently based on perceived group |
recency_bias |
Last signal mentioned dominating the overall verdict |
in_group_favoritism |
Belonging cues weighted over job-relevant evidence |
Each flag includes: the exact quoted phrase, which agent said it, severity level, explanation, and a corrective reframe.
# Full pipeline — pipeline.py
full_pipeline = SequentialAgent(
name="BiasAuditorPanel",
sub_agents=[panel, post_panel]
)
# Step 1 — all three run concurrently
panel = ParallelAgent(
name="HiringPanel",
sub_agents=[
technical_interviewer, # LlmAgent + google_search
culture_assessor, # LlmAgent
seniority_assessor, # LlmAgent
]
)
# Step 2 — strict order: audit before synthesize
post_panel = SequentialAgent(
name="AuditAndSynthesize",
sub_agents=[
bias_auditor, # LlmAgent + FunctionTool(flag_bias) + BuiltInPlanner
verdict_synthesizer, # LlmAgent + output_schema + BuiltInPlanner
]
)| Agent | File | Tools | Output Key | Planner |
|---|---|---|---|---|
TechnicalInterviewer |
agents/technical.py |
google_search |
technical_transcript |
— |
CultureFitAssessor |
agents/culture.py |
— | culture_transcript |
— |
SeniorityAssessor |
agents/seniority.py |
— | seniority_transcript |
— |
BiasAuditor |
agents/auditor.py |
FunctionTool(flag_bias) |
bias_report |
BuiltInPlanner(budget=8192) |
VerdictSynthesizer |
agents/synthesizer.py |
— | final_verdict |
BuiltInPlanner(budget=8192) |
All events are emitted by run_pipeline() via asyncio.Queue and consumed by useBackendRuntime() on the frontend.
| Event | Payload | UI Effect |
|---|---|---|
pipeline_start |
{ provider } |
Provider chip shown, timer starts |
agent_start |
{ agent } |
Sidebar dot pulses, column cursor blinks |
transcript_chunk |
{ agent, text } |
Text appends character by character |
agent_verdict |
{ agent, position, justification } |
Verdict badge appears in column footer |
bias_flag |
{ agent_name, bias_type, quote, severity, explanation, corrective_reframe } |
Red flag card slides in mid-transcript |
auditor_summary |
{ total_flags, confidence_score, most_biased_agent, ... } |
Confidence ring draws, report tab unlocks |
final_verdict |
{ raw_verdict, debiased_verdict, final_recommendation, ... } |
Verdict flip rendered, verdict tab unlocks |
agent_done |
{ agent } |
Sidebar dot turns green |
done |
{ session_id } |
All agents confirmed complete |
| Technology | Version | Purpose |
|---|---|---|
| React | 19 | UI framework |
| TanStack Start | latest | Meta-framework (Vite + Nitro) |
| TanStack Router | latest | File-based routing |
| Tailwind CSS | v4 | Styling with OKLCH design tokens |
| shadcn/ui | New York | Radix-based UI primitives |
| Recharts | latest | Bias breakdown charts |
| Lucide React | latest | Icons |
| Bun | latest | Package manager and runtime |
| Technology | Version | Purpose |
|---|---|---|
| Python | 3.9+ | Runtime |
| FastAPI | 0.115+ | REST API + SSE streaming |
| Uvicorn | 0.34+ | ASGI server |
| Pydantic | v2 | Schema validation |
| Google ADK | latest | Agent orchestration |
| google-generativeai | latest | Gemini 2.5 Flash access |
| PyMuPDF (fitz) | 1.24+ | PDF text extraction |
| sse-starlette | latest | Server-Sent Events |
| OpenAI Python SDK | 1.0+ | Grok and Groq fallback |
| python-dotenv | latest | Environment variable loading |
Fairlens/
├── docs/
│ ├── system_architecture.jpg # Architecture diagram
│ ├── backend-architecture.md # Detailed backend documentation
│ └── ui-architecture.md # UI design system documentation
│
├── fairlens_backend/ # Python FastAPI backend
│ ├── main.py # FastAPI entry point, routes, CORS, session management
│ ├── pipeline.py # Google ADK pipeline orchestrator
│ ├── grok_pipeline.py # Grok/xAI fallback pipeline
│ ├── groq_pipeline.py # Groq fallback pipeline
│ ├── agents/
│ │ ├── technical.py # TechnicalInterviewer — LlmAgent + google_search
│ │ ├── culture.py # CultureFitAssessor — LlmAgent
│ │ ├── seniority.py # SeniorityAssessor — LlmAgent
│ │ ├── auditor.py # BiasAuditor — LlmAgent + FunctionTool + BuiltInPlanner
│ │ └── synthesizer.py # VerdictSynthesizer — LlmAgent + output_schema
│ ├── models/
│ │ ├── schemas.py # Pydantic models (RunRequest, FinalVerdict, BiasFlag...)
│ │ └── provider.py # Provider resolution (Gemini → Grok → Groq)
│ ├── prompts/
│ │ └── system_prompts.py # System prompts for all five agents
│ ├── tools/
│ │ └── flag_bias.py # flag_bias() FunctionTool + in-memory session store
│ └── requirements.txt
│
├── src/ # React 19 frontend
│ ├── routes/
│ │ └── index.tsx # Root route, stage machine (input → panel → report)
│ ├── components/
│ │ ├── InputScreen.tsx # Candidate profile input + PDF upload
│ │ ├── LivePanel.tsx # Three-column streaming transcript view
│ │ ├── ReportScreen.tsx # Auditor report + final verdict
│ │ ├── Sidebar.tsx # Pipeline status sidebar
│ │ └── primitives.tsx # Chip, InlineFlag, VerdictBadge, ConfidenceRing
│ ├── lib/
│ │ ├── use-backend-runtime.ts # SSE consumer hook (real backend)
│ │ └── use-scenario-runtime.ts # Mock streaming fallback
│ └── styles.css # OKLCH design tokens and animations
│
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
- Python 3.9+ (or Docker / Docker Compose)
- Bun (or Node.js 18+)
- Google AI Studio API key — aistudio.google.com
- Optional: xAI API key for Grok fallback
- Optional: Groq API key for Groq fallback
This builds and orchestrates both the Python FastAPI backend and the Bun React frontend with optimal container boundaries.
-
Clone the repository:
git clone https://github.com/your-username/fairlens.git cd fairlens -
Configure environment variables: Create
fairlens_backend/.env(using.env.exampleas a template):cp .env.example fairlens_backend/.env
Open
fairlens_backend/.envand enter your API keys. -
Launch the services:
docker compose up --build -d
This will spin up the backend (port 8000) with automatic health-checking and the frontend (port 5173).
-
Verify Health:
curl http://localhost:8000/health # Returns: { "status": "ok" }
-
Clone the repository:
git clone https://github.com/your-username/fairlens.git cd fairlens -
Backend environment: Create
fairlens_backend/.env:GOOGLE_API_KEY=your_google_api_key_here GOOGLE_GENAI_USE_VERTEXAI=FALSE # Optional fallbacks XAI_API_KEY=your_xai_api_key_here GROQ_API_KEY=your_groq_api_key_here
-
Backend setup:
cd fairlens_backend # Create and activate virtual environment python -m venv ../.venv # Windows ..\.venv\Scripts\Activate.ps1 # macOS / Linux source ../.venv/bin/activate # Install dependencies pip install -r requirements.txt # Verify installation python -c "import google.adk; print('ADK ready')" python -c "import fitz; print('PyMuPDF ready')" # Start the backend server uvicorn main:app --reload --port 8000
Backend runs at
http://localhost:8000 -
Frontend setup: Open a new terminal in the project root:
# Install dependencies bun install # Start the development server bun run dev
Frontend runs at
http://localhost:5173
The application includes built-in security features to protect API integrity and prevent resource exhaustion:
- UUID v4 format validation on
session_id: AnyPOST /runwith a non-UUID v4 format is rejected (400 Bad Request). - Candidate profile size limit: Candidate profiles exceeding 50KB are rejected (
413 Payload Too Large). - Concurrent session limit: Up to 10 concurrent pipeline runs are allowed. Excess sessions receive
503 Service Unavailable. - CORS restrictions: Access is restricted strictly to local dev origins in development.
- Data persistence: Ephemeral, in-memory state storage. No candidate data or transcripts are stored in databases.
Health check.
{ "status": "ok" }Upload a PDF resume. Returns a structured candidate JSON profile.
Request: multipart/form-data with file: UploadFile
Response:
{
"candidate": {
"name": "Alex Kim",
"target_role": "",
"target_level": "L3 / L4 / L5 / L6",
"years_experience": 6,
"education": "Coding bootcamp",
"current_company": "Series A healthcare startup",
"current_title": "Software Engineer",
"past_companies": ["Agency X", "Freelance"],
"key_projects": ["..."],
"interview_notes": "",
"interviewer_raw_notes": []
},
"raw_text_preview": "First 500 characters of extracted text..."
}Errors:
400— File is not a PDF422— No text could be extracted (scanned image PDF)502— All LLM providers failed
Start the multi-agent pipeline. Returns an SSE stream.
Request:
{
"session_id": "uuid-string",
"candidate": { "name": "...", "key_projects": ["..."], "...": "..." },
"target_level": "L3 | L4 | L5 | L6",
"panel_mode": "Balanced | Technical-heavy | Culture-heavy"
}Response: text/event-stream
See SSE Event Stream for full event catalogue.
Errors:
409— Session already running
Retrieve the final verdict for a completed session.
Response: FinalVerdict JSON object
Errors:
425— Pipeline still running404— Session not found
The confidence score (0–100) reflects how bias-contaminated the panel's reasoning was.
deduction = (HIGH flags × 15) + (MEDIUM flags × 7) + (LOW flags × 3)
If verdict did NOT change after debiasing:
deduction = deduction × 0.5 ← penalty halved, verdict held up
confidence_score = max(20, 100 - deduction)
A score of 100 means zero bias detected. A score of 20 means the majority of panel reasoning was flagged. When the raw and debiased verdicts differ, that difference is the evidence that bias was affecting the decision.
resolve_provider()
│
├── GOOGLE_API_KEY valid? ──► Gemini 2.5 Flash (Google ADK)
│ Full ParallelAgent pipeline
│ Google Search grounding
│
├── ADK exception at runtime?
│ │
│ ├── XAI_API_KEY valid? ──► Grok grok-2-1212
│ │ Sequential fallback pipeline
│ │
│ └── GROQ_API_KEY valid? ──► Groq llama-3.3-70b-versatile
│ Sequential fallback pipeline
│
└── None available ──► error SSE event
FairLens is a reflection and discussion tool. Bias flags are surfaced to prompt review and reconsideration — they are not definitive verdicts. Final hiring decisions remain with humans. FairLens does not store candidate data between sessions. All session state is held in memory and cleared on server restart.
5 Days of Gen AI — Google × Kaggle Capstone Project

