"""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, Depends, HTTPException, Query, Response from pydantic import BaseModel, Field from app import jobs, places from app.config import Config from app.models import ( AFFINITY, RUNGS, TRACKS, Agent, Application, Company, CvLanguage, CvLanguages, FetchTerms, Gate, Limits, Prompts, Role, RoleRow, SavedFilter, HandReason, ScoredRole, Status, Subscription, Weights, company_key, levels_between, ) from app.storage import Store from app.web.deps import ConfigDep, StoreDep from desk.notices import classify from desk.tools import agent 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 def _feed_filters( 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", "cv"] = "score", gated: bool = False, judged: Literal["", "liked", "unjudged", "passed"] = "", pay: Literal["", "stated", "normalised", "stated_only"] = "", company_keys: list[str] = Query(default=[]), tokens: list[str] = Query(default=[], alias="places"), level_from: str = "", level_to: str = "", track: str = "", seniority_unknown: bool = True, pay_unknown: bool = False, closing: bool = False, ) -> dict[str, Any]: """The feed's filters, as `Store.roles_page`, `count_roles` and `role_facets` take them, read from the query of `GET /api/roles` and `GET /api/roles/facets` alike. A place token that names nothing, a rung outside `RUNGS` and a track outside `TRACKS` are a 422 sentence, not an empty feed. The three seniority parameters become the levels between them (`levels_between`), which is what the store filters on. `order=cv` is the score order with the agent's judged roles first by `cv_score` (`by_cv`). A request that names an agent keeps to its fetch gate in every order, newest included (`fetch_gate`), unless `gated`.""" for token in tokens: if not places.known(token): raise HTTPException(422, f"No place is known as {token!r}.") for name, rung in (("level_from", level_from), ("level_to", level_to)): if rung and rung not in RUNGS: raise HTTPException(422, f"{name} is one of {', '.join(RUNGS)}, not {rung!r}.") if track and track not in TRACKS: raise HTTPException(422, f"track is one of {', '.join(TRACKS)}, not {track!r}.") levels: tuple[str, ...] = () if level_from or level_to or track: # The store reads an empty list as "no filter", so a range that holds no # level must be refused here or it would list every role. levels = levels_between(level_from, level_to, track) if not levels: raise HTTPException(422, "That seniority range holds no level.") return { "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(store, agent), "by_score": agent is not None and order in ("score", "cv"), "by_cv": agent is not None and order == "cv", "gated": gated, "fetch_gate": agent is not None, "judged": judged or None, "pay": pay or None, "company_keys": company_keys, "places": tokens, "seniority": list(levels), "seniority_unknown": seniority_unknown, "pay_unknown": pay_unknown, "closing": closing} FeedFilters = Annotated[dict[str, Any], Depends(_feed_filters)] class FacetCount(BaseModel): """One value of a facet and how many roles hold it; `value` "" is unknown.""" value: str count: int class Facets(BaseModel): seniority: list[FacetCount] pay: list[FacetCount] @router.get("/roles/facets") def role_facets(store: StoreDep, filters: FeedFilters) -> Facets: """How many roles the feed with these parameters holds at each seniority level and each pay state, each facet counted with its own filter left out (`Store.role_facets`). Declared before `/roles/{uid}`, which would otherwise read `facets` as a uid.""" found = store.role_facets(**filters) return Facets(**{name: [FacetCount(value=v, count=n) for v, n in counts] for name, counts in found.items()}) @router.get("/roles/{uid}") def get_role(uid: str, store: StoreDep, agent: int | None = None) -> ScoredRole: """One role, open or closed, for the read page, with `agent`'s vote and score, the prompt that gave its fit, its `judgement` against the agent's CV and the language flag (the default agent's when absent; None when there is no agent). `copies` lists the open copies of a kept role (`RoleCopy`, for "Also posted"); a copy itself opens too, with `dup_of` naming its kept role.""" 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, config: ConfigDep, queue: QueueDep) -> ScoredRole: """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`. A like from an enabled agent also queues the role's summary, see `_queue_summary`.""" owner = _agent_or_default(store, body.agent) try: voted = store.set_vote(owner.id, uid, body.value) except KeyError: raise HTTPException(404, f"no such role: {uid}") from None if body.value == 1 and owner.enabled: _queue_summary(voted, store, config, queue) return voted @router.delete("/roles/{uid}/vote") def unvote_role(uid: str, store: StoreDep, agent: int | None = None) -> ScoredRole: """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` is `RoleRow`, not the full `Role`: the fields a feed row draws, with an excerpt built on the server, never the big columns (`description`, `feed_text`, `raw`, `article_text`) a full role carries — see `Store.roles_page`. The reader fetches the rest by uid when it opens one, `GET /api/roles/{uid}`.""" items: list[RoleRow] total: int @router.get("/roles") def list_roles( store: StoreDep, filters: FeedFilters, 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. Every order keeps to the roles that agent's fetch gate passes, a gated one only with `gated=1`: with `order=score` (the default) best first by final score, carrying `score` and `gated_reason`; with `order=newest` newest first, carrying `gated_reason` and no score; with `order=cv` (CV match) the roles the agent's `judge` read come first by `cv_score`, the rest after them by CV closeness, then score. Without `agent` the default agent's votes and hidden companies apply, the order is newest over every open role 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. `pay` keeps only roles whose `salary_state` is stated or normalised, normalised only, or stated but not normalised (`Store.PAY`); `pay_unknown` lets the roles that state no pay through as well. `closing=1` keeps the roles whose `deadline` is today or in the next four days (Closing soon). Each row carries `deadline`, the agent's `cv_score` (None when not judged), and `lang_flag` and `lang_note`, the posting's languages against the agent's (`app.models.language_flag`). `company` and `place` are substrings, kept for links from other pages. The rail's fields are `company_keys` (repeated, exact keys) and `places` (repeated place tokens, `app.places`: `country:DK`, `region:skane`, `place:malmo`, matched on whole folded words), several values joined by OR, and the seniority range: `level_from` and `level_to` (rungs of `RUNGS`, either or both) and `track` (`ic` or `people`), which keep the levels between the two rungs on that track (`levels_between`). A role with no level passes the seniority filter unless `seniority_unknown` is false. The parameters are read by `_feed_filters`. A copy of another role (`Store.rebuild_dupes`) is never a row; its kept role's `copies` says how many it stands for.""" return RolesPage(items=store.roles_page(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)]) # ------------------------------------------------------------ suggestions class CompanySuggestion(BaseModel): """A company for the rail's Company field: its key, the name shown, its open roles and the agent's affinity.""" key: str name: str count: int affinity: int class PlaceSuggestion(BaseModel): """A place token for the rail's Place field (`places.Suggestion`).""" token: str label: str kind: Literal["country", "region", "place", "remote"] count: int class PlaceLabel(BaseModel): token: str label: str def _starts_a_word(text: str, folded: str) -> bool: """`text` starts a word, or a run of words, of `folded`: `nor` finds `novo nordisk`, `novo nor` too. Both are folded already.""" return f" {text}" in f" {folded}" @router.get("/suggest/companies") def suggest_companies( store: StoreDep, q: str = "", agent: int | None = None, limit: Annotated[int, Query(ge=1, le=50)] = 12, ) -> list[CompanySuggestion]: """Companies with open roles whose name has a word that starts with `q`, folded as places are (`places.fold`), so `orsted` finds Ørsted and `kobenhavn` finds a name with København in it. By open roles, most first. The companies `agent` (the default agent when absent) hid are left out, as the feed leaves them out. An empty `q` suggests nothing.""" text = places.fold(q) if not text: return [] aliases = store.company_aliases() found = [CompanySuggestion(key=key, name=names[0] if names else key, count=count, affinity=affinity) for key, names, count, affinity in store.open_companies(_agent_id(store, agent)) if any(_starts_a_word(text, places.fold(name)) for name in names) or any(_starts_a_word(text, fold) for fold in aliases.get(key, ()))] found.sort(key=lambda c: (-c.count, c.name.casefold())) return found[:limit] @router.get("/suggest/places") def suggest_places( store: StoreDep, q: str = "", agent: int | None = None, limit: Annotated[int, Query(ge=1, le=50)] = 12, ) -> list[PlaceSuggestion]: """Place tokens for the text typed so far: "Remote" (`remote:any`) when `q` starts "remote", countries, the remote tokens ("Remote · Denmark"), regions, then towns, each by open roles (`places.suggest`, over every open role's place line and every open remote role's area). The count of `remote:any` is the remote roles in the scope of `agent`, the default agent when absent, as the feed counts them, and the other remote tokens are kept to that agent's scope, its `require` gates on country. An empty `q` suggests nothing.""" if not places.fold(q): return [] viewer = _agent_id(store, agent) gaz = store.gazetteer() found = store.agent(viewer) if viewer is not None else None scope = {p for g in (found.gates if found is not None else ()) if g.field == "country" and g.mode == "require" for v in g.values for p in gaz.lookup(f"country:{v}") or ()} return [PlaceSuggestion(token=s.token, label=s.label, kind=s.kind, count=s.count) for s in places.suggest( q, store.open_places(), limit, remote=store.open_remote_areas(), gaz=gaz, scope=scope, remote_any=lambda: store.count_roles(places=["remote:any"], agent=viewer, by_score=False))] @router.get("/places/labels") def place_labels(tokens: list[str] = Query(default=[])) -> list[PlaceLabel]: """The chip text of each token read from the address, in the order asked: `country:DK` is Denmark, `region:skane` Skåne. A token that names nothing is left out, so the page drops its chip rather than send it to `/api/roles` for a 422.""" return [PlaceLabel(token=t, label=places.label(t)) for t in tokens if places.known(t)] # ------------------------------------------------- roles: text and summary 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, agent: int | None = None) -> ScoredRole: """Fetch the posting page once and keep it as plain text, for a role whose description is a teaser (`jobs.posting.fetch_posting`); a Jobindex role is read from the page its "Se jobbet" link leads to. The role comes back as `agent` sees it, as `GET /api/roles/{uid}` does: the page merges the answer into the open role, and one without the vote would blank the reader's.""" agent_id = _agent_id(store, agent) try: jobs.posting.fetch_posting(store, uid) except jobs.posting.PostingError as exc: raise HTTPException(exc.status, str(exc)) from exc role = store.role(uid, agent_id) if role is None: raise HTTPException(404, f"no such role: {uid}") return role def _queue_summary(role: Role, store: Store, config: Config, queue: Any) -> None: """Queue the summary of a role the owner just saved or liked, without waiting for the next pull: one batch of this uid, under the key the read page's button uses, so a double tap and the button share one job. Only while the summarise stage is on (`jobs.stages`), for a role with no summary yet and some text, and with a model reachable; otherwise nothing, and the save or vote is not the place to say why.""" if (role.summary or not (role.article_text.strip() or role.description.strip()) or not jobs.stages.stage_on(config, store, "summarise") or not agent.backend(config.agent)): return queue.enqueue(f"{jobs.summarise.TASK.kind}_batch", {"uids": [role.uid]}, label=f"Summarising {role.title or role.uid}", dedup_key=f"summarise:{role.uid}") @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 (`jobs.stages`). 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 # ------------------------------------------------------------------ stages class StageBody(BaseModel): on: bool @router.get("/stages") def list_stages(store: StoreDep, config: ConfigDep) -> list[jobs.stages.Stage]: """The stages of a pull with a switch, extract, summarise, judge and fetch_text: whether each is on, whether the stored switch or config.yaml says so, its model, and who would answer.""" return jobs.stages.describe(config, store) @router.put("/stages/{name}") def set_stage(name: str, body: StageBody, store: StoreDep, config: ConfigDep) -> jobs.stages.Stage: """Store the switch for one stage. Nothing starts: the next pull runs the stage, or Run the pull now does so at once.""" try: jobs.stages.set_stage(store, name, body.on) except KeyError: raise HTTPException(404, f"no such stage: {name}") from None return jobs.stages.describe_one(config, store, name) # --------------------------------------------------------------- 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. `from_search` marks a row that exists only because a search listed its roles and somebody judged it (`Store.set_affinity`): no board, not even a detached one, and no `ats`, `careers_url`, `domain` or `hand_reason`, which every way of following a company or listing it by hand writes one of (`jobs.sources.known_from_search_only`). `watch` and `careers_opened_at` are the Watchlist's (`Company`'s), the latter also when a person last looked at the careers page. `by_hand` marks a company with no board shown that is not `from_search`, and `hand_reason` says why it is read by hand (`app.models.HAND_REASONS`). `all_countries` and `all_roles` are the company's two fetch overrides: its big boards read with the agents' wide reach, and with no role-type narrowing. `target` is the attached board in full, `host:slug`, where `board` is its host alone; the page compares it with the board typed to know whether a replacement closes anything. `ats_slug` cannot stand in for it, since the careers site may run on another host than the board.""" key: str name: str notes: str = "" board: str target: 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 = "" city: str = "" domain: str = "" watch: int | None = None careers_opened_at: str = "" failing_since: str = "" failing_reason: str = "" from_search: bool = False hand_reason: str = "" by_hand: bool = False all_countries: bool = False all_roles: bool = False #: The board's own reach in its params (`jobs.reach.OVERRIDE_KEYS`), and #: what a pull asks its board for (`jobs.reach.line`). reach_params: dict[str, Any] = {} reach: str = "" #: The roles the board listed when it was last sized, and that day #: (ISO); None and "" before it is sized (`jobs.reach.SIZE`). size: int | None = None size_checked: str = "" #: What limits the board's read, in words (`jobs.limits.WORDS`), and the #: board's own open roles, which `open_roles` also counts the searches' #: roles beside; None with no board. limits: list[str] = [] board_open: int | None = None 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 def _company_outs(store: Store, agent: int | None) -> list[CompanyOut]: from plugins import readers boards = _company_boards(store) ever_boarded = {company_key(s.company) for s in store.subscriptions(source="ats")} counts = store.open_role_counts() failing = jobs.pull.failing_boards(store) subs = {s.id: s for s in store.subscriptions(source="ats")} plan = jobs.reach.plan(store, subs.values()) state = jobs.limits.state_of(store) per_board = jobs.limits.texts(store) out = [] for c in store.companies(agent): sub_id, host, on, target = boards.get(c.key, (None, "", None, "")) since, reason = failing.get(target, ("", "")) sub = subs.get(sub_id) if sub_id is not None else None from_search = jobs.sources.known_from_search_only(c, ever_boarded) module = readers.HOSTS.get(target.partition(":")[0]) if sub else None reach_line = jobs.reach.line(plan, sub) if sub else "" board = per_board.get(sub_id, jobs.limits.Texts(0, 0)) if sub else None found = jobs.limits.words(module, state, target, sub, plan.sizes.get(target), plan=plan, line=reach_line, counts=board) if module and sub else [] out.append(CompanyOut(key=c.key, name=c.name, notes=c.notes, board=host, target=target, 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, city=c.city, domain=c.domain, watch=c.watch, careers_opened_at=c.careers_opened_at, failing_since=since, failing_reason=reason, from_search=from_search, hand_reason=c.hand_reason, by_hand=c.key not in boards and not from_search, all_countries=bool(c.all_countries), all_roles=bool(c.all_roles), reach_params={k: v for k, v in (sub.params if sub else {}).items() if k in jobs.reach.OVERRIDE_KEYS}, reach=reach_line, size=plan.sizes.get(target) if sub else None, size_checked=store.state.get( jobs.reach.SIZE_CHECKED + target, "") if sub else "", limits=found, board_open=board.open if board else None)) return out def _one_company(store: Store, key: str) -> CompanyOut: """`key` as the list shows it, with the default agent's affinity.""" return next(c for c in _company_outs(store, _agent_id(store, None)) if c.key == key) @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.""" return _company_outs(store, _agent_id(store, agent)) class NewCompanyBody(BaseModel): name: str careers_url: str = "" notes: str = "" hand_reason: HandReason = "added" @router.post("/companies", status_code=201) def add_company(body: NewCompanyBody, store: StoreDep) -> CompanyOut: """A company put on the list checked by hand: no board, `hand_reason` `added` unless it says another. 409 when its key, from the name, is taken.""" try: company = jobs.sources.add_by_hand(store, body.name, careers_url=body.careers_url, notes=body.notes, hand_reason=body.hand_reason) except jobs.sources.Conflict as exc: raise HTTPException(409, str(exc)) from exc except ValueError as exc: raise HTTPException(422, str(exc)) from exc return _one_company(store, company.key) class CompanyPatch(BaseModel): name: str | None = None careers_url: str | None = None notes: str | None = None hand_reason: HandReason | None = None @router.patch("/companies/{key}") def edit_company(key: str, body: CompanyPatch, store: StoreDep) -> CompanyOut: """Change any of a company's name, careers link, notes and reason; a field left out stays. The key never changes, and `name` only for a company without a board: 409 for one with a subscription, shown or not (see `jobs.sources.edit_company`).""" fields = body.model_dump(exclude_unset=True) if any(v is None for v in fields.values()): raise HTTPException(422, "A field is left out, not null.") try: jobs.sources.edit_company(store, key, **fields) except KeyError: raise HTTPException(404, f"no such company: {key}") from None except jobs.sources.Conflict as exc: raise HTTPException(409, str(exc)) from exc except ValueError as exc: raise HTTPException(422, str(exc)) from exc return _one_company(store, key) @router.delete("/companies/{key}", status_code=204) def remove_company(key: str, store: StoreDep) -> Response: """Delete a company and every agent's stance on it. 409 for one with a board shown or with open roles; detach the board first.""" try: jobs.sources.remove_company(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 Response(status_code=204) class CompanyBoardBody(BaseModel): board: str @router.post("/companies/{key}/board") def set_company_board(key: str, body: CompanyBoardBody, store: StoreDep, queue: QueueDep) -> 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. Queues a pull right after, so the board is read by the one already running or the very next one rather than the schedule, up to six hours later; a refusal because one is already running is not an error, see `app.jobs.pull.claim_run`.""" 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 queue.enqueue("pull") 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} def _score_after_change(queue: Any) -> Job | None: """The `score` job whose result will include a change just written. A `score` that is queued and has not started will read the change, so it is the answer: the plain one, keyed `score`, or a follow-up. Else a plain request, which the queue dedupes to a live job keyed `score` because the kind is `solo`. When that job is already running it read the old state, so it gets one follow-up that waits for it (`depends_on`, `after="done"`), deduped on `score:after:`: ten requests during one run are one extra pass. A pull's `score` stage is a plain `score` job too, queued when its stage starts, so a request during a pull joins it.""" queued = queue.jobs.last("score", states=("queued",)) if queued is not None and (queued.dedup_key == "score" or queued.dedup_key.startswith("score:after:")): return queued job: Job | None = queue.enqueue("score") if job is not None and job.state == "running": job = queue.enqueue("score", depends_on=[job.id], after="done", dedup_key=f"score:after:{job.id}") return job @router.post("/score") def request_score(queue: QueueDep) -> Job: """Score every agent's roles after a change: now, or right after the `score` that is already running (see `_score_after_change`). Returns the job to wait for; the Search agents page waits on it after a save.""" job = _score_after_change(queue) if job is None: raise HTTPException(409, "Scoring would not start.") return job class AffinityBody(BaseModel): affinity: int #: Whose affinity; the default agent when absent. agent: int | None = None class AffinityOut(Company): #: The `score` job whose result will include this change; None when none #: could be queued. score_job: int | None = None @router.post("/companies/{key}/affinity") def set_affinity(key: str, body: AffinityBody, store: StoreDep, queue: QueueDep) -> AffinityOut: """-1 hidden, 0 neutral, 1 liked, 2 favourite, for `body.agent` or the default agent. A key with roles and no company row gets one first (see `Store.set_affinity`); 404 for a key with neither. A change here is not seen in Agent match until `score` has run, so it queues one (`_score_after_change`) and answers with its id.""" 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 job = _score_after_change(queue) jobs.cascade.fetch_text_after(queue, job) return AffinityOut(**company.model_dump(), score_job=job.id if job else None) class WatchBody(BaseModel): #: True on the Watchlist's list, False not on it, None clears the rating. watch: bool | None @router.post("/companies/{key}/watch") def set_watch(key: str, body: WatchBody, store: StoreDep) -> Company: """Rate a company for the Watchlist: 1 worth checking by hand, 0 not, null back to unrated. Global, and apart from affinity. 404 for an unknown key.""" watch = None if body.watch is None else int(body.watch) try: return store.update_company(key, watch=watch) except KeyError: raise HTTPException(404, f"no such company: {key}") from None class OverrideBody(BaseModel): on: bool def _override(store: Store, queue: Any, key: str, on: bool, setter: str) -> Company: """Switch one of a company's two overrides of the fetch gate. Either way the agents' fetch gates change for the roles already stored, so a rescore is queued (`_score_after_change`) with the fetch text cascade behind it. On also queues a pull, as the other reopening switches do; off queues no pull, since no role closes until the next pull reads the board with its filters again. 404 for an unknown key.""" try: company = getattr(store, setter)(key, on) except KeyError: raise HTTPException(404, f"no such company: {key}") from None jobs.cascade.fetch_text_after(queue, _score_after_change(queue)) if on: queue.enqueue("pull") return company @router.post("/companies/{key}/all-countries") def set_all_countries(key: str, body: OverrideBody, store: StoreDep, queue: QueueDep) -> Company: """All countries on or off: global, apart from affinity. On, the company's roles skip the place part of every agent's fetch gate (the `any` gates, `jobs.score.failed_gates`), and its big boards are read with the agents' wide reach, Europe today, rather than their places (`app/jobs/reach.py`). See `_override`.""" return _override(store, queue, key, body.on, "set_all_countries") @router.post("/companies/{key}/all-roles") def set_all_roles(key: str, body: OverrideBody, store: StoreDep, queue: QueueDep) -> Company: """All roles on or off: global, apart from affinity. On, the company's roles skip the role part of every agent's fetch gate, the titles to leave out (`jobs.score.failed_gates`), and its boards are read with no fetch terms (`app/jobs/reach.py`). See `_override`.""" return _override(store, queue, key, body.on, "set_all_roles") class CareersBody(BaseModel): careers_url: str @router.post("/companies/{key}/careers") def set_careers_url(key: str, body: CareersBody, store: StoreDep) -> Company: """Set or correct where a company's careers page is; "" clears it. 422 for anything but an http(s) URL (`jobs.sources.check_careers_url`, the rule the by-hand edit shares), 404 for an unknown key.""" try: url = jobs.sources.check_careers_url(body.careers_url) except ValueError as exc: raise HTTPException(422, str(exc)) from exc try: return store.update_company(key, careers_url=url) except KeyError: raise HTTPException(404, f"no such company: {key}") from None @router.post("/companies/{key}/opened") def mark_careers_opened(key: str, store: StoreDep) -> Company: """Stamp that the company's careers page was just opened from the Watchlist. 404 for an unknown key.""" try: return store.update_company(key, careers_opened_at=store.now()) 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. `failing_since` and `failing_reason` say since when it has failed on every fetch and why it last did (`jobs.pull.failing_boards`), both empty while it answers.""" id: int source: str target: str label: str provider: str params: dict[str, Any] on: bool open_roles: int countries: list[tuple[str, int]] failing_since: str = "" failing_reason: str = "" 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], failing: dict[str, tuple[str, str]]) -> SourceOut: since, reason = failing.get(sub.target, ("", "")) 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]), failing_since=since, failing_reason=reason) 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, {}), jobs.pull.failing_boards(store)) @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() failing = jobs.pull.failing_boards(store) searches = [_source_out(s, counts.get(s.id, {}), failing) for s in store.subscriptions(source="search") if s.show] boards = [_source_out(s, counts.get(s.id, {}), failing) 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, queue: QueueDep) -> dict[str, Any]: """On or off. Off closes the open roles at once; on queues a pull right after, so the ones it still lists reopen once the pull that is already running reads it, or the very next one does, rather than waiting for the schedule, up to six hours later. A refusal because one is already running is not an error, see `app.jobs.pull.claim_run`.""" 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) if body.on: queue.enqueue("pull") return {"source": _one_source(store, sub_id), "closed": closed} class ReachBody(BaseModel): #: `agents`: the enabled agents' reach; `own`: the `countries` (ISO #: codes) and remote given here. The wide reach and no role narrowing #: are the company's overrides (`/api/companies/{key}/all-countries`, #: `/all-roles`), not a board's reach. mode: Literal["agents", "own"] countries: list[str] = [] remote: bool = False @router.post("/sources/{sub_id}/reach") def set_reach(sub_id: int, body: ReachBody, store: StoreDep) -> dict[str, Any]: """A board's own reach, which wins over the agents' (see `app/jobs/reach.py`), or none. The next pull reads the board so; a narrower reach closes the roles outside it then, except those with a vote or an application. A reach set here wins over the company's All countries override.""" sub = store.subscription(sub_id) if sub is None or sub.source != "ats": raise HTTPException(404, f"no such board: {sub_id}") named = sorted({c.strip() for c in body.countries if c.strip()}) tokens = {c: places.parse(f"country:{c}") for c in named} if unknown := [c for c, t in tokens.items() if not places.known(str(t)) or t.value == "EU"]: raise HTTPException(422, f"Not a country: {', '.join(unknown)}.") # The ISO code is what the reach compares against, not the name or alias typed. codes = sorted({t.value for t in tokens.values()}) if body.mode == "own" and not (codes or body.remote): raise HTTPException(422, "Name a country or remote, or take the agents' reach.") params = {k: v for k, v in sub.params.items() if k not in jobs.reach.OVERRIDE_KEYS} if body.mode == "own": params |= {"countries": codes, "remote": body.remote} sub = store.update_subscription(sub_id, params=params) return {"source": _one_source(store, sub_id), "reach": jobs.reach.line(jobs.reach.plan(store, [sub]), sub)} @router.post("/sources/{sub_id}/size") def recheck_size(sub_id: int, store: StoreDep, queue: QueueDep) -> dict[str, Any]: """Size a board again, the one way its size changes once it was added (`jobs.sources.size_board`): its reach may change with it, so a pull is queued right after, as the other routes that change what is read do. 422 when the board does not answer; the size it had stays.""" sub = store.subscription(sub_id) if sub is None or sub.source != "ats": raise HTTPException(404, f"no such board: {sub_id}") try: size = jobs.sources.size_board(store, sub.target) except ValueError as exc: raise HTTPException(422, str(exc)) from exc queue.enqueue("pull") checked = store.state.get(jobs.reach.SIZE_CHECKED + sub.target, "") return {"size": size, "size_checked": checked, "reach": jobs.reach.line(jobs.reach.plan(store, [sub]), sub)} class ReaderOut(BaseModel): """What a reader declares (`plugins/readers/_contract.py`), for the Sources page: `filters` holds only the dimensions it filters.""" name: str label: str scope: str listing: str text: str filters: dict[str, str] places: str robots: str #: `Reads.complete`, `page_size`, `ceiling`, `teaser`, `empty`, and #: `fields` as a dict: the traits `jobs.limits` turns into words. complete: str page_size: int | None = None ceiling: int | None = None teaser: bool = False empty: str = "trusted" fields: dict[str, str] = {} @router.get("/readers") def list_readers() -> list[ReaderOut]: """Every reader that declares `READS`, boards first, by label.""" from plugins import readers found = [m for m in readers.READERS.values() if isinstance(getattr(m, "READS", None), readers.Reads)] return [ReaderOut(name=m.NAME, label=m.LABEL, scope=m.READS.scope, listing=m.READS.listing, text=m.READS.text, filters=m.READS.filters.declared(), places=m.READS.places, robots=m.READS.robots, complete=m.READS.complete, page_size=m.READS.page_size, ceiling=m.READS.ceiling, teaser=m.READS.teaser, empty=m.READS.empty, fields=m.READS.fields.model_dump()) for m in sorted(found, key=lambda m: (m.READS.scope != "board", m.LABEL.lower()))] class UnmappedOut(BaseModel): """A host word no table of `app/prep/hosts` maps (`Store.unmapped`).""" field: str host: str word: str roles: int first_seen: str @router.get("/prep/unmapped") def list_unmapped(store: StoreDep) -> list[UnmappedOut]: """The host words the last prep could not map, per field and host, most roles first: what a table in `app/prep/hosts` should learn.""" return [UnmappedOut(**w) for w in store.unmapped()] class UnlinkedOut(BaseModel): """A place text the gazetteer does not know (`Store.unlinked_places`).""" fold: str text: str roles: int countries: list[tuple[str, int]] companies: list[str] @router.get("/prep/unlinked") def list_unlinked(store: StoreDep) -> list[UnlinkedOut]: """The place texts of open roles no place resolves, most roles first: what a city, a spelling or a no-place word in `app/models.py` and `app/places.py` should learn.""" return [UnlinkedOut(**p) for p in store.unlinked_places()] class SearchBody(BaseModel): provider: str name: str = "" q: str = "" area: int = 0 country: str = "" where: str = "" region: str = "" remote: 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, region=body.region, remote=body.remote, 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, queue: QueueDep) -> 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. Queues a pull right after, so its roles are read by the one already running or the very next one rather than the schedule, up to six hours later; a refusal because one is already running is not an error, see `app.jobs.pull.claim_run`.""" 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 queue.enqueue("pull") 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, queue: QueueDep) -> 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. Queues a pull right after, so its roles are read by the one already running or the very next one rather than the schedule, up to six hours later; a refusal because one is already running is not an error, see `app.jobs.pull.claim_run`.""" try: sub, found = jobs.sources.add_board(store, body.board, body.name) except ValueError as exc: raise HTTPException(422, str(exc)) from exc queue.enqueue("pull") 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, config: ConfigDep, queue: QueueDep) -> 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. A saved role is also queued for its summary, see `_queue_summary`.""" 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) saved = store.save_application(application) _queue_summary(role, store, config, queue) return saved @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. `intent` is the body from before an agent had prompts: without `prompts` it is stored as one prompt named after the agent. `fetch_terms` narrow what big boards send (`app/jobs/reach.py`); `[]` narrows nothing, and leaving the key out keeps an existing agent's. `cv_text`, `cv_languages`, `like_text`, `avoid_text` and `must_text` are what `judge` reads a role against (`app/jobs/judge.py`), kept the same way when left out or null.""" id: int | None = None name: str = Field(min_length=1) prompts: Prompts | None = None intent: str = "" gates: list[Gate] = [] weights: Weights = Weights() limits: Limits = Limits() fetch_terms: FetchTerms | None = None cv_text: str | None = None cv_languages: CvLanguages | None = None like_text: str | None = None avoid_text: str | None = None must_text: str | None = None enabled: bool = True class CvText(BaseModel): cv_text: str = Field(min_length=1) class CvLanguagesOut(BaseModel): languages: list[CvLanguage] @router.post("/agents/cv-languages") def cv_languages(body: CvText, config: ConfigDep) -> CvLanguagesOut: """The languages a CV states, each with a level, from one model call (`jobs.judge.suggest_languages`), for the owner to edit before saving. Nothing is stored. 503 when no model is reachable, 502 when the call gives no answer.""" if not body.cv_text.strip(): raise HTTPException(422, "Paste a CV first.") if not agent.backend(config.agent): raise HTTPException(503, "No model is reachable from here, so nothing can read the " "languages. Set up the API key or Claude Code.") try: found = jobs.judge.suggest_languages(config, body.cv_text) except agent.AgentError as exc: raise HTTPException(502, classify(exc, backend=agent.backend(config.agent)).text) \ from exc return CvLanguagesOut(languages=found) @router.post("/agents") def save_agent(body: AgentBody, store: StoreDep, queue: QueueDep) -> Agent: """Queues the rescore, which the page's `POST /api/score` after a save joins, and the fetch text cascade behind it (`cascade.fetch_text_after`).""" try: saved = store.save_agent(body.name, body.intent, body.gates, body.weights, body.enabled, agent_id=body.id, limits=body.limits, prompts=body.prompts, fetch_terms=body.fetch_terms, cv_text=body.cv_text, cv_languages=body.cv_languages, like_text=body.like_text, avoid_text=body.avoid_text, must_text=body.must_text) except ValueError as exc: raise HTTPException(409, str(exc)) from exc except KeyError: raise HTTPException(404, f"no such agent: {body.id}") from None jobs.cascade.fetch_text_after(queue, _score_after_change(queue)) return saved @router.delete("/agents/{agent_id}", status_code=204) def delete_agent(agent_id: int, store: StoreDep) -> Response: """Its prompts, scores, votes, affinities and saved filters go with it.""" if not store.delete_agent(agent_id): raise HTTPException(404, f"no such agent: {agent_id}") return Response(status_code=204) # ---------------------------------------------------------- saved filters class FilterBody(BaseModel): #: Checked by `Store.save_filter`, so a blank name is a 422 sentence. name: str #: The feed's query string as `roles.js` `addressFor` writes it, without #: the agent. query: str = "" @router.get("/agents/{agent_id}/filters") def list_saved_filters(agent_id: int, store: StoreDep) -> list[SavedFilter]: """The agent's saved filters, by name. 404 for an unknown agent.""" if store.agent(agent_id) is None: raise HTTPException(404, f"no such agent: {agent_id}") return store.saved_filters(agent_id) @router.post("/agents/{agent_id}/filters", status_code=201) def save_filter(agent_id: int, body: FilterBody, store: StoreDep) -> SavedFilter: """Save the feed's filters under a name for the agent. 404 for an unknown agent, 422 for an empty name, 409 for a name the agent already has regardless of case. There is no editing: a change is a new one.""" if store.agent(agent_id) is None: raise HTTPException(404, f"no such agent: {agent_id}") if not body.name.strip(): raise HTTPException(422, "Give the filter a name.") try: return store.save_filter(agent_id, body.name, body.query) except KeyError: raise HTTPException(404, f"no such agent: {agent_id}") from None except ValueError as exc: raise HTTPException(409, f"A filter named {body.name.strip()!r} is already saved.") \ from exc @router.delete("/filters/{filter_id}", status_code=204) def delete_saved_filter(filter_id: int, store: StoreDep) -> Response: if not store.delete_filter(filter_id): raise HTTPException(404, f"no such saved filter: {filter_id}") return Response(status_code=204)