Give a search agent several prompts and score a role by its best one

Migration 14 moves each non-empty agents.intent into agent_prompts as one
prompt named after the agent, with its cached vector, and drops the three
intent columns. A role's fit is the maximum over the agent's prompts of the
calibrated cosine, and scores.prompt names the prompt that won. The agents
API takes prompts and still takes intent; the role endpoint serves the
agent's score and prompt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Opus 5.5 committed 2026-09-29 16:19:57 +02:00
1 parent b6afe24eaa
commit 4e3c3f130e
9 files changed
+552 -127

No files matched your search

+44 -8
View File
@@ -177,25 +177,34 @@ BEGIN
SELECT RAISE(ABORT, 'application_events is append-only');
END;
-- A search agent: a named saved search with its own intent text, gates and
-- A search agent: a named saved search with its own prompts, gates and
-- weights. gates is a list of {field, values, mode: require|prefer, weight}.
-- intent_vec caches the intent's vector; intent_key is sha1 of the embedding
-- model and the intent text, so editing either makes it stale. limits is how
-- deep into this agent's ranking extract and summarise read, as JSON: a key
-- it lacks means the `Limits` default.
-- limits is how deep into this agent's ranking extract and summarise read,
-- as JSON: a key it lacks means the `Limits` default.
CREATE TABLE IF NOT EXISTS agents (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL UNIQUE,
intent TEXT NOT NULL DEFAULT '',
gates TEXT NOT NULL DEFAULT '[]',
weights TEXT NOT NULL DEFAULT '{}',
enabled INTEGER NOT NULL DEFAULT 1,
created_at TEXT NOT NULL,
intent_key TEXT NOT NULL DEFAULT '',
intent_vec BLOB,
limits TEXT NOT NULL DEFAULT '{}'
);
-- What an agent looks for, as several named texts in order; a role's fit is
-- its best prompt's. vec caches the text's vector and vec_key is sha1 of the
-- embedding model and the text, so editing one prompt re-embeds that one.
CREATE TABLE IF NOT EXISTS agent_prompts (
agent_id INTEGER NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
position INTEGER NOT NULL,
name TEXT NOT NULL,
text TEXT NOT NULL DEFAULT '',
vec_key TEXT NOT NULL DEFAULT '',
vec BLOB,
PRIMARY KEY (agent_id, position),
UNIQUE (agent_id, name COLLATE NOCASE)
);
-- One agent's stance on a company: -1 hidden, 0 neutral, 1 liked, 2
-- favourite. No row is 0, so the table holds only what somebody set. Per
-- agent, because a company that is noise for one search is the target of
@@ -220,12 +229,14 @@ CREATE TABLE IF NOT EXISTS role_votes (
);
-- A role is scored per agent. A gated role keeps its row, with the reason.
-- prompt names the agent's prompt that gave the fit, '' when fit did not count.
CREATE TABLE IF NOT EXISTS scores (
uid TEXT NOT NULL REFERENCES roles(uid) ON DELETE CASCADE,
agent_id INTEGER NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
score REAL NOT NULL DEFAULT 0,
gated_reason TEXT NOT NULL DEFAULT '',
scored_at TEXT NOT NULL,
prompt TEXT NOT NULL DEFAULT '',
PRIMARY KEY (uid, agent_id)
);
@@ -388,6 +399,31 @@ ALTER TABLE roles ADD COLUMN salary_text TEXT NOT NULL DEFAULT '';
"""),
(13, "roles.country recomputed from place for every not-yet-extracted role whose "
"board gave none, country lookup fix", lambda conn: _recompute_country(conn)),
# An agent's one intent becomes its first prompt, named after the agent,
# with its cached vector: the key hashes the model and the text, which
# are unchanged, so nothing is embedded again. An empty intent becomes no
# prompt. The three columns are then dropped, as v6 dropped the ones it
# moved.
(14, "agent_prompts and scores.prompt: an agent holds several prompts, and a "
"score names the one that gave the fit", """
CREATE TABLE agent_prompts (
agent_id INTEGER NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
position INTEGER NOT NULL,
name TEXT NOT NULL,
text TEXT NOT NULL DEFAULT '',
vec_key TEXT NOT NULL DEFAULT '',
vec BLOB,
PRIMARY KEY (agent_id, position),
UNIQUE (agent_id, name COLLATE NOCASE)
);
INSERT INTO agent_prompts (agent_id, position, name, text, vec_key, vec)
SELECT id, 0, name, intent, intent_key, intent_vec FROM agents
WHERE TRIM(intent, ' ' || char(9, 10, 13)) <> '';
ALTER TABLE agents DROP COLUMN intent;
ALTER TABLE agents DROP COLUMN intent_key;
ALTER TABLE agents DROP COLUMN intent_vec;
ALTER TABLE scores ADD COLUMN prompt TEXT NOT NULL DEFAULT '';
"""),
)
#: What a file created from `SCHEMA` today is already at.
+87 -43
View File
@@ -22,8 +22,9 @@ import numpy as np
from desk.models import Item
from app.models import (
AFFINITY, REMOTE, STATUSES, Agent, Application, ApplicationEvent, Candidate,
Company, Gate, Limits, Role, RoleRow, ScoredRole, Subscription, Weights, company_key,
country_of, excerpt, place_key, posted_at, posted_host, remote_of, title_key,
Company, Gate, Limits, Prompt, Role, RoleRow, ScoredRole, Subscription, Weights,
check_prompts, company_key, country_of, excerpt, place_key, posted_at, posted_host,
remote_of, title_key,
)
from app.storage import schema
@@ -369,14 +370,20 @@ class Store:
f"ON CONFLICT(uid) DO UPDATE SET {', '.join(updates)}", row)
return not existed
def role(self, uid: str, agent_id: int | None = None) -> Role | None:
"""One role with its tags, and with `vote` and `voted_at` as
`agent_id` judged it; None (unjudged) without an agent."""
row = self._row(f"SELECT roles.*, v.vote, v.voted_at FROM roles {_WITH_VOTES} "
"WHERE roles.uid=?", (agent_id, uid))
def role(self, uid: str, agent_id: int | None = None) -> ScoredRole | None:
"""One role with its tags, and with `vote`, `voted_at`, `score`,
`gated_reason` and `prompt` as `agent_id` judged and scored it; None
(unjudged, unscored) without an agent. The score is moved by the vote
as `roles` serves it."""
row = self._row(
f"SELECT roles.*, v.vote, v.voted_at, {_VOTED_SCORE} AS score, "
"COALESCE(s.gated_reason, '') AS gated_reason, COALESCE(s.prompt, '') AS prompt "
f"FROM roles {_WITH_VOTES} "
"LEFT JOIN scores s ON s.uid = roles.uid AND s.agent_id = ? WHERE roles.uid=?",
(agent_id, agent_id, uid))
if row is None:
return None
role = Role.from_row(row)
role = ScoredRole.from_row(row)
role.tags = self._tags_of(uid)
return role
@@ -397,7 +404,7 @@ class Store:
assert role is not None
return role
def set_vote(self, agent_id: int, uid: str, value: int | None) -> Role:
def set_vote(self, agent_id: int, uid: str, value: int | None) -> ScoredRole:
"""One agent's judgement of one role: 1 like, 0 neither way, -1 pass,
None unjudged again, which deletes the row. A vote never hides a
role; it moves it in that agent's ranking (see `roles`) and shapes its
@@ -532,7 +539,7 @@ class Store:
order = "roles.posted_at DESC, roles.uid"
scored = agent is not None and by_score
if scored:
select += f", {_VOTED_SCORE} AS score, s.gated_reason"
select += f", {_VOTED_SCORE} AS score, s.gated_reason, s.prompt"
order = "score DESC, " + order
elif open_only:
# Newest first, open only: idx_roles_posted covers this exactly
@@ -584,7 +591,7 @@ class Store:
order = "roles.posted_at DESC, roles.uid"
scored = agent is not None and by_score
if scored:
select += f", {_VOTED_SCORE} AS score, s.gated_reason"
select += f", {_VOTED_SCORE} AS score, s.gated_reason, s.prompt"
order = "score DESC, " + order
elif open_only:
# Same reasoning as `roles`: the planner otherwise sorts every
@@ -763,8 +770,9 @@ class Store:
held to the limits of the agent that ranked it; a key the JSON lacks
is the `Limits` default. The role is `r`. A company an agent hid
needs no clause: `score` writes no rows for it under that agent. An
agent without an intent counts for nothing here: its scores have no
fit, so they say how fresh a role is, not whether it is wanted."""
agent without a prompt with text counts for nothing here: its scores
have no fit, so they say how fresh a role is, not whether it is
wanted."""
defaults = Limits()
return (f"""r.uid IN (SELECT uid FROM (
SELECT s.uid, s.score, a.limits, ROW_NUMBER() OVER (
@@ -772,7 +780,9 @@ class Store:
ORDER BY s.score DESC, top.posted_at DESC, s.uid) AS n
FROM scores s
JOIN agents a ON a.id = s.agent_id AND a.enabled = 1
AND TRIM(a.intent, ' ' || char(9, 10, 13)) <> ''
AND EXISTS (SELECT 1 FROM agent_prompts p
WHERE p.agent_id = a.id
AND TRIM(p.text, ' ' || char(9, 10, 13)) <> '')
JOIN roles top ON top.uid = s.uid AND top.closed_at IS NULL
WHERE s.gated_reason = '')
WHERE n <= COALESCE(json_extract(limits, '$.{stage}_top'), ?)
@@ -1000,42 +1010,71 @@ class Store:
sql = "SELECT * FROM agents"
if enabled_only:
sql += " WHERE enabled = 1"
return [Agent.from_row(r)
for r in self._rows(sql + " ORDER BY name COLLATE NOCASE")]
return self._agents(self._rows(sql + " ORDER BY name COLLATE NOCASE"))
def agent(self, agent_id: int) -> Agent | None:
row = self._row("SELECT * FROM agents WHERE id=?", (agent_id,))
return Agent.from_row(row) if row else None
found = self._agents(self._rows("SELECT * FROM agents WHERE id=?", (agent_id,)))
return found[0] if found else None
def default_agent(self) -> Agent | None:
"""The agent a vote or an affinity goes to when none is named: the
enabled one with the lowest id, else the lowest id, else None."""
row = self._row("SELECT * FROM agents ORDER BY enabled DESC, id LIMIT 1")
return Agent.from_row(row) if row else None
found = self._agents(self._rows(
"SELECT * FROM agents ORDER BY enabled DESC, id LIMIT 1"))
return found[0] if found else None
def _agents(self, rows: Sequence[sqlite3.Row]) -> list[Agent]:
"""The rows as agents, each with its prompts in order, read with one
query for them all."""
prompts: dict[int, list[dict[str, str]]] = {}
for p in self._rows(
"SELECT agent_id, name, text FROM agent_prompts WHERE agent_id IN "
"(SELECT value FROM json_each(?)) ORDER BY agent_id, position",
(json.dumps([r["id"] for r in rows]),)):
prompts.setdefault(p["agent_id"], []).append({"name": p["name"], "text": p["text"]})
return [Agent.from_row({**dict(r), "prompts": prompts.get(r["id"], [])})
for r in rows]
def save_agent(self, name: str, intent: str = "", gates: Sequence[Gate] = (),
weights: Weights | None = None, enabled: bool = True,
agent_id: int | None = None, limits: Limits | None = None) -> Agent:
"""Create an agent, or with `agent_id` replace that one's fields.
Raises ValueError on an empty or taken name, KeyError on an unknown id."""
agent_id: int | None = None, limits: Limits | None = None,
prompts: Sequence[Prompt] | None = None) -> Agent:
"""Create an agent, or with `agent_id` replace that one's fields and
prompts. Without `prompts`, a non-empty `intent` is its one prompt,
named after the agent. A prompt whose text is unchanged keeps its
cached vector, whatever its name or place, so an edit re-embeds only
the prompts it changed. Raises ValueError on an empty or taken name,
or two prompts of one name, KeyError on an unknown id."""
name = name.strip()
if not name:
raise ValueError("an agent needs a name")
fields = (name, intent, json.dumps([g.model_dump() for g in gates]),
if prompts is None:
prompts = [Prompt(name=name, text=intent)] if intent.strip() else []
prompts = check_prompts(list(prompts))
fields = (name, json.dumps([g.model_dump() for g in gates]),
(weights or Weights()).model_dump_json(),
(limits or Limits()).model_dump_json(), int(enabled))
try:
with self.transaction() as conn:
if agent_id is None:
agent_id = conn.execute(
"""INSERT INTO agents (name, intent, gates, weights, limits,
enabled, created_at) VALUES (?,?,?,?,?,?,?)""",
"""INSERT INTO agents (name, gates, weights, limits, enabled,
created_at) VALUES (?,?,?,?,?,?)""",
(*fields, self.now())).lastrowid
elif not conn.execute(
"""UPDATE agents SET name=?, intent=?, gates=?, weights=?,
limits=?, enabled=? WHERE id=?""",
"""UPDATE agents SET name=?, gates=?, weights=?, limits=?, enabled=?
WHERE id=?""",
(*fields, agent_id)).rowcount:
raise KeyError(agent_id)
cached = {r["text"]: (r["vec_key"], r["vec"]) for r in conn.execute(
"SELECT text, vec_key, vec FROM agent_prompts WHERE agent_id=?",
(agent_id,))}
conn.execute("DELETE FROM agent_prompts WHERE agent_id=?", (agent_id,))
conn.executemany(
"""INSERT INTO agent_prompts (agent_id, position, name, text, vec_key, vec)
VALUES (?,?,?,?,?,?)""",
[(agent_id, n, p.name, p.text, *cached.get(p.text, ("", None)))
for n, p in enumerate(prompts)])
except sqlite3.IntegrityError as exc:
raise ValueError(f"an agent named {name!r} already exists") from exc
assert agent_id is not None
@@ -1044,20 +1083,22 @@ class Store:
return found
def delete_agent(self, agent_id: int) -> bool:
"""Its scores, votes and affinities go with it, by the foreign keys."""
"""Its prompts, scores, votes and affinities go with it, by the
foreign keys."""
return self._write("DELETE FROM agents WHERE id=?", (agent_id,)) > 0
def intent_vector(self, agent_id: int, key: str) -> np.ndarray | None:
"""The agent's cached intent vector, if it was made under `key`."""
row = self._row("SELECT intent_key, intent_vec FROM agents WHERE id=?",
(agent_id,))
if row is None or row["intent_key"] != key or row["intent_vec"] is None:
def prompt_vector(self, agent_id: int, name: str, key: str) -> np.ndarray | None:
"""The cached vector of the agent's prompt `name`, if it was made
under `key`."""
row = self._row("SELECT vec_key, vec FROM agent_prompts WHERE agent_id=? AND name=?",
(agent_id, name))
if row is None or row["vec_key"] != key or row["vec"] is None:
return None
return unpack(row["intent_vec"])
return unpack(row["vec"])
def set_intent_vector(self, agent_id: int, key: str, vec: np.ndarray) -> None:
self._write("UPDATE agents SET intent_key=?, intent_vec=? WHERE id=?",
(key, pack(vec), agent_id))
def set_prompt_vector(self, agent_id: int, name: str, key: str, vec: np.ndarray) -> None:
self._write("UPDATE agent_prompts SET vec_key=?, vec=? WHERE agent_id=? AND name=?",
(key, pack(vec), agent_id, name))
# --------------------------------------------------------------- scores
@@ -1088,9 +1129,11 @@ class Store:
for r in rows]
def replace_scores(self, agent_id: int,
rows: Sequence[tuple[str, float, str]]) -> int:
rows: Sequence[tuple[str, float, str] | tuple[str, float, str, str]]
) -> int:
"""`(uid, score, gated_reason)` for every role this agent scored,
replacing whatever it had: a role closed or muted since the last run
with the name of the prompt that gave the fit as a fourth item ('' when
left out), replacing whatever it had: a role closed or muted since the last run
drops out rather than keeping a stale score. One transaction, so a
reader sees the old list or the new one. An agent deleted while its
run was scoring gets nothing written and 0 back: its rows are gone
@@ -1101,9 +1144,10 @@ class Store:
return 0
conn.execute("DELETE FROM scores WHERE agent_id=?", (agent_id,))
conn.executemany(
"""INSERT INTO scores (uid, agent_id, score, gated_reason, scored_at)
VALUES (?,?,?,?,?)""",
[(uid, agent_id, score, reason, stamp) for uid, score, reason in rows])
"""INSERT INTO scores (uid, agent_id, score, gated_reason, prompt, scored_at)
VALUES (?,?,?,?,?,?)""",
[(row[0], agent_id, row[1], row[2], row[3] if len(row) > 3 else "", stamp)
for row in rows])
return len(rows)
def scores(self, agent_id: int) -> dict[str, tuple[float, str]]: