stellenpilot 0.1.0__py3-none-any.whl

stellenpilot/__init__.py

@@ -0,0 +1,3 @@
+"""Local job hunt pipeline."""
+
+__version__ = "0.1.0"

stellenpilot/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

stellenpilot/cli.py

@@ -0,0 +1,289 @@
+"""Command line: stellenpilot init | doctor | run | serve | gmail | demo"""
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import shutil
+import sys
+from importlib import resources
+from pathlib import Path
+
+from .config import Settings
+
+ENV_TEMPLATE = """# Secrets for stellenpilot. This file is ignored by git. Never commit it.
+# LLM (pick one, matching llm.provider in config.toml)
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+# Optional job sources
+ADZUNA_APP_ID=
+ADZUNA_APP_KEY=
+THEIRSTACK_API_KEY=
+# Optional daily digest to yourself (see docs/digest.md)
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USER=
+SMTP_PASSWORD=
+DIGEST_TO=
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+"""
+
+
+def _examples_dir() -> Path:
+    return Path(str(resources.files("stellenpilot").joinpath("examples")))
+
+
+def cmd_init(home: Path) -> None:
+    ex = _examples_dir()
+    for src, dst in (("config.example.toml", "config.toml"), ("profile.example.toml", "profile.toml")):
+        target = home / dst
+        if target.exists():
+            print(f"keep  {dst} (already exists)")
+        else:
+            shutil.copy(ex / src, target)
+            print(f"made  {dst}")
+    env = home / ".env"
+    if not env.exists():
+        env.write_text(ENV_TEMPLATE, encoding="utf-8")
+        print("made  .env (put your API keys here)")
+    print("\nNext: edit profile.toml with your real CV facts, check config.toml, then run `stellenpilot doctor`.")
+
+
+def cmd_doctor(settings: Settings) -> int:
+    from .sources import REGISTRY
+    ok = True
+    print(f"home: {settings.home}")
+    print(f"config.toml: {'found' if (settings.home / 'config.toml').exists() else 'missing, using defaults'}")
+    if not settings.profile:
+        print("profile.toml: MISSING (run stellenpilot init)"); ok = False
+    elif settings.profile.get("person", {}).get("name") == "Alex Example":
+        print("profile.toml: still the example profile. Replace it with your own facts.")
+    else:
+        print("profile.toml: ok")
+    for name, mod in REGISTRY.items():
+        on = settings["sources"].get(name)
+        need = [k for k in getattr(mod, "NEEDS", ()) if not settings.secret(k)]
+        covered = getattr(mod, "COUNTRIES", None)
+        country = settings["search"]["country"].lower()
+        state = "off" if not on else (f"ON but missing {', '.join(need)}" if need else
+                                      f"on, but it does not cover '{country}' (skipped)" if covered and country not in covered else "on")
+        if name == "watchlist":
+            state = f"{len(settings['watch'].get('companies') or [])} companies"
+        ok &= not (on and need and name != "watchlist")
+        print(f"source {name:15} {state}")
+    ok &= _check_llm(settings)
+    from .tailor import find_soffice
+    print(f"pdf export: {'LibreOffice found' if find_soffice() else 'LibreOffice not found, DOCX only'}")
+    print(f"gmail: {'on' if settings['gmail'].get('enabled') else 'off'}")
+    return 0 if ok else 1
+
+
+def llm_status(settings: Settings) -> tuple[bool, str]:
+    from .llm import LLM
+    prov = settings["llm"]["provider"]
+    try:
+        llm = LLM(settings)
+    except RuntimeError as e:
+        return False, f"{prov}: {e}"
+    if not llm.local:
+        return True, (f"{prov} ({llm.model})" if llm.enabled else "none: keyword scoring and template letters")
+    try:
+        models = llm.list_models()
+    except Exception as e:
+        start = "Start the Ollama app (or run: ollama serve)" if prov == "ollama" else "Start the model server"
+        return False, f"nothing answers at {llm.base_url}. {start}, then test again. ({e.__class__.__name__})"
+    have = any(m == llm.model or m.split(":")[0] == llm.model or m.endswith("/" + llm.model) for m in models)
+    if have or (len(models) == 1 and prov != "ollama"):
+        return True, f"{prov} at {llm.base_url}, model {llm.model} ready"
+    hint = f" Run: ollama pull {llm.model}" if prov == "ollama" else ""
+    return False, f"{prov} is running, but model '{llm.model}' is not installed. Available: {', '.join(models[:8]) or 'none'}.{hint}"
+
+
+def _check_llm(settings: Settings) -> bool:
+    ok, msg = llm_status(settings)
+    print(f"llm: {msg}" if ok else f"llm: PROBLEM: {msg}")
+    return ok
+
+
+def setup_checks(settings: Settings) -> list[dict]:
+    """The same checks as `stellenpilot doctor`, as data for the dashboard's setup guide."""
+    from .sources import REGISTRY
+    from .tailor import find_soffice
+    out = []
+    name = settings.profile.get("person", {}).get("name") if settings.profile else ""
+    out.append({"step": "cv", "ok": bool(name) and name != "Alex Example",
+                "text": f"CV saved for {name}" if name and name != "Alex Example" else "Your CV is not saved yet"})
+    out.append({"step": "search", "ok": bool(settings["search"]["keywords"]),
+                "text": f"Looking for {', '.join(settings['search']['keywords'][:3])} near {settings['search']['city']}"})
+    ok, msg = llm_status(settings)
+    out.append({"step": "ai", "ok": ok, "text": "AI model: " + msg})
+    on = [n for n, m in REGISTRY.items() if n != "watchlist" and settings["sources"].get(n)]
+    for n in on:
+        need = [k for k in getattr(REGISTRY[n], "NEEDS", ()) if not settings.secret(k)]
+        if need:
+            out.append({"step": "sources", "ok": False, "text": f"{REGISTRY[n].LABEL} is on but its key is missing"})
+    out.append({"step": "sources", "ok": bool(on), "text": f"{len(on)} job source{'s' if len(on) != 1 else ''} on" if on else "No job source is switched on"})
+    out.append({"step": "extra", "ok": True, "optional": True,
+                "text": "PDF export: LibreOffice found" if find_soffice() else "No LibreOffice, so you get Word files only (optional)"})
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="stellenpilot", description="Stellenpilot: your local job search assistant")
+    ap.add_argument("--home", type=Path, default=Path.cwd(), help="folder with config.toml and profile.toml")
+    ap.add_argument("-v", "--verbose", action="store_true")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("init", help="create config.toml, profile.toml and .env from the examples")
+    sub.add_parser("doctor", help="check your setup")
+    r = sub.add_parser("run", help="search, score, tailor and sync once")
+    r.add_argument("--no-tailor", action="store_true", help="skip CV and letter generation")
+    s = sub.add_parser("serve", help="open the local dashboard")
+    s.add_argument("--port", type=int, default=8765)
+    s.add_argument("--host", default=os.environ.get("JOBHUNT_HOST", "127.0.0.1"),
+                   help="address to listen on; keep 127.0.0.1 unless you run inside Docker")
+    sub.add_parser("gmail", help="sync statuses from Gmail once")
+    sub.add_parser("demo", help="load fictional sample jobs to try the dashboard without any keys")
+    sub.add_parser("notify-test", help="send a test digest by email or Telegram")
+    sub.add_parser("telegram-id", help="show your Telegram chat id after you messaged your bot")
+    im = sub.add_parser("import", help="turn your existing CV (PDF, DOCX, TXT) into profile.imported.toml")
+    im.add_argument("cv", type=Path)
+    ad = sub.add_parser("add", help="add a job yourself, from a link or pasted text")
+    ad.add_argument("url", nargs="?", default="", help="link to the ad on a company careers page")
+    ad.add_argument("--text", help="ad text, or a path to a .txt file, or - to read from stdin")
+    ad.add_argument("--title", default="")
+    ad.add_argument("--company", default="")
+    ad.add_argument("--location", default="")
+    ad.add_argument("--tailor", action="store_true", help="also make the CV and cover letter now")
+    w = sub.add_parser("watch", help="find the watchlist entry for a company's careers page")
+    w.add_argument("url", help="careers page or job link, or an entry like greenhouse:trivago")
+    a = ap.parse_args(argv)
+    logging.basicConfig(level=logging.INFO if a.verbose else logging.WARNING, format="%(message)s")
+    home = a.home.resolve()
+
+    if a.cmd == "init":
+        cmd_init(home)
+        return 0
+    settings = Settings(home)
+    if a.cmd == "doctor":
+        return cmd_doctor(settings)
+    if a.cmd == "run":
+        from .pipeline import run
+        res = run(settings, tailor=not a.no_tailor)
+        print(f"{res['new']} new jobs, {res['shortlisted']} shortlisted, {res['docs']} files made, "
+              f"{len(res['gmail'])} Gmail updates")
+        for p in res["problems"]:
+            print(f"  problem: {p}")
+        return 0
+    if a.cmd == "serve":
+        from .server import serve
+        serve(settings, a.port, a.host)
+        return 0
+    if a.cmd == "gmail":
+        from .db import DB
+        from .gmail_sync import sync
+        changes = sync(DB(settings.db_path), home, settings["gmail"].get("lookback_days", 3))
+        print(f"{len(changes)} status changes")
+        return 0
+    if a.cmd == "notify-test":
+        from .db import DB, today
+        from .notify import send_digest
+        if not (settings["notify"].get("email") or settings["notify"].get("telegram")):
+            print("Turn on email or telegram under [notify] in config.toml first.")
+            return 1
+        cfg = dict(settings["notify"], only_when_new=False)
+        settings.cfg["notify"] = cfg
+        problems = send_digest(settings, DB(settings.db_path), {"new": 0, "shortlisted": 0, "problems": ["(test message)"]}, today())
+        print("\n".join(problems) if problems else "Sent. Check your inbox or Telegram.")
+        return 1 if problems else 0
+    if a.cmd == "telegram-id":
+        from .notify import telegram_chat_ids
+        token = settings.secret("TELEGRAM_BOT_TOKEN")
+        if not token:
+            print("Put TELEGRAM_BOT_TOKEN in .env first (from @BotFather).")
+            return 1
+        ids = telegram_chat_ids(token)
+        if not ids:
+            print("No messages yet. Send any message (e.g. /start) to your bot in Telegram, then run this again.")
+            return 1
+        for cid, who in ids:
+            print(f"TELEGRAM_CHAT_ID={cid}    ({who})")
+        return 0
+    if a.cmd == "import":
+        from .importer import import_cv
+        try:
+            out, notes = import_cv(a.cv, settings)
+        except FileNotFoundError as e:
+            print(f"Import failed: {e}")
+            return 1
+        except (RuntimeError, ValueError) as e:
+            print(f"Import failed: {e}")
+            return 1
+        except OSError as e:  # network: the AI model server is not running or not reachable
+            print(f"Import failed: could not reach the AI model ({e}). Is it running? Check with: stellenpilot doctor")
+            return 1
+        except Exception as e:  # never show a raw traceback for a bad file or odd model output
+            print(f"Import failed: {e.__class__.__name__}: {e}")
+            return 1
+        print(f"Wrote {out.name}. Review it, then rename it to profile.toml.")
+        for n in notes[:12]:
+            print(f"  check: {n}")
+        if len(notes) > 12:
+            print(f"  ... {len(notes) - 12} more notes in the file")
+        return 0
+    if a.cmd == "add":
+        from .db import DB
+        from .manual import AddError, add_job
+        text = a.text or ""
+        if text == "-":
+            text = sys.stdin.read()
+        elif text and len(text) < 260 and "\n" not in text and Path(text).is_file():
+            text = Path(text).read_text(encoding="utf-8", errors="replace")
+        try:
+            res = add_job(settings, DB(settings.db_path), tailor=a.tailor, url=a.url, text=text,
+                          title=a.title, company=a.company, location=a.location)
+        except AddError as e:
+            print(f"Not added: {e}")
+            return 1
+        except Exception as e:  # never a raw traceback for an odd page or a model hiccup
+            print(f"Not added: {e.__class__.__name__}: {e}")
+            return 1
+        j = res["job"]
+        if res["status"] == "exists":
+            print(f"Already on your board: {j['title']} at {j['company']} (match {j['match']})")
+            return 0
+        print(f"Added: {j['title']} at {j['company']}, match {j['match']} ({j['fit']}). {j['why']}")
+        if j.get("german_level"):
+            print(f"  German asked for: {j['german_level']}")
+        if res.get("tailored"):
+            print(f"  Documents: {res['tailored']['folder']}")
+        return 0
+    if a.cmd == "watch":
+        from .sources.watchlist import fetch_company, parse_careers_url, title_matches, title_rules
+        entry = a.url if ":" in a.url and "//" not in a.url else parse_careers_url(a.url)
+        if not entry:
+            print("Could not recognize that link. Supported: Greenhouse, Lever, Ashby, Personio, SmartRecruiters.\n"
+                  "Tip: open a job on the company's careers page and use the link of its Apply page.")
+            return 1
+        try:
+            jobs = fetch_company(entry, settings["search"]["country"])
+        except Exception as e:
+            print(f"{entry}: could not read the feed ({e})")
+            return 1
+        rules = title_rules(settings)
+        hits = [j for j in jobs if title_matches(j["title"], rules)]
+        print(f"{entry}: {len(jobs)} open jobs, {len(hits)} match your keywords ({' or '.join(' + '.join(r) for r in rules)})")
+        for j in hits[:8]:
+            print(f"  * {j['title']}  ({j['location']})")
+        print(f'\nAdd this to [watch] companies in config.toml:  "{entry}"')
+        return 0
+    if a.cmd == "demo":
+        from .demo import load_demo
+        n = load_demo(settings)
+        print(f"Loaded {n} fictional jobs into {settings.db_path.name}. Now run: stellenpilot serve")
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

stellenpilot/config.py

@@ -0,0 +1,136 @@
+"""Load config.toml, profile.toml and secrets from the environment or a .env file."""
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+DEFAULTS = {
+    "search": {
+        "keywords": ["Werkstudent Data", "Junior Data Engineer"],
+        "city": "Berlin",
+        "radius_km": 50,
+        "nearby_cities": [],
+        "country": "de",
+        "include_remote": True,
+        "max_age_days": 3,
+        "exclude_title_words": ["senior", "lead", "head of", "principal"],
+    },
+    "language": {"skip_if_german_too_high": True, "my_german_level": "", "german_tolerance": 1},
+    "sources": {
+        "arbeitsagentur": True,
+        "arbeitnow": True,
+        "adzuna": False,
+        "theirstack": False,
+        "limits": {"adzuna_calls": 4, "theirstack_jobs": 6, "arbeitsagentur_results": 50},
+        "theirstack_options": {"location_ids": [], "english_only": True},
+    },
+    "llm": {"provider": "none", "model": "", "base_url": ""},
+    "tailor": {"min_match": 70, "max_per_run": 5, "output_dir": "output", "make_pdf": True, "only_english_ads": True, "letter_language": "auto"},
+    "gmail": {"enabled": False, "lookback_days": 3},
+    "watch": {"companies": [], "title_words": [], "max_age_days": 30},
+    "notify": {"email": False, "telegram": False, "only_when_new": False},
+    "schedule": {"enabled": False, "time": "08:45"},
+}
+
+
+def _merge(base: dict, over: dict) -> dict:
+    out = dict(base)
+    for k, v in over.items():
+        out[k] = _merge(base[k], v) if isinstance(v, dict) and isinstance(base.get(k), dict) else v
+    return out
+
+
+def load_dotenv(path: Path) -> None:
+    """Minimal .env reader: KEY=value lines, existing env vars win."""
+    if not path.exists():
+        return
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        val = val.strip()
+        if val[:1] in ("'", '"') and val[:1] in val[1:]:
+            val = val[1:val.index(val[0], 1)]
+        else:
+            val = val.split(" #")[0].strip()
+        os.environ.setdefault(key.strip(), val)
+
+
+class Settings:
+    def __init__(self, home: Path):
+        self.home = home
+        load_dotenv(home / ".env")
+        cfg_path = home / "config.toml"
+        user = tomllib.loads(cfg_path.read_text(encoding="utf-8")) if cfg_path.exists() else {}
+        self.cfg = _merge(DEFAULTS, user)
+        prof_path = home / "profile.toml"
+        self.profile = tomllib.loads(prof_path.read_text(encoding="utf-8")) if prof_path.exists() else {}
+        self.db_path = home / "jobhunt.db"
+
+    def __getitem__(self, key):
+        return self.cfg[key]
+
+    @staticmethod
+    def secret(name: str) -> str | None:
+        val = os.environ.get(name, "").strip()
+        return val or None
+
+
+# ---------------------------------------------------------------- saving from the dashboard
+
+def _toml_value(v) -> str:
+    import json
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return repr(v)
+    if isinstance(v, list):
+        return "[" + ", ".join(_toml_value(x) for x in v) + "]"
+    return json.dumps(str(v), ensure_ascii=False)  # JSON strings are valid TOML basic strings
+
+
+def dump_toml(data: dict, prefix: str = "") -> str:
+    import json
+    key = lambda k: k if k.replace("_", "").replace("-", "").isalnum() else json.dumps(k, ensure_ascii=False)
+    lines = [f"{key(k)} = {_toml_value(v)}" for k, v in data.items() if not isinstance(v, dict)]
+    for k, v in data.items():
+        if isinstance(v, dict):
+            name = f"{prefix}.{key(k)}" if prefix else key(k)
+            lines += ["", f"[{name}]", dump_toml(v, name).strip("\n")]
+    return "\n".join(lines).strip("\n") + "\n"
+
+
+def save_user_config(home: Path, updates: dict) -> dict:
+    """Merge updates into config.toml, keep a backup, return the new merged config."""
+    path = home / "config.toml"
+    user = tomllib.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+    user = _merge(user, updates)
+    body = ("# Saved from the dashboard. Every option is explained in config.example.toml in the project.\n\n"
+            + dump_toml(user))
+    tomllib.loads(body)  # never write a file that would not load
+    if path.exists():
+        path.replace(home / "config.backup.toml")
+    path.write_text(body, encoding="utf-8")
+    return _merge(DEFAULTS, user)
+
+
+def save_secrets(home: Path, secrets: dict) -> None:
+    """Set keys in .env, keeping every other line. Empty values are ignored (keep the old key)."""
+    secrets = {k: v.strip() for k, v in secrets.items() if v and v.strip()}
+    if not secrets:
+        return
+    for v in secrets.values():
+        if "\n" in v or "\r" in v:
+            raise ValueError("A key cannot contain a line break.")
+    path = home / ".env"
+    lines = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    left = dict(secrets)
+    for i, ln in enumerate(lines):
+        name = ln.split("=", 1)[0].strip()
+        if "=" in ln and not ln.lstrip().startswith("#") and name in left:
+            lines[i] = f"{name}={left.pop(name)}"
+    lines += [f"{k}={v}" for k, v in left.items()]
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    os.environ.update(secrets)

stellenpilot/db.py

@@ -0,0 +1,166 @@
+"""SQLite storage for jobs and runs. One file, no server."""
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS jobs (
+  id TEXT PRIMARY KEY,
+  source TEXT NOT NULL,
+  title TEXT NOT NULL,
+  company TEXT NOT NULL DEFAULT '',
+  location TEXT NOT NULL DEFAULT '',
+  remote INTEGER NOT NULL DEFAULT 0,
+  url TEXT NOT NULL DEFAULT '',
+  description TEXT NOT NULL DEFAULT '',
+  posted_at TEXT,
+  found_at TEXT NOT NULL,
+  job_type TEXT NOT NULL DEFAULT '',
+  lang TEXT NOT NULL DEFAULT '',
+  match INTEGER,
+  fit TEXT NOT NULL DEFAULT '',
+  why TEXT NOT NULL DEFAULT '',
+  gaps TEXT NOT NULL DEFAULT '',
+  gap_tags TEXT NOT NULL DEFAULT '[]',
+  status TEXT NOT NULL DEFAULT 'new',
+  status_source TEXT NOT NULL DEFAULT 'run',
+  status_updated_at TEXT,
+  status_note TEXT NOT NULL DEFAULT '',
+  folder TEXT NOT NULL DEFAULT '',
+  closed INTEGER NOT NULL DEFAULT 0,
+  closed_at TEXT,
+  interview_at TEXT,
+  prep TEXT NOT NULL DEFAULT '',
+  rating INTEGER,
+  notes TEXT NOT NULL DEFAULT '',
+  dedupe_key TEXT NOT NULL DEFAULT '',
+  german_level TEXT NOT NULL DEFAULT '',
+  summary_en TEXT NOT NULL DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS jobs_dedupe ON jobs(dedupe_key);
+CREATE TABLE IF NOT EXISTS runs (
+  date TEXT PRIMARY KEY,
+  found INTEGER NOT NULL DEFAULT 0,
+  added INTEGER NOT NULL DEFAULT 0,
+  shortlisted INTEGER NOT NULL DEFAULT 0,
+  docs_made INTEGER NOT NULL DEFAULT 0,
+  gmail_updates INTEGER NOT NULL DEFAULT 0,
+  notes TEXT NOT NULL DEFAULT '',
+  stage TEXT NOT NULL DEFAULT 'done',
+  stage_at TEXT,
+  stage_note TEXT NOT NULL DEFAULT ''
+);
+"""
+
+STATUSES = ("new", "ready", "applied", "interview", "offer", "rejected", "skipped")
+# Fields the user owns. The pipeline never overwrites them.
+USER_FIELDS = ("rating", "notes")
+EDITABLE = {"status", "status_note", "rating", "notes", "closed", "interview_at", "prep", "folder"}
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def today() -> str:
+    return datetime.now().date().isoformat()
+
+
+class DB:
+    def __init__(self, path: Path | str):
+        self.conn = sqlite3.connect(str(path), check_same_thread=False, timeout=30)
+        self.conn.row_factory = sqlite3.Row
+        self.conn.executescript(SCHEMA)
+        self._migrate()
+
+    def _migrate(self) -> None:
+        """Add columns introduced after a user's database was created."""
+        have = {r[1] for r in self.conn.execute("PRAGMA table_info(jobs)")}
+        for col in ("german_level", "summary_en"):
+            if col not in have:
+                self.conn.execute(f"ALTER TABLE jobs ADD COLUMN {col} TEXT NOT NULL DEFAULT ''")
+        self.conn.commit()
+
+    # ---------- jobs ----------
+    def job_ids(self) -> set[str]:
+        return {r[0] for r in self.conn.execute("SELECT id FROM jobs")}
+
+    def dedupe_keys(self) -> set[str]:
+        return {r[0] for r in self.conn.execute("SELECT dedupe_key FROM jobs") if r[0]}
+
+    def insert_job(self, job: dict) -> bool:
+        """Insert a new job. Returns False if the id already exists."""
+        row = {
+            "found_at": today(), "status": "new", "status_source": "run",
+            "status_updated_at": now(), **job,
+        }
+        row["gap_tags"] = json.dumps(row.get("gap_tags") or [])
+        row["remote"] = int(bool(row.get("remote")))
+        cols = [c for c in row if c in self._columns()]
+        sql = f"INSERT OR IGNORE INTO jobs ({','.join(cols)}) VALUES ({','.join('?' * len(cols))})"
+        cur = self.conn.execute(sql, [row[c] for c in cols])
+        self.conn.commit()
+        return cur.rowcount == 1
+
+    def update_job(self, job_id: str, fields: dict, *, by_user: bool = False) -> None:
+        if not by_user:
+            fields = {k: v for k, v in fields.items() if k not in USER_FIELDS}
+        if "gap_tags" in fields:
+            fields["gap_tags"] = json.dumps(fields["gap_tags"])
+        cols = [c for c in fields if c in self._columns() and c != "id"]
+        if not cols:
+            return
+        sql = f"UPDATE jobs SET {', '.join(f'{c} = ?' for c in cols)} WHERE id = ?"
+        self.conn.execute(sql, [fields[c] for c in cols] + [job_id])
+        self.conn.commit()
+
+    def mark_ready(self, job_id: str, folder: str, note: str) -> None:
+        """Store the folder; move to 'ready' only if the user has not changed the status meanwhile."""
+        self.conn.execute("UPDATE jobs SET folder = ? WHERE id = ?", (folder, job_id))
+        self.conn.execute("UPDATE jobs SET status = 'ready', status_source = 'run', status_updated_at = ?, "
+                          "status_note = ? WHERE id = ? AND status = 'new'", (now(), note, job_id))
+        self.conn.commit()
+
+    def set_status(self, job_id: str, status: str, *, source: str, note: str = "") -> None:
+        if status not in STATUSES:
+            raise ValueError(f"unknown status {status}")
+        self.update_job(job_id, {"status": status, "status_source": source,
+                                 "status_updated_at": now(), "status_note": note}, by_user=True)
+
+    def jobs(self, where: str = "1=1", params: tuple = ()) -> list[dict]:
+        rows = self.conn.execute(f"SELECT * FROM jobs WHERE {where} ORDER BY match DESC NULLS LAST, found_at DESC", params)
+        out = []
+        for r in rows:
+            d = dict(r)
+            d["gap_tags"] = json.loads(d["gap_tags"] or "[]")
+            d["remote"] = bool(d["remote"])
+            d["closed"] = bool(d["closed"])
+            out.append(d)
+        return out
+
+    def job(self, job_id: str) -> dict | None:
+        found = self.jobs("id = ?", (job_id,))
+        return found[0] if found else None
+
+    def _columns(self) -> set[str]:
+        if not hasattr(self, "_cols"):
+            self._cols = {r[1] for r in self.conn.execute("PRAGMA table_info(jobs)")}
+        return self._cols
+
+    # ---------- runs ----------
+    def run_update(self, date: str, **fields) -> None:
+        self.conn.execute("INSERT OR IGNORE INTO runs (date) VALUES (?)", (date,))
+        if fields:
+            cols = ", ".join(f"{k} = ?" for k in fields)
+            self.conn.execute(f"UPDATE runs SET {cols} WHERE date = ?", [*fields.values(), date])
+        self.conn.commit()
+
+    def stage(self, stage: str, note: str = "") -> None:
+        """Live progress for the dashboard's office scene."""
+        self.run_update(today(), stage=stage, stage_at=now(), stage_note=note)
+
+    def runs(self) -> list[dict]:
+        return [dict(r) for r in self.conn.execute("SELECT * FROM runs ORDER BY date DESC")]

stellenpilot/demo.py

@@ -0,0 +1,54 @@
+"""Fictional sample data so anyone can try the dashboard without keys or network."""
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+
+from .db import DB, today
+from .text import dedupe_key
+
+D = date.today()
+
+
+def _iso(days_ago: int) -> str:
+    return (D - timedelta(days=days_ago)).isoformat()
+
+
+SAMPLES = [
+    dict(id="demo-1", source="Bundesagentur für Arbeit", title="Working Student Data Engineering", company="Nordlicht Energy GmbH",
+         location="Essen, Nordrhein Westfalen", job_type="Werkstudent", match=86, fit="Strong", lang="English",
+         why="Python, SQL and AWS pipelines match your project work closely.", gaps="No Snowflake yet.",
+         gap_tags=["Snowflake"], status="ready", folder="", url="https://example.com/jobs/1"),
+    dict(id="demo-2", source="Arbeitnow", title="Werkstudent Data Analytics", company="Rhein Mobility AG",
+         location="Remote, Düsseldorf", remote=True, job_type="Werkstudent", match=78, fit="Strong", lang="English",
+         why="Remote. Power BI and SQL reporting are the core of the role.", gaps="Asks for dbt.",
+         gap_tags=["dbt"], status="new", url="https://example.com/jobs/2"),
+    dict(id="demo-3", source="Adzuna", title="Junior Data Engineer", company="Ruhr Logistics SE",
+         location="Dortmund", job_type="Full time", match=74, fit="Possible", lang="English",
+         why="Airflow and Docker experience fits their batch pipelines.", gaps="Kafka and Terraform are new to you.",
+         gap_tags=["Kafka", "Terraform"], status="applied", status_source="manual", url="https://example.com/jobs/3"),
+    dict(id="demo-4", source="TheirStack", title="Working Student BI", company="Kölner Retail Tech",
+         location="Köln", job_type="Werkstudent", match=69, fit="Possible", lang="English",
+         why="Dashboard work in Power BI.", gaps="Retail domain and dbt.", gap_tags=["dbt"],
+         status="interview", interview_at=(datetime.now(timezone.utc) + timedelta(days=4)).replace(hour=8, minute=0, microsecond=0).isoformat(),
+         prep="## About Kölner Retail Tech\nA fictional company used for the demo.\n## Likely questions\n- Walk us through a pipeline you built\n- How do you check data quality?\n## Questions to ask them\n- What does the BI stack look like?",
+         url="https://example.com/jobs/4"),
+    dict(id="demo-5", source="Bundesagentur für Arbeit", title="Werkstudent Datenmanagement", company="Westfalen Stadtwerke",
+         location="Bochum", job_type="Werkstudent", match=58, fit="Stretch", lang="German needed",
+         why="Data cleaning in SAP.", gaps="Asks for fluent German.", gap_tags=["German", "SAP"],
+         status="skipped", status_note="Ad asks for fluent German", url="https://example.com/jobs/5"),
+    dict(id="demo-6", source="Arbeitnow", title="Data Analyst Intern (paid)", company="Spree Insights",
+         location="Remote, Berlin", remote=True, job_type="", match=64, fit="Possible", lang="English",
+         why="Remote. SQL and Python analysis.", gaps="dbt and Looker.", gap_tags=["dbt", "Looker"],
+         status="rejected", status_source="gmail", status_note="Rejection email", url="https://example.com/jobs/6"),
+]
+
+
+def load_demo(settings) -> int:
+    db = DB(settings.db_path)
+    for i, job in enumerate(SAMPLES):
+        job = {**job, "found_at": _iso(i % 3), "posted_at": _iso(i % 3 + 1),
+               "dedupe_key": dedupe_key(job["company"], job["title"])}
+        db.insert_job(job)
+    db.run_update(today(), found=42, added=6, shortlisted=3, docs_made=3, gmail_updates=1,
+                  notes="Demo data", stage="done")
+    return len(SAMPLES)