Metadata-Version: 2.4
Name: karyab
Version: 0.1.0
Summary: Personal job-finding automation: fetch, rank, track job postings.
Project-URL: Repository, https://codeberg.org/maxagahi/karyab
Author: maxagahi
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: automation,cli,job-search,jobs
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: oauth
Requires-Dist: msal>=1.28; extra == 'oauth'
Provides-Extra: rank
Requires-Dist: anthropic>=0.40; extra == 'rank'
Provides-Extra: ui
Requires-Dist: fastapi>=0.110; extra == 'ui'
Requires-Dist: jinja2>=3.1; extra == 'ui'
Requires-Dist: markdown>=3.6; extra == 'ui'
Requires-Dist: python-multipart>=0.0.9; extra == 'ui'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'ui'
Description-Content-Type: text/markdown

# karyab

**kaaryab** (Persian _کاریاب_, "job finder") — a personal job-hunting automation.

karyab fetches job postings from multiple sources, ranks them against your
profile, builds a daily shortlist you can act on, and tracks the applications
you submit — nudging you to follow up when a posting goes quiet.

> **Privacy by design.** This repository contains **code, workflows and setup
> only**. Your personal data — profile, CV, API keys, the application database —
> never lives in the repo. It lives under your XDG directories
> (`~/.config/karyab`, `~/.local/share/karyab`). See [AGENTS.md](AGENTS.md) and
> [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## What it does

```
 sources ──▶ normalize ──▶ store ──▶ rank ──▶ digest ──▶ you apply
                                                            │
                                                  track ◀───┘
                                                    │
                                            follow-up nudges
```

- **Fetch** from ATS feeds (Greenhouse / Lever / Ashby), aggregator APIs
  (Adzuna / The Muse / Remotive), parsed email job-alerts, and remote-job boards.
- **Rank** each posting for fit against your profile using an LLM, with a cheap
  pre-filter and a short human-readable reason per match.
- **Digest** the top new matches into a daily Markdown file (and, later, an MCP
  server you query from inside Claude Code).
- **Track** the jobs you apply to through a status lifecycle, and surface stale
  applications (applied, no response in N days) so you remember to follow up.

## Status

Early scaffold. **What actually runs today vs. what is planned** is tracked
honestly in [docs/ROADMAP.md](docs/ROADMAP.md). Modules that are not yet
implemented raise `NotImplementedError` rather than pretending to work.

## Quick start

`make` is the single interface — it owns a local `.venv`, so you never manage
dependencies by hand. `make help` lists everything.

```bash
make setup          # install + create config/secrets + init the database
make config         # edit your profile, sources, and keys (config + secrets)
make run            # fetch -> rank -> digest (the daily cycle)
```

Then, day to day:

```bash
make fetch          # pull + store postings from enabled sources
make rank           # score stored jobs for fit
make digest         # render the markdown shortlist
make show-digest    # print the latest digest
make followups      # applications gone quiet
make apply JOB=<id> # mark a job applied
make mcp            # run the MCP server for Claude Code
```

Schedule the daily fetch with a systemd user timer:

```bash
make timers-install # enable the daily timer   (make timers-status / -logs / -uninstall)
```

See [docs/PLAN.md](docs/PLAN.md) for the build plan and module interfaces.

## Reading Outlook/Microsoft mail (OAuth2)

karyab supports OAuth2 device-code authentication for Microsoft IMAP
(personal `@outlook.com` / `@hotmail.com` accounts, and work accounts with
the right Azure permissions).

**One-time setup:**

1. In `~/.config/karyab/config.toml`, configure the email source:

   ```toml
   [sources.email]
   enabled = true
   imap_host  = "outlook.office365.com"
   folder     = "INBOX"
   username   = "you@outlook.com"
   auth       = "oauth"
   # oauth_client_id = "9e5f94bc-e8a4-4e73-b8be-63364c29d753"  # Thunderbird client (default)
   # oauth_authority = "https://login.microsoftonline.com/consumers"  # personal accounts
   ```

2. Authenticate once:

   ```bash
   karyab email-auth
   # Prints a URL and a short code. Open the URL in your browser, enter the code.
   # karyab waits, then caches the refresh token in ~/.local/share/karyab/ms-token-cache.json
   ```

3. Subsequent `karyab fetch` runs refresh the token silently — no browser needed.

**If the default client ID stops working** (Microsoft has restricted the
Thunderbird public client in some regions), register a free Azure app:
`portal.azure.com → App registrations → New registration → allow public client
flows → add delegated permission IMAP.AccessAsUser.All`. Set the resulting
Application ID as `oauth_client_id` in your config.

For Gmail and other providers, use `auth = "basic"` (default) and store your
app password in `~/.config/karyab/secrets.toml`.

## Ranking with Claude Code (no API key)

Set `[ranker] backend = "manual"` in `~/.config/karyab/config.toml`, then start
the MCP server and ask Claude Code to rank your jobs:

```toml
[ranker]
backend = "manual"
```

```bash
make mcp   # starts karyab-mcp in stdio mode for Claude Code
```

In Claude Code, use the MCP tools:

1. `get_profile` — review your candidate profile
2. `list_unranked_jobs` — see jobs pending a score
3. `set_job_rank` — score each job 0–100 with a short reason

After scoring, run `make digest` to build the shortlist from the scores you set.

## Development

```bash
make dev            # install dev+runtime deps into .venv + git hooks
make test           # run tests
make check          # lint, format, type-check, secret-scan everything
```

Conventions, the no-secrets rule, and how data is laid out on disk live in
[AGENTS.md](AGENTS.md).

## License

[Apache-2.0](LICENSE).
