diff --git a/docs/decisions.md b/docs/decisions.md index a08b3bb..b5dc538 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -68,7 +68,7 @@ What was decided for roledesk and the one reason for each. The longer reasoning **Jobindex and Adzuna first, not Jooble.** Jobindex, Denmark's largest board, has an RSS twin for every search page, with phrase and required-word syntax and a region id; no key. Adzuna has a documented API with a free key for the UK and most of the EU, but no Denmark. Jooble gives a key only on a manual application and answered a Cloudflare challenge. LinkedIn and Indeed have no public search API. Jobnet was left out at first because its search answered 401; see the next paragraph. -**freehire, Jobnet and Akademikernes Jobbank are the fourth to sixth search providers (2026-10-03).** They came from comparing roledesk with github.com/MadsLorentzen/ai-job-search, which reads them. freehire.me is a public JSON API over about 50 hosts (no key, 300 requests a minute, robots.txt invites API use) whose search carries the full text; most of its Danish rows are employers roledesk does not follow, and a copy of a board role folds into the board's by the dupes rule, which now treats every `readers.PROVIDERS` name as a search host. Its query is an OR of words over title, company, text and place, so a search is narrowed by country. Jobnet's `/bff/FindJob/Search` answers 401 without the header `x-csrf: 1` and 200 with it, no login; it has no robots.txt and carries the full text. Jobbank is an RSS feed per search with the text on each ad's page as JSON-LD, so it is the first search reader with `detail`: enrich and the Fetch button read a search role's page through the board path (`plugins.ats.reader_of`), with the same bar, budgets and per-role state, and `Store.enrich_waiting` hands over search roles too. Its robots.txt allows `/job/` and disallows `/fwd/webjob/`, which is never followed. On a copy of the live data, a first page of each gave 266 roles, of which 20 were copies of roles already read. Jobdanmark is left out: about a quarter of its ads are on Jobnet, freehire carries the rest, and its listing has no text. LinkedIn's guest endpoints are left out: robots.txt disallows `/` for every agent and the terms forbid automated access. +**freehire, Jobnet and Akademikernes Jobbank are the fourth to sixth search providers (2026-10-03).** They came from comparing roledesk with github.com/MadsLorentzen/ai-job-search, which reads them. freehire.me is a public JSON API over about 50 hosts (no key, 300 requests a minute, robots.txt invites API use) whose search carries the full text; most of its Danish rows are employers roledesk does not follow, and a copy of a board role folds into the board's by the dupes rule, which now treats every `readers.PROVIDERS` name as a search host. Its query is an OR of words over title, company, text and place, so a search is narrowed by country. Jobnet's `/bff/FindJob/Search` answers 401 without the header `x-csrf: 1` and 200 with it, no login; it has no robots.txt and carries the full text. Jobbank is an RSS feed per search with the text on each ad's page as JSON-LD, so it is the first search reader with `detail`: fetch text and the Fetch button read a search role's page through the board path (`plugins.ats.reader_of`), with the same bar, budgets and per-role state, and `Store.enrich_waiting` hands over search roles too. Its robots.txt allows `/job/` and disallows `/fwd/webjob/`, which is never followed. On a copy of the live data, a first page of each gave 266 roles, of which 20 were copies of roles already read. Jobdanmark is left out: about a quarter of its ads are on Jobnet, freehire carries the rest, and its listing has no text. LinkedIn's guest endpoints are left out: robots.txt disallows `/` for every agent and the terms forbid automated access. **Platsbanken is the third search provider, for Sweden.** The JobTech API (`jobsearch.api.jobtechdev.se/search`) needs no key, states a total, so completeness follows Adzuna's rule, and filters by the taxonomy id of a län (`platsbanken.REGIONS`; Skåne is `CaRE_1nn_cSU`). It refuses an offset above 2000, which the page limit never reaches. The ads carry no usable remote field, so `remote` is read off the headline. Free text ranks by all words rather than requiring them; a quoted phrase narrows it. @@ -88,13 +88,13 @@ What was decided for roledesk and the one reason for each. The longer reasoning **Discovery that finds nothing readable does not detach a board.** `discover --add` on a company that is read from a board and whose site now names only, say, Workday changes nothing and says so. A board that answers is stronger evidence than a page that names no board; `set-board` or Detach is the explicit step. -**SmartRecruiters' board list has no description, so its text is read per role by `enrich`.** Its `/postings` endpoint gives title, location and department; the text is only on `/postings/{id}`, whose `jobAd.sections` hold `jobDescription`, `qualifications` and `additionalInformation` (joined) and `companyDescription` (left out, the same blurb on every role). Reading it for every role would multiply a board's requests by its roles, so the reader declares `text="detail"` and `enrich` reads only the ranked roles (2026-09-30; 209 open roles had no text before). +**SmartRecruiters' board list has no description, so its text is read per role by fetch text.** Its `/postings` endpoint gives title, location and department; the text is only on `/postings/{id}`, whose `jobAd.sections` hold `jobDescription`, `qualifications` and `additionalInformation` (joined) and `companyDescription` (left out, the same blurb on every role). Reading it for every role would multiply a board's requests by its roles, so the reader declares `text="detail"` and fetch text reads only the roles in the cut (2026-09-30; 209 open roles had no text before). **The body cap is 96 MB, with one retry for Greenhouse.** openings.go's 8 MB cap was written against arbitrary URLs, while `ats` only fetches a fixed allow-list of seven ATS hosts, and the real run found `?content=true` boards between 9 and 41 MB. A board that still exceeds 96 MB retries once without `?content=true`, trading the description for the listing. The seven hosts became 22 modules, each with its own allow-list of host names; Greenhouse is still the only reader with a fallback feed. **A board request is streamed, with a 30 s read timeout and a 60 s deadline.** `_get` counts the body as it arrives and refuses it at `MAX_BYTES`, where reading `response.content` first held the whole body in memory before the check. httpx's timeouts are per phase, so a board that keeps sending a byte now and then never timed out; the deadline covers the whole request, redirects and body included, and is checked between chunks. openings.go's 10 s read timeout failed `greenhouse:mongodb` and `greenhouse:feedzai` in a pull of 2026-09-28. Measured on 2026-09-29, three runs each of those two and the five Greenhouse boards with the most open roles, with and without `pay_transparency=true` (84 requests, every one a CloudFront miss): a body of up to 10.4 MB arrives in under a second once it starts, and the first byte waited up to 16.6 s, with the three slowest at 16.6, 14.4 and 10.9 s. The flag made no measurable difference; the slow first byte is the origin's, with or without it. A read may wait 30 s, about twice the worst seen, and the deadline is 60 s, which leaves a large board room on a slower link. -**Workable's list endpoint has no URL and no text.** The parser was first written to Workable's published role object, since every slug tried in the build answered an empty list; the first populated board (Hugging Face, 2026-09-28) showed the v3 shape instead: `location` an object, `department` a list, a `shortcode` and no URL, and no description. The role page is `apply.workable.com/{slug}/j/{shortcode}/`. The text is on `/api/v2/accounts/{slug}/jobs/{shortcode}` (`description`, `requirements`, `benefits`), read by `enrich` for the ranked roles as for SmartRecruiters; the row keeps the `shortcode` for it, since `source_id` is the numeric id. +**Workable's list endpoint has no URL and no text.** The parser was first written to Workable's published role object, since every slug tried in the build answered an empty list; the first populated board (Hugging Face, 2026-09-28) showed the v3 shape instead: `location` an object, `department` a list, a `shortcode` and no URL, and no description. The role page is `apply.workable.com/{slug}/j/{shortcode}/`. The text is on `/api/v2/accounts/{slug}/jobs/{shortcode}` (`description`, `requirements`, `benefits`), read by fetch text for the roles in the cut as for SmartRecruiters; the row keeps the `shortcode` for it, since `source_id` is the numeric id. **Workable and SmartRecruiters are read to the end, and a board closes roles only when it read the total it states.** Workable answers 10 roles a page with a `nextPage` token and SmartRecruiters at most 100 a page by `offset`, and both parsers read page one only, so the settle took page one for the whole board and closed what fell off it: Delivery Hero stated 980 roles and 100 were open. `_paged` follows the pages 0.5 s apart, up to 100 pages, and the plugin stamps `ats:complete` only when the distinct ids read equal `total` or `totalFound`. The count is taken on the raw results, so a row the parser drops does not block closure, and on distinct ids, so a role repeated by a shifted offset does not fake completeness. A 429 after page one ends the read: the roles read are stored and nothing closes, because a partial list is no evidence that the rest closed. A 429 on page one is a failure like any other. The other five hosts answer with the whole board and are complete whenever they parse. Since then there are 22 host modules, not seven; a board over 100 pages is swept across pulls and closes by two finished sweeps (below), and `_paged` is `_runner.read_listing`. @@ -106,7 +106,7 @@ What was decided for roledesk and the one reason for each. The longer reasoning **A host is handed the fetch.** A module imports `desk` and `._shared` only and receives `get`, which `ats.py` binds to its own `_get` at call time. The allow-list, the redirect rule, the byte cap and the deadline stay in one place, and a test that patches `ats._get` reaches every host. `_get` refuses an IP address, a local or numeric host name and any port but 443 before it asks, because a Teamtailor or SuccessFactors slug is a host name somebody typed. -**Per-role text is read by the enrich run, ranked roles first.** Workday, SuccessFactors, Oracle, Phenom, BambooHR, Jobylon, Rippling and Gem list a role without its text. The pull reads listings only. After scoring, the `enrich` stage reads the role pages of roles without text that an enabled agent ranks in its top `enrich.top` (500) at `enrich.min_score` (0.5) or more, best score first, 200 per board and 1,000 per run, and only the roles it filled are embedded and scored again. It follows every pull, a saved agent and a star change, not a vote. A read that brought no text is tried again after `retry_days` (7). `detail` may fill `DETAIL_FIELDS` only, the columns a later pull with an empty listing value leaves alone; title, url, department and `salary_text` come from the listing. Completeness is decided by the listing alone. The pull used to read 200 pages per board in the order roles were found, so a board of 800 roles took four pulls to reach the roles that mattered. Eightfold, SmartRecruiters and Workable list their roles without text too and are read the same way. +**Per-role text is read by fetch text, for the roles in the cut.** Workday, SuccessFactors, Oracle, Phenom, BambooHR, Jobylon, Rippling and Gem list a role without its text. The pull reads listings only. After scoring, the `fetch_text` stage (called `enrich` until 2026-10-04, renamed because it reads data and calls no model) reads the role pages of roles without text that are in the cut of an enabled agent, 200 per board and 1,000 per run, and only the roles it filled are embedded and scored again. It follows every pull, a saved agent, an affinity change and an All countries or All roles switch, not a vote. A read that brought no text is tried again after `retry_days` (7). `detail` may fill `DETAIL_FIELDS` only, the columns a later pull with an empty listing value leaves alone; title, url, department and `salary_text` come from the listing. Completeness is decided by the listing alone. The pull used to read 200 pages per board in the order roles were found, so a board of 800 roles took four pulls to reach the roles that mattered. Eightfold, SmartRecruiters and Workable list their roles without text too and are read the same way. **robots.txt is decided when a reader is built, not checked at run time.** The builder reads the host's robots.txt, the owner decides per reader whether to read it anyway, and `READS.robots` records the decision and the date. The runtime matcher went with the readers rework. Jobindex is read in full although its robots.txt disallows `sort=`, `page=` and `geoareaid=`; Adzuna's API host disallows `/` for every agent; the owner decided to read its documented API with the account's key anyway, since the rule is aimed at crawlers. It needs a key in the config and has not run live yet. HR Manager's portal disallows everything but the application form; no attached company uses it. The companies once kept off the automatic route by robots.txt (Novonesis, Darktrace, Criteo, Snyk, Bang & Olufsen, Pandora, Terma, Zenegy, Umbraco) stay on the Watchlist with reason `robots` until each is decided. The SuccessFactors reader uses `/search/` and `/job/` only. Since then `hrmanager:teknologisk` (the Danish Technological Institute) has been attached and has 7 open roles, so an attached company does use HR Manager; and Novonesis, Darktrace and Criteo are Workday boards, no longer on the Watchlist. @@ -136,11 +136,11 @@ What was decided for roledesk and the one reason for each. The longer reasoning **A description keeps its shape as marked lines.** `_shared.html_text` turns a host's HTML into a line per paragraph, `• ` before a list item and `## ` before a heading (an `

`..`

`, or a paragraph of at most 80 characters set wholly in bold). `strip_html` had flattened a posting into one line, so sections and bullets ran together in the reader. Plain text with marks, not sanitised HTML, is stored because summarise, extract and embed read the same column, and the reader pane escapes each line before drawing it as `

`, `
  • ` or `

    `; a row's excerpt drops the marks. Titles and teasers stay one line through `strip_html`. List readers overwrite the description on every pull, so their roles take the new shape on the next pull; a detail reader reads a role's page once, so its roles read before 2026-09-30 keep the flat text. -**Readers scrape; `prep` decides.** A reader hands on the host's own words (`seniority`, `employment`, `remote`, and `country` only when the host states one per role) and does light cleanup only: text from HTML, dates, the places of a role as a list, pay figures. Mapping lived in 25 readers, each spelling its tables its own way, so changing what "Experienced" means touched a plugin. The `prep` stage (`app/prep/`) maps centrally after every pull and every enrich run. Seniority, employment and remote go through the host's table in `app/prep/hosts/.py` (whole words, or `MATCH` fragments by substring or token), then a shared word map. Country comes from the resolved places (several European countries give `EU`), and the host's country is only a fallback. Places and company aliases are resolved, and copies and duplicates are folded over the whole database. `upsert_role` stores the host words (`*_host` columns, migration 22) and marks the role `prep_due`. When a table changes, its fingerprint makes the next prep map every open role again from the stored words, with no pull. A word no table knows is listed in `unmapped` (`app prep unmapped`, the Sources page). A host's `remote: False` stays unknown rather than onsite, because SmartRecruiters, Ashby, Recruitee and Workable send it for hybrid roles too. +**Readers scrape; `prep` decides.** A reader hands on the host's own words (`seniority`, `employment`, `remote`, and `country` only when the host states one per role) and does light cleanup only: text from HTML, dates, the places of a role as a list, pay figures. Mapping lived in 25 readers, each spelling its tables its own way, so changing what "Experienced" means touched a plugin. The `prep` stage (`app/prep/`) maps centrally after every pull and every fetch text run. Seniority, employment and remote go through the host's table in `app/prep/hosts/.py` (whole words, or `MATCH` fragments by substring or token), then a shared word map. Country comes from the resolved places (several European countries give `EU`), and the host's country is only a fallback. Places and company aliases are resolved, and copies and duplicates are folded over the whole database. `upsert_role` stores the host words (`*_host` columns, migration 22) and marks the role `prep_due`. When a table changes, its fingerprint makes the next prep map every open role again from the stored words, with no pull. A word no table knows is listed in `unmapped` (`app prep unmapped`, the Sources page). A host's `remote: False` stays unknown rather than onsite, because SmartRecruiters, Ashby, Recruitee and Workable send it for hybrid roles too. **Unmapped places and words are fixed in code, from a list on Sources.** Settings › Sources › Unmapped lists the place texts of open roles no place resolves (`app prep unlinked`, with the countries and companies of their roles) and the host words no table maps. It has no editor: the owner tells Claude what a text is, and the `unmapped` skill in `.claude/skills` says which dictionary or host table takes it. Code rather than `add_place_alias` rows, because a fix then reaches a new database and is reviewed like any other change. The prep fingerprint covers `places.seed()`, so the next prep adds the new places and spellings to the database and maps every open role again. Copy the list puts both lists on the clipboard, or selects them on the page where there is no clipboard. -**Fetch terms narrow what big boards send across Europe.** An agent's `fetch_terms` (migration 23) are words a big board must match when it is read with the wide reach: a company set to All countries, or a one-country host whose reach was dropped for needing over 8 requests. A company set to **All roles** (`companies.all_roles`, migration 24) takes no terms on any of its boards, and will take no category or level filter either. It replaced a board's `{"terms": false}` param, which migration 24 moved to the board's company. On its own, All roles changes nothing today, since the narrow reach takes no terms; it is kept for the role filters to come. The terms of a pull are the union over the enabled agents; one enabled agent without terms switches them off. The narrow reach takes no terms, because it already leaves at most about 150 roles on any big board. The survey of 2026-09-30 found that every host's keyword matches the whole text, so a term cuts less than a title filter would ("engineer" left 1,713 of Bosch's 4,830). SmartRecruiters, SuccessFactors, Workday, Phenom, Eightfold and Oracle take one term a request, with one series per term unioned by id; over 8 series the place filter goes first, then the terms. A term-filtered read is never the whole board: it writes no size, prunes no per-role state and closes nothing. Category and level filters wait until something maps agent terms to host ids. A town in a gate is still fetched as its country. +**Fetch terms narrow what every big board sends.** An agent's `fetch_terms` (migration 23) are words a board of 300 or more roles must match, on a host that takes one query per request (SmartRecruiters, SuccessFactors, Workday, Phenom, Eightfold, Oracle), on the narrow and the wide reach alike (2026-10-04; until then only the wide reach of an All countries company took them). A company set to **All roles** (`companies.all_roles`, migration 24) takes no terms on any of its boards, and its roles skip the titles to leave out in scoring. The terms of a pull are the union over the enabled agents; one enabled agent without terms switches them off. The survey of 2026-09-30 found that every host's keyword matches the whole text, so a term cuts less than a title filter would ("engineer" left 1,713 of Bosch's 4,830). One series per term is unioned by id. Over 8 series a wide read drops the place filter and keeps the terms; a narrow read keeps the places, which the agent's fetch gate needs, and drops the terms. A term-filtered read is never the whole board: it writes no size, prunes no per-role state and closes roles by age only, which is accepted because ranking relies on recency, not on closing. A town in a gate is still fetched as its country. **Seniority has three sources.** `seniority_stated` is the host's word mapped by that host's table in `app/prep/hosts/`, `seniority_title` is `seniority.from_title`, and `seniority_model` is `extract`'s verdict; `roles.seniority` is the first of model, stated, title. `extract` reads roles without a model value, every agent's first pick before anyone's second, with the other two as hints it may overrule, since host vocabularies differ and 57% of roles state nothing. `app seniority` shows per host how often the stated level agrees with the model. @@ -172,31 +172,37 @@ What was decided for roledesk and the one reason for each. The longer reasoning **Scoring is per search agent.** A role is scored as `(uid, agent) -> score`, because a role is only good for a given search. Each gate has a mode: `require` becomes a SQL `WHERE`, `prefer` becomes a weighted term in the score. Gated roles keep their row with a reason. `companies.affinity = 2` skips the `any` group, `-1` mutes. +**Three decisions per agent: fetch gate, analysis score, final score (2026-10-04).** The one blended score used to pick what the models read and order the feed, and the owner could not tell which rule did what. Now the fetch gate (region, place, role) is a yes or no applied at the host, in scoring, again after extract and in the feed; the analysis score picks the cut the models read; the final score, `(0.6 fit + 0.2 newness + 0.2 affinity + 0.2 taste) / sum`, orders the feed. Everything else, such as seniority, location and pay, is a filter. `docs/architecture.md` is the target design this follows. + +**The feed shows every role the agent's fetch gate passes, in every order.** Newest first used to show roles the agent rejected, so a change of order changed which roles were shown. With an agent named, every order joins `scores` and hides gated roles unless Show gated is on. + +**Saved filters are per agent, stored on the server (`saved_filters`, migration 32).** A saved filter is the feed's query string under a name: applied with one click, deleted, never edited, since a change is a new one. They are per agent because an agent's filters change with what it hunts, and on the server so they follow the owner across devices. + **An agent is the group: it holds several prompts, and `fit` is the best prompt's.** A hunt spans several kinds of role (AI and data leadership, customer-facing technical leadership, AI research), and one blended paragraph ranks a role by its distance to the blend. Each prompt is a named text in `agent_prompts` (migration 14, which moved every non-empty `agents.intent` into a prompt named after the agent and dropped the intent columns), embedded on its own and cached under sha1 of model and text, so an edit re-embeds one prompt. A role's fit is the maximum over the prompts of the calibrated cosine, the first prompt winning a tie, and `scores.prompt` names the winner. Votes, liked companies, gates, weights, limits and `taste` stay per agent, so a vote counts for every prompt; a market watch is a second agent with its own. No third level above the agent was added. `POST /api/agents` still takes `intent` when `prompts` is absent. On the live data of 2026-09-29 the embedder separates the three kinds of role but not seniority: an individual contributor's posting on the same subject ranks beside a head's, so seniority has to come from `extract` and a prefer gate, or from votes. **`fit` is the cosine between a role and a prompt of the agent, mapped to a level by constants calibrated per embedding model: `clip((cos - lo) / (hi - lo), 0, 1)`.** `(cos + 1) / 2` spanned only about 0.87 to 0.95 on multilingual-e5-small, so a prefer gate at 0.2 outweighed all of fit. Min-max across the roles an agent scored in the run fixed the spread but made fit a rank: the best role of a poor set got 1, a role's fit and the 0.9 favourite floor's meaning drifted from run to run, and the `limits` bars that bound the paid stages compared an absolute number with a relative one. The constants are `CALIBRATION` in `app/config.py`, keyed by model name, and an entry under `embed.calibration` replaces a model's built-in one; keyed by model, a change of `embed.model` cannot carry another geometry's constants along. A model with none falls back to min-max per run, with gated roles left out of the range, and the log warns once per run. `taste` is mapped the same way with its own pair. The starter agents' prefer weights are 0.05. **multilingual-e5-small's constants are fit 0.75 to 0.88 and taste -0.14 to 0.19, measured on a copy of the live database.** Over 16,841 open roles and five different intents the raw fit cosine pooled to p1 0.7528, p50 0.7989, p99 0.8528, p99.5 0.8595, p99.9 0.8711 and max 0.9031; per intent p1 ranged 0.7456 to 0.7700 and p99.9 0.8413 to 0.8773. `hi` is above every intent's p99.9, so about 5 of the "Copenhagen engineering" agent's 4,156 ungated roles clip to 1; at 0.86 (p99.5) 75 would, and lose their order where it matters most. The span 0.13 is close to the 0.145 min-max span it replaces, so a prefer weight keeps about its old size against fit. The copy had no votes, so taste comes from synthetic ones, 30 liked and 30 passed roles for each of three intents (pooled p1 -0.1404, p50 0.0429, p99.9 0.1924), and should be re-measured once real votes exist. -**The default bars are 0.55 for extract and 0.65 for summarise.** On the same data, the Copenhagen agent's ungated roles clearing each bar, min-max then calibrated, were: 0.3: 3,467 and 3,520; 0.4: 1,837 and 2,090; 0.5: 519 and 728; 0.55: 200 and 307; 0.6: 56 and 111; 0.65: 15 and 35. So 0.55 sends about 300 roles to extract and 0.65 about 35 to summarise, which its top 30 trims; the top-N backstops (500 and 30) stay for an agent whose bar admits more. The old defaults, 0.3 and 0.5, admit 3,520 and 728 on the calibrated scale, where only the top N would stop them. An agent keeps the limits stored with it, so one saved under the old defaults keeps 0.3 and 0.5 until it is edited: a migration cannot tell a stored default from a choice. +**The cut's defaults are 500 by fit and 150 by CV closeness, each at least 0.6 (2026-10-04).** The old bars, 0.55 for extract and 0.65 for summarise, were measured on the blended score. Migration 32 reset every agent's limits, since a bar on the blended score means nothing on plain fit. Among agent 2's 7,263 roles passing the fetch gate, 2,086 reach fit 0.6, 1,580 reach CV closeness 0.6 and 2,437 either, so for a broad agent the counts stop the lists; the minimum is for a narrow agent, so roles that do not fit are not read to fill the count. -**An agent without a prompt that has text feeds neither model stage.** Its scores have no fit term, so they order roles by recency, affinity and prefer gates, and a fresh role of any kind clears a bar. `Store._top_scope` leaves such an agent out, and each score run raises one `score.no_intent` notice naming the enabled agents without an intent. The agent still ranks its own list. +**An agent without a prompt that has text has no fit list.** Its cut is the CV list and its liked and saved roles; it feeds no summarise top, and each score run raises one `score.no_intent` notice naming the enabled agents without an intent. The agent still ranks its own list. **The embedding backend is effectively required.** The intent is a CV or a paragraph per agent, and TF-IDF cannot relate "Kubernetes" to "container orchestration". The model is `intfloat/multilingual-e5-small`, not the English-only `all-MiniLM-L6-v2` roledesk started with: the corpus turned European, and on a sample of the live roles (all open Danish-country roles plus a random sample of the rest, language labelled by a stop-word count) against the "Copenhagen engineering" agent's intent, MiniLM separates engineering from non-engineering roles with an AUC of 0.68 overall but only 0.74 restricted to Danish-country roles, where a Danish-country engineering role beats the rest's non-engineering median only 68% of the time; multilingual-e5-small reaches an AUC of 0.70 overall and 1.00 on Danish-country roles, for about 3x the CPU time. A second multilingual candidate, `paraphrase-multilingual-MiniLM-L12-v2`, measured *worse* than plain MiniLM (AUC 0.60) and was dropped. e5 needs its own "query: " / "passage: " prefixes, which `app/jobs/embed.py` adds by matching the model name, not a separate setting. **Summary and tagging are off; `extract` replaces them.** Every profile declares `SummaryPolicy(enabled=False)` and `TaggingPolicy(enabled=False)`. `extract` is a roledesk `ModelTask` on Haiku that turns title and description into the gate columns, and fills only the columns a plugin left empty. Summaries and tags came back as the `summarise` stage and the Summarise button (below); what stays off is desk's own `SummaryPolicy` and `TaggingPolicy`. -**A score is the weighted sum over the sum of the weights.** The agent's `fit`, `recency` and `affinity` weights and every prefer gate's `weight` form one denominator, so a score stays in 0..1 whatever the weights are. +**A score is the weighted sum over the sum of the weights.** The agent's `fit`, `recency`, `affinity` and `taste` weights form one denominator, so a score stays in 0..1 whatever the weights are. Prefer gates were removed on 2026-10-04 (migration 32 dropped them): hybrid and similar wishes are feed filters, so a role is never judged twice by the score and by a filter. **A gate rejects on evidence, not on absence, and `any` gates are one group.** A require gate used to gate a role whose column was empty ("country unknown"), and extract, which fills that column, is bounded to the roles that rank, so 2,281 of 15,556 open roles were out of reach for good: every board that writes "Remote", "Hybrid" or "Distributed" as its location. Now an empty column neither passes nor fails; the role ranks, extract reads it, and the rescore gates it on what it found. `any` is the third mode: the `any` gates form one group a role must match one of, so "in Denmark, or remote" is two `any` gates, where require alone could only say "and". `remote` is also read off the location line, as `country` is, since Greenhouse puts "Hybrid" there and nowhere else. -**A favourite passes the `any` group, not the `require` gates, and has no floor.** A favourite used to skip every gate and score at least 0.9. Starring is how the owner widens one company's roles beyond the agent's places, and with every gate skipped a starred Databricks brought 471 US roles. With the `require` gates kept, the owner's agent shows 166 Databricks roles, all in Europe, against 53 unstarred. The floor went with it: over the widened set it put every role of a starred company above all others whatever its fit. The affinity term still lifts them, and with the default weight of 0.2 Databricks held 33 of the top 60 rows on the data of 2026-09-29. +**A favourite only raises the level; All countries skips the places (2026-10-04).** A favourite used to skip every gate and score at least 0.9, then (2026-09-29) to skip the `any` group, which made affinity both a widening and a ranking. Since 2026-10-04 the widening belongs to the company switches, the same for every agent: All countries skips the place part of the fetch gate (the `any` group) and All roles the role part (fetch terms and `exclude` gates on title). The `require` gates (the region) apply to every role. Affinity adds about 0.05 (liked) or 0.1 (favourite) to both levels of the cut and its weighted share to the final score. **Gates match loosely where the column is free text.** `place` takes the Place filter's tokens on whole folded words, so `Berlin` matches "Berlin, Germany" and `Lund` no longer matches "Billund"; `company` compares company keys, `languages` passes when every required language is a value, `salary_min` is at least the smallest value, and the rest are case-insensitive equality. Each gate is one SQL `CASE` column, so a require gate filters while the gated row keeps every failed gate as its reason. **`exclude` gates titles out by phrase, not by `function`.** Sales titles (Account Executive, Account Director, Client Partner) and individual data engineering ranked high for the owner's agent, since their postings read like the sales engineering and data leadership the prompts describe. `function = sales` could not remove them: the keyword classifier files "Solutions Engineer" and "pre-sales" under sales, so on the data of 2026-09-30 it would also have gated Field CTO, Director Field Engineering, Staff Solutions Engineer and every AI Deployment Strategist in the agent's top 400. The fourth mode, `exclude`, gates a role that matches any of its values, and the gate's `CASE` column returns the position of the first value that matched so the reason names it ("title account executive"). It applies to favourites, which skip only the `any` group. The new `title` field matches a value as whole words of `title_key`, `LIKE '% phrase %'` over the padded key, so `data engineer` gates "Senior MLOps/Data Engineer" and not "Data Engineering Manager", and Forward Deployed Engineer is untouched. The form has a Leave out titles line under Where. Bare `sales` and `vice president` stay off the owner's list, because they would take Sales Engineer and VP roles, and `account manager` stays off because it would take Technical Account Manager. Measured on the agent's 5,089 ranked roles, the list the owner took gated 283, 13 of them in the top 100. -**A role with no vector is scored without `fit`.** The fit weight leaves the denominator, so a role `embed` has not reached yet ranks on recency, affinity and prefer gates instead of sinking to the bottom. It is gated as "no vector" only when fit is the only weighted term, and as "no intent vector" when the intent could not be embedded. +**A role with no vector is scored without `fit`.** The fit weight leaves the denominator, so a role `embed` has not reached yet ranks on recency and affinity instead of sinking to the bottom. It is gated as "no vector" only when fit is the only weighted term, and as "no intent vector" when the intent could not be embedded. **Each run replaces an agent's scores.** `replace_scores` deletes and inserts in one transaction, so a role closed or muted since the last run drops out rather than keeping a stale score, and a reader sees one list or the other. @@ -204,13 +210,13 @@ What was decided for roledesk and the one reason for each. The longer reasoning **`embed` and `score` run in the server process.** newsdesk isolates `embed` in a child process with a timeout. roledesk's run is one bounded pass over open roles, and in-process keeps the embedder replaceable in tests. The cost is torch's memory staying in the server after the first run; isolate it if that becomes the problem. -**The pull cascade is `pull → embed → score → extract → score → summarise`.** Every stage is always in the chain and a stage that is off (the switch under Runs, else config.yaml) finds nothing, as in newsdesk. The free stages run first: embed and score cost no tokens, and their score is what bounds the two model stages. Extract reads only what ranks, then score runs again so the gates read what it filled. A stage is addressed by its position in the tuple, since `score` is in it twice. Extract reads `on_ingest` only as a stage of a pull, so with `auto` and no model reachable a pull passes it quietly. Later decisions added `prep` and `enrich`: the cascade is `pull → prep → embed → score → enrich → prep → embed → score → extract → score → summarise`, and `CASCADES` in `app/jobs/cascade.py` is the source. +**The pull cascade is `pull → prep → embed → score → fetch_text → prep → embed → score → extract → score → judge → summarise`.** Every stage is always in the chain and a stage that is off (the switch under Runs, else config.yaml) finds nothing, as in newsdesk. The free stages run first: embed and score cost no tokens, and score writes the cut that bounds everything after it. Extract reads the cut, then score runs again so the fetch gate and the cut see the real location and remote area before judge reads anything. Summarise runs last, on the final order. A stage is addressed by its position in the tuple, since `score` is in it three times. Extract reads `on_ingest` only as a stage of a pull, so with `auto` and no model reachable a pull passes it quietly. `CASCADES` in `app/jobs/cascade.py` is the source. -**Extract is bounded like summarise: the top roles of each agent, by that agent's own `limits`.** Extract has short answers but would otherwise touch every open role, and the seed boards alone produced 29,000; at Haiku's rates that is tens of dollars for a first pass over roles nobody will look at. Bounded to the ranking, a pull reads a few hundred. `extract_top` is the backstop (default 500) and `extract_min` the real stop (default 0.55, about 300 roles for the starter agent): a fixed count stays flat whatever the boards produce, where a percentage would not. The bounds are per agent rather than config, because one agent may be a wide monitoring search that should read a thousand and another a narrow hunt that wants fifty; one global number fits neither. A batch dealt named uids finishes them whatever their rank, so a running batch is not cut short by a rescore. +**The cut is the one selection for fetch text, extract and judge (2026-10-04).** Per agent, over the roles passing its fetch gate, the cut is the best `cut_fit_top` by fit level at or above `cut_fit_min`, then the best `cut_cv_top` by CV level at or above `cut_cv_min` among the rest, then every role it liked and every saved role (`scores.cut` is `fit`, `cv` or `kept`). A level is the plain fit or CV closeness plus the affinity bonus. Newness and taste are out: a role is read once and pulls run every few hours, and votes come after the read. The two lists are not merged into one number, since they answer different questions (what I want, what I am) and a merged number lets the stronger side crowd the other out. One depth: a second bar inside the cut would defeat its purpose. Without the Where lines only 118 of agent 2's 500 best by fit were roles it could take, so the cut keeps the fetch gate. The cost is mostly a one-off catch-up (about 16 minutes of extract and an hour of judge for 650 roles on the subscription backend); a change to the CV, a prompt or the like texts re-judges the whole cut, which is accepted. A batch dealt named uids finishes them whatever their rank. **`extract_batch` and `summarise_batch` are `isolate=True`, with a timeout.** `context.check()` only runs between the calls `modeltask.one` makes, not inside one, so a call that hangs on either backend was otherwise unkillable short of restarting the server; a process boundary is what lets a Kill, or the timeout itself, actually end it. One call is already bounded at `agent.timeout`, so the deadline is a few calls' worth (30 minutes for extract, 15 for summarise): a batch still running after that is stuck, not slow. The cost: an isolated job's context has no working `stop`, `task` or `fan_out` (see `pipeline/child.py`'s `context_for`), so a refusal or an account-level failure inside a batch can no longer stop the rest of that task's queued siblings, which run on to the same failure instead of being spared it. -**A third order, CV match, from a model reading each agent's best roles against its CV (2026-10-03).** Taken from the `/rank` of github.com/MadsLorentzen/ai-job-search, which has a model score a posting against a written profile on five dimensions. Fit compares topics; it cannot tell a step down, years of experience or a stated deal-breaker, which a model reading both texts can. An agent may hold a CV (pasted, or a `.md`/`.txt` file the browser reads into the box), its languages with a level (suggested from the CV by one model call, then edited), and a soft profile of two free texts, "What I like" (`like_text`) and "What I don't like" (`avoid_text`, the column keeps its name), each covering the work, the workplace and situations, with no split into tasks versus environment; the prompts stay what the owner wants. Both texts feed the career score, which the rubric judges against what the person wants (the prompts), what they like and what they do not like, and whether the tasks and the setting would energise them. A deal-breaker is a hard rule and lives in the agent's gates, so the form has no must-haves box; `must_text` stays a column that only the API sets, and the verdicts and the cap below apply whenever it is non-empty. The stage `judge` (after summarise in the pull, switched under Runs like extract, Haiku by default) reads the pairs of an enabled agent with a CV within its `judge_top` and `judge_min` limits and the `judge_cv_top` closest to the CV (below), once per `input_key` (a hash of the CV, prompts, both texts and the role's text), and stores skills, experience and career (0 to 100, their rubric bands verbatim), 1 to 3 strengths and gaps in `role_judgements`, which rescoring and closing never touch. The CV match is the weighted mean of the three, with the weights per agent (`cv_skills`, `cv_experience`, `cv_career` in `agents.weights`, default 30, 25, 30) applied when a role is served, so changing them needs no model call. Culture is left out (guessed from ad text) and location too (the gates do it): a must-haves text (set through the API) that names a place makes the model mark location down, so places belong in the Where rules. The model reports facts and code applies the rules: the must-haves text, when set, is read as one must-have per line (leading bullets and numbers dropped), the judge's profile (``, `` and, when set, ``) numbers them M1..Mn, and for each judgement the model answers `musts`, a verdict per must-have, "met", "broken" only when the posting text clearly contradicts it, or "unclear" when the text does not say (never inferred from silence; a must-have the model leaves out counts as unclear). It scores career on its rubric as before and the career is stored as given. The cap is code's: when a role is served, any "broken" verdict makes career count as `min(career, BROKEN_CAP)` with `BROKEN_CAP = 39` (`app.models`), in `cv_score`, in `Store.judgement` (which serves the model's career, `career_capped` and the must-haves with their text) and in `store._cv_sql`, which reads a `broken` count stored beside the verdicts (`role_judgements.musts` and `.broken`, migration 29), so CV match orders by the capped value too. The verdicts store each line's text, so the reader still shows the must-haves a judgement was made against after the text is edited. The judge's `input_key` carries a format version (`judge.FORMAT`, 3) and the likes text (`agents.like_text`, migration 30), so judgements made before the verdicts or the likes existed are made again; until then they serve with the verdicts they have, or none and no cap. The reader shows each must-have with ✓ met, ✗ broken or ? unclear, and career as "39 (capped: breaks a must-have; model said 55)". CV closeness (2026-10-03) is a free, local signal beside the judge, never in its place: the score run cuts the CV into chunks (`embed.cv_chunks`: paragraphs, a longer one cut by line, then sentence, then word, neighbours joined again up to `CV_CHUNK_CHARS` = 1,200 characters, inside e5's 512 tokens), embeds each as a prompt is ("query: " for an e5 model), caches them in `agent_cv_vectors` under sha1 of the model, the chunking version and the CV text, and stores each ungated role's best cosine over the chunks, scaled to 0..1, as `scores.cv_fit` (migration 31). It is no term of the Agent match score. It has its own band, `Calibration.cv`, fit's when a model has none: a CV chunk is longer than a prompt and sits closer to every posting, so on the copy of 2026-10-03 fit's band (0.75, 0.88) clipped 88 of agent 2's 7,270 ungated roles to 1 and the 50 closest tied on posting date; (0.77, 0.90) clips one. The judge then also reads the `judge_cv_top` (default 50, per agent beside `judge_top` and `judge_min`) ungated roles closest to the CV that the first set leaves out, closest first, under the same `input_key`, give-up and text rules; a gated role stays out however close. On that copy 43 of agent 2's 50 closest roles were outside its 150 best by score, ranked 153 to 2,632 by score (median 831), 20 of them under `judge_min`. CV match puts the judged roles first by `cv_score`, then the others by `cv_fit`, then by score; a row carries `cv_fit`, and under CV match an unjudged row's gutter shows it faint and italic over an empty bar, a dash without one. Their scale is ten postings a run; ours is the top of a ranking that has already scored every role for free. +**A third order, CV match, from a model reading each agent's best roles against its CV (2026-10-03).** Taken from the `/rank` of github.com/MadsLorentzen/ai-job-search, which has a model score a posting against a written profile on five dimensions. Fit compares topics; it cannot tell a step down, years of experience or a stated deal-breaker, which a model reading both texts can. An agent may hold a CV (pasted, or a `.md`/`.txt` file the browser reads into the box), its languages with a level (suggested from the CV by one model call, then edited), and a soft profile of two free texts, "What I like" (`like_text`) and "What I don't like" (`avoid_text`, the column keeps its name), each covering the work, the workplace and situations, with no split into tasks versus environment; the prompts stay what the owner wants. Both texts feed the career score, which the rubric judges against what the person wants (the prompts), what they like and what they do not like, and whether the tasks and the setting would energise them. A deal-breaker is a hard rule and lives in the agent's gates, so the form has no must-haves box; `must_text` stays a column that only the API sets, and the verdicts and the cap below apply whenever it is non-empty. The stage `judge` (after extract and its rescore in the pull, switched under Runs like extract, Haiku by default; since 2026-10-04 it reads the agent's whole cut instead of its own limits) reads the pairs of an enabled agent with a CV, once per `input_key` (a hash of the CV, prompts, both texts and the role's text), and stores skills, experience and career (0 to 100, their rubric bands verbatim), 1 to 3 strengths and gaps in `role_judgements`, which rescoring and closing never touch. The CV match is the weighted mean of the three, with the weights per agent (`cv_skills`, `cv_experience`, `cv_career` in `agents.weights`, default 30, 25, 30) applied when a role is served, so changing them needs no model call. Culture is left out (guessed from ad text) and location too (the gates do it): a must-haves text (set through the API) that names a place makes the model mark location down, so places belong in the Where rules. The model reports facts and code applies the rules: the must-haves text, when set, is read as one must-have per line (leading bullets and numbers dropped), the judge's profile (``, `` and, when set, ``) numbers them M1..Mn, and for each judgement the model answers `musts`, a verdict per must-have, "met", "broken" only when the posting text clearly contradicts it, or "unclear" when the text does not say (never inferred from silence; a must-have the model leaves out counts as unclear). It scores career on its rubric as before and the career is stored as given. The cap is code's: when a role is served, any "broken" verdict makes career count as `min(career, BROKEN_CAP)` with `BROKEN_CAP = 39` (`app.models`), in `cv_score`, in `Store.judgement` (which serves the model's career, `career_capped` and the must-haves with their text) and in `store._cv_sql`, which reads a `broken` count stored beside the verdicts (`role_judgements.musts` and `.broken`, migration 29), so CV match orders by the capped value too. The verdicts store each line's text, so the reader still shows the must-haves a judgement was made against after the text is edited. The judge's `input_key` carries a format version (`judge.FORMAT`, 3) and the likes text (`agents.like_text`, migration 30), so judgements made before the verdicts or the likes existed are made again; until then they serve with the verdicts they have, or none and no cap. The reader shows each must-have with ✓ met, ✗ broken or ? unclear, and career as "39 (capped: breaks a must-have; model said 55)". CV closeness (2026-10-03) is a free, local signal beside the judge, never in its place: the score run cuts the CV into chunks (`embed.cv_chunks`: paragraphs, a longer one cut by line, then sentence, then word, neighbours joined again up to `CV_CHUNK_CHARS` = 1,200 characters, inside e5's 512 tokens), embeds each as a prompt is ("query: " for an e5 model), caches them in `agent_cv_vectors` under sha1 of the model, the chunking version and the CV text, and stores each ungated role's best cosine over the chunks, scaled to 0..1, as `scores.cv_fit` (migration 31). It is no term of the Agent match score. It has its own band, `Calibration.cv`, fit's when a model has none: a CV chunk is longer than a prompt and sits closer to every posting, so on the copy of 2026-10-03 fit's band (0.75, 0.88) clipped 88 of agent 2's 7,270 ungated roles to 1 and the 50 closest tied on posting date; (0.77, 0.90) clips one. The judge then also read the 50 ungated roles closest to the CV that its score list left out; this became the cut's CV list (2026-10-04). On that copy 43 of agent 2's 50 closest roles were outside its 150 best by score, ranked 153 to 2,632 by score (median 831), 20 of them under `judge_min`. CV match puts the judged roles first by `cv_score`, then the others by `cv_fit`, then by score; a row carries `cv_fit`, and under CV match an unjudged row's gutter shows it faint and italic over an empty bar, a dash without one. Their scale is ten postings a run; ours is the top of a ranking that has already scored every role for free. **A posting's languages and deadline, and a flag rather than a score.** Extract reads `languages_required` as objects (language, level on the ladder basic, conversational, professional, fluent, native, and required or plus) and a deadline, from the opening and the closing lines of the text, since both usually sit at the end. Jobnet and Jobbank state a deadline, kept as `deadline_host`; prep composes `deadline` host first. The language flag is computed when a role is served from the posting's languages and the agent's: ⚠ when a required one is missing or its level is above the agent's, ★ when a plus one is the agent's; it never changes a score. Closing soon is the deadline from today to today plus four days, in UTC. @@ -298,7 +304,7 @@ What was decided for roledesk and the one reason for each. The longer reasoning **A search role's posting text is fetched on demand, not in the pull.** `POST /api/roles/{uid}/text` (`app/jobs/posting.py`) fetches it only when the read page asks, because following Jobindex's link for every role during a pull would count as a click in Jobindex's own statistics; one click for a posting somebody actually opened is fair. A Jobindex role's `vis-job` page is a short ad with a "Se jobbet" link to the posting itself (the employer's site, The Hub, or Jobindex's `jobannonce`); the fetch keeps that link as `roles.posting_url` (migration 26, never written by a pull), reads the text from it, and falls back to the `vis-job` page's own text. The reader's link-out prefers `posting_url`, so it leads to the full posting once the text was fetched. -**Summarising is bounded to the top roles of each agent, by that agent's own `limits`, and off unless switched on.** The pull's `summarise` stage only considers roles with no summary yet that are in the top `summarise_top` (default 30) of an enabled agent's scores and at `summarise_min` (default 0.65, about 35 roles for the starter agent, stricter than extract's since a summary is the long answer), so the cost stays flat whatever the backlog of open roles is. The bounds live on the agent, beside its gates and weights, for the same reason as extract's: a wide monitoring search and a narrow hunt want different depths, and the agent is where the difference is already expressed. Whether the stage runs is the switch under Runs, or `summarise.enabled` in config.yaml until the switch is used, and both default to off like `extract`; the read page's Summarise button asks for one role's summary either way. The roles the owner marked are summarised whatever their rank (2026-10-03): every open role with an application (the star) or an ▲ from an enabled agent joins the waiting set beside the top lists, once each and under the same give-up rule, since a handful the owner picked is not the backlog the bounds exist for. Saving or liking such a role queues a `summarise_batch` for that one uid at once, under the key the button uses so a double tap is one job, when the stage is on, the role has text and no summary and a model is reachable. +**Summarise runs after the ranking, on the top of the feed, and is off unless switched on.** It is no part of any score. The pull's last stage considers roles with no summary yet that are in the best `summarise_top` (default 50) by final score of an enabled agent with a prompt, so the cost stays flat whatever the backlog is. Whether the stage runs is the switch under Runs, or `summarise.enabled` in config.yaml until the switch is used; the read page's Summarise button asks for one role's summary either way. The roles the owner marked are summarised whatever their rank (2026-10-03): every open role with an application (the star) or an ▲ from an enabled agent joins the waiting set, once each and under the same give-up rule. Saving or liking such a role queues a `summarise_batch` for that one uid at once, under the key the button uses so a double tap is one job, when the stage is on, the role has text and no summary and a model is reachable. **`extract` and `summarise` are switched on the page, and a stored setting beats config.yaml.** `extract.enabled` and `summarise.enabled` were read at startup and both false, and nothing in the UI said so: an agent's card read "reads 500 at 0.55 · summarises 30 at 0.65" while neither stage had ever run. The `state` keys `stage:extract` and `stage:summarise` ("on" or "off") override the file, `stages.stage_on` in `app/jobs/stages.py` is the one function that decides, and the finders of both tasks ask it, so the stage in a pull, `app job extract` and `app job summarise` agree; with no key the file applies, so config.yaml is the default for a fresh database and an existing deployment behaves as before until someone uses the switch. It is a stored setting rather than a rewrite of config.yaml because rewriting config.yaml from the app would lose its comments and a restart is what the switch is meant to avoid. The switch is under Runs (`GET` and `PUT /api/stages`, `app stages`), beside "Run the pull now": turning a stage on starts nothing, the next pull runs it. It works with no model reachable and says who would answer, since a pull passes a model stage quietly then. A search agent's card says "extract is off" and links to the switch; its limits stay editable either way, since they are what the stage reads once on. The Summarise button queues `summarise_batch` for one uid and never asked the switch.