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:
1 parent
a629eda8de
commit
471ace703c
15 files changed
+593
-23
No files matched your search
@@ -13,7 +13,7 @@ uv run app job pull # read every board and search, embed and score th
|
||||
uv run app serve # http://127.0.0.1:8790
|
||||
```
|
||||
|
||||
`uv run app worker` drains the queue without the web app, and `uv run pytest` runs the app's tests and the copied modules' own. `config.yaml` is the committed default, with one starter agent and four Copenhagen searches on Jobindex; `config.example.yaml` documents every key, including the `summarise:` block below.
|
||||
`uv run app worker` drains the queue without the web app, and `uv run pytest` runs the app's tests and the copied modules' own. `config.yaml` is the committed default, with one starter agent and four Copenhagen searches on Jobindex; `config.example.yaml` documents every key, including the `extract:` and `summarise:` blocks, which set the default for the two model stages; the switch under Settings, Sources, Runs overrides it without a restart, and `app stages` does the same from the command line.
|
||||
|
||||
## Sources: job boards and company boards
|
||||
|
||||
@@ -51,7 +51,7 @@ The cog opens `/settings`: a rail of pages on the left, the page beside it, stic
|
||||
|
||||
Likes, hidden companies and votes belong to a search agent, not to the account: two agents rank the same roles differently, and one may hide a company the other favours. An agent also learns from votes: its `taste` weight scores a role by how close it is to the roles the agent liked minus the ones it passed.
|
||||
|
||||
The reader, `/roles/{uid}`, shows the full posting: the same vote and Save controls, the company's own affinity, the tags and the summary when there is one. Opening a role marks it read, and so does a vote. A search role's posting is a teaser; the reader offers a Fetch button that scrapes the original listing once and stores the text. A Summarise button asks for a short summary of that one role; `config.yaml`'s `summarise:` block turns summarising on for the pull itself, bounded to the top roles of each agent by that agent's own `limits` so the cost stays flat.
|
||||
The reader, `/roles/{uid}`, shows the full posting: the same vote and Save controls, the company's own affinity, the tags and the summary when there is one. Opening a role marks it read, and so does a vote. A search role's posting is a teaser; the reader offers a Fetch button that scrapes the original listing once and stores the text. A Summarise button asks for a short summary of that one role; The switch under Settings, Sources, Runs (default from `config.yaml`'s `summarise:` block) turns summarising on for the pull itself, bounded to the top roles of each agent by that agent's own `limits` so the cost stays flat.
|
||||
|
||||
## Docs
|
||||
|
||||
|
||||
+32
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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)
|
||||
@@ -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
@@ -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
@@ -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
@@ -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);
|
||||
|
||||
@@ -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
@@ -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):
|
||||
|
||||
+6
-2
@@ -51,7 +51,9 @@ agent:
|
||||
# default: on the API backend every batch of 20 roles is a paid call. On, a
|
||||
# pull reads only the best roles of every enabled agent, as deep and as low
|
||||
# as that agent's own limits say (see agents below), after a first score; a
|
||||
# second score then applies the gates to what was filled.
|
||||
# second score then applies the gates to what was filled. `enabled` is only the
|
||||
# default for a fresh database: the switch under Settings, Sources, Runs (or
|
||||
# `app stages extract on|off`) overrides it and needs no restart.
|
||||
extract:
|
||||
enabled: false
|
||||
model: claude-haiku-4-5-20251001
|
||||
@@ -60,7 +62,9 @@ extract:
|
||||
# (app/jobs/summarise.py). Off by default. On, each pull summarises the best
|
||||
# roles of every enabled agent that have none yet, by that agent's limits, so
|
||||
# the cost stays bounded however many roles are open. The Summarise button on
|
||||
# a role's page asks for that one role either way.
|
||||
# a role's page asks for that one role either way. `enabled` is only the
|
||||
# default for a fresh database: the switch under Settings, Sources, Runs (or
|
||||
# `app stages summarise on|off`) overrides it and needs no restart.
|
||||
summarise:
|
||||
enabled: false
|
||||
model: claude-haiku-4-5-20251001
|
||||
|
||||
+4
-2
@@ -124,7 +124,7 @@ 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 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.
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
@@ -182,7 +182,9 @@ 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` scrapes `original_url` only when the read page asks for it, because following Jobindex's redirect 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.
|
||||
|
||||
**Summarising is bounded to the top roles of each agent, by that agent's own `limits`, and off by default.** 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. `summarise.enabled: false` matches `extract`'s own default; the read page's Summarise button asks for one role's summary either way.
|
||||
**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.
|
||||
|
||||
**`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.
|
||||
|
||||
**The schedules element's narrow layout is fixed upstream, in `../boilerplate`.** `<desk-schedules>` is a shadow root the app cannot lay out from outside, and `pipeline/` is a downstream copy refreshed with `git archive`, so a fix landing only in roledesk would be reverted by the next refresh.
|
||||
|
||||
|
||||
+1
-1
@@ -6,6 +6,6 @@ What is left after the phone rework of 2026-09-25, for whoever picks the repo up
|
||||
- **The boilerplate moved on.** Since roledesk's last refresh (`77052a8`, the schedules fix) it has `4573f6d` (the kit: the layout patterns every app built for itself, as classes) and `1679e88` (deploy from a WSL checkout, the sandbox setup). Refresh `deploy/` and `pipeline/` with `git archive`, and see whether `app/static/app.css` should use the kit's classes instead of its own copies of the same rules.
|
||||
- **Restart the server.** A server started before the rework runs the old code; on start the database migrates to schema v4 (vote, summary, article text on `roles`).
|
||||
- **The live database has two agents**, "Berlin backend" and "Remote EU stretch", so Ranking edits the first and the Roles order menu lists both by name. Delete one with the CLI for a plain Best match.
|
||||
- **Summarising is off** (`summarise.enabled: false`) and needs a model backend, as extract does. The Summarise button on a read page works either way once a backend is configured.
|
||||
- **Summarising is off** until the switch under Runs (default `summarise.enabled: false`) is used, and needs a model backend, as extract does. The Summarise button on a read page works either way once a backend is configured.
|
||||
- **Ranking's gates are still a JSON box** under Advanced. A form (country list, remote require or prefer) is the next step there.
|
||||
- **Votes do not train fit.** A vote only moves the rank at read time. Feeding votes into the intent vector is worth doing once there are a few hundred.
|
||||
@@ -0,0 +1,270 @@
|
||||
"""The switch for the two model stages: the stored setting beats config.yaml,
|
||||
every route to a stage asks the one function, and the API and `app stages`
|
||||
show and set it. Nothing here reaches a model."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Iterator
|
||||
from dataclasses import replace
|
||||
from datetime import UTC, datetime
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
from fastapi import FastAPI
|
||||
from fastapi.testclient import TestClient
|
||||
|
||||
from app import cli
|
||||
from app.config import Config, ServerConfig
|
||||
from app.jobs import cascade, stages
|
||||
from app.main import create_app
|
||||
from app.storage import Store
|
||||
from desk.models import Item
|
||||
from desk.tools import agent
|
||||
from pipeline import JOBS, TASKS
|
||||
|
||||
NAMES = ("extract", "summarise")
|
||||
|
||||
|
||||
def posting(source_id: str) -> Item:
|
||||
item = Item(source_id=source_id, location=f"https://boards.example/{source_id}",
|
||||
title=f"Backend Engineer {source_id}", body="Python and Go on Kubernetes.",
|
||||
published_at=datetime(2026, 9, 20, tzinfo=UTC),
|
||||
raw={"company": "Acme", "place": "Copenhagen"})
|
||||
item.source = "ats"
|
||||
return item
|
||||
|
||||
|
||||
def config(tmp_path: Path, on: bool = False) -> Config:
|
||||
return Config(database=str(tmp_path / "roledesk.db"),
|
||||
extract={"enabled": on}, summarise={"enabled": on})
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def store(tmp_path: Path) -> Store:
|
||||
return Store(tmp_path / "roledesk.db")
|
||||
|
||||
|
||||
def ranked(store: Store) -> None:
|
||||
"""Two roles scored well for one enabled agent: inside both stages' bounds."""
|
||||
for sid in ("1", "2"):
|
||||
store.upsert_role(posting(sid))
|
||||
one = store.save_agent("Backend", "python backend")
|
||||
store.replace_scores(one.id, [(posting("1").uid, 1.0, ""), (posting("2").uid, 0.9, "")])
|
||||
|
||||
|
||||
def answered_by(monkeypatch: pytest.MonkeyPatch, backend: str) -> None:
|
||||
monkeypatch.setattr(agent, "backend", lambda settings: backend)
|
||||
|
||||
|
||||
# ---------------------------------------------------------- the one decision
|
||||
|
||||
@pytest.mark.parametrize("name", NAMES)
|
||||
def test_a_stored_setting_beats_config_and_an_absent_one_falls_back(
|
||||
store: Store, tmp_path: Path, name: str) -> None:
|
||||
on, off = config(tmp_path, True), config(tmp_path, False)
|
||||
assert stages.stored(store, name) is None
|
||||
assert stages.stage_on(on, store, name) is True
|
||||
assert stages.stage_on(off, store, name) is False
|
||||
|
||||
stages.set_stage(store, name, True)
|
||||
assert store.state[f"stage:{name}"] == "on"
|
||||
assert stages.stage_on(off, store, name) is True
|
||||
|
||||
stages.set_stage(store, name, False)
|
||||
assert store.state[f"stage:{name}"] == "off"
|
||||
assert stages.stage_on(on, store, name) is False
|
||||
|
||||
del store.state[f"stage:{name}"]
|
||||
assert stages.stage_on(on, store, name) is True
|
||||
|
||||
|
||||
def test_one_stage_does_not_move_the_other_and_a_junk_value_is_absent(
|
||||
store: Store, tmp_path: Path) -> None:
|
||||
off = config(tmp_path, False)
|
||||
stages.set_stage(store, "extract", True)
|
||||
assert stages.stage_on(off, store, "summarise") is False
|
||||
store.state["stage:summarise"] = "maybe"
|
||||
assert stages.stage_on(off, store, "summarise") is False
|
||||
with pytest.raises(KeyError):
|
||||
stages.set_stage(store, "embed", True)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("name", NAMES)
|
||||
def test_a_pull_runs_a_stage_on_by_the_setting_though_config_says_off(
|
||||
store: Store, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, name: str) -> None:
|
||||
ranked(store)
|
||||
answered_by(monkeypatch, "api")
|
||||
stage = cascade.task(name, cascade="pull")
|
||||
assert stage.finder(config(tmp_path, False), store) == []
|
||||
|
||||
stages.set_stage(store, name, True)
|
||||
|
||||
[batch] = stage.finder(config(tmp_path, False), store)
|
||||
assert len(batch.payload["uids"]) == 2
|
||||
|
||||
|
||||
@pytest.mark.parametrize("name", NAMES)
|
||||
def test_a_pull_passes_a_stage_off_by_the_setting_though_config_says_on(
|
||||
store: Store, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, name: str) -> None:
|
||||
ranked(store)
|
||||
answered_by(monkeypatch, "api")
|
||||
stage = cascade.task(name, cascade="pull")
|
||||
assert len(stage.finder(config(tmp_path, True), store)) == 1
|
||||
|
||||
stages.set_stage(store, name, False)
|
||||
|
||||
assert stage.finder(config(tmp_path, True), store) == []
|
||||
|
||||
|
||||
@pytest.mark.parametrize("name", NAMES)
|
||||
def test_the_task_on_its_own_reads_the_same_setting(
|
||||
store: Store, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, name: str) -> None:
|
||||
"""`app job extract` and the `/api/jobs` entry point are the stage off the
|
||||
cascade: the same finder, the same switch."""
|
||||
ranked(store)
|
||||
answered_by(monkeypatch, "api")
|
||||
alone = TASKS[name]()
|
||||
assert alone.finder(config(tmp_path, False), store) == []
|
||||
stages.set_stage(store, name, True)
|
||||
assert len(alone.finder(config(tmp_path, False), store)) == 1
|
||||
|
||||
|
||||
# ------------------------------------------------------------------- the API
|
||||
|
||||
@pytest.fixture
|
||||
def app(tmp_path: Path) -> FastAPI:
|
||||
return create_app(Config(server=ServerConfig(host="127.0.0.1", port=0),
|
||||
database=tmp_path / "roledesk.db"))
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def client(app: FastAPI) -> Iterator[TestClient]:
|
||||
with TestClient(app) as c:
|
||||
yield c
|
||||
|
||||
|
||||
def test_get_stages_lists_both_with_their_source_model_and_who_answers(
|
||||
client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
answered_by(monkeypatch, "api")
|
||||
res = client.get("/api/stages")
|
||||
|
||||
assert res.status_code == 200
|
||||
assert res.json() == [
|
||||
{"name": "extract", "on": False, "source": "config",
|
||||
"model": "claude-haiku-4-5-20251001", "backend": "api",
|
||||
"answer": "answered by the Claude API"},
|
||||
{"name": "summarise", "on": False, "source": "config",
|
||||
"model": "claude-haiku-4-5-20251001", "backend": "api",
|
||||
"answer": "answered by the Claude API"},
|
||||
]
|
||||
|
||||
|
||||
def test_who_answers_is_said_for_the_api_claude_code_and_nobody(
|
||||
client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
answers = {}
|
||||
for backend in ("api", "claude_code", ""):
|
||||
answered_by(monkeypatch, backend)
|
||||
[first, second] = client.get("/api/stages").json()
|
||||
assert first["backend"] == second["backend"] == backend
|
||||
answers[backend] = first["answer"]
|
||||
|
||||
assert answers["api"] == "answered by the Claude API"
|
||||
assert answers["claude_code"] == "answered by the Claude Code sign-in on this machine"
|
||||
assert answers[""] == ("no model is reachable: set ANTHROPIC_API_KEY or "
|
||||
"CLAUDE_CODE_OAUTH_TOKEN, see docs/llm-backends.md")
|
||||
|
||||
|
||||
def test_put_stores_the_setting_returns_the_same_shape_and_starts_nothing(
|
||||
client: TestClient, store: Store) -> None:
|
||||
before = client.get("/api/jobs").json()
|
||||
|
||||
res = client.put("/api/stages/summarise", json={"on": True})
|
||||
|
||||
assert res.status_code == 200
|
||||
assert res.json()["name"] == "summarise"
|
||||
assert res.json()["on"] is True and res.json()["source"] == "stored"
|
||||
assert store.state["stage:summarise"] == "on"
|
||||
assert client.get("/api/stages").json()[0]["source"] == "config"
|
||||
assert client.get("/api/jobs").json() == before
|
||||
|
||||
res = client.put("/api/stages/summarise", json={"on": False})
|
||||
assert res.json()["on"] is False and store.state["stage:summarise"] == "off"
|
||||
|
||||
|
||||
def test_an_unknown_stage_is_404_and_a_bad_body_is_422(client: TestClient) -> None:
|
||||
assert client.put("/api/stages/embed", json={"on": True}).status_code == 404
|
||||
assert client.put("/api/stages/extract", json={"on": "sometimes"}).status_code == 422
|
||||
assert client.put("/api/stages/extract", json={}).status_code == 422
|
||||
|
||||
|
||||
def test_agent_backend_off_is_named_rather_than_blamed_on_missing_keys(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, store: Store) -> None:
|
||||
off = Config(database=str(tmp_path / "roledesk.db"), agent={"backend": "off"})
|
||||
[first, _] = stages.describe(off, store)
|
||||
assert first.backend == "" and "agent.backend" in first.answer
|
||||
|
||||
|
||||
def test_the_summarise_button_works_with_the_stage_off(
|
||||
app: FastAPI, store: Store, monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
"""Off by the stored setting over an `on` config: the button queues
|
||||
`summarise_batch` for one uid, which never asks the switch."""
|
||||
monkeypatch.setitem(JOBS, "summarise_batch",
|
||||
replace(JOBS["summarise_batch"], isolate=False, timeout=0.0))
|
||||
app.state.config.summarise.enabled = True
|
||||
stages.set_stage(store, "summarise", False)
|
||||
store.upsert_role(posting("1"))
|
||||
uid = posting("1").uid
|
||||
monkeypatch.setattr(agent, "backend", lambda settings: "api")
|
||||
monkeypatch.setattr(agent, "ask_json", lambda settings, **kw: agent.Reply(
|
||||
data={"summaries": [{"uid": i["uid"], "summary": "Backend role, Python."}
|
||||
for i in kw["question"]["summaries"]]}, backend="api"))
|
||||
|
||||
res = TestClient(app).post(f"/api/roles/{uid}/summarise")
|
||||
|
||||
assert res.status_code == 202
|
||||
app.state.queue.drain(timeout=30)
|
||||
assert store.role(uid).summary == "Backend role, Python." # type: ignore[union-attr]
|
||||
|
||||
|
||||
# ----------------------------------------------------------------- the CLI
|
||||
|
||||
def test_app_stages_prints_and_sets_through_the_same_function(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
|
||||
capsys: pytest.CaptureFixture[str]) -> None:
|
||||
answered_by(monkeypatch, "claude_code")
|
||||
path = tmp_path / "config.yaml"
|
||||
path.write_text(f"database: {tmp_path / 'roledesk.db'}\nextract:\n enabled: true\n")
|
||||
|
||||
assert cli.main(["-c", str(path), "stages"]) == 0
|
||||
out = capsys.readouterr().out.splitlines()
|
||||
assert out[0].startswith("extract") and " on " in out[0] and "config.yaml" in out[0]
|
||||
assert out[1].startswith("summarise") and " off " in out[1]
|
||||
assert "Claude Code sign-in" in out[1]
|
||||
|
||||
assert cli.main(["-c", str(path), "stages", "extract", "off"]) == 0
|
||||
line = capsys.readouterr().out.strip()
|
||||
assert line.startswith("extract") and " off " in line and "set by the switch" in line
|
||||
assert Store(tmp_path / "roledesk.db").state["stage:extract"] == "off"
|
||||
|
||||
assert cli.main(["-c", str(path), "stages", "summarise", "on"]) == 0
|
||||
capsys.readouterr()
|
||||
assert cli.main(["-c", str(path), "stages"]) == 0
|
||||
out = capsys.readouterr().out.splitlines()
|
||||
assert " off " in out[0] and " on " in out[1]
|
||||
|
||||
|
||||
def test_app_stages_wants_a_stage_and_a_state_together(
|
||||
tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
|
||||
path = tmp_path / "config.yaml"
|
||||
path.write_text(f"database: {tmp_path / 'roledesk.db'}\n")
|
||||
assert cli.main(["-c", str(path), "stages", "extract"]) == 1
|
||||
assert "on or off" in capsys.readouterr().err
|
||||
with pytest.raises(SystemExit):
|
||||
cli.main(["-c", str(path), "stages", "embed", "on"])
|
||||
|
||||
|
||||
def test_runs_has_the_switch_block(
|
||||
client: TestClient) -> None:
|
||||
page = client.get("/settings/sources").text
|
||||
assert 'id="stages"' in page and 'id="stages-list"' in page and 'id="stages-answer"' in page
|
||||
assert "Run the pull now does so at once" in page and "/settings/agents" in page
|
||||
Reference in new issue
Block a user