linkedin-apply-assistant 0.1.1

package/src/linkedin_apply_assistant/paths.py

@@ -0,0 +1,135 @@
+"""Runtime path resolution for the standalone assistant."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+
+try:
+    from platformdirs import user_cache_dir, user_config_dir, user_data_dir
+except ModuleNotFoundError:
+
+    def _windows_base(env_name: str, fallback: Path) -> Path:
+        value = os.environ.get(env_name)
+        return Path(value).expanduser() if value else fallback
+
+    def user_config_dir(appname: str) -> str:
+        base = _windows_base("APPDATA", Path.home() / ".config")
+        return str(base / appname)
+
+    def user_data_dir(appname: str) -> str:
+        base = _windows_base("LOCALAPPDATA", Path.home() / ".local" / "share")
+        return str(base / appname)
+
+    def user_cache_dir(appname: str) -> str:
+        base = _windows_base("LOCALAPPDATA", Path.home() / ".cache")
+        return str(base / appname / "cache")
+
+
+APP_NAME = "linkedin-apply-assistant"
+
+
+@dataclass(frozen=True)
+class RuntimePaths:
+    """Resolved paths for config, data, cache, browser profile, and outputs."""
+
+    workspace: Path | None
+    config_dir: Path
+    data_dir: Path
+    cache_dir: Path
+    config_file: Path
+    qa_bank_file: Path
+    browser_profile_dir: Path
+    output_dir: Path
+    reports_dir: Path
+
+
+def _optional_path(value: str | Path | None) -> Path | None:
+    if value is None:
+        return None
+    return Path(value).expanduser()
+
+
+def _resolve_under_workspace(workspace: Path, path: Path) -> Path:
+    if path.is_absolute():
+        return path
+    return workspace / path
+
+
+def resolve_runtime_paths(
+    workspace: str | Path | None = None,
+    config: str | Path | None = None,
+    qa_bank: str | Path | None = None,
+    browser_profile: str | Path | None = None,
+    output_dir: str | Path | None = None,
+) -> RuntimePaths:
+    """Resolve runtime paths without touching the filesystem."""
+
+    workspace_path = _optional_path(workspace)
+    if workspace_path is not None:
+        workspace_path = workspace_path.resolve()
+        config_dir = workspace_path / "configs"
+        data_dir = workspace_path / "data"
+        cache_dir = workspace_path / ".cache"
+        default_config = config_dir / "config.yml"
+        default_qa_bank = config_dir / "qa_bank.yml"
+        default_browser_profile = workspace_path / "browser-profile"
+        default_output = workspace_path / "output"
+    else:
+        config_dir = Path(user_config_dir(APP_NAME))
+        data_dir = Path(user_data_dir(APP_NAME))
+        cache_dir = Path(user_cache_dir(APP_NAME))
+        default_config = config_dir / "config.yml"
+        default_qa_bank = config_dir / "qa_bank.yml"
+        default_browser_profile = data_dir / "browser-profile"
+        default_output = data_dir / "output"
+
+    config_override = _optional_path(config)
+    qa_bank_override = _optional_path(qa_bank)
+    browser_override = _optional_path(browser_profile)
+    output_override = _optional_path(output_dir)
+
+    if workspace_path is not None:
+        if config_override is not None:
+            config_override = _resolve_under_workspace(workspace_path, config_override)
+        if qa_bank_override is not None:
+            qa_bank_override = _resolve_under_workspace(workspace_path, qa_bank_override)
+        if browser_override is not None:
+            browser_override = _resolve_under_workspace(workspace_path, browser_override)
+        if output_override is not None:
+            output_override = _resolve_under_workspace(workspace_path, output_override)
+
+    resolved_output = output_override or default_output
+
+    return RuntimePaths(
+        workspace=workspace_path,
+        config_dir=config_dir,
+        data_dir=data_dir,
+        cache_dir=cache_dir,
+        config_file=config_override or default_config,
+        qa_bank_file=qa_bank_override or default_qa_bank,
+        browser_profile_dir=browser_override or default_browser_profile,
+        output_dir=resolved_output,
+        reports_dir=resolved_output / "reports",
+    )
+
+
+def ensure_runtime_dirs(
+    paths: RuntimePaths,
+    *,
+    include_browser_profile: bool = False,
+) -> RuntimePaths:
+    """Create runtime directories that are safe for local package operation."""
+
+    for directory in (
+        paths.config_dir,
+        paths.data_dir,
+        paths.cache_dir,
+        paths.output_dir,
+        paths.reports_dir,
+    ):
+        directory.mkdir(parents=True, exist_ok=True)
+    if include_browser_profile:
+        paths.browser_profile_dir.mkdir(parents=True, exist_ok=True)
+    return paths

package/src/linkedin_apply_assistant/qa_bank.py

@@ -0,0 +1,352 @@
+"""Standalone Q&A matching with explicit data paths."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from difflib import SequenceMatcher
+from pathlib import Path
+import re
+from typing import Any
+import unicodedata
+
+import yaml
+
+from .paths import RuntimePaths
+from .safety import domain_from_url, normalize_url_for_audit
+
+
+MATCH_THRESHOLD = 0.75
+
+STOPWORDS = {
+    "a",
+    "an",
+    "the",
+    "is",
+    "are",
+    "was",
+    "were",
+    "of",
+    "in",
+    "on",
+    "at",
+    "to",
+    "for",
+    "with",
+    "by",
+    "from",
+    "as",
+    "and",
+    "or",
+    "but",
+    "if",
+    "your",
+    "you",
+    "our",
+    "this",
+    "that",
+    "do",
+    "does",
+    "did",
+    "what",
+    "what's",
+    "how",
+    "have",
+    "has",
+    "be",
+    "been",
+    "being",
+    "will",
+    "would",
+}
+
+
+def normalize(text: str) -> str:
+    """Strip accents and punctuation, lowercase, and collapse whitespace."""
+
+    if not text:
+        return ""
+    normalized = unicodedata.normalize("NFKD", text)
+    normalized = "".join(ch for ch in normalized if not unicodedata.combining(ch))
+    normalized = normalized.lower()
+    normalized = re.sub(r"[^\w\s]", " ", normalized)
+    normalized = re.sub(r"\s+", " ", normalized)
+    return normalized.strip()
+
+
+def tokenize(text: str) -> set[str]:
+    """Return content tokens for fuzzy question matching."""
+
+    return {token for token in normalize(text).split() if token not in STOPWORDS and len(token) > 1}
+
+
+def similarity(question: str, pattern: str) -> float:
+    """Hybrid similarity using containment, token overlap, and sequence ratio."""
+
+    norm_q = normalize(question)
+    norm_p = normalize(pattern)
+    if len(norm_p) >= 4 and norm_p in norm_q:
+        return 0.95 + (len(norm_p) / max(len(norm_q), 1)) * 0.05
+
+    tokens_q = tokenize(question)
+    tokens_p = tokenize(pattern)
+    if not tokens_p:
+        return 0.0
+    token_score = len(tokens_q & tokens_p) / len(tokens_p)
+    seq_score = SequenceMatcher(None, norm_q, norm_p).ratio()
+    return max(token_score * 0.85 + seq_score * 0.15, seq_score)
+
+
+class QABank:
+    """Application Q&A knowledge bank backed by explicit package paths."""
+
+    def __init__(
+        self,
+        bank_file: str | Path | None = None,
+        pending_file: str | Path | None = None,
+        profile: dict[str, Any] | None = None,
+    ) -> None:
+        self.bank_file = Path(bank_file).expanduser() if bank_file is not None else None
+        self.pending_file = Path(pending_file).expanduser() if pending_file is not None else None
+        self.profile = profile or {}
+        self.data = self._load()
+        self.session_unknowns: list[dict[str, Any]] = []
+
+    @classmethod
+    def from_runtime_paths(
+        cls,
+        paths: RuntimePaths,
+        profile: dict[str, Any] | None = None,
+    ) -> "QABank":
+        """Create a bank using standalone runtime locations."""
+
+        return cls(
+            bank_file=paths.qa_bank_file,
+            pending_file=paths.data_dir / "pending_questions.md",
+            profile=profile,
+        )
+
+    def _load(self) -> dict[str, Any]:
+        if self.bank_file is None or not self.bank_file.exists():
+            return {"qa_pairs": []}
+        parsed = yaml.safe_load(self.bank_file.read_text(encoding="utf-8"))
+        if parsed is None:
+            return {"qa_pairs": []}
+        if not isinstance(parsed, dict):
+            raise ValueError("Q&A bank root must be a mapping")
+        pairs = parsed.get("qa_pairs")
+        if pairs is None:
+            parsed["qa_pairs"] = []
+        elif not isinstance(pairs, list):
+            raise ValueError("qa_pairs must be a list")
+        return dict(parsed)
+
+    def _patterns_for(self, qa: dict[str, Any]) -> list[str]:
+        patterns = qa.get("patterns", qa.get("question_patterns", []))
+        if isinstance(patterns, str):
+            return [patterns]
+        if isinstance(patterns, list):
+            return [str(pattern) for pattern in patterns if str(pattern).strip()]
+        return []
+
+    def _field_type_for(self, qa: dict[str, Any]) -> str:
+        return str(qa.get("field_type") or qa.get("response_type") or "text")
+
+    def _substitute_placeholders(
+        self,
+        text: str,
+        context: dict[str, Any] | None = None,
+    ) -> str:
+        if not text or "{" not in text:
+            return text
+        ctx = context or {}
+        replacements = {
+            "{company}": ctx.get("company", ""),
+            "{role}": ctx.get("role", ""),
+            "{portfolio}": self.profile.get("portfolio", ""),
+            "{linkedin}": self.profile.get("linkedin", ""),
+            "{github}": self.profile.get("github", ""),
+            "{email}": self.profile.get("email", ""),
+            "{phone}": self.profile.get("phone", ""),
+            "{full_name}": self.profile.get("full_name", ""),
+            "{first_name}": self.profile.get("first_name", ""),
+            "{last_name}": self.profile.get("last_name", ""),
+        }
+        for placeholder, value in replacements.items():
+            text = text.replace(placeholder, str(value))
+        return text
+
+    def find_answer(
+        self,
+        question_text: str,
+        field_type: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        """Return a matched answer record, or ``None`` when no threshold match exists."""
+
+        if not question_text:
+            return None
+
+        def type_compatible(bank_type: str, requested: str | None) -> bool:
+            if not requested or not bank_type:
+                return True
+            bank_type = bank_type.lower()
+            requested = requested.lower()
+            if bank_type == requested:
+                return True
+            if bank_type == "radio_or_select" and requested in {"radio", "select"}:
+                return True
+            textish = {"text", "textarea", "email", "tel", "url", "number"}
+            return bank_type in textish and requested in textish
+
+        best: dict[str, Any] | None = None
+        best_score = 0.0
+        best_compatible: dict[str, Any] | None = None
+        best_compatible_score = 0.0
+
+        for qa in self.data.get("qa_pairs", []):
+            if not isinstance(qa, dict):
+                continue
+            bank_type = self._field_type_for(qa)
+            compatible = type_compatible(bank_type, field_type)
+            for pattern in self._patterns_for(qa):
+                score = similarity(question_text, pattern)
+                if field_type and compatible:
+                    score = min(score * 1.05, 1.0)
+                candidate = {
+                    "id": qa.get("id", "?"),
+                    "answer": self._substitute_placeholders(str(qa.get("answer", "")), context),
+                    "field_type": bank_type,
+                    "matched_pattern": pattern,
+                    "score": round(score, 3),
+                }
+                pattern_specificity = len(normalize(pattern))
+                best_specificity = len(normalize(best["matched_pattern"])) if best else -1
+                compatible_specificity = (
+                    len(normalize(best_compatible["matched_pattern"])) if best_compatible else -1
+                )
+                if score > best_score or (
+                    score == best_score and pattern_specificity > best_specificity
+                ):
+                    best_score = score
+                    best = candidate
+                if compatible and (
+                    score > best_compatible_score
+                    or (
+                        score == best_compatible_score
+                        and pattern_specificity > compatible_specificity
+                    )
+                ):
+                    best_compatible_score = score
+                    best_compatible = candidate
+
+        if field_type:
+            if best_compatible and best_compatible_score >= MATCH_THRESHOLD:
+                return best_compatible
+            return None
+        if best and best_score >= MATCH_THRESHOLD:
+            return best
+        return None
+
+    def log_pending(
+        self,
+        question_text: str,
+        context: dict[str, Any] | None = None,
+        field_type: str | None = None,
+        is_required: bool = False,
+    ) -> dict[str, Any]:
+        """Record an unknown question in memory and append when a pending path exists."""
+
+        ctx = context or {}
+        normalized_url = normalize_url_for_audit(ctx.get("apply_url") or ctx.get("url") or "")
+        entry = {
+            "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M"),
+            "question": question_text.strip(),
+            "company": ctx.get("company", "unknown"),
+            "role": ctx.get("role", "unknown"),
+            "ats": ctx.get("ats", "unknown"),
+            "domain": ctx.get("domain") or domain_from_url(normalized_url),
+            "field_type": field_type or "text",
+            "required": is_required,
+        }
+        self.session_unknowns.append(entry)
+        if self.pending_file is not None:
+            self._append_pending(entry)
+        return entry
+
+    def _append_pending(self, entry: dict[str, Any]) -> None:
+        if self.pending_file is None:
+            return
+        self.pending_file.parent.mkdir(parents=True, exist_ok=True)
+        existing_questions: set[str] = set()
+        if self.pending_file.exists():
+            content = self.pending_file.read_text(encoding="utf-8")
+            for line in content.splitlines():
+                match = re.match(r"^###\s+Q:\s*(.+?)\s*$", line)
+                if match:
+                    existing_questions.add(normalize(match.group(1)))
+
+        if normalize(entry["question"]) in existing_questions:
+            self._increment_pending_counter(entry["question"], entry)
+            return
+
+        header_needed = not self.pending_file.exists() or self.pending_file.stat().st_size == 0
+        with self.pending_file.open("a", encoding="utf-8") as handle:
+            if header_needed:
+                handle.write(self._pending_header())
+            handle.write(self._format_pending_entry(entry))
+
+    def _pending_header(self) -> str:
+        return """# Pending Application Questions
+
+These are questions the assistant encountered that are not in your selected Q&A bank yet.
+Add a truthful answer below each question, then copy the final entry into your own Q&A bank.
+
+Format for adding an answer:
+```
+**Answer:** Your answer here
+**Field type:** text | textarea | number | select | radio_or_select
+**Patterns:** synonym1, synonym2
+```
+
+---
+
+"""
+
+    def _format_pending_entry(self, entry: dict[str, Any]) -> str:
+        seen_marker = f"[seen 1 time as of {entry['timestamp']}]"
+        return f"""### Q: {entry["question"]}
+
+- **First seen:** {entry["timestamp"]}
+- **First context:** {entry["company"]} - {entry["role"]} ({entry["ats"]})
+- **Domain:** {entry["domain"] or "unknown"}
+- **Field type:** {entry["field_type"]}
+- **Required:** {entry["required"]}
+- **Stats:** {seen_marker}
+
+**Answer:** _(fill in here)_
+
+**Patterns:** _(optional - add synonyms separated by commas)_
+
+---
+
+"""
+
+    def _increment_pending_counter(self, question: str, entry: dict[str, Any]) -> None:
+        if self.pending_file is None or not self.pending_file.exists():
+            return
+        lines = self.pending_file.read_text(encoding="utf-8").splitlines(keepends=True)
+        norm_target = normalize(question)
+        for i, line in enumerate(lines):
+            match = re.match(r"^###\s+Q:\s*(.+?)\s*$", line)
+            if not match or normalize(match.group(1)) != norm_target:
+                continue
+            for j in range(i, min(i + 20, len(lines))):
+                stat_match = re.match(
+                    r"^- \*\*Stats:\*\* \[seen (\d+) times? as of [^\]]+\]\s*$",
+                    lines[j],
+                )
+                if stat_match:
+                    new_count = int(stat_match.group(1)) + 1
+                    lines[j] = f"- **Stats:** [seen {new_count} times as of {entry['timestamp']}]\n"
+                    self.pending_file.write_text("".join(lines), encoding="utf-8")
+                    return

package/src/linkedin_apply_assistant/redaction.py

@@ -0,0 +1,119 @@
+"""Central report redaction for local JSON and Markdown artifacts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+import re
+from typing import Any
+
+from .form_engine import normalize_space
+from .safety import normalize_url_for_audit
+
+
+REDACTION_MARKER = "[REDACTED]"
+MARKDOWN_VALUE_LIMIT = 180
+
+_SENSITIVE_KEY_PARTS = (
+    "password",
+    "secret",
+    "token",
+    "cookie",
+    "credential",
+    "auth",
+    "session",
+    "browser_profile",
+    "browser-profile",
+    "raw_html",
+    "html",
+    "screenshot",
+    "resume_contents",
+    "cover_letter_contents",
+    "document_contents",
+    "phone_answer",
+    "email_answer",
+    "answer_phone",
+    "answer_email",
+    "application_history",
+    "candidate",
+    "profile",
+    "documents",
+    "raw_form",
+    "raw_state",
+)
+
+_SENSITIVE_EXACT_KEYS = {"answer", "email", "phone", "tel"}
+
+_URL_KEYS = {"url", "apply_url", "search_url"}
+
+_SENSITIVE_VALUE_PATTERNS = (
+    re.compile(r"\bBearer\s+[A-Za-z0-9._~+/=-]+", re.IGNORECASE),
+    re.compile(r"\bsessionid\s*=", re.IGNORECASE),
+    re.compile(r"\bcookie\s*[:=]", re.IGNORECASE),
+    re.compile(r"<\s*html\b", re.IGNORECASE),
+    re.compile(r"[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}"),
+    re.compile(r"\+?\d[\d\s().-]{7,}\d"),
+)
+
+
+def _normalized_key(key: Any) -> str:
+    return re.sub(r"[\s-]+", "_", str(key or "").strip().lower())
+
+
+def _is_sensitive_key(key: Any) -> bool:
+    normalized = _normalized_key(key)
+    if normalized in _SENSITIVE_EXACT_KEYS:
+        return True
+    return any(part in normalized for part in _SENSITIVE_KEY_PARTS)
+
+
+def _is_url_key(key: Any) -> bool:
+    normalized = _normalized_key(key)
+    return normalized in _URL_KEYS or normalized.endswith("_url")
+
+
+def _is_sensitive_value(value: str) -> bool:
+    return any(pattern.search(value) for pattern in _SENSITIVE_VALUE_PATTERNS)
+
+
+def sanitize_report_payload(payload: Any) -> Any:
+    """Return a sanitized copy of a report payload without mutating input."""
+
+    return _sanitize_value(payload, key="")
+
+
+def _sanitize_value(value: Any, *, key: Any) -> Any:
+    if _is_sensitive_key(key):
+        return REDACTION_MARKER
+    if isinstance(value, Mapping):
+        return {
+            str(item_key): _sanitize_value(item_value, key=item_key)
+            for item_key, item_value in value.items()
+        }
+    if isinstance(value, tuple):
+        return [_sanitize_value(item, key=key) for item in value]
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return [_sanitize_value(item, key=key) for item in value]
+    if isinstance(value, str):
+        if _is_url_key(key):
+            return normalize_url_for_audit(value)
+        if _is_sensitive_value(value):
+            return REDACTION_MARKER
+        return value
+    return value
+
+
+def sanitize_markdown_value(value: Any) -> str:
+    """Return compact Markdown-safe text for a sanitized report field."""
+
+    sanitized = sanitize_report_payload(value)
+    if isinstance(sanitized, (Mapping, list, tuple)):
+        rendered = REDACTION_MARKER if sanitized == REDACTION_MARKER else str(sanitized)
+    else:
+        rendered = str(sanitized)
+    rendered = normalize_space(rendered).replace("|", r"\|")
+    if len(rendered) > MARKDOWN_VALUE_LIMIT:
+        return f"{rendered[: MARKDOWN_VALUE_LIMIT - 3]}..."
+    return rendered
+
+
+__all__ = ["REDACTION_MARKER", "sanitize_markdown_value", "sanitize_report_payload"]