feat(7728): one delivery order for rules, and each delivery recorded with whether it was opened
CI & Build / TypeScript typecheck (push) Successful in 41s
CI & Build / Plugin hooks (push) Successful in 17s
CI & Build / Python lint (push) Successful in 3s
CI & Build / Python tests (push) Failing after 1m41s
CI & Build / integration (push) Successful in 1m59s
CI & Build / Build & push image (push) Skipped
CI & Build / TypeScript typecheck (push) Successful in 41s
CI & Build / Plugin hooks (push) Successful in 17s
CI & Build / Python lint (push) Successful in 3s
CI & Build / Python tests (push) Failing after 1m41s
CI & Build / integration (push) Successful in 1m59s
CI & Build / Build & push image (push) Skipped
Every rule arm now ranks what it delivers with one function (services/rule_order.py): enforcement, then salience, then how narrowly the rule was reached, then first mention before reminder, then the rule's own open rate at that moment, then similarity. A crowded moment drops the same rules whichever arm brought them, and a rule that holds is never cut for a line beside it. The open rate comes from a new table, rule_deliveries (migration 0129): one row per rule line a plugin session is shown, full or repeat, with the open stamped on the latest delivery it followed. The plugin routes bind the session per request; the prompt, pre-tool and write-path hooks now send it, and the opened hook reports every open, with its acts only when no hook had just named the rule. Rows are pruned daily after 180 days. Also fixes the TypeScript check: the store's list row now carries the new enforcement field. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,42 @@
|
|||||||
|
"""rule deliveries — each rule line a session was shown, and whether it was opened after
|
||||||
|
|
||||||
|
Revision ID: 0129
|
||||||
|
Revises: 0128
|
||||||
|
Create Date: 2026-11-22
|
||||||
|
|
||||||
|
One row per rule line delivered to a session, with the open stamped on the
|
||||||
|
delivery it followed. The open rate per rule and moment is read from it, both
|
||||||
|
for the ordering of what reaches a moment and for the adherence readout.
|
||||||
|
"""
|
||||||
|
import sqlalchemy as sa
|
||||||
|
from alembic import op
|
||||||
|
|
||||||
|
revision = "0129"
|
||||||
|
down_revision = "0128"
|
||||||
|
branch_labels = None
|
||||||
|
depends_on = None
|
||||||
|
|
||||||
|
|
||||||
|
def upgrade() -> None:
|
||||||
|
op.create_table(
|
||||||
|
"rule_deliveries",
|
||||||
|
sa.Column("id", sa.BigInteger(), primary_key=True),
|
||||||
|
sa.Column("user_id", sa.BigInteger(), nullable=False),
|
||||||
|
sa.Column("session_id", sa.Text(), nullable=False),
|
||||||
|
sa.Column("rule_id", sa.BigInteger(), nullable=False),
|
||||||
|
sa.Column("source", sa.Text(), nullable=False),
|
||||||
|
sa.Column("at", sa.Text(), nullable=False),
|
||||||
|
sa.Column("form", sa.Text(), nullable=False),
|
||||||
|
sa.Column("delivered_at", sa.DateTime(timezone=True), nullable=False,
|
||||||
|
server_default=sa.func.now()),
|
||||||
|
sa.Column("opened_at", sa.DateTime(timezone=True), nullable=True),
|
||||||
|
sa.CheckConstraint("form IN ('full', 'repeat')", name="ck_rule_deliveries_form"),
|
||||||
|
)
|
||||||
|
op.create_index("ix_rule_deliveries_session_rule", "rule_deliveries",
|
||||||
|
["user_id", "session_id", "rule_id", "delivered_at"])
|
||||||
|
op.create_index("ix_rule_deliveries_rule_at", "rule_deliveries", ["rule_id", "at"])
|
||||||
|
op.create_index("ix_rule_deliveries_delivered_at", "rule_deliveries", ["delivered_at"])
|
||||||
|
|
||||||
|
|
||||||
|
def downgrade() -> None:
|
||||||
|
op.drop_table("rule_deliveries")
|
||||||
@@ -111,6 +111,9 @@ export const useRulebooksStore = defineStore("rulebooks", () => {
|
|||||||
// force as the same row re-fetched, or a preference the operator just
|
// force as the same row re-fetched, or a preference the operator just
|
||||||
// created would sit in the list looking like a rule until a reload.
|
// created would sit in the list looking like a rule until a reload.
|
||||||
kind: rule.kind,
|
kind: rule.kind,
|
||||||
|
enforcement: rule.enforcement ?? "inform",
|
||||||
|
// Mirrors rule_brief: present only when raised or lowered.
|
||||||
|
salience: rule.salience && rule.salience !== "normal" ? rule.salience : undefined,
|
||||||
updated_at: rule.updated_at,
|
updated_at: rule.updated_at,
|
||||||
when_to_apply: rule.when_to_apply || undefined,
|
when_to_apply: rule.when_to_apply || undefined,
|
||||||
arose_from_id: rule.arose_from_id ?? undefined,
|
arose_from_id: rule.arose_from_id ?? undefined,
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "grimoire",
|
"name": "grimoire",
|
||||||
"description": "Grimoire for Claude Code: connects the grimoire MCP server, adds the hooks that deliver live project state and relevant records at the right moment, ships the shared client-neutral Grimoire skills (using-grimoire, writing-plans, reporting-back, systematic-debugging, verification, brainstorming, reusing-code, shape-accounting, family-canon), and syncs your saved Grimoire Processes as skills (/grimoire:sync).",
|
"description": "Grimoire for Claude Code: connects the grimoire MCP server, adds the hooks that deliver live project state and relevant records at the right moment, ships the shared client-neutral Grimoire skills (using-grimoire, writing-plans, reporting-back, systematic-debugging, verification, brainstorming, reusing-code, shape-accounting, family-canon), and syncs your saved Grimoire Processes as skills (/grimoire:sync).",
|
||||||
"version": "2026.11.05.0301",
|
"version": "2026.11.22.2312",
|
||||||
"author": {
|
"author": {
|
||||||
"name": "Bryan Van Deusen"
|
"name": "Bryan Van Deusen"
|
||||||
},
|
},
|
||||||
|
|||||||
@@ -125,6 +125,8 @@ if [ -n "$session_id" ]; then
|
|||||||
[ -n "$rule_seen" ] && exclude_q="${exclude_q}&exclude_rule_ids=${rule_seen}"
|
[ -n "$rule_seen" ] && exclude_q="${exclude_q}&exclude_rule_ids=${rule_seen}"
|
||||||
# What the session actually OPENED, as against what it was shown.
|
# What the session actually OPENED, as against what it was shown.
|
||||||
exclude_q="${exclude_q}$(grimoire_held_query "$rule_state_dir/${safe_sid}.opened.ids")"
|
exclude_q="${exclude_q}$(grimoire_held_query "$rule_state_dir/${safe_sid}.opened.ids")"
|
||||||
|
# Which session the rule lines go to, so each is recorded as a delivery.
|
||||||
|
exclude_q="${exclude_q}&session_id=${safe_sid}"
|
||||||
# Which reply shapes it already holds in full: the core is
|
# Which reply shapes it already holds in full: the core is
|
||||||
# sent whole once, and as its one-line reminder on every later turn.
|
# sent whole once, and as its one-line reminder on every later turn.
|
||||||
shapefile=$(grimoire_shapes_file "$safe_sid")
|
shapefile=$(grimoire_shapes_file "$safe_sid")
|
||||||
|
|||||||
@@ -240,6 +240,8 @@ if [ -n "$session_id" ]; then
|
|||||||
[ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
|
[ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
|
||||||
# What the session actually OPENED, as against what it was shown.
|
# What the session actually OPENED, as against what it was shown.
|
||||||
rule_exclude_q="${rule_exclude_q}$(grimoire_held_query "$state_dir/${safe_sid}.opened.ids")"
|
rule_exclude_q="${rule_exclude_q}$(grimoire_held_query "$state_dir/${safe_sid}.opened.ids")"
|
||||||
|
# Which session the rule lines go to, so each is recorded as a delivery.
|
||||||
|
rule_exclude_q="${rule_exclude_q}&session_id=${safe_sid}"
|
||||||
fi
|
fi
|
||||||
|
|
||||||
# Not `|| exit 0`: an unreachable instance must not discard a local finding
|
# Not `|| exit 0`: an unreachable instance must not discard a local finding
|
||||||
|
|||||||
@@ -79,23 +79,30 @@ printf '%s\n' "$rule_id" | grimoire_rules_append "$state_dir/${safe_sid}.opened.
|
|||||||
# answers with one line putting the question to the reader. Nothing is
|
# answers with one line putting the question to the reader. Nothing is
|
||||||
# mounted by this.
|
# mounted by this.
|
||||||
#
|
#
|
||||||
# An open of a rule a hook has just NAMED is not reported. A ranked arm or a
|
# EVERY OPEN IS REPORTED: the server stamps it on this session's latest
|
||||||
# moment line put it in front of the reader, and that explains the open; the
|
# delivery of the rule, which is how an open rate per delivery is measured.
|
||||||
# moment beside it did not, so counting it would propose mounts on whatever
|
#
|
||||||
# moment happened to fire while search was surfacing the rule. The window is
|
# The acts go with it only when the rule was NOT just named by a hook. A
|
||||||
# short for the same reason: a few minutes of agent work reaches many moments.
|
# ranked arm or a moment line put a named rule in front of the reader, and
|
||||||
|
# that explains the open; the moment beside it did not, so counting it would
|
||||||
|
# propose mounts on whatever moment happened to fire while search was
|
||||||
|
# surfacing the rule. The window is short for the same reason: a few minutes
|
||||||
|
# of agent work reaches many moments.
|
||||||
command -v curl >/dev/null 2>&1 || exit 0
|
command -v curl >/dev/null 2>&1 || exit 0
|
||||||
grimoire_config || exit 0
|
grimoire_config || exit 0
|
||||||
|
acts=""
|
||||||
case ",$(grimoire_rules_live "$state_dir/${safe_sid}.rules.ids")," in
|
case ",$(grimoire_rules_live "$state_dir/${safe_sid}.rules.ids")," in
|
||||||
*",${rule_id},"*) exit 0 ;;
|
*",${rule_id},"*) ;;
|
||||||
|
*)
|
||||||
|
acts_file="${TMPDIR:-/tmp}/grimoire-moment/${safe_sid}.acts"
|
||||||
|
now=$(date +%s 2>/dev/null) || now=0
|
||||||
|
if [ -f "$acts_file" ] && [ "$now" -gt 0 ]; then
|
||||||
|
acts=$(awk -F '\t' -v since=$((now - 90)) \
|
||||||
|
'$1 + 0 >= since { sub(/^[^\t]*\t/, ""); print }' "$acts_file" 2>/dev/null \
|
||||||
|
| tail -n 3 | paste -sd ',' - 2>/dev/null)
|
||||||
|
fi
|
||||||
|
;;
|
||||||
esac
|
esac
|
||||||
acts_file="${TMPDIR:-/tmp}/grimoire-moment/${safe_sid}.acts"
|
|
||||||
[ -f "$acts_file" ] || exit 0
|
|
||||||
now=$(date +%s 2>/dev/null) || exit 0
|
|
||||||
acts=$(awk -F '\t' -v since=$((now - 90)) \
|
|
||||||
'$1 + 0 >= since { sub(/^[^\t]*\t/, ""); print }' "$acts_file" 2>/dev/null \
|
|
||||||
| tail -n 3 | paste -sd ',' - 2>/dev/null)
|
|
||||||
[ -n "$acts" ] || exit 0
|
|
||||||
|
|
||||||
sid_esc=$(printf '%s' "$session_id" | grimoire_json_escape) || exit 0
|
sid_esc=$(printf '%s' "$session_id" | grimoire_json_escape) || exit 0
|
||||||
event_cwd=$(grimoire_json_pick "$event_flat" '.cwd')
|
event_cwd=$(grimoire_json_pick "$event_flat" '.cwd')
|
||||||
|
|||||||
@@ -101,6 +101,8 @@ if [ -n "$session_id" ]; then
|
|||||||
[ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
|
[ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
|
||||||
# What the session actually OPENED, as against what it was shown.
|
# What the session actually OPENED, as against what it was shown.
|
||||||
rule_exclude_q="${rule_exclude_q}$(grimoire_held_query "$state_dir/${safe_sid}.opened.ids")"
|
rule_exclude_q="${rule_exclude_q}$(grimoire_held_query "$state_dir/${safe_sid}.opened.ids")"
|
||||||
|
# Which session the rule lines go to, so each is recorded as a delivery.
|
||||||
|
rule_exclude_q="${rule_exclude_q}&session_id=${safe_sid}"
|
||||||
# The Systems whose rulings were shown in full — shared with the write-path
|
# The Systems whose rulings were shown in full — shared with the write-path
|
||||||
# hook, for the reason the rule file is.
|
# hook, for the reason the rule file is.
|
||||||
rulingsfile="$state_dir/${safe_sid}.rulings.ids"
|
rulingsfile="$state_dir/${safe_sid}.rulings.ids"
|
||||||
|
|||||||
@@ -198,9 +198,12 @@ def create_app() -> Quart:
|
|||||||
from grimoire.services.logging import start_log_retention_loop
|
from grimoire.services.logging import start_log_retention_loop
|
||||||
from grimoire.services.notifications import start_notification_loop
|
from grimoire.services.notifications import start_notification_loop
|
||||||
|
|
||||||
|
from grimoire.services.rule_deliveries import start_prune_loop as start_rule_delivery_prune
|
||||||
|
|
||||||
start_log_retention_loop()
|
start_log_retention_loop()
|
||||||
start_notification_loop()
|
start_notification_loop()
|
||||||
start_auth_token_retention_loop()
|
start_auth_token_retention_loop()
|
||||||
|
start_rule_delivery_prune()
|
||||||
|
|
||||||
# The proxy hop count saved in Settings decides every request's client
|
# The proxy hop count saved in Settings decides every request's client
|
||||||
# address, so it is loaded before serving, under a deadline (a failed
|
# address, so it is loaded before serving, under a deadline (a failed
|
||||||
|
|||||||
@@ -60,6 +60,7 @@ from grimoire.models.retrieval_log import RetrievalLog # noqa: E402, F401
|
|||||||
from grimoire.models.retrieval_tuning import RetrievalTuningEvent # noqa: E402, F401
|
from grimoire.models.retrieval_tuning import RetrievalTuningEvent # noqa: E402, F401
|
||||||
from grimoire.models.note_usage import NoteUsageEvent # noqa: E402, F401
|
from grimoire.models.note_usage import NoteUsageEvent # noqa: E402, F401
|
||||||
from grimoire.models.rule_usage import RuleUsageEvent # noqa: E402, F401
|
from grimoire.models.rule_usage import RuleUsageEvent # noqa: E402, F401
|
||||||
|
from grimoire.models.rule_delivery import RuleDelivery # noqa: E402, F401
|
||||||
from grimoire.models.system_usage import SystemUsageEvent # noqa: E402, F401
|
from grimoire.models.system_usage import SystemUsageEvent # noqa: E402, F401
|
||||||
from grimoire.models.retrieval_judgment import RetrievalJudgment # noqa: E402, F401
|
from grimoire.models.retrieval_judgment import RetrievalJudgment # noqa: E402, F401
|
||||||
from grimoire.models.moment_mapping import MomentMapping # noqa: E402, F401
|
from grimoire.models.moment_mapping import MomentMapping # noqa: E402, F401
|
||||||
|
|||||||
@@ -0,0 +1,69 @@
|
|||||||
|
from datetime import datetime
|
||||||
|
|
||||||
|
from sqlalchemy import BigInteger, DateTime, Index, Text, func
|
||||||
|
from sqlalchemy.orm import Mapped, mapped_column
|
||||||
|
|
||||||
|
from grimoire.models import Base
|
||||||
|
from grimoire.models.base import iso
|
||||||
|
|
||||||
|
FULL = "full"
|
||||||
|
REPEAT = "repeat"
|
||||||
|
FORMS = (FULL, REPEAT)
|
||||||
|
|
||||||
|
|
||||||
|
class RuleDelivery(Base):
|
||||||
|
"""One rule line put in front of one session, and whether it was opened after.
|
||||||
|
|
||||||
|
WHAT IT ANSWERS that `rule_usage_events` cannot. A surfaced event and a
|
||||||
|
pulled event are counted separately, so "was THIS delivery opened" has no
|
||||||
|
answer there: a rule opened once in a session reads as pulled whether it
|
||||||
|
was delivered once or twenty times. Here each delivery is a row, and the
|
||||||
|
open is stamped on the delivery it followed — so the open rate per rule,
|
||||||
|
per moment and per arm is a count of rows, and the ordering function reads
|
||||||
|
it as the rule's history at that moment.
|
||||||
|
|
||||||
|
`at` is where the rule was delivered: the moment it was mounted on
|
||||||
|
(`work.finish`) or the arm that found it (`pre_tool_rule`). `form` is
|
||||||
|
whether the line carried the rule's trigger (`full`) or only cited it
|
||||||
|
(`repeat`). Repeats are recorded too: they are deliveries a session can
|
||||||
|
open, and the case for retiring a rule rests on how rarely they are.
|
||||||
|
|
||||||
|
FK-free on `rule_id` and `user_id`, like the other telemetry tables: the
|
||||||
|
evidence that a rule was delivered forty times and opened never outlives
|
||||||
|
the rule, because it is the case for having deleted it.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__tablename__ = "rule_deliveries"
|
||||||
|
|
||||||
|
id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
|
||||||
|
user_id: Mapped[int] = mapped_column(BigInteger, nullable=False)
|
||||||
|
session_id: Mapped[str] = mapped_column(Text, nullable=False)
|
||||||
|
rule_id: Mapped[int] = mapped_column(BigInteger, nullable=False)
|
||||||
|
source: Mapped[str] = mapped_column(Text, nullable=False)
|
||||||
|
at: Mapped[str] = mapped_column(Text, nullable=False)
|
||||||
|
form: Mapped[str] = mapped_column(Text, nullable=False)
|
||||||
|
delivered_at: Mapped[datetime] = mapped_column(
|
||||||
|
DateTime(timezone=True), nullable=False, server_default=func.now(),
|
||||||
|
)
|
||||||
|
opened_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||||
|
|
||||||
|
__table_args__ = (
|
||||||
|
# Stamping an open: this session's latest delivery of this rule.
|
||||||
|
Index("ix_rule_deliveries_session_rule", "user_id", "session_id", "rule_id", "delivered_at"),
|
||||||
|
# History: a batch of rules at one moment.
|
||||||
|
Index("ix_rule_deliveries_rule_at", "rule_id", "at"),
|
||||||
|
Index("ix_rule_deliveries_delivered_at", "delivered_at"),
|
||||||
|
)
|
||||||
|
|
||||||
|
def to_dict(self) -> dict:
|
||||||
|
return {
|
||||||
|
"id": self.id,
|
||||||
|
"user_id": self.user_id,
|
||||||
|
"session_id": self.session_id,
|
||||||
|
"rule_id": self.rule_id,
|
||||||
|
"source": self.source,
|
||||||
|
"at": self.at,
|
||||||
|
"form": self.form,
|
||||||
|
"delivered_at": iso(self.delivered_at),
|
||||||
|
"opened_at": iso(self.opened_at),
|
||||||
|
}
|
||||||
@@ -20,6 +20,7 @@ from grimoire.services import plugin_context as plugin_ctx_svc
|
|||||||
from grimoire.services import reply_shapes as reply_shapes_svc
|
from grimoire.services import reply_shapes as reply_shapes_svc
|
||||||
from grimoire.services import repo_bindings as repo_bindings_svc
|
from grimoire.services import repo_bindings as repo_bindings_svc
|
||||||
from grimoire.services import report_check as report_check_svc
|
from grimoire.services import report_check as report_check_svc
|
||||||
|
from grimoire.services import rule_deliveries as rule_deliveries_svc
|
||||||
from grimoire.services import rule_moment_judgments as judgments_svc
|
from grimoire.services import rule_moment_judgments as judgments_svc
|
||||||
from grimoire.services import shape_check as shape_check_svc
|
from grimoire.services import shape_check as shape_check_svc
|
||||||
from grimoire.services import task_claims as task_claims_svc
|
from grimoire.services import task_claims as task_claims_svc
|
||||||
@@ -36,6 +37,22 @@ plugin_bp = Blueprint("plugin", __name__, url_prefix="/api/plugin")
|
|||||||
_MARKETPLACE_KEY = "plugin_marketplace_url"
|
_MARKETPLACE_KEY = "plugin_marketplace_url"
|
||||||
|
|
||||||
|
|
||||||
|
@plugin_bp.before_request
|
||||||
|
async def _bind_delivery_session() -> None:
|
||||||
|
"""Bind the session this request delivers to, for the delivery record.
|
||||||
|
|
||||||
|
A hook names it as `session_id` in the query, or carries it in the event
|
||||||
|
it posts (`/moment` sends the PreToolUse event whole). A request that
|
||||||
|
names none records no deliveries and reads no delivery history.
|
||||||
|
"""
|
||||||
|
sid = request.args.get("session_id") or ""
|
||||||
|
if not sid and request.method == "POST":
|
||||||
|
body = await request.get_json(silent=True)
|
||||||
|
if isinstance(body, dict):
|
||||||
|
sid = str(body.get("session_id") or "")
|
||||||
|
rule_deliveries_svc.bind_session(sid)
|
||||||
|
|
||||||
|
|
||||||
def _int_list(raw: str | None) -> list[int]:
|
def _int_list(raw: str | None) -> list[int]:
|
||||||
"""A comma-separated id list from the query string; non-ints dropped."""
|
"""A comma-separated id list from the query string; non-ints dropped."""
|
||||||
return [int(p) for p in (raw or "").split(",") if p.strip().isdigit()]
|
return [int(p) for p in (raw or "").split(",") if p.strip().isdigit()]
|
||||||
@@ -336,7 +353,10 @@ async def rule_opened():
|
|||||||
"""A session opened a rule shortly after these acts.
|
"""A session opened a rule shortly after these acts.
|
||||||
|
|
||||||
Body: `{"rule_id", "session_id", "acts": [<PreToolUse event>, ...]}` —
|
Body: `{"rule_id", "session_id", "acts": [<PreToolUse event>, ...]}` —
|
||||||
the calls the plugin saw in the window before the `get_rule`. Each is
|
the calls the plugin saw in the window before the `get_rule`. Every open
|
||||||
|
is first stamped on this session's latest delivery of the rule, which is
|
||||||
|
how the open rate per delivery is measured; `acts` is empty when the
|
||||||
|
rule was one a hook had just named, which explains the open by itself. Each is
|
||||||
resolved to its moments, and the open is counted as evidence that the
|
resolved to its moments, and the open is counted as evidence that the
|
||||||
rule belongs on them; once a pair has repeated across enough distinct
|
rule belongs on them; once a pair has repeated across enough distinct
|
||||||
sessions, `context` carries the line asking the reader to offer the
|
sessions, `context` carries the line asking the reader to offer the
|
||||||
@@ -349,8 +369,13 @@ async def rule_opened():
|
|||||||
rule_id = int(data.get("rule_id") or 0)
|
rule_id = int(data.get("rule_id") or 0)
|
||||||
except (TypeError, ValueError):
|
except (TypeError, ValueError):
|
||||||
rule_id = 0
|
rule_id = 0
|
||||||
|
if rule_id > 0:
|
||||||
|
# The open, against the delivery it followed — whatever the acts say.
|
||||||
|
await rule_deliveries_svc.mark_opened(
|
||||||
|
g.user.id, str(data.get("session_id") or ""), rule_id,
|
||||||
|
)
|
||||||
acts = data.get("acts")
|
acts = data.get("acts")
|
||||||
if rule_id <= 0 or not isinstance(acts, list):
|
if rule_id <= 0 or not isinstance(acts, list) or not acts:
|
||||||
return jsonify({"moments": [], "context": ""})
|
return jsonify({"moments": [], "context": ""})
|
||||||
project_id, _repo, _unbound = await _project_scope()
|
project_id, _repo, _unbound = await _project_scope()
|
||||||
return jsonify(await judgments_svc.opened_after(
|
return jsonify(await judgments_svc.opened_after(
|
||||||
|
|||||||
@@ -183,6 +183,10 @@ _NOT_INCLUDED = [
|
|||||||
"app_logs", "notifications",
|
"app_logs", "notifications",
|
||||||
"invitation_tokens", "password_reset_tokens",
|
"invitation_tokens", "password_reset_tokens",
|
||||||
"retrieval_logs",
|
"retrieval_logs",
|
||||||
|
# Per-session delivery rows, keyed by session ids that mean nothing on
|
||||||
|
# another instance and pruned after months anyway. The ordering reads
|
||||||
|
# them as history; a restored instance rebuilds it within weeks.
|
||||||
|
"rule_deliveries",
|
||||||
# Verdicts on retrieval_logs rows, so they go where their subject
|
# Verdicts on retrieval_logs rows, so they go where their subject
|
||||||
# goes: a restore that carried a judgment of a call it did not carry would
|
# goes: a restore that carried a judgment of a call it did not carry would
|
||||||
# leave a verdict on nothing. A sample, re-takeable by the review pass.
|
# leave a verdict on nothing. A sample, re-takeable by the review pass.
|
||||||
|
|||||||
@@ -24,11 +24,14 @@ logger = logging.getLogger(__name__)
|
|||||||
|
|
||||||
def _io() -> rp.MomentIO:
|
def _io() -> rp.MomentIO:
|
||||||
"""Resolved at CALL time, so a test patching either module's name is seen."""
|
"""Resolved at CALL time, so a test patching either module's name is seen."""
|
||||||
from grimoire.services import rule_usage, rulebooks
|
from grimoire.services import rule_deliveries, rule_usage, rulebooks
|
||||||
|
|
||||||
|
bound = rule_deliveries.bound()
|
||||||
return rp.MomentIO(
|
return rp.MomentIO(
|
||||||
lookup=rulebooks.rules_on_moments,
|
lookup=rulebooks.rules_on_moments,
|
||||||
record_rule_surfaced=rule_usage.record_rule_surfaced,
|
record_rule_surfaced=rule_usage.record_rule_surfaced,
|
||||||
|
history=rule_deliveries.history if bound else None,
|
||||||
|
record_delivery=rule_deliveries.record if bound else None,
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -974,10 +974,15 @@ def _rule_io() -> rp.RuleIO:
|
|||||||
the pipeline reports to whatever this module's `semantic_search_rules`,
|
the pipeline reports to whatever this module's `semantic_search_rules`,
|
||||||
`record_retrieval` and `record_rule_surfaced` are at the moment it runs.
|
`record_retrieval` and `record_rule_surfaced` are at the moment it runs.
|
||||||
"""
|
"""
|
||||||
|
from grimoire.services import rule_deliveries
|
||||||
|
|
||||||
|
bound = rule_deliveries.bound()
|
||||||
return rp.RuleIO(
|
return rp.RuleIO(
|
||||||
search=semantic_search_rules,
|
search=semantic_search_rules,
|
||||||
record_retrieval=record_retrieval,
|
record_retrieval=record_retrieval,
|
||||||
record_rule_surfaced=record_rule_surfaced,
|
record_rule_surfaced=record_rule_surfaced,
|
||||||
|
history=rule_deliveries.history if bound else None,
|
||||||
|
record_delivery=rule_deliveries.record if bound else None,
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -35,6 +35,7 @@ import time
|
|||||||
from dataclasses import dataclass, field
|
from dataclasses import dataclass, field
|
||||||
from typing import Any, Callable
|
from typing import Any, Callable
|
||||||
|
|
||||||
|
from grimoire.services import rule_order
|
||||||
from grimoire.services.lessons import LESSON_NOTE_TYPE, claim_line
|
from grimoire.services.lessons import LESSON_NOTE_TYPE, claim_line
|
||||||
|
|
||||||
logger = logging.getLogger(__name__)
|
logger = logging.getLogger(__name__)
|
||||||
@@ -576,6 +577,12 @@ class RuleIO:
|
|||||||
|
|
||||||
record_retrieval: Callable[..., Any]
|
record_retrieval: Callable[..., Any]
|
||||||
record_rule_surfaced: Callable[..., Any]
|
record_rule_surfaced: Callable[..., Any]
|
||||||
|
history: Callable[..., Any] | None = None
|
||||||
|
"""`rule_deliveries.history`: `{rule_id: open rate}` for (rule, at) pairs.
|
||||||
|
None leaves every rule's history unknown."""
|
||||||
|
record_delivery: Callable[..., Any] | None = None
|
||||||
|
"""`rule_deliveries.record`: each line shown, against the session the
|
||||||
|
door bound. None records nothing."""
|
||||||
|
|
||||||
|
|
||||||
@dataclass(frozen=True)
|
@dataclass(frozen=True)
|
||||||
@@ -773,6 +780,30 @@ async def _reserve_slot_for_preference(
|
|||||||
# ── The pipeline ─────────────────────────────────────────────────────────
|
# ── The pipeline ─────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
|
||||||
|
def _record_delivery(io, moment: RuleMoment, source: str, shown: list[tuple[int, str, bool]]) -> None:
|
||||||
|
"""Record each line shown — `(rule_id, at, was_a_repeat)` — as a delivery."""
|
||||||
|
if io.record_delivery is None or not shown:
|
||||||
|
return
|
||||||
|
try:
|
||||||
|
io.record_delivery(moment.user_id, None, source, [
|
||||||
|
(rid, at, "repeat" if repeat else "full") for rid, at, repeat in shown
|
||||||
|
])
|
||||||
|
except Exception: # noqa: BLE001 - observation never breaks the observed
|
||||||
|
_telemetry_failed(source)
|
||||||
|
|
||||||
|
|
||||||
|
async def _history(io, moment: RuleMoment, pairs: list[tuple[int, str]]) -> dict[int, float]:
|
||||||
|
"""Each rule's open rate where it is about to be delivered; {} when the
|
||||||
|
door has no history to read or the read fails — unknown, never an error."""
|
||||||
|
if io.history is None or not pairs:
|
||||||
|
return {}
|
||||||
|
try:
|
||||||
|
return await io.history(moment.user_id, pairs) or {}
|
||||||
|
except Exception: # noqa: BLE001 - history orders lines, it never withholds them
|
||||||
|
logger.debug("rule delivery history unreadable", exc_info=True)
|
||||||
|
return {}
|
||||||
|
|
||||||
|
|
||||||
async def run_rule_arm(
|
async def run_rule_arm(
|
||||||
arm: RuleArm, moment: RuleMoment, *, floor: float, budget: int, io: RuleIO,
|
arm: RuleArm, moment: RuleMoment, *, floor: float, budget: int, io: RuleIO,
|
||||||
checkpoint_floor: float = 0.0,
|
checkpoint_floor: float = 0.0,
|
||||||
@@ -801,6 +832,19 @@ async def run_rule_arm(
|
|||||||
# still has something to say, it just says it differently.
|
# still has something to say, it just says it differently.
|
||||||
if not shown:
|
if not shown:
|
||||||
return RuleResult()
|
return RuleResult()
|
||||||
|
# Into the one delivery order: a rule that holds outranks one that
|
||||||
|
# informs whatever their scores, and score breaks the last tie.
|
||||||
|
history = await _history(io, moment, [(rule.id, arm.source) for _s, rule in shown])
|
||||||
|
shown = [
|
||||||
|
c.extra for c in rule_order.ordered(
|
||||||
|
rule_order.Candidate(
|
||||||
|
rule=rule, specificity=rule_order.BY_RESEMBLANCE,
|
||||||
|
opened_rate=history.get(rule.id), similarity=score,
|
||||||
|
seen=rule.id in moment.exclude, extra=(score, rule),
|
||||||
|
)
|
||||||
|
for score, rule in shown
|
||||||
|
)
|
||||||
|
]
|
||||||
|
|
||||||
lines = [
|
lines = [
|
||||||
_rule_hint_line(
|
_rule_hint_line(
|
||||||
@@ -836,6 +880,11 @@ async def run_rule_arm(
|
|||||||
)
|
)
|
||||||
except Exception: # noqa: BLE001 - observation never breaks the observed
|
except Exception: # noqa: BLE001 - observation never breaks the observed
|
||||||
_telemetry_failed(source)
|
_telemetry_failed(source)
|
||||||
|
# A stop-only arm shows its lines to nobody: only a hold speaks.
|
||||||
|
if not arm.stop_only:
|
||||||
|
_record_delivery(io, moment, source, [
|
||||||
|
(rule.id, source, rule.id in moment.exclude) for _s, rule in shown
|
||||||
|
])
|
||||||
return RuleResult(
|
return RuleResult(
|
||||||
lines=lines, rule_ids=rule_ids,
|
lines=lines, rule_ids=rule_ids,
|
||||||
shown_rule_ids=[rule.id for _score, rule in shown],
|
shown_rule_ids=[rule.id for _score, rule in shown],
|
||||||
@@ -1597,6 +1646,10 @@ class MomentIO:
|
|||||||
"""`rulebooks.rules_on_moments`, or a stand-in with its signature."""
|
"""`rulebooks.rules_on_moments`, or a stand-in with its signature."""
|
||||||
|
|
||||||
record_rule_surfaced: Callable[..., Any]
|
record_rule_surfaced: Callable[..., Any]
|
||||||
|
history: Callable[..., Any] | None = None
|
||||||
|
"""As on `RuleIO`."""
|
||||||
|
record_delivery: Callable[..., Any] | None = None
|
||||||
|
"""As on `RuleIO`."""
|
||||||
|
|
||||||
|
|
||||||
def _reached_by(hit: dict) -> str:
|
def _reached_by(hit: dict) -> str:
|
||||||
@@ -1626,8 +1679,20 @@ async def run_moment_arm(
|
|||||||
if not pairs:
|
if not pairs:
|
||||||
return RuleResult()
|
return RuleResult()
|
||||||
by_moment = {hit["moment"]: hit for hit in reached}
|
by_moment = {hit["moment"]: hit for hit in reached}
|
||||||
# Stable: catalog order within each half, fresh half first.
|
# The one delivery order (services/rule_order.py), then the cap — so
|
||||||
shown = sorted(pairs, key=lambda pair: pair[0].id in moment.exclude)[:limit]
|
# what a crowded moment drops is the lowest-ranked, not the last
|
||||||
|
# mounted. Ties keep catalog order.
|
||||||
|
history = await _history(io, moment, [(rule.id, at) for rule, at in pairs])
|
||||||
|
shown = [
|
||||||
|
c.extra for c in rule_order.ordered(
|
||||||
|
rule_order.Candidate(
|
||||||
|
rule=rule, specificity=rule_order.BY_MOUNT,
|
||||||
|
opened_rate=history.get(rule.id),
|
||||||
|
seen=rule.id in moment.exclude, extra=(rule, at),
|
||||||
|
)
|
||||||
|
for rule, at in pairs
|
||||||
|
)
|
||||||
|
][:limit]
|
||||||
|
|
||||||
lines = []
|
lines = []
|
||||||
for rule, at in shown:
|
for rule, at in shown:
|
||||||
@@ -1651,6 +1716,9 @@ async def run_moment_arm(
|
|||||||
)
|
)
|
||||||
except Exception: # noqa: BLE001 - observation never breaks the observed
|
except Exception: # noqa: BLE001 - observation never breaks the observed
|
||||||
_telemetry_failed(MOMENT_RULE_SOURCE)
|
_telemetry_failed(MOMENT_RULE_SOURCE)
|
||||||
|
_record_delivery(io, moment, MOMENT_RULE_SOURCE, [
|
||||||
|
(rule.id, at, rule.id in moment.exclude) for rule, at in shown
|
||||||
|
])
|
||||||
return RuleResult(
|
return RuleResult(
|
||||||
lines=lines, rule_ids=rule_ids,
|
lines=lines, rule_ids=rule_ids,
|
||||||
shown_rule_ids=[rule.id for rule, _at in shown],
|
shown_rule_ids=[rule.id for rule, _at in shown],
|
||||||
|
|||||||
@@ -0,0 +1,180 @@
|
|||||||
|
"""Each rule line a session is shown, whether it was opened after, and what
|
||||||
|
that history says about where a rule is worth delivering.
|
||||||
|
|
||||||
|
Three calls, one table (`rule_deliveries`):
|
||||||
|
|
||||||
|
- `record` — fire-and-forget, from the plugin doors that know the session:
|
||||||
|
every line an arm put in front of it, full or repeat.
|
||||||
|
- `mark_opened` — the session opened a rule: the latest unopened delivery of
|
||||||
|
it in that session gets the stamp. An open with no delivery behind it (the
|
||||||
|
agent looked a rule up unprompted) stamps nothing.
|
||||||
|
- `history` — for the ordering function: each rule's smoothed open rate at
|
||||||
|
the place it is about to be delivered, over the last `HISTORY_DAYS`.
|
||||||
|
|
||||||
|
Deliveries are kept `RETAIN_DAYS` and pruned daily: enough history to rank on
|
||||||
|
and to read adherence from, without a row per tool call accumulating forever.
|
||||||
|
"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import logging
|
||||||
|
import re
|
||||||
|
from contextvars import ContextVar
|
||||||
|
from datetime import datetime, timedelta, timezone
|
||||||
|
|
||||||
|
from sqlalchemy import and_, case, delete, func, select, tuple_, update
|
||||||
|
|
||||||
|
from grimoire.models import async_session
|
||||||
|
from grimoire.models.rule_delivery import FORMS, FULL, RuleDelivery
|
||||||
|
from grimoire.services import rule_order
|
||||||
|
from grimoire.services.background import spawn
|
||||||
|
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
HISTORY_DAYS = 90
|
||||||
|
RETAIN_DAYS = 180
|
||||||
|
# An open counts against a delivery made within this window before it; an
|
||||||
|
# older one was read by a context that is long gone.
|
||||||
|
OPEN_WINDOW = timedelta(hours=6)
|
||||||
|
_SESSION_MAX = 200
|
||||||
|
_UNSAFE = re.compile(r"[^A-Za-z0-9._-]")
|
||||||
|
|
||||||
|
# The session a plugin request is delivering to, bound once per request by the
|
||||||
|
# plugin routes so the arms several calls deep record against it without every
|
||||||
|
# signature between carrying it. Unbound (the MCP door, a test) records nothing.
|
||||||
|
_session: ContextVar[str] = ContextVar("rule_delivery_session", default="")
|
||||||
|
|
||||||
|
|
||||||
|
def bind_session(session_id: str | None) -> None:
|
||||||
|
_session.set(_clean_session(session_id))
|
||||||
|
|
||||||
|
|
||||||
|
def bound() -> bool:
|
||||||
|
"""Whether this request delivers to a known session — the doors that
|
||||||
|
record deliveries are the ones that read their history back."""
|
||||||
|
return bool(_session.get())
|
||||||
|
|
||||||
|
|
||||||
|
def _clean_session(session_id: str | None) -> str:
|
||||||
|
# The plugin's own filename-safe form of the id, so a hook that sends the
|
||||||
|
# raw id and one that sends the safe one name the same session.
|
||||||
|
return _UNSAFE.sub("_", (session_id or "").strip())[:_SESSION_MAX]
|
||||||
|
|
||||||
|
|
||||||
|
def record(
|
||||||
|
user_id: int, session_id: str | None, source: str,
|
||||||
|
lines: list[tuple[int, str, str]],
|
||||||
|
) -> None:
|
||||||
|
"""Record delivered lines: `(rule_id, at, form)` each. Fire-and-forget,
|
||||||
|
and a no-op without a session, since an open could never be tied back.
|
||||||
|
`session_id` None means the one bound for this request."""
|
||||||
|
sid = _clean_session(_session.get() if session_id is None else session_id)
|
||||||
|
if not sid or not lines:
|
||||||
|
return
|
||||||
|
try:
|
||||||
|
rows = [
|
||||||
|
{"user_id": int(user_id), "session_id": sid, "rule_id": int(rid),
|
||||||
|
"source": source, "at": str(at or source), "form": form if form in FORMS else FULL}
|
||||||
|
for rid, at, form in lines
|
||||||
|
]
|
||||||
|
except Exception: # noqa: BLE001 - observation never breaks the observed
|
||||||
|
logger.debug("rule delivery payload build failed", exc_info=True)
|
||||||
|
return
|
||||||
|
spawn(_insert(rows), site="rule_delivery_write")
|
||||||
|
|
||||||
|
|
||||||
|
async def _insert(rows: list[dict]) -> None:
|
||||||
|
async with async_session() as session:
|
||||||
|
session.add_all(RuleDelivery(**row) for row in rows)
|
||||||
|
await session.commit()
|
||||||
|
|
||||||
|
|
||||||
|
async def mark_opened(user_id: int, session_id: str | None, rule_id: int) -> bool:
|
||||||
|
"""Stamp the latest unopened delivery of this rule in this session.
|
||||||
|
|
||||||
|
Returns whether a delivery was stamped. Only that one: a rule delivered
|
||||||
|
five times and opened once was opened after the fifth line, and the four
|
||||||
|
before it were passed over.
|
||||||
|
"""
|
||||||
|
sid = _clean_session(session_id)
|
||||||
|
if not sid or not rule_id:
|
||||||
|
return False
|
||||||
|
now = datetime.now(timezone.utc)
|
||||||
|
async with async_session() as session:
|
||||||
|
latest = (await session.execute(
|
||||||
|
select(RuleDelivery.id)
|
||||||
|
.where(
|
||||||
|
RuleDelivery.user_id == user_id,
|
||||||
|
RuleDelivery.session_id == sid,
|
||||||
|
RuleDelivery.rule_id == rule_id,
|
||||||
|
RuleDelivery.opened_at.is_(None),
|
||||||
|
RuleDelivery.delivered_at >= now - OPEN_WINDOW,
|
||||||
|
)
|
||||||
|
.order_by(RuleDelivery.delivered_at.desc(), RuleDelivery.id.desc())
|
||||||
|
.limit(1)
|
||||||
|
)).scalar_one_or_none()
|
||||||
|
if latest is None:
|
||||||
|
return False
|
||||||
|
await session.execute(
|
||||||
|
update(RuleDelivery).where(RuleDelivery.id == latest).values(opened_at=now)
|
||||||
|
)
|
||||||
|
await session.commit()
|
||||||
|
return True
|
||||||
|
|
||||||
|
|
||||||
|
async def history(user_id: int, pairs: list[tuple[int, str]]) -> dict[int, float]:
|
||||||
|
"""`{rule_id: smoothed open rate}` at each pair's place, for this user.
|
||||||
|
|
||||||
|
A rule with no delivery there is left out, which the ordering reads as
|
||||||
|
unknown rather than as never opened.
|
||||||
|
"""
|
||||||
|
wanted = list(dict.fromkeys((int(rid), str(at)) for rid, at in pairs))
|
||||||
|
if not wanted:
|
||||||
|
return {}
|
||||||
|
since = datetime.now(timezone.utc) - timedelta(days=HISTORY_DAYS)
|
||||||
|
async with async_session() as session:
|
||||||
|
rows = (await session.execute(
|
||||||
|
select(
|
||||||
|
RuleDelivery.rule_id, RuleDelivery.at,
|
||||||
|
func.count(RuleDelivery.id),
|
||||||
|
func.sum(case((RuleDelivery.opened_at.is_not(None), 1), else_=0)),
|
||||||
|
)
|
||||||
|
.where(
|
||||||
|
RuleDelivery.user_id == user_id,
|
||||||
|
RuleDelivery.delivered_at >= since,
|
||||||
|
tuple_(RuleDelivery.rule_id, RuleDelivery.at).in_(wanted),
|
||||||
|
)
|
||||||
|
.group_by(RuleDelivery.rule_id, RuleDelivery.at)
|
||||||
|
)).all()
|
||||||
|
return {
|
||||||
|
int(rid): rule_order.opened_rate(int(delivered), int(opened or 0))
|
||||||
|
for rid, _at, delivered, opened in rows
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
async def prune(retain_days: int = RETAIN_DAYS) -> int:
|
||||||
|
cutoff = datetime.now(timezone.utc) - timedelta(days=retain_days)
|
||||||
|
async with async_session() as session:
|
||||||
|
result = await session.execute(
|
||||||
|
delete(RuleDelivery).where(and_(RuleDelivery.delivered_at < cutoff))
|
||||||
|
)
|
||||||
|
await session.commit()
|
||||||
|
return int(result.rowcount or 0)
|
||||||
|
|
||||||
|
|
||||||
|
_prune_task = None
|
||||||
|
|
||||||
|
|
||||||
|
async def _prune_tick() -> None:
|
||||||
|
try:
|
||||||
|
removed = await prune()
|
||||||
|
if removed:
|
||||||
|
logger.info("Rule delivery retention: deleted %d row(s)", removed)
|
||||||
|
except Exception:
|
||||||
|
logger.exception("Rule delivery retention failed")
|
||||||
|
|
||||||
|
|
||||||
|
def start_prune_loop() -> None:
|
||||||
|
global _prune_task
|
||||||
|
if _prune_task is None or _prune_task.done():
|
||||||
|
from grimoire.services.background import start_periodic
|
||||||
|
_prune_task = start_periodic(86400, _prune_tick, label="rule_delivery_retention") # daily
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
"""The one order in which rules reach a moment.
|
||||||
|
|
||||||
|
Every arm that puts rules in front of a session — the rules mounted on a
|
||||||
|
moment, the rules a typed trigger matched, the rules a semantic search found —
|
||||||
|
ranks what it has the same way, so a crowded moment drops the same rules
|
||||||
|
whichever arm brought them:
|
||||||
|
|
||||||
|
1. **enforcement** — `enforce`, then `hold`, then `inform`. A rule that stops
|
||||||
|
the work is never the one cut to make room for a line beside it.
|
||||||
|
2. **salience** — `high`, `normal`, `low`, as the rule's author declared it.
|
||||||
|
3. **specificity** — how narrowly the rule was reached. A trigger that named
|
||||||
|
this command or this path says more than a mount on the whole moment, and a
|
||||||
|
mount says more than a resemblance.
|
||||||
|
4. **news** — at the same rank, a rule this session has not been shown yet
|
||||||
|
comes before one it has, so a cap cuts a reminder rather than a first
|
||||||
|
mention.
|
||||||
|
5. **history** — how often this rule was opened when delivered at this
|
||||||
|
moment before. A rule sessions keep opening here outranks one they keep
|
||||||
|
passing over.
|
||||||
|
6. **similarity** — the search score, when there is one. Last, because it is
|
||||||
|
the one signal that says what the work resembles rather than what it is.
|
||||||
|
|
||||||
|
Each key is a declared or recorded fact, read in that order, so the outcome
|
||||||
|
can be explained line by line: "it outranked that one because it holds".
|
||||||
|
"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from collections.abc import Iterable
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
ENFORCEMENT_RANK = {"enforce": 0, "hold": 1, "inform": 2}
|
||||||
|
SALIENCE_RANK = {"high": 0, "normal": 1, "low": 2}
|
||||||
|
|
||||||
|
# How narrowly a rule was reached, larger is narrower.
|
||||||
|
BY_RESEMBLANCE = 0
|
||||||
|
BY_MOUNT = 1
|
||||||
|
BY_TRIGGER = 2
|
||||||
|
|
||||||
|
# A rule with no delivery history at a moment ranks as if half its deliveries
|
||||||
|
# there were opened: unknown is neither proof of use nor of neglect.
|
||||||
|
UNKNOWN_HISTORY = 0.5
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class Candidate:
|
||||||
|
"""One rule an arm could deliver, with what it knows about how it got here."""
|
||||||
|
|
||||||
|
rule: Any
|
||||||
|
specificity: int = BY_RESEMBLANCE
|
||||||
|
opened_rate: float | None = None
|
||||||
|
"""Share of this rule's earlier deliveries at this moment that were opened."""
|
||||||
|
similarity: float | None = None
|
||||||
|
seen: bool = False
|
||||||
|
"""Already shown to this session."""
|
||||||
|
extra: Any = None
|
||||||
|
"""Whatever the arm needs back with the rule — the moment it was mounted
|
||||||
|
on, its score pair — carried through the sort untouched."""
|
||||||
|
|
||||||
|
|
||||||
|
def order_key(c: Candidate) -> tuple:
|
||||||
|
rule = c.rule
|
||||||
|
return (
|
||||||
|
ENFORCEMENT_RANK.get(getattr(rule, "enforcement", None) or "inform", 2),
|
||||||
|
SALIENCE_RANK.get(getattr(rule, "salience", None) or "normal", 1),
|
||||||
|
-c.specificity,
|
||||||
|
c.seen,
|
||||||
|
-(UNKNOWN_HISTORY if c.opened_rate is None else c.opened_rate),
|
||||||
|
-(c.similarity or 0.0),
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def ordered(candidates: Iterable[Candidate]) -> list[Candidate]:
|
||||||
|
"""The candidates in delivery order. Stable: ties keep the arm's own order."""
|
||||||
|
return sorted(candidates, key=order_key)
|
||||||
|
|
||||||
|
|
||||||
|
def opened_rate(delivered: int, opened: int) -> float:
|
||||||
|
"""A smoothed open rate, so one delivery opened once does not read as certainty."""
|
||||||
|
return (opened + 1) / (delivered + 2)
|
||||||
@@ -0,0 +1,107 @@
|
|||||||
|
"""Real-Postgres tests for `rule_deliveries`: a delivery recorded against a
|
||||||
|
session, the open stamped on the one it followed, and the history read back."""
|
||||||
|
import asyncio
|
||||||
|
from datetime import datetime, timedelta, timezone
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
from sqlalchemy import delete, select, update
|
||||||
|
|
||||||
|
from grimoire.models import async_session
|
||||||
|
from grimoire.models.rule_delivery import RuleDelivery
|
||||||
|
from grimoire.services import background, rule_deliveries
|
||||||
|
from tests.helpers import ensure_user
|
||||||
|
|
||||||
|
pytestmark = [pytest.mark.integration, pytest.mark.usefixtures("_dispose_engine")]
|
||||||
|
|
||||||
|
RULE = 9_100_001
|
||||||
|
OTHER = 9_100_002
|
||||||
|
|
||||||
|
|
||||||
|
async def _user() -> int:
|
||||||
|
async with async_session() as s:
|
||||||
|
user = await ensure_user(s, "rule_delivery_owner")
|
||||||
|
uid = user.id
|
||||||
|
await s.commit()
|
||||||
|
await s.execute(delete(RuleDelivery).where(RuleDelivery.user_id == uid))
|
||||||
|
await s.commit()
|
||||||
|
return uid
|
||||||
|
|
||||||
|
|
||||||
|
async def _rows(uid: int) -> list[RuleDelivery]:
|
||||||
|
async with async_session() as s:
|
||||||
|
return list((await s.execute(
|
||||||
|
select(RuleDelivery).where(RuleDelivery.user_id == uid).order_by(RuleDelivery.id)
|
||||||
|
)).scalars().all())
|
||||||
|
|
||||||
|
|
||||||
|
async def _record(uid, sid, source, lines):
|
||||||
|
rule_deliveries.record(uid, sid, source, lines)
|
||||||
|
await background.drain()
|
||||||
|
|
||||||
|
|
||||||
|
async def test_an_open_is_stamped_on_the_sessions_latest_delivery_only():
|
||||||
|
uid = await _user()
|
||||||
|
await _record(uid, "s-1", "moment_rule", [(RULE, "work.finish", "full")])
|
||||||
|
await asyncio.sleep(0.01)
|
||||||
|
await _record(uid, "s-1", "moment_rule", [(RULE, "work.finish", "repeat")])
|
||||||
|
await _record(uid, "s-2", "moment_rule", [(RULE, "work.finish", "full")])
|
||||||
|
|
||||||
|
assert await rule_deliveries.mark_opened(uid, "s-1", RULE) is True
|
||||||
|
rows = await _rows(uid)
|
||||||
|
opened = [(r.session_id, r.form) for r in rows if r.opened_at is not None]
|
||||||
|
assert opened == [("s-1", "repeat")]
|
||||||
|
# A second open with nothing left unopened in the session stamps the earlier one.
|
||||||
|
assert await rule_deliveries.mark_opened(uid, "s-1", RULE) is True
|
||||||
|
assert await rule_deliveries.mark_opened(uid, "s-1", RULE) is False
|
||||||
|
|
||||||
|
|
||||||
|
async def test_an_open_with_no_delivery_behind_it_stamps_nothing():
|
||||||
|
uid = await _user()
|
||||||
|
assert await rule_deliveries.mark_opened(uid, "s-1", OTHER) is False
|
||||||
|
assert await rule_deliveries.mark_opened(uid, "", RULE) is False
|
||||||
|
|
||||||
|
|
||||||
|
async def test_without_a_session_nothing_is_recorded():
|
||||||
|
uid = await _user()
|
||||||
|
rule_deliveries.bind_session("")
|
||||||
|
await _record(uid, None, "prompt_rule", [(RULE, "prompt_rule", "full")])
|
||||||
|
assert await _rows(uid) == []
|
||||||
|
|
||||||
|
|
||||||
|
async def test_a_bound_session_is_the_one_recorded():
|
||||||
|
uid = await _user()
|
||||||
|
rule_deliveries.bind_session("bound s/3")
|
||||||
|
await _record(uid, None, "prompt_rule", [(RULE, "prompt_rule", "full")])
|
||||||
|
# The plugin's filename-safe form, so the raw and safe ids agree.
|
||||||
|
assert [r.session_id for r in await _rows(uid)] == ["bound_s_3"]
|
||||||
|
rule_deliveries.bind_session("")
|
||||||
|
|
||||||
|
|
||||||
|
async def test_history_is_the_smoothed_open_rate_at_each_place():
|
||||||
|
uid = await _user()
|
||||||
|
await _record(uid, "s-1", "moment_rule", [(RULE, "work.finish", "full")] * 3
|
||||||
|
+ [(RULE, "work.deliver", "full"), (OTHER, "work.finish", "full")])
|
||||||
|
await rule_deliveries.mark_opened(uid, "s-1", RULE) # one of the five RULE rows
|
||||||
|
|
||||||
|
history = await rule_deliveries.history(uid, [(RULE, "work.finish"), (OTHER, "work.finish")])
|
||||||
|
rows = await _rows(uid)
|
||||||
|
stamped_at = next(r.at for r in rows if r.opened_at is not None)
|
||||||
|
finish_opened = 1 if stamped_at == "work.finish" else 0
|
||||||
|
assert history[RULE] == pytest.approx((finish_opened + 1) / (3 + 2))
|
||||||
|
assert history[OTHER] == pytest.approx(1 / 3)
|
||||||
|
# A place with no delivery is unknown, not zero.
|
||||||
|
assert await rule_deliveries.history(uid, [(RULE, "reply.report")]) == {}
|
||||||
|
|
||||||
|
|
||||||
|
async def test_old_deliveries_are_pruned():
|
||||||
|
uid = await _user()
|
||||||
|
await _record(uid, "s-1", "moment_rule", [(RULE, "work.finish", "full"), (OTHER, "work.finish", "full")])
|
||||||
|
async with async_session() as s:
|
||||||
|
await s.execute(
|
||||||
|
update(RuleDelivery)
|
||||||
|
.where(RuleDelivery.user_id == uid, RuleDelivery.rule_id == RULE)
|
||||||
|
.values(delivered_at=datetime.now(timezone.utc) - timedelta(days=rule_deliveries.RETAIN_DAYS + 1))
|
||||||
|
)
|
||||||
|
await s.commit()
|
||||||
|
assert await rule_deliveries.prune() >= 1
|
||||||
|
assert [r.rule_id for r in await _rows(uid)] == [OTHER]
|
||||||
@@ -166,7 +166,9 @@ def test_an_open_of_a_rule_a_hook_just_named_is_not_reported(sandbox):
|
|||||||
{"session_id": "s1", "tool_name": "mcp__grimoire__get_rule",
|
{"session_id": "s1", "tool_name": "mcp__grimoire__get_rule",
|
||||||
"tool_input": {"rule_id": 11}}, env)
|
"tool_input": {"rule_id": 11}}, env)
|
||||||
assert out.stdout == ""
|
assert out.stdout == ""
|
||||||
assert not (tmp / "curl.log").exists()
|
# The open is reported for the delivery record, with no acts to count.
|
||||||
|
assert json.loads((tmp / "curl.body").read_text()) == {
|
||||||
|
"rule_id": 11, "session_id": "s1", "acts": []}
|
||||||
# The open itself is still recorded.
|
# The open itself is still recorded.
|
||||||
assert (named / "s1.opened.ids").read_text().startswith("11\t")
|
assert (named / "s1.opened.ids").read_text().startswith("11\t")
|
||||||
# A rule no hook named is still reported.
|
# A rule no hook named is still reported.
|
||||||
@@ -176,7 +178,7 @@ def test_an_open_of_a_rule_a_hook_just_named_is_not_reported(sandbox):
|
|||||||
assert json.loads((tmp / "curl.body").read_text())["rule_id"] == 1
|
assert json.loads((tmp / "curl.body").read_text())["rule_id"] == 1
|
||||||
|
|
||||||
|
|
||||||
def test_an_open_with_nothing_in_the_window_sends_nothing(sandbox):
|
def test_an_open_with_nothing_in_the_window_sends_only_the_open(sandbox):
|
||||||
tmp, env = sandbox
|
tmp, env = sandbox
|
||||||
ledger = tmp / "grimoire-moment"
|
ledger = tmp / "grimoire-moment"
|
||||||
ledger.mkdir()
|
ledger.mkdir()
|
||||||
@@ -185,9 +187,9 @@ def test_an_open_with_nothing_in_the_window_sends_nothing(sandbox):
|
|||||||
)
|
)
|
||||||
out = _run("grimoire_record_opened.sh",
|
out = _run("grimoire_record_opened.sh",
|
||||||
{"session_id": "s1", "tool_name": "mcp__grimoire__get_rule",
|
{"session_id": "s1", "tool_name": "mcp__grimoire__get_rule",
|
||||||
"tool_input": {"rule_id": 11}}, env)
|
"tool_input": {"rule_id": 11}}, env, FAKE_CURL_REPLY='{"moments":[],"context":""}')
|
||||||
assert out.stdout == ""
|
assert out.stdout == ""
|
||||||
assert not (tmp / "curl.log").exists()
|
assert json.loads((tmp / "curl.body").read_text())["acts"] == []
|
||||||
|
|
||||||
|
|
||||||
def test_session_end_removes_the_sessions_moment_files_and_no_others(sandbox):
|
def test_session_end_removes_the_sessions_moment_files_and_no_others(sandbox):
|
||||||
|
|||||||
@@ -0,0 +1,131 @@
|
|||||||
|
"""The one delivery order, key by key, and both rule arms reading it."""
|
||||||
|
from types import SimpleNamespace
|
||||||
|
from unittest.mock import AsyncMock, MagicMock
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
|
||||||
|
from grimoire.services import retrieval_pipeline as rp
|
||||||
|
from grimoire.services import rule_order as ro
|
||||||
|
|
||||||
|
|
||||||
|
def _r(rid, enforcement="inform", salience="normal"):
|
||||||
|
return SimpleNamespace(id=rid, title=f"rule {rid}", kind="rule", when_to_apply="when",
|
||||||
|
enforcement=enforcement, salience=salience)
|
||||||
|
|
||||||
|
|
||||||
|
def _ids(cands):
|
||||||
|
return [c.rule.id for c in ro.ordered(cands)]
|
||||||
|
|
||||||
|
|
||||||
|
def test_a_rule_that_stops_the_work_outranks_any_line_beside_it():
|
||||||
|
cands = [ro.Candidate(_r(1), similarity=0.95),
|
||||||
|
ro.Candidate(_r(2, "hold"), similarity=0.71),
|
||||||
|
ro.Candidate(_r(3, "enforce"), similarity=0.70)]
|
||||||
|
assert _ids(cands) == [3, 2, 1]
|
||||||
|
|
||||||
|
|
||||||
|
def test_salience_decides_between_rules_of_the_same_enforcement():
|
||||||
|
cands = [ro.Candidate(_r(1, salience="low")), ro.Candidate(_r(2)),
|
||||||
|
ro.Candidate(_r(3, salience="high"))]
|
||||||
|
assert _ids(cands) == [3, 2, 1]
|
||||||
|
|
||||||
|
|
||||||
|
def test_a_trigger_outranks_a_mount_and_a_mount_outranks_a_resemblance():
|
||||||
|
cands = [ro.Candidate(_r(1), specificity=ro.BY_RESEMBLANCE, similarity=0.9),
|
||||||
|
ro.Candidate(_r(2), specificity=ro.BY_MOUNT),
|
||||||
|
ro.Candidate(_r(3), specificity=ro.BY_TRIGGER)]
|
||||||
|
assert _ids(cands) == [3, 2, 1]
|
||||||
|
|
||||||
|
|
||||||
|
def test_a_first_mention_outranks_a_reminder_at_the_same_rank():
|
||||||
|
cands = [ro.Candidate(_r(1), seen=True), ro.Candidate(_r(2))]
|
||||||
|
assert _ids(cands) == [2, 1]
|
||||||
|
|
||||||
|
|
||||||
|
def test_history_breaks_the_tie_before_similarity_does():
|
||||||
|
cands = [ro.Candidate(_r(1), opened_rate=0.1, similarity=0.9),
|
||||||
|
ro.Candidate(_r(2), opened_rate=0.8, similarity=0.7),
|
||||||
|
ro.Candidate(_r(3), similarity=0.99)]
|
||||||
|
# Unknown history ranks between them, as an even chance.
|
||||||
|
assert _ids(cands) == [2, 3, 1]
|
||||||
|
|
||||||
|
|
||||||
|
def test_ties_keep_the_arms_own_order():
|
||||||
|
cands = [ro.Candidate(_r(i)) for i in (4, 2, 9)]
|
||||||
|
assert _ids(cands) == [4, 2, 9]
|
||||||
|
|
||||||
|
|
||||||
|
def test_a_rule_with_no_declared_fields_reads_as_inform_normal():
|
||||||
|
bare = SimpleNamespace(id=1)
|
||||||
|
assert ro.order_key(ro.Candidate(bare))[:2] == (2, 1)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.parametrize(("delivered", "opened", "rate"), [(0, 0, 0.5), (1, 1, 2 / 3), (10, 0, 1 / 12)])
|
||||||
|
def test_the_open_rate_is_smoothed(delivered, opened, rate):
|
||||||
|
assert ro.opened_rate(delivered, opened) == pytest.approx(rate)
|
||||||
|
|
||||||
|
|
||||||
|
PUSH = [{"moment": "work.deliver", "tool": "Bash", "match": "git push", "via": "default"}]
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_the_moment_arm_delivers_in_that_order_before_its_cap():
|
||||||
|
pairs = [(_r(i), "work.deliver") for i in range(1, 11)] + [(_r(99, "hold"), "work.deliver")]
|
||||||
|
result = await rp.run_moment_arm(
|
||||||
|
PUSH, rp.RuleMoment(user_id=1, query="", project_id=2),
|
||||||
|
io=rp.MomentIO(lookup=AsyncMock(return_value=pairs), record_rule_surfaced=MagicMock()),
|
||||||
|
)
|
||||||
|
# The holding rule was mounted last and still leads; the cap cut ordinary ones.
|
||||||
|
assert result.shown_rule_ids[0] == 99
|
||||||
|
assert len(result.shown_rule_ids) == rp.MOMENT_RULE_LIMIT
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_the_semantic_arm_delivers_in_that_order():
|
||||||
|
hits = [(0.91, _r(1)), (0.74, _r(2, "hold"))]
|
||||||
|
io = rp.RuleIO(search=AsyncMock(return_value=hits), record_retrieval=MagicMock(),
|
||||||
|
record_rule_surfaced=MagicMock())
|
||||||
|
result = await rp.run_rule_arm(
|
||||||
|
rp.PROMPT_RULE, rp.RuleMoment(user_id=1, query="q", project_id=2, where="here"),
|
||||||
|
floor=0.5, budget=5, io=io,
|
||||||
|
)
|
||||||
|
assert result.shown_rule_ids[:2] == [2, 1]
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_each_line_shown_is_recorded_as_a_delivery_with_its_form():
|
||||||
|
recorded = MagicMock()
|
||||||
|
pairs = [(_r(5), "work.finish"), (_r(6), "work.finish")]
|
||||||
|
await rp.run_moment_arm(
|
||||||
|
PUSH, rp.RuleMoment(user_id=1, query="", project_id=2, exclude=frozenset({6})),
|
||||||
|
io=rp.MomentIO(lookup=AsyncMock(return_value=pairs), record_rule_surfaced=MagicMock(),
|
||||||
|
record_delivery=recorded),
|
||||||
|
)
|
||||||
|
_uid, _sid, source, lines = recorded.call_args.args
|
||||||
|
assert source == rp.MOMENT_RULE_SOURCE
|
||||||
|
assert lines == [(5, "work.finish", "full"), (6, "work.finish", "repeat")]
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_history_reorders_rules_of_equal_rank_and_a_failed_read_is_unknown():
|
||||||
|
pairs = [(_r(5), "work.finish"), (_r(6), "work.finish")]
|
||||||
|
|
||||||
|
async def history(_uid, _pairs):
|
||||||
|
return {6: 0.9, 5: 0.1}
|
||||||
|
|
||||||
|
result = await rp.run_moment_arm(
|
||||||
|
PUSH, rp.RuleMoment(user_id=1, query="", project_id=2),
|
||||||
|
io=rp.MomentIO(lookup=AsyncMock(return_value=pairs), record_rule_surfaced=MagicMock(),
|
||||||
|
history=history),
|
||||||
|
)
|
||||||
|
assert result.shown_rule_ids == [6, 5]
|
||||||
|
|
||||||
|
async def broken(_uid, _pairs):
|
||||||
|
raise RuntimeError("no database")
|
||||||
|
|
||||||
|
result = await rp.run_moment_arm(
|
||||||
|
PUSH, rp.RuleMoment(user_id=1, query="", project_id=2),
|
||||||
|
io=rp.MomentIO(lookup=AsyncMock(return_value=pairs), record_rule_surfaced=MagicMock(),
|
||||||
|
history=broken),
|
||||||
|
)
|
||||||
|
assert result.shown_rule_ids == [5, 6]
|
||||||
Reference in New Issue
Block a user