Summarise and fetch text: a summary stage after score, two role routes

app/jobs/summarise.py is a ModelTask beside extract: about 60 words per role
from title, company, place and the fetched page else the description (capped
at 8000 characters). The pull cascade gains a summarise stage after score that
takes only roles without a summary in the top summarise.per_agent of an
enabled agent's ungated scores, and finds nothing when summarise.enabled is
false or no model is reachable. A reply that leaves a role unanswered is
counted in the state table and the role is given up after three.

POST /api/roles/{uid}/text scrapes original_url once and stores
article_text; POST /api/roles/{uid}/summarise queues a summarise_batch for
that uid alone, deduped per role.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Fable 5.1 committed 2026-09-25 21:39:43 +02:00
1 parent 7d31cca394
commit 9035529e0d
12 files changed
+733 -10

No files matched your search

+2 -1
View File
@@ -407,5 +407,6 @@ def test_follows_walks_the_cascade_and_stops_at_its_end() -> None:
assert cascade.follows("pull", "pull") == "extract"
assert cascade.follows("pull", "extract") == "embed"
assert cascade.follows("pull", "embed") == "score"
assert cascade.follows("pull", "score") == ""
assert cascade.follows("pull", "score") == "summarise"
assert cascade.follows("pull", "summarise") == ""
assert cascade.follows("pull", "nope") == ""
+43
View File
@@ -312,3 +312,46 @@ def test_an_application_may_point_at_a_role(store: Store) -> None:
saved = store.save_application(Application(role_uid=posting().uid, status="applied"))
assert saved.role_uid == posting().uid
assert [e.status for e in store.application_events(saved.id)] == ["applied"]
# -------------------------------------------------- summary and posting text
def test_the_posting_text_is_stored_and_stamped(store: Store) -> None:
store.upsert_role(posting())
role = store.set_article_text(posting().uid, "The whole posting.")
assert role is not None
assert role.article_text == "The whole posting." and role.article_at == store.now()
assert store.set_article_text("nope", "x") is None
def test_a_summary_is_written_once(store: Store) -> None:
store.upsert_role(posting())
uid = posting().uid
assert store.set_summary(uid, "First.") is True
assert store.set_summary(uid, "Second.") is False
role = store.role(uid)
assert role is not None and role.summary == "First." and role.summarised_at
assert store.set_summary("nope", "x") is False
def test_summarise_waits_on_the_top_of_each_enabled_agent(store: Store) -> None:
"""Two agents each contribute their own top one; a closed role, a hidden
company's role and a gated score are not in anybody's top."""
for sid, company in (("a", "Acme"), ("b", "Acme"), ("c", "Hidden"), ("d", "Acme")):
store.upsert_role(posting(sid, company=company))
a, b, c, d = (posting(s).uid for s in "abcd")
store.add_company("Hidden", key="hidden", affinity=-1)
with store.transaction() as conn:
conn.execute("UPDATE roles SET closed_at = ? WHERE uid = ?", (store.now(), d))
one = store.save_agent("One")
two = store.save_agent("Two")
store.replace_scores(one.id, [(d, 0.99, ""), (a, 0.9, ""), (b, 0.5, "")])
store.replace_scores(two.id, [(a, 0.95, "remote"), (c, 0.9, ""), (b, 0.8, "")])
waiting = {r.uid for r in store.summarise_waiting(10, per_agent=1)}
# `c` is agent two's best open ungated role but its company is hidden.
assert waiting == {a}
assert {r.uid for r in store.summarise_waiting(10, per_agent=2)} == {a, b}
assert store.summarise_pending(per_agent=2) == 2
assert [r.uid for r in store.summarise_waiting(10, 1, uids=[d])] == [d]
+197
View File
@@ -0,0 +1,197 @@
"""The `summarise` task, with the model call stubbed: which roles are offered,
what one item carries, what an answer writes, and the cascade stage. Nothing
here reaches a model."""
from __future__ import annotations
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
import pytest
from app.config import Config
from app.jobs import cascade, summarise
from app.storage import Store
from desk import modeltask
from desk.models import Item
from desk.tools import agent
from pipeline import TASKS
def posting(source_id: str, body: str = "Python and Go on Kubernetes. Pays 700k DKK.",
**raw: object) -> Item:
item = Item(source_id=source_id, location=f"https://boards.example/{source_id}",
title=f"Backend Engineer {source_id}", body=body,
published_at=datetime(2026, 9, 20, tzinfo=UTC),
raw={"company": "Acme", "place": "Copenhagen", **raw})
item.source = "ats"
return item
class Model:
"""Stands in for `agent.ask_json`: records what it was asked and hands
back whatever `reply` builds from the batch."""
def __init__(self, reply: Any) -> None:
self.reply = reply
self.asked: list[list[dict[str, Any]]] = []
def __call__(self, settings: Any, **kwargs: Any) -> agent.Reply:
items = kwargs["question"]["summaries"]
self.asked.append(items)
return agent.Reply(data={"summaries": self.reply(items)}, backend="api")
def written(items: list[dict[str, Any]]) -> list[dict[str, str]]:
return [{"uid": i["uid"], "summary": f"A backend role at Acme, {i['uid']}."}
for i in items]
def stub(monkeypatch: pytest.MonkeyPatch, reply: Any = written) -> Model:
model = Model(reply)
monkeypatch.setattr(agent, "backend", lambda settings: "api")
monkeypatch.setattr(agent, "ask_json", model)
return model
@pytest.fixture
def store(tmp_path: Path) -> Store:
return Store(tmp_path / "roledesk.db")
@pytest.fixture
def config(tmp_path: Path) -> Config:
return Config(database=str(tmp_path / "roledesk.db"),
summarise={"enabled": True, "per_agent": 2})
def ranked(store: Store, *ids: str, agent_name: str = "Backend",
enabled: bool = True) -> list[str]:
"""Store a role per id and score them for one agent, best first."""
uids = []
for sid in ids:
store.upsert_role(posting(sid))
uids.append(posting(sid).uid)
one = store.save_agent(agent_name, "python backend", enabled=enabled)
store.replace_scores(one.id, [(uid, 1.0 - n / 10, "") for n, uid in enumerate(uids)])
return uids
def test_a_batch_writes_the_summary_and_stamps_summarised_at(
store: Store, config: Config, monkeypatch: pytest.MonkeyPatch) -> None:
[uid] = ranked(store, "1")
model = stub(monkeypatch)
result = modeltask.run(summarise.TASK, config, store)
role = store.role(uid)
assert role is not None
assert role.summary == f"A backend role at Acme, {uid}."
assert role.summarised_at is not None
assert result["summarised"] == 1 and result["pending"] == 0
[[item]] = model.asked
assert item == {"uid": uid, "title": "Backend Engineer 1", "company": "Acme",
"place": "Copenhagen", "text": "Python and Go on Kubernetes. Pays 700k DKK."}
def test_the_fetched_page_is_read_before_the_description_and_capped(
store: Store, config: Config, monkeypatch: pytest.MonkeyPatch) -> None:
[uid] = ranked(store, "1")
store.set_article_text(uid, "word " * 3000)
model = stub(monkeypatch)
modeltask.run(summarise.TASK, config, store)
text = model.asked[0][0]["text"]
assert text.startswith("word word") and len(text) == summarise.EXCERPT
def test_only_the_top_of_an_enabled_agent_without_a_summary_is_offered(
store: Store, config: Config, monkeypatch: pytest.MonkeyPatch) -> None:
first, second, third = ranked(store, "1", "2", "3")
ranked(store, "4", agent_name="Off", enabled=False)
store.set_summary(first, "Already written, long enough.")
gated = posting("5")
store.upsert_role(gated)
backend = store.agents()[0]
store.replace_scores(backend.id, [(first, 0.9, ""), (second, 0.8, ""),
(third, 0.7, ""), (gated.uid, 0.95, "remote")])
model = stub(monkeypatch)
modeltask.run(summarise.TASK, config, store)
# The top two ungated are `first` and `second`; `first` has one already.
assert [[i["uid"] for i in batch] for batch in model.asked] == [[second]]
def test_a_role_with_no_text_is_skipped_not_sent(
store: Store, config: Config, monkeypatch: pytest.MonkeyPatch) -> None:
store.upsert_role(posting("1", body=" "))
empty = posting("1").uid
one = store.save_agent("Backend", "python")
store.replace_scores(one.id, [(empty, 0.9, "")])
model = stub(monkeypatch)
modeltask.run(summarise.TASK, config, store)
summarise.run_batch(config, store, uids=[empty])
assert model.asked == []
assert store.summarise_pending(config.summarise.per_agent) == 0
def test_a_named_uid_is_summarised_whatever_its_rank_or_the_switch(
store: Store, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""The read page's button: a batch of one uid, with `enabled` off and the
role in nobody's top list."""
store.upsert_role(posting("1"))
uid = posting("1").uid
stub(monkeypatch)
off = Config(database=str(tmp_path / "roledesk.db"))
result = summarise.run_batch(off, store, uids=[uid])
assert result["summarised"] == 1
assert store.role(uid).summary # type: ignore[union-attr]
def test_an_unknown_or_empty_answer_is_rejected_and_the_role_given_up_after_three(
store: Store, config: Config, monkeypatch: pytest.MonkeyPatch) -> None:
[uid] = ranked(store, "1")
stub(monkeypatch, lambda items: [{"uid": "not-in-the-batch", "summary": "A role."},
{"uid": items[0]["uid"], "summary": "N/A"}])
result = modeltask.run(summarise.TASK, config, store)
assert result["rejected"] == ["not-in-the-batch", uid]
assert store.role(uid).summary == "" # type: ignore[union-attr]
assert store.summarise_pending(2) == 1
modeltask.run(summarise.TASK, config, store)
modeltask.run(summarise.TASK, config, store)
assert store.summarise_pending(2) == 0, "given up after three unanswered replies"
def test_disabled_finds_nothing_and_asks_nobody(
store: Store, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
ranked(store, "1")
model = stub(monkeypatch)
result = modeltask.run(summarise.TASK, Config(database=str(tmp_path / "x.db")), store)
assert model.asked == [] and result["summarised"] == 0
def test_summarise_follows_score_and_finds_nothing_without_a_model(
store: Store, config: Config, monkeypatch: pytest.MonkeyPatch) -> None:
ranked(store, "1", "2")
assert cascade.follows("pull", "score") == "summarise"
assert "summarise" in TASKS
stage = cascade.task("summarise", cascade="pull")
monkeypatch.setattr(agent, "backend", lambda settings: "")
assert stage.finder(config, store) == []
monkeypatch.setattr(agent, "backend", lambda settings: "api")
[batch] = stage.finder(config, store)
assert len(batch.payload["uids"]) == 2
assert stage.kind == "summarise_batch" and stage.callback == cascade.STEP
+82
View File
@@ -496,3 +496,85 @@ def test_prune_previews_then_switches_off(client: TestClient, store: Store) -> N
done = client.post("/api/prune", json={"region": "DK,EU"}).json()
assert (done["pruned"], done["roles_closed"], done["boards_left"]) == (1, 1, 1)
assert client.get("/api/prune", params={"region": " "}).status_code == 422
# ------------------------------------------------- roles: text and summary
def test_the_posting_text_is_fetched_once(
client: TestClient, store: Store, monkeypatch: pytest.MonkeyPatch) -> None:
from desk.tools import scrape
from desk.tools.article import ArticleContent
store.upsert_role(posting("1"))
uid = posting("1").uid
asked: list[str] = []
def gone(url: str) -> scrape.Scraped:
asked.append(url)
return scrape.Scraped(None, "not_found", "http", ())
monkeypatch.setattr(scrape, "scrape", gone)
assert client.post("/api/roles/nope/text").status_code == 404
res = client.post(f"/api/roles/{uid}/text")
assert res.status_code == 422 and "gone" in res.json()["detail"]
assert asked == ["https://boards.example/acme/1"]
def found(url: str) -> scrape.Scraped:
content = ArticleContent(format="plain", content=" The whole posting.\n",
source_url=url, method="test")
return scrape.Scraped(content, "", "http", ())
monkeypatch.setattr(scrape, "scrape", found)
res = client.post(f"/api/roles/{uid}/text")
assert res.status_code == 200
body = res.json()
assert body["uid"] == uid and body["article_text"] == "The whole posting."
assert body["article_at"]
assert client.post(f"/api/roles/{uid}/text").status_code == 409
def test_summarise_queues_one_role_and_the_job_writes_it(
app: FastAPI, store: Store, monkeypatch: pytest.MonkeyPatch) -> None:
"""No lifespan, so no worker: the job waits in the table until drained."""
from typing import Any
from desk.tools import agent
client = TestClient(app)
store.upsert_role(posting("1"))
store.upsert_role(posting("2"))
uid, bare = posting("1").uid, posting("2").uid
with store.transaction() as conn:
conn.execute("UPDATE roles SET description = '' WHERE uid = ?", (bare,))
monkeypatch.setattr(agent, "backend", lambda settings: "")
assert client.post("/api/roles/nope/summarise").status_code == 404
res = client.post(f"/api/roles/{uid}/summarise")
assert res.status_code == 422 and "model" in res.json()["detail"]
asked: list[Any] = []
def ask_json(settings: Any, **kwargs: Any) -> agent.Reply:
items = kwargs["question"]["summaries"]
asked.append([i["uid"] for i in items])
return agent.Reply(data={"summaries": [
{"uid": i["uid"], "summary": "Backend role in Berlin, Python."}
for i in items]}, backend="api")
monkeypatch.setattr(agent, "backend", lambda settings: "api")
monkeypatch.setattr(agent, "ask_json", ask_json)
res = client.post(f"/api/roles/{bare}/summarise")
assert res.status_code == 422 and "no text" in res.json()["detail"]
res = client.post(f"/api/roles/{uid}/summarise")
assert res.status_code == 202
job = res.json()
assert job["kind"] == "summarise_batch" and job["payload"] == {"uids": [uid]}
assert job["state"] == "queued"
assert client.post(f"/api/roles/{uid}/summarise").json()["id"] == job["id"]
app.state.queue.drain(timeout=30)
assert asked == [[uid]]
assert store.role(uid).summary == "Backend role in Berlin, Python." # type: ignore[union-attr]
assert client.post(f"/api/roles/{uid}/summarise").status_code == 409