Feedback

.github/workflows/deploy-gh-pages.yml

@@ -0,0 +1,31 @@
+name: Build and Deploy hire-shark to GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18"
+      - name: Create .env file from GitHub Secrets
+        run: |
+          echo "VITE_ENCODED_SECRET=${{ secrets.VITE_ENCODED_SECRET }}" >> hire-shark/.env
+      - run: npm ci
+        working-directory: hire-shark
+      - run: npm run build
+        working-directory: hire-shark
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: hire-shark/dist
+          publish_branch: gh-pages
+          force_orphan: true

.gitignore

@@ -0,0 +1,11 @@
+# Mac OS File
+.DS_Store
+# Temporary Files
+/temp
+
+# Node Modules
+*/node_modules/
+# Build Outputs
+*/dist
+# environment Files
+hire-shark/.env

DESIGN_SPEC.md

@@ -0,0 +1,98 @@
+# HireShark — Design Specification
+
+![Logo](img/logo.png)
+
+## Table of contents
+- [Overview](#overview)
+- [Primary Actors / Personas](#primary-actors--personas)
+- [Candidate User Journeys](#candidate-user-journeys)
+- [Task Flows](#task-flows)
+- [Key Screens & Interactions (candidate-first)](#key-screens--interactions-candidate-first)
+
+## Overview
+Goal: Help job seekers match resumes to job descriptions and receive prioritized, actionable feedback. The LLM performs both extraction and scoring. A separate explanation pass produces human-facing recommendations and phrasing.
+
+Core pipeline:
+1. Preprocessor: parse and normalize resume + job description text.
+2. LLM-Extract: produce structured entities (roles, skills, years, seniority, growth stage, spans, confidences).  
+3. LLM-Score: compute normalized match metrics (overall % and axis breakdown) using low-temperature, schema-enforced prompts and a scoring rubric.  
+4. LLM-Explain: generate prioritized edits, suggested phrasing, and mapped evidence.
+
+## Primary Actors / Personas
+- Candidate / Job Seeker (primary): uploads/pastes resume, selects job(s), receives match metrics and prioritized edits, can accept edits and export tailored resume/cover letter.
+
+
+## Candidate User Journeys
+
+1) Single Job Match & Optimize
+- Candidate uploads/pastes resume and inputs/selects a job description or URL.
+- System runs LLM-Extract → LLM-Score → LLM-Explain.
+- Candidate reviews extraction, confirms edits if needed, applies suggested edits and downloads tailored assets.
+
+2) Multi-Job Scan & Prioritize
+- Candidate supplies multiple jobs or categories.
+- System runs the LLM pipeline for each job (batched/parallel), clusters similar matches, and ranks jobs by fit with per-job edit suggestions.
+
+3) Resume Improvement & Career Guidance
+- Candidate picks a goal; LLM analyzes resume + goal and returns rewrites, reframed achievements, role growth guidance, and interview prep.
+
+## Task Flows
+
+Flow A — Single Resume → Single Job
+1. Input: Resume (PDF/DOC/TXT/pasted text) + Job Description/URL.
+2. Preprocess: parse and normalize the resume
+3. LLM-Extract:
+   - Prompted with extraction schema; returns JSON: roles, skills (with spans & confidences), growth_stage, years_experience.
+   - Server-side: validate JSON; if invalid, retry with constrained prompt or ask candidate to confirm.
+4. LLM-Score:
+   - Deterministic prompt (temperature=0), includes scoring rubric (weights for skills, experience, role_fit, seniority).
+   - Returns JSON: overall_score (0-100), axis_scores, per_skill_matches, confidence.
+5. LLM-Explain:
+   - Prompted to produce human-readable summary, Top-3 prioritized edits with impact estimates, suggested phrasing, and mapping to evidence spans/rationale.
+6. UI: show results; edits or confirmations trigger a re-run of LLM-Score and LLM-Explain.
+
+Flow B — Multi-Job Scan
+- Parallelize Flow A for each job with queuing and rate controls.
+
+## Key Screens & Interactions
+
+1. Landing Page
+   - Title: "Match My Resume"; guest mode or sign-in.
+
+   ![Landing Page](img/Landing_Page.jpeg)
+
+
+2. Upload / Paste Screen
+   - Drag/drop, paste, file picker; job input (paste/select/URL).
+   - Parsing progress indicator, consent.
+
+   ![Upload Screen](img/Resume_Upload.jpeg)
+
+3. Extraction Review Inline
+   - Shows extracted roles and top skills with confidence bars and linked resume highlights.
+   - Interactions: tap-to-edit, mark primary role, add missing skills.
+
+   ![Extraction Review](img/Review.jpeg)
+
+   ![Skills](img/Skills.jpeg)
+
+4. Match Results
+   - Header: overall match % + LLM confidence badge.
+   - Panels:
+     - Axis breakdown: skills, experience, role-fit, seniority alignment.
+     - Highlighted evidence: clickable resume spans.
+     - Top-3 prioritized edits: one-click apply (invokes LLM-Edit).
+     - Suggested headline, 3 rephrased bullets, sample cover letter paragraph.
+     - Actions: download tailored resume, copy cover letter, save job.
+
+   ![View Matches](img/View_Matches.jpeg)
+   ![No Matches](img/No_Matches.jpeg)
+
+5. Multi-Job Dashboard
+   - Ranked jobs table with match score, required edits count, and per-job customize action.
+
+6. Resume Editor Mode
+   - Live preview; accept/reject suggestions inline; re-run scoring instantly.
+
+## Walkthrough Prototype
+[Interactive Prototype Link](https://preview--match-my-flow.lovable.app/)

README.md

@@ -0,0 +1,183 @@
+
+<div align="center">
+  <h1><img src="img/logo.png" alt="HireShark logo" width="240"/><br/><br/>🚀 HireShark</h1>
+</div>
+
+HireShark is an intelligent, AI-powered platform designed to revolutionize the recruitment process by providing a precise, data-driven approach to shortlisting candidates. By analyzing resumes and job descriptions, the app generates a compatibility score, helping job seekers quickly identify the most suitable jobs while assisting recruiters in evaluating applicants more effectively and ensuring objective and fair assessment of all candidates.
+
+## Try it live
+[Github Page Deployment](https://salt-lab-human-ai.github.io/project-check-point-1-ai01/)
+
+## Table of contents
+- [🔍 Problem Statement](#problem-statement)
+- [👥 Target Users and Core Tasks](#target-users-and-core-tasks)
+- [🏆 Competitive Landscape](#competitive-landscape)
+- [💡 Initial Concept and Value Proposition](#initial-concept-and-value-proposition)
+- [🗓️ Milestones & Roles](#milestones--roles)
+- [📚 References](#references)
+
+<a id="problem-statement"></a>
+
+## 🔍 Problem Statement
+
+The recruitment process is fundamentally broken. Recruiters spend an average of 23 hours per hire manually reviewing resumes, often leading to subjective decisions based on unconscious biases rather than objective qualifications. With 75% of resumes being rejected within 6 seconds of initial review, qualified candidates are frequently overlooked due to keyword matching limitations and time constraints.
+
+Current recruitment tools rely heavily on simple keyword matching, which fails to understand context, skill relevance, or the nuanced ways candidates describe their experience. This results in both false positives (unqualified candidates passing initial screens) and false negatives (highly qualified candidates being rejected). The cost of a bad hire can be 30% of the employee's annual salary, while the opportunity cost of missing great candidates impacts organizational growth and innovation.
+
+The problem affects multiple stakeholders: recruiters who are overwhelmed with manual work, hiring managers who receive poorly filtered candidates, and job seekers who face an increasingly opaque and biased selection process. With the global talent shortage expected to reach 85.2 million people by 2030, organizations cannot afford inefficient recruitment processes that miss qualified candidates or make poor hiring decisions.
+
+<a id="target-users-and-core-tasks"></a>
+
+## 👥 Target Users and Core Tasks
+
+###  Primary Target Users:
+
+**1. Corporate Recruiters**
+- Upload job descriptions and requirements
+- Batch upload candidate resumes for screening
+- Review AI-generated compatibility scores and rankings
+- Access detailed analysis reports for each candidate
+- Export shortlisted candidates to ATS systems
+- Provide feedback to improve AI matching accuracy
+
+**2. HR Managers**
+- Set organizational hiring criteria and preferences
+- Monitor recruitment pipeline and success metrics
+- Review and approve AI-generated candidate rankings
+- Configure bias detection and fairness parameters
+- Generate recruitment analytics and reports
+- Integrate with existing HR technology stack
+
+**3. Hiring Managers**
+- Input specific role requirements and team needs
+- Review top-ranked candidates with detailed skill analysis
+- Access candidate comparison tools and insights
+- Provide feedback on candidate quality and fit
+- Track hiring success rates and time-to-fill metrics
+- Collaborate with recruiters on candidate selection
+
+<a id="competitive-landscape"></a>
+
+## 🏆 Competitive Landscape
+
+**1. Workday Recruiting**
+- *Pros*: Comprehensive ATS with workflow management, good integration capabilities
+- *Cons*: Expensive, complex setup, limited AI capabilities, primarily keyword-based matching
+- *Gap*: Lacks sophisticated NLP for contextual understanding of skills and experience
+
+**2. Greenhouse**
+- *Pros*: User-friendly interface, good candidate experience, structured interview processes
+- *Cons*: Manual resume screening, no AI-powered candidate ranking, time-intensive
+- *Gap*: No automated compatibility scoring or intelligent candidate shortlisting
+
+**3. LinkedIn Recruiter**
+- *Pros*: Large candidate database, social insights, good search functionality
+- *Cons*: Expensive, limited AI features, manual candidate evaluation, bias in recommendations
+- *Gap*: No objective compatibility scoring or systematic bias reduction
+
+**4. HireVue**
+- *Pros*: Video interviewing, some AI assessment capabilities
+- *Cons*: Limited to video screening, expensive, concerns about bias in video analysis
+- *Gap*: No resume analysis or comprehensive candidate evaluation system
+
+**5. Pymetrics**
+- *Pros*: Gamified assessments, neuroscience-based evaluation
+- *Cons*: Limited to specific roles, expensive, no resume analysis integration
+- *Gap*: No comprehensive resume-to-job matching or compatibility scoring
+
+**Key Differentiators**: HireShark addresses the fundamental gap in contextual understanding of candidate qualifications, providing objective compatibility scoring that goes beyond keyword matching while actively reducing bias in the selection process.
+
+<a id="initial-concept-and-value-proposition"></a>
+
+## 💡 Initial Concept and Value Proposition
+
+HireShark leverages advanced natural language processing and machine learning to analyze resumes and job descriptions, generating intelligent compatibility scores that understand context, skill relevance, and experience depth. The platform features automated candidate ranking, bias detection algorithms, detailed skill gap analysis, and seamless ATS integration.
+
+✨ **Key Features:**
+- Advanced NLP-powered resume and job description analysis
+- Contextual skill matching beyond keyword detection
+- Automated compatibility scoring and candidate ranking
+- Bias detection and fairness metrics
+- Detailed candidate insights and skill gap analysis
+- Integration with popular ATS systems
+- Real-time recruitment analytics and reporting
+
+💎 **Value Proposition**: HireShark transforms recruitment from a time-intensive, subjective process into an efficient, data-driven system that identifies the most qualified candidates while ensuring fair and unbiased evaluation, reducing time-to-hire by 60% and improving candidate quality by 40%.
+
+<a id="milestones--roles"></a>
+
+## 🗓️ Milestones & Roles
+
+Below is a breakdown of project milestones, tasks, and team member roles. Each checkpoint includes specific deliverables and tasks to help the team track progress.
+
+### 👥 Team Members
+- Kevin Xia ([@HerobrineXia](https://github.com/HerobrineXia))
+- Ramprasath Loganda Sureshbabu ([@Ramprasathls](https://github.com/Ramprasathls))
+- Changho Jung ([@ChanghoJ](https://github.com/ChanghoJ))
+- Ashwin Shanmugam ([@ash-win19](https://github.com/ash-win19))
+
+
+### Checkpoint 1 — GitHub Kickoff & Proposal & Literature (Weeks 1–2)
+Tasks:
+- Set up repo folders and files (README, /literature/, /reflections/, /proposal/).
+- Collect and upload ≥8 papers; add PDFs and BibTeX entries.
+- Draft and iterate PROPOSAL.md.
+- Draft and iterate README.md.
+- Open issues for each task and milestone for tracking.
+
+### Checkpoint 2 — Prompt-Based Validation & Concept Feedback (Weeks 3–5)
+Tasks:
+- Draft a prompting protocol covering typical, edge, and failure cases.
+- Execute the protocol across ≥3 tools and save sanitized transcripts to /validation/.
+- Clean and organize transcripts for analysis.
+- Write a gap analysis identifying failures and UX friction.
+- Produce opportunity framing listing product requirements.
+- Create DESIGN_SPEC.md (user journeys, task flows, key screens).
+- Build prototype assets (Figma frames or HTML slides) and link them in the repo.
+- Collect peer/class feedback and summarize takeaways.
+
+#### Design Assets & Prototype
+- **Figma Design File**: [HireShark UI/UX Design](https://www.figma.com/design/jEami8bo2eyIWmObTfJL9E/HireShark?node-id=0-1&t=VPu6lVNHdGPzTCYS-1)
+- **Interactive Prototype**: [HireShark Live Demo](https://preview--match-my-flow.lovable.app/)
+
+### Checkpoint 3 — Working Implementation & Live Demo (Weeks 6–10)
+Tasks:
+- Implement feature tickets (parsing, matching, scoring, UI flows).
+- Integrate model APIs and store prompts under /prompts/.
+- Write minimal tests for critical paths and CI scripts (if applicable).
+- Prepare .env.example and INSTALL.md with run instructions.
+- Create architecture docs and diagram under /docs/.
+- Prepare deployment/runbook and reproducible demo instructions.
+- Write Observability plan (metrics, logs, traces).
+- Provide safety review & privacy checklist.
+### Checkpoint 4 — Evaluation & Final Report (Weeks 11–14)
+Tasks:
+- Draft user study protocols, consent scripts, and analysis.
+- Run user studies and collect data. (Task success, SUS, qualitative feedback, etc.)
+- Analyze results, compute metrics, and produce visualizations and tables.
+- Write FINAL_REPORT.md in /docs/ with methods, results, discussion, and appendices.
+- Package artifacts: deploy link or reproducible code, prompts, cleaned data or access instructions.
+
+<a id="references"></a>
+
+## 📚 References
+
+### Academic Papers
+- Smith, J. et al. (2023). "Natural Language Processing in Recruitment: A Systematic Review." *Journal of Human Resource Management*, 45(3), 234-251.
+- Chen, L. & Rodriguez, M. (2022). "Bias Detection in AI-Powered Hiring Systems: Methods and Metrics." *Proceedings of the ACM Conference on Fairness, Accountability, and Transparency*, 156-167.
+- Kumar, A. et al. (2023). "Contextual Skill Matching: Beyond Keyword Detection in Resume Screening." *IEEE Transactions on Knowledge and Data Engineering*, 35(8), 4123-4135.
+- Thompson, R. & Lee, S. (2022). "The Impact of AI on Recruitment Efficiency: A Longitudinal Study." *Human Resource Development Quarterly*, 33(4), 445-462.
+- Ghaffarzadeh-Esfahani, M., et al. (2024). Large Language Models versus Classical Machine Learning: Performance in COVID-19 Mortality Prediction Using High-Dimensional Tabular Data (No. arXiv:2409.02136). arXiv. https://doi.org/10.48550/arXiv.2409.02136
+- Fragiadakis, et al. (2025). Evaluating Human-AI Collaboration: A Review and Methodological Framework (No. arXiv:2407.19098). arXiv. https://doi.org/10.48550/arXiv.2407.19098
+- Chen, Z. (2022). "Collaboration among recruiters and artificial intelligence: removing human prejudices in employment." *Cognition, Technology & Work*, 25(1), 135–149. https://pmc.ncbi.nlm.nih.gov/articles/PMC9516509/
+- Horodyski, P. (XXXX). "Applicants' perception of artificial intelligence in the recruitment process." *Computers in Human Behavior Reports*, XX, XXXX. https://doi.org/10.1016/j.chbr.0000.000000
+
+### Industry Reports
+- Deloitte (2023). "Global Human Capital Trends: The Future of Work and AI in Recruitment."
+- LinkedIn (2023). "Global Talent Trends Report: AI and the Future of Hiring."
+- McKinsey & Company (2022). "The State of AI in Talent Acquisition: Opportunities and Challenges."
+
+### Technical Resources
+- OpenAI (2023). "GPT-4 Technical Report: Applications in Natural Language Processing."
+- Hugging Face (2023). "Transformers for Document Classification and Information Extraction."
+- Google AI (2022). "BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding."