"""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, Limits, 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 one with no board), 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, and `ats_slug` its name there, so a followed company with no `board` and an `ats` is one the app cannot read yet; `careers_url` is where a person can. `failing_since` and `failing_reason` say since when the board has failed on every fetch and why it last did, both empty while it answers.""" key: str name: str board: str subscription_id: int | None = None on: bool | None = None affinity: int open_roles: int ats: str = "" ats_slug: str = "" careers_url: str = "" country: str = "" failing_since: str = "" failing_reason: str = "" def _company_boards(store: Store) -> dict[str, tuple[int, str, bool, str]]: """`company_key -> (subscription id, ats host, on, target)`, 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. A detached board (`show` 0) is no board.""" boards: dict[str, tuple[int, str, bool, str]] = {} for sub in store.subscriptions(source="ats"): if not sub.show: continue boards.setdefault(company_key(sub.company), ( sub.id, sub.board, bool(sub.subscribed and sub.fetch), sub.target)) 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() failing = jobs.pull.failing_boards(store) out = [] for c in store.companies(_agent_id(store, agent)): sub_id, host, on, target = boards.get(c.key, (None, "", None, "")) since, reason = failing.get(target, ("", "")) 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, ats_slug=c.ats_slug, careers_url=c.careers_url, country=c.country, failing_since=since, failing_reason=reason)) return out class CompanyBoardBody(BaseModel): board: str @router.post("/companies/{key}/board") def set_company_board(key: str, body: CompanyBoardBody, store: StoreDep) -> dict[str, Any]: """Attach a board to a company, or replace the one it has. The board is fetched first and refused if it does not answer; replacing closes the old board's open roles.""" if store.company(key) is None: raise HTTPException(404, f"no such company: {key}") try: sub, found, closed = jobs.sources.set_board(store, key, body.board) except ValueError as exc: raise HTTPException(422, str(exc)) from exc return {"source": _one_source(store, sub.id), "found": found, "closed": closed} @router.delete("/companies/{key}/board") def detach_company_board(key: str, store: StoreDep) -> dict[str, Any]: """Stop reading a company's board: its open roles close, the row stays.""" try: closed = jobs.sources.detach_board(store, key) except KeyError: raise HTTPException(404, f"no such company: {key}") from None except ValueError as exc: raise HTTPException(409, str(exc)) from exc return {"closed": closed} 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 not detached, 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") if s.show] 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 by its ATS board: `set_board` keyed by the name, so an existing company gets it attached or replaced. The board is fetched first and refused if it does not answer.""" 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() limits: Limits = Limits() 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, limits=body.limits) 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)