Metadata-Version: 2.4
Name: job-hunter-kit
Version: 0.1
Summary: Job search automation with LLM API pipeline mode and Claude Code agent mode.
Author: Abdul Basit
License: MIT
Project-URL: Homepage, https://github.com/abdulrbasit/job-hunter
Project-URL: Repository, https://github.com/abdulrbasit/job-hunter
Project-URL: Issues, https://github.com/abdulrbasit/job-hunter/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: anthropic>=0.50.0
Requires-Dist: openai>=1.68.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-jobspy>=0.20.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: headroom-ai>=0.1.0; sys_platform != "win32"
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == "browser"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ty>=0.0.1a20; extra == "dev"
Provides-Extra: secrets
Requires-Dist: keyring>=24.0.0; extra == "secrets"
Provides-Extra: all
Requires-Dist: job-hunter-kit[browser,secrets]; extra == "all"
Dynamic: license-file

# Job Hunter

Job Hunter is an installable Python package for running a personal job-search workspace. It has one CLI and two modes:

- `agent`: Python handles deterministic work; Claude/Codex skills handle screening, scoring, tailoring, and writing.
- `llm-api`: Python runs the autonomous LLM-backed pipeline for unattended jobs.

The default mode is `agent`.

## Install

```bash
pip install job-hunter-kit
# or
uv tool install job-hunter-kit
```

## Create a Workspace

```bash
job-hunter init my-job-hunter-workspace
cd my-job-hunter-workspace
cp .env.example .env
job-hunter config check
job-hunter doctor
```

Edit `config/job_hunter.yml` with deterministic machine choices: titles, regions, exclusions, profile paths, mode, scoring thresholds, LLM search gate, and provider/model choices. Put personal positioning and writing preferences in `profile/career_context.md`. Secrets use fixed environment variable names in `.env` or GitHub Actions.

## Daily Use

```bash
job-hunter hunt --region primary
job-hunter brief
job-hunter dashboard --no-interactive
```

In `agent` mode, open the workspace in Claude Code or Codex and use:

```text
/job-hunter brief
/job-hunter batch
/job-hunter one <url>
/job-hunter finalize
```

In `llm-api` mode, `job-hunter hunt` runs scrape, score, tailor, cover letter, PDF, tracker, and README updates in one pipeline.

## Public CLI

- `job-hunter init <workspace>` creates a workspace.
- `job-hunter config check` validates `config/job_hunter.yml`.
- `job-hunter doctor` checks setup health.
- `job-hunter hunt` discovers and enriches jobs.
- `job-hunter brief` writes the daily briefing.
- `job-hunter tailor` processes provided job URLs or JD text.
- `job-hunter dashboard`, `job-hunter applications`, and `job-hunter analytics` inspect application state.
- `job-hunter update-skills` refreshes bundled `.claude/skills/` only.
- `job-hunter version` and `job-hunter update-info` show version and upgrade guidance.

Support commands such as `agent-context`, `import-job`, `compile-pdf`, `update-readme`, `mark-processed`, `discard-job`, `cleanup-transient`, and `finalize-run` exist for skills and automation.

## Data Contract

Deterministic user choices live in `config/job_hunter.yml`; human career and writing guidance lives in `profile/career_context.md`. Persistent URL dedup lives in `outputs/state/discovered_urls.yml`. Product updates must not overwrite `config/`, `profile/`, `outputs/`, or `.env`.

See `DATA_CONTRACT.md` for the full contract.

## Development

```bash
uv sync --extra dev
uv run pytest tests/ -q --tb=short
uv run ruff format --check job_hunter tests .github/scripts
uv run ruff check job_hunter tests .github/scripts
uv run ty check job_hunter tests
uv build
```

MIT licensed. See `CONTRIBUTING.md`.
