Show and set each board's reach on the Companies list, list the readers' declarations on Sources, and document filtering at the source

A company row says what a pull asks its board for; its editor sets the board's own reach (the agents', all roles, or countries and remote) through /api/sources/{id}/reach. /api/readers lists each reader's listing, text, filters, places and robots decision, folded under the Follow form.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Opus 5.5 committed 2026-09-30 10:03:41 +02:00
1 parent 3462a4abe7
commit dafca5435e
8 files changed
+333 -8

No files matched your search

+4 -2
View File
@@ -12,13 +12,15 @@ task in `pipeline.TASKS` and the default schedule in `pipeline.SCHEDULES`.
sources.py what a pull reads, changed by hand: boards and searches
added, switched on or off
discover.py which ATS a company's careers site runs on, from its pages
reach.py which countries a pull asks each big board for, from the agents
"""
from __future__ import annotations
from typing import Any
from app.jobs import cascade, discover, embed, extract, pull, score, sources, stages, summarise
from app.jobs import (cascade, discover, embed, extract, pull, reach, score, sources, stages,
summarise)
from app.jobs.pull import search_target, seed_searches
from app.jobs.score import seed_agents
@@ -38,4 +40,4 @@ def bootstrap(config_path: str = "") -> tuple[Any, Any]:
__all__ = ["BOOTSTRAP", "bootstrap", "cascade", "discover", "embed", "extract", "pull",
"score", "search_target", "seed_agents", "seed_searches", "sources", "stages", "summarise"]
"reach", "score", "search_target", "seed_agents", "seed_searches", "sources", "stages", "summarise"]
+31
View File
@@ -36,6 +36,8 @@ from typing import Any
from app import places
from app.models import Agent, Gate, Subscription, company_key
from app.storage import Store
from plugins import readers
from plugins.readers import _runner
#: A board that listed fewer roles than this when last read whole is read
#: whole.
@@ -233,3 +235,32 @@ def reaches(store: Store, subs: Iterable[Subscription]) -> Mapping[str, dict[str
subs = list(subs)
found = plan(store, subs)
return {s.target: r for s in subs if (r := found.for_subscription(s)) is not None}
#: Why a board is read whole, as the Companies list says it.
_WHOLE = {"small": f"under {SMALL} roles", "unknown": "not read whole yet",
"override": "set here", "favourite": "favourite, too many countries to ask",
"agents": "an agent takes any place"}
def line(found: Plan, sub: Subscription) -> str:
"""What a pull asks `sub`'s board for, once its reader has narrowed the
reach, in a few words: "DK, SE, remote · agents", "all roles · under 300
roles", "all roles · Greenhouse cannot filter"."""
module = readers.HOSTS.get(sub.target.partition(":")[0])
if module is None:
return ""
given, why = found.why(sub)
ask = _runner.ask_for(module, sub.params, given.params())
if _runner.filtered(ask):
words = sorted(ask.countries) if len(ask.countries) <= 4 \
else [f"{len(ask.countries)} countries"]
if ask.remote:
words.append("remote")
return f"{', '.join(words)} · {'set here' if why == 'override' else why}"
if why in ("agents", "favourite") and not given.everywhere:
if not module.READS.filters.declared():
return f"all roles · {module.LABEL} cannot filter"
if why == "agents":
return f"all roles · {module.LABEL} cannot ask for these"
return f"all roles · {_WHOLE[why]}"
+63 -1
View File
@@ -17,6 +17,11 @@
* into the Follow form's `#b-host`, and a slug. Saving posts to
* `/api/companies/{key}/board`, which reads the board once before keeping
* it; Detach stops reading it and keeps the company.
*
* A row with a board says what a pull asks it for ("reads DK, SE · agents",
* `reach` from app/jobs/reach.py), and its editor has a second line that
* sets the board's own reach: the agents', all roles, or its own countries
* and remote, posted to `/api/sources/{id}/reach`.
*/
(function () {
"use strict";
@@ -90,6 +95,7 @@
sub.appendChild(link);
}
sub.append(` · ${count(company.open_roles, "open role")}`);
if (company.reach) sub.append(` · reads ${company.reach}`);
if (company.failing_since) {
// The board has failed on every pull since then; after 21 days its
// roles close.
@@ -199,6 +205,58 @@
return form;
}
/** The open row's reach editor, for a row with a board: the agents' reach,
all roles, or the board's own countries and remote. */
function reachEditor(company, rerender) {
if (company.subscription_id == null) return null;
const own = company.reach_params || {};
const form = document.createElement("form");
form.className = "board-edit";
form.autocomplete = "off";
const mode = document.createElement("select");
mode.setAttribute("aria-label", `What ${company.name}'s board is asked for`);
for (const [value, label] of [["agents", "Agents' reach"], ["all", "All roles"],
["own", "These countries"]]) {
mode.appendChild(new Option(label, value));
}
mode.value = own.reach === "all" ? "all" : (own.countries || own.remote != null ? "own" : "agents");
const codes = document.createElement("input");
codes.type = "text";
codes.spellcheck = false;
codes.placeholder = "DK SE";
codes.value = (own.countries || []).join(" ");
codes.setAttribute("aria-label", "Country codes");
const remote = document.createElement("select");
remote.setAttribute("aria-label", "Remote roles");
remote.append(new Option("and remote", "yes"), new Option("no remote", "no"));
remote.value = own.remote ? "yes" : "no";
const save = document.createElement("button");
save.type = "submit";
save.textContent = "Set reach";
const shown = () => { codes.hidden = remote.hidden = mode.value !== "own"; };
mode.addEventListener("change", shown);
shown();
form.append(mode, codes, remote, save);
form.addEventListener("submit", async (event) => {
event.preventDefault();
save.disabled = true;
try {
const result = await api(`/api/sources/${company.subscription_id}/reach`, {
method: "POST",
body: { mode: mode.value, countries: codes.value.split(/[\s,]+/).filter(Boolean),
remote: remote.value === "yes" },
});
window.toast.info(`${company.name}: reads ${result.reach} from the next pull.`);
editing = null;
await loadCompanies(agentId());
rerender();
} catch (err) {
save.disabled = false;
}
});
return form;
}
/** The board switch, or nothing for a company with no board:
there is no subscription to switch. */
function onSwitch(company, rerender) {
@@ -274,7 +332,11 @@
row.appendChild(affinityControl(company.key, company.affinity, async () => render(), agent));
}
row.appendChild(subLine(company, render));
if (editing === company.key) row.appendChild(boardEditor(company, render));
if (editing === company.key) {
row.appendChild(boardEditor(company, render));
const reach = reachEditor(company, render);
if (reach) row.appendChild(reach);
}
body.appendChild(row);
}
const open = rows.reduce((sum, c) => sum + c.open_roles, 0);
+44
View File
@@ -15,6 +15,11 @@
*
* It is also the page's first script, so it shows the one section of the
* four the URL fragment names and marks it in the settings rail.
*
* Under the Follow form of Company boards, a fold lists what each reader
* declares (`/api/readers`): how its list arrives, where the text is, what
* it filters at the source, how it states places, and the robots.txt
* decision taken when it was built.
*/
(function () {
"use strict";
@@ -277,6 +282,44 @@
}
}
// ----------------------------------------------------------------- readers
/** "country one, remote ids", or "none". */
function filters(reader) {
const shown = Object.entries(reader.filters).map(([name, how]) => `${name} ${how}`);
return shown.length ? shown.join(", ") : "none";
}
function renderReaders(readers) {
const fold = document.createElement("details");
fold.className = "prune";
fold.id = "readers";
const summary = document.createElement("summary");
summary.textContent = `What each reader does (${readers.length})`;
const list = document.createElement("div");
list.className = "srows";
for (const reader of readers) {
const row = document.createElement("div");
row.className = "srow";
const name = document.createElement("span");
name.className = "name";
const label = document.createElement("span");
label.textContent = reader.label;
const scope = document.createElement("span");
scope.className = "badge";
scope.textContent = reader.scope === "search" ? "job board" : "company board";
name.append(label, scope);
const sub = document.createElement("span");
sub.className = "sub";
sub.textContent = [`list ${reader.listing}`, `text ${reader.text}`,
`filters ${filters(reader)}`, `places ${reader.places}`, reader.robots].join(" · ");
row.append(name, sub);
list.appendChild(row);
}
fold.append(summary, list);
$("#board-form").after(fold);
}
// ------------------------------------------------------ one section shown
// Sources shows one section: the one the fragment names or contains, or the
@@ -317,6 +360,7 @@
document.addEventListener("DOMContentLoaded", async () => {
if (!$("#searches-list")) return;
if ($("#board-form")) api("/api/readers").then(renderReaders, () => {});
try {
await load();
} catch (err) {
+71 -1
View File
@@ -471,6 +471,10 @@ class CompanyOut(BaseModel):
from_search: bool = False
hand_reason: str = ""
by_hand: bool = False
#: The board's own reach in its params (`jobs.reach.OVERRIDE_KEYS`), and
#: what a pull asks its board for (`jobs.reach.line`).
reach_params: dict[str, Any] = {}
reach: str = ""
def _company_boards(store: Store) -> dict[str, tuple[int, str, bool, str]]:
@@ -493,10 +497,13 @@ def _company_outs(store: Store, agent: int | None) -> list[CompanyOut]:
ever_boarded = {company_key(s.company) for s in store.subscriptions(source="ats")}
counts = store.open_role_counts()
failing = jobs.pull.failing_boards(store)
subs = {s.id: s for s in store.subscriptions(source="ats")}
plan = jobs.reach.plan(store, subs.values())
out = []
for c in store.companies(agent):
sub_id, host, on, target = boards.get(c.key, (None, "", None, ""))
since, reason = failing.get(target, ("", ""))
sub = subs.get(sub_id) if sub_id is not None else None
from_search = jobs.sources.known_from_search_only(c, ever_boarded)
out.append(CompanyOut(key=c.key, name=c.name, notes=c.notes, board=host,
subscription_id=sub_id, on=on, affinity=c.affinity,
@@ -506,7 +513,10 @@ def _company_outs(store: Store, agent: int | None) -> list[CompanyOut]:
watch=c.watch, careers_opened_at=c.careers_opened_at,
failing_since=since, failing_reason=reason,
from_search=from_search, hand_reason=c.hand_reason,
by_hand=c.key not in boards and not from_search))
by_hand=c.key not in boards and not from_search,
reach_params={k: v for k, v in (sub.params if sub else {}).items()
if k in jobs.reach.OVERRIDE_KEYS},
reach=jobs.reach.line(plan, sub) if sub else ""))
return out
@@ -800,6 +810,66 @@ def switch_source(sub_id: int, body: SwitchBody, store: StoreDep,
return {"source": _one_source(store, sub_id), "closed": closed}
class ReachBody(BaseModel):
#: `agents`: the enabled agents' reach; `all`: every role; `own`: the
#: `countries` (ISO codes) and remote given here.
mode: Literal["agents", "all", "own"]
countries: list[str] = []
remote: bool = False
@router.post("/sources/{sub_id}/reach")
def set_reach(sub_id: int, body: ReachBody, store: StoreDep) -> dict[str, Any]:
"""A board's own reach, which wins over the agents' (see
`app/jobs/reach.py`), or none. The next pull reads the board so; a
narrower reach closes the roles outside it then, except those with a
vote or an application."""
sub = store.subscription(sub_id)
if sub is None or sub.source != "ats":
raise HTTPException(404, f"no such board: {sub_id}")
codes = sorted({c.strip().upper() for c in body.countries if c.strip()})
if unknown := [c for c in codes if not places.known(f"country:{c}") or c == "EU"]:
raise HTTPException(422, f"Not a country code: {', '.join(unknown)}.")
if body.mode == "own" and not (codes or body.remote):
raise HTTPException(422, "Name a country or remote, or read all roles.")
params = {k: v for k, v in sub.params.items() if k not in jobs.reach.OVERRIDE_KEYS}
if body.mode == "all":
params["reach"] = "all"
elif body.mode == "own":
params |= {"countries": codes, "remote": body.remote}
sub = store.update_subscription(sub_id, params=params)
return {"source": _one_source(store, sub_id),
"reach": jobs.reach.line(jobs.reach.plan(store, [sub]), sub)}
class ReaderOut(BaseModel):
"""What a reader declares (`plugins/readers/_contract.py`), for the
Sources page: `filters` holds only the dimensions it filters."""
name: str
label: str
scope: str
listing: str
text: str
filters: dict[str, str]
places: str
robots: str
@router.get("/readers")
def list_readers() -> list[ReaderOut]:
"""Every reader that declares `READS`, boards first, by label."""
from plugins import readers
found = [m for m in readers.READERS.values() if isinstance(getattr(m, "READS", None),
readers.Reads)]
return [ReaderOut(name=m.NAME, label=m.LABEL, scope=m.READS.scope,
listing=m.READS.listing, text=m.READS.text,
filters=m.READS.filters.declared(), places=m.READS.places,
robots=m.READS.robots)
for m in sorted(found, key=lambda m: (m.READS.scope != "board", m.LABEL.lower()))]
class SearchBody(BaseModel):
provider: str
name: str = ""