Files
jobboard/app/web/api.py
T
WolfandClaude Fable 5.1 c69fb0b6c4 Merge main: read state and tags meet per-agent votes and affinity
The per-agent migration becomes v6 behind main's v5. A vote still stamps
the role's read_at, tag counts hide the agent's hidden companies, and
/api/filters takes the agent like /api/roles.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-28 12:59:41 +02:00

582 lines
22 KiB
Python

"""The JSON routes the tabs use: roles, companies, sources, applications,
agents.
`/api/jobs*`, `/api/schedules*`, `/api/notices` and `/ws/jobs` are
`pipeline.web`'s and `/api/account*` is `auth`'s, both wired in `app/main.py`.
This is roledesk's own API, over the same store. Every refusal is
`{"detail": "<sentence>"}`, which `api()` in `static/app.js` turns into a toast.
"""
from __future__ import annotations
from typing import Annotated, Any, Literal
from fastapi import APIRouter, HTTPException, Query, Response
from pydantic import BaseModel, Field
from app import jobs
from app.models import (
AFFINITY, Agent, Application, Company, Gate, Role, ScoredRole, Status, Subscription,
Weights, company_key,
)
from app.storage import Store
from app.web.deps import ConfigDep, StoreDep
from desk.tools import agent, scrape
from pipeline import Job
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, 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
@router.post("/roles/{uid}/vote")
def vote_role(uid: str, body: VoteBody, store: StoreDep) -> Role:
"""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(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, 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(owner.id, uid, None)
except KeyError:
raise HTTPException(404, f"no such role: {uid}") from None
@router.post("/roles/{uid}/read")
def read_role(uid: str, store: StoreDep) -> Role:
"""Mark a role read. Never hides it; a vote does this too, see `vote_role`."""
try:
return store.set_read(uid, True)
except KeyError:
raise HTTPException(404, f"no such role: {uid}") from None
@router.delete("/roles/{uid}/read")
def unread_role(uid: str, store: StoreDep) -> Role:
"""Unread again: what pressing the state a role already has does."""
try:
return store.set_read(uid, False)
except KeyError:
raise HTTPException(404, f"no such role: {uid}") from None
class RolesPage(BaseModel):
"""One page of roles, and how many the same filters match in all."""
items: list[ScoredRole]
total: int
@router.get("/roles")
def list_roles(
store: StoreDep,
q: str = "",
company: str = "",
place: str = "",
function: str = "",
remote: str = "",
days: int | None = None,
show_muted: bool = False,
include_read: bool = True,
tags: list[str] = Query(default=[]),
tag_mode: Literal["any", "all"] = "any",
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, `limit` of them from `offset`, with the total. See
`Store.roles` for what each filter does.
`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.
`include_read` set false hides a role already marked read. `tags` is
`?tags=a&tags=b`, kept to a role with any of them or, with
`tag_mode=all`, every one."""
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, "include_read": include_read, "tags": tags,
"tag_mode": tag_mode, "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))
class TagCount(BaseModel):
"""One tag as the filter row offers it: how many open roles carry it and
how many of those are unread."""
tag: str
count: int
unread: int
class FiltersOut(BaseModel):
tags: list[TagCount]
@router.get("/filters")
def list_filters(store: StoreDep, show_muted: bool = False,
agent: int | None = None) -> FiltersOut:
"""The tag vocabulary for the feed's filter row, most-used first. The
companies `agent` hid (the default agent's without one) are left out
unless `show_muted`, matching `/api/roles`."""
hidden_for = _agent_id(store, agent)
return FiltersOut(tags=[TagCount(tag=tag, count=count, unread=unread)
for tag, count, unread in store.tag_counts(hidden_for, show_muted)])
# ------------------------------------------------- roles: text and summary
#: What the read page toasts when a posting page gave nothing readable, by
#: `desk.tools.failures` category.
_UNREADABLE = {
"timeout": "The posting page took too long to answer. Try again in a minute.",
"unreachable": "The posting page could not be reached.",
"rate_limited": "The posting site is refusing requests for now. Try again later.",
"server_error": "The posting site answered with an error. Try again later.",
"not_found": "The posting page is gone, so the role has probably closed.",
"denied": "The posting site refused to show the page.",
"consent_wall": "The posting page showed a consent banner instead of the posting.",
"js_required": "The posting page only renders in a browser. Open it with the link instead.",
"empty": "The posting page had no readable text on it.",
}
def _known_role(store: Store, uid: str) -> Role:
role = store.role(uid)
if role is None:
raise HTTPException(404, f"no such role: {uid}")
return role
@router.post("/roles/{uid}/text")
def fetch_text(uid: str, store: StoreDep) -> Role:
"""Fetch the posting page once and keep it as plain text, for a role whose
description is a teaser. Synchronous: one request the person asked for,
and on demand rather than in the pull because each fetch of a Jobindex
redirect counts as a click in its statistics."""
role = _known_role(store, uid)
if role.article_text:
raise HTTPException(409, "The posting text is already fetched.")
if not role.original_url:
raise HTTPException(422, "This role has no link to fetch the posting from.")
got = scrape.scrape(role.original_url)
text = got.content.plain_text.strip() if got.content is not None else ""
if not text:
raise HTTPException(422, _UNREADABLE.get(
got.failure, "Nothing readable came back from the posting page."))
updated = store.set_article_text(uid, text)
if updated is None:
raise HTTPException(404, f"no such role: {uid}")
return updated
@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.
Pressed twice, the second press gets the first one's job."""
role = _known_role(store, uid)
if role.summary:
raise HTTPException(409, "This role already has a summary.")
if not (role.article_text.strip() or role.description.strip()):
raise HTTPException(422, "This role has no text to summarise. Fetch the posting first.")
if not agent.backend(config.agent):
raise HTTPException(422, "No model is reachable from here, so nothing can "
"write a summary. Set up the API key or Claude Code.")
job = queue.enqueue(f"{jobs.summarise.TASK.kind}_batch", {"uids": [uid]},
label=f"Summarising {role.title or uid}",
dedup_key=f"summarise:{uid}")
if job is None:
raise HTTPException(409, "The summary would not start.")
return job
# --------------------------------------------------------------- companies
class CompanyOut(BaseModel):
"""A company row plus what only the store can join in: the ats host it is
read from (empty for a company known only from a search), the id of that
board's subscription, whether it is on, and how many of its roles are
still open."""
key: str
name: str
board: str
subscription_id: int | None = None
on: bool | None = None
affinity: int
open_roles: int
def _company_boards(store: Store) -> dict[str, tuple[int, str, bool]]:
"""`company_key -> (subscription id, ats host, on)`, read off each
company's own subscription. Same join as `Store.company_boards`, with the
id and switch state a company row needs to draw its own on/off control
rather than fetching `/api/sources` as well."""
boards: dict[str, tuple[int, str, bool]] = {}
for sub in store.subscriptions(source="ats"):
boards.setdefault(company_key(sub.company), (sub.id, sub.board,
bool(sub.subscribed and sub.fetch)))
return boards
@router.get("/companies")
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(_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,
open_roles=counts.get(c.key, 0)))
return out
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:
"""-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.set_affinity(owner.id, key, body.affinity)
except KeyError:
raise HTTPException(404, f"no such company: {key}") from None
queue.enqueue("score")
return company
# ----------------------------------------------------------------- sources
class SourceOut(BaseModel):
"""A board or a saved search, with what it brings in: its open roles, and
the countries they are in, most first."""
id: int
source: str
target: str
label: str
provider: str
params: dict[str, Any]
on: bool
open_roles: int
countries: list[tuple[str, int]]
class SourcesOut(BaseModel):
searches: list[SourceOut]
boards: list[SourceOut]
#: Whether an adzuna search can run: a key in the config or the environment.
adzuna_key: bool
def _source_out(sub: Subscription, countries: dict[str, int]) -> SourceOut:
return SourceOut(
id=sub.id, source=sub.source, target=sub.target, label=sub.label,
provider=sub.board, params=sub.params, on=bool(sub.subscribed and sub.fetch),
open_roles=sum(countries.values()),
countries=sorted(countries.items(), key=lambda kv: -kv[1]))
def _one_source(store: Store, sub_id: int) -> SourceOut:
sub = store.subscription(sub_id)
if sub is None:
raise HTTPException(404, f"no such board or search: {sub_id}")
return _source_out(sub, store.open_countries_by_subscription().get(sub_id, {}))
@router.get("/sources")
def list_sources(store: StoreDep, config: ConfigDep) -> SourcesOut:
"""Every board, and every search not removed. A board switched off stays
listed, so it can be switched back on."""
counts = store.open_countries_by_subscription()
searches = [_source_out(s, counts.get(s.id, {}))
for s in store.subscriptions(source="search") if s.show]
boards = [_source_out(s, counts.get(s.id, {})) for s in store.subscriptions(source="ats")]
return SourcesOut(searches=searches, boards=boards,
adzuna_key=jobs.sources.has_key(config, "adzuna"))
class SwitchBody(BaseModel):
on: bool
@router.post("/sources/{sub_id}/switch")
def switch_source(sub_id: int, body: SwitchBody, store: StoreDep) -> dict[str, Any]:
"""On or off for the next pull. Off closes the open roles at once; on
reopens the ones the next pull still finds."""
if store.subscription(sub_id) is None:
raise HTTPException(404, f"no such board or search: {sub_id}")
_, closed = jobs.sources.set_fetch(store, sub_id, body.on)
return {"source": _one_source(store, sub_id), "closed": closed}
class SearchBody(BaseModel):
provider: str
name: str = ""
q: str = ""
area: int = 0
country: str = ""
where: str = ""
pages: Annotated[int, Field(ge=0, le=10)] = 0
def _params(body: SearchBody) -> dict[str, Any]:
try:
return jobs.sources.search_params(body.provider, body.q, area=body.area,
country=body.country, where=body.where,
pages=body.pages)
except ValueError as exc:
raise HTTPException(422, str(exc)) from exc
@router.post("/searches/try")
def try_search(body: SearchBody, config: ConfigDep) -> dict[str, Any]:
"""Run a search once without saving it: how many it finds, whether that is
every match, and the first ten, so a query can be tuned before it is kept."""
try:
rows, complete = jobs.sources.try_search(config, body.provider, body.name,
_params(body))
except ValueError as exc:
raise HTTPException(422, str(exc)) from exc
sample = [{k: r.get(k) for k in ("title", "company", "place", "url")} for r in rows[:10]]
return {"found": len(rows), "complete": complete, "sample": sample}
@router.post("/searches")
def save_search(body: SearchBody, store: StoreDep, config: ConfigDep) -> dict[str, Any]:
"""Save a search, or update the one of that provider and name. It is run
once first and refused if it finds nothing."""
try:
sub, found, complete = jobs.sources.save_search(config, store, body.provider,
body.name, _params(body))
except ValueError as exc:
raise HTTPException(422, str(exc)) from exc
return {"source": _one_source(store, sub.id), "found": found, "complete": complete}
@router.delete("/searches/{sub_id}")
def remove_search(sub_id: int, store: StoreDep) -> dict[str, Any]:
try:
_, closed = jobs.sources.remove_search(store, sub_id)
except KeyError:
raise HTTPException(404, f"no such search: {sub_id}") from None
return {"closed": closed}
class BoardBody(BaseModel):
board: str
name: str
@router.post("/boards", status_code=201)
def add_board(body: BoardBody, store: StoreDep) -> dict[str, Any]:
"""Follow a company's ATS board. It is fetched first, and refused if it
does not answer or lists nothing."""
try:
sub, found = jobs.sources.add_board(store, body.board, body.name)
except ValueError as exc:
raise HTTPException(422, str(exc)) from exc
return {"source": _one_source(store, sub.id), "found": found}
@router.get("/prune")
def prune_preview(store: StoreDep, region: str = "europe") -> dict[str, Any]:
"""The boards a prune would switch off: every one on, none of whose open
roles is in the region."""
try:
_, plan = jobs.sources.prune_plan(store, region)
except ValueError as exc:
raise HTTPException(422, str(exc)) from exc
return {"region": region, "boards": [{"id": sub.id, "label": sub.label,
"target": sub.target, "open_roles": n}
for sub, n in plan]}
class PruneBody(BaseModel):
region: str = "europe"
@router.post("/prune")
def prune(body: PruneBody, store: StoreDep) -> dict[str, Any]:
try:
return jobs.sources.prune(store, body.region)
except ValueError as exc:
raise HTTPException(422, str(exc)) from exc
# ----------------------------------------------------------- applications
class SaveBody(BaseModel):
role_uid: str
status: Status = "saved"
@router.post("/applications", status_code=201)
def save_role(body: SaveBody, store: StoreDep) -> Application:
"""Track one role: the ★ on a role. Pressing it twice does not
double-track it: the existing row comes back rather than a second one
starting at `saved` over whatever status it has since moved to."""
existing = next((a for a in store.applications() if a.role_uid == body.role_uid), None)
if existing is not None:
return existing
role = store.role(body.role_uid)
if role is None:
raise HTTPException(404, f"no such role: {body.role_uid}")
application = Application(
role_uid=role.uid, company_key=role.company_key, role_title=role.title,
url=role.original_url, status=body.status, source=role.source)
return store.save_application(application)
@router.delete("/applications/{app_id}", status_code=204)
def unsave_role(app_id: str, store: StoreDep) -> Response:
"""The ★ pressed again. Only while the application is still `saved`: once
it has moved on, it is history, and withdrawn is the status for that."""
application = store.application(app_id)
if application is None:
raise HTTPException(404, f"no such application: {app_id}")
if application.status != "saved":
raise HTTPException(409, f"This application is at {application.status} already, "
"so it stays. Set it to withdrawn instead.")
store.delete_application(app_id)
return Response(status_code=204)
@router.get("/applications")
def list_applications(store: StoreDep) -> list[Application]:
"""Every tracked application, with the role title and company key it was
saved with — enough for the page to list them without a join; the
company's full name comes from `/api/companies`, already on the page."""
return store.applications()
class StatusBody(BaseModel):
status: Status
@router.post("/applications/{app_id}/status")
def set_status(app_id: str, body: StatusBody, store: StoreDep) -> Application:
try:
return store.set_application_status(app_id, body.status)
except ValueError as exc:
raise HTTPException(422, str(exc)) from exc
except KeyError:
raise HTTPException(404, f"no such application: {app_id}") from None
# ------------------------------------------------------------------ agents
@router.get("/agents")
def list_agents(store: StoreDep) -> list[Agent]:
return store.agents()
class AgentBody(BaseModel):
"""Create when `id` is missing, replace that agent's fields when given."""
id: int | None = None
name: str = Field(min_length=1)
intent: str = ""
gates: list[Gate] = []
weights: Weights = Weights()
enabled: bool = True
@router.post("/agents")
def save_agent(body: AgentBody, store: StoreDep) -> Agent:
"""Scores are not recomputed here: that is the `score` task, which the
page starts after a save."""
try:
return store.save_agent(body.name, body.intent, body.gates, body.weights,
body.enabled, agent_id=body.id)
except ValueError as exc:
raise HTTPException(409, str(exc)) from exc
except KeyError:
raise HTTPException(404, f"no such agent: {body.id}") from None
@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)