Per-agent ranking: votes, affinity and a taste term; settings are three sub-tabs

Votes on roles and company affinity move to role_votes and agent_companies,
one row per search agent, so two agents rank the same roles differently. The
score gains taste, the cosine to mean(liked) - mean(passed) of the agent's
votes, as newsdesk ranks articles. The API takes agent on roles, votes and
companies and falls back to the default agent, the enabled one with the
lowest id.

Settings become Search agents (a list again, with New and Delete), Sources
(job boards, company boards and runs with the message log, one section per
plugin) and Account. Old paths answer 301 to their section.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Fable 5.1 committed 2026-09-28 12:53:41 +02:00
1 parent 515d2250fc
commit a0772519b3
28 files changed
+1461 -668

No files matched your search

+68 -24
View File
@@ -28,16 +28,42 @@ from pipeline.web import QueueDep
router = APIRouter(prefix="/api", tags=["roledesk"])
# ------------------------------------------------------------------ agent
def _agent_id(store: Store, agent: int | None) -> int | None:
"""The agent a request means: the one named (404 when unknown), else the
default (`Store.default_agent`), else None when there is no agent at all."""
if agent is not None:
if store.agent(agent) is None:
raise HTTPException(404, f"no such agent: {agent}")
return agent
found = store.default_agent()
return found.id if found else None
def _agent_or_default(store: Store, agent: int | None) -> Agent:
"""`_agent_id` for a write, which has to land somewhere: 422 when no
agent exists yet."""
agent_id = _agent_id(store, agent)
found = store.agent(agent_id) if agent_id is not None else None
if found is None:
raise HTTPException(422, "No search agent exists yet. Add one under Settings.")
return found
# ------------------------------------------------------------------- roles
class VoteBody(BaseModel):
value: Literal[-1, 0, 1]
#: Whose vote; the default agent when absent.
agent: int | None = None
@router.get("/roles/{uid}")
def get_role(uid: str, store: StoreDep) -> Role:
"""One role, open or closed, for the read page."""
role = store.role(uid)
def get_role(uid: str, store: StoreDep, agent: int | None = None) -> Role:
"""One role, open or closed, for the read page, with `agent`'s vote (the
default agent's when absent; None when there is no agent)."""
role = store.role(uid, _agent_id(store, agent))
if role is None:
raise HTTPException(404, f"no such role: {uid}")
return role
@@ -45,19 +71,23 @@ def get_role(uid: str, store: StoreDep) -> Role:
@router.post("/roles/{uid}/vote")
def vote_role(uid: str, body: VoteBody, store: StoreDep) -> Role:
"""1 like, 0 neither way, -1 pass. The role stays listed either way; the
vote moves it in a ranking, see `Store.roles`."""
"""1 like, 0 neither way, -1 pass, for `body.agent` or the default agent.
The role stays listed either way; the vote moves it in that agent's
ranking, see `Store.roles`, and shapes its taste at the next `score`."""
owner = _agent_or_default(store, body.agent)
try:
return store.set_vote(uid, body.value)
return store.set_vote(owner.id, uid, body.value)
except KeyError:
raise HTTPException(404, f"no such role: {uid}") from None
@router.delete("/roles/{uid}/vote")
def unvote_role(uid: str, store: StoreDep) -> Role:
"""Unjudged again: what pressing the stance a role already has does."""
def unvote_role(uid: str, store: StoreDep, agent: int | None = None) -> Role:
"""Unjudged again for `agent` or the default agent: what pressing the
stance a role already has does."""
owner = _agent_or_default(store, agent)
try:
return store.set_vote(uid, None)
return store.set_vote(owner.id, uid, None)
except KeyError:
raise HTTPException(404, f"no such role: {uid}") from None
@@ -80,25 +110,31 @@ def list_roles(
days: int | None = None,
show_muted: bool = False,
agent: int | None = None,
order: Literal["score", "newest"] = "score",
gated: bool = False,
judged: Literal["", "liked", "unjudged", "passed"] = "",
offset: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(ge=1, le=1000)] = 60,
) -> RolesPage:
"""Open roles, newest first, `limit` of them from `offset`, with the
total. See `Store.roles` for what each filter does.
"""Open roles, `limit` of them from `offset`, with the total. See
`Store.roles` for what each filter does.
A muted company's roles are left out unless `show_muted` is set. With
`agent`, ordered by that agent's score moved by the role's vote, and
carrying `score` and `gated_reason`; a gated role only with `gated=1`.
`judged` keeps the liked, the unjudged or the passed."""
if agent is not None and store.agent(agent) is None:
raise HTTPException(404, f"no such agent: {agent}")
`agent` says whose votes, hidden companies and scores are meant. Each
role carries that agent's `vote`; a company it hid is left out unless
`show_muted` is set; `judged` keeps the liked, the unjudged or the
passed. With `order=score` (the default) the roles are the ones that
agent scored, best first, carrying `score` and `gated_reason`, a gated
one only with `gated=1`; with `order=newest` every open role, newest
first, with no score. Without `agent` the default agent's votes and
hidden companies apply, the order is newest and there is no score; with
no agent at all, every vote is None and nothing is hidden."""
agent_id = _agent_id(store, agent)
by_score = agent is not None and order == "score"
filters: dict[str, Any] = {
"q": q or None, "company": company or None, "place": place or None,
"function": function or None, "remote": remote or None, "days": days,
"hide_muted": not show_muted, "agent": agent, "gated": gated,
"judged": judged or None}
"hide_muted": not show_muted, "agent": agent_id, "by_score": by_score,
"gated": gated, "judged": judged or None}
return RolesPage(items=store.roles(limit=limit, offset=offset, **filters),
total=store.count_roles(**filters))
@@ -200,11 +236,13 @@ def _company_boards(store: Store) -> dict[str, tuple[int, str, bool]]:
@router.get("/companies")
def list_companies(store: StoreDep) -> list[CompanyOut]:
def list_companies(store: StoreDep, agent: int | None = None) -> list[CompanyOut]:
"""Every company, with `affinity` as `agent` (the default agent when
absent) has it; 0 throughout when there is no agent."""
boards = _company_boards(store)
counts = store.open_role_counts()
out = []
for c in store.companies():
for c in store.companies(_agent_id(store, agent)):
sub_id, host, on = boards.get(c.key, (None, "", None))
out.append(CompanyOut(key=c.key, name=c.name, board=host,
subscription_id=sub_id, on=on, affinity=c.affinity,
@@ -214,16 +252,21 @@ def list_companies(store: StoreDep) -> list[CompanyOut]:
class AffinityBody(BaseModel):
affinity: int
#: Whose affinity; the default agent when absent.
agent: int | None = None
@router.post("/companies/{key}/affinity")
def set_affinity(key: str, body: AffinityBody, store: StoreDep, queue: QueueDep) -> Company:
"""A change here is not seen in Best match until `score` has run: the
queue dedupes to a live job of that kind, so several clicks are one run."""
"""-1 hidden, 0 neutral, 1 liked, 2 favourite, for `body.agent` or the
default agent. A change here is not seen in Best match until `score` has
run: the queue dedupes to a live job of that kind, so several clicks are
one run."""
if body.affinity not in AFFINITY:
raise HTTPException(422, "affinity is -1, 0, 1 or 2")
owner = _agent_or_default(store, body.agent)
try:
company = store.update_company(key, affinity=body.affinity)
company = store.set_affinity(owner.id, key, body.affinity)
except KeyError:
raise HTTPException(404, f"no such company: {key}") from None
queue.enqueue("score")
@@ -482,6 +525,7 @@ def save_agent(body: AgentBody, store: StoreDep) -> Agent:
@router.delete("/agents/{agent_id}", status_code=204)
def delete_agent(agent_id: int, store: StoreDep) -> Response:
"""Its scores, votes and affinities go with it."""
if not store.delete_agent(agent_id):
raise HTTPException(404, f"no such agent: {agent_id}")
return Response(status_code=204)
+46 -47
View File
@@ -1,26 +1,32 @@
"""The pages: two tabs, a cog, and six settings pages behind it.
"""The pages: two tabs, a cog, and three settings pages behind it.
`TABS` is the top bar, Roles and Applications, and `SETTINGS` is the row of
sub-tabs under the cog at `/settings/<name>`: the setup pages first (Ranking,
Searches, Companies), the system ones after (Pulls, Messages, Account).
sub-tabs under the cog at `/settings/<name>`: Search agents, Sources, Account.
`base.html` renders the first, `settings/_tabs.html` the second, every page
marks itself active by its own `path`, and adding one is one entry here plus
one template. `/settings` itself is Ranking.
one template. `/settings` itself is Search agents.
Every page is a shell. Each is filled and driven by its own script under
`static/` from the JSON routes in `web/api.py`; Pulls and Account are shells
around the modules' own elements. What the server renders is only what a
select needs to offer, so the options cannot drift from what the store
accepts.
`static/` from the JSON routes in `web/api.py`; the Runs section of Sources
and the Account page are shells around the modules' own elements. What the
server renders is only what a select needs to offer, so the options cannot
drift from what the store accepts.
The pages that were tabs before the settings shell (`/agents`, `/companies`,
`/sources`, `/jobs`, `/schedules`, `/messages`, `/account`) answer 301 to
their new place, query string kept, so a bookmark still lands.
Sources is one page in three sections, one per plugin: job boards (the
`search` plugin's queries), company boards (`ats`) and the runs that read
them, with the message log at the end. Its scripts are the ones the sections
had as pages of their own, each guarding on its own root element.
Every path a page has had before (`/agents`, `/companies`, `/sources`,
`/jobs`, `/schedules`, `/messages`, `/account`, and the six sub-tabs the
settings shell started with) answers 301 to its place now, query string
kept, so a bookmark still lands. A merged page's old path lands on its
section's anchor.
`FUNCTIONS` is `plugins.ats`'s, not `app`'s: the nine job functions are the
classifier's vocabulary, and this reaches `plugins/` the same way `app.cli`
does, since a plugin is app-agnostic and never reaches back into `app`. The
Jobindex areas and Adzuna countries on the Searches page come from
Jobindex areas and Adzuna countries on the Sources page come from
`plugins.search` for the same reason.
"""
@@ -64,22 +70,25 @@ TABS: tuple[Tab, ...] = (
#: The sub-tabs under the cog, in order; `settings/_tabs.html` renders them.
SETTINGS: tuple[Tab, ...] = (
Tab("/settings/ranking", "Ranking", "settings/ranking.html"),
Tab("/settings/searches", "Searches", "settings/searches.html"),
Tab("/settings/companies", "Companies", "settings/companies.html"),
Tab("/settings/pulls", "Pulls", "settings/pulls.html"),
Tab("/settings/messages", "Messages", "settings/messages.html"),
Tab("/settings/agents", "Search agents", "settings/agents.html"),
Tab("/settings/sources", "Sources", "settings/sources.html"),
Tab("/settings/account", "Account", "settings/account.html"),
)
#: Where each page that used to be a tab lives now.
#: Where each page that used to be a tab or a sub-tab lives now. The fragment
#: is the section on the merged page; a browser keeps it across the 301.
MOVED: dict[str, str] = {
"/agents": "/settings/ranking",
"/companies": "/settings/companies",
"/sources": "/settings/searches",
"/jobs": "/settings/pulls",
"/schedules": "/settings/pulls",
"/messages": "/settings/messages",
"/agents": "/settings/agents",
"/settings/ranking": "/settings/agents",
"/companies": "/settings/sources#company-boards",
"/settings/companies": "/settings/sources#company-boards",
"/sources": "/settings/sources#job-boards",
"/settings/searches": "/settings/sources#job-boards",
"/jobs": "/settings/sources#runs",
"/schedules": "/settings/sources#runs",
"/settings/pulls": "/settings/sources#runs",
"/messages": "/settings/sources#messages",
"/settings/messages": "/settings/sources#messages",
"/account": "/settings/account",
}
@@ -142,42 +151,32 @@ def settings() -> RedirectResponse:
return RedirectResponse(SETTINGS[0].path, status_code=302)
@router.get("/settings/ranking", response_class=HTMLResponse)
def ranking(request: Request) -> HTMLResponse:
return page(request, "settings/ranking.html")
@router.get("/settings/agents", response_class=HTMLResponse)
def agents(request: Request) -> HTMLResponse:
return page(request, "settings/agents.html")
@router.get("/settings/searches", response_class=HTMLResponse)
def searches(request: Request) -> HTMLResponse:
return page(request, "settings/searches.html", areas=AREA_OPTIONS,
@router.get("/settings/sources", response_class=HTMLResponse)
def sources(request: Request) -> HTMLResponse:
return page(request, "settings/sources.html", areas=AREA_OPTIONS,
countries=COUNTRY_OPTIONS)
@router.get("/settings/companies", response_class=HTMLResponse)
def companies(request: Request) -> HTMLResponse:
return page(request, "settings/companies.html")
@router.get("/settings/pulls", response_class=HTMLResponse)
def pulls(request: Request) -> HTMLResponse:
return page(request, "settings/pulls.html")
@router.get("/settings/messages", response_class=HTMLResponse)
def messages(request: Request) -> HTMLResponse:
return page(request, "settings/messages.html")
@router.get("/settings/account", response_class=HTMLResponse)
def account(request: Request) -> HTMLResponse:
return page(request, "settings/account.html")
def _moved(to: str) -> Callable[[Request], RedirectResponse]:
"""A 301 to `to`, carrying the query string, so `/agents?x=1` keeps it."""
"""A 301 to `to`, carrying the query string, so `/agents?x=1` keeps it.
The query goes before `to`'s fragment, if it has one, or the browser
would read `#runs?x=1` as one fragment."""
path, _, fragment = to.partition("#")
def redirect(request: Request) -> RedirectResponse:
query = request.url.query
return RedirectResponse(f"{to}?{query}" if query else to, status_code=301)
target = f"{path}?{query}" if query else path
return RedirectResponse(f"{target}#{fragment}" if fragment else target,
status_code=301)
return redirect