abstractnote 0.1.0__py3-none-any.whl

abstractnote/recall/review.py

@@ -0,0 +1,191 @@
+"""Proposed matches and disagreements for a person to look at (``GET /note/review``), and the confirm action.
+
+Every item comes from stored records, never from reading text (ADR 0004):
+
+- ``close_match`` (rule ``unsure_match``): the processor answered ``unsure`` for a mention, so it created a new
+  entry and recorded an active ``skos:closeMatch`` claim from it to the candidate (``process/revise.py``). Shown
+  while the claim is active and the two are still separate entries.
+- ``merge`` (rule ``merged_by_model``): an ``entity.merge`` the processor made on its own, still in force and not
+  confirmed by you. Merges you confirm here are never listed.
+- ``contradiction`` (rule ``disputed_pair``): two active claims that a note marked as disagreeing
+  (``claim.add`` with ``disputes``, the model's ``contradicts`` decision). Both are kept until one is withdrawn.
+
+Actions: ``confirm`` (``POST /note/review/{id}/confirm``) records a user-action revision with action
+``match.confirm``: for a close match it merges the new entry into the candidate and supersedes the close-match
+claim; for a merge it records that you keep it (no op changes the graph). The other actions are the existing
+endpoints: ``unmerge`` a merge, ``keep_apart`` (retract the close-match claim) and ``retract`` one side of a
+disagreement.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .. import ids
+from ..store.notes import _uj, clamp_limit
+
+CLOSE_MATCH = "skos:closeMatch"  # the predicate process/revise.py records for an unsure match
+CONFIRM_ACTION = "match.confirm"
+SIDE_NOTES = 3
+
+
+def review_id(kind: str, key: str) -> str:
+    return "rq_" + ids.digest("review", kind, key)[:26]
+
+
+def _entity_side(nb: Any, eid: str) -> Dict[str, Any]:
+    s = nb.store
+    row = s.entity_row(eid)
+    members = s.merged_members(eid)
+    q = ",".join("?" for _ in members)
+    notes = [r[0] for r in s.q(f"SELECT en.note_id FROM entity_notes en JOIN notes n ON n.note_id=en.note_id WHERE"
+                               f" en.entity_id IN ({q}) AND n.archived_at IS NULL GROUP BY en.note_id"
+                               f" ORDER BY MAX(en.at) DESC LIMIT ?", [*members, SIDE_NOTES])]
+    return {"type": "entity", "id": eid, "name": row["name"] if row else eid, "kind": row["kind"] if row else None,
+            "note_ids": notes}
+
+
+def _claim_side(nb: Any, row: Any) -> Dict[str, Any]:
+    from .changes import claim_text
+
+    return {"type": "claim", "id": row["claim_id"], "name": claim_text(nb, row), "kind": None,
+            "note_ids": [row["note_id"]] if row["note_id"] else []}
+
+
+def _evidence(first: Optional[str], sides: List[Dict[str, Any]]) -> List[str]:
+    out: List[str] = []
+    for nid in [first, *[n for side in sides for n in side["note_ids"]]]:
+        if nid and nid not in out:
+            out.append(nid)
+    return out
+
+
+def _act(action: str, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+    return {"action": action, "method": "POST", "path": path, "body": body}
+
+
+def _confirmed(nb: Any) -> set:
+    return {r[0] for r in nb.store.q("SELECT target FROM revisions WHERE action=? AND applied_index=1",
+                                     (CONFIRM_ACTION,))}
+
+
+def _close_matches(nb: Any) -> List[Dict[str, Any]]:
+    s = nb.store
+    out = []
+    for r in s.q("SELECT * FROM claims WHERE predicate=? AND status='active' AND object_id IS NOT NULL"
+                 " ORDER BY recorded_at DESC, claim_id", (CLOSE_MATCH,)):
+        a, b = s.canonical(r["subject_id"]), s.canonical(r["object_id"])
+        if a == b:
+            continue  # joined since: nothing left to decide
+        rid = review_id("close_match", r["claim_id"])
+        sides = [_entity_side(nb, a), _entity_side(nb, b)]
+        out.append({
+            "review_id": rid, "kind": "close_match", "why": "unsure_match", "reason": None, "at": r["recorded_at"],
+            "sides": sides, "evidence_note_ids": _evidence(r["note_id"], sides),
+            "actions": [_act("confirm", f"/note/review/{rid}/confirm", {}),
+                        _act("keep_apart", f"/note/claims/{r['claim_id']}/retract", {"reason": None})],
+            "_target": {"claim_id": r["claim_id"], "from_id": a, "into_id": b},
+        })
+    return out
+
+
+def _merges(nb: Any, confirmed: set) -> List[Dict[str, Any]]:
+    s = nb.store
+    out = []
+    for m in s.q("SELECT m.*, r.recorded_at, r.note_id AS cause_note_id, r.action FROM merges m JOIN revisions r ON"
+                 " r.revision_id=m.revision_id WHERE m.undone_at IS NULL AND r.applied_index=1"
+                 " ORDER BY r.recorded_at DESC, m.from_id"):
+        if m["action"] == CONFIRM_ACTION:
+            continue  # a merge you made here needs no review
+        row = s.entity_row(m["from_id"])
+        if row is None or row["merged_into"] != m["into_id"]:
+            continue  # merged elsewhere since
+        rid = review_id("merge", f"{m['from_id']}|{m['into_id']}|{m['revision_id']}")
+        if rid in confirmed:
+            continue
+        sides = [_entity_side(nb, m["from_id"]), _entity_side(nb, m["into_id"])]
+        out.append({
+            "review_id": rid, "kind": "merge", "why": "merged_by_model", "reason": m["reason"] or None,
+            "at": m["recorded_at"], "sides": sides, "evidence_note_ids": _evidence(m["cause_note_id"], sides),
+            "actions": [_act("confirm", f"/note/review/{rid}/confirm", {}),
+                        _act("unmerge", f"/note/entities/{m['into_id']}/unmerge",
+                             {"from_id": m["from_id"], "reason": ""})],
+            "_target": {"from_id": m["from_id"], "into_id": m["into_id"], "revision_id": m["revision_id"]},
+        })
+    return out
+
+
+def _contradictions(nb: Any) -> List[Dict[str, Any]]:
+    s = nb.store
+    out = []
+    seen = set()
+    for r in s.q("SELECT * FROM claims WHERE status='active' AND disputed_with_json!='[]'"
+                 " ORDER BY recorded_at DESC, claim_id"):
+        for other in _uj(r["disputed_with_json"], []) or []:
+            pair = tuple(sorted((r["claim_id"], other)))
+            if pair in seen:
+                continue
+            o = s.claim_row(other)
+            if o is None or o["status"] != "active":
+                continue
+            seen.add(pair)
+            first, second = sorted((r, o), key=lambda x: (x["observed_at"], x["claim_id"]))
+            rid = review_id("contradiction", "|".join(pair))
+            sides = [_claim_side(nb, first), _claim_side(nb, second)]
+            out.append({
+                "review_id": rid, "kind": "contradiction", "why": "disputed_pair", "reason": None,
+                "at": max(r["recorded_at"], o["recorded_at"]), "sides": sides,
+                "evidence_note_ids": _evidence(second["note_id"], sides),
+                "actions": [_act("retract", f"/note/claims/{side['id']}/retract", {"reason": None}) for side in sides],
+                "_target": {"claim_ids": list(pair)},
+            })
+    return out
+
+
+def _all(nb: Any) -> List[Dict[str, Any]]:
+    items = _close_matches(nb) + _merges(nb, _confirmed(nb)) + _contradictions(nb)
+    items.sort(key=lambda it: (it["at"] or "", it["review_id"]), reverse=True)
+    return items
+
+
+def _public(item: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in item.items() if not k.startswith("_")}
+
+
+def review(nb: Any, limit: int = 50) -> Dict[str, Any]:
+    """``{items: [ReviewItem], next_cursor: null}``, newest first (docs/api.md, ``GET /note/review``)."""
+    return {"items": [_public(it) for it in _all(nb)[: clamp_limit(limit, 50, 500)]], "next_cursor": None}
+
+
+def review_item(nb: Any, rid: str) -> Optional[Dict[str, Any]]:
+    for it in _all(nb):
+        if it["review_id"] == rid:
+            return it
+    return None
+
+
+def confirm(nb: Any, rid: str, account: Optional[str], *, client: str = "web",
+            occurred_at: Optional[str] = None) -> Dict[str, Any]:
+    """Confirm a proposed match: a user-action revision ``match.confirm`` targeting the review id."""
+    item = review_item(nb, rid)
+    if item is None:
+        raise ValueError("That match is not waiting for review.")
+    s = nb.store
+    at = ids.normalize_time(occurred_at) if occurred_at else ids.utc_now()
+    target = item["_target"]
+    names = [side["name"] for side in item["sides"]]
+    if item["kind"] == "close_match":
+        ops = [{"op": "entity.merge", "payload": {"from_id": target["from_id"], "into_id": target["into_id"],
+                                                  "reason": "You confirmed they are the same."}},
+               {"op": "claim.supersede", "payload": {"claim_id": target["claim_id"], "by_claim_id": None,
+                                                     "reason": "confirmed as the same", "valid_until": at}}]
+        summary = f"Joined {names[0]} into {names[1]}: you confirmed they are the same."
+    elif item["kind"] == "merge":
+        if s.entity_row(target["from_id"])["merged_into"] != target["into_id"]:
+            raise ValueError("That match is not waiting for review.")
+        ops = []
+        summary = f"You confirmed that {names[0]} and {names[1]} are the same."
+    else:
+        raise ValueError("A disagreement is settled by retracting one of its two statements.")
+    out = nb._user_revision(CONFIRM_ACTION, rid, ops, account, summary, client=client, occurred_at=at)
+    return {**out, "review_id": rid}

abstractnote/recall/search.py

@@ -0,0 +1,205 @@
+"""Quick recall (``note_search``): full-text (FTS5 BM25) plus vector cosine, fused by reciprocal rank.
+
+Runs over notes, entities and claims with filters (since/until on history
+time, kinds, entities, topics) and ``as_of`` (only what existed by then), and
+returns facets by kind, topic, entity and month. No model is called; a query
+vector is one embedder call (none with the hashing embedder's local vectors).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence
+
+from .. import ids
+from ..store.embeddings import top_k, vector_key
+from ..store.notes import clamp_limit, fts_terms
+from . import shapes
+
+RRF_K = 60
+POOL = 200
+NOTE_VECTOR_MIN = 0.2
+ENTITY_LIMIT = 10
+CLAIM_LIMIT = 10
+
+
+def _rrf(*ranked: Sequence[str]) -> Dict[str, float]:
+    scores: Dict[str, float] = {}
+    for lst in ranked:
+        for rank, key in enumerate(lst):
+            scores[key] = scores.get(key, 0.0) + 1.0 / (RRF_K + rank + 1)
+    return scores
+
+
+def _list(value: Any) -> List[str]:
+    if value in (None, "", []):
+        return []
+    if isinstance(value, str):
+        return [v.strip() for v in value.split(",") if v.strip()]
+    return [str(v) for v in value if str(v).strip()]
+
+
+def search(nb: Any, query: str = "", *, since: Optional[str] = None, until: Optional[str] = None,
+           kinds: Any = None, entities: Any = None, topics: Any = None, limit: int = 20,
+           as_of: Optional[str] = None) -> Dict[str, Any]:
+    limit = clamp_limit(limit, 20, 200)
+    query = str(query or "").strip()
+    since_n = ids.optional_time(since, field="since")
+    until_n = ids.optional_time(until, field="until")
+    as_of_n = ids.optional_time(as_of, field="as_of")
+    kinds_l, topics_l = _list(kinds), [t.lstrip("#").lower() for t in _list(topics)]
+    entity_l = _list(entities)
+    store = nb.store
+
+    # ---------------------------------------------------------------- note filter (SQL)
+    where = ["n.archived_at IS NULL"]
+    params: List[Any] = []
+    if since_n:
+        where.append("n.occurred_at>=?")
+        params.append(since_n)
+    bound = min(x for x in (until_n, as_of_n) if x) if (until_n or as_of_n) else None
+    if bound:
+        where.append("n.occurred_at<=?")
+        params.append(bound)
+    if kinds_l:
+        where.append(f"n.kind IN ({','.join('?' for _ in kinds_l)})")
+        params += kinds_l
+    if topics_l:
+        where.append(f"n.note_id IN (SELECT note_id FROM note_topics WHERE topic IN ({','.join('?' for _ in topics_l)}))")
+        params += topics_l
+    if entity_l:
+        members: List[str] = []
+        for e in entity_l:
+            members += store.merged_members(store.canonical(e))
+        where.append(f"n.note_id IN (SELECT note_id FROM entity_notes WHERE entity_id IN ({','.join('?' for _ in members)}))")
+        params += members
+    cond = " AND ".join(where)
+
+    terms = fts_terms(query)
+    fts_notes: List[str] = []
+    snippets: Dict[str, str] = {}
+    if terms:
+        for r in store.q(
+                f"SELECT f.note_id, snippet(notes_fts, 2, '', '', '…', 24) AS snip FROM notes_fts f JOIN notes n"
+                f" ON n.note_id=f.note_id WHERE notes_fts MATCH ? AND {cond} ORDER BY bm25(notes_fts) LIMIT ?",
+                [terms, *params, POOL]):
+            fts_notes.append(r[0])
+            snippets[r[0]] = r[1]
+    warnings: List[str] = []
+    qvec = None
+    if query:
+        if nb.cache.embedder is None and nb.cache.get(vector_key(query, nb.cache.model_id)) is None:
+            warnings.append(nb.cache.missing_embedder + " These results match the words only.")
+        else:
+            qvec = nb.cache.embed_query(query)
+    vec_notes: List[str] = []
+    vec_score: Dict[str, float] = {}
+    if qvec is not None:
+        filtered = len(params) > 0
+        allowed = {r[0] for r in store.q(f"SELECT n.note_id FROM notes n WHERE {cond}", params)} if filtered else None
+        archived = set() if filtered else {r[0] for r in store.q("SELECT note_id FROM notes WHERE archived_at IS NOT NULL")}
+        for nid, s in nb.note_vectors.nearest(qvec, POOL, NOTE_VECTOR_MIN, allowed=allowed, exclude=archived):
+            vec_notes.append(nid)
+            vec_score[nid] = s
+    if query:
+        fused = _rrf(fts_notes, vec_notes)
+        order = sorted(fused, key=lambda k: (-fused[k], k))
+    else:
+        order = [r[0] for r in store.q(f"SELECT n.note_id FROM notes n WHERE {cond} ORDER BY n.occurred_at DESC LIMIT ?",
+                                       [*params, POOL])]
+        fused = {k: 0.0 for k in order}
+    fts_set, vec_set = set(fts_notes), set(vec_notes)
+    note_items = []
+    facet_kind: Dict[str, int] = {}
+    facet_topic: Dict[str, int] = {}
+    facet_entity: Dict[str, int] = {}
+    facet_month: Dict[str, int] = {}
+    for i, nid in enumerate(order):
+        row = store.note_row(nid)
+        if row is None:
+            continue
+        k = row["kind"] or "unfiled"
+        facet_kind[k] = facet_kind.get(k, 0) + 1
+        facet_month[row["occurred_at"][:7]] = facet_month.get(row["occurred_at"][:7], 0) + 1
+        note_topics = store.note_topics(nid)
+        for t in note_topics:
+            facet_topic[t] = facet_topic.get(t, 0) + 1
+        ents = sorted({store.canonical(r[0]) for r in store.q("SELECT entity_id FROM entity_notes WHERE note_id=?",
+                                                               (nid,))})
+        for e in ents:
+            facet_entity[e] = facet_entity.get(e, 0) + 1
+        if len(note_items) < limit:
+            item = shapes.note_ref(row)
+            if snippets.get(nid):
+                item["excerpt"] = " ".join(snippets[nid].split())
+            item.update({"score": round(fused[nid], 6), "matched_by": [m for m, s in (("fts", fts_set), ("vector", vec_set))
+                                                                         if nid in s],
+                         "topics": note_topics, "entity_ids": ents, "insight_kind": row["insight_kind"]})
+            note_items.append(item)
+
+    # ---------------------------------------------------------------- entities
+    ent_items: List[Dict[str, Any]] = []
+    if query:
+        e_cond = "e.merged_into IS NULL"
+        e_params: List[Any] = []
+        if as_of_n:
+            e_cond += " AND COALESCE(e.first_seen, e.created_at)<=?"
+            e_params.append(as_of_n)
+        fts_e = [r[0] for r in store.q(
+            f"SELECT f.entity_id FROM entities_fts f JOIN entities e ON e.entity_id=f.entity_id WHERE entities_fts MATCH ?"
+            f" AND {e_cond} ORDER BY bm25(entities_fts) LIMIT ?", [terms, *e_params, POOL])] if terms else []
+        vec_e: List[str] = []
+        if qvec is not None:
+            rows = store.q(f"SELECT e.entity_id, v.vector FROM entities e JOIN vectors v ON v.vector_key=e.vector_key"
+                           f" WHERE {e_cond}", e_params)
+            vec_e = [e for e, _ in top_k(qvec, [(r[0], r[1]) for r in rows], POOL, NOTE_VECTOR_MIN)]
+        fe = _rrf(fts_e, vec_e)
+        for eid in sorted(fe, key=lambda k: (-fe[k], k))[:ENTITY_LIMIT]:
+            b = store.entity_brief(eid)
+            if b:
+                b.update({"score": round(fe[eid], 6),
+                          "matched_by": [m for m, s in (("fts", set(fts_e)), ("vector", set(vec_e))) if eid in s]})
+                ent_items.append(b)
+
+    # ---------------------------------------------------------------- claims
+    claim_items: List[Dict[str, Any]] = []
+    if query:
+        c_cond = "1=1"
+        c_params: List[Any] = []
+        if as_of_n:
+            c_cond += " AND c.observed_at<=?"
+            c_params.append(as_of_n)
+        if since_n:
+            c_cond += " AND c.observed_at>=?"
+            c_params.append(since_n)
+        if until_n:
+            c_cond += " AND c.observed_at<=?"
+            c_params.append(until_n)
+        fts_c = [r[0] for r in store.q(
+            f"SELECT f.claim_id FROM claims_fts f JOIN claims c ON c.claim_id=f.claim_id WHERE claims_fts MATCH ?"
+            f" AND {c_cond} ORDER BY bm25(claims_fts) LIMIT ?", [terms, *c_params, POOL])] if terms else []
+        vec_c: List[str] = []
+        if qvec is not None:
+            rows = store.q(f"SELECT c.claim_id, v.vector FROM claims c JOIN vectors v ON v.vector_key=c.vector_key"
+                           f" WHERE {c_cond}", c_params)
+            vec_c = [c for c, _ in top_k(qvec, [(r[0], r[1]) for r in rows], POOL, NOTE_VECTOR_MIN)]
+        fc = _rrf(fts_c, vec_c)
+        for cid in sorted(fc, key=lambda k: (-fc[k], k))[:CLAIM_LIMIT]:
+            row = store.claim_row(cid)
+            if row is not None:
+                d = store.claim_dict(row)
+                if as_of_n:
+                    vf, vu = d["valid_from"], d["valid_until"]
+                    d["believed_at_as_of"] = (vf is None or vf <= as_of_n) and (vu is None or vu > as_of_n)
+                d["score"] = round(fc[cid], 6)
+                claim_items.append(d)
+
+    names = {e: store._name(e) for e in facet_entity}
+    facets = {
+        "kinds": [{"kind": k, "count": v} for k, v in sorted(facet_kind.items(), key=lambda x: (-x[1], x[0]))],
+        "topics": [{"topic": k, "count": v} for k, v in sorted(facet_topic.items(), key=lambda x: (-x[1], x[0]))],
+        "entities": [{"entity_id": k, "name": names[k], "count": v}
+                     for k, v in sorted(facet_entity.items(), key=lambda x: (-x[1], x[0]))[:20]],
+        "months": [{"month": k, "count": v} for k, v in sorted(facet_month.items())],
+    }
+    return {"query": query, "as_of": as_of_n, "notes": note_items, "entities": ent_items, "claims": claim_items,
+            "facets": facets, "considered": len(order), "warnings": warnings}

abstractnote/recall/shapes.py

@@ -0,0 +1,52 @@
+"""The pinned response shapes of docs/api.md ("Pinned response shapes"); clients decode them strictly."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from typing import Any, Dict, Optional
+
+EXCERPT_CHARS = 280
+
+
+def excerpt(text: Optional[str], limit: int = EXCERPT_CHARS) -> str:
+    """A list excerpt of a note body (the full text is always available from the note itself)."""
+    t = " ".join(str(text or "").split())
+    return t if len(t) <= limit else t[: limit - 1].rstrip() + "…"
+
+
+def note_ref(r: sqlite3.Row) -> Dict[str, Any]:
+    """``NoteRef``: ``{note_id, title, kind, occurred_at, excerpt}``."""
+    return {"note_id": r["note_id"], "title": r["title"] or "", "kind": r["kind"], "occurred_at": r["occurred_at"],
+            "excerpt": excerpt(r["summary"] or r["one_line"] or r["text"])}
+
+
+def insight(r: sqlite3.Row) -> Dict[str, Any]:
+    """``Insight``: ``{note_id, title, body, insight_kind, occurred_at, acked_at, evidence_note_ids, entity_ids}``."""
+    return {"note_id": r["note_id"], "title": r["title"] or "", "body": r["text"] or "",
+            "insight_kind": r["insight_kind"], "occurred_at": r["occurred_at"], "acked_at": r["acked_at"],
+            "evidence_note_ids": _list(r["evidence_note_ids_json"]), "entity_ids": _list(r["entity_ids_json"])}
+
+
+def insight_facts(r: sqlite3.Row) -> Optional[Dict[str, Any]]:
+    """The ``insight`` field of ``GET /note/notes/{id}``: ``{kind, evidence_note_ids, entity_ids, acked_at}`` for an
+    insight note, ``None`` for any other note."""
+    if not r["insight_kind"]:
+        return None
+    return {"kind": r["insight_kind"], "evidence_note_ids": _list(r["evidence_note_ids_json"]),
+            "entity_ids": _list(r["entity_ids_json"]), "acked_at": r["acked_at"]}
+
+
+def task(r: sqlite3.Row) -> Dict[str, Any]:
+    return {"task_id": r["task_id"], "note_id": r["note_id"], "text": r["text"], "status": r["status"],
+            "due": r["due"], "closed_at": r["closed_at"]}
+
+
+def _list(raw: Optional[str]) -> list:
+    if not raw:
+        return []
+    try:
+        v = json.loads(raw)
+    except ValueError:
+        return []
+    return v if isinstance(v, list) else []

abstractnote/recall/then_now.py

@@ -0,0 +1,100 @@
+"""Then versus now: the earliest and latest understanding of an entity (or a relationship) and the
+turning points between them, each with the note that caused it. Deterministic; cached per entity
+revision count (``then_now_cache``)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from ..store.notes import _uj
+
+
+def _claim_line(c: Dict[str, Any]) -> str:
+    obj = c.get("object_name") or c.get("object_literal") or c.get("object_id")
+    return f"{c.get('subject_name') or c['subject_id']} {c['predicate']} {obj}"
+
+
+def then_now(nb: Any, entity_id: str) -> Dict[str, Any]:
+    s = nb.store
+    if s.entity_row(entity_id) is None:
+        raise ValueError("That entity is not in this notebook.")
+    eid = s.canonical(entity_id)
+    members = s.merged_members(eid)
+    q = ",".join("?" for _ in members)
+    count = int(s.q1(f"SELECT COALESCE(SUM(revision_count), 0) FROM entities WHERE entity_id IN ({q})", members)[0])
+    key = "entity:" + eid
+    cached = s.q1("SELECT revision_count, payload_json FROM then_now_cache WHERE key=?", (key,))
+    if cached is not None and int(cached[0]) == count:
+        return json.loads(cached[1])
+
+    summaries = s.q(f"SELECT * FROM entity_summaries WHERE entity_id IN ({q}) ORDER BY at, revision_id", members)
+    earliest_claims = s.q(f"SELECT * FROM claims WHERE subject_id IN ({q}) OR object_id IN ({q})"
+                          f" ORDER BY observed_at, seq LIMIT 5", [*members, *members])
+    current = [c for c in s.beliefs_at(_now(), entity_id=eid)]
+
+    def summary_point(r: Any) -> Dict[str, Any]:
+        return {"at": r["at"], "summary": r["summary"], "note_id": r["note_id"], "revision_id": r["revision_id"]}
+
+    turning: List[Dict[str, Any]] = []
+    for r in summaries[1:]:
+        turning.append({"at": r["at"], "kind": "summary", "text": r["summary"], "note_id": r["note_id"],
+                        "revision_id": r["revision_id"]})
+    for r in s.q(f"SELECT c.*, v.at AS closed_at, v.note_id AS closing_note FROM claims c JOIN revisions v ON"
+                 f" v.revision_id=c.closed_revision_id WHERE (c.subject_id IN ({q}) OR c.object_id IN ({q}))",
+                 [*members, *members]):
+        d = s.claim_dict(r)
+        turning.append({"at": r["closed_at"], "kind": "retract" if r["status"] == "retracted" else "supersede",
+                        "text": _claim_line(d) + (f" (replaced: {r['closed_reason']})" if r["closed_reason"] else ""),
+                        "claim_id": r["claim_id"], "superseded_by": r["superseded_by"],
+                        "note_id": r["closing_note"], "revision_id": r["closed_revision_id"]})
+    for r in s.q(f"SELECT * FROM claims WHERE (subject_id IN ({q}) OR object_id IN ({q})) AND disputed_with_json!='[]'"
+                 f" AND certainty='disputed'", [*members, *members]):
+        turning.append({"at": r["observed_at"], "kind": "dispute", "text": _claim_line(s.claim_dict(r)),
+                        "claim_id": r["claim_id"], "note_id": r["note_id"], "revision_id": r["revision_id"]})
+    for r in s.q(f"SELECT * FROM merges WHERE from_id IN ({q}) OR into_id IN ({q})", [*members, *members]):
+        turning.append({"at": r["at"], "kind": "merge", "text": f"{r['from_id']} is {r['into_id']}",
+                        "note_id": (s.revision_row(r["revision_id"]) or {"note_id": None})["note_id"],
+                        "revision_id": r["revision_id"]})
+    turning.sort(key=lambda t: (t["at"] or "", t["kind"]))
+    payload = {
+        "entity_id": eid,
+        "earliest": summary_point(summaries[0]) if summaries else None,
+        "latest": summary_point(summaries[-1]) if summaries else None,
+        "earliest_claims": [s.claim_dict(r) for r in earliest_claims],
+        "current_beliefs": current,
+        "turning_points": turning,
+        "revision_count": count,
+    }
+    with s.lock:
+        s.conn.execute("INSERT OR REPLACE INTO then_now_cache(key, revision_count, payload_json) VALUES (?,?,?)",
+                       (key, count, json.dumps(payload, sort_keys=True)))
+    return payload
+
+
+def _now() -> str:
+    from .. import ids
+
+    return ids.utc_now()
+
+
+def relation_then_now(claims: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Then versus now of a link, from its claims in history order (as built by ``expand.relation``)."""
+    if not claims:
+        return {"earliest": [], "latest": [], "turning_points": []}
+    first_at = claims[0]["observed_at"]
+    earliest = [c for c in claims if c["observed_at"] == first_at]
+    latest = [c for c in claims if c["status"] == "active" and c["valid_until"] is None]
+    turning = [{"at": c["closed"]["at"], "kind": c["closed"]["kind"], "claim_id": c["claim_id"],
+                "superseded_by": c["superseded_by"], "note_id": c["closed"]["note_id"],
+                "reason": c["closed"]["reason"]} for c in claims if c.get("closed")]
+    turning += [{"at": c["observed_at"], "kind": "dispute", "claim_id": c["claim_id"], "note_id": c["note_id"],
+                 "disputed_with": c["disputed_with"]} for c in claims if c["certainty"] == "disputed"]
+    turning.sort(key=lambda t: (t["at"] or "", t["kind"]))
+    return {"earliest": [_brief(c) for c in earliest], "latest": [_brief(c) for c in latest],
+            "turning_points": turning}
+
+
+def _brief(c: Dict[str, Any]) -> Dict[str, Any]:
+    return {"claim_id": c["claim_id"], "text": _claim_line(c), "observed_at": c["observed_at"],
+            "note_id": c["note_id"], "certainty": c["certainty"]}

abstractnote/store/__init__.py

@@ -0,0 +1,12 @@
+"""Storage: the note index, the AbstractMemory projection, embeddings, the queue and ``Notebook``."""
+
+from .embeddings import HashingEmbedder, TextEmbedder, VectorCache, gateway_embedder, openai_compat_embedder
+from .kg import ClaimStore
+from .notebook import Notebook
+from .notes import NoteStore
+from .queue import Queue
+
+__all__ = [
+    "ClaimStore", "HashingEmbedder", "NoteStore", "Notebook", "Queue", "TextEmbedder", "VectorCache",
+    "gateway_embedder", "openai_compat_embedder",
+]