jobctrl 0.0.1__tar.gz → 2.0.8__tar.gz

jobctrl-2.0.8/.gitignore

@@ -0,0 +1,66 @@
+# User data (NEVER commit)
+profile.json
+resume.txt
+resume.pdf
+*.env
+.env.*
+!.env.example
+
+# Runtime artifacts
+.jobctrl-e2e-state.json
+*.db
+*.db-shm
+*.db-wal
+*.db-journal
+.runtime_tailor_test/
+tailored_resumes/
+cover_letters/
+chrome-workers/
+apply-workers/
+apply_logs/
+logs/
+.dev/
+
+# Local design and planning scratchpads
+handoff_from_design/
+docs/superpowers/
+.planning/
+
+# MCP configs (per-machine)
+.mcp*.json
+
+# Python
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Node
+node_modules/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code
+.claude/
+.codex/
+.venv/
+.worktrees/
+
+# VitePress docs site
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+
+# Generated by @tanstack/router-plugin

jobctrl-2.0.8/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: jobctrl
+Version: 2.0.8
+Summary: AI-powered end-to-end job application pipeline
+Project-URL: Homepage, https://github.com/ebarti/JobCtrl
+Project-URL: Repository, https://github.com/ebarti/JobCtrl
+Project-URL: Issues, https://github.com/ebarti/JobCtrl/issues
+Author: Eloi Barti
+License-Expression: AGPL-3.0-only
+Keywords: ai,apply,automation,job-application,job-search,resume
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: click>=8.3.3
+Requires-Dist: httpx>=0.24
+Requires-Dist: jobstreaming==0.0.2
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0
+Requires-Dist: opentelemetry-sdk>=1.27
+Requires-Dist: pandas>=2.0
+Requires-Dist: playwright>=1.40
+Requires-Dist: publicsuffix2<3,>=2.20191221
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pypdf>=6.14.2
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: temporalio>=1.6
+Requires-Dist: typer>=0.9.0
+Requires-Dist: websocket-client>=1.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: cryptography>=43.0; extra == 'dev'
+Requires-Dist: google-auth>=2.0; extra == 'dev'
+Requires-Dist: hatchling==1.29.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-randomly>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff==0.15.8; extra == 'dev'
+Provides-Extra: providers
+Requires-Dist: claude-agent-sdk==0.2.115; extra == 'providers'
+Requires-Dist: google-antigravity==0.1.2; extra == 'providers'
+Requires-Dist: mcp>=1.28.1; extra == 'providers'
+Requires-Dist: openai-codex-cli-bin==0.137.0a4; extra == 'providers'
+Requires-Dist: openai-codex==0.1.0b3; extra == 'providers'
+Requires-Dist: pyasn1>=0.6.4; extra == 'providers'
+Description-Content-Type: text/markdown
+
+# JobCtrl Automation Worker
+
+This package contains JobCtrl's Python automation engine and CLI. It owns job
+discovery, enrichment, scoring, tailoring, cover letters, PDF generation,
+profile import, and local browser apply automation.
+
+Use it from the repository root through `uv`:
+
+```bash
+uv --project workers/automation run jobctrl doctor
+uv --project workers/automation run jobctrl run
+uv --project workers/automation run jobctrl worker
+```
+
+The full local application is normally started from the repository root with
+`pnpm dev`, which runs Temporal, the TypeScript API, the React web app, and this
+worker together.
+
+Useful docs:
+
+- root `README.md` for the public overview and quick start;
+- `docs/user/getting-started.md` for setup and local stack commands;
+- `docs/user/configuration.md` for environment variables;
+- `docs/architecture/` and `docs/architecture/pipeline/` for internal
+  runtime ownership.
+
+Profile data, generated materials, browser state, logs, and SQLite databases
+are sensitive local artifacts. Do not commit them or include them in public bug
+reports.

jobctrl-2.0.8/README.md

@@ -0,0 +1,29 @@
+# JobCtrl Automation Worker
+
+This package contains JobCtrl's Python automation engine and CLI. It owns job
+discovery, enrichment, scoring, tailoring, cover letters, PDF generation,
+profile import, and local browser apply automation.
+
+Use it from the repository root through `uv`:
+
+```bash
+uv --project workers/automation run jobctrl doctor
+uv --project workers/automation run jobctrl run
+uv --project workers/automation run jobctrl worker
+```
+
+The full local application is normally started from the repository root with
+`pnpm dev`, which runs Temporal, the TypeScript API, the React web app, and this
+worker together.
+
+Useful docs:
+
+- root `README.md` for the public overview and quick start;
+- `docs/user/getting-started.md` for setup and local stack commands;
+- `docs/user/configuration.md` for environment variables;
+- `docs/architecture/` and `docs/architecture/pipeline/` for internal
+  runtime ownership.
+
+Profile data, generated materials, browser state, logs, and SQLite databases
+are sensitive local artifacts. Do not commit them or include them in public bug
+reports.

jobctrl-2.0.8/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "jobctrl"
+version = "2.0.8"
+description = "AI-powered end-to-end job application pipeline"
+readme = "README.md"
+license = "AGPL-3.0-only"
+requires-python = ">=3.11"
+authors = [{ name = "Eloi Barti" }]
+keywords = ["job-search", "automation", "ai", "resume", "apply", "job-application"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+]
+
+dependencies = [
+    "typer>=0.9.0",
+    "click>=8.3.3",
+    "rich>=13.0",
+    "httpx>=0.24",
+    "websocket-client>=1.8",
+    "beautifulsoup4>=4.12",
+    "playwright>=1.40",
+    "python-dotenv>=1.0",
+    "pypdf>=6.14.2",
+    "pyyaml>=6.0",
+    "pandas>=2.0",
+    "temporalio>=1.6",
+    "opentelemetry-api>=1.27",
+    "opentelemetry-sdk>=1.27",
+    "opentelemetry-exporter-otlp-proto-http>=1.27",
+    "opentelemetry-instrumentation-httpx>=0.48b0",
+    # Typed, concurrent job-board events plus resumable checkpoints. Pin the
+    # integration contract so JobCtrl's durable adapter changes deliberately.
+    "jobstreaming==0.0.2",
+    # Pydantic backs the canonical employer-analysis domain model
+    # (``domain/materials/analysis.py``) and is also pulled transitively by
+    # the agent SDKs below. Declared explicitly because the domain layer
+    # imports it directly.
+    "pydantic>=2.10",
+    # Gmail verification scopes derive sender domains from application URLs and
+    # need public-suffix-aware eTLD+1 parsing.
+    "publicsuffix2>=2.20191221,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "cryptography>=43.0",
+    "google-auth>=2.0",
+    "hatchling==1.29.0",
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "pytest-randomly>=4.0",
+    "ruff==0.15.8",
+]
+providers = [
+    "claude-agent-sdk==0.2.115",
+    "mcp>=1.28.1",
+    "openai-codex==0.1.0b3",
+    "openai-codex-cli-bin==0.137.0a4",
+    "google-antigravity==0.1.2",
+    "pyasn1>=0.6.4",
+]
+
+# Source checkouts keep the provider ensemble available on ordinary `uv sync`
+# and `uv run`. Production payload builders use `--no-default-groups --no-dev`
+# and acquire provider wheels separately through the signed provider-pack path.
+[dependency-groups]
+provider-runtime = [
+    "claude-agent-sdk==0.2.115",
+    "openai-codex==0.1.0b3",
+    "openai-codex-cli-bin==0.137.0a4",
+    "google-antigravity==0.1.2",
+]
+release-build = ["build==1.4.3", "hatchling==1.29.0"]
+
+[project.scripts]
+jobctrl = "jobctrl.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/ebarti/JobCtrl"
+Repository = "https://github.com/ebarti/JobCtrl"
+Issues = "https://github.com/ebarti/JobCtrl/issues"
+
+[build-system]
+# Release builds run with --no-isolation, so both the build backend and the
+# locked development environment must resolve this exact, audited backend.
+requires = ["hatchling==1.29.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jobctrl"]
+
+[tool.hatch.build]
+artifacts = ["src/jobctrl/config/*.yaml", "src/jobctrl/assets/fonts/*"]
+
+[tool.hatch.build.targets.sdist.force-include]
+"../../LICENSE" = "LICENSE"
+"../../NOTICE" = "NOTICE"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+markers = [
+    "system_browser: opt-in smoke requiring a real local system Chrome/Chromium; set JOBCTRL_RUN_SYSTEM_BROWSER_TESTS=1",
+]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+extraPaths = ["src"]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+
+[tool.uv]
+default-groups = ["provider-runtime"]
+
+# The workspace dependency cutoff intentionally freezes the broad dependency
+# graph. Keep it as a fixed project value, rather than a caller-provided
+# relative `UV_EXCLUDE_NEWER` value, so locked source runtimes and release
+# workflows resolve against the same graph. Provider runtimes and the audited
+# JobStreaming integration move independently, so admit only their reviewed
+# releases without moving the global cutoff for everything else.
+exclude-newer = "2026-07-09T19:15:43.240437Z"
+exclude-newer-package = { "google-antigravity" = "2026-06-04T21:19:27Z", "claude-agent-sdk" = "2026-07-10T00:00:00Z", "jobstreaming" = "2026-07-18T00:00:00Z" }

jobctrl-2.0.8/src/jobctrl/__init__.py

@@ -0,0 +1,3 @@
+"""JobCtrl — AI-powered end-to-end job application pipeline."""
+
+__version__ = "2.0.8"

jobctrl-2.0.8/src/jobctrl/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m jobctrl`."""
+
+from jobctrl.cli import app
+
+app()

jobctrl-2.0.8/src/jobctrl/actions.py

@@ -0,0 +1,363 @@
+"""Structured local action entrypoints for JobCtrl automation.
+
+These wrappers give API/UI callers one local surface for invoking existing
+Python automation without pasting shell commands. They intentionally delegate to
+the current stage implementations; later phases can replace the internals with
+queue-backed workers without changing the caller contract.
+"""
+
+from __future__ import annotations
+
+import traceback
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+from uuid import uuid4
+
+from jobctrl import config
+from jobctrl.database import get_connection, init_db
+from jobctrl.operational_metrics import record_operational_attempt_metric
+from jobctrl.pipeline import SUPPORTED_STAGE_ORDER
+from jobctrl.state import record_job_event, utc_now
+from jobctrl.workflow_specs import (
+    build_apply_workflow_spec,
+    build_profile_import_workflow_spec,
+    build_run_stage_workflow_spec,
+    start_workflow_spec_and_wait_sync,
+    workflow_result_to_dict,
+)
+
+INTERNAL_PIPELINE_ACTION_STAGES: tuple[str, ...] = (*SUPPORTED_STAGE_ORDER, "enrich")
+ACTION_STAGES: tuple[str, ...] = (*INTERNAL_PIPELINE_ACTION_STAGES, "apply", "profile_import")
+
+
+@dataclass(frozen=True)
+class LocalActionRequest:
+    """Input for a local automation action."""
+
+    stage: str
+    job_url: str | None = None
+    limit: int = 0
+    workers: int = 1
+    min_score: int = 7
+    validation_mode: str = "normal"
+    dry_run: bool = False
+    rescore: bool = False
+    retailor: bool = False
+    tailor_models: tuple[str, ...] = ()
+    tailor_judge_model: str | None = None
+    tailor_judge_min_score: float | None = None
+    model: str = "default"
+    headless: bool = False
+    continuous: bool = False
+    pdf_path: str | None = None
+    import_profile: bool = True
+    import_style: bool = True
+
+
+@dataclass(frozen=True)
+class LocalActionResult:
+    """Structured result returned by every local action wrapper."""
+
+    ok: bool
+    action_id: str
+    stage: str
+    status: str
+    started_at: str
+    finished_at: str
+    duration_ms: int
+    job_url: str | None = None
+    dry_run: bool = False
+    result: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+    traceback: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def run_local_action(request: LocalActionRequest) -> LocalActionResult:
+    """Run one structured local action and record start/finish events."""
+    action_id = f"act-{uuid4().hex}"
+    started_at = utc_now()
+    start = perf_counter()
+
+    if request.stage not in ACTION_STAGES:
+        return LocalActionResult(
+            ok=False,
+            action_id=action_id,
+            stage=request.stage,
+            status="failed",
+            started_at=started_at,
+            finished_at=utc_now(),
+            duration_ms=int((perf_counter() - start) * 1000),
+            job_url=request.job_url,
+            dry_run=request.dry_run,
+            error=f"Unknown action stage: {request.stage}",
+        )
+
+    try:
+        _bootstrap_runtime()
+        _record_action_event(
+            request,
+            "ActionStarted",
+            "info",
+            f"{request.stage} action started",
+            {"action_id": action_id, "dry_run": request.dry_run},
+        )
+
+        if request.stage == "profile_import" and request.dry_run:
+            result = {"planned": _describe_action(request)}
+            return _finish_action(
+                request,
+                action_id,
+                started_at,
+                start,
+                ok=True,
+                status="dry_run",
+                result=result,
+            )
+
+        result = _execute_action(request)
+        ok = _action_succeeded(result)
+        status = "succeeded" if ok else "failed"
+        return _finish_action(request, action_id, started_at, start, ok=ok, status=status, result=result)
+    except Exception as exc:  # noqa: BLE001 - action API must return structured failure
+        return _finish_action(
+            request,
+            action_id,
+            started_at,
+            start,
+            ok=False,
+            status="failed",
+            result={},
+            error=str(exc),
+            traceback_text=traceback.format_exc(),
+        )
+
+
+def run_stage_action(
+    stage: str,
+    *,
+    job_url: str | None = None,
+    limit: int = 0,
+    workers: int = 1,
+    min_score: int = 7,
+    validation_mode: str = "normal",
+    dry_run: bool = False,
+    rescore: bool = False,
+    retailor: bool = False,
+    tailor_models: tuple[str, ...] = (),
+    tailor_judge_model: str | None = None,
+    tailor_judge_min_score: float | None = None,
+) -> LocalActionResult:
+    """Convenience entrypoint for a pipeline stage action."""
+    return run_local_action(
+        LocalActionRequest(
+            stage=stage,
+            job_url=job_url,
+            limit=limit,
+            workers=workers,
+            min_score=min_score,
+            validation_mode=validation_mode,
+            dry_run=dry_run,
+            rescore=rescore,
+            retailor=retailor,
+            tailor_models=tailor_models,
+            tailor_judge_model=tailor_judge_model,
+            tailor_judge_min_score=tailor_judge_min_score,
+        )
+    )
+
+
+def _bootstrap_runtime() -> None:
+    config.load_env()
+    config.ensure_dirs()
+    init_db()
+
+
+def _execute_action(request: LocalActionRequest) -> dict[str, Any]:
+    if request.stage in INTERNAL_PIPELINE_ACTION_STAGES:
+        return _start_and_wait(
+            build_run_stage_workflow_spec(
+                {
+                    "tenantId": "local",
+                    "stage": request.stage,
+                    "minScore": request.min_score,
+                    "dryRun": request.dry_run,
+                    "workers": request.workers,
+                    "validationMode": request.validation_mode,
+                    "limit": request.limit,
+                    "rescore": request.rescore,
+                    "retailor": request.retailor,
+                    "tailorModels": request.tailor_models,
+                    "tailorJudgeModel": request.tailor_judge_model,
+                    "tailorJudgeMinScore": request.tailor_judge_min_score,
+                }
+            )
+        )
+    if request.stage == "apply":
+        return _start_and_wait(
+            build_apply_workflow_spec(
+                {
+                    "tenantId": "local",
+                    "jobUrl": request.job_url,
+                    "limit": _effective_apply_limit(request),
+                    "minScore": request.min_score,
+                    "headless": request.headless,
+                    "model": request.model,
+                    "dryRun": request.dry_run,
+                    "continuous": request.continuous,
+                    "workers": request.workers,
+                }
+            )
+        )
+    if request.stage == "profile_import":
+        if not request.pdf_path:
+            raise ValueError("profile_import requires pdf_path.")
+        return _start_and_wait(
+            build_profile_import_workflow_spec(
+                {
+                    "tenantId": "local",
+                    "pdfPath": str(Path(request.pdf_path).expanduser()),
+                    "importProfile": request.import_profile,
+                    "importStyle": request.import_style,
+                }
+            )
+        )
+    raise ValueError(f"Unknown action stage: {request.stage}")
+
+
+def _start_and_wait(spec) -> dict[str, Any]:
+    started = start_workflow_spec_and_wait_sync(spec)
+    result = workflow_result_to_dict(started.result)
+    return {
+        "status": _workflow_status(result),
+        "runId": started.run_id,
+        "workflowId": started.workflow_id,
+        "firstExecutionRunId": started.first_execution_run_id,
+        **(result if isinstance(result, dict) else {"result": result}),
+    }
+
+
+def _action_succeeded(result: dict[str, Any]) -> bool:
+    if result.get("errors"):
+        return False
+    if int(result.get("failed") or 0) > 0:
+        return False
+    if result.get("failure") or result.get("error"):
+        return False
+    if result.get("ok") is False:
+        return False
+    status = str(result.get("status") or "ok").lower()
+    return not status.startswith("error") and status not in {"failed", "failure"}
+
+
+def _workflow_status(result: Any) -> str:
+    if isinstance(result, dict):
+        if result.get("failure") or result.get("error") or result.get("ok") is False:
+            return "failed"
+        return str(result.get("status") or "succeeded")
+    return "succeeded"
+
+
+def _effective_apply_limit(request: LocalActionRequest) -> int:
+    return 0 if request.continuous else max(1, request.limit)
+
+
+def _finish_action(
+    request: LocalActionRequest,
+    action_id: str,
+    started_at: str,
+    start: float,
+    *,
+    ok: bool,
+    status: str,
+    result: dict[str, Any],
+    error: str | None = None,
+    traceback_text: str | None = None,
+) -> LocalActionResult:
+    finished_at = utc_now()
+    duration_ms = int((perf_counter() - start) * 1000)
+    try:
+        _record_action_event(
+            request,
+            "ActionSucceeded" if ok else "ActionFailed",
+            "info" if ok else "error",
+            f"{request.stage} action {status}",
+            {
+                "action_id": action_id,
+                "duration_ms": duration_ms,
+                "error": error,
+            },
+        )
+        if request.dry_run:
+            _record_dry_run_metric(request, action_id, duration_ms)
+    except Exception:  # noqa: BLE001 - action results must stay JSON-safe when event logging fails
+        pass
+    return LocalActionResult(
+        ok=ok,
+        action_id=action_id,
+        stage=request.stage,
+        status=status,
+        started_at=started_at,
+        finished_at=finished_at,
+        duration_ms=duration_ms,
+        job_url=request.job_url,
+        dry_run=request.dry_run,
+        result=result,
+        error=error,
+        traceback=traceback_text,
+    )
+
+
+def _record_action_event(
+    request: LocalActionRequest,
+    event_type: str,
+    level: str,
+    message: str,
+    payload: dict[str, Any],
+) -> None:
+    conn = get_connection()
+    record_job_event(
+        conn,
+        request.job_url,
+        request.stage,
+        event_type,
+        level=level,
+        message=message,
+        payload=payload,
+    )
+    conn.commit()
+
+
+def _record_dry_run_metric(request: LocalActionRequest, action_id: str, duration_ms: int) -> None:
+    conn = get_connection()
+    record_operational_attempt_metric(
+        conn,
+        stage=request.stage,
+        attempt_kind="local_action",
+        outcome="dry_run",
+        adapter="api",
+        run_id=action_id,
+        job_url=request.job_url,
+        duration_ms=duration_ms,
+        metadata={
+            "workers": request.workers,
+            "limit": request.limit,
+            "rescore": request.rescore,
+            "retailor": request.retailor,
+            "tailor_models": list(request.tailor_models),
+            "tailor_judge_model": request.tailor_judge_model,
+            "tailor_judge_min_score": request.tailor_judge_min_score,
+        },
+    )
+    conn.commit()
+
+
+def _describe_action(request: LocalActionRequest) -> dict[str, Any]:
+    planned = asdict(request)
+    if request.stage == "apply":
+        planned["effective_limit"] = _effective_apply_limit(request)
+    return planned

jobctrl-2.0.8/src/jobctrl/apply/__init__.py

@@ -0,0 +1 @@
+"""Apply pipeline: Chrome management, prompt building, orchestration, and dashboard."""