From 81d0f8def537b765fd4d2786a0992d5ae7db332e Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 4 Oct 2026 10:09:15 +0000 Subject: [PATCH] feat(notes): keep note titles and summaries up to date with the model A note whose title or text changed is refined once nobody has touched it for two minutes: the model rewrites its one-line summary, and its title when that is empty, Untitled or no longer fits. On by default, switched off in Settings > Assistant (ai.refine_notes). Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01XZQXJtCvJgbG1Z2H312KcS --- DEVLOG.md | 9 ++- docs/notes.md | 15 +++- fastapi_backend/app/domain/notebook.py | 80 +++++++++++++++++++ fastapi_backend/app/domain/routines.py | 17 +++- fastapi_backend/app/domain/store.py | 2 + fastapi_backend/tests/api/test_notebook.py | 48 +++++++++++ fastapi_backend/tests/fake_llm.py | 6 ++ .../components/settings/bodies.tsx | 1 + nextjs-frontend/components/settings/model.ts | 7 ++ 9 files changed, 177 insertions(+), 8 deletions(-) diff --git a/DEVLOG.md b/DEVLOG.md index 121a31793..22d61f76a 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -41,11 +41,12 @@ Todo: - [x] Pages: create, read, change, move in the tree, delete; a page per resource made on first open - [x] @ and # mentions: links and backlinks, a search to pick what to link -- [ ] Web app: tree explorer in the left navigation, page view with title, summary, date, place and backlinks; the +- [x] Web app: tree explorer in the left navigation, page view with title, summary, date, place and backlinks; the page of a recording or entity reached from its detail view -- [ ] Editor: BlockSuite (AFFiNE's block editor, OctoBase/Yjs documents) behind one component; plain text kept for - search and the assistant. Waits on Adeel's link for the exact editor -- [ ] AI title and summary refinement (notes.refine, on by default, can be switched off); costs to the activity ledger +- [x] Editor: BlockSuite (AFFiNE's block editor on Yjs documents, what OctoBase stores) behind one component; plain + text kept for search and the assistant +- [x] AI title and summary refinement (ai.refine_notes, on by default, can be switched off) +- [ ] Costs of refinement to the activity ledger (once "Activity history and budgets" lands) - [ ] Assistant and MCP tools: find, read, write, link and file notes; changes by the assistant are undoable - [ ] Self-organising: a routine files notes into PARA and links them to entities and topics, proposing what it isn't sure of diff --git a/docs/notes.md b/docs/notes.md index 6a1451f0c..891408371 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -3,9 +3,9 @@ Every resource, entity and topic in Lens has a page of its own, and next to them sit free notes that people and the assistant write. The assistant is the main writer and organiser; people can do everything it can. -Status: **built**: pages over the API (free notes in a tree, a page per recording, entity, collection or speaker), -@ and # links with backlinks. **In progress**: the tree in the left navigation, the page view and its editor, AI -refinement of titles and summaries. **Planned**: assistant and MCP tools, a routine that files notes (PARA and the +Status: **built**: pages (free notes in a tree, a page per recording, entity, collection or speaker), @ and # links +with backlinks, the tree in the left navigation, the page view with the BlockSuite editor, and the model keeping +titles and summaries up to date. **Planned**: assistant and MCP tools, a routine that files notes (PARA and the ontology), attachments on encrypted object storage, pages in the graph, # links to SKOS topics. ## A page @@ -40,6 +40,15 @@ vocabulary of their own; see [the graph](graph.md)). `GET /api/v1/notes/targets? Links are kept as rows (`note_link`), so every page lists its backlinks; links to things that are gone or that the reader can't see show without a name. +## Titles and summaries + +With **Settings → Assistant → Keep note titles and summaries up to date** (`ai.refine_notes`, on by default), a note +whose title or text changed is sent to the model once nobody has touched it for two minutes. The model rewrites the +one-line summary to fit the whole note, and the title only when it is empty, "Untitled" or no longer fits. A note being +typed is never sent on each keystroke, empty notes are never sent, and nothing is sent without a model configured. The +API and `lens worker` processes run this pass with the routines. Model calls are measured by telemetry; their costs go +to the activity ledger once it exists. + ## Access Pages belong to a namespace: anyone with a role there reads them, editors write, move and delete them. The pages of diff --git a/fastapi_backend/app/domain/notebook.py b/fastapi_backend/app/domain/notebook.py index b8a07aa50..1e45fda53 100644 --- a/fastapi_backend/app/domain/notebook.py +++ b/fastapi_backend/app/domain/notebook.py @@ -215,6 +215,7 @@ def create(db, sid, account, title, body="", summary=None, date=None, place=None "text": plain(body), "doc": _doc(doc), "author": author, + "refine_pending": True, "created_by": account, "updated_by": account, "created_at": t, @@ -253,6 +254,8 @@ def update(db, pid, account, title=None, body=None, summary=UNSET, date=UNSET, p if place is not UNSET: sets.append("place = $place") args["place"] = _place(place) + if title is not None or body is not None: + sets.append("refine_pending = true") if body is not None: sets += ["body = $body", "text = $text"] args["body"] = _body(body) @@ -398,3 +401,80 @@ def follow(db, thing, dst): for p in db.rows("SELECT record::id(id) AS id FROM note_page WHERE about = $a", a=thing): db.q("UPDATE $r SET space = $s, about_key = $k", r=R("note_page", p["id"]), s=dst, k=f"{dst}:{kind}:{key}") db.q("UPDATE note_link SET space = $s WHERE page = $p", s=dst, p=p["id"]) + + +# ---------- refining titles and summaries (ai.refine_notes) ---------- +QUIET_SECONDS = 120 # a page is refined once nobody has changed it for this long +REFINE_BATCH = 5 # pages refined per pass +REFINE_CHARS = 12_000 # of a page's text the model reads +REFINE_SCHEMA = { + "type": "object", + "properties": {"title": {"type": "string"}, "summary": {"type": "string"}}, + "required": ["title", "summary"], +} +REFINE_SYSTEM = ( + "You keep a note's title and its one-line summary true to the whole note. The summary is the context an assistant " + "reads before deciding whether to open the note, so it says what the note holds, specifically, in one sentence of " + "at most 200 characters. Keep the title as it is unless it is empty, 'Untitled' or no longer describes the note; " + "then give a short, specific title of at most 80 characters. Write in the note's language." + ' Reply with JSON: {"title": ..., "summary": ...}.' +) + + +def refine(db, cfg, pid): + """Ask the model for the page's title and summary; saved unless someone changed the page meanwhile. Returns what + changed: {"title"?, "summary"?}.""" + from . import llm + + p = db.one("SELECT record::id(id) AS id, title, summary, text, updated_at FROM $r", r=R("note_page", int(pid))) + if not p: + raise KeyError(pid) + if not (p.get("text") or "").strip(): + db.q("UPDATE $r SET refine_pending = false, refine_claim = NONE", r=R("note_page", p["id"])) + return {} + user = f"Title: {p['title']}\nSummary: {p.get('summary') or '(none)'}\n\nNote:\n{p['text'][:REFINE_CHARS]}" + out = llm.json_out(cfg, REFINE_SYSTEM, user, REFINE_SCHEMA) + title = " ".join(str(out.get("title") or "").split())[:TITLE_MAX] or p["title"] + summary = " ".join(str(out.get("summary") or "").split())[:SUMMARY_MAX] or p.get("summary") + now = db.one("SELECT updated_at FROM $r", r=R("note_page", p["id"])) + if not now or now.get("updated_at") != p.get("updated_at"): + db.q("UPDATE $r SET refine_claim = NONE", r=R("note_page", p["id"])) + return {} # changed while the model was thinking: it's still pending, so a later pass looks again + changed = {k: v for k, v in (("title", title), ("summary", summary)) if v and v != p.get(k)} + sets = ["refine_pending = false", "refine_claim = NONE", "refined_at = $t"] + [f"{k} = ${k}" for k in changed] + if "summary" in changed: + sets.append("summary_by = 'assistant'") + db.q(f"UPDATE $r SET {', '.join(sets)}", r=R("note_page", p["id"]), t=store.now(), **changed) + return changed + + +def refine_due(db, cfg, log=None): + """Refine the pages whose title or text changed since they were last refined and that nobody has touched for a + while (so a page being typed isn't sent on every keystroke). Off with ai.refine_notes, or without a model.""" + from . import llm + + if not cfg["ai"].get("refine_notes", True) or not llm.configured(cfg): + return 0 + t = dt.datetime.now(dt.timezone.utc) + quiet = (t - dt.timedelta(seconds=QUIET_SECONDS)).isoformat(timespec="seconds") + rows = db.rows( + "SELECT record::id(id) AS id, refine_claim FROM note_page WHERE refine_pending = true AND updated_at < $q LIMIT $n", + q=quiet, + n=REFINE_BATCH * 4, + ) + done = 0 + for p in rows: + if done >= REFINE_BATCH: + break + if (p.get("refine_claim") or "") > quiet: + continue # another process took it a moment ago + db.q("UPDATE $r SET refine_claim = $c", r=R("note_page", p["id"]), c=store.now()) + try: + refine(db, cfg, p["id"]) + except Exception as e: # noqa: BLE001 - one page failing doesn't stop the others + if log: + log(f"notes: couldn't refine page {p['id']}: {type(e).__name__}: {e}") + # not again until it changes + db.q("UPDATE $r SET refine_pending = false, refine_claim = NONE", r=R("note_page", p["id"])) + done += 1 + return done diff --git a/fastapi_backend/app/domain/routines.py b/fastapi_backend/app/domain/routines.py index b321fa24a..abe149d91 100644 --- a/fastapi_backend/app/domain/routines.py +++ b/fastapi_backend/app/domain/routines.py @@ -22,7 +22,21 @@ import datetime as dt import threading -from . import fedora, jobs, organize, schedule, semantic, sensor_digests, sensor_patterns, sensors, sources, store, telemetry, workflows +from . import ( + fedora, + jobs, + notebook, + organize, + schedule, + semantic, + sensor_digests, + sensor_patterns, + sensors, + sources, + store, + telemetry, + workflows, +) R = store.R ACTIONS = ("sync", "pipeline", "workflow", "sensors") @@ -524,6 +538,7 @@ def loop(): every(lambda: cfg_fn()["sources"]["check_seconds"], sources.poll_due, "watched folders"), every(lambda: CHECK_SECONDS, run_due, "routines"), every(lambda: cfg_fn()["fedora"]["sync_seconds"], fedora.sync_due, "fedora"), + every(lambda: notebook.QUIET_SECONDS / 2, notebook.refine_due, "notes"), ] diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index 78ae2702a..c0a5c456a 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -239,6 +239,7 @@ def labels(): "ai": { "tools": True, "extensions": True, # tools, skills, hooks and plugins people add (extensions.py) + "refine_notes": True, # the model keeps notes' titles and one-line summaries true to the whole note (notebook.py) "disabled_tools": [], "max_steps": 6, "max_transcript_reads": 20, @@ -899,6 +900,7 @@ def close(self): "DEFINE INDEX IF NOT EXISTS note_page_space ON note_page FIELDS space", "DEFINE INDEX IF NOT EXISTS note_page_parent ON note_page FIELDS parent", "DEFINE INDEX IF NOT EXISTS note_page_about ON note_page FIELDS about_key UNIQUE", + "DEFINE INDEX IF NOT EXISTS note_page_refine ON note_page FIELDS refine_pending", # the links in a page's body (@ and # mentions), for backlinks and the graph "DEFINE TABLE IF NOT EXISTS note_link SCHEMALESS", "DEFINE INDEX IF NOT EXISTS note_link_page ON note_link FIELDS page", diff --git a/fastapi_backend/tests/api/test_notebook.py b/fastapi_backend/tests/api/test_notebook.py index 68f8774fb..c333e26d9 100644 --- a/fastapi_backend/tests/api/test_notebook.py +++ b/fastapi_backend/tests/api/test_notebook.py @@ -155,3 +155,51 @@ def test_domain_helpers(): body = "**Hi** @[Ada](entity:5) and #[Caps](entity:9), @[Ada](entity:5) twice, @[x](nope:1)\n\n- [ ] [site](http://x)" assert notebook.mentions(body) == [("@", "entity", 5, "Ada"), ("#", "entity", 9, "Caps")] assert notebook.plain(body) == "Hi Ada and Caps, Ada twice, x\n\nsite" + + +@pytest.fixture +def llm(cfg): + from tests import fake_llm + + srv, url = fake_llm.start() + cfg["llm"].update(base_url=url, model="fake") + fake_llm.Handler.seen = [] + yield fake_llm.Handler + srv.shutdown() + + +def _age(db, pid, seconds=600): + import datetime as dt + + old = (dt.datetime.now(dt.UTC) - dt.timedelta(seconds=seconds)).isoformat(timespec="seconds") + db.q("UPDATE $r SET updated_at = $t", r=R("note_page", pid), t=old) + + +def test_refining_titles_and_summaries(client, env, db, cfg, llm): + he = env["he"] + p = _new(client, he, title="Untitled", body="Capsid samples ship on Friday.\n\nAlice sends them.") + # nothing happens while someone may still be typing + assert notebook.refine_due(db, cfg) == 0 + _age(db, p["id"]) + assert notebook.refine_due(db, cfg) == 1 + got = client.get(f"/api/v1/notes/{p['id']}", headers=he).json() + assert (got["title"], got["summary"], got["summary_by"]) == ("Capsid plan", "About Capsid samples ship on Friday.", "assistant") + # done until the note changes; a person's title change makes it due again, and their own title stays + assert notebook.refine_due(db, cfg) == 0 + client.patch(f"/api/v1/notes/{p['id']}", headers=he, json={"title": "Shipping"}) + _age(db, p["id"]) + assert notebook.refine_due(db, cfg) == 1 + assert client.get(f"/api/v1/notes/{p['id']}", headers=he).json()["title"] == "Shipping" + # switched off, nothing is sent + client.patch(f"/api/v1/notes/{p['id']}", headers=he, json={"body": "New text"}) + _age(db, p["id"]) + cfg["ai"]["refine_notes"] = False + n = len(llm.seen) + assert notebook.refine_due(db, cfg) == 0 and len(llm.seen) == n + # empty notes aren't sent + cfg["ai"]["refine_notes"] = True + e = _new(client, he, title="Empty") + _age(db, e["id"]) + _age(db, p["id"]) + notebook.refine_due(db, cfg) + assert len(llm.seen) == n + 1 diff --git a/fastapi_backend/tests/fake_llm.py b/fastapi_backend/tests/fake_llm.py index ce9741b0a..96ffc0107 100644 --- a/fastapi_backend/tests/fake_llm.py +++ b/fastapi_backend/tests/fake_llm.py @@ -129,6 +129,12 @@ def do_POST(self): ) elif set(schema.get("properties", {})) == {"names"}: content = json.dumps({"names": Handler.names or ["travel", "Family Trips", "calls"]}) + elif set(schema.get("properties", {})) == {"title", "summary"}: + # a note's title and summary (notebook.refine): the title kept, the first line of the note as its summary + text = body["messages"][-1]["content"] + title = re.search(r"^Title: (.*)$", text, re.M).group(1) + first = text.split("Note:\n", 1)[1].strip().splitlines()[0] + content = json.dumps({"title": "Capsid plan" if title == "Untitled" else title, "summary": f"About {first}"}) elif set(schema.get("properties", {})) == {"choice", "confidence"}: content = json.dumps(Handler.decision or {"choice": schema["properties"]["choice"]["enum"][0], "confidence": 0.9}) elif body.get("response_format"): diff --git a/nextjs-frontend/components/settings/bodies.tsx b/nextjs-frontend/components/settings/bodies.tsx index 6322a5aab..2f84227a0 100644 --- a/nextjs-frontend/components/settings/bodies.tsx +++ b/nextjs-frontend/components/settings/bodies.tsx @@ -951,6 +951,7 @@ function AiBody({ ctx }: { ctx: BodyCtx }) { The assistant uses the model set in LLM provider; it needs one that supports tool calls.

+
Tools
    diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts index ec08d4435..7c77b5046 100644 --- a/nextjs-frontend/components/settings/model.ts +++ b/nextjs-frontend/components/settings/model.ts @@ -613,6 +613,13 @@ export const FIELDS: FieldSpec[] = [ hint: "Without tools, answers use search results only.", }, { section: "ai", key: "disabled_tools", label: "Tools", kind: "checks" }, + { + section: "ai", + key: "refine_notes", + label: "Keep note titles and summaries up to date", + kind: "switch", + hint: "A couple of minutes after a note changes, the model rewrites its one-line summary, and its title when that no longer fits.", + }, { section: "ai", key: "max_steps",