tam159/next-role

---

What is NextRole?

Preparing for an interview takes hours of tedious resume tailoring and company research. NextRole automates the heavy lifting. Hand it your current CV and a target Job Description (or just a JD URL) — whether you’re applying externally or angling for an internal move — and a team of specialized AI agents researches the company, rewrites your resume to fit, coaches you round-by-round, and prints a cheat sheet for the day of.

• 📄 Tailored resume → PDF — your experience rewritten against the exact JD + company research, rendered with rendercv (editable & re-renderable).
• 🔍 Deep company & role recon — live web research distilled into a match analysis.
• 🎯 Structured interview prep — a self-introduction plus per-round STAR stories mapped to the role.
• ⚡ Day-of battlecard — a one-page-per-round PDF cheat sheet for the final high-pressure review.
• 🗓️ Time-boxed prep plans — a study plan that fits 1 month, 2 weeks, or just 3 hours.
• 🔗 Paste a JD URL — point it at a careers page; it extracts and processes the posting for you.
• 💬 Iterate by chatting — “add a 4th round”, “add React to my skills” — streaming multi-turn edits, with the right agent owning each file.
• 🗂️ Built-in workspace — upload, preview (PDF / MD / YAML / JSON / code), print-to-PDF, and swap the LLM at runtime.

Demo

Your browser does not support the video tag.

▶️ Watch the full walkthrough in HD on YouTube »

Quick Start

The whole stack — frontend, backend, Postgres, Redis, S3-compatible object storage, and an analytics stack (ClickHouse, Dagster, Cube, Superset) — runs in Docker.

# 1. Clone & configure
git clone https://github.com/tam159/next-role.git
cd next-role
cp .env.example .env          # then fill in your API keys (see table below)

# 2. Launch everything
docker compose up -d

# 3. Find your host ports (set in .env, vary per machine)
docker ps                     # read the 0.0.0.0:->... mappings

# 4. Open the app
#    Frontend UI      →  http://localhost:/
#    Backend API docs →  http://localhost:/docs

💡 Pick your LLM in the app. Open the in-app Configuration dialog to set the main agent and subagent models — no rebuild needed. See LLM configuration below for recommended models and free / local options.

Architecture

NextRole is a supervisor agent orchestrating three specialist subagents on LangGraph + DeepAgents. The main agent handles intake, document processing, and the final battlecard; it delegates research, resume tailoring, and interview coaching to declarative subagents (defined in subagents.yaml, each with its own model, tools, and skills).

How It Works

A five-stage generation pipeline. Stage 4 runs the resume tailor and interview coach in parallel; after generation, Stage 6 routes follow-up edits to whichever agent owns the target file.

Roadmap

• 💤 “Auto-dream” consolidation — sleep-time compaction that prunes stale notes and merges insights into durable memory.
• 🔐 Wider execute allowlist in sandbox mode — remote sandboxes shipped (SANDBOX_PROVIDER=e2b → self-hosted CubeSandbox or E2B Cloud); next, let sandboxed deployments auto-approve more than the conservative read-only list.
• 📊 Agent evaluation — LangSmith evals over the workflow (the @pytest.mark.eval marker is already reserved).
• 🎨 Enhanced UI — richer artifact editing, diff views, and inline regeneration.
• 🔌 MCP / A2A examples — sample integrations driving career_agent from external agents and IDEs.
• ☁️ Cloud deployment — binary artifacts already live in S3-compatible object storage (SeaweedFS locally; point OBJECT_STORE_* at S3 / GCS / Azure). Remaining: managed bucket provisioning (versioning, SSE, IAM) and presigned-URL delivery.
• 🌐 More sources & ATS-aware tailoring — pluggable retrievers + keyword/ATS optimization passes.

Limitations

Multi-user mode isolates data; before opening signups to untrusted users, also move shell execution off the default local mode (SANDBOX_PROVIDER=e2b).

• 🔒 Local shell execution is the default — with SANDBOX_PROVIDER=local, execute and render commands run via subprocess on the host (HiL-gated). Safe locally and for a trusted team; for untrusted multi-tenant use switch to e2b so every command runs in an isolated microVM (deploy/cubesandbox/).
• 🧪 LLM evals deferred — current tests are unit + local-DB integration; automated quality evals aren’t wired up yet.
• 🧠 Personalization is preferences-only — the agent persists and auto-applies the preferences you state across sessions, but doesn’t yet infer your style/history on its own or consolidate memory over time (see roadmap).
• ⏱️ Latency — a full run makes several LLM and tool calls across multiple agents; expect minutes, not seconds.

🗺️ Explore the codebase graph

This repo ships a pre-built architecture knowledge graph in .ua/ — the whole codebase mapped by Understand-Anything into 1,100+ nodes across 10 architectural layers, with a guided tour. Browse it as an interactive dashboard:

The same treatment exists for the product’s design history: every feature ships with a PRD in docs/prd/ — an OKF knowledge bundle whose committed interactive graph (docs/prd/viz.html) maps how features extend and supersede each other. The codebase graph maps the code; the PRD graph maps the decisions. See docs/prd/README.md to browse or regenerate it.

Contributing

PRs and issues are welcome! Start with CONTRIBUTING.md — it walks through the fork → PR workflow, local setup, the CI quality gate (code quality + backend tests + frontend tests), testing, and conventions. Stack-specific details live in backend/AGENTS.md, frontend/AGENTS.md, and analytics/AGENTS.md; commits follow Conventional Commits.

New here? Issues labelled good first issue are a gentle place to start, and questions are welcome in Discussions.

License

MIT © 2026 Tam Nguyen

Acknowledgements

Built on DeepAgents, LangChain / LangGraph / LangSmith, rendercv, WeasyPrint, Tavily, and LlamaIndex / LlamaParse.