README's tabs table now matches two tabs and the settings cog, and mentions the read page, votes, and the Fetch/Summarise buttons. docs/decisions.md gets a new "The phone" section recording each decision the mobile plan made, confirmed against the merged code. docs/mobile-plan.md is deleted per its own package C. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
58 lines
4.3 KiB
Markdown
58 lines
4.3 KiB
Markdown
# roledesk
|
|
|
|
A job-search engine for one person. It reads the public job boards of the companies you follow (Greenhouse, Lever, Ashby, Workable, SmartRecruiters, Recruitee, Personio) and runs saved searches on boards that span companies (Jobindex, Adzuna), keeps every posting with when it was first seen and when it closed, scores the open roles for each of your search agents, and tracks the applications you make.
|
|
|
|
Built on the [boilerplate](../boilerplate): its job queue and scheduler (`pipeline/`), password (`auth/`) and deploy kit (`deploy/`), plus the plugin contract and tools from news (`desk/`). FastAPI, Jinja2, SQLite, `uv`, no build step.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
uv sync --all-extras
|
|
uv run app companies seed # 186 companies from seed/companies.json, one board each
|
|
uv run app job pull # read every board and search, then extract, embed and score
|
|
uv run app serve # http://127.0.0.1:8790
|
|
```
|
|
|
|
`uv run app worker` drains the queue without the web app, and `uv run pytest` runs the app's tests and the copied modules' own. `config.yaml` is the committed default, with one starter agent and four Copenhagen searches on Jobindex; `config.example.yaml` documents every key, including the `summarise:` block below.
|
|
|
|
## Searches and companies
|
|
|
|
The Searches and Companies sub-tabs do all of this; the same actions exist on the command line:
|
|
|
|
```bash
|
|
uv run app searches add jobindex "Copenhagen golang" --q "golang go-udvikler" --area 1
|
|
uv run app searches add adzuna "Berlin backend" --q backend --country de --where Berlin
|
|
uv run app searches list
|
|
uv run app companies prune --in DK,SE,NO,EU # lists; add --apply to unsubscribe
|
|
```
|
|
|
|
A Jobindex query is its own syntax: words are OR, `"a b"` is a phrase, `+word` is required; `--area 1` is Region Hovedstaden. An Adzuna search needs a free key from developer.adzuna.com in `ADZUNA_APP_ID` and `ADZUNA_APP_KEY`. `searches add` runs the search once and saves it only if it finds something. Switching a board or search off closes its open roles; the next pull after switching it back on reopens the ones it still lists. The `embeddings` extra is what `fit` needs, `agent` is for `extract` on a model, `passkeys` for the Account tab's passkeys.
|
|
|
|
## The tabs
|
|
|
|
Two tabs, and a cog for settings.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Roles** | open roles, newest or by Best match, with filters, votes (▲ like ● neither way ▼ pass) and a Save button. A title opens the role's own read page |
|
|
| **Applications** | the saved roles and their status, each change recorded as an event |
|
|
|
|
The cog opens `/settings`, one shell with six sub-tabs:
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Ranking** | the one search agent the UI edits: intent, weights, and require/prefer gates behind an Advanced disclosure. Saving rescores it |
|
|
| **Searches** | saved searches that find roles across companies (try, save, edit, remove) |
|
|
| **Companies** | every company whose board is read, its open roles, and its affinity: hidden, neutral, liked, favourite; following a company and pruning boards by region live here too |
|
|
| **Pulls** | a Pull now button and what is running, the pull schedule, and the extract/embed/score buttons behind a disclosure |
|
|
| **Messages** | everything the server said that nobody has cleared |
|
|
| **Account** | the password, sessions and passkeys. Open on loopback, locked on anything else |
|
|
|
|
A role's read page, `/roles/{uid}`, shows the full posting: the same vote and Save controls, the company's own affinity, and the summary when there is one. A search role's posting is a teaser; its page offers a Fetch button that scrapes the original listing once and stores the text. A Summarise button asks for a short summary of that one role; `config.yaml`'s `summarise:` block turns summarising on for the pull itself, bounded to the top `per_agent` roles of each agent so the cost stays flat.
|
|
|
|
## Docs
|
|
|
|
- [`docs/decisions.md`](docs/decisions.md): what was decided for roledesk and why.
|
|
- [`desk/README.md`](desk/README.md), [`pipeline/README.md`](pipeline/README.md), [`auth/README.md`](auth/README.md), [`deploy/README.md`](deploy/README.md): the copied modules, where each comes from and how to refresh it.
|
|
- [`docs/hosting.md`](docs/hosting.md), [`docs/release.md`](docs/release.md), [`docs/server.md`](docs/server.md), [`docs/password-protection.md`](docs/password-protection.md), [`docs/llm-backends.md`](docs/llm-backends.md): the boilerplate's deployment docs.
|