linkedin-apply-assistant 0.1.1

package/src/linkedin_apply_assistant/contracts.py

@@ -0,0 +1,255 @@
+"""Stable workflow contracts for the standalone assistant."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping, Protocol, Sequence
+
+from .form_engine import DetectionResult, FillResult
+
+
+@dataclass(frozen=True)
+class JobRecord:
+    """Plain-value LinkedIn job context used by workflow reports."""
+
+    job_id: str = ""
+    title: str = ""
+    company: str = ""
+    url: str = ""
+    location: str = ""
+    source: str = "linkedin"
+    search_url: str = ""
+    ats: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SearchRequest:
+    """Inputs for a search-only workflow run."""
+
+    limit: int = 10
+    search_url: str | None = None
+    query: str | None = None
+    location: str | None = None
+    profile: dict[str, Any] = field(default_factory=dict)
+    paths: Any = None
+
+
+@dataclass(frozen=True)
+class SurfaceIdentity:
+    """Stable identity for a visible application surface."""
+
+    url: str = ""
+    title: str = ""
+    surface: str = ""
+    ats: str = ""
+    job_id: str = ""
+
+    def key(self) -> str:
+        """Return a compact key for fill-once session deduplication."""
+
+        return "|".join((self.url, self.title, self.surface, self.ats, self.job_id))
+
+
+@dataclass(frozen=True)
+class ReportArtifact:
+    """One report file produced by a workflow."""
+
+    kind: str
+    path: Path
+
+
+@dataclass
+class SearchResult:
+    """Search workflow output and report metadata."""
+
+    command: str = "search"
+    timestamp: str = ""
+    search_url: str = ""
+    jobs: list[JobRecord] = field(default_factory=list)
+    events: list[dict[str, Any]] = field(default_factory=list)
+    summary: dict[str, Any] = field(default_factory=dict)
+    reports: list[ReportArtifact] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class AssistEvent:
+    """One assistive fill workflow event."""
+
+    type: str
+    surface: str = ""
+    ats: str = ""
+    status: str = ""
+    filled_count: int = 0
+    required_empty_count: int = 0
+    unknown_count: int = 0
+    reached_submit_step: bool = False
+    blocked_reason: str = ""
+    job: dict[str, Any] = field(default_factory=dict)
+    identity: SurfaceIdentity | None = None
+    required_empty: list[Any] = field(default_factory=list)
+    unknown_questions: list[Any] = field(default_factory=list)
+    timestamp: str = ""
+
+
+@dataclass(frozen=True)
+class AssistRequest:
+    """Inputs for a visible-browser assistive fill session."""
+
+    start_url: str | None = None
+    mode: str = "auto"
+    max_cycles: int = 1
+    profile: dict[str, Any] = field(default_factory=dict)
+    qa_context: dict[str, Any] = field(default_factory=dict)
+    documents: dict[str, Any] = field(default_factory=dict)
+    paths: Any = None
+
+
+@dataclass
+class AssistResult:
+    """Assist workflow output and report metadata."""
+
+    command: str = "assist"
+    timestamp: str = ""
+    events: list[AssistEvent] = field(default_factory=list)
+    summary: dict[str, Any] = field(default_factory=dict)
+    reports: list[ReportArtifact] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class SubmissionResult:
+    """Read-only submission policy decision."""
+
+    status: str = "disabled"
+    reason: str = "Browser submission is disabled in this package boundary."
+    allowed: bool = False
+
+
+@dataclass(frozen=True)
+class SubmitDecision:
+    """Plain-value audit record for an explicit submit/apply boundary."""
+
+    timestamp: str = ""
+    command: str = ""
+    policy: str = ""
+    action: str = ""
+    allowed: bool = False
+    status: str = "disabled"
+    reason: str = ""
+    company: str = ""
+    role: str = ""
+    url: str = ""
+    domain: str = ""
+    ats: str = ""
+    confirmation_state: str = ""
+
+
+class BrowserSession(Protocol):
+    """Visible browser session abstraction."""
+
+    @property
+    def pages(self) -> Sequence[Any]:
+        """Return pages or tabs known to the session."""
+
+    def open_url(self, url: str) -> None:
+        """Open a URL in the visible session."""
+
+    def close(self) -> None:
+        """Close the session when the caller owns it."""
+
+
+class BrowserSessionFactory(Protocol):
+    """Factory that creates visible browser sessions."""
+
+    def open(self, request: AssistRequest | SearchRequest) -> BrowserSession:
+        """Open a session for a workflow request."""
+
+
+class LinkedInDiscovery(Protocol):
+    """LinkedIn search result discovery boundary."""
+
+    def discover(self, request: SearchRequest) -> Sequence[JobRecord | Mapping[str, Any]]:
+        """Return candidate job records for a search request."""
+
+
+class ApplySurfaceDetector(Protocol):
+    """Current apply surface detection boundary."""
+
+    def detect(self, session: BrowserSession) -> DetectionResult:
+        """Detect the currently fillable application surface."""
+
+
+class FillAdapter(Protocol):
+    """Fill-only adapter boundary."""
+
+    def fill(
+        self,
+        detection: DetectionResult,
+        profile: dict[str, Any],
+        bank: Any = None,
+        qa_context: dict[str, Any] | None = None,
+        documents: dict[str, Any] | None = None,
+    ) -> FillResult:
+        """Fill a detected surface without performing submission."""
+
+
+class QAMatcher(Protocol):
+    """Q&A matching boundary."""
+
+    def find_answer(
+        self,
+        question_text: str,
+        field_type: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        """Find an answer for a question."""
+
+    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."""
+
+
+class SubmissionPolicy(Protocol):
+    """Submission policy boundary."""
+
+    def decide(
+        self,
+        action: str,
+        context: dict[str, Any] | None = None,
+    ) -> SubmissionResult:
+        """Return whether an action is allowed."""
+
+
+class ReportSink(Protocol):
+    """Workflow report writing boundary."""
+
+    def write(self, command: str, report: dict[str, Any]) -> Sequence[ReportArtifact]:
+        """Write report artifacts for a workflow command."""
+
+
+__all__ = [
+    "ApplySurfaceDetector",
+    "AssistEvent",
+    "AssistRequest",
+    "AssistResult",
+    "BrowserSession",
+    "BrowserSessionFactory",
+    "FillAdapter",
+    "JobRecord",
+    "LinkedInDiscovery",
+    "QAMatcher",
+    "ReportArtifact",
+    "ReportSink",
+    "SearchRequest",
+    "SearchResult",
+    "SubmissionPolicy",
+    "SubmissionResult",
+    "SubmitDecision",
+    "SurfaceIdentity",
+]

package/src/linkedin_apply_assistant/form_engine.py

@@ -0,0 +1,180 @@
+"""Import-safe form primitives for the standalone assistant."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import re
+from typing import Any
+
+
+_real_print = print
+
+
+def safe_print(*args: object, **kwargs: object) -> None:
+    """Print text while tolerating narrow console encodings."""
+
+    try:
+        _real_print(*args, **kwargs)
+    except UnicodeEncodeError:
+        cleaned = []
+        for arg in args:
+            try:
+                cleaned.append(str(arg))
+            except Exception:
+                cleaned.append(repr(arg))
+        try:
+            _real_print(*cleaned, **kwargs)
+        except UnicodeEncodeError:
+            ascii_cleaned = [
+                str(arg).encode("ascii", errors="replace").decode("ascii") for arg in cleaned
+            ]
+            _real_print(*ascii_cleaned, **kwargs)
+
+
+@dataclass
+class FillResult:
+    """Submit-free fill result shared by package fill-only surfaces."""
+
+    filled: list[Any] = field(default_factory=list)
+    required_empty: list[Any] = field(default_factory=list)
+    unknown_questions: list[Any] = field(default_factory=list)
+    reached_submit_step: bool = False
+    surface: str = ""
+
+
+@dataclass
+class DetectionResult:
+    """Read-only detection result for the currently visible application surface."""
+
+    surface: str = "none"
+    page: Any = None
+    ats: str = ""
+    job_context: dict[str, Any] = field(default_factory=dict)
+
+
+ATS_PATTERNS: dict[str, tuple[str, ...]] = {
+    "greenhouse": (
+        r"boards\.greenhouse\.io",
+        r"job-boards\.greenhouse\.io",
+        r"greenhouse\.io/embed",
+    ),
+    "lever": (
+        r"jobs\.lever\.co",
+        r"lever\.co/[a-z0-9-]+/",
+    ),
+    "ashby": (
+        r"jobs\.ashbyhq\.com",
+        r"ashbyhq\.com",
+    ),
+    "workday": (
+        r"\.myworkdayjobs\.com",
+        r"workday\.com",
+    ),
+    "smartrecruiters": (
+        r"smartrecruiters\.com",
+        r"jobs\.smartrecruiters\.com",
+    ),
+    "recruitee": (r"\.recruitee\.com",),
+    "workable": (
+        r"apply\.workable\.com",
+        r"jobs\.workable\.com",
+    ),
+    "bamboohr": (r"\.bamboohr\.com",),
+    "icims": (r"\.icims\.com",),
+    "taleo": (r"\.taleo\.net",),
+    "successfactors": (
+        r"\.successfactors\.com",
+        r"jobs\.sap\.com",
+    ),
+    "personio": (
+        r"\.personio\.de",
+        r"jobs\.personio\.com",
+    ),
+    "teamtailor": (r"\.teamtailor\.com",),
+    "jobvite": (
+        r"jobs\.jobvite\.com",
+        r"\.jobvite\.com",
+    ),
+    "resumator": (r"applytojob\.com",),
+}
+
+
+def detect_ats(url: str) -> str:
+    """Return the known ATS identifier for a URL, or ``unknown``."""
+
+    for ats, patterns in ATS_PATTERNS.items():
+        for pattern in patterns:
+            if re.search(pattern, url or "", re.IGNORECASE):
+                return ats
+    return "unknown"
+
+
+def normalize_space(value: Any) -> str:
+    """Collapse whitespace for stable text comparisons."""
+
+    return re.sub(r"\s+", " ", str(value or "")).strip()
+
+
+def load_jobs(input_file: Path) -> list[dict[str, Any]]:
+    """Load a JSON job list or object with a ``jobs`` list from an explicit path."""
+
+    payload = json.loads(Path(input_file).read_text(encoding="utf-8"))
+    if isinstance(payload, list):
+        jobs = payload
+    elif isinstance(payload, dict) and isinstance(payload.get("jobs"), list):
+        jobs = payload["jobs"]
+    else:
+        raise ValueError("job input must be a list or an object with a jobs list")
+    if not all(isinstance(job, dict) for job in jobs):
+        raise ValueError("every job entry must be an object")
+    return list(jobs)
+
+
+def load_applied_job_ids(path: Path) -> set[str]:
+    """Load applied job ids from an explicit JSONL path."""
+
+    applied_path = Path(path).expanduser()
+    if not applied_path.exists():
+        return set()
+    ids: set[str] = set()
+    for line in applied_path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(payload, dict):
+            continue
+        job_id = str(payload.get("job_id") or "").strip()
+        if job_id:
+            ids.add(job_id)
+    return ids
+
+
+def append_applied_job_id(
+    path: Path,
+    job_id: str,
+    *,
+    metadata: dict[str, Any] | None = None,
+) -> Path:
+    """Append one applied job id to an explicit JSONL path."""
+
+    clean_job_id = normalize_space(job_id)
+    if not clean_job_id:
+        raise ValueError("job_id is required")
+
+    target = Path(path).expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload: dict[str, Any] = {
+        "job_id": clean_job_id,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+    if metadata:
+        payload["metadata"] = dict(metadata)
+    with target.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(payload, ensure_ascii=False, default=str) + "\n")
+    return target