HermePrep — Generic Edition

A local, scheduled AI study buddy for job-hunting — fork it, fill in one config file with your own background, pick an LLM provider (local and free, or a hosted API), and get a personalized daily study plan every morning.

Every day, it prepares:

• A real LeetCode problem (hints, multiple solution tiers, a diagram)
• A CS fundamentals concept (with a diagram and further-reading links)
• A tailored interview Q&A, grounded in your actual projects
• (Twice a week) A digest of fresh job postings matching your target role shown in a clean local web page, with a desktop notification when it's ready.

Who this is for: freshers, career-switchers, college students, or anyone doing structured interview prep who'd rather have a study plan waiting for them each morning than build one from scratch every day.

📖 Read the full write-up: Tired of Doing Job Prep Manually Every Day? I Built Agents That Do It For Me — the complete Windows setup walkthrough with screenshots, from installing Ollama to scheduling it with Task Scheduler.

Inspired by freeCodeCamp's "How to Build and Schedule Local AI Assistants for Daily Tasks".

See it actually running first

HermePrep is the my real, permanently-running setup — Windows, Ollama (phi4-mini), real resume data filled in. If you want to see this genuinely working before committing to setting up your own copy, look there first.

This repo is the generalized version of that project: same agents, same features, but config-driven so anyone can plug in their own background and (new here) choice of LLM provider — not just Ollama.

🤖 Setting this up with an AI assistant

This repo ships a CLAUDE.md file written specifically to guide Claude (or Claude Code) through setting this up for you — picking a provider, filling in your profile from your resume, installing the right dependencies, and scheduling it. If you have Claude Code, just open this repo and ask it to set the project up for you; it'll walk through the file in order and check in with you at the right points. Otherwise, follow the Quick Start below manually.

Choose your LLM provider

Provider	Cost	Setup	Best for
Ollama	Free	Install Ollama + pull a model	Fully local/private, no ongoing cost, needs decent hardware (~4GB+ VRAM)
Groq	Free tier (generous)	Just an API key	Fastest to get started, no local hardware needed
Mistral	Free tier available	Just an API key	Good alternative if Groq doesn't fit
Gemini	Free tier available	Just an API key	Good alternative, Google ecosystem

Switching providers later is a one-line change in .env (LLM_PROVIDER=...) — nothing else in the codebase needs to change.

Features

• Any LLM provider — Ollama (local/free), Groq, Mistral, or Gemini, picked via one .env setting
• One scheduled task, smart daily rotation — each agent declares which weekdays it runs; no need for four separate cron/Task Scheduler entries
• No-repeat memory — every agent logs what it's already covered so you don't see the same DSA problem or interview question loop back too soon
• Real, curated DSA problems (not AI-invented) — tagged Beginner / Intermediate / Advanced, each with Brute Force → Better → Optimal solution tiers, a real LeetCode link, and a real matching YouTube video (or a search link if you skip the optional YouTube API key)
• Live "Further Reading" links for CS fundamentals, fetched via DuckDuckGo at generation time — never hallucinated URLs
• Diagrams — Mermaid flowcharts for DSA approaches and CS concepts, with a clean fallback if the model's diagram syntax comes out invalid
• Voice read-aloud for sample interview answers — browser's built-in text-to-speech, with a voice picker
• A tabbed, dark-themed local web viewer with a native desktop popup notification when your daily digest is ready
• Fully config-driven personalization — your background lives in one file (config/profile.py), agent code never changes

How it works (architecture)

job-prep-agents/
├── CLAUDE.md               # setup/customization guide for AI assistants
├── llm_provider.py         # unified factory: any provider, one function
├── scheduler.py            # loads every agent, runs what's due, builds the viewer
├── run_scheduler.bat       # Windows Task Scheduler entry point
├── notify.ps1              # native popup notification (Windows)
├── .env.example            # copy to .env — provider + API key settings
├── requirements.txt         # core deps + Ollama (comment out if unused)
├── requirements-groq.txt    # only needed if LLM_PROVIDER=groq
├── requirements-mistral.txt # only needed if LLM_PROVIDER=mistral
├── requirements-gemini.txt  # only needed if LLM_PROVIDER=gemini
├── config/
│   └── profile.py          # YOUR background — fill this in
├── examples/
│   └── profile.metta.py    # a real, filled-out example profile for reference
├── outputs/                 # generated each run: viewer-YYYY-MM-DD.html + raw .md
├── history/                 # auto-tracked: what's already been covered per agent
└── agents/
    ├── _history.py          # shared no-repeat tracking helper
    ├── _websearch.py         # shared DuckDuckGo lookup helper (graceful fallback)
    ├── dsa_problem.py         # curated real LeetCode problems + tiered solutions
    ├── cs_fundamentals.py     # rotating OS/DBMS/CN/OOP/System Design concepts
    ├── interview_qa.py        # tailored + generic interview Q&A
    └── job_digest.py          # Mon & Thu: job postings matching your target role

Every agent is a Python file with a NAME and a run() that returns Markdown. scheduler.py doesn't know what any agent does — it discovers and runs everything in agents/. Adding a new agent is just adding a new file — see CONTRIBUTING.md.

The "calendar" — one scheduled task, not four

Each agent declares which weekdays it runs via a SCHEDULE set (0=Monday ... 6=Sunday); no attribute means "every day". dsa_problem, cs_fundamentals, interview_qa run daily; job_digest runs Mon/Thu by default. You only need one scheduled task — the scheduler figures out which agents actually run each day.

Quick start

1. Clone and set up a virtual environment

git clone <this-repo-url>
cd job-prep-agents
python -m venv venv
# Windows: venv\Scripts\activate     macOS/Linux: source venv/bin/activate
pip install -r requirements.txt

If you're using a hosted API provider instead of Ollama, also install that provider's package (and feel free to remove langchain-ollama from requirements.txt if you're not using Ollama at all):

pip install -r requirements-groq.txt      # if using Groq
pip install -r requirements-mistral.txt   # if using Mistral
pip install -r requirements-gemini.txt    # if using Gemini

2. Configure your provider

cp .env.example .env

Set LLM_PROVIDER to ollama, groq, mistral, or gemini, then fill in that provider's section only:

Ollama (local, free)

1. Install Ollama: https://ollama.com
2. Pull a model based on your VRAM:

   ollama pull phi4-mini      # good default, 4GB+ VRAM
   ollama pull qwen2.5:3b     # lighter alternative
   ollama pull gemma2:2b      # fastest / lightest fallback

3. Set OLLAMA_MODEL in .env to match.

VRAM/context-window note: some models default to a huge context window, which can force far more memory allocation than the model's file size suggests — sometimes overflowing a small GPU into slow CPU inference. This project caps context via num_ctx=4096 in every agent already. If things run slowly, check ollama ps — if PROCESSOR isn't close to 100% GPU, the model/context is too big for your VRAM.

Groq (hosted, free tier, fastest to set up)

1. Get a free key: https://console.groq.com/keys
2. Set GROQ_API_KEY in .env.
3. GROQ_MODEL defaults to a current general-purpose model — check https://console.groq.com/docs/models if you want to change it (Groq retires/renames models fairly often).

Mistral (hosted, free tier available)

1. Get a key: https://console.mistral.ai/
2. Set MISTRAL_API_KEY in .env.
3. MISTRAL_MODEL defaults to mistral-large-latest (a rolling alias that always points to their current flagship model).

Gemini (hosted, free tier available)

1. Get a free key: https://aistudio.google.com/apikey
2. Set GEMINI_API_KEY in .env.
3. GEMINI_MODEL defaults to gemini-flash-latest (a rolling alias).

3. (Optional) Job digest + embedded videos

• OLLAMA_API_KEY — needed for the job_digest agent's web search regardless of which LLM_PROVIDER you picked above (search and chat inference are separate concerns here). Get one at https://docs.ollama.com/api/authentication
• YOUTUBE_API_KEY — optional, enables real embedded videos for DSA problems instead of just a search link:
  1. https://console.cloud.google.com/ → create/select a project
  2. Enable the YouTube Data API v3
  3. Credentials → Create Credentials → API key → paste into .env

4. Fill in your own profile

Open config/profile.py and replace the placeholders with your own background — see examples/profile.metta.py for a real, detailed reference. This is the only file with personal content.

If you have Claude Code, this is exactly what CLAUDE.md is for — it can read your resume/notes and fill this in for you.

5. Test it manually

python scheduler.py

Watch for [run]/[ok] lines. When it finishes, your browser should auto-open to outputs/viewer-<today>.html.

6. Schedule it

Windows — edit run_scheduler.bat's two paths (project folder + venv's python.exe), then:

schtasks /Create /SC DAILY /TN "HermePrep" /TR "C:\full\path\to\job-prep-agents\run_scheduler.bat" /ST 10:30 /RL HIGHEST

Verify anytime with schtasks /Query /TN "HermePrep" /V /FO LIST — check the Last Result field is 0 after a run.

macOS/Linux — scheduler.py itself is already cross-platform; add a cron entry, e.g.:

30 10 * * * cd /full/path/to/job-prep-agents && ./venv/bin/python scheduler.py >> runner.log 2>&1

Note: the desktop popup notification (notify.ps1) is Windows-specific — on macOS/Linux you'd want a small osascript/notify-send equivalent (not included yet — contributions welcome, see CONTRIBUTING.md).

What you'll see each morning

A tabbed HTML page (outputs/viewer-YYYY-MM-DD.html) — one tab per agent that ran that day, plus a browsable outputs/index.html linking every day so far.

What's in each tab

• DSA Problem — a real, curated LeetCode problem (Beginner/Intermediate/ Advanced), hints, then Brute Force → Better → Optimal solutions each with reasoning and complexity, a Mermaid diagram, a real LeetCode link, and either an embedded matching YouTube video or a search link
• CS Fundamentals — a rotating concept, a diagram where it helps, a likely interview question with a sample answer, and live "Further Reading" links
• Interview Prep — technical + behavioral questions rotating through your project anchors, real past questions, ML fundamentals gaps, and generic industry-standard questions not tied to your specific projects. Every Sample Answer gets a 🔊 Read Aloud button (with a voice picker) and 📋 Copy.
• Job Digest (Mon & Thu) — fresh postings matching your JOB_SEARCH_QUERIES

Customization guide

Want to change...	Edit this file
Your background, projects, target roles, past questions	config/profile.py
Which LLM provider / model	.env
Which DSA problems are covered / their difficulty	agents/dsa_problem.py → PROBLEM_BANK
Which CS topics rotate through	agents/cs_fundamentals.py → TOPICS
Which interview focus areas show up	agents/interview_qa.py → FOCUS_AREAS
Job search queries	config/profile.py → JOB_SEARCH_QUERIES
Which days an agent runs	that agent's SCHEDULE set
The look of the viewer page	scheduler.py → PAGE_STYLE / VIEWER_SCRIPT
Adding a new LLM provider	llm_provider.py — add a new elif branch

Troubleshooting

Scheduler hangs for minutes with no output (Ollama)

Almost always Ollama loading the model into memory for the first time (or after being idle) — not actually stuck. Check ollama ps in a second terminal. Set OLLAMA_KEEP_ALIVE=30m in .env so repeated runs stay fast.

ollama ps shows a huge memory size / mostly CPU, not GPU

The model's default context window is likely bigger than your VRAM can hold. This project already caps num_ctx=4096 in every agent via llm_provider.py.

"Unknown LLM_PROVIDER" or a missing-API-key error

Check .env — LLM_PROVIDER must be exactly ollama, groq, mistral, or gemini, and the matching *_API_KEY for hosted providers must be filled in.

A hosted provider's default model errors as "retired" or "unknown"

Hosted API providers change their model catalogs fairly often. Check the docs link in .env.example for that provider and set *_MODEL explicitly.

Windows batch file errors with garbled paths

The entire path needs to be inside one pair of quotes, not just the part with a space. Wrong: cd /d C:\"My Folder"\project. Right: cd /d "C:\My Folder\project".

Windows Task Scheduler: task exists but "Last Result" isn't 0

-2147024891 (0x80070005) is "Access Denied" — a Task-Scheduler-specific permissions issue, not a script bug (especially if double-clicking the .bat directly works fine). Try recreating the task with /RL HIGHEST, and check Windows Security → Virus & threat protection → Controlled folder access, which sometimes blocks non-interactively-triggered scripts.

Embedded YouTube video shows "Error 153"

That's YouTube's error for "video owner disabled embedding elsewhere." This project already works around it with a clickable thumbnail + link instead of an <iframe>, which works regardless of embed permissions.

Mermaid diagram shows a "bomb icon" / syntax error

Small/fast models occasionally produce invalid Mermaid syntax. The viewer validates syntax before rendering and shows a clean "Diagram unavailable" message instead.

A note on trust

Even hosted, more capable models still occasionally get things wrong — spot- check DSA solutions, job postings, and technical explanations before trusting them fully. Treat this as a study nudge and starting point, not gospel.

Contributing

See CONTRIBUTING.md — new agents, new LLM providers, cross-platform (macOS/Linux) scheduling support, and docs are all welcome.

License

MIT — free to use, modify, and redistribute.