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>
218 lines
8.2 KiB
Python
218 lines
8.2 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 ("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
|