"""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": ""}`, 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. `ats` is the host its careers site runs on whether or not the app reads it, so a followed company with no `board` and an `ats` is one the app cannot read yet; `careers_url` is where a person can.""" key: str name: str board: str subscription_id: int | None = None on: bool | None = None affinity: int open_roles: int ats: str = "" careers_url: str = "" country: str = "" 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), ats=c.ats, careers_url=c.careers_url, country=c.country)) 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} # ----------------------------------------------------------- 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)