# Project export: HirED This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: UC Berkeley AI Hackathon 2026 - Tagline: AI Career Coach for Resume Gaps - Devpost: https://devpost.com/software/hired-f17pvo - GitHub: https://github.com/mango-ship-it/HirED - Demo: https://agentverse.ai/agents/details/agent1qw5ytjncz2ccn6j6utk7t7z0fnxwm9hxwp6aw0g5pw2nj6trwfhwjp9xugz/profile - Video: https://www.youtube.com/embed/LFXW2fy6uvM?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 4 GitHub contributor(s) — Claude Sonnet 4.6 (2 commits), inthree3 (2 commits), 1kaden (2 commits), Bobby Reyes (1 commits) ## Devpost submission (written by the team) ### Inspiration There are already a lot of resume enhancer tools out there that focus on making your resume more ATS-friendly, but that's just not enough anymore. You need to actually see your future by looking at your competitors and fellow applicants, and figure out how to fix your weaknesses while sharpening your strengths to stand out. We kept running into the same limitations with existing job prep tools, so we thought: what if we tried building this with Claude instead? When we consulted LLMs ourselves for job prep, the advice always stayed surface level. It never went deep enough into real job descriptions, actual activities, or anything concrete we could act on. ### What it does We built a multi-agent system that pulls from real data sources like job postings, potential mentors, certificates, and events. ### How we built it We built an agent environment and used it as the backend for a career coaching application. ### Challenges we ran into Ddoski's world Fetch.ai UI/UX Deepgram Redis Pika TokenRouter Tech ### Accomplishments we're proud of Our product can pull in people, events, posts, and pretty much all the information relevant to a job application. We also designed our own reliable multi-agent system from scratch. ### What we learned Automating browser work without vision AI turned out to be really hard. We also learned that a result looking fine on the surface doesn't mean it's actually reliable. We need some way to verify and certify that the output can be trusted. ### What's next for We want to build a verification layer that checks how reliable our agents' outputs actually are, instead of just trusting whatever looks polished on the surface. We also want to move past heuristics and rule-based scraping, and bring in vision AI so agents can navigate and read web pages the way a human would, making data collection much more robust. On top of that, we're planning to expand our data sources beyond job postings and events to include real conversations with mentors and alumni, so the advice feels less like a chatbot and more like an actual career coach who knows the industry. Finally, we want to turn this into a continuous feedback loop, where the system tracks your applications over time and adjusts its recommendations based on what's actually working for you. ## README (from the GitHub repository) # HirED ## Detected evidence (automated analysis) Indexed codebase: 4 recognized source files, 32 KB. - FastAPI (technology) — claimed on Devpost, not found in the code - Python (language) — claimed on Devpost, not found in the code - React (technology) — claimed on Devpost, not found in the code - AI coding agent: Claude Code — evidence: config files committed to the repository; commit authorship or trailers ## Codebase structure (from repository index) ### Files (4 of 4) ``` .claude/skills/plan-feature/SKILL.md API_CONTRACT.md MASTER.md README.md ``` ### Dependencies No dependency index available. ### Recent commits (newest first) - docs: integrate scoring section into report/results phase (§5.3) - docs: add API_CONTRACT.md as locked frontend/backend source of truth - docs: add details for scoring phase - docs: update sponsor stack — Fetch.ai uAgents, Sai (jobs/LinkedIn), Deepgram voice, narrated slides - docs: add MASTER.md project plan and plan-feature planning skill (#1) - Initial commit ## Key source files (fetched from GitHub, selected and truncated for size) ### API_CONTRACT.md ```markdown # API_CONTRACT.md Locked together by frontend + backend — update this file the moment anything changes. This is the single source of truth, not FRONTEND.md's rough sketch. --- ## 1. `POST /score` **DECIDED:** Frontend sends the raw file (multipart `FormData`); backend parses it (`pdfplumber`/`python-docx`) and feeds extracted data to the agents. Frontend does no PDF parsing. **Request:** (multipart form data, not raw JSON — file upload) ``` user_id: "string — UUID generated client-side on first visit" resume_file: target: { "type": "role" | "school" | "job_posting_text", "value": "string — e.g. 'Software Engineering Internship' or pasted job posting text" } ``` **Response (200):** ```json { "score": 72, "categories": { "skills_match": { "score": 65, "weight": 0.35 }, "quantified_achievements": { "score": 40, "weight": 0.25 }, "experience": { "score": 80, "weight": 0.20 }, "education": { "score": 90, "weight": 0.10 }, "clarity": { "score": 70, "weight": 0.10 } }, "lessons": [ { "category": "quantified_achievements", "principle": "Recruiters scan for numbers — unquantified bullets get skipped.", "example": "Before: 'Helped improve process' → After: 'Reduced processing time 30%'", "action": "Add a number to bullet 2 of your projects section." } ], "status": { "scoring": "complete", "benchmark": "complete" | "pending" | "failed", "resources": "complete" | "pending" | "failed" } } ``` **Why `status` exists:** scoring now pulls data from multiple agents (Fetch.ai + scoring agent) running in parallel. Per decision on #6, a slow/failed agent does NOT fail the whole request — `/score` still returns what it has. Frontend reads `status` and conditionally renders the benchmark/resources sections instead of assuming they're always present. If `"pending"`, frontend can poll or just show a "still calculating" state for that section; if `"failed"`, hide that section gracefully rather than showing broken/empty data. --- ## 2. `POST /benchmark` **Request:** ```json { "user_id": "string — same UUID sent with /score", "score": 72, "target": { "type": "role", "value": "Software Engineering Internship" } } ``` **Response (200):** ```json { "percentile": 65, "sample_size": 87, "message": "Top 35% of users targeting this role. Users who moved into the top 20% most often fixed quantified_achievements first." } ``` --- ## 3. `POST /resources` **Request:** ```json { "user_id": "string — same UUID sent with /score", "gap_category": "quantified_achievements", "context": { "first_gen": true, "target_type": "tech_internship" } } ``` **Response (200):** ```json { "resources": [ { "name": "string", "url": "string", "description": "string" } ] } ``` --- ## Error Shape (all endpoints, same format) ```json { "error": "string — human-readable message", "code": "INV [truncated — 1647 more characters] ``` ### MASTER.md ```markdown # HirED — Master Plan > Single source of truth for the hackathon build. Last updated **2026-06-20**. > Legend: **[ASSUMPTION]** = my working default pending your confirmation · **[OPEN]** = needs a call (see §11). **Tagline:** _Get your score for your resume and see what your next step is._ The score + roadmap result module is internally branded **NextStep** — this is the "money shot" screen users see after analysis. **Brand voice:** reliable and kind. Every surface — loading copy, report language, error states — should read like a coach who's on the user's side, not a cold grading system. Avoid clinical/judgmental phrasing ("you failed to…") in favor of constructive framing ("here's what's missing, and how to close it"). --- ## 0. Decisions locked (2026-06-20) - **Profile input is chat-first:** chat / elevator-pitch → resume paste → PDF/DOCX → LinkedIn URL. - **Target input:** company + role text first (job-description URL = stretch). - **Agents via Fetch.ai (uAgents):** resource lookup and peer-benchmark each run as a standalone **uAgent** (own process, auto-registered on Fetch.ai's Almanac); FastAPI bridges to them with `uagents.query()`. See §7. - **Jobs/LinkedIn via Sai:** **Sai** (Simular's computer-using GUI agent) connects users to live job postings, LinkedIn, and applications — it drives real sites/apps in a remote desktop. See §7. - **Voice via Deepgram:** speech-to-text for a spoken elevator pitch / voice mock-interviews, plus **TTS narration** for the slide-based lessons. See §7. - **Lessons = narrated slides, not Pika video:** lessons + roadmap ship as custom slide cards with Deepgram TTS narration (Pika video lessons dropped). See §9. - **API contract locked in `FRONTEND.md`:** `/score`, `/benchmark`, `/resources` (+ voice) — backend implements exactly those shapes (§7). - **Python backend, 3 processes:** FastAPI + the two uAgents run as separate Python processes; all sponsor integrations (Claude, Fetch.ai, Deepgram, Redis, Sai) live server-side. - **Planning Skill:** built a reusable `plan-feature` Claude Code skill under `.claude/skills/` (see §12). - **Benchmark mechanism locked:** the peer-benchmark percentile is computed via **scraped JDs → synthetic competitor resumes (with generated avatars) → pairwise 2AFC comparisons judged by Claude → ELO aggregation → percentile.** This is the concrete algorithm behind the `benchmark_agent` referenced in §0/§6/§7. --- ## 1. One-liner HirED is an AI **career tutor** for first-gen, low-income, and career-transitioning job seekers. Describe yourself (or upload a resume), pick a target job or school, and get: a compatibility score, the **1–3 specific gaps that matter most**, **free** resources to close them, a step-by-step roadmap, and a tailored resume — then **re-score** to watch your number climb. ## 2. Pitch / why it matters - **The hidden curriculum.** Job hunting has unwritten rules — how to qu [truncated — 22140 more characters] ``` [1 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]