offerprinter 0.2.0__py3-none-any.whl

offerprinter/services/tracker.py

@@ -0,0 +1,210 @@
+"""A local record of every application you have printed.
+
+Job hunting is a long, demoralising process with no scoreboard. This module is
+the scoreboard. Every run appends a row to a plain JSON file in
+``~/.offerprinter/applications.json`` — no server, no account, no sync, just a
+file you own and can delete, grep, or check into your own private repo.
+
+It powers three things:
+  * ``offerprinter list``   — everything you have applied for
+  * ``offerprinter stats``  — totals, spend, average fit, outcomes
+  * achievements            — the small, silly nudges that keep you going
+
+Nothing here ever leaves your machine.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+#: Where applications are recorded. Override with OFFERPRINTER_HOME.
+DEFAULT_HOME = Path.home() / ".offerprinter"
+
+#: Valid values for a record's `status` field, in pipeline order.
+STATUSES = ("printed", "applied", "screening", "interview", "offer", "rejected")
+
+
+class ApplicationRecord(BaseModel):
+    """One printed application package."""
+
+    slug: str
+    company: str
+    role: str
+    printed_at: str  # ISO-8601 UTC
+    provider: str = ""
+    model: str = ""
+    fit_score: int | None = None
+    fit_band: str = ""
+    cost_usd: float = 0.0
+    total_tokens: int = 0
+    output_dir: str = ""
+    status: str = "printed"
+    notes: str = ""
+
+    @property
+    def printed_date(self) -> str:
+        return self.printed_at[:10]
+
+
+class Tracker:
+    """Read/write access to the local application history."""
+
+    def __init__(self, home: Path | None = None) -> None:
+        self.home = Path(home or os.environ.get("OFFERPRINTER_HOME") or DEFAULT_HOME)
+        self.path = self.home / "applications.json"
+
+    # -- persistence --------------------------------------------------------
+
+    def load(self) -> list[ApplicationRecord]:
+        """Return every record, oldest first. A corrupt file is never fatal."""
+        if not self.path.is_file():
+            return []
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return []
+        records = []
+        for item in raw if isinstance(raw, list) else []:
+            try:
+                records.append(ApplicationRecord(**item))
+            except (TypeError, ValueError):
+                continue  # skip a bad row rather than losing the whole history
+        return records
+
+    def save(self, records: list[ApplicationRecord]) -> None:
+        self.home.mkdir(parents=True, exist_ok=True)
+        payload = [r.model_dump() for r in records]
+        self.path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+    # -- mutations ----------------------------------------------------------
+
+    def record(self, record: ApplicationRecord) -> list[str]:
+        """Append a run and return any achievements newly unlocked by it."""
+        records = self.load()
+        before = unlocked(records)
+        records.append(record)
+        self.save(records)
+        return sorted(unlocked(records) - before)
+
+    def set_status(self, slug: str, status: str) -> ApplicationRecord | None:
+        """Update the most recent record for a slug. Returns it, or None."""
+        if status not in STATUSES:
+            raise ValueError(f"Unknown status '{status}'. Use one of: {', '.join(STATUSES)}")
+        records = self.load()
+        for record in reversed(records):
+            if record.slug == slug:
+                record.status = status
+                self.save(records)
+                return record
+        return None
+
+
+class Stats(BaseModel):
+    """Aggregate view of the whole history."""
+
+    total: int = 0
+    companies: int = 0
+    average_fit: float = 0.0
+    best_fit: int = 0
+    best_fit_role: str = ""
+    total_cost_usd: float = 0.0
+    total_tokens: int = 0
+    by_status: dict[str, int] = Field(default_factory=dict)
+    first_printed: str = ""
+    last_printed: str = ""
+
+
+def summarise(records: list[ApplicationRecord]) -> Stats:
+    """Roll a list of records up into headline numbers."""
+    if not records:
+        return Stats()
+
+    scored = [r for r in records if r.fit_score is not None]
+    best = max(scored, key=lambda r: r.fit_score or 0, default=None)
+    by_status: dict[str, int] = {}
+    for record in records:
+        by_status[record.status] = by_status.get(record.status, 0) + 1
+
+    return Stats(
+        total=len(records),
+        companies=len({r.company.lower() for r in records if r.company}),
+        average_fit=round(sum(r.fit_score or 0 for r in scored) / len(scored), 1)
+        if scored
+        else 0.0,
+        best_fit=best.fit_score if best and best.fit_score is not None else 0,
+        best_fit_role=f"{best.role} at {best.company}" if best else "",
+        total_cost_usd=round(sum(r.cost_usd for r in records), 4),
+        total_tokens=sum(r.total_tokens for r in records),
+        by_status=by_status,
+        first_printed=min(r.printed_at for r in records)[:10],
+        last_printed=max(r.printed_at for r in records)[:10],
+    )
+
+
+# --- achievements ------------------------------------------------------------
+#
+# Deliberately small and a bit silly. Job hunting is a grind with almost no
+# feedback loop; a line that says "that's ten applications this month" is a
+# cheap way to make the grind visible.
+
+#: id -> (emoji, title, description, predicate over the full record list)
+ACHIEVEMENTS: dict[str, tuple[str, str, str]] = {
+    "first_print": ("🖨", "First Print", "You printed your first application package."),
+    "five_printed": ("🖐", "Warmed Up", "Five applications printed."),
+    "ten_printed": ("🔟", "Double Digits", "Ten applications printed."),
+    "fifty_printed": ("💯", "Machine", "Fifty applications printed."),
+    "strong_fit": ("🎯", "Bullseye", "Scored 85+ on a role — apply to that one today."),
+    "honest_stretch": ("🧗", "Honest Stretch", "Applied to a role you scored under 50 on. Brave."),
+    "five_companies": ("🌍", "Spread Bet", "Applications to five different companies."),
+    "thrifty": ("🪙", "Thrifty", "Ten packages printed for under one dollar total."),
+    "local_hero": ("🏠", "Local Hero", "Printed a package on a locally-hosted model."),
+    "interview": ("🤝", "In The Room", "Marked an application as reaching interview."),
+    "offer": ("🏆", "Offer Printed", "Marked an application as an offer. Congratulations."),
+}
+
+
+def unlocked(records: list[ApplicationRecord]) -> set[str]:
+    """Return the ids of every achievement earned by this history."""
+    if not records:
+        return set()
+
+    earned: set[str] = {"first_print"}
+    count = len(records)
+    if count >= 5:
+        earned.add("five_printed")
+    if count >= 10:
+        earned.add("ten_printed")
+    if count >= 50:
+        earned.add("fifty_printed")
+    if len({r.company.lower() for r in records if r.company}) >= 5:
+        earned.add("five_companies")
+    if any((r.fit_score or 0) >= 85 for r in records):
+        earned.add("strong_fit")
+    if any(r.fit_score is not None and r.fit_score < 50 for r in records):
+        earned.add("honest_stretch")
+    if count >= 10 and sum(r.cost_usd for r in records) < 1.0:
+        earned.add("thrifty")
+    if any(r.provider == "ollama" for r in records):
+        earned.add("local_hero")
+    statuses = {r.status for r in records}
+    if statuses & {"interview", "offer"}:
+        earned.add("interview")
+    if "offer" in statuses:
+        earned.add("offer")
+    return earned
+
+
+def describe(achievement_id: str) -> str:
+    """One-line human description of an achievement, for the CLI."""
+    emoji, title, description = ACHIEVEMENTS.get(achievement_id, ("🎖", achievement_id, ""))
+    return f"{emoji}  {title} — {description}"
+
+
+def utc_now() -> str:
+    """Current time as an ISO-8601 UTC string (stable, sortable, timezone-safe)."""
+    return datetime.now(UTC).isoformat(timespec="seconds")

offerprinter/services/writer.py

@@ -0,0 +1,142 @@
+"""Write a generated package to disk as .md, .docx and/or .pdf, plus a combined file.
+
+Kept separate from generation so the format concerns live in one place. The
+.docx writer does a lightweight Markdown-to-Word rendering (headings, bullets,
+bold) — enough to produce clean, ATS-friendly documents without a heavy
+dependency. The .pdf writer is our own (see `pdf_writer.py`), for the same
+reason: recruiters ask for PDFs and ATS parsers want plain Helvetica text.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from offerprinter.models.schemas import ApplicationPackage, Artifact
+from offerprinter.services.pdf_writer import write_pdf
+
+#: Output formats `write_package` knows how to produce.
+SUPPORTED_FORMATS = ("md", "docx", "pdf")
+
+
+def _write_md(artifact: Artifact, folder: Path) -> Path:
+    path = folder / f"{artifact.filename}.md"
+    path.write_text(artifact.content.rstrip() + "\n", encoding="utf-8")
+    return path
+
+
+def _write_pdf(artifact: Artifact, folder: Path) -> Path:
+    return write_pdf(artifact.content, folder / f"{artifact.filename}.pdf")
+
+
+_BOLD_RE = re.compile(r"\*\*(.+?)\*\*")
+
+
+def _add_markdown_runs(paragraph, text: str) -> None:
+    """Add text to a python-docx paragraph, honouring **bold** spans."""
+    pos = 0
+    for m in _BOLD_RE.finditer(text):
+        if m.start() > pos:
+            paragraph.add_run(text[pos : m.start()])
+        run = paragraph.add_run(m.group(1))
+        run.bold = True
+        pos = m.end()
+    if pos < len(text):
+        paragraph.add_run(text[pos:])
+
+
+def _write_docx(artifact: Artifact, folder: Path) -> Path:
+    from docx import Document
+
+    doc = Document()
+    for raw_line in artifact.content.splitlines():
+        line = raw_line.rstrip()
+        if not line:
+            doc.add_paragraph()
+            continue
+        if line.startswith("### "):
+            doc.add_heading(line[4:], level=3)
+        elif line.startswith("## "):
+            doc.add_heading(line[3:], level=2)
+        elif line.startswith("# "):
+            doc.add_heading(line[2:], level=1)
+        elif line.lstrip().startswith(("- ", "* ")):
+            stripped = line.lstrip()[2:]
+            p = doc.add_paragraph(style="List Bullet")
+            _add_markdown_runs(p, stripped)
+        elif re.match(r"^\d+\.\s", line.lstrip()):
+            stripped = re.sub(r"^\d+\.\s", "", line.lstrip())
+            p = doc.add_paragraph(style="List Number")
+            _add_markdown_runs(p, stripped)
+        else:
+            p = doc.add_paragraph()
+            _add_markdown_runs(p, line)
+
+    path = folder / f"{artifact.filename}.docx"
+    doc.save(str(path))
+    return path
+
+
+def _combined_markdown(package: ApplicationPackage) -> str:
+    parts = [f"# Application Package — {package.role} at {package.company}\n"]
+    parts.append(
+        "> Generated by OfferPrinter. Every statement is drawn from your real CV — "
+        "nothing here is fabricated. Review before sending.\n"
+    )
+    if package.fit:
+        parts.append(f"\n**Fit score: {package.fit.score}/100 — {package.fit.band}.** ")
+        parts.append(f"{package.fit.verdict}\n")
+    for artifact in package.artifacts:
+        parts.append("\n---\n")
+        parts.append(artifact.content.rstrip())
+    return "\n".join(parts) + "\n"
+
+
+def write_package(
+    package: ApplicationPackage, output_dir: str, formats: list[str]
+) -> dict[str, list[Path]]:
+    """Write every artifact in the requested formats. Returns paths written.
+
+    Returns a dict mapping artifact key (plus "_combined") to the list of files
+    written for it.
+    """
+    folder = Path(output_dir) / package.slug
+    folder.mkdir(parents=True, exist_ok=True)
+
+    def write_all(artifact: Artifact) -> list[Path]:
+        paths: list[Path] = []
+        if "md" in formats:
+            paths.append(_write_md(artifact, folder))
+        if "docx" in formats:
+            paths.append(_write_docx(artifact, folder))
+        if "pdf" in formats:
+            paths.append(_write_pdf(artifact, folder))
+        return paths
+
+    written: dict[str, list[Path]] = {}
+    for artifact in package.artifacts:
+        written[artifact.key] = write_all(artifact)
+
+    # The fit score is structured data rather than a generated document, so it
+    # gets rendered here rather than coming back from the model as Markdown.
+    if package.fit:
+        written["fit_score"] = write_all(
+            Artifact(
+                key="fit_score",
+                title="Fit Score",
+                filename="fit-score",
+                content=package.fit.as_markdown(),
+            )
+        )
+
+    # Combined package — a single file with everything.
+    written["_combined"] = write_all(
+        Artifact(
+            key="_combined",
+            title="Full Package",
+            filename="full-package",
+            content=_combined_markdown(package),
+        )
+    )
+
+    return written

offerprinter/ui/__init__.py

@@ -0,0 +1,9 @@
+"""Terminal presentation helpers.
+
+Kept apart from the pipeline so that nothing in the core depends on how (or
+whether) progress is drawn. The CLI is the only consumer.
+"""
+
+from offerprinter.ui.printer import PrinterAnimation, render_fit_bar
+
+__all__ = ["PrinterAnimation", "render_fit_bar"]

offerprinter/ui/printer.py

@@ -0,0 +1,165 @@
+"""The printer animation — an ASCII dot-matrix printer feeding paper.
+
+Purely cosmetic, and that is the point: a generation run is 30-60 seconds of
+nothing, and watching a little printer chug through five documents is far nicer
+than watching a spinner. It degrades safely — if the output is not a terminal
+(piped, redirected, CI, or `--no-animation`), it prints plain status lines
+instead and nothing is lost.
+"""
+
+from __future__ import annotations
+
+import itertools
+import os
+import sys
+import threading
+import time
+
+from rich.console import Console, Group
+from rich.live import Live
+from rich.text import Text
+
+#: The printer body. `{roll}` animates the paper feed rollers.
+_PRINTER = r"""     ╔═══════════════════════════════════╗
+     ║  ● OfferPrinter        {status}  ║
+     ╟───────────────────────────────────╢
+     ║ {roll} ║
+     ╚═══════════════════════════════════╝"""
+
+#: Frames for the paper-feed rollers, cycled while a document is generating.
+_ROLLERS = [
+    "▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚▚",
+    "▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞▞",
+]
+
+#: How a sheet of paper looks as it emerges, one line at a time.
+_SHEET_TOP = "      ┌─────────────────────────────────┐"
+_SHEET_ROW = "      │ {line:<31} │"
+_SHEET_BOTTOM = "      └─────────────────────────────────┘"
+
+_STATUS_WIDTH = 10
+
+
+def _supports_animation(console: Console) -> bool:
+    """Animate only when there's a human watching a real terminal."""
+    if os.environ.get("OFFERPRINTER_NO_ANIM"):
+        return False
+    if os.environ.get("CI"):
+        return False
+    return console.is_terminal and not console.is_jupyter
+
+
+class PrinterAnimation:
+    """Draws the printer while artifacts generate, feeding a sheet per artifact.
+
+    Use as a context manager:
+
+        with PrinterAnimation(console, total=5) as anim:
+            anim.status("Reading the job description")
+            anim.sheet("Tailored CV")
+    """
+
+    def __init__(self, console: Console, total: int, enabled: bool = True) -> None:
+        self.console = console
+        self.total = max(total, 1)
+        self.enabled = enabled and _supports_animation(console)
+        self.done = 0
+        self._status = "warming up"
+        self._sheets: list[str] = []
+        self._live: Live | None = None
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._frames = itertools.cycle(_ROLLERS)
+        self._lock = threading.Lock()
+
+    # -- rendering ----------------------------------------------------------
+
+    def _render(self) -> Group:
+        with self._lock:
+            status = self._status[:_STATUS_WIDTH].ljust(_STATUS_WIDTH)
+            sheets = list(self._sheets)
+
+        body = Text(
+            _PRINTER.format(status=status, roll=next(self._frames)),
+            style="bright_cyan",
+        )
+        lines: list[Text | str] = [body]
+        if sheets:
+            lines.append(Text(_SHEET_TOP, style="grey58"))
+            for name in sheets:
+                lines.append(Text(_SHEET_ROW.format(line=f"✓ {name}"), style="green"))
+            lines.append(Text(_SHEET_BOTTOM, style="grey58"))
+        return Group(*lines)
+
+    def _spin(self) -> None:
+        while not self._stop.wait(0.18):
+            if self._live is not None:
+                self._live.update(self._render())
+
+    # -- public API ---------------------------------------------------------
+
+    def status(self, message: str) -> None:
+        """Update the little status readout on the printer's front panel."""
+        with self._lock:
+            self._status = message
+        if not self.enabled:
+            self.console.print(f"[cyan]…[/cyan] {message}")
+        elif self._live is not None:
+            self._live.update(self._render())
+
+    def sheet(self, title: str) -> None:
+        """Feed one finished sheet out of the printer."""
+        self.done += 1
+        with self._lock:
+            self._sheets.append(title)
+            self._status = f"{self.done}/{self.total}"
+        if not self.enabled:
+            self.console.print(f"  [green]✓[/green] {title}")
+        elif self._live is not None:
+            self._live.update(self._render())
+
+    def __enter__(self) -> PrinterAnimation:
+        if self.enabled:
+            self._live = Live(
+                self._render(),
+                console=self.console,
+                refresh_per_second=12,
+                transient=False,
+            )
+            self._live.__enter__()
+            self._thread = threading.Thread(target=self._spin, daemon=True)
+            self._thread.start()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)
+        if self._live is not None:
+            with self._lock:
+                self._status = "done".ljust(_STATUS_WIDTH)
+            self._live.update(self._render())
+            self._live.__exit__(*exc_info)  # type: ignore[arg-type]
+            self._live = None
+
+
+def render_fit_bar(score: int, width: int = 24) -> Text:
+    """A coloured 0-100 bar for the fit score, for the end-of-run summary."""
+    filled = round(score / 100 * width)
+    colour = "green" if score >= 70 else "yellow" if score >= 50 else "red"
+    bar = Text()
+    bar.append("█" * filled, style=colour)
+    bar.append("░" * (width - filled), style="grey37")
+    return bar
+
+
+def type_out(console: Console, text: str, delay: float = 0.012, style: str = "") -> None:
+    """Print text a character at a time, for the one line that deserves it."""
+    if not _supports_animation(console) or delay <= 0:
+        console.print(text, style=style)
+        return
+    for char in text:
+        console.print(char, end="", style=style, highlight=False, markup=False)
+        sys.stdout.flush()
+        time.sleep(delay)
+    console.print()