finch-cli 0.1.1__py3-none-any.whl

finch_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Finch CLI - tailor your resume to any job posting from your terminal."""
+
+__version__ = "0.1.1"

finch_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

finch_cli/_data/base_resume.md

@@ -0,0 +1,32 @@
+# Jordan Park
+
+jordan@example.com · linkedin.com/in/jordanpark · github.com/jordanpark · College Station, TX
+
+## Education
+
+**Texas A&M University**, BS Computer Science, May 2026
+- GPA: 3.84 / 4.00
+- Coursework: Machine Learning, Distributed Systems, Linear Algebra, Operating Systems, Databases
+
+## Experience
+
+**Engineering Intern, Nimbus Labs** - May 2025 to Aug 2025
+- Shipped a distributed training pipeline that cut iteration time from 4 hours to 38 minutes
+- Wrote a 200-test evaluation harness that flagged 3 silent regressions in the production model
+- Owned the model rollout to staging across 14 GPUs with zero-downtime cutover
+
+**SWE Intern, Stripe (Issuing)** - May 2024 to Aug 2024
+- Implemented an idempotency layer for the card-issuing API, cut duplicate-charge incidents 92 percent
+- Reviewed 28 PRs across three teams and wrote the team's first incident-runbook template
+
+## Projects
+
+**Tiny GPT trainer** - PyTorch, CUDA, wandb
+From-scratch GPT-2 small implementation with FlashAttention, fully open-sourced, 1.2k GitHub stars.
+
+**Climate dashboard** - React, D3, Tailwind
+Interactive visualization of NOAA temperature anomalies for 8,000 monitoring stations, deployed to Cloudflare Pages.
+
+## Skills
+
+Python, PyTorch, CUDA, distributed training, Go, Rust, React, TypeScript, PostgreSQL, Redis, Docker, Linux

finch_cli/_data/job_post.txt

@@ -0,0 +1,25 @@
+Software Engineer Intern, Distributed Systems
+Stripe - Remote (US / Canada)
+
+About the team
+
+The Distributed Systems team at Stripe owns the infrastructure that moves money across our platform. We run multi-region postgres and kafka clusters, build the storage primitives that every product team uses, and keep latency under 50ms p99 across continents. You will be joining a focused team where every change you ship affects every Stripe API call.
+
+What you will do
+
+- Design and implement features in core distributed systems written in Go and Rust
+- Improve the reliability and observability of our storage layer (postgres, kafka, redis)
+- Reduce p99 latency for high-throughput services through profiling, indexing, and caching changes
+- Write the runbooks and instrumentation that let your team debug production issues without paging the original author
+- Collaborate with senior engineers on incident response and write postmortems
+
+What we look for
+
+- Currently pursuing a BS, MS, or PhD in CS, EE, or a related field with strong systems coursework
+- Proficient in at least one of Go, Rust, Python, or C++
+- Experience with concurrency primitives, networking, or distributed systems through coursework or projects
+- Comfortable reading large unfamiliar codebases and shipping non-trivial PRs
+- Bonus: open source contributions, prior internship at a high-traffic SaaS, exposure to postgres internals, kafka, or eBPF
+
+Compensation
+$58 to $72 per hour, depending on year and location.

finch_cli/cli.py

@@ -0,0 +1,155 @@
+"""Finch CLI - entry point."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from . import __version__
+from .fetch import FetchError, fetch_job
+from .output import write_or_print
+from .tailor import DEFAULT_BASE_URL, DEFAULT_MODEL, TailorError, tailor_resume
+
+console = Console()
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="finch")
+def main() -> None:
+    """Finch - tailor your resume to any job posting from your terminal.
+
+    Run `finch tailor --help` or `finch ui --help` to get started, or visit
+    https://applyfinch.com for the full web product (auto-apply included,
+    free during beta).
+    """
+
+
+@main.command()
+@click.option(
+    "--resume",
+    "-r",
+    "resume_path",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    help="Path to your base resume (markdown or plain text).",
+)
+@click.option(
+    "--job",
+    "-j",
+    "job_url",
+    default=None,
+    help="URL of the job posting.",
+)
+@click.option(
+    "--job-file",
+    "job_file",
+    default=None,
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    help="Path to a text file containing the job posting (use if --job won't extract).",
+)
+@click.option(
+    "--out",
+    "-o",
+    "out_path",
+    default=None,
+    type=click.Path(dir_okay=False, writable=True),
+    help="Write the tailored resume to this path. If omitted, prints to terminal.",
+)
+@click.option(
+    "--model",
+    default=DEFAULT_MODEL,
+    show_default=True,
+    help="Model name. Any chat model on the configured base-url.",
+)
+@click.option(
+    "--api-key",
+    default=None,
+    help="API key. Defaults to $DEEPSEEK_API_KEY, $FINCH_API_KEY, or $OPENAI_API_KEY.",
+)
+@click.option(
+    "--base-url",
+    default=None,
+    show_default=False,
+    help=f"OpenAI-compatible base URL. Default: {DEFAULT_BASE_URL} (DeepSeek). "
+    "Works with OpenAI, Together, Groq, Fireworks, anything API-compatible.",
+)
+def tailor(
+    resume_path: str,
+    job_url: str | None,
+    job_file: str | None,
+    out_path: str | None,
+    model: str,
+    api_key: str | None,
+    base_url: str | None,
+) -> None:
+    """Tailor your resume to a specific job posting."""
+    if not job_url and not job_file:
+        console.print("[red]Error:[/red] provide either --job <url> or --job-file <path>.")
+        sys.exit(2)
+    if job_url and job_file:
+        console.print("[red]Error:[/red] use only one of --job or --job-file.")
+        sys.exit(2)
+
+    base_resume = Path(resume_path).read_text(encoding="utf-8")
+    if not base_resume.strip():
+        console.print(f"[red]Error:[/red] resume file {resume_path} is empty.")
+        sys.exit(2)
+
+    if job_file:
+        job_text = Path(job_file).read_text(encoding="utf-8")
+        console.print(f"[dim]Read job description from {job_file} ({len(job_text):,} chars).[/dim]")
+    else:
+        try:
+            with console.status(f"Fetching job posting from {job_url}...", spinner="dots"):
+                job_text = fetch_job(job_url)
+        except FetchError as e:
+            console.print(f"[red]Fetch failed:[/red] {e}")
+            sys.exit(1)
+        console.print(f"[dim]Fetched job posting ({len(job_text):,} chars).[/dim]")
+
+    if base_url and base_url != DEFAULT_BASE_URL:
+        console.print(
+            f"[yellow]warning:[/] sending your API key to {base_url}. "
+            f"only use --base-url for providers you trust."
+        )
+
+    try:
+        with console.status("Tailoring resume against the job...", spinner="dots"):
+            tailored = tailor_resume(
+                base_resume,
+                job_text,
+                model=model,
+                api_key=api_key,
+                base_url=base_url,
+            )
+    except TailorError as e:
+        console.print(f"[red]Tailoring failed:[/red] {e}")
+        sys.exit(1)
+
+    write_or_print(tailored, out_path)
+
+
+@main.command()
+@click.option(
+    "--demo",
+    is_flag=True,
+    help="Pre-load the bundled example resume and job posting on launch.",
+)
+@click.option(
+    "--model",
+    default=DEFAULT_MODEL,
+    show_default=True,
+    help="Model name. Any chat model on the configured base-url.",
+)
+def ui(demo: bool, model: str) -> None:
+    """Launch the Finch TUI - jobs / library / tailor in three tabs."""
+    from .tui import run as run_tui
+
+    run_tui(demo=demo, model=model)
+
+
+if __name__ == "__main__":
+    main()

finch_cli/fetch.py

@@ -0,0 +1,131 @@
+"""Fetch a job posting URL and extract the readable content.
+
+Defends against SSRF: only http/https schemes, refuses private / loopback /
+link-local / multicast / reserved IP ranges. The hostname is resolved with
+getaddrinfo so DNS-rebinding-style "evil.example -> 127.0.0.1" is caught at
+both the original URL and after each redirect hop.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from urllib.parse import urlparse
+
+import httpx
+import trafilatura
+
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_BYTES = 5 * 1024 * 1024  # 5 MB cap on fetched bodies
+DEFAULT_MAX_REDIRECTS = 5
+DEFAULT_UA = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) finch-cli/0.1 Safari/537.36"
+)
+
+
+class FetchError(RuntimeError):
+    """A fetch or extraction failure with a user-facing message."""
+
+
+def _check_url_safe(url: str) -> None:
+    """Raise FetchError if the URL points anywhere we refuse to fetch from.
+
+    - scheme must be http or https
+    - resolves the host; refuses private / loopback / link-local / multicast / reserved IPs
+      (blocks 127.0.0.1, ::1, 10/8, 172.16/12, 192.168/16, 169.254/16, etc.)
+    """
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise FetchError(
+            f"refusing scheme {parsed.scheme!r}: only http and https are allowed."
+        )
+    host = parsed.hostname
+    if not host:
+        raise FetchError(f"refusing url with no host: {url}")
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except socket.gaierror as e:
+        raise FetchError(f"could not resolve host {host}: {e}") from e
+    for info in infos:
+        addr = info[4][0]
+        try:
+            ip = ipaddress.ip_address(addr)
+        except ValueError:
+            continue
+        if (
+            ip.is_private
+            or ip.is_loopback
+            or ip.is_link_local
+            or ip.is_multicast
+            or ip.is_reserved
+            or ip.is_unspecified
+        ):
+            raise FetchError(
+                f"refusing to fetch internal/private host {host} ({addr}). "
+                f"if this is a public job page, paste the description into a file "
+                f"and use --job-file instead."
+            )
+
+
+def fetch_url(
+    url: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    max_bytes: int = DEFAULT_MAX_BYTES,
+    max_redirects: int = DEFAULT_MAX_REDIRECTS,
+) -> str:
+    """Fetch a URL and return raw HTML. SSRF-checked at every redirect hop."""
+    _check_url_safe(url)
+    headers = {
+        "User-Agent": DEFAULT_UA,
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.5",
+    }
+    current = url
+    try:
+        with httpx.Client(
+            timeout=timeout, follow_redirects=False, headers=headers
+        ) as client:
+            for _ in range(max_redirects + 1):
+                r = client.get(current)
+                if 300 <= r.status_code < 400 and r.headers.get("location"):
+                    next_url = str(httpx.URL(r.headers["location"], base=r.url))
+                    _check_url_safe(next_url)
+                    current = next_url
+                    continue
+                r.raise_for_status()
+                if len(r.content) > max_bytes:
+                    raise FetchError(
+                        f"response too large ({len(r.content):,} bytes; "
+                        f"limit is {max_bytes:,}). aborting."
+                    )
+                return r.text
+            raise FetchError(f"too many redirects (more than {max_redirects}).")
+    except httpx.HTTPStatusError as e:
+        raise FetchError(
+            f"job page returned HTTP {e.response.status_code}. "
+            f"it may be behind auth or geo-blocked. "
+            f"try saving the description to a file and use --job-file."
+        ) from e
+    except httpx.HTTPError as e:
+        raise FetchError(f"could not fetch job page: {e}") from e
+
+
+def extract_text(html: str) -> str:
+    """Extract the main readable text from a page."""
+    text = trafilatura.extract(
+        html, include_comments=False, include_tables=True, favor_recall=True
+    )
+    if not text or len(text.strip()) < 80:
+        raise FetchError(
+            "Could not extract readable content from the job page. "
+            "It probably requires JavaScript to render (Workday, Greenhouse iframe, etc.). "
+            "Paste the job description into a text file and pass it with --job-file instead."
+        )
+    return text.strip()
+
+
+def fetch_job(url: str) -> str:
+    """Convenience: fetch a URL and extract its readable text."""
+    return extract_text(fetch_url(url))

finch_cli/jobs.py

@@ -0,0 +1,166 @@
+"""Fetch the SimplifyJobs internship + new-grad lists.
+
+Same two sources Finch's job bank uses. Cached locally for fast TUI reloads.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+
+SOURCES: dict[str, str] = {
+    "intern": "https://raw.githubusercontent.com/SimplifyJobs/Summer2026-Internships/dev/.github/scripts/listings.json",
+    "newgrad": "https://raw.githubusercontent.com/SimplifyJobs/New-Grad-Positions/dev/.github/scripts/listings.json",
+}
+
+CACHE_DIR = (
+    Path(os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache"))) / "finch-cli"
+)
+CACHE_TTL_SECONDS = 6 * 60 * 60  # six hours
+MAX_FEED_BYTES = 25 * 1024 * 1024  # 25 MB safety cap on feed size
+
+
+@dataclass
+class Job:
+    id: str
+    source: str
+    company: str
+    title: str
+    locations: list[str]
+    url: str
+    terms: list[str]
+    sponsorship: str | None
+    active: bool
+    date_posted: int
+    date_updated: int
+    category: str | None
+    degrees: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, d: dict, source: str) -> "Job":
+        return cls(
+            id=str(d.get("id", "")),
+            source=source,
+            company=d.get("company_name") or "",
+            title=d.get("title") or "",
+            locations=list(d.get("locations") or []),
+            url=d.get("url") or "",
+            terms=list(d.get("terms") or []),
+            sponsorship=d.get("sponsorship"),
+            active=bool(d.get("active", False)),
+            date_posted=int(d.get("date_posted") or 0),
+            date_updated=int(d.get("date_updated") or 0),
+            category=d.get("category"),
+            degrees=list(d.get("degrees") or []),
+        )
+
+    def age_label(self) -> str:
+        if not self.date_posted:
+            return "?"
+        delta = datetime.now(timezone.utc).timestamp() - self.date_posted
+        days = int(delta // 86400)
+        if days < 1:
+            hours = int(delta // 3600)
+            return f"{max(hours, 0)}h"
+        if days < 30:
+            return f"{days}d"
+        months = days // 30
+        return f"{months}mo"
+
+    def loc_label(self) -> str:
+        if not self.locations:
+            return "-"
+        if len(self.locations) == 1:
+            return self.locations[0]
+        return f"{self.locations[0]} +{len(self.locations) - 1}"
+
+    def term_label(self) -> str:
+        return ", ".join(self.terms) if self.terms else "-"
+
+    def sponsorship_label(self) -> str:
+        s = (self.sponsorship or "").strip()
+        if not s:
+            return "?"
+        # Compact known buckets
+        sl = s.lower()
+        if "u.s. citizen" in sl or "us citizen" in sl:
+            return "US only"
+        if "offered" in sl:
+            return "sponsors"
+        if "no sponsorship" in sl or "does not offer" in sl:
+            return "no spon"
+        return s[:10]
+
+
+def _cache_path(source: str) -> Path:
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    return CACHE_DIR / f"{source}.json"
+
+
+def _is_fresh(p: Path) -> bool:
+    if not p.exists():
+        return False
+    age = datetime.now(timezone.utc).timestamp() - p.stat().st_mtime
+    return age < CACHE_TTL_SECONDS
+
+
+def load_jobs(*, force_refresh: bool = False) -> list[Job]:
+    """Return active jobs from both sources, sorted by date_posted desc."""
+    all_jobs: list[Job] = []
+    for source, url in SOURCES.items():
+        cache = _cache_path(source)
+        if force_refresh or not _is_fresh(cache):
+            with httpx.Client(timeout=30, follow_redirects=True) as client:
+                r = client.get(url, headers={"User-Agent": "finch-cli/0.1"})
+                r.raise_for_status()
+                if len(r.content) > MAX_FEED_BYTES:
+                    continue  # upstream feed too large; skip safely
+                cache.write_text(r.text, encoding="utf-8")
+        try:
+            data = json.loads(cache.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(data, list):
+            continue
+        for d in data:
+            if not isinstance(d, dict) or not d.get("id"):
+                continue
+            try:
+                all_jobs.append(Job.from_json(d, source))
+            except Exception:
+                # one malformed record shouldn't kill the whole feed
+                continue
+    active = [j for j in all_jobs if j.active]
+    active.sort(key=lambda j: j.date_posted, reverse=True)
+    return active
+
+
+def filter_jobs(
+    jobs: list[Job],
+    *,
+    query: str = "",
+    source: str | None = None,
+    term_substring: str | None = None,
+) -> list[Job]:
+    q = query.lower().strip()
+    out: list[Job] = []
+    for j in jobs:
+        if source and j.source != source:
+            continue
+        if term_substring:
+            ts = term_substring.lower()
+            if not any(ts in t.lower() for t in j.terms):
+                continue
+        if q:
+            blob = (
+                f"{j.title} {j.company} {' '.join(j.locations)} {j.category or ''}"
+            ).lower()
+            if q not in blob:
+                continue
+        out.append(j)
+    return out

finch_cli/output.py

@@ -0,0 +1,20 @@
+"""Output helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.markdown import Markdown
+
+
+def write_or_print(content: str, out_path: str | None) -> None:
+    console = Console()
+    if out_path:
+        Path(out_path).write_text(content, encoding="utf-8")
+        console.print(
+            f"[green]wrote[/green] {out_path}  ({len(content):,} chars, "
+            f"{len(content.splitlines()):,} lines)"
+        )
+    else:
+        console.print(Markdown(content))