convez.ai
MCP ServerProdutividadeAvançado
tam159

NextRole — Acelerador de Carreira com IA

tam159/next-role

Automatize CV, pesquisa e prep de entrevista em minutos com agentes IA

Ver no GitHub
BomPluginScore · de 0 a 100

MCP Server que automatiza preparação de entrevistas de emprego usando múltiplos agentes IA. Transforma seu CV e job description em resume tailorizado, pesquisa de empresa, plano de prep estruturado e battlcard para o dia da entrevista. Integra LangGraph, LangChain e web research para iteração contínua.

Instalação

$npx convez-ai tam159/next-role

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
68
Forks
15
Acompanhando
5
Saúde
100%
Último commit
há 5 dias
Versão
—
Issues abertas
10
Contribuidores
3

Casos de uso

  • Candidatos ajustando CV para posições específicas em 30 min vs 3 horas
  • Profissionais em transição pesquisando automáticamente cultura e tecnologia da empresa
  • Candidatos internos preparando argumentos para promoção com dados estruturados
  • Equipes de recrutamento gerando análises de fit candidato-vaga

Veredito

Ferramenta sólida e bem-engineered para automação end-to-end de entrevistas, com agentes especializados e workspace integrado. Recomendada para profissionais técnicos que fazem entrevistas frequentes ou equipes que processam alto volume de candidatos; exige setup Docker e chaves de API.

README

A tradução para o português deste README ainda está na fila.

NextRole 🚀

✨ GenAI-Accelerated Career Advancement ✨

Upload your CV + a job description. Get a tailored resume PDF, a researched interview-prep doc, and a day-of battlecard cheat sheet — built by a multi-agent system with long-term memory.

Python Next.js React License: MIT PRs Welcome GitHub stars

LangChain LangGraph DeepAgents LangSmith Exposes MCP + A2A


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

▶️ Watch the full walkthrough in HD on YouTube »

Quick Start

The whole stack — frontend, backend, Postgres, Redis — 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:<host>->... mappings

# 4. Open the app
#    Frontend UI      →  http://localhost:<FRONTEND_LOCAL_PORT>/
#    Backend API docs →  http://localhost:<LANGGRAPH_LOCAL_PORT>/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.

VariableRequiredPurpose
OPENAI_API_KEY✅Default main + subagent models
TAVILY_API_KEY✅Web research (hiring-recon)
LLAMA_CLOUD_API_KEY✅Document parsing (LlamaParse)
POSTGRES_PASSWORD✅Local Postgres password
ANTHROPIC_API_KEY / GOOGLE_API_KEY⬜Alternative providers (swap at runtime)
OPENAI_API_BASE⬜Self-hosted / Azure / LM Studio endpoint
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION⬜AWS Bedrock models
LANGCHAIN_API_KEY + LANGCHAIN_TRACING_V2=true⬜LangSmith tracing (recommended)
FRONTEND_LOCAL_PORT / LANGGRAPH_LOCAL_PORT / POSTGRES_LOCAL_PORT / REDIS_LOCAL_PORTpresetHost port mappings

Secrets live only in .env (gitignored); gitleaks runs on every commit.

Models are swappable at runtime — no rebuild. Open the in-app Configuration dialog and set Main agent / Subagents to a <provider>:<model> string (e.g. anthropic:claude-sonnet-4.6); leave blank to use the defaults. Settings persist in your browser's local storage.

Recommended: Claude Sonnet 4.x, GPT-5.x, or Gemini 3.x — e.g. anthropic:claude-sonnet-4.6, openai:gpt-5.4, google_genai:gemini-3.5-flash.

Run it for free or fully local:

  • Tavily and LlamaCloud both include a generous monthly free tier — plenty for local use.
  • Google AI Studio offers a free tier for Gemini flash / lite models.
  • Fully local — point OPENAI_API_BASE at LM Studio or Ollama (both expose an OpenAI-compatible API) and fill your local model in the UI.

Output quality tracks the model you pick — smaller local models trade some quality for zero cost.

  • Code edits hot-reload in both containers — just save the file.
  • Add a frontend dep: pnpm --dir frontend add <pkg> → docker compose restart frontend
  • Add a backend dep: uv add <pkg> → docker compose up -d --build backend
  • Change .env: docker compose restart <service>
  • Stop: docker compose down (add -v to wipe the DB & Redis volumes)

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).

NextRole architecture

How It Works

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

How NextRole works

  1. Intake — the agent asks for your CV, the JD (file, URL, or pasted text), your prep timeline, and any extra context.
  2. Process documents — uploads are parsed to markdown via LlamaParse (parse_document); JD URLs are pulled via Tavily (extract_jd). Results land in /processed/, alongside a persisted intake note.
  3. Research — the hiring-recon subagent gathers company + role intel and a match analysis → /research/<resume>/<jd>.md.
  4. Tailor & coach (parallel) — resume-tailor rewrites the CV as a rendercv YAML and renders a PDF; interview-coach writes a structured prep doc (self-intro + per-round STAR stories).
  5. Battlecard — the main agent assembles a one-page-per-round JSON and renders it to a day-of PDF via WeasyPrint.
  6. Multi-turn updates — ask for changes in chat; the owning agent reads the existing file, preserves everything you didn't name, and re-renders.

The full procedure (file layout, update routing, source-of-truth conventions) lives in backend/app/career_agent/README.md. Per-feature design docs are in docs/prd/.

The agent's behavior is configured by files, not hardcoded — making it easy to read, diff, and extend:

PrimitiveWhereRoleWhen loaded
MemoryAGENTS.mdPer-stage procedure manual (semantic memory)Always (system prompt)
Skillsskills/<consumer>/<name>/SKILL.mdTask workflows (procedural memory)On demand, per consumer
Subagentssubagents.yamlSpecialist delegates → the task toolAlways
Toolstools.py + DeepAgents built-insparse_document, extract_jd, render_battlecard_pdf, prepare_render_settings, list_files, overwrite_file, plus read/write/edit_file, ls/glob/grep, execute—
FilesystemCompositeBackendRoutes virtual paths to the right store (see below)—
Middlewaremiddleware.pyModelOverrideMiddleware (runtime LLM swap) + UtcDatetimeMiddleware—

Subagents only receive the tools they opt into in YAML — tool whitelisting keeps interview-coach, for example, from inheriting the main agent's full toolset.

A single CompositeBackend gives the agent one virtual filesystem while routing each path prefix to the right physical store — Postgres for text artifacts, disk for binaries and render outputs, and a shell backend that translates virtual paths to real ones before running commands like rendercv render.

flowchart LR
    Agent["Agent filesystem tools<br/>read_file · write_file · edit_file<br/>ls · glob · grep · execute"]
    CB{{"CompositeBackend<br/>routes virtual paths"}}
    Agent --> CB
    subgraph Shell["VirtualPathShellBackend · default route"]
        SH["rewrites /virtual/path → on-disk path<br/>before subprocess.run<br/>(e.g. rendercv render /tailored_resume/...)"]
    end
    subgraph Store["StoreBackend · Postgres + pgvector"]
        ST["/memory/ · /processed/ · /research/<br/>/interview_coach/<br/>/large_tool_results/ · /workspace/"]
    end
    subgraph Disk["FilesystemBackend · disk (binaries + renders)"]
        DK["/upload/ · /tailored_resume/<br/>/render_intermediate/<br/>/interview_battlecard/"]
    end
    CB -->|default| Shell
    CB -->|KV routes| Store
    CB -->|binary + PDF routes| Disk
    Sem["Semantic memory · AGENTS.md"] -. loaded into system prompt .-> Agent
    Proc["Procedural memory · skills/*/SKILL.md"] -. loaded on demand .-> Agent
    Work["Working memory · LangGraph thread"] -. drives .-> Agent
    Store --- Epi["Episodic memory · persisted artifacts<br/>(incl. /memory/ auto-memory)"]
    Disk --- Epi

Mapped to memory types:

  • Working memory — the live LangGraph conversation thread.
  • Semantic memory — AGENTS.md, always in the system prompt.
  • Procedural memory — skills/*/SKILL.md, loaded on demand.
  • Episodic memory — persisted artifacts in Postgres + disk, including auto-memory: standing preferences saved to the /memory/ route and auto-applied across sessions.
LayerStack
BackendPython 3.13 · LangChain v1 · LangGraph 1.x · DeepAgents 0.6 · uv · served on langchain/langgraph-api:3.13
Agent I/OTavily (web search) · LlamaParse / LlamaCloud (document parsing) · rendercv (resume → PDF) · WeasyPrint (battlecard → PDF)
FrontendNext.js 16 · React 19 · TypeScript · Tailwind · pnpm · @langchain/react (v2 useStream)
DataPostgreSQL 18 + pgvector · Redis 8
InfraDocker Compose (frontend · backend · postgres · redis)
ObservabilityLangSmith

Because NextRole runs on the LangGraph Agent Server, the career_agent assistant is also reachable by other tools and agents — no extra code:

  • MCP — exposed as Model Context Protocol tools at /mcp (Streamable HTTP), usable by any MCP-compliant client. → docs
  • A2A — Google's Agent2Agent protocol at /a2a/{assistant_id} (JSON-RPC 2.0; message/send + message/stream). → docs
  • The full server API is browsable at the /docs endpoint of your deployment.

NextRole Agent Expose

Set LANGCHAIN_API_KEY and LANGCHAIN_TRACING_V2=true in .env, and every run — each LLM call, tool call, and nested subagent — is traced at smith.langchain.com under the LANGCHAIN_PROJECT you configure. Optional, but invaluable for debugging the multi-agent flow.

Roadmap

  • 💤 "Auto-dream" consolidation — sleep-time compaction that prunes stale notes and merges insights into durable memory.
  • 📦 Remote sandboxes — swap LocalShellBackend for an isolated remote sandbox (e.g. Daytona) so render/shell steps are safe for multi-tenant use.
  • 📊 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.
  • 🧵 Per-thread / multi-user scoping — namespace artifacts per user instead of the current global layout.
  • 🌐 More sources & ATS-aware tailoring — pluggable retrievers + keyword/ATS optimization passes.

Limitations

NextRole is built for local, single-user, trusted use today.

  • 🔒 Local shell execution — VirtualPathShellBackend runs render commands via subprocess on the host. Safe locally; not hardened for multi-tenant production (needs sandboxing — see roadmap).
  • 👤 Global file scoping — uploads and artifacts share one filesystem layout; re-uploading a filename overwrites. No per-user isolation yet.
  • 🧪 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.

Contributing

PRs and issues are welcome! Start with CONTRIBUTING.md — it walks through the fork → PR workflow, local setup, the CI quality gate (pre-commit + backend tests), testing, and conventions. Stack-specific details live in backend/CLAUDE.md and frontend/CLAUDE.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.

Ver o original no GitHub

Bom para

Relacionados