Merge main: read state and tags meet per-agent votes and affinity

The per-agent migration becomes v6 behind main's v5. A vote still stamps
the role's read_at, tag counts hide the agent's hidden companies, and
/api/filters takes the agent like /api/roles.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Fable 5.1 committed 2026-09-28 12:59:41 +02:00
commit c69fb0b6c4
23 files changed
+2270 -717

No files matched your search

+164 -19
View File
@@ -77,6 +77,29 @@ _COMPANY_SELECT = """SELECT c.*, COALESCE(ac.affinity, 0) AS affinity FROM compa
_SUBSCRIPTION_FIELDS = ("label", "company", "board", "params", "subscribed", "fetch",
"show", "target_id")
#: A tag's longest stored form, and how many a role may carry. Long enough for
#: "senior backend engineer" and short enough that the filter row stays a row.
_MAX_TAG_LEN = 40
_MAX_TAGS = 12
def _normalise_tags(tags: Sequence[str]) -> list[str]:
"""Each tag stripped, lowercased, its internal whitespace collapsed to one
space and cut to `_MAX_TAG_LEN`; empties and repeats dropped, order kept,
capped at `_MAX_TAGS`. What `set_tags` and `set_summary` store, so the
filter row never has to trust what a model or a person typed."""
seen: set[str] = set()
out: list[str] = []
for tag in tags:
cleaned = " ".join(str(tag).split()).lower()[:_MAX_TAG_LEN]
if not cleaned or cleaned in seen:
continue
seen.add(cleaned)
out.append(cleaned)
if len(out) >= _MAX_TAGS:
break
return out
def _iso(moment: datetime) -> str:
"""UTC, to the second. Every timestamp column is compared as text, so every
@@ -289,19 +312,42 @@ class Store:
return not existed
def role(self, uid: str, agent_id: int | None = None) -> Role | None:
"""One role, with `vote` and `voted_at` as `agent_id` judged it; None
(unjudged) without an agent."""
"""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))
return Role.from_row(row) if row else None
if row is None:
return None
role = Role.from_row(row)
role.tags = self._tags_of(uid)
return role
def set_read(self, uid: str, read: bool = True) -> Role:
"""Mark a role read, or unread again. Stamps `read_at` only the first
time — a role already read keeps the moment it was first opened —
and clears it outright when `read` is False. Raises KeyError for an
unknown uid."""
if read:
changed = self._write(
"UPDATE roles SET read_at = COALESCE(read_at, ?) WHERE uid = ?",
(self.now(), uid))
else:
changed = self._write("UPDATE roles SET read_at = NULL WHERE uid = ?", (uid,))
if not changed:
raise KeyError(uid)
role = self.role(uid)
assert role is not None
return role
def set_vote(self, agent_id: int, uid: str, value: int | None) -> Role:
"""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
taste direction (see `jobs/score.py`). Returns the role with this
agent's vote. Raises ValueError for another value and KeyError for an
unknown uid or agent."""
taste direction (see `jobs/score.py`). Voting is reading, so a vote
stamps the role's `read_at` too, the same once-only way `set_read`
does; clearing a vote is not un-reading, and leaves it alone. Returns
the role with this agent's vote. Raises ValueError for another value
and KeyError for an unknown uid or agent."""
if isinstance(value, bool) or value not in VOTES:
raise ValueError(f"a vote is -1, 0 or 1, not {value!r}")
with self.transaction() as conn:
@@ -311,11 +357,14 @@ class Store:
conn.execute("DELETE FROM role_votes WHERE agent_id=? AND uid=?",
(agent_id, uid))
else:
now = self.now()
conn.execute(
"""INSERT INTO role_votes (agent_id, uid, vote, voted_at) VALUES (?,?,?,?)
ON CONFLICT(agent_id, uid) DO UPDATE
SET vote=excluded.vote, voted_at=excluded.voted_at""",
(agent_id, uid, value, self.now()))
(agent_id, uid, value, now))
conn.execute("UPDATE roles SET read_at = COALESCE(read_at, ?) WHERE uid = ?",
(now, uid))
role = self.role(uid, agent_id)
assert role is not None
return role
@@ -333,12 +382,50 @@ class Store:
if conn.execute(f"SELECT 1 FROM {table} WHERE {column}=?", (value,)).fetchone() is None:
raise KeyError(value)
def set_tags(self, uid: str, tags: Sequence[str]) -> list[str]:
"""Replace one role's tags in one transaction. See `_normalise_tags`
for how each one is cleaned up. Returns what was stored, sorted the
way `role` and `roles` read it back. Raises KeyError for an unknown
uid."""
with self.transaction() as conn:
if conn.execute("SELECT 1 FROM roles WHERE uid=?", (uid,)).fetchone() is None:
raise KeyError(uid)
return self._replace_tags(conn, uid, tags)
def _replace_tags(self, conn: sqlite3.Connection, uid: str,
tags: Sequence[str]) -> list[str]:
"""`set_tags`'s write, against an already-open transaction so
`set_summary` can share it."""
cleaned = _normalise_tags(tags)
conn.execute("DELETE FROM role_tags WHERE uid=?", (uid,))
conn.executemany("INSERT INTO role_tags (uid, tag) VALUES (?,?)",
[(uid, tag) for tag in cleaned])
return sorted(cleaned)
def _tags_of(self, uid: str) -> list[str]:
return [str(r["tag"]) for r in self._rows(
"SELECT tag FROM role_tags WHERE uid=? ORDER BY tag", (uid,))]
def _tags_by_uid(self, uids: Sequence[str]) -> dict[str, list[str]]:
"""Every tag of these roles, by uid, sorted — one query for a whole
page rather than one per role."""
if not uids:
return {}
out: dict[str, list[str]] = {}
rows = self._rows(
"SELECT uid, tag FROM role_tags WHERE uid IN (SELECT value FROM json_each(?)) "
"ORDER BY uid, tag", (json.dumps(list(uids)),))
for r in rows:
out.setdefault(r["uid"], []).append(str(r["tag"]))
return out
def roles(self, limit: int = 100, company: str | None = None,
place: str | None = None, open_only: bool = True,
q: str | None = None, function: str | None = None,
remote: str | None = None, days: int | None = None,
hide_muted: bool = False, agent: int | None = None,
by_score: bool = True, gated: bool = False,
hide_muted: bool = False, include_read: bool = True,
tags: Sequence[str] = (), tag_mode: str = "any",
agent: int | None = None, by_score: bool = True, gated: bool = False,
judged: str | None = None, offset: int = 0) -> list[ScoredRole]:
"""Newest first by `first_seen`. `company` and `place` are
case-insensitive substrings of the columns a board wrote — not the
@@ -358,6 +445,12 @@ class Store:
for a default query that would otherwise have plenty. With no agent
every vote is None, nothing is hidden and `judged` reads as such.
`include_read` set False excludes a role `set_read` or `set_vote` has
stamped, the same way and for the same reason as `hide_muted`:
before `limit`, not after. `tags` keeps only roles carrying at least
one of them (`tag_mode="any"`, the default) or every one
(`tag_mode="all"`), also before `limit`.
With `agent` and `by_score`, ordered by that agent's score instead,
highest first, carrying `score` and `gated_reason` on each row. Only
roles it has scored are listed, and a gated one only when `gated` is
@@ -367,36 +460,46 @@ class Store:
no score.
`offset` skips that many rows of the same order, for the page that
loads the next 60 as it is scrolled; `count_roles` is the total."""
loads the next 60 as it is scrolled; `count_roles` is the total.
Every returned role carries its tags, read with one extra query for
the whole page rather than one per role."""
sql, params = self._roles_from(
company=company, place=place, open_only=open_only, q=q, function=function,
remote=remote, days=days, hide_muted=hide_muted, agent=agent,
by_score=by_score, gated=gated, judged=judged)
remote=remote, days=days, hide_muted=hide_muted, include_read=include_read,
tags=tags, tag_mode=tag_mode, agent=agent, by_score=by_score, gated=gated,
judged=judged)
select = "SELECT roles.*, v.vote, v.voted_at"
order = "roles.first_seen DESC, roles.uid"
if agent is not None and by_score:
select += f", {_VOTED_SCORE} AS score, s.gated_reason"
order = "score DESC, " + order
return [ScoredRole.from_row(r) for r in self._rows(
found = [ScoredRole.from_row(r) for r in self._rows(
f"{select} {sql} ORDER BY {order} LIMIT ? OFFSET ?", [*params, limit, offset])]
by_uid = self._tags_by_uid([r.uid for r in found])
for r in found:
r.tags = by_uid.get(r.uid, [])
return found
def count_roles(self, company: str | None = None, place: str | None = None,
open_only: bool = True, q: str | None = None,
function: str | None = None, remote: str | None = None,
days: int | None = None, hide_muted: bool = False,
agent: int | None = None, by_score: bool = True,
include_read: bool = True, tags: Sequence[str] = (),
tag_mode: str = "any", agent: int | None = None, by_score: bool = True,
gated: bool = False, judged: str | None = None) -> int:
"""How many roles `roles` would list with the same filters and no limit."""
sql, params = self._roles_from(
company=company, place=place, open_only=open_only, q=q, function=function,
remote=remote, days=days, hide_muted=hide_muted, agent=agent,
by_score=by_score, gated=gated, judged=judged)
remote=remote, days=days, hide_muted=hide_muted, include_read=include_read,
tags=tags, tag_mode=tag_mode, agent=agent, by_score=by_score, gated=gated,
judged=judged)
row = self._row(f"SELECT COUNT(*) AS n {sql}", params)
return int(row["n"]) if row else 0
def _roles_from(self, *, company: str | None, place: str | None, open_only: bool,
q: str | None, function: str | None, remote: str | None,
days: int | None, hide_muted: bool, agent: int | None,
days: int | None, hide_muted: bool, include_read: bool,
tags: Sequence[str], tag_mode: str, agent: int | None,
by_score: bool, gated: bool, judged: str | None) -> tuple[str, list[Any]]:
"""The `FROM ... WHERE ...` that `roles` and `count_roles` share, with
its parameters in order. The agent's votes are always joined as `v`
@@ -431,6 +534,22 @@ class Store:
where.append("company_key NOT IN (SELECT company_key FROM agent_companies "
"WHERE agent_id = ? AND affinity = -1)")
params.append(agent)
if not include_read:
where.append("roles.read_at IS NULL")
if tags:
marks = ", ".join("?" for _ in tags)
if tag_mode == "all":
where.append(
f"(SELECT COUNT(DISTINCT rt.tag) FROM role_tags rt "
f"WHERE rt.uid = roles.uid AND rt.tag IN ({marks})) = ?")
params += [*tags, len(tags)]
elif tag_mode == "any":
where.append(
f"EXISTS (SELECT 1 FROM role_tags rt "
f"WHERE rt.uid = roles.uid AND rt.tag IN ({marks}))")
params += list(tags)
else:
raise ValueError(f"tag_mode is any or all, not {tag_mode!r}")
sql = f"FROM roles {_WITH_VOTES}"
joins: list[Any] = [agent]
if agent is not None and by_score:
@@ -442,6 +561,26 @@ class Store:
sql += " WHERE " + " AND ".join(where)
return sql, [*joins, *params]
def tag_counts(self, agent_id: int | None = None,
show_muted: bool = False) -> list[tuple[str, int, int]]:
"""`(tag, open_count, unread_count)` over open roles, most-used tag
first and then alphabetically. What `/api/filters` serves; the
companies `agent_id` hid are left out unless `show_muted`, the same
default as `roles`, and with no agent nothing is hidden."""
where = "r.closed_at IS NULL"
params: list[Any] = []
if not show_muted and agent_id is not None:
where += (" AND r.company_key NOT IN (SELECT company_key FROM agent_companies "
"WHERE agent_id = ? AND affinity = -1)")
params.append(agent_id)
rows = self._rows(
f"""SELECT rt.tag AS tag, COUNT(*) AS n, SUM(r.read_at IS NULL) AS unread
FROM role_tags rt JOIN roles r ON r.uid = rt.uid
WHERE {where}
GROUP BY rt.tag
ORDER BY n DESC, rt.tag ASC""", params)
return [(str(r["tag"]), int(r["n"]), int(r["unread"])) for r in rows]
def mark_closed(self, source: str, seen_ids: Sequence[str],
subscription_id: int) -> int:
"""Close every open role of one board that a complete fetch of it did not
@@ -599,15 +738,21 @@ class Store:
f"SELECT r.* FROM roles r WHERE {where} "
"ORDER BY r.first_seen DESC, r.uid LIMIT ?", [*params, limit])]
def set_summary(self, uid: str, summary: str) -> bool:
def set_summary(self, uid: str, summary: str, tags: Sequence[str] = ()) -> bool:
"""Write a role's summary and stamp `summarised_at`. Only over an empty
one, so a second batch that carried the same role does not replace the
first answer. False for an unknown uid or one already summarised."""
first answer. Given `tags`, they replace the role's tags in the same
transaction — see `_replace_tags` — but only when the summary was
actually written, so a rejected late answer cannot plant tags on a
role it did not get to summarise. False for an unknown uid or one
already summarised."""
with self.transaction() as conn:
written = conn.execute(
"UPDATE roles SET summary = ?, summarised_at = ? "
"WHERE uid = ? AND summary = ''", (summary, self.now(), uid)).rowcount
conn.execute("DELETE FROM state WHERE key = ?", (self._SUMMARY_MISSED + uid,))
if written and tags:
self._replace_tags(conn, uid, tags)
return bool(written)
def summarise_missed(self, uids: Sequence[str], why: str = "") -> int: