bvandeusenandClaude Opus 5
95a37318fc
CI & Build / Python lint (push) Failing after 9s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 44s
CI & Build / integration (push) Successful in 45s
CI & Build / Python tests (push) Successful in 1m26s
CI & Build / Build & push image (push) Skipped
Rules were the only major record type with no vector, so `search` could never return one and a rule could arrive only by being preloaded. That single fact is what made every rule compete for one always-on budget. THE DECISION THE TASK ASKED FOR, made explicitly: a sibling rule_embeddings table, not a polymorphic embedding row. The ROW could have been generalised; the SEARCH could not. semantic_search_notes is Note-specific scoping end to end — the visibility clause, the supersession penalty, note_type/task_kind/system filters — and a rule shares none of it, scoping instead by rulebook ownership or project. Generalising the row while still needing two searches is the worst of both: a key with referential integrity to neither table, on the path every session start runs, to share four columns. What is genuinely common is BEHAVIOUR — get_embedding, chunk_document, embedding_text, CHUNKER_VERSION — and those are reused as-is. Sharing them is the DRY win; sharing the table would have been the DRY costume. The document shape is measured, not chosen (note 2485). That pass found the snippet was the only discriminative record in the corpus — a 0.153 top-to-second gap against 0.010-0.023 — and that the cause was its SHAPE: purpose stated twice in a short single-topic document. rule_document reproduces it: the trigger in the title AND as the body's first line. And it excludes `why`, which matters more than any of it. `why` is dated incident narrative — rule 46's runs to 4,300 characters — and long multi-topic prose is exactly what made sixteen dev-logs mutually indistinguishable. Adding it would not give the vector more to work with; it would give every rule the SAME thing to work with. rule_document takes no `why` parameter at all, so a well-meaning caller cannot pass one. A rule with no trigger degrades to title + statement — findable, less sharp. That is an argument for backfilling triggers (step 6), not for padding the document with whatever text is nearby. search(content_type="rule") returns the rule WITH its why and how_to_apply: they are its operational half, the session payload never carries them, and a caller who went looking should not have to re-fetch. Writes re-index fire-and-forget like notes; startup backfills in its own try block so neither backfill can skip the other. rule_embeddings is derived, so it joins note_embeddings in the backup's explicitly-NOT-included list. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
59 lines
2.2 KiB
Python
59 lines
2.2 KiB
Python
"""rule_embeddings — rules become findable by meaning (milestone 307 step 4,
|
|
decision note 3026)
|
|
|
|
Revision ID: 0089
|
|
Revises: 0088
|
|
Create Date: 2026-08-26
|
|
|
|
Rules were the only major record type with no vector, so `search` could never
|
|
return one and a rule could only ever arrive by being preloaded. That single
|
|
fact is what made every rule compete for the same always-on budget.
|
|
|
|
A sibling table rather than a generalisation of note_embeddings: the row could
|
|
have been made polymorphic, but the SEARCH could not — semantic_search_notes is
|
|
Note-specific scoping end to end, and a rule shares none of it. See the model
|
|
docstring for the full reasoning.
|
|
|
|
The vectors are DERIVED data. Nothing is backfilled here: the startup backfill
|
|
regenerates them, which is also how a chunker-version bump is handled.
|
|
"""
|
|
import sqlalchemy as sa
|
|
from alembic import op
|
|
|
|
revision = "0089"
|
|
down_revision = "0088"
|
|
branch_labels = None
|
|
depends_on = None
|
|
|
|
# Matches note_embeddings — bge-small-en-v1.5, 384-dim unit-normalized.
|
|
_EMBEDDING_DIM = 384
|
|
|
|
|
|
def upgrade() -> None:
|
|
op.create_table(
|
|
"rule_embeddings",
|
|
sa.Column("rule_id", sa.BigInteger(), sa.ForeignKey("rules.id", ondelete="CASCADE"), primary_key=True),
|
|
sa.Column("chunk_index", sa.Integer(), primary_key=True),
|
|
sa.Column("chunk_text", sa.Text(), nullable=False),
|
|
sa.Column("chunker_version", sa.Integer(), nullable=False),
|
|
sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
|
|
)
|
|
# The vector column is added by raw DDL for the same reason 0067 did it:
|
|
# the type comes from the pgvector extension, not from SQLAlchemy's
|
|
# type system.
|
|
op.execute(f"ALTER TABLE rule_embeddings ADD COLUMN embedding vector({_EMBEDDING_DIM}) NOT NULL")
|
|
# HNSW for cosine distance — matches Vector.cosine_distance (`<=>`), so the
|
|
# search is an indexed ORDER BY ... LIMIT k rather than a full scan.
|
|
op.execute(
|
|
"""
|
|
CREATE INDEX ix_rule_embeddings_embedding_hnsw
|
|
ON rule_embeddings
|
|
USING hnsw (embedding vector_cosine_ops)
|
|
"""
|
|
)
|
|
|
|
|
|
def downgrade() -> None:
|
|
op.execute("DROP INDEX IF EXISTS ix_rule_embeddings_embedding_hnsw")
|
|
op.drop_table("rule_embeddings")
|