jobhunter-cli 0.1.0__py3-none-any.whl

jobhunter/__main__.py

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

jobhunter/core/filters.py

@@ -0,0 +1,110 @@
+import datetime
+import re
+from functools import lru_cache
+
+from jobhunter.core.settings import settings
+from jobhunter.models import Job
+
+
+@lru_cache(maxsize=512)
+def _get_word_pattern(keyword: str) -> re.Pattern:
+  """Compiles and caches word boundary regex patterns for tech keywords."""
+  return re.compile(rf"(?<![a-z0-9]){re.escape(keyword.lower())}(?![a-z0-9])")
+
+
+def has_word(keyword: str, text: str) -> bool:
+  """Checks if a keyword exists in the text as a whole word, ignoring case."""
+  if not text or not keyword:
+    return False
+  return bool(_get_word_pattern(keyword).search(text.lower()))
+
+
+def is_valid_title(job: Job) -> bool:
+  """Checks if the job title passes the include/exclude filters."""
+  title = (job.title or "").lower()
+  filters = settings.filters
+
+  is_excluded = bool(filters.title_exclude and any(has_word(ex, title) for ex in filters.title_exclude))
+
+  is_included = not filters.title_include or any(has_word(inc, title) for inc in filters.title_include)
+
+  return is_included and not is_excluded
+
+
+def is_valid_company(job: Job) -> bool:
+  """Checks if the job company passes the exclude filters."""
+  company = (job.company or "").lower()
+  filters = settings.filters
+
+  is_excluded = bool(filters.company_exclude and any(has_word(ex, company) for ex in filters.company_exclude))
+
+  return not is_excluded
+
+
+def is_valid_location(job: Job) -> bool:
+  """Checks location filters, giving absolute priority to location_allow_terms."""
+  location = (job.location or "").lower()
+  filters = settings.filters
+
+  is_allowed = bool(filters.location_allow_terms and any(has_word(allow, location) for allow in filters.location_allow_terms))
+
+  is_excluded = bool(filters.location_exclude_terms and any(has_word(ex, location) for ex in filters.location_exclude_terms))
+
+  is_missing_required = bool(filters.location_require_terms and not any(has_word(req, location) for req in filters.location_require_terms))
+
+  return is_allowed or (not is_excluded and not is_missing_required)
+
+
+def is_job_remote(job: Job) -> bool:
+  """Checks if the job is remote based on attribute or description keywords."""
+  is_flagged_remote = job.remote is True
+
+  search_text = f"{job.title or ''} {job.location or ''} {job.description or ''}"
+
+  has_remote_keyword = bool(settings.filters.remote_keywords and any(has_word(kw, search_text) for kw in settings.filters.remote_keywords))
+
+  return is_flagged_remote or has_remote_keyword
+
+
+def is_recent_enough(job: Job) -> bool:
+  """Checks if the job posting is within the max age days filter."""
+  has_no_date = not job.posted
+  if has_no_date:
+    return True
+
+  try:
+    posted_date = datetime.datetime.strptime(str(job.posted)[:10], "%Y-%m-%d").date()
+    age_days = (datetime.datetime.now(datetime.UTC).date() - posted_date).days
+    is_within_age_limit = age_days <= settings.filters.max_age_days
+
+    return is_within_age_limit
+  except ValueError, TypeError:
+    return True
+
+
+def count_stack_hits(job: Job) -> int:
+  """Counts how many stack keywords are present in the job title and description."""
+  filters = settings.filters
+  if not filters.stack_keywords:
+    return 0
+
+  search_text = f"{job.title or ''} {job.description or ''}"
+  return sum(1 for kw in filters.stack_keywords if has_word(kw, search_text))
+
+
+def has_required_stack(job: Job) -> bool:
+  """Checks if the job description contains the required stack keywords."""
+  filters = settings.filters
+
+  no_stack_required = filters.min_stack_hits <= 0 or not filters.stack_keywords
+
+  has_enough_hits = count_stack_hits(job) >= filters.min_stack_hits
+
+  return no_stack_required or has_enough_hits
+
+
+def passes_all_filters(job: Job) -> bool:
+  """Master function to run a job through all active filters."""
+  is_remote_valid = not settings.filters.require_remote or is_job_remote(job)
+
+  return is_remote_valid and is_valid_title(job) and is_valid_company(job) and is_valid_location(job) and is_recent_enough(job) and has_required_stack(job)

jobhunter/core/http.py

@@ -0,0 +1,57 @@
+import atexit
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from jobhunter.core.logger import console
+
+logger = logging.getLogger(__name__)
+
+RETRYABLE_STATUS = {408, 429}
+CLIENT = httpx.Client(headers={"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"})
+
+atexit.register(CLIENT.close)
+
+
+def _should_retry(e: httpx.HTTPError) -> bool:
+  if isinstance(e, httpx.HTTPStatusError):
+    code = e.response.status_code
+    return code in RETRYABLE_STATUS or code >= 500
+  return isinstance(e, httpx.RequestError)
+
+
+def fetch_url(url: str, headers: dict | None = None, timeout: float = 15.0, retries: int = 3, backoff: float = 1.5, parse_json: bool = False, expected_type: type | None = None, **kwargs) -> Any:
+  """Fetches data from a URL. Returns parsed JSON if `parse_json=True` or `expected_type` is provided, else returns `httpx.Response`."""
+  if retries <= 0:
+    raise ValueError("retries must be at least 1")
+
+  if expected_type is not None:
+    parse_json = True
+
+  for attempt in range(retries):
+    try:
+      response = CLIENT.get(url, headers=headers, timeout=timeout, **kwargs)
+      response.raise_for_status()
+
+      if parse_json:
+        data = response.json()
+        if expected_type and not isinstance(data, expected_type):
+          raise ValueError(f"Expected {expected_type.__name__} from {url}, got {type(data).__name__}")
+        return data
+
+      return response
+
+    except httpx.HTTPError as e:
+      if _should_retry(e) and attempt < retries - 1:
+        time.sleep(backoff * (2**attempt))
+      else:
+        is_client_not_found = isinstance(e, httpx.HTTPStatusError) and e.response.status_code in {404, 410}
+        if not is_client_not_found:
+          logger.error(f"HTTP request failed permanently for {url}: {e}")
+          console.print(f"  [red]✖ Network error fetching {url}: {e}[/red]")
+        raise
+
+    except ValueError as e:
+      raise RuntimeError(f"JSON decoding or type error for {url}: {e}") from e

jobhunter/core/logger.py

@@ -0,0 +1,54 @@
+import logging
+from pathlib import Path
+
+from rich.console import Console
+from rich.logging import RichHandler
+
+console = Console()
+
+
+def setup_logging(level: str = "INFO", log_file: str = "logs/jobhunter.log") -> None:
+  """Configures global application logging to output to both the console (Rich) and a log file."""
+  numeric_level = getattr(logging, level.upper(), logging.INFO)
+
+  log_path = Path(log_file)
+  log_path.parent.mkdir(parents=True, exist_ok=True)
+
+  # 1. Rich Console Handler (Terminal UI & Tracebacks)
+  console_handler = RichHandler(
+    console=console,
+    rich_tracebacks=True,
+    tracebacks_show_locals=False,
+    markup=True,
+  )
+  # hide normal logger.info() from the terminal and only show errors!
+  console_handler.setLevel(logging.CRITICAL)
+
+  # 2. Standard File Handler (For debugging history)
+  file_handler = logging.FileHandler(log_path, encoding="utf-8")
+  file_handler.setLevel(numeric_level)
+  file_formatter = logging.Formatter(
+    "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+  )
+  file_handler.setFormatter(file_formatter)
+
+  logging.basicConfig(
+    level=numeric_level,
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[console_handler, file_handler],
+    force=True,
+  )
+
+  # 3. Suppress Noisy Third-Party Loggers
+  noisy_prefixes = ("openai", "httpx", "httpcore", "urllib3", "ddgs", "primp")
+
+  # Direct suppression
+  for noisy_logger in noisy_prefixes:
+    logging.getLogger(noisy_logger).setLevel(logging.WARNING)
+
+  # Aggressive sub-logger suppression loop
+  for name, logger in logging.root.manager.loggerDict.items():
+    if any(name.startswith(prefix) for prefix in noisy_prefixes) and isinstance(logger, logging.Logger):
+      logger.setLevel(logging.WARNING)

jobhunter/core/paths.py

@@ -0,0 +1,124 @@
+import contextlib
+import hashlib
+import json
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from filelock import FileLock
+
+from jobhunter.core.logger import console
+
+logger = logging.getLogger(__name__)
+
+
+def get_project_root() -> Path:
+  """Returns the root directory of the project by searching for 'pyproject.toml'."""
+  current_dir = Path(__file__).resolve().parent
+
+  for directory in [current_dir, *current_dir.parents]:
+    if (directory / "pyproject.toml").exists():
+      return directory
+
+  return Path.cwd()
+
+
+ROOT_PATH = get_project_root()
+LOCKS_PATH = ROOT_PATH / ".locks"
+DATA_PATH = ROOT_PATH / "data"
+CONFIG_PATH = ROOT_PATH / "config"
+
+
+def _resolve_path(path_in: str | Path) -> Path:
+  """
+  Safely resolves a path against the project root.
+  If path_in is absolute, it returns it as-is.
+  If path_in is relative, it prepends ROOT_PATH.
+  """
+  return ROOT_PATH / path_in
+
+
+def _json_default(obj: Any) -> Any:
+  """Fallback handler for non-standard JSON types like Pydantic models."""
+  if hasattr(obj, "model_dump"):
+    return obj.model_dump(mode="json")
+  return str(obj)
+
+
+def write(path_from_root: str | Path, data: Any, timeout: int = 10):
+  """Atomically writes data to disk using a persistent lockfile for process safety."""
+  path = _resolve_path(path_from_root)
+
+  directory = path.parent
+  directory.mkdir(parents=True, exist_ok=True)
+  LOCKS_PATH.mkdir(exist_ok=True)
+
+  if isinstance(data, bytes):
+    raw_bytes = data
+  elif isinstance(data, str):
+    raw_bytes = data.encode("utf-8")
+  elif isinstance(data, (dict, list)):
+    raw_bytes = json.dumps(data, indent=2, default=_json_default).encode("utf-8")
+  elif hasattr(data, "model_dump"):
+    raw_bytes = json.dumps(data.model_dump(mode="json"), indent=2).encode("utf-8")
+  else:
+    raw_bytes = str(data).encode("utf-8")
+
+  path_hash = hashlib.md5(str(path.resolve()).encode()).hexdigest()
+  lock_path = LOCKS_PATH / f"{path.name}_{path_hash}.lock"
+
+  with FileLock(str(lock_path), timeout=timeout):
+    fd, temp_path = tempfile.mkstemp(dir=directory, prefix=".tmp_")
+
+    try:
+      with os.fdopen(fd, "wb") as f:
+        f.write(raw_bytes)
+        f.flush()
+        if hasattr(os, "fdatasync"):
+          os.fdatasync(f.fileno())
+        else:
+          os.fsync(f.fileno())
+
+      os.replace(temp_path, path)
+
+    except Exception:
+      with contextlib.suppress(OSError):
+        if os.path.exists(temp_path):
+          os.remove(temp_path)
+      raise
+
+
+def read[T: (dict, list, str)](
+  path_from_root: str | Path,
+  expected_type: type[T] = str,
+) -> T:
+  """Reads and parses a file. Returns a default empty instance ({}, [], "") if missing."""
+  path = _resolve_path(path_from_root)
+
+  try:
+    text = path.read_text(encoding="utf-8")
+  except FileNotFoundError:
+    return expected_type()
+
+  if expected_type in (dict, list):
+    try:
+      data = json.loads(text)
+
+      if not isinstance(data, expected_type):
+        raise TypeError(f"Type mismatch in {path}: Expected {expected_type.__name__}, got {type(data).__name__}")
+
+    except (json.JSONDecodeError, TypeError) as e:
+      logger.warning(f"Error reading or parsing {path}: {e}")
+      console.print(f"  [yellow]⚠ Warning: Could not parse {path.name} (corrupted). Using default empty state.[/yellow]")
+      return expected_type()
+
+    return data
+
+  return text  # type: ignore
+
+
+def delete(path_from_root: str | Path):
+  """Safely unlinks a file if it exists."""
+  _resolve_path(path_from_root).unlink(missing_ok=True)

jobhunter/core/settings.py

@@ -0,0 +1,123 @@
+import json
+import os
+from typing import Any
+
+from pydantic import BaseModel, Field
+from pydantic.aliases import AliasChoices
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .paths import CONFIG_PATH, read
+
+
+class ProfileConfig(BaseModel):
+  target_roles: str = ""
+
+
+class FiltersConfig(BaseModel):
+  title_include: list[str] = []
+  title_exclude: list[str] = []
+  stack_keywords: list[str] = []
+  min_stack_hits: int = 0
+  company_exclude: list[str] = []
+  company_priority: list[str] = []
+  require_remote: bool = True
+  remote_keywords: list[str] = ["remote", "wfh", "work from home", "anywhere", "telecommute", "fully remote", "100% remote"]
+  location_exclude_terms: list[str] = ["us only", "us-only", "united states only", "canada only", "uk only", "must reside in"]
+  location_allow_terms: list[str] = ["worldwide", "emea", "anywhere", "global"]
+  location_require_terms: list[str] = []
+  max_age_days: int = 14
+
+
+class LimitsConfig(BaseModel):
+  max_candidates_per_run: int = 30
+  description_max_chars: int = 7000
+  seen_retention_days: int = 90
+
+
+class ScoringWeight(BaseModel):
+  name: str
+  weight: int
+  what: str
+
+
+class EvaluatingConfig(BaseModel):
+  score_threshold: int = 65
+  scoring_weights: list[ScoringWeight] = Field(default_factory=list)
+
+
+class LLMConfig(BaseModel):
+  provider: str = "openai"
+  base_url: str | None = None
+  model: str | None = None
+  request_delay: int = 5
+  temperature: float = 0.0
+  timeout: int = 600
+
+
+class TelegramConfig(BaseModel):
+  link_preview: bool = False
+  notify_on_empty: bool = True
+
+
+class WorkersConfig(BaseModel):
+  evaluation_workers: int = 1
+  fetch_workers: int = 8
+  discovery_workers: int = 8
+  pruning_workers: int = 8
+
+
+class Settings(BaseSettings):
+  telegram_bot_token: str = Field(default="", validation_alias=AliasChoices("TELEGRAM_BOT_TOKEN", "telegram_bot_token"))
+  telegram_chat_id: str = Field(default="", validation_alias=AliasChoices("TELEGRAM_CHAT_ID", "telegram_chat_id"))
+  llm_api_key: str = Field(default="", validation_alias=AliasChoices("LLM_API_KEY", "llm_api_key"))
+
+  profile: ProfileConfig = Field(default_factory=ProfileConfig)
+  boards: dict[str, Any] = Field(default_factory=dict)
+  companies: dict[str, list[str]] = Field(default_factory=dict)
+  filters: FiltersConfig = Field(default_factory=FiltersConfig)
+  limits: LimitsConfig = Field(default_factory=LimitsConfig)
+  evaluating: EvaluatingConfig = Field(default_factory=EvaluatingConfig)
+  llm: LLMConfig = Field(default_factory=LLMConfig)
+  telegram: TelegramConfig = Field(default_factory=TelegramConfig)
+  workers: WorkersConfig = Field(default_factory=WorkersConfig)
+
+  cv_text: str = ""
+  preferences_text: str = ""
+
+  model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+
+def load_settings() -> Settings:
+  """Loads settings from files or environment variable fallbacks, returning a Settings object."""
+  config_path = CONFIG_PATH / "config.json"
+
+  if config_path.exists():
+    config_data = read(config_path, dict)
+  else:
+    config_str = os.getenv("CONFIG_JSON")
+    if config_str:
+      try:
+        config_data = json.loads(config_str)
+      except Exception:
+        config_data = {}
+    else:
+      config_data = {}
+
+  # Remove "_help"
+  config_data.pop("_help", None)
+
+  # Load Markdown with env fallbacks
+  cv_path = CONFIG_PATH / "cv.md"
+  cv_text = read(cv_path) if cv_path.exists() else os.getenv("CV") or ""
+
+  pref_path = CONFIG_PATH / "preferences.md"
+  preferences_text = read(pref_path) if pref_path.exists() else os.getenv("PREFERENCES") or ""
+
+  return Settings(
+    cv_text=cv_text,
+    preferences_text=preferences_text,
+    **config_data,
+  )
+
+
+settings = load_settings()

jobhunter/core/textutil.py

@@ -0,0 +1,33 @@
+import html
+import re
+from datetime import datetime
+
+
+def clean_html(text: str | None) -> str:
+  """Cleans HTML content by removing tags, unescaping entities, and normalizing whitespace."""
+  if not text:
+    return ""
+
+  # 1. Remove script and style blocks with their contents
+  text = re.sub(r"<(script|style)[^>]*>.*?</\1>", " ", text, flags=re.DOTALL | re.IGNORECASE)
+
+  # 2. Strip HTML tags
+  text = re.sub(r"<[^>]+>", " ", text)
+
+  # 3. Unescape entities after tags are gone
+  text = html.unescape(text)
+
+  # 4. Normalize whitespace
+  return re.sub(r"\s+", " ", text).strip()
+
+
+def parse_date(date_str: str | None) -> str:
+  """Parses an ISO date string into YYYY-MM-DD format."""
+  if not date_str:
+    return ""
+
+  try:
+    dt = datetime.fromisoformat(date_str.replace("Z", "+00:00"))
+    return dt.strftime("%Y-%m-%d")
+  except ValueError:
+    return date_str.strip()

jobhunter/main.py

@@ -0,0 +1,94 @@
+import logging
+import sys
+from typing import Annotated
+
+import typer
+
+from jobhunter.core.logger import console, setup_logging
+from jobhunter.pipeline import evaluate, fetch, send
+from jobhunter.tools import discover, prompt, prune
+
+app = typer.Typer(
+  help="JobHunter - Automated job scraping and filtering pipeline.",
+  no_args_is_help=True,
+  context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+SourceOpt = Annotated[str | None, typer.Option("--source", "-s", help="Specific source to fetch from")]
+NoAggOpt = Annotated[bool, typer.Option("--no-aggregators", help="Skip aggregator boards")]
+IgnoreSeenOpt = Annotated[bool, typer.Option("--ignore-seen", help="Ignore seen jobs and fetch all")]
+LimitOpt = Annotated[int | None, typer.Option("--limit", "-l", help="Overrides max_candidates limit in config.json")]
+WriteOpt = Annotated[bool, typer.Option("--write", "-w", help="Write changes to config.json")]
+JobUidOpt = Annotated[str | None, typer.Option("--job", "-j", help="Evaluate a specific candidate by their UID")]
+DryRunOpt = Annotated[bool, typer.Option("--dry-run", help="Send Telegram alerts without updating local state files")]
+
+
+@app.command("run", help="Run the full pipeline (fetch -> evaluate -> send)")
+def run_all(
+  source: SourceOpt = None,
+  no_aggregators: NoAggOpt = False,
+  ignore_seen: IgnoreSeenOpt = False,
+  limit: LimitOpt = None,
+  dry_run: DryRunOpt = False,
+):
+  fetch.main(source_name=source, no_aggregators=no_aggregators, ignore_seen=ignore_seen, limit=limit)
+  evaluate.main(limit=limit)
+  send.main(dry_run=dry_run)
+
+
+@app.command("fetch", help="Fetch jobs from configured boards")
+def fetch_jobs(
+  source: SourceOpt = None,
+  no_aggregators: NoAggOpt = False,
+  ignore_seen: IgnoreSeenOpt = False,
+  limit: LimitOpt = None,
+):
+  fetch.main(source_name=source, no_aggregators=no_aggregators, ignore_seen=ignore_seen, limit=limit)
+
+
+@app.command("evaluate", help="Score and evaluate candidates")
+def evaluate_jobs(
+  job: JobUidOpt = None,
+  limit: LimitOpt = None,
+):
+  evaluate.main(job_uid=job, limit=limit)
+
+
+@app.command("send", help="Send passing jobs to Telegram")
+def send_jobs(dry_run: DryRunOpt = False):
+  send.main(dry_run=dry_run)
+
+
+@app.command("discover", help="Discover and validate new company boards")
+def discover_boards(
+  write: WriteOpt = False,
+  source: SourceOpt = None,
+  titles: Annotated[str | None, typer.Option("--titles", "-t", help="Comma-separated list of titles to search for")] = None,
+):
+  discover.main(write_flag=write, source_name=source, titles_override=titles)
+
+
+@app.command("prune", help="Prune broken company entries from config.json")
+def prune_companies(write: WriteOpt = False, source: SourceOpt = None):
+  prune.main(write_flag=write, source_name=source)
+
+
+@app.command("prompt", help="Prints the AI evaluation prompt for review")
+def show_prompt():
+  prompt.main()
+
+
+def main():
+  """Entry point wrapper to catch global exceptions."""
+  setup_logging(level="INFO")
+
+  try:
+    app()
+  except KeyboardInterrupt:
+    console.print("\n[yellow]Aborted by user.[/yellow]")
+    sys.exit(1)
+  except Exception as e:
+    logger = logging.getLogger(__name__)
+    logger.exception(f"Fatal error: {e}")
+    console.print(f"[bold red]Fatal error: {e}[/bold red]")
+    sys.exit(1)

jobhunter/models.py

@@ -0,0 +1,81 @@
+from pydantic import BaseModel, Field, computed_field
+
+from jobhunter.core.settings import settings
+
+
+class Job(BaseModel):
+  source: str
+  board: str
+  company: str
+  job_id: str
+  title: str
+  url: str
+  location: str
+  remote: bool | None = None
+  posted: str = ""
+  description: str
+
+  @computed_field
+  @property
+  def uid(self) -> str:
+    """Dynamically generates a unique identifier for the job."""
+    return f"{self.source}:{self.board}:{self.job_id or self.url}"
+
+
+class Candidate(BaseModel):
+  uid: str = Field(..., description="Unique compound identifier: source:board:job_id_or_url")
+  priority: bool = False
+  stack_hits: int = 0
+  status: str = Field(default="pending", description="Pipeline status: pending, saved, applied, rejected")
+  source: str = ""
+  board: str = ""
+  company: str
+  job_id: str = ""
+  title: str
+  url: str
+  location: str
+  remote: bool | None = None
+  posted: str = ""
+  description: str = ""
+
+  @classmethod
+  def from_job(cls, job: Job, priority: bool, stack_hits: int) -> Candidate:
+    """Factory method to convert a raw scraped Job into a stored Candidate."""
+    max_chars = settings.limits.description_max_chars
+    truncated_description = (job.description or "No description provided.")[:max_chars]
+
+    return cls(
+      uid=job.uid,
+      priority=priority,
+      stack_hits=stack_hits,
+      status="pending",
+      source=job.source,
+      board=job.board,
+      company=job.company,
+      job_id=job.job_id,
+      title=job.title,
+      url=job.url,
+      location=job.location,
+      remote=job.remote,
+      posted=job.posted,
+      description=truncated_description,
+    )
+
+
+class EvaluationResult(BaseModel):
+  """The exact JSON schema the LLM must return."""
+
+  reasoning: str = Field(description="A brief 2-3 sentence thought process analyzing the match before scoring.")
+  hard_fail: bool = Field(description="True if the job hits any hard gate or dealbreaker.")
+  hard_fail_reason: str = Field(default="", description="If hard_fail is true, a max 12-word explanation. Otherwise empty.")
+  strengths: list[str] = Field(description="2-3 short items showing requirements explicitly met by the CV.")
+  gaps: list[str] = Field(default_factory=list, description="Missing requirements or weak points compared to the CV.")
+  score: int = Field(description="Final match score (0-100) based on the rubric.")
+  score_explanation: str = Field(description="A 1-2 sentence explanation of exactly why the job passed or failed the score threshold.")
+  pitch: str = Field(default="", description="A short, one-sentence first-person pitch. Empty if score is below threshold.")
+
+
+class EvaluatedCandidate(Candidate):
+  """A candidate that has been evaluated by the AI."""
+
+  evaluation: EvaluationResult