Files
jobboard/app/web/api.py
T

465 lines
17 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 Role
from desk.tools import agent, scrape
from pipeline import Job
from pipeline.web import QueueDep
from app.models import (
AFFINITY, Agent, Application, Company, Gate, Role, ScoredRole, Status, Subscription,
Weights,
)
from app.storage import Store
from app.web.deps import ConfigDep, StoreDep
router = APIRouter(prefix="/api", tags=["roledesk"])
# ------------------------------------------------------------------- roles
class VoteBody(BaseModel):
value: Literal[-1, 0, 1]
@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)
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. The role stays listed either way; the
vote moves it in a ranking, see `Store.roles`."""
try:
return store.set_vote(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."""
try:
return store.set_vote(uid, None)
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,
agent: int | None = None,
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.
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}")
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}
return RolesPage(items=store.roles(limit=limit, offset=offset, **filters),
total=store.count_roles(**filters))
# ------------------------------------------------- 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 the two things only the store can join in: the ats
host it is read from, and how many of its roles are still open."""
key: str
name: str
board: str
affinity: int
open_roles: int
@router.get("/companies")
def list_companies(store: StoreDep) -> list[CompanyOut]:
boards = store.company_boards()
counts = store.open_role_counts()
return [CompanyOut(key=c.key, name=c.name, board=boards.get(c.key, ""),
affinity=c.affinity, open_roles=counts.get(c.key, 0))
for c in store.companies()]
class AffinityBody(BaseModel):
affinity: int
@router.post("/companies/{key}/affinity")
def set_affinity(key: str, body: AffinityBody, store: StoreDep) -> Company:
if body.affinity not in AFFINITY:
raise HTTPException(422, "affinity is -1, 0, 1 or 2")
try:
return store.update_company(key, affinity=body.affinity)
except KeyError:
raise HTTPException(404, f"no such company: {key}") from None
# ----------------------------------------------------------------- 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:
if not store.delete_agent(agent_id):
raise HTTPException(404, f"no such agent: {agent_id}")
return Response(status_code=204)