Score roles per search agent, and run pull into extract, embed and score

embed stores one vector per open role; score rates every open role for
every enabled agent from require and prefer gates, fit against the
agent's intent, recency and company affinity, keeping gated rows with a
reason. Schema v3 adds vectors and the cached intent vector. The page
gets an agent order, the score on each row, and an Agents tab. Two
starter agents in roles.yaml are imported once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Opus 5.5 committed 2026-09-23 12:14:21 +02:00
1 parent 4dfb8831aa
commit bc60324fab
22 files changed
+1457 -44

No files matched your search

+9 -3
View File
@@ -1,12 +1,17 @@
"""The work roledesk queues. Importing this package registers every job.
"""The work roledesk queues. Importing this package registers every job and
every task in `pipeline.TASKS`.
pull.py read every configured plugin and store the roles it yields
extract.py title and description into the gate columns, on Haiku
embed.py one vector per open role, for fit
score.py every open role scored for every enabled search agent
cascade.py pull → extract → embed → score, and what `TASKS` offers
"""
from __future__ import annotations
from roledesk.jobs import extract, pull
from roledesk.jobs import cascade, embed, extract, pull, score
from roledesk.jobs.score import seed_agents
#: What `JobQueue(bootstrap=...)` and `pipeline.worker --bootstrap` are given.
BOOTSTRAP = "roledesk.jobs:bootstrap"
@@ -22,4 +27,5 @@ def bootstrap(config_path: str = "") -> tuple[object, object]:
return config, Store(config.database)
__all__ = ["BOOTSTRAP", "bootstrap", "extract", "pull"]
__all__ = ["BOOTSTRAP", "bootstrap", "cascade", "embed", "extract", "pull", "score",
"seed_agents"]
+105
View File
@@ -0,0 +1,105 @@
"""The tasks roledesk offers, and the order a pull runs them in.
pull → extract → embed → score
newsdesk's cascade convention: a cascade is a tuple of task names, and the
final job of one task starts the next (`step` is the callback it carries).
Nothing is alive between two tasks.
Every stage is always in the chain, and a stage that is switched off finds
nothing: `extract.enabled: false`, or an `on_ingest` this pull does not
satisfy, is an extract stage with no batches whose final job moves straight
on. Extract runs before score so the gates read what it filled; before embed
too, since embedding does not read its columns and the order costs nothing.
A batch that failed, or a stage somebody killed, does not stop the chain: the
work comes round on the next pull, and a rescore of what did arrive is worth
having either way.
"""
from __future__ import annotations
from collections.abc import Callable
from dataclasses import replace
from functools import partial
from typing import Any
from desk.tools import agent
from pipeline import TASKS, Tally, Task
from roledesk.jobs import embed, extract, pull, score # noqa: F401 -- registers the jobs
STEP = "roledesk.jobs.cascade:step"
CASCADES: dict[str, tuple[str, ...]] = {
"pull": ("pull", "extract", "embed", "score"),
}
def _once(config: Any, store: Any) -> list[dict[str, Any]]:
"""One batch with nothing in its payload: a task that is a single job."""
return [{}]
def _extract(cascade: str) -> Task:
"""`extract` as a stage, reading `on_ingest` when it is one of a pull.
`never`, or `auto` with no model reachable, is a stage that finds
nothing. Standing on its own, as the button, it reads neither."""
stage = extract.extract_task()
if not cascade:
return stage
find = stage.finder
def during_a_pull(config: Any, store: Any) -> list[Any]:
when = config.extract.on_ingest
if when == "never" or (when == "auto" and not agent.backend(config.agent)):
return []
return find(config, store)
return replace(stage, finder=during_a_pull)
STAGES: dict[str, Callable[[str], Task]] = {
"pull": lambda cascade: pull.pull_task(),
"extract": _extract,
"embed": lambda cascade: Task(kind="embed", finder=_once, label="Embedding roles"),
"score": lambda cascade: Task(kind="score", finder=_once,
label="Scoring roles for every agent"),
}
def task(name: str, *, cascade: str = "") -> Task:
"""One stage as a `Task`. With `cascade` its final job carries `step`,
and the next stage follows; without, it stops when its batches do."""
return replace(STAGES[name](cascade), name=name,
callback=STEP if cascade else "",
carries={"cascade": cascade, "task": name})
def follows(cascade: str, name: str) -> str:
"""What runs after `name`, or "" at the end or for an unknown name."""
tasks = CASCADES.get(cascade, ())
if name not in tasks:
return ""
at = tasks.index(name)
return tasks[at + 1] if at + 1 < len(tasks) else ""
def step(config: Any, store: Any, tally: Tally, payload: dict[str, Any], *,
context: Any) -> dict[str, Any]:
"""The callback: make the next task. A killed stage is skipped and the
chain goes on, as in newsdesk's cascade."""
name, done = payload.get("cascade", ""), payload.get("task", "")
following = follows(name, done)
if following:
context.task(task(following, cascade=name))
out: dict[str, Any] = {"task": done, "next": following}
if tally.killed:
out["skipped"] = "cancelled"
return out
#: What `roledesk job <name>` and the Jobs view offer. `pull` is the whole
#: chain; the others are one stage each, on their own.
TASKS["pull"] = partial(task, "pull", cascade="pull")
for _name in ("extract", "embed", "score"):
TASKS[_name] = partial(task, _name)
+79
View File
@@ -0,0 +1,79 @@
"""`embed`: one vector per open role, for the `fit` term of a score.
The encoder is `desk.tools.embedding`; the table is roledesk's own `vectors`
(see `Store.put_vectors`). What gets encoded is the title and the opening of
the description, which is what says what a role is.
sentence-transformers is optional, as in newsdesk. Without it this task puts
one notice on screen and does nothing; `score` then leaves `fit` out and ranks
on what it has.
"""
from __future__ import annotations
import logging
from typing import Any
from desk.tools import embedding
from pipeline import NULL, Notice, RunContext, job
from roledesk.config import Config
from roledesk.models import Role
from roledesk.storage import Store
log = logging.getLogger(__name__)
#: How much of the description the encoder sees. MiniLM truncates at 256
#: tokens anyway; 2000 characters is past that for any language.
BODY_CHARS = 2000
#: Roles encoded per call, and per commit: a kill loses at most one chunk.
CHUNK = 64
def document(role: Role) -> str:
return f"{role.title}\n{role.description[:BODY_CHARS]}"
def load_embedder(model: str) -> embedding.Embedder:
"""The encoder. A seam of its own so a test hands in a fake and nothing
downloads a model; `score` loads through it too."""
return embedding.load(model)
def unavailable(exc: BaseException) -> Notice:
"""The notice for a machine without sentence-transformers. One code and
key for `embed` and `score`, so the two say it as one line."""
return Notice(
code="embed.unavailable", level="warning", kind="expected", key="embed",
text="sentence-transformers is not installed, so roles are not embedded "
"and scores leave fit out.",
fix="Install it into roledesk's environment: "
"`uv pip install sentence-transformers`.",
detail=str(exc), where="roledesk.jobs.embed")
@job("embed", "Embedding roles", solo=True, resource="cpu")
def run_embed(config: Config, store: Store, *,
context: RunContext = NULL) -> dict[str, Any]:
"""Embed every open role that has no vector from the configured model."""
model = config.embed.model
try:
embedder = load_embedder(model)
except ImportError as exc:
log.warning("%s", exc)
context.notice(unavailable(exc))
return {"embedded": 0, "skipped": True, "reason": "sentence-transformers missing"}
dropped = store.drop_vectors(keep=model)
if dropped:
log.info("dropped %d vectors from a previous embedding model", dropped)
roles = store.roles_to_embed(model, config.embed.per_run)
for at in range(0, len(roles), CHUNK):
context.check()
context.progress(at, len(roles), f"embedding roles, {at} of {len(roles)}")
chunk = roles[at:at + CHUNK]
vectors = embedder.encode([document(r) for r in chunk])
store.put_vectors(model, [(r.uid, v) for r, v in zip(chunk, vectors, strict=True)])
context.progress(len(roles), len(roles),
f"embedding roles, {len(roles)} of {len(roles)}")
return {"embedded": len(roles), "dropped": dropped}
+3 -6
View File
@@ -27,7 +27,7 @@ from typing import Any
from desk import modeltask
from desk.modeltask import ModelTask
from pipeline import NULL, RunContext, TASKS, Task, job
from pipeline import NULL, RunContext, Task, job
from roledesk.config import Config
from roledesk.models import PERMITS, REMOTE, SENIORITIES, ExtractResult, Role
from roledesk.storage import Store
@@ -219,9 +219,6 @@ def run_batch(config: Config, store: Store, *, context: RunContext = NULL,
def extract_task() -> Task:
"""Finds nothing while `extract.enabled` is false, so the task, the
button and the cascade stage are all no-ops with the switch off."""
return replace(modeltask.of(TASK), label=TASK.label)
#: `roledesk job extract` and the Jobs view's Extract. Finds nothing while
#: `extract.enabled` is false, so pressing it with the switch off is a no-op.
TASKS["extract"] = extract_task
+4 -7
View File
@@ -20,7 +20,7 @@ import logging
from datetime import UTC, datetime
from typing import Any
from pipeline import NULL, RunContext, TASKS, Tally, Task, job
from pipeline import NULL, RunContext, Tally, Task, job
from roledesk.config import Config
from roledesk.storage import Store
@@ -103,11 +103,8 @@ def close_boards(config: Config, store: Store, tally: Tally, *,
return {"boards": answered, "failed": failed, "roles": roles, "closed": closed}
def _pull_task() -> Task:
def pull_task() -> Task:
"""The pull on its own. `roledesk.jobs.cascade` makes it the first stage
of the chain that `TASKS["pull"]` starts."""
return Task(kind="pull_batch", finder=_boards, name="pull",
label="Reading every board", settle=SETTLE)
#: Offered as `roledesk job pull` and to `<desk-jobs>`'s Pull button, the same
#: way newsdesk's cascade stages register themselves in `TASKS`.
TASKS["pull"] = _pull_task
+217
View File
@@ -0,0 +1,217 @@
"""`score`: every open role, scored for every enabled search agent.
A role is scored per agent, `(uid, agent) -> score`, because a role is only
good for a given search. For each agent:
require gates a role that fails one keeps its row, with score 0 and the
reason ("place unknown", "remote not remote")
prefer gates `weight` when the role matches, 0 when it does not
fit cos(role vector, intent vector), mapped to 0..1
recency 0.5 ** (days since first_seen / 14)
affinity (companies.affinity + 1) / 3
Every term is 0..1. The score is the weighted sum over the sum of the weights
(the agent's three and its prefer gates'), so it stays 0..1. A favourite
company (`affinity = 2`) skips the gates and is floored at 0.9; a muted one
(`-1`) is not scored at all. A role with no vector is scored without `fit`,
unless `fit` is all there is, when it is gated as "no vector".
Recomputed in full on every run, and each agent's rows are replaced in one
transaction: nothing is incremental, so nothing can drift.
"""
from __future__ import annotations
import hashlib
import logging
import math
from collections.abc import Sequence
from datetime import datetime
from typing import Any
import numpy as np
from pipeline import NULL, RunContext, job
from roledesk.config import Config
from roledesk.jobs import embed
from roledesk.models import Agent, Candidate, Gate, Weights
from roledesk.storage import Store
log = logging.getLogger(__name__)
HALF_LIFE_DAYS = 14.0
#: Where a favourite company's roles start, whatever else they score.
FAVOURITE_FLOOR = 0.9
#: The `state` key that records the starter agents were imported.
SEEDED = "agents:seeded"
# ------------------------------------------------------------------- terms
def recency(first_seen: str, now: datetime) -> float:
"""1.0 for a role first seen now, halving every `HALF_LIFE_DAYS`."""
try:
seen = datetime.fromisoformat(first_seen)
except ValueError:
return 0.0
days = max((now - seen).total_seconds(), 0.0) / 86400
return math.pow(0.5, days / HALF_LIFE_DAYS)
def affinity_term(affinity: int) -> float:
"""-1..2 to 0..1. -1 never gets here; neutral is 1/3."""
return (affinity + 1) / 3
def fit_term(role: np.ndarray, intent: np.ndarray) -> float:
"""Cosine to 0..1. Rescaled rather than clipped, as newsdesk does, so a
role pointing away from the intent sits below an unrelated one."""
norms = float(np.linalg.norm(role) * np.linalg.norm(intent))
if norms == 0:
return 0.5
return (float(np.dot(role, intent)) / norms + 1.0) / 2.0
def _reason(gate: Gate, state: int) -> str:
if state < 0:
return f"{gate.field} unknown"
if gate.field == "salary_min":
return f"salary_min under {min(gate.values, key=lambda v: float(v))}"
return f"{gate.field} not {' / '.join(str(v) for v in gate.values)}"
def score_one(candidate: Candidate, gates: Sequence[Gate], weights: Weights,
fit: float | None, now: datetime, *,
missing: str = "no vector") -> tuple[float, str]:
"""One role for one agent: `(score, gated_reason)`. `fit` is None when
the role or the intent has no vector; `missing` says which."""
favourite = candidate.affinity == 2
if not favourite:
failed = [_reason(g, state) for g, state in zip(gates, candidate.gates, strict=True)
if g.mode == "require" and state != 1]
if failed:
return 0.0, ", ".join(failed)
terms = [(weights.recency, recency(candidate.first_seen, now)),
(weights.affinity, affinity_term(candidate.affinity))]
terms += [(g.weight, 1.0 if state == 1 else 0.0)
for g, state in zip(gates, candidate.gates, strict=True) if g.mode == "prefer"]
if fit is not None:
terms.append((weights.fit, fit))
total = sum(w for w, _ in terms)
if not total:
if favourite:
return FAVOURITE_FLOOR, ""
# Fit was the only term with any weight, and there is no fit.
return 0.0, missing if fit is None and weights.fit else "no weights"
score = sum(w * t for w, t in terms) / total
return (max(score, FAVOURITE_FLOOR) if favourite else score), ""
# ------------------------------------------------------------------ vectors
def intent_key(model: str, intent: str) -> str:
return hashlib.sha1(f"{model}\n{intent}".encode()).hexdigest()
class _Encoder:
"""The embedder, loaded on first use only: an agent whose intent vector
is cached costs no model load at all."""
def __init__(self, model: str, context: RunContext) -> None:
self.model = model
self.context = context
self._embedder: Any = None
self.failed = False
def encode(self, text: str) -> np.ndarray | None:
if self.failed:
return None
if self._embedder is None:
try:
self._embedder = embed.load_embedder(self.model)
except ImportError as exc:
self.failed = True
self.context.notice(embed.unavailable(exc))
return None
return np.asarray(self._embedder.encode([text])[0])
def _intent(store: Store, agent: Agent, model: str,
encoder: _Encoder) -> np.ndarray | None:
if not agent.intent.strip():
return None
key = intent_key(model, agent.intent)
cached = store.intent_vector(agent.id, key)
if cached is not None:
return cached
vec = encoder.encode(agent.intent)
if vec is not None:
store.set_intent_vector(agent.id, key, vec)
return vec
# ------------------------------------------------------------------- the job
def score_agent(store: Store, agent: Agent, vectors: dict[str, np.ndarray],
intent: np.ndarray | None, now: datetime) -> dict[str, int]:
rows: list[tuple[str, float, str]] = []
gated = 0
for candidate in store.score_candidates(agent.gates):
role_vec = vectors.get(candidate.uid)
fit = fit_term(role_vec, intent) if role_vec is not None and intent is not None \
else None
value, reason = score_one(
candidate, agent.gates, agent.weights, fit, now,
missing="no vector" if intent is not None else "no intent vector")
gated += bool(reason)
rows.append((candidate.uid, round(value, 6), reason))
store.replace_scores(agent.id, rows)
return {"scored": len(rows), "gated": gated}
@job("score", "Scoring roles for every agent", solo=True, resource="cpu")
def run_score(config: Config, store: Store, *,
context: RunContext = NULL) -> dict[str, Any]:
seed_agents(config, store)
agents = store.agents(enabled_only=True)
model = config.embed.model
vectors = store.vectors(model) if agents else {}
encoder = _Encoder(model, context)
now = store.clock()
scored = gated = 0
for n, agent in enumerate(agents):
context.check()
context.progress(n, len(agents), f"scoring for {agent.name}, {n + 1} of {len(agents)}")
counts = score_agent(store, agent, vectors, _intent(store, agent, model, encoder), now)
scored += counts["scored"]
gated += counts["gated"]
log.info("%-20s %6d scored, %6d gated", agent.name, counts["scored"], counts["gated"])
context.progress(len(agents), len(agents), "")
return {"agents": len(agents), "scored": scored, "gated": gated,
"vectors": len(vectors)}
# ------------------------------------------------------------------ seeding
def seed_agents(config: Config, store: Store) -> list[str]:
"""Import `roles.yaml`'s `agents:` into an empty table, once. The state
marker is what makes it once: deleting every agent afterwards is a
choice, and a restart must not undo it."""
if store.state.get(SEEDED) or store.agents():
return []
added = []
for seed in config.agents:
try:
store.save_agent(seed.name, seed.intent, seed.gates, seed.weights,
seed.enabled)
except ValueError as exc:
log.warning("agents: %s", exc)
continue
added.append(seed.name)
if added:
store.state[SEEDED] = store.now()
log.info("imported %d agents from %s", len(added), config.path or "roles.yaml")
return added