From 64f367cc18baca4bbe8b3dbf26569f658f079c3b Mon Sep 17 00:00:00 2001 From: Wolf Date: Tue, 29 Sep 2026 21:48:24 +0200 Subject: [PATCH] Plan starred companies, filters in history, and place and company chips Co-Authored-By: Claude Fable 5.1 --- docs/plan-feed-filters.md | 145 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 docs/plan-feed-filters.md diff --git a/docs/plan-feed-filters.md b/docs/plan-feed-filters.md new file mode 100644 index 0000000..3152202 --- /dev/null +++ b/docs/plan-feed-filters.md @@ -0,0 +1,145 @@ +# Plan: starred companies, filters in history, place and company chips + +Planned 2026-09-29 from the owner's dictated notes. This file is folded into `decisions.md` and deleted when the packages land. + +## What was asked + +1. A starred company shows its roles across Europe, every other company stays limited to the agent's places. +2. A click on a company name in the feed filters the feed to that company. Back removes the filter. +3. A company is starred from the feed, not from Settings. +4. A seniority filter that does not lose the roles with no known seniority. The same worry for Pay. +5. A place filter that finds every role in Denmark, and takes several places, e.g. Denmark and Skåne. +6. Company and place fields with autocomplete against what the database holds, each pick a chip, several chips per field. +7. `Skane` finds `Skåne`, `Malmo` finds `Malmö`, `Kobenhavn` finds `København`. + +## Measured on the live database, 2026-09-29 + +| Fact | Number | +|---|---| +| Open roles | 33,881 | +| With `seniority` | 0, extract has never run | +| With pay stated | 4,345 (13%) | +| With `remote` | 8,582 (25%) | +| `country` empty | 2,152 | +| `country = 'DK'` | 1,132 | +| Denmark or Copenhagen in `place`, `country` is `EU` or empty | 61 | +| Distinct `place` values | 5,613 | +| Companies with an affinity | 0 | +| Databricks open roles, of which in the US | 790, 471 | + +The Place filter is a substring of `place`, so `Denmark` misses `København K` and `Ballerup`. The `place` gate is a substring too, so `Lund` matches `Billund` and `Albertslund`. `place_key` keeps `ø` and `æ`, since `_fold` does not translate them. The ★ on a feed row saves the role; the company control is `affinityControl` (`app/static/app.js`), which has Favourite, Like and Hidden. + +## Decisions + +**A star is affinity 2, and a favourite passes the `any` group, not the `require` gates.** Today a favourite skips every gate, so a starred Databricks would bring 471 US roles. The owner's agent requires a European country and then any of a country, remote or a town. With the new rule a starred company's roles are gated by Europe only. An agent with no `require` gate shows a favourite's roles from everywhere, as today. + +**The 0.9 floor for a favourite is removed.** With the gates widened, the floor would put every European role of a starred company above all other roles whatever its fit. The affinity term still lifts them, and one click on the company name lists them all. No company has an affinity today, so no stored score changes meaning. + +**A filter pushes a history entry, the search box and typing replace it.** This reverses the rule in `roles.js` that a filter replaces. `popstate` reads the address into the filter and reloads. Agent and order are not filters and replace. + +**A place is matched on whole folded words.** `roles.place_fold` holds `places.fold(place)`: casefolded, marks stripped, `ø` to `o`, `æ` to `ae`, `å` to `a`, punctuation to spaces. A match is `' ' || place_fold || ' ' LIKE '% lund %'`, so `Lund` no longer finds `Billund`. The `place` gate uses the same matcher. + +**A place filter is a token.** `country:DK` matches `country = 'DK'`, or a role whose country is empty or `EU` and whose `place_fold` has a name of that country. `region:skane` matches any town or name of the region in `app/places.py`. `place:malmo` matches the folded words and the aliases of that town (`copenhagen`, `kobenhavn`, `kopenhamn`). Several tokens are joined by OR. A `place` gate value accepts the same tokens, a bare value is read as `place:`. + +**Seniority comes from the title when nothing better is known.** `app/seniority.py` classifies a title into `SENIORITIES`. It fills `roles.seniority` at ingest and in the migration where the column is empty; extract overwrites it. The filter takes several levels and keeps roles with no level unless told otherwise. The rail shows how many roles each level and "no level" hold under the other filters, and the same for Pay. + +**Suggestions are computed per request.** 5,613 distinct places and 743 company keys are small enough to fold and match in Python without a cache. + +## Contract + +Every package builds against this, so waves can run before the one below has merged. + +### `app/places.py` (package A) + +```python +def fold(text: str) -> str # "Skåne län" -> "skane lan", "København K" -> "kobenhavn k" +def parse(token: str) -> Token # "country:DK", "region:skane", "place:malmo"; bare text -> place +def match_sql(token: str, *, place: str = "place_fold", country: str = "country") -> tuple[str, list] +def suggest(q: str, places: Iterable[tuple[str, str, int]], limit: int = 12) -> list[Suggestion] +REGIONS: dict[str, Region] # key -> label, names, towns +``` + +`Token` has `kind`, `value`, `label`. `Suggestion` has `token`, `label`, `kind` (`country`, `region`, `place`) and `count`. `places` is `(place, country, open roles)`. A place suggestion is a town: the first comma part of each `;` part of `place`, grouped by its fold, labelled by its commonest spelling. `q` matches a word prefix of the fold of a label, name or alias. Countries come first, then regions, then towns by count. Regions to start with: Skåne, Capital Region of Denmark, Zealand, Øresund (the two capital regions), Jutland, Funen. + +### `app/seniority.py` (package B) + +```python +def from_title(title: str) -> str # one of SENIORITIES, "" when the title does not say +``` + +Word-bounded, on the folded title, highest level wins. English, Danish, Swedish, German and French titles. + +### `GET /api/roles` (package E) + +New parameters, the old `company` and `place` substrings stay for links from other pages: + +| Parameter | Meaning | +|---|---| +| `company_keys` | repeated, exact `company_key`, OR | +| `places` | repeated place tokens, OR | +| `seniority` | repeated levels, OR | +| `seniority_unknown` | default true: roles with no level pass the seniority filter | +| `pay_unknown` | default false: roles that state no pay pass the pay filter | + +`RoleRow` gains `seniority`. + +### New routes (package E) + +| Route | Answer | +|---|---| +| `GET /api/suggest/companies?q=&agent=&limit=` | `[{key, name, count, affinity}]`, word prefix on the folded name, by open roles | +| `GET /api/suggest/places?q=&limit=` | `[{token, label, kind, count}]` | +| `GET /api/places/labels?tokens=` | `[{token, label}]`, for chips read from the address | +| `GET /api/roles/facets?` | `{seniority: [{value, count}], pay: [{value, count}]}`, each counted with its own filter left out; value `""` is unknown | + +### `app/static/chips.js` (package D) + +```js +window.chipInput(root, { suggest, onChange, placeholder, label }) -> { values(), set(items), clear() } +``` + +`root` is an empty element. `suggest(q)` resolves to `[{value, label, hint}]`. An item is `{value, label}`. A pick becomes a chip with a remove button; Enter picks the first suggestion, arrows move, Escape shuts the list, Backspace in an empty field removes the last chip. Text that matches no suggestion becomes no chip. `onChange(items)` runs after each add or remove. + +## Work packages + +Each owns the files named and nothing else. A package that finds it needs another file stops and reports. + +### Wave 1, in parallel + +| Package | Model | Owns | +|---|---|---| +| A, places | Sonnet | `app/places.py`, `tests/test_places.py` | +| B, seniority | Sonnet | `app/seniority.py`, `tests/test_seniority.py` | +| C, favourite rule | Sonnet | `app/jobs/score.py`, `tests/test_score.py` | +| D, chip input | Opus | `app/static/chips.js`, `app/static/chips.css`, `tests/js/chips.test.mjs` | +| F, history, company filter and star | Opus | `app/static/roles.js`, `app/templates/roles.html`, `app/static/app.css` | + +F sends `company_keys`, which the server ignores until E lands, so F is checked against a stub and again after wave 2. + +F in detail: the company name in a feed row and in the reader is a link to `/?company_keys=` and pushes; with exactly one company filtered a strip above the feed names it, counts its open roles, links its careers page and carries `affinityControl`; `setFilter` pushes and `popstate` restores. + +### Wave 2, after A, B and C are merged + +| Package | Model | Owns | +|---|---|---| +| E, storage and API | Opus | `app/storage/store.py`, `app/storage/schema.py`, `app/web/api.py`, `app/models.py`, `plugins/ats.py`, `tests/test_storage.py`, `tests/test_web.py` | + +Migration 17 adds `roles.place_fold` with an index-free backfill, and fills `seniority` from the title where it is empty. `upsert_role` writes both. `_gate_sql` uses `places.match_sql`. + +### Wave 3, after D, E and F are merged + +| Package | Model | Owns | +|---|---|---| +| G, the rail | Opus | `app/static/roles.js`, `app/templates/roles.html`, `app/static/app.css` | + +Company and Place become chip inputs on the suggest routes. Seniority is a row of level buttons with "and no level" ticked, each with its facet count; Pay shows its counts and gets "and no pay stated". Chips are read from and written to the address. + +### Review + +The planner reads every diff, runs the suite, and checks the pages in a browser at 1400 and 390 pixels on a copy of the live database before each merge. + +## Not in this plan + +- Duplicates: SAP's one role shows four times in the feed. It is item 1 of the backlog. +- The owner's agent still passes any role in Sweden and Germany (`country` DK, SE, DE in the `any` group). Once E lands the group can be `country:DK`, remote and `region:skane`; the owner changes it under Settings, Search agents. +- Reading only some countries of a large board ("A filter in a target", `plan-hosts-wave-2.md`).