A require gate on an empty column gated the role ("country unknown"), and extract, the stage that fills the column, is bounded to the roles that rank, so 2,281 of 15,556 open roles could never come back: every board that writes "Remote", "Hybrid" or "Distributed" as its location. An empty column now neither passes nor fails a gate; the role ranks, extract reads it, the rescore decides.
`any` is a third gate mode: the any gates are one group a role must match one of, so a ranking can say "in Denmark, or remote", which require alone could not. The group is gated only when some member had evidence against it.
`remote_of(place)` fills `remote` from the location line the way `country_of` fills `country`, and the startup backfill does both, since Greenhouse writes "Hybrid" as the location and gives no flag.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
307 lines
13 KiB
Python
307 lines
13 KiB
Python
"""`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 ("remote not remote")
|
|
any gates one group: a role that matches none of them, and has the
|
|
column filled for at least one, is gated ("none of
|
|
country DK / remote remote")
|
|
prefer gates `weight` when the role matches, 0 when it does not
|
|
|
|
A gate rejects on evidence, never on absence: a role whose column is empty
|
|
is not gated by it. `extract` is what fills an empty column, and it reads
|
|
only the roles that rank, so gating on an empty column would keep those
|
|
roles out of extract's reach for good.
|
|
fit cos(role vector, intent vector), min-max scaled across
|
|
the roles this agent scores in this run: the closest is 1,
|
|
the farthest 0, a lone role 1
|
|
recency 0.5 ** (days since first_seen / 14)
|
|
affinity (the agent's affinity for the company + 1) / 3
|
|
taste cos(role vector, liked direction), min-max scaled like fit,
|
|
where the direction is mean(liked vectors) - mean(passed vectors)
|
|
over this agent's votes; with only likes it is the liked mean,
|
|
with only passes the negated passed mean; no votes, no term
|
|
|
|
Every term is 0..1. The score is the weighted sum over the sum of the weights
|
|
(the agent's four and its prefer gates'), so it stays 0..1. A favourite
|
|
company (`affinity = 2`) skips the gates and is floored at 0.9; a hidden one
|
|
(`-1`) is not scored at all. A role with no vector is scored without `fit`
|
|
and `taste`, unless `fit` is all there is, when it is gated as "no vector".
|
|
An agent with no votes scores every role without `taste`; the direction is
|
|
newsdesk's `centroid(liked) - centroid(disliked)`.
|
|
|
|
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 app.config import Config
|
|
from app.jobs import embed
|
|
from app.models import Agent, Candidate, Gate, Weights
|
|
from app.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 cosine(role: np.ndarray, intent: np.ndarray) -> float:
|
|
"""Raw cosine, -1..1; 0 when either vector is zero."""
|
|
norms = float(np.linalg.norm(role) * np.linalg.norm(intent))
|
|
if norms == 0:
|
|
return 0.0
|
|
return float(np.dot(role, intent)) / norms
|
|
|
|
|
|
def taste_direction(vectors: dict[str, np.ndarray],
|
|
votes: dict[str, int]) -> np.ndarray | None:
|
|
"""`mean(liked) - mean(passed)` over the voted roles that have a vector.
|
|
A side with no votes is zero, so likes alone point at the liked mean and
|
|
passes alone away from the passed mean. None when neither side has a
|
|
vector: no votes, no direction. A neutral vote says nothing."""
|
|
liked = [vectors[uid] for uid, vote in votes.items() if vote == 1 and uid in vectors]
|
|
passed = [vectors[uid] for uid, vote in votes.items() if vote == -1 and uid in vectors]
|
|
if not liked and not passed:
|
|
return None
|
|
direction = np.zeros_like(liked[0] if liked else passed[0], dtype=np.float64)
|
|
if liked:
|
|
direction += np.mean(liked, axis=0)
|
|
if passed:
|
|
direction -= np.mean(passed, axis=0)
|
|
return direction
|
|
|
|
|
|
def scale(cosines: dict[str, float]) -> dict[str, float]:
|
|
"""Min-max to 0..1 across one agent's run, so `fit` ranks roles rather
|
|
than stating a level.
|
|
|
|
`(cos + 1) / 2` was the level, and on MiniLM it spans about 0.55 to 0.79
|
|
for real postings against a real intent, so a prefer gate weighted 0.2
|
|
moved a score more than the whole spread of fit did. Scaled, the closest
|
|
role is 1 and the farthest 0. A single role, or roles that are all equally
|
|
close, get 1: there is nothing to tell them apart by.
|
|
"""
|
|
if not cosines:
|
|
return {}
|
|
low, high = min(cosines.values()), max(cosines.values())
|
|
if high - low < 1e-9:
|
|
return dict.fromkeys(cosines, 1.0)
|
|
return {uid: (value - low) / (high - low) for uid, value in cosines.items()}
|
|
|
|
|
|
def _wanted(gate: Gate) -> str:
|
|
if gate.field == "salary_min":
|
|
return f"salary_min {min(gate.values, key=lambda v: float(v))}"
|
|
return f"{gate.field} {' / '.join(str(v) for v in gate.values)}"
|
|
|
|
|
|
def _reason(gate: Gate) -> str:
|
|
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 failed_gates(candidate: Candidate, gates: Sequence[Gate]) -> list[str]:
|
|
"""Why this role is gated, as reasons: every require gate it fails, and
|
|
the `any` group when it matches none of them. A gate with an empty column
|
|
(state -1) neither passes nor fails, so the group fails only when some
|
|
member had evidence. None for a favourite, which skips the gates."""
|
|
if candidate.affinity == 2:
|
|
return []
|
|
states = list(zip(gates, candidate.gates, strict=True))
|
|
reasons = [_reason(g) for g, state in states if g.mode == "require" and state == 0]
|
|
group = [(g, state) for g, state in states if g.mode == "any"]
|
|
if group and not any(state == 1 for _, state in group) \
|
|
and any(state == 0 for _, state in group):
|
|
reasons.append("none of " + ", ".join(_wanted(g) for g, _ in group))
|
|
return reasons
|
|
|
|
|
|
def score_one(candidate: Candidate, gates: Sequence[Gate], weights: Weights,
|
|
fit: float | None, now: datetime, *, taste: float | None = None,
|
|
missing: str = "no vector") -> tuple[float, str]:
|
|
"""One role for one agent: `(score, gated_reason)`. `fit` and `taste` are
|
|
already scaled to 0..1 (see `scale`), or None when there is nothing to
|
|
measure: no role vector, no intent vector, no votes. A None term leaves
|
|
the denominator; `missing` says why fit is out."""
|
|
favourite = candidate.affinity == 2
|
|
if failed := failed_gates(candidate, gates):
|
|
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))
|
|
if taste is not None:
|
|
terms.append((weights.taste, taste))
|
|
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]:
|
|
"""Two passes: the cosines of the roles this agent scores, to its intent
|
|
and to its taste direction, then every score with both scaled across
|
|
them. A gated role is left out of the scaling, so a role that fails a
|
|
require gate cannot stretch the range the ranked roles share. The voted
|
|
roles are scored like any other; a liked one sits near the direction it
|
|
helped make, which is what a like should do."""
|
|
candidates = store.score_candidates(agent.id, agent.gates)
|
|
direction = taste_direction(vectors, store.votes(agent.id))
|
|
cosines: dict[str, float] = {}
|
|
tastes: dict[str, float] = {}
|
|
for candidate in candidates:
|
|
role_vec = vectors.get(candidate.uid)
|
|
if role_vec is None or failed_gates(candidate, agent.gates):
|
|
continue
|
|
if intent is not None:
|
|
cosines[candidate.uid] = cosine(role_vec, intent)
|
|
if direction is not None:
|
|
tastes[candidate.uid] = cosine(role_vec, direction)
|
|
fits, tastes = scale(cosines), scale(tastes)
|
|
rows: list[tuple[str, float, str]] = []
|
|
gated = 0
|
|
for candidate in candidates:
|
|
value, reason = score_one(
|
|
candidate, agent.gates, agent.weights, fits.get(candidate.uid), now,
|
|
taste=tastes.get(candidate.uid),
|
|
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 `config.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 "the defaults")
|
|
return added
|