Prep stage: host words stored raw, mapped centrally in app/prep after every pull

upsert_role stores the host's own words (roles.*_host), the place texts
unresolved when they change, and the company key unresolved on insert, and
marks the role prep_due. app.prep maps seniority, employment, remote and
country through the host tables in app/prep/hosts, resolves places and
company aliases, lists unknown words in `unmapped`, remaps every open role
when the tables' fingerprint changes, and runs rebuild_dupes, which moves
out of the pull's settle. Migration 22 adds the columns and the table and
fills the host words from raw. Cascade: pull, prep, embed, score, enrich,
prep, embed, score, extract, score, summarise. `app prep [unmapped]
[--remap]`, /api/prep/unmapped and a fold on the Sources page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Opus 5.5 committed 2026-09-30 11:19:22 +02:00
1 parent a66aac95cf
commit d04ceae7e0
31 files changed
+1468 -330

No files matched your search

+140 -44
View File
@@ -22,13 +22,12 @@ import numpy as np
from desk.models import Item
from app import dupes, places
from app.models import (
AFFINITY, HAND_REASONS, LEVELS, REMOTE, SENIORITIES, STATUSES, Agent, Application,
AFFINITY, HAND_REASONS, LEVELS, STATUSES, Agent, Application,
ApplicationEvent, Candidate, Company, Gate, Limits, Prompt, Role, RoleCopy, RolePlace,
RoleRow, ScoredRole,
Subscription, Weights, check_prompts, company_fold, company_key, country_of, excerpt, place_key,
posted_at, posted_host, remote_of, title_key,
host_word, posted_at, posted_host, remote_of, title_key,
)
from app.seniority import from_title
from app.storage import gazetteer, schema
#: Text columns a plugin may fill from `Item.raw` under the same name. An
@@ -36,7 +35,17 @@ from app.storage import gazetteer, schema
#: says less than `extract` found keeps what `extract` found. `function` is
#: not here: it is not a board field (see the note by `keep_filled` below).
#: Nor is `seniority`, which is the title's level unless a board states one.
_RAW_TEXT = ("place", "country", "currency")
_RAW_TEXT = ("place", "currency")
#: The host's own words a reader hands on in `Item.raw`, stored as
#: `<name>_host` (`host_word`) for `app.prep` to map. `seniority_host` is
#: rewritten every pull, as the host's level always was; the others are kept
#: filled, since a role's own page (`enrich`) may state what its listing
#: does not.
_HOST_WORDS = ("seniority", "employment", "remote", "country")
_KEPT_HOST_WORDS = ("employment_host", "remote_host", "country_host")
#: What prep maps from that a pull rewrites whatever it brings.
_PREP_OVERWRITTEN = ("title", "seniority_host")
_RAW_INT = ("salary_min", "salary_max")
#: What `extract` may fill. Only an empty column is written: a board's own
@@ -154,14 +163,11 @@ def _iso(moment: datetime) -> str:
return moment.astimezone(UTC).isoformat(timespec="seconds")
def _remote(value: Any) -> str:
"""A plugin's remote flag as one of `REMOTE`. `True` is 'remote'; anything
unrecognised is '' (unknown), which `extract` may fill later."""
if value is True:
return "remote"
text = str(value or "").strip().lower().replace("-", "").replace(" ", "")
text = {"onsite": "onsite", "office": "onsite", "inoffice": "onsite"}.get(text, text)
return text if text in REMOTE else ""
def _own_texts(conn: sqlite3.Connection, uid: str) -> list[str]:
"""One role's own place texts as stored, in the host's order."""
return list(dict.fromkeys(r[0] for r in conn.execute(
"SELECT text FROM role_places WHERE uid = ? AND url = '' ORDER BY position, rowid",
(uid,))))
def _like(text: str) -> str:
@@ -607,10 +613,19 @@ class Store:
"""Store one posting. Returns True when it was new.
`first_seen` and `created_at` are written on insert only; `last_seen` on
every call, and a role seen again is open again. The gate columns come
every call, and a role seen again is open again. The raw columns come
from `item.raw` under their own names, with `company` falling back to
the subscription's and `country` to what `place` names; an empty value
never overwrites a filled column.
the subscription's; an empty value never overwrites a filled column.
Nothing is mapped here: that is `app.prep`, which runs after every
pull. The host's words go to `seniority_host`, `employment_host`,
`remote_host` and `country_host` (`host_word`), `company_key` is
written unresolved on a new role only, and the mapped columns
(`seniority_stated`, `seniority_title`, `seniority`, `employment`,
`remote`, `country`) are left as prep last wrote them. `prep_due`
is 1 on a new role and grows by one when the title, the company, a
host word or the place texts changed or the role reopens, which
is what the next prep reads.
`posted_at` (see `app.models.posted_at`) is set from this pull's own
`published_at` and `stamp`; on an update the `ON CONFLICT` clause below
@@ -627,20 +642,14 @@ class Store:
alone for good, whatever the plugin's raw guess now says — see
`set_extracted` for the other half of the rule.
`seniority` is the first filled of three levels. `seniority_model`
is extract's (`set_extracted`) and never written here.
`seniority_stated` is the host's word as `raw["seniority"]` carries
it, already in `SENIORITIES` (anything else is ''), and
`seniority_title` is `seniority.from_title`; both are rewritten every
pull. The classifier is called here rather than in a plugin, so a
role from any source gets it, the way `country` comes from `place`.
The role's places (`role_places`) are the texts of `raw["places"]`,
else `raw["place"]` cut at `;` (`gazetteer.texts`), each resolved
against the gazetteer; `place` is the line shown, the texts joined
when `raw` has none. Like `place`, a pull with no place leaves them
as they are. `place_fold` is written with `place`, under the same
keep-filled rule. `teaser` is kept-filled too.
else `raw["place"]` cut at `;` (`gazetteer.texts`), written unresolved
when they differ from the stored ones; prep resolves them. Texts that
did not change keep their resolved rows, so the feed's Place filter
stays right between a pull and its prep. `place` is the line shown,
the texts joined when `raw` has none. Like `place`, a pull with no
place leaves them as they are. `place_fold` is written with `place`,
under the same keep-filled rule. `teaser` is kept-filled too.
A role is embedded from its description, else its teaser, else its
title (`app.jobs.embed.document`). When a pull brings a better one of
@@ -660,12 +669,11 @@ class Store:
"source": item.source,
"source_id": item.source_id,
"subscription_id": subscription.id if subscription else None,
"company_key": self.resolve_company(company),
"company_key": company_key(company),
"company": company,
"title": item.title,
"title_key": title_key(item.title),
"place_key": place_key(place),
"remote": _remote(raw.get("remote")),
"description": item.body,
"feed_text": item.excerpt,
"original_url": item.location,
@@ -677,30 +685,26 @@ class Store:
"created_at": stamp,
}
row |= {name: str(raw.get(name) or "") for name in _RAW_TEXT}
row |= {f"{name}_host": host_word(raw.get(name)) for name in _HOST_WORDS}
row["place"] = place
row["country"] = row["country"] or country_of(place)
row["remote"] = row["remote"] or remote_of(place)
row |= {name: _int_or_none(raw.get(name)) for name in _RAW_INT}
row["function"] = str(raw.get("function") or "")
stated = str(raw.get("seniority") or "")
row["seniority_stated"] = stated if stated in SENIORITIES else ""
row["seniority_title"] = from_title(item.title)
row["seniority"] = row["seniority_stated"] or row["seniority_title"]
row["teaser"] = str(raw.get("teaser") or "")
row["place_fold"] = places.fold(row["place"])
# A board's own pay line, one per pull like title or published_at —
# not kept-filled like _RAW_TEXT: a board that stops stating pay
# must be able to clear it, not leave a stale line behind.
row["salary_text"] = str(raw.get("salary_text") or "")
row["prep_due"] = 1
keep_filled = ("company", "company_key", "place_key", "remote", "description",
"feed_text", "original_url", "teaser", *_RAW_TEXT)
keep_filled = ("company", "place_key", "description", "feed_text", "original_url",
"teaser", *_RAW_TEXT, *_KEPT_HOST_WORDS)
updates = [f"{c}=COALESCE(NULLIF(excluded.{c}, ''), roles.{c})" for c in keep_filled]
updates += [f"{c}=COALESCE(excluded.{c}, roles.{c})"
for c in (*_RAW_INT, "subscription_id")]
updates += [f"{c}=excluded.{c}"
for c in ("title", "title_key", "published_at", "raw", "last_seen",
"salary_text", "seniority_stated", "seniority_title")]
"salary_text", "seniority_host")]
updates.append("posted_at=MIN(excluded.posted_at, roles.posted_at)")
# Not `keep_filled`'s COALESCE(NULLIF(...)): that would let a fresh
# pull's classifier guess overwrite what extract decided, which is
@@ -711,11 +715,17 @@ class Store:
updates.append("function=CASE WHEN roles.extracted_at IS NULL "
"THEN COALESCE(NULLIF(excluded.function, ''), roles.function) "
"ELSE roles.function END")
# The model's level, else the host's, else the title's.
updates.append("seniority=COALESCE(NULLIF(roles.seniority_model, ''), "
"NULLIF(excluded.seniority_stated, ''), excluded.seniority_title)")
updates.append("place_fold=CASE WHEN excluded.place != '' "
"THEN excluded.place_fold ELSE roles.place_fold END")
# One more than before when what prep maps from changed, or the role
# reopens, so a prep that read the old values leaves it due
# (`Store.prepped`). `roles.` is the stored row here, `excluded.`
# what this pull brought.
changed = [f"roles.{c} IS NOT excluded.{c}" for c in _PREP_OVERWRITTEN]
changed += [f"(excluded.{c} != '' AND roles.{c} IS NOT excluded.{c})"
for c in ("company", *_KEPT_HOST_WORDS)]
updates.append(f"prep_due=CASE WHEN roles.closed_at IS NOT NULL OR {' OR '.join(changed)} "
"THEN roles.prep_due + 1 ELSE roles.prep_due END")
updates.append("closed_at=NULL")
columns = ", ".join(row)
marks = ", ".join(f":{c}" for c in row)
@@ -725,8 +735,11 @@ class Store:
conn.execute(
f"INSERT INTO roles ({columns}) VALUES ({marks}) "
f"ON CONFLICT(uid) DO UPDATE SET {', '.join(updates)}", row)
if place_texts:
gazetteer.write(conn, self._gazetteer(conn), row["uid"], place_texts)
if place_texts and (before is None or _own_texts(conn, row["uid"]) != place_texts):
gazetteer.write_texts(conn, row["uid"], place_texts)
if before is not None:
conn.execute("UPDATE roles SET prep_due = prep_due + 1 WHERE uid = ?",
(row["uid"],))
# `embed` encodes a role once, from the best text it has. When a
# later pull brings a better one, as a host that states the text
# on the role's own page does, the vector goes, so the next
@@ -1253,6 +1266,89 @@ class Store:
remotes)
return len(countries) + len(remotes)
# ----------------------------------------------------------------- prep
def prep_rows(self, scope: Literal["due", "open", "all"] = "due") -> list[sqlite3.Row]:
"""What `app.prep` maps a role from, and what it holds now: the roles
due (`prep_due` above 0), every open role, or every role."""
where = {"due": "prep_due > 0", "open": "closed_at IS NULL", "all": "1"}[scope]
return self._rows(
f"""SELECT uid, prep_due, {_HOST} AS host, title, company, company_key, place,
seniority_host, employment_host, remote_host, country_host,
seniority_model, seniority_stated, seniority_title, seniority,
employment, remote, country,
json_extract(raw, '$.places') AS raw_places
FROM roles WHERE {where}""")
def resolve_role_places(self, uids: Sequence[str]) -> dict[str, list[int]]:
"""Resolve these roles' own places against the gazetteer, writing the
rows that resolve differently; `uid -> place ids` for each that has
places (`gazetteer.relink_uids`)."""
with self.transaction() as conn:
return gazetteer.relink_uids(conn, self._gazetteer(conn), list(uids))
def company_folds(self) -> dict[str, list[str]]:
"""`fold -> company keys` of `company_aliases`, sorted: what
`resolve_company` asks one name at a time, for prep's whole batch."""
out: dict[str, list[str]] = {}
for r in self._rows("SELECT fold, company_key FROM company_aliases "
"ORDER BY fold, company_key"):
out.setdefault(str(r["fold"]), []).append(str(r["company_key"]))
return out
def write_prep(self, mapped: Sequence[dict[str, Any]]) -> int:
"""Write what prep mapped, one dict per role with `uid`, `due` (the
`prep_due` it read), `company_key`, `seniority_stated`,
`seniority_title`, `employment`, `remote`, `remote_places` and
`country`. `seniority` is the model's level, else the stated, else
the title's. An empty `remote` or `country` leaves the column as it
is, since `extract` fills an empty one. `remote_places`, what the
place texts say, only fills an empty column: it is a guess from a
line, weaker than what `extract` read in the posting. `prep_due` goes back to 0 only when no pull
changed the role since it was read. Returns the rows written."""
with self.transaction() as conn:
return conn.executemany(
"""UPDATE roles SET company_key = :company_key,
seniority_stated = :seniority_stated,
seniority_title = :seniority_title,
seniority = COALESCE(NULLIF(seniority_model, ''),
NULLIF(:seniority_stated, ''), :seniority_title),
employment = :employment,
remote = COALESCE(NULLIF(:remote, ''), NULLIF(remote, ''),
:remote_places),
country = COALESCE(NULLIF(:country, ''), country),
prep_due = CASE WHEN prep_due = :due THEN 0 ELSE prep_due END
WHERE uid = :uid""", mapped).rowcount
def host_words(self) -> list[tuple[str, str, str, int]]:
"""`(field, host, word, open roles)` for every host word an open role
carries, the word lowercased: what prep checks against its tables."""
found: list[tuple[str, str, str, int]] = []
for field in ("seniority", "employment", "remote", "country"):
found += [(field, str(r[0]), str(r[1]), int(r[2])) for r in self._rows(
f"""SELECT {_HOST}, LOWER({field}_host), COUNT(*) FROM roles
WHERE closed_at IS NULL AND {field}_host != '' GROUP BY 1, 2""")]
return found
def replace_unmapped(self, rows: Iterable[tuple[str, str, str, int]]) -> None:
"""Make `unmapped` these `(field, host, word, roles)`, keeping the
`first_seen` of a word already listed."""
stamp = self.now()
with self.transaction() as conn:
seen = {(r[0], r[1], r[2]): r[3] for r in conn.execute(
"SELECT field, host, word, first_seen FROM unmapped")}
conn.execute("DELETE FROM unmapped")
conn.executemany(
"INSERT INTO unmapped (field, host, word, roles, first_seen) "
"VALUES (?, ?, ?, ?, ?)",
[(*r, seen.get(r[:3], stamp)) for r in rows])
def unmapped(self) -> list[dict[str, Any]]:
"""The host words no table maps, by field and host, most roles first."""
return [dict(r) for r in self._rows(
"SELECT field, host, word, roles, first_seen FROM unmapped "
"ORDER BY field, host, roles DESC, word")]
# -------------------------------------------------------------- extract
def _top_scope(self, stage: Literal["extract", "summarise"]) -> tuple[str, list[Any]]: