Documentation · v1.1

NextSteps Documentation

Everything you need to set up, configure, and use NextSteps — the AI career automation agent that handles your entire job application pipeline.

Quick Start

Get NextSteps running locally in 3 steps.

Clone & Install

Requires Python 3.12+ and uv package manager.

# Clone the repository git clone https://github.com/YOUR_USERNAME/NextSteps.git cd NextSteps # Install dependencies uv sync

Set Environment Variables

Create a .env file in the project root with your API keys.

# .env GROQ_API_KEY=your_groq_api_key_here TAVILY_API_KEY=your_tavily_api_key_here

Get your keys: Groq Console · Tavily Dashboard — both have generous free tiers.

Run the Server

Start the FastAPI backend and open the frontend.

# Start the API server python main.py # Or directly with uvicorn uvicorn api.main:app --reload # Open frontend/dashboard.html in your browser # API docs available at http://localhost:8000/docs

Supported URLs

NextSteps uses Tavily Extract to fetch job descriptions from URLs. Some sites block automated access.

Works well ✅

Lever / lever.co Greenhouse / greenhouse.io Workable / workable.com Company career pages Ashby / ashbyhq.com BambooHR SmartRecruiters

Blocked ❌

LinkedIn Indeed Naukri Glassdoor Monster Shine

For blocked sites: Use the "Paste JD manually" option on the dashboard. Copy the job description text from the website and paste it directly — no URL needed.

CV Format Guide

NextSteps uses PyMuPDF to extract text from your PDF. The format of your resume affects extraction quality.

✅ Good Format

Single-column layout · Plain text (not images) · Standard fonts · Clear section headers · Bullet points for experience

❌ Avoid

Multi-column layouts · Table-based designs · Heavy graphics · Text embedded as images · Fancy templates with sidebars

API Reference

All endpoints are served from http://localhost:8000. Interactive API docs at /docs.

Method	Endpoint	Description
GET	/health	Service health check
POST	/parse	Upload CV (PDF) + job URL → profile + JD + company context
POST	/match	Profile + JD → skill gap report
POST	/apply	Gap report → tailored bullets + cover letter + ATS score
POST	/apply/stream	Streaming cover letter generation (SSE)
POST	/interview/start	JD + gap report → interview questions
POST	/interview/answer	Score one answer (RAG-grounded)
POST	/interview/summary	All scored answers → session report

Parse endpoint details

# POST /parse — multipart/form-data cv: PDF file (required, max 10MB) job_url: string (required — use placeholder if pasting JD) raw_jd_text: string (optional — raw JD text, skips URL scraping) company_name: string (optional — fallback company name)

Architecture

NextSteps is a multi-agent pipeline. Each phase calls specialized agent functions through a FastAPI REST layer.

┌─────────────────────────────────────────────────────────────┐ │ Frontend (HTML/JS) │ │ index.html · dashboard.html · docs.html │ └─────────────────────────┬───────────────────────────────────┘ │ REST API ┌─────────────────────────▼───────────────────────────────────┐ │ FastAPI Backend │ │ /parse /match /apply /apply/stream /interview/* │ └─────┬────────┬────────┬────────┬────────┬───────────────────┘ │ │ │ │ │ ┌─────▼──┐ ┌───▼───┐ ┌──▼───┐ ┌──▼────┐ ┌▼─────────┐ │CV Parse│ │JD │ │Skill │ │Resume │ │Interviewer│ │ Agent │ │Scraper│ │Match │ │Tailor │ │ Agent │ └────────┘ └───────┘ └──────┘ └───────┘ └──────────┘ │ │ │ │ │ ┌────▼──┐ ┌──▼──────────┐ ┌─────▼────┐ │ │Tavily │ │ ChromaDB │ │ RAG │ │ │Search │ │(skills+chunks) │ Retrieval│ │ └───────┘ └─────────────┘ └──────────┘ │ ┌───▼─────┐ ┌──────────────┐ │pymupdf4 │ │SentenceTransf│ │ llm │ │ ormers │ └─────────┘ └──────────────┘

Tech Stack

Component	Technology
LLM Inference	Groq — gpt-oss-120b, gpt-oss-20b
Web Intelligence	Tavily — JD extraction + company research
Vector Store	ChromaDB — persistent, cosine similarity
Embeddings	SentenceTransformers — all-MiniLM-L6-v2
Backend	FastAPI + Uvicorn
Validation	Pydantic v2 (extra='forbid')
PDF Parsing	PyMuPDF / pymupdf4llm
Frontend	Vanilla HTML/CSS/JS

5-Phase Workflow

Phase 1 — Parse & Extract

Upload your CV PDF and paste a job URL (or raw text). Tavily fetches the full JD. PyMuPDF reads your CV. Groq structures both into Pydantic models. Company context is enriched via a Tavily search.

Phase 2 — Skill Match

Your skills are embedded into ChromaDB with SentenceTransformers. Cosine similarity is computed for each JD requirement. Skills are classified as match weak gap. An overall match percentage is generated.

Phase 3 — Application Package

Groq rewrites your resume bullets to mirror JD keywords. A company-aware cover letter is generated (with streaming). The ATS compatibility score checks keyword matches and suggests improvements.

Phase 4 — Mock Interview

10 role-specific questions are generated from your gap report. Each answer is scored on 3 axes (relevance, depth, clarity), grounded in your CV via RAG retrieval. Exit anytime for a partial scorecard.

Phase 5 — AI Tutor coming soon

Socratic skill tutor that teaches each gap skill through interactive sessions. Includes a code coach with practice problems and 4-axis code review.

Frequently Asked Questions

Why can't I use LinkedIn or Indeed URLs?

These sites actively block automated data extraction with JavaScript rendering, CAPTCHAs, and login walls. Use the "Paste JD" feature instead — copy the job description text and paste it directly.

What LLM model is used?

NextSteps uses gpt-oss-120b for most tasks (CV parsing, resume tailoring, interview scoring) and gpt-oss-20b for JD extraction. Both run on Groq's inference engine.

Is my data stored permanently?

CV data is processed in-memory and written to temp files that are deleted after parsing. ChromaDB stores embeddings locally in the /data directory. No data is sent to external servers beyond Groq and Tavily API calls.

Can I change the API endpoint?

Yes — click the ⚙ Settings icon in the dashboard navbar to configure a custom API URL (e.g., your Railway deployment).

How do I clear my session?

Click "↺ Start Fresh" in the sidebar, or go to Settings → Clear All Data. This removes all localStorage data and resets the UI to the initial state.