Switch the extract and summarise stages on the page, over config.yaml

A stored `stage:extract` / `stage:summarise` in the state table overrides
extract.enabled / summarise.enabled; with none, the file applies. One
function, stages.stage_on, decides, and both tasks' finders ask it.
GET/PUT /api/stages and `app stages` show and set it with who would answer;
Runs has a "What the model reads" block, and a search agent's card says when
a stage is off and links to the switch.

Co-Authored-By: Claude Sonnet <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Sonnet committed 2026-09-29 15:54:53 +02:00
1 parent a629eda8de
commit 471ace703c
15 files changed
+593 -23

No files matched your search

+32
View File
@@ -5,6 +5,7 @@
app worker [--workers http=8,cpu=1] [--until-idle]
app companies seed|add|set-board|detach|discover|check
app searches add|list|remove
app stages [extract|summarise on|off]
app db init
`app job` queues the work on a queue of its own and drains it here, so a
@@ -109,6 +110,11 @@ def build_parser() -> argparse.ArgumentParser:
"remove", help="stop running a search and close its open roles")
search_remove.add_argument("name")
stages = sub.add_parser(
"stages", help="show whether extract and summarise run, or switch one")
stages.add_argument("name", nargs="?", choices=["extract", "summarise"])
stages.add_argument("state", nargs="?", choices=["on", "off"])
db = sub.add_parser("db", help="database housekeeping")
db.add_argument("action", choices=["init"])
return parser
@@ -129,6 +135,8 @@ def main(argv: list[str] | None = None) -> int:
return run_companies(args)
if args.command == "searches":
return run_searches(args)
if args.command == "stages":
return run_stages(args)
return init_db(args)
except (FileNotFoundError, config_mod.ConfigError) as exc:
print(exc, file=sys.stderr)
@@ -412,6 +420,30 @@ def add_search(config: config_mod.Config, store: Store, args: argparse.Namespace
return 0
def run_stages(args: argparse.Namespace) -> int:
"""`app stages` prints what `GET /api/stages` returns; `app stages extract
on` stores the switch through the function `PUT /api/stages/extract`
calls, and prints the result."""
from app import jobs
from app.storage import Store
if bool(args.name) != bool(args.state):
print("stages: give a stage and on or off, or neither", file=sys.stderr)
return 1
config = config_mod.load(args.config)
store = Store(config.database)
if args.name:
jobs.stages.set_stage(store, args.name, args.state == "on")
found = [jobs.stages.describe_one(config, store, args.name)]
else:
found = jobs.stages.describe(config, store)
for stage in found:
where = "set by the switch" if stage.source == "stored" else "config.yaml's default"
print(f"{stage.name:10} {'on ' if stage.on else 'off'} {where}; "
f"{stage.model}; {stage.answer}")
return 0
def init_db(args: argparse.Namespace) -> int:
"""Create the file, or bring it to the current schema."""
from app.storage import LATEST, Store
+3 -2
View File
@@ -8,6 +8,7 @@ task in `pipeline.TASKS` and the default schedule in `pipeline.SCHEDULES`.
summarise.py about 60 words on each of the best roles, on Haiku
cascade.py pull → embed → score → extract → score → summarise, what `TASKS`
offers, the `pull` job a schedule fires, and that schedule
stages.py whether extract and summarise run: the switch, else config.yaml
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
@@ -17,7 +18,7 @@ from __future__ import annotations
from typing import Any
from app.jobs import cascade, discover, embed, extract, pull, score, sources, summarise
from app.jobs import cascade, discover, embed, extract, pull, score, sources, stages, summarise
from app.jobs.pull import search_target, seed_searches
from app.jobs.score import seed_agents
@@ -37,4 +38,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", "summarise"]
"score", "search_target", "seed_agents", "seed_searches", "sources", "stages", "summarise"]
+2 -2
View File
@@ -8,7 +8,7 @@ Nothing is alive between two tasks. A stage is addressed by its position in
the tuple, not its name, since `score` runs twice.
Every stage is always in the chain, and a stage that is switched off finds
nothing: `extract.enabled: false`, or an `on_ingest` this pull does not
nothing: a stage switched off (`stages.stage_on`), or an `on_ingest` this pull does not
satisfy, is an extract stage with no batches whose final job moves straight
on. The free stages go first: embed and score cost no tokens, and the score
they produce is what bounds the two that do. Extract reads only the best
@@ -69,7 +69,7 @@ def _extract(cascade: str) -> Task:
def _summarise(cascade: str) -> Task:
"""`summarise` as a stage: nothing with no model reachable, so a machine
without one pulls in silence rather than failing a batch per pull. Off
(`summarise.enabled: false`) is nothing in either case. Standing on its
(`stages.stage_on`) is nothing in either case. Standing on its
own, as the button, a missing model fails the batch with a notice."""
stage = summarise.summarise_task()
if not cascade:
+19 -4
View File
@@ -19,7 +19,8 @@ fills columns that are still empty: a board's structured field wins over what
a model read out of the prose. See `Store.set_extracted`.
Off by default (`extract.enabled: false`), because on the API backend every
batch is a paid call.
batch is a paid call. Whether it runs is `stages.stage_on`: the switch under
Runs, else the config file.
"""
from __future__ import annotations
@@ -35,6 +36,7 @@ from desk import modeltask
from desk.modeltask import ModelTask
from pipeline import NULL, RunContext, Task, job
from app.config import Config
from app.jobs import stages
from app.models import PERMITS, REMOTE, SENIORITIES, ExtractResult, Role
from app.storage import Store
@@ -234,7 +236,20 @@ def run_batch(config: Config, store: Store, *, context: RunContext = NULL,
return modeltask.one(TASK, config, store, uids or [], context=context).model_dump()
def _always(config: Config) -> Any:
"""The settings with the file's flag out of the way: `batches` reads
`enabled` off them, and the switch is `stages.stage_on`, which needs the
store that `settings` is not given."""
return config.extract.model_copy(update={"enabled": True})
def extract_task() -> Task:
"""Finds nothing while `extract.enabled` is false, so the task, the
button and the cascade stage are all no-ops with the switch off."""
return replace(modeltask.of(TASK), label=TASK.label)
"""Finds nothing while the stage is off (`stages.stage_on`), so the task,
the button and the cascade stage are all no-ops with the switch off."""
stage = modeltask.of(replace(TASK, settings=_always))
find = stage.finder
def when_on(config: Config, store: Store) -> Any:
return find(config, store) if stages.stage_on(config, store, "extract") else []
return replace(stage, finder=when_on)
+91
View File
@@ -0,0 +1,91 @@
"""Whether the two model stages of a pull, `extract` and `summarise`, run.
`extract.enabled` and `summarise.enabled` in config.yaml are read at startup
and say nothing on the page, so the switch lives in the database as well: the
`state` keys `stage:extract` and `stage:summarise`, "on" or "off". A stored
value beats the file; with none, the file applies, so config.yaml is the
default for a fresh database and a deployment that never uses the switch
behaves as it did. `stage_on` is the one place that decides, and both tasks'
finders ask it (`extract.extract_task`, `summarise.summarise_task`).
`describe` is what `GET /api/stages` and `app stages` show: for each stage
whether it is on, where that comes from, the model it uses, and who would
answer.
"""
from __future__ import annotations
from typing import Literal
from pydantic import BaseModel
from app.config import Config
from app.storage import Store
from desk.tools import agent
NAMES = ("extract", "summarise")
NO_MODEL = ("no model is reachable: set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN, "
"see docs/llm-backends.md")
ANSWERS = {
"api": "answered by the Claude API",
"claude_code": "answered by the Claude Code sign-in on this machine",
}
class Stage(BaseModel):
"""One model stage as the page shows it. `source` is "stored" when the
switch set it and "config" when it is still config.yaml's default.
`backend` is `agent.backend`'s answer, "" for nobody, and `answer` says
it in words."""
name: Literal["extract", "summarise"]
on: bool
source: Literal["stored", "config"]
model: str
backend: str
answer: str
def _key(name: str) -> str:
return f"stage:{name}"
def stored(store: Store, name: str) -> bool | None:
"""The switch's value, or None while nobody has used it."""
value = store.state.get(_key(name))
return {"on": True, "off": False}.get(value or "")
def stage_on(config: Config, store: Store, name: str) -> bool:
"""Whether stage `name` runs: the stored setting, else config.yaml's."""
value = stored(store, name)
return getattr(config, name).enabled if value is None else value
def set_stage(store: Store, name: str, on: bool) -> None:
"""Store the switch. A `KeyError` for a name that is not a stage."""
if name not in NAMES:
raise KeyError(name)
store.state[_key(name)] = "on" if on else "off"
def answer(config: Config) -> tuple[str, str]:
"""Who would answer a model call, as `(backend, sentence)`."""
backend = agent.backend(config.agent)
if backend:
return backend, ANSWERS.get(backend, f"answered by {backend}")
if config.agent.backend == "off":
return "", "no model is reachable: `agent.backend` is `off` in config.yaml"
return "", NO_MODEL
def describe_one(config: Config, store: Store, name: str) -> Stage:
backend, said = answer(config)
return Stage(name=name, on=stage_on(config, store, name),
source="config" if stored(store, name) is None else "stored",
model=getattr(config, name).model, backend=backend, answer=said)
def describe(config: Config, store: Store) -> list[Stage]:
return [describe_one(config, store, name) for name in NAMES]
+17 -4
View File
@@ -15,7 +15,8 @@ button) takes those roles whatever their rank. See `Store.summarise_waiting`.
The text is `article_text` when the posting page was fetched, else
`description`. A role with neither is not waiting at all, so it is never sent.
Off by default (`summarise.enabled: false`), like extract.
Off by default (`summarise.enabled: false`), like extract. Whether it runs is
`stages.stage_on`: the switch under Runs, else the config file.
"""
from __future__ import annotations
@@ -29,6 +30,7 @@ from desk.models import ModelTaskResult
from desk.modeltask import ModelTask
from pipeline import NULL, RunContext, Task, job
from app.config import Config
from app.jobs import stages
from app.models import Role
from app.storage import Store
@@ -195,8 +197,19 @@ def run_batch(config: Config, store: Store, *, context: RunContext = NULL,
return modeltask.one(TASK, config, store, uids or [], context=context).model_dump()
def _always(config: Config) -> Any:
"""See `extract._always`."""
return config.summarise.model_copy(update={"enabled": True})
def summarise_task() -> Task:
"""Finds nothing while `summarise.enabled` is false, so the task, `app
job summarise` and the cascade stage are all no-ops with the switch
"""Finds nothing while the stage is off (`stages.stage_on`), so the task,
`app job summarise` and the cascade stage are all no-ops with the switch
off."""
return replace(modeltask.of(TASK), label=TASK.label)
stage = modeltask.of(replace(TASK, settings=_always))
find = stage.finder
def when_on(config: Config, store: Store) -> Any:
return find(config, store) if stages.stage_on(config, store, "summarise") else []
return replace(stage, finder=when_on)
+30 -2
View File
@@ -28,6 +28,10 @@
/** @type {object[]} every agent, as the server lists them */
let agents = [];
/** @type {Object<string, boolean>} whether extract and summarise run, from
* `/api/stages`; empty when that did not answer, and then a card says
* nothing about them */
let stageOn = {};
/** @type {number | "new" | null} the card in edit mode: an agent's id, NEW
* for the blank one on top, null for none */
let editing = null;
@@ -112,9 +116,27 @@
return `fit ${w.fit} · newness ${w.recency} · companies ${w.affinity} · liked ${w.taste}${gates}`;
}
// What the model reads after a pull, one clause per stage. A stage that is
// off says so, with a link to its switch under Runs: the numbers are only
// what it would read once it is on.
function limitsLine(row) {
const l = Object.assign({}, DEFAULT_LIMITS, row.limits);
return `reads ${l.extract_top} at ${l.extract_min} · summarises ${l.summarise_top} at ${l.summarise_min}`;
const p = el("p", "agent-limits");
const clauses = [
["extract", `reads ${l.extract_top} at ${l.extract_min}`, `${l.extract_top} at ${l.extract_min}`],
["summarise", `summarises ${l.summarise_top} at ${l.summarise_min}`, `${l.summarise_top} at ${l.summarise_min}`],
];
clauses.forEach(([name, on, would], i) => {
if (i) p.append(" · ");
if (stageOn[name] === false) {
const off = link("/settings/sources#stages", `${name} is off`);
off.title = "Switch it on under Runs, What the model reads.";
p.append(off, ` (${would})`);
} else {
p.append(on);
}
});
return p;
}
function card(row, fallback) {
@@ -136,7 +158,7 @@
? el("p", "agent-intent", intent)
: el("p", "agent-intent empty", "Nothing described yet, so fit has nothing to measure against. Edit says what this agent looks for."));
div.appendChild(el("p", "agent-weights", weightsLine(row)));
div.appendChild(el("p", "agent-limits", limitsLine(row)));
div.appendChild(limitsLine(row));
const actions = el("div", "agent-card-actions");
const edit = el("button", "secondary", "Edit");
@@ -330,6 +352,12 @@
async function load() {
agents = await api("/api/agents");
// A card is only worded by it, so a failure leaves the cards as they were.
try {
stageOn = Object.fromEntries((await api("/api/stages")).map((s) => [s.name, s.on]));
} catch (err) {
stageOn = {};
}
}
document.addEventListener("DOMContentLoaded", async () => {
+83 -1
View File
@@ -1,4 +1,9 @@
/* The Runs section of Sources: the "Run the pull now" button.
/* The Runs section of Sources: the "Run the pull now" button, and the
* switches for the two stages that ask a model.
*
* The switches are `/api/stages`: one row per stage, drawn as the search
* rows above are (`.srow`, `.switch`), and a switch is a PUT that stores the
* setting and starts nothing.
*
* What the queue is doing and when it runs next are `<desk-jobs>`' and
* `<desk-schedules>`' business, and they draw themselves. The single stages
@@ -52,11 +57,88 @@
});
}
// ------------------------------------------------- what the model reads
const DOES = {
extract: "fills in country, seniority, salary and the like from what the posting says",
summarise: "writes a short summary and tags for the best roles",
};
const el = (tag, className, text) => {
const node = document.createElement(tag);
if (className) node.className = className;
if (text !== undefined) node.textContent = text;
return node;
};
/** The On/Off switch of a search agent's card, on a stage. */
function stageSwitch(stage, rerender) {
const label = el("label", "switch");
const box = el("input");
box.type = "checkbox";
box.setAttribute("role", "switch");
box.checked = stage.on;
box.setAttribute("aria-label", `Run ${stage.name} in the pull`);
const track = el("span", "switch-track");
track.setAttribute("aria-hidden", "true");
label.append(box, track, el("span", "switch-label", stage.on ? "On" : "Off"));
box.addEventListener("change", async () => {
box.disabled = true;
try {
Object.assign(stage, await window.api(`/api/stages/${stage.name}`,
{ method: "PUT", body: { on: box.checked } }));
} catch (err) {
box.checked = !box.checked;
box.disabled = false;
return;
}
rerender();
});
return label;
}
function renderStages(stages) {
const list = document.getElementById("stages-list");
list.replaceChildren();
for (const stage of stages) {
const row = el("div", "srow");
if (!stage.on) row.dataset.muted = "true";
const name = el("span", "name");
name.append(el("span", "", stage.name[0].toUpperCase() + stage.name.slice(1)),
el("span", "badge", stage.model));
row.append(name, stageSwitch(stage, () => renderStages(stages)));
const sub = el("span", "sub");
sub.append(`${DOES[stage.name]}. How deep it reads is set per search agent, under `);
const agents = el("a", "", "Search agents");
agents.href = "/settings/agents";
sub.append(agents, stage.source === "config"
? ". Following config.yaml until this switch is used."
: ".");
row.appendChild(sub);
list.appendChild(row);
}
const first = stages[0];
document.getElementById("stages-answer").textContent = first
? first.answer[0].toUpperCase() + first.answer.slice(1) + "."
+ (first.backend ? "" : " The switches still work, and a pull passes these stages until a model is reachable.")
: "";
}
async function loadStages() {
if (!document.getElementById("stages-list")) return;
try {
renderStages(await window.api("/api/stages"));
} catch (err) {
/* already toasted */
}
}
function update(state) {
pulling = (state.cascades || []).some((c) => isPull(c) && live(c));
paint();
}
loadStages();
document.addEventListener("app:jobs", (e) => update(e.detail || {}));
// A snapshot that arrived before this script loaded.
if (window.live && window.live.jobs) update(window.live.jobs);
+7
View File
@@ -111,6 +111,13 @@
</div>
<p class="lede">On the schedule below the pull reads every board, embed and score rank every role, extract fills in what the best postings say, score runs again with what it filled, and summarise writes the summaries.</p>
{# The two stages that ask a model, switched here rather than in config.yaml
(`GET /api/stages`); jobs.js draws the rows into #stages-list. #}
<h3 id="stages">What the model reads</h3>
<p class="lede">Extract and summarise ask a model, which costs tokens on the API. Turning one on starts nothing: the next pull runs it, and Run the pull now does so at once. How deep each reads is set per search agent, under <a href="/settings/agents">Search agents</a>.</p>
<div id="stages-list" class="srows"></div>
<p id="stages-answer" class="count" role="status"></p>
<h3>What is running</h3>
{# The element is the queue's own, served by its own router — see
pipeline/web/static/jobs.js; base.html loads its script. `idle="show"`
+26 -1
View File
@@ -247,7 +247,7 @@ def fetch_text(uid: str, store: StoreDep) -> Role:
@router.post("/roles/{uid}/summarise", status_code=202)
def summarise_role(uid: str, store: StoreDep, config: ConfigDep, queue: QueueDep) -> Job:
"""Queue a summary of one role, whatever its rank and whether or not the
pull summarises (`summarise.enabled`). The job's batch is this uid alone.
pull summarises (`jobs.stages`). The job's batch is this uid alone.
Pressed twice, the second press gets the first one's job."""
role = _known_role(store, uid)
if role.summary:
@@ -265,6 +265,31 @@ def summarise_role(uid: str, store: StoreDep, config: ConfigDep, queue: QueueDep
return job
# ------------------------------------------------------------------ stages
class StageBody(BaseModel):
on: bool
@router.get("/stages")
def list_stages(store: StoreDep, config: ConfigDep) -> list[jobs.stages.Stage]:
"""The two model stages of a pull: whether each is on, whether the
stored switch or config.yaml says so, its model, and who would answer."""
return jobs.stages.describe(config, store)
@router.put("/stages/{name}")
def set_stage(name: str, body: StageBody, store: StoreDep,
config: ConfigDep) -> jobs.stages.Stage:
"""Store the switch for one stage. Nothing starts: the next pull runs the
stage, or Run the pull now does so at once."""
try:
jobs.stages.set_stage(store, name, body.on)
except KeyError:
raise HTTPException(404, f"no such stage: {name}") from None
return jobs.stages.describe_one(config, store, name)
# --------------------------------------------------------------- companies
class CompanyOut(BaseModel):