Metadata-Version: 2.4
Name: evidence-job-hunt
Version: 0.1.0
Summary: Evidence-gated, human-in-the-loop job discovery and triage CLI
Author: Job Hunt Contributors
License: MIT License
        
        Copyright (c) 2026 Job Hunt contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Tesliana-code/job-hunt
Project-URL: Repository, https://github.com/Tesliana-code/job-hunt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7.0,>=6.0
Dynamic: license-file

# Job Hunt

An evidence-gated, human-in-the-loop CLI for finding and triaging jobs.

Job Hunt discovers listings from public company hiring systems, removes duplicates, scores the remaining roles against claims you have verified, and builds a short daily report. It can prepare context for semantic analysis and application materials. Every application remains a human decision.

## Install

Job Hunt is distributed as the `evidence-job-hunt` Python package. The installed command is `jobhunt`.

```bash
pipx install evidence-job-hunt
```

If `pipx` is missing, follow the [official pipx installation guide](https://pipx.pypa.io/stable/installation/).

Job Hunt requires Python 3.10 or newer.

## First run

```bash
jobhunt init
jobhunt doctor
```

`jobhunt init` asks a few plain-language questions about:

- the roles you want;
- where you can work;
- technologies you can honestly claim;
- compensation and excluded industries;
- one concrete piece of verified professional evidence.

It creates a private workspace in `~/.jobhunt`. Your profile, listings, decisions, and generated reports stay there rather than inside the installed package.

When configuration is valid, `jobhunt doctor` ends with:

```text
RESULT: READY
```

## Morning routine

```bash
jobhunt daily
jobhunt open
```

`daily` reads configured public Ashby, Greenhouse, and Lever boards, filters titles, normalizes descriptions, removes previously seen listings, calculates provisional evidence-based scores, and writes the daily report.

`open` opens the report folder. The shortlist is deliberately small enough to inspect rather than another feed to scroll.

To preview discovery without writing jobs or changing state:

```bash
jobhunt discover --preview
```

## LinkedIn searches

```bash
jobhunt linkedin --freshness day
```

This generates targeted LinkedIn search links. It does not log into LinkedIn, scrape an account, or automate applications. You open the searches and choose listings manually.

## One manually selected listing

Save the public job description as a text file, then run:

```bash
jobhunt ingest PATH_TO_JOB.txt
```

The same normalization, deduplication, and scoring pipeline is used.

## From candidate to application

Mechanical scores are provisional. A title can say “AI” while the actual job requires browser internals, Kubernetes operations, or another profession entirely.

Prepare a self-contained semantic-analysis bundle:

```bash
jobhunt analyze JOB
```

After reviewing the evidence map and gaps, record a decision:

```bash
jobhunt decide JOB SHORTLISTED \
  --analysis-score 74 \
  --analysis-recommendation "STRONG MATCH" \
  --reason "Evidence-backed reason for the decision."
```

Optional stretch assessment remains separate from factual fit:

```bash
jobhunt stretch JOB STRETCH_CANDIDATE \
  --direct-matches 4 \
  --core-gap "Explicit missing requirement" \
  --hard-blockers 0 \
  --learning-ramp-weeks 8 \
  --reason "Why this is a credible bounded stretch."
```

For an eligible shortlisted role:

```bash
jobhunt application-bundle JOB
```

The lifecycle is explicit:

```text
DISCOVERED → REJECTED / MAYBE / SHORTLISTED
SHORTLISTED → APPROVED_TO_APPLY → APPLIED
```

Only record `APPLIED` after you have submitted the application yourself.

## Why the evidence registry exists

`~/.jobhunt/profile/evidence.yaml` is the factual boundary. Each claim has safe wording, technologies, evidence strength, and forbidden exaggerations.

The mechanical layer can match and score those claims. An LLM can interpret whether the evidence is direct, transferable, missing, or blocked. Neither layer receives permission to invent experience or turn an experiment into production work.

## Useful commands

```text
jobhunt init                         Create a private workspace
jobhunt doctor                       Validate configuration
jobhunt daily                        Run discovery, triage, and reporting
jobhunt open                         Open the report folder
jobhunt discover --preview           Preview public ATS matches
jobhunt linkedin --freshness day     Generate manual LinkedIn searches
jobhunt ingest JOB.txt               Process one saved listing
jobhunt analyze JOB                  Prepare semantic-analysis context
jobhunt decide JOB STATE             Record a human lifecycle decision
jobhunt stretch JOB STATUS           Record a stretch assessment
jobhunt application-bundle JOB       Prepare gated application context
jobhunt help                          Show CLI help
```

## Private workspace

The default workspace is `~/.jobhunt`. To use another location:

```bash
export JOBHUNT_HOME="$HOME/my-job-search"
```

Back up this directory if you want to preserve listing history and lifecycle decisions.

Advanced users can edit the generated YAML, profile, evidence registry, resume template, discovery targets, and prompts directly. See [GETTING_STARTED.md](GETTING_STARTED.md).

## Safety boundary

Job Hunt does not submit forms, contact employers, send outreach, fabricate qualifications, or automate a LinkedIn account. It prepares evidence and preserves an audit trail; the candidate controls every consequential action.

## Development

```bash
git clone https://github.com/Tesliana-code/job-hunt.git
cd job-hunt
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v
```

The project is licensed under the MIT License.
