linkedin-apply-assistant 0.1.1

package/src/linkedin_apply_assistant/safety.py

@@ -0,0 +1,230 @@
+"""Safety policy, bounded audit metadata, and automation limits."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import urlparse, urlunparse
+
+from .contracts import SubmissionResult, SubmitDecision
+
+
+POLICY_NAME = "phase16-disabled-submit-policy"
+POLICY_VERSION = "2026-06-07"
+DISABLED_SUBMISSION_REASON = "Browser submission is disabled in this package boundary."
+FUTURE_SUBMIT_POLICY = (
+    "Any future submit-capable release must require per-application interactive "
+    "confirmation immediately before the specific application is sent. Broad approvals, "
+    "background sending, and unattended modes are outside this package boundary."
+)
+
+SEARCH_LIMIT_DEFAULT = 10
+SEARCH_LIMIT_CAP = 25
+ASSIST_CYCLES_DEFAULT = 1
+ASSIST_CYCLES_CAP = 25
+
+BROWSER_PROFILE_WARNING = (
+    "Browser profile warning: visible browser profiles can contain cookies, sessions, "
+    "and local form data. Keep the profile directory local, ignored, and under your "
+    "control."
+)
+
+RISK_STATUSES = frozenset({"login", "mfa", "checkpoint", "captcha", "rate_limited", "throttled"})
+
+
+def utc_timestamp() -> str:
+    """Return a stable UTC timestamp for audit records."""
+
+    return datetime.now(timezone.utc).isoformat()
+
+
+def domain_from_url(url: str | None) -> str:
+    """Return a lower-case hostname without userinfo or port."""
+
+    value = str(url or "").strip()
+    parsed = urlparse(value)
+    hostname = parsed.hostname
+    if not hostname and "://" not in value and "/" not in value:
+        hostname = value
+    return (hostname or "").lower().rstrip(".")
+
+
+def normalize_url_for_audit(url: str | None) -> str:
+    """Return bounded URL metadata suitable for local reports."""
+
+    parsed = urlparse(str(url or ""))
+    if parsed.scheme.lower() not in {"http", "https"} or not parsed.hostname:
+        return ""
+    netloc = parsed.hostname.lower().rstrip(".")
+    if parsed.port:
+        netloc = f"{netloc}:{parsed.port}"
+    path = (parsed.path or "").rstrip("/")
+    return urlunparse((parsed.scheme.lower(), netloc, path, "", "", ""))
+
+
+def clamp_search_limit(value: int | str | None) -> int:
+    """Clamp public search requests to the package safety boundary."""
+
+    return _clamp_non_negative_int(value, SEARCH_LIMIT_CAP)
+
+
+def clamp_assist_cycles(value: int | str | None) -> int:
+    """Clamp public assist cycles to the package safety boundary."""
+
+    return _clamp_non_negative_int(value, ASSIST_CYCLES_CAP)
+
+
+def _clamp_non_negative_int(value: int | str | None, cap: int) -> int:
+    try:
+        parsed = int(value) if value is not None else 0
+    except (TypeError, ValueError):
+        parsed = 0
+    return min(max(parsed, 0), cap)
+
+
+def backoff_delay(
+    attempt: int,
+    *,
+    base_seconds: float = 1.0,
+    cap_seconds: float = 30.0,
+) -> float:
+    """Return deterministic exponential backoff seconds without sleeping."""
+
+    if attempt <= 0:
+        return 0.0
+    delay = base_seconds * (2 ** (attempt - 1))
+    return min(float(delay), float(cap_seconds))
+
+
+class DisabledSubmissionPolicy:
+    """Submission policy that blocks every browser submission action."""
+
+    policy = POLICY_NAME
+
+    def decide(
+        self,
+        action: str,
+        context: dict[str, Any] | None = None,
+    ) -> SubmissionResult:
+        return SubmissionResult(
+            status="disabled",
+            reason=DISABLED_SUBMISSION_REASON,
+            allowed=False,
+        )
+
+    def submit_decision(
+        self,
+        action: str,
+        *,
+        command: str = "apply",
+        context: dict[str, Any] | None = None,
+        confirmation_state: str = "",
+    ) -> SubmitDecision:
+        ctx = dict(context or {})
+        url = normalize_url_for_audit(ctx.get("url") or ctx.get("apply_url") or "")
+        domain = domain_from_url(url or ctx.get("domain") or "")
+        return SubmitDecision(
+            timestamp=utc_timestamp(),
+            command=command,
+            policy=f"{POLICY_NAME}@{POLICY_VERSION}",
+            action=str(action or "submit"),
+            allowed=False,
+            status="disabled",
+            reason=DISABLED_SUBMISSION_REASON,
+            company=str(ctx.get("company") or ""),
+            role=str(ctx.get("role") or ctx.get("title") or ""),
+            url=url,
+            domain=domain,
+            ats=str(ctx.get("ats") or ""),
+            confirmation_state=str(confirmation_state or "not_confirmed"),
+        )
+
+    def audit_event(
+        self,
+        action: str,
+        *,
+        command: str = "apply",
+        context: dict[str, Any] | None = None,
+        confirmation_state: str = "",
+    ) -> dict[str, Any]:
+        """Return a dictionary audit event for report writers."""
+
+        return asdict(
+            self.submit_decision(
+                action,
+                command=command,
+                context=context,
+                confirmation_state=confirmation_state,
+            )
+        )
+
+
+def disabled_submit_audit_payload(
+    *,
+    command: str = "apply",
+    action: str = "submit",
+    context: dict[str, Any] | None = None,
+    confirmation_state: str = "",
+) -> dict[str, Any]:
+    """Build a privacy-bounded disabled submit audit payload."""
+
+    decision = DisabledSubmissionPolicy().audit_event(
+        action,
+        command=command,
+        context=context,
+        confirmation_state=confirmation_state,
+    )
+    return {
+        "command": command,
+        "timestamp": decision["timestamp"],
+        "decision": decision,
+        "events": [
+            {
+                "type": "submit_decision",
+                "action": action,
+                "status": decision["status"],
+                "allowed": decision["allowed"],
+                "policy": decision["policy"],
+                "reason": decision["reason"],
+                "company": decision["company"],
+                "role": decision["role"],
+                "url": decision["url"],
+                "domain": decision["domain"],
+                "ats": decision["ats"],
+                "confirmation_state": decision["confirmation_state"],
+                "timestamp": decision["timestamp"],
+            }
+        ],
+        "summary": {
+            "command": command,
+            "policy": decision["policy"],
+            "action": action,
+            "status": decision["status"],
+            "allowed": decision["allowed"],
+            "submitted": 0,
+            "reason": decision["reason"],
+            "confirmation_state": decision["confirmation_state"],
+        },
+    }
+
+
+__all__ = [
+    "ASSIST_CYCLES_CAP",
+    "ASSIST_CYCLES_DEFAULT",
+    "BROWSER_PROFILE_WARNING",
+    "DISABLED_SUBMISSION_REASON",
+    "DisabledSubmissionPolicy",
+    "FUTURE_SUBMIT_POLICY",
+    "POLICY_NAME",
+    "POLICY_VERSION",
+    "RISK_STATUSES",
+    "SEARCH_LIMIT_CAP",
+    "SEARCH_LIMIT_DEFAULT",
+    "backoff_delay",
+    "clamp_assist_cycles",
+    "clamp_search_limit",
+    "disabled_submit_audit_payload",
+    "domain_from_url",
+    "normalize_url_for_audit",
+]

package/src/linkedin_apply_assistant/workflows.py

@@ -0,0 +1,435 @@
+"""Selector-light workflow orchestration."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Mapping, Sequence
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
+
+from .contracts import (
+    AssistEvent,
+    AssistRequest,
+    AssistResult,
+    BrowserSession,
+    BrowserSessionFactory,
+    FillAdapter,
+    JobRecord,
+    LinkedInDiscovery,
+    ReportArtifact,
+    ReportSink,
+    SearchRequest,
+    SearchResult,
+    SubmissionPolicy,
+    SurfaceIdentity,
+)
+from .form_engine import DetectionResult, FillResult, normalize_space
+from .linkedin_layer import DEFAULT_SEARCH_URL, sanitize_linkedin_search_url
+from .safety import (
+    clamp_assist_cycles,
+    clamp_search_limit,
+    domain_from_url,
+    normalize_url_for_audit,
+)
+
+
+def utc_timestamp() -> str:
+    """Return an ISO timestamp for reports."""
+
+    return datetime.now(timezone.utc).isoformat()
+
+
+def build_search_url(request: SearchRequest) -> str:
+    """Build or sanitize the LinkedIn jobs search URL for a request."""
+
+    if request.search_url:
+        return sanitize_linkedin_search_url(request.search_url)
+
+    parsed = urlparse(DEFAULT_SEARCH_URL)
+    query: dict[str, list[str]] = {}
+    if request.query:
+        query["keywords"] = [request.query]
+    if request.location:
+        query["location"] = [request.location]
+    return urlunparse(
+        (
+            parsed.scheme,
+            parsed.netloc,
+            parsed.path,
+            "",
+            urlencode(query, doseq=True),
+            "",
+        )
+    )
+
+
+def normalized_job_url(url: str) -> str:
+    """Normalize a job URL enough for within-run deduplication."""
+
+    parsed = urlparse(url or "")
+    query = parse_qs(parsed.query)
+    for key in ("trk", "refId", "trackingId", "position", "pageNum"):
+        query.pop(key, None)
+    return urlunparse(
+        (
+            parsed.scheme.lower(),
+            parsed.netloc.lower(),
+            parsed.path.rstrip("/"),
+            "",
+            urlencode(query, doseq=True),
+            "",
+        )
+    )
+
+
+def job_from_record(record: JobRecord | Mapping[str, Any], *, search_url: str = "") -> JobRecord:
+    """Convert a mapping or JobRecord into the stable JobRecord shape."""
+
+    if isinstance(record, JobRecord):
+        if search_url and not record.search_url:
+            return JobRecord(**{**record.__dict__, "search_url": search_url})
+        return record
+
+    raw = dict(record)
+    job_id = normalize_space(raw.get("job_id") or raw.get("linkedin_job_id") or raw.get("id") or "")
+    url = normalize_space(raw.get("url") or raw.get("linkedin_url") or "")
+    return JobRecord(
+        job_id=job_id,
+        title=normalize_space(raw.get("title") or raw.get("role") or ""),
+        company=normalize_space(raw.get("company") or ""),
+        url=url,
+        location=normalize_space(raw.get("location") or ""),
+        source=normalize_space(raw.get("source") or "linkedin"),
+        search_url=normalize_space(raw.get("search_url") or search_url),
+        ats=normalize_space(raw.get("ats") or ""),
+        raw=raw,
+    )
+
+
+def dedupe_jobs(
+    records: Sequence[JobRecord | Mapping[str, Any]], *, search_url: str
+) -> list[JobRecord]:
+    """Deduplicate by LinkedIn job id first, then normalized URL fallback."""
+
+    seen: set[str] = set()
+    jobs: list[JobRecord] = []
+    for record in records:
+        job = job_from_record(record, search_url=search_url)
+        dedupe_key = f"id:{job.job_id}" if job.job_id else f"url:{normalized_job_url(job.url)}"
+        if not dedupe_key or dedupe_key in seen:
+            continue
+        seen.add(dedupe_key)
+        jobs.append(job)
+    return jobs
+
+
+def _job_payload(job: JobRecord) -> dict[str, Any]:
+    url = normalize_url_for_audit(job.url)
+    search_url = normalize_url_for_audit(job.search_url)
+    return {
+        "job_id": job.job_id,
+        "title": job.title,
+        "company": job.company,
+        "url": url,
+        "domain": domain_from_url(url),
+        "location": job.location,
+        "source": job.source,
+        "search_url": search_url,
+        "ats": job.ats,
+    }
+
+
+def _report_artifacts(artifacts: Sequence[ReportArtifact] | None) -> list[ReportArtifact]:
+    return list(artifacts or [])
+
+
+def run_search_workflow(
+    request: SearchRequest,
+    discovery: LinkedInDiscovery,
+    report_sink: ReportSink,
+    submission_policy: SubmissionPolicy | None = None,
+) -> SearchResult:
+    """Run search-only discovery, deduplication, and reporting."""
+
+    search_url = build_search_url(request)
+    effective_limit = clamp_search_limit(request.limit)
+    records: Sequence[JobRecord | Mapping[str, Any]] = []
+    if effective_limit > 0:
+        records = discovery.discover(
+            SearchRequest(
+                limit=effective_limit,
+                search_url=search_url,
+                query=request.query,
+                location=request.location,
+                profile=dict(request.profile),
+                paths=request.paths,
+            )
+        )
+
+    jobs = dedupe_jobs(records, search_url=search_url)[:effective_limit]
+    timestamp = utc_timestamp()
+    events = [
+        {
+            "type": "job",
+            "action": "discovered",
+            "status": "recorded",
+            "surface": "linkedin_search",
+            "ats": job.ats,
+            "blocked_reason": "",
+            "unknown_questions": [],
+            "required_empty_count": 0,
+            **_job_payload(job),
+        }
+        for job in jobs
+    ]
+    summary = {
+        "command": "search",
+        "requested_limit": request.limit,
+        "effective_limit": effective_limit,
+        "discovered": len(records),
+        "deduplicated": len(jobs),
+        "submitted": 0,
+    }
+    report = {
+        "command": "search",
+        "timestamp": timestamp,
+        "search_url": search_url,
+        "jobs": [_job_payload(job) for job in jobs],
+        "events": events,
+        "summary": summary,
+    }
+    artifacts = _report_artifacts(report_sink.write("search", report))
+    return SearchResult(
+        timestamp=timestamp,
+        search_url=search_url,
+        jobs=jobs,
+        events=events,
+        summary=summary,
+        reports=artifacts,
+    )
+
+
+def surface_identity_from_detection(detection: DetectionResult) -> SurfaceIdentity:
+    """Build a stable fill-once identity for a detected surface."""
+
+    page = detection.page
+    url = normalize_space(getattr(page, "url", "") if page is not None else "")
+    title_attr = getattr(page, "title", "")
+    title = title_attr() if callable(title_attr) else title_attr
+    context = dict(detection.job_context or {})
+    return SurfaceIdentity(
+        url=url or normalize_space(context.get("apply_url") or context.get("url") or ""),
+        title=normalize_space(title or context.get("title") or context.get("role") or ""),
+        surface=normalize_space(detection.surface),
+        ats=normalize_space(detection.ats),
+        job_id=normalize_space(context.get("job_id") or ""),
+    )
+
+
+def _assist_event(
+    event_type: str,
+    detection: DetectionResult,
+    result: FillResult,
+    identity: SurfaceIdentity,
+    *,
+    status: str,
+    blocked_reason: str = "",
+) -> AssistEvent:
+    return AssistEvent(
+        type=event_type,
+        surface=detection.surface,
+        ats=detection.ats,
+        status=status,
+        filled_count=len(result.filled),
+        required_empty_count=len(result.required_empty),
+        unknown_count=len(result.unknown_questions),
+        reached_submit_step=bool(result.reached_submit_step),
+        blocked_reason=blocked_reason,
+        job=dict(detection.job_context or {}),
+        identity=identity,
+        required_empty=list(result.required_empty),
+        unknown_questions=list(result.unknown_questions),
+        timestamp=utc_timestamp(),
+    )
+
+
+def _event_payload(event: AssistEvent) -> dict[str, Any]:
+    job = _bounded_job_context(event.job)
+    identity = _identity_payload(event.identity)
+    return {
+        "type": event.type,
+        "action": event.type,
+        "timestamp": event.timestamp,
+        "surface": event.surface,
+        "ats": event.ats,
+        "status": event.status,
+        "filled_count": event.filled_count,
+        "required_empty_count": event.required_empty_count,
+        "unknown_count": event.unknown_count,
+        "reached_submit_step": event.reached_submit_step,
+        "blocked_reason": event.blocked_reason,
+        "job": job,
+        "identity": identity,
+        "required_empty": list(event.required_empty),
+        "unknown_questions": [_unknown_question_payload(item) for item in event.unknown_questions],
+        "feedback": compact_assist_feedback(event),
+    }
+
+
+def _bounded_job_context(context: Mapping[str, Any] | None) -> dict[str, Any]:
+    ctx = dict(context or {})
+    url = normalize_url_for_audit(ctx.get("apply_url") or ctx.get("url") or "")
+    domain = domain_from_url(url or ctx.get("domain") or "")
+    return {
+        "job_id": normalize_space(ctx.get("job_id") or ""),
+        "company": normalize_space(ctx.get("company") or ""),
+        "role": normalize_space(ctx.get("role") or ctx.get("title") or ""),
+        "title": normalize_space(ctx.get("title") or ctx.get("role") or ""),
+        "url": url,
+        "domain": domain,
+        "ats": normalize_space(ctx.get("ats") or ""),
+    }
+
+
+def _identity_payload(identity: SurfaceIdentity | None) -> dict[str, Any]:
+    if identity is None:
+        return {}
+    url = normalize_url_for_audit(identity.url)
+    return {
+        "url": url,
+        "domain": domain_from_url(url),
+        "title": identity.title,
+        "surface": identity.surface,
+        "ats": identity.ats,
+        "job_id": identity.job_id,
+    }
+
+
+def _unknown_question_payload(item: Any) -> dict[str, Any] | str:
+    if not isinstance(item, Mapping):
+        return normalize_space(item)
+    url = normalize_url_for_audit(item.get("apply_url") or item.get("url") or "")
+    return {
+        "question": normalize_space(item.get("question") or ""),
+        "field_type": normalize_space(item.get("field_type") or "text"),
+        "required": bool(item.get("required")),
+        "ats": normalize_space(item.get("ats") or ""),
+        "company": normalize_space(item.get("company") or ""),
+        "role": normalize_space(item.get("role") or item.get("title") or ""),
+        "domain": domain_from_url(url or item.get("domain") or ""),
+    }
+
+
+def compact_assist_feedback(event: AssistEvent) -> str:
+    """Return one compact user-facing assist feedback line."""
+
+    surface = event.surface or "none"
+    ats = event.ats or "unknown"
+    return (
+        f"{surface}/{ats} status={event.status or 'unknown'} "
+        f"filled={event.filled_count} required_empty={event.required_empty_count} "
+        f"unknown={event.unknown_count} submit_step={str(event.reached_submit_step).lower()}"
+    )
+
+
+def run_assist_workflow(
+    request: AssistRequest,
+    session_factory: BrowserSessionFactory,
+    detector: Any,
+    fill_adapter: FillAdapter,
+    report_sink: ReportSink,
+    submission_policy: SubmissionPolicy | None = None,
+    bank: Any = None,
+) -> AssistResult:
+    """Run one bounded assistive fill-only session."""
+
+    session: BrowserSession | None = None
+    events: list[AssistEvent] = []
+    seen: set[str] = set()
+    timestamp = utc_timestamp()
+    try:
+        session = session_factory.open(request)
+        if request.start_url:
+            session.open_url(request.start_url)
+
+        cycles = clamp_assist_cycles(request.max_cycles)
+        for _ in range(cycles):
+            detection = detector.detect(session)
+            if detection.surface == "none":
+                continue
+            identity = surface_identity_from_detection(detection)
+            if detection.surface == "browser_blocked":
+                blocked_reason = normalize_space(
+                    detection.job_context.get("blocked_reason")
+                    or "Visible browser requires user action."
+                )
+                events.append(
+                    _assist_event(
+                        "blocked",
+                        detection,
+                        FillResult(surface=detection.surface),
+                        identity,
+                        status="blocked",
+                        blocked_reason=blocked_reason,
+                    )
+                )
+                continue
+            if identity.key() in seen:
+                events.append(
+                    AssistEvent(
+                        type="skipped",
+                        surface=detection.surface,
+                        ats=detection.ats,
+                        status="duplicate",
+                        job=dict(detection.job_context or {}),
+                        identity=identity,
+                        timestamp=utc_timestamp(),
+                    )
+                )
+                continue
+            seen.add(identity.key())
+            fill_surface = getattr(fill_adapter, "fill")
+            fill_result = fill_surface(
+                detection,
+                dict(request.profile),
+                bank,
+                dict(request.qa_context),
+                dict(request.documents),
+            )
+            status = "blocked" if fill_result.required_empty else "filled"
+            blocked_reason = "; ".join(str(item) for item in fill_result.required_empty)
+            events.append(
+                _assist_event(
+                    "filled",
+                    detection,
+                    fill_result,
+                    identity,
+                    status=status,
+                    blocked_reason=blocked_reason,
+                )
+            )
+    finally:
+        # Live sessions are intentionally visible; factories can choose no-op close.
+        if session is not None and getattr(session, "close_on_exit", False):
+            session.close()
+
+    summary = {
+        "command": "assist",
+        "mode": request.mode,
+        "requested_cycles": request.max_cycles,
+        "effective_cycles": clamp_assist_cycles(request.max_cycles),
+        "events": len(events),
+        "filled": sum(1 for event in events if event.type == "filled"),
+        "blocked": sum(1 for event in events if event.status == "blocked"),
+        "duplicates": sum(1 for event in events if event.status == "duplicate"),
+        "required_empty": sum(event.required_empty_count for event in events),
+        "unknown_questions": sum(event.unknown_count for event in events),
+        "submitted": 0,
+    }
+    report = {
+        "command": "assist",
+        "timestamp": timestamp,
+        "events": [_event_payload(event) for event in events],
+        "summary": summary,
+    }
+    artifacts = _report_artifacts(report_sink.write("assist", report))
+    return AssistResult(timestamp=timestamp, events=events, summary=summary, reports=artifacts)