Files
jobboard/app/web/api.py
T
WolfandClaude Opus 5.5 77b45a4b0f Read role pages in an enrich stage after scoring, best roles first
The pull reads listings only. `enrich` (app/jobs/enrich.py) takes the open
roles without text that an enabled agent ranks ungated in its best
`enrich.top` at `enrich.min_score` or above, best score first, on boards
whose reader has `detail`, within `enrich.per_board` and `enrich.per_run`,
one batch per board. `plugins.ats.read_board_details` reads them and keeps
the per-board state; a read that gave no text is read again after
`enrich.retry_days` (finding 18). Filled roles are upserted, which drops
their vectors, and embed and score follow; `cascade.step` passes over both
when nothing was filled.

The pull cascade is pull, embed, score, enrich, embed, score, extract, score,
summarise. Saving an agent and changing a company's affinity queue the
`enrich` job (enrich, embed, score) behind their rescore; a vote does not.
The stage has a switch, `stage:enrich`, over `enrich.enabled`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 09:53:29 +02:00

988 lines
40 KiB
Python

"""The JSON routes the tabs use: roles, companies, sources, applications,
agents.
`/api/jobs*`, `/api/schedules*`, `/api/notices` and `/ws/jobs` are
`pipeline.web`'s and `/api/account*` is `auth`'s, both wired in `app/main.py`.
This is roledesk's own API, over the same store. Every refusal is
`{"detail": "<sentence>"}`, which `api()` in `static/app.js` turns into a toast.
"""
from __future__ import annotations
from typing import Annotated, Any, Literal
from fastapi import APIRouter, Depends, HTTPException, Query, Response
from pydantic import BaseModel, Field
from app import jobs, places
from app.models import (
AFFINITY, LEVELS, Agent, Application, Company, Gate, Limits, Prompts, Role, RoleRow,
HandReason, 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
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"] = "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"),
seniority: list[str] = Query(default=[]),
seniority_unknown: bool = True,
pay_unknown: 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 and a
level outside `LEVELS` are a 422 sentence, not an empty feed."""
for token in tokens:
if not places.known(token):
raise HTTPException(422, f"No place is known as {token!r}.")
for level in seniority:
if level not in LEVELS:
raise HTTPException(422, f"Seniority is one of {', '.join(LEVELS)}, not {level!r}.")
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 == "score", "gated": gated,
"judged": judged or None, "pay": pay or None, "company_keys": company_keys,
"places": tokens, "seniority": seniority, "seniority_unknown": seniority_unknown,
"pay_unknown": pay_unknown}
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, and the prompt that gave its fit (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) -> 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`."""
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) -> 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. 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. `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.
`company` and `place` are substrings, kept for links from other pages.
The rail's fields are `company_keys` (repeated, exact keys),
`places` (repeated place tokens, `app.places`: `country:DK`,
`region:skane`, `place:malmo`, matched on whole folded words) and
`seniority` (repeated levels), each several values joined by OR. 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"]
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 []
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)]
found.sort(key=lambda c: (-c.count, c.name.casefold()))
return found[:limit]
@router.get("/suggest/places")
def suggest_places(
store: StoreDep,
q: str = "",
limit: Annotated[int, Query(ge=1, le=50)] = 12,
) -> list[PlaceSuggestion]:
"""Place tokens for the text typed so far: countries, then regions, then
towns, each by open roles (`places.suggest`, over every open role's place
line). An empty `q` suggests nothing."""
return [PlaceSuggestion(token=s.token, label=s.label, kind=s.kind, count=s.count)
for s in places.suggest(q, store.open_places(), limit)]
@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
#: 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 (`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 two model stages of a pull: 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`)."""
key: str
name: str
notes: 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 = ""
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
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]:
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)
out = []
for c in store.companies(agent):
sub_id, host, on, target = boards.get(c.key, (None, "", None, ""))
since, reason = failing.get(target, ("", ""))
from_search = jobs.sources.known_from_search_only(c, ever_boarded)
out.append(CompanyOut(key=c.key, name=c.name, notes=c.notes, 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, 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))
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:<id>`: 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 Best 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.enrich_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 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."""
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,
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 SearchBody(BaseModel):
provider: str
name: str = ""
q: str = ""
area: int = 0
country: str = ""
where: str = ""
region: 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, 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) -> 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.
`intent` is the body from before an agent had prompts: without `prompts`
it is stored as one prompt named after the agent."""
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()
enabled: bool = True
@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 enrich run behind it (`cascade.enrich_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)
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.enrich_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 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)