From b875b8ed7866d9d8f462fa04db6e1e6b1b7e0df5 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 4 Oct 2026 14:07:37 +0000 Subject: [PATCH] feat(notes): suggest the project or area a top-level note fits under A free note at the top of the tree gets the project or area page it fits under (links between them, shared links, title words), best first with why, from GET /api/v1/notes/{id}/homes. One click on the note page puts it inside; the assistant sees the same as could_go_in in read_note. No model is asked and nothing moves on its own. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01XZQXJtCvJgbG1Z2H312KcS --- DEVLOG.md | 6 +- docs/notes.md | 9 +- fastapi_backend/app/api/v1/routes/notebook.py | 8 ++ fastapi_backend/app/domain/ai_tools.py | 7 +- fastapi_backend/app/domain/notebook.py | 61 +++++++++++++ fastapi_backend/app/schemas/notebook.py | 8 ++ fastapi_backend/tests/api/test_notebook.py | 39 ++++++++ nextjs-frontend/app/openapi-client/index.ts | 6 ++ nextjs-frontend/app/openapi-client/sdk.gen.ts | 18 ++++ .../app/openapi-client/types.gen.ts | 63 +++++++++++++ .../components/notes/home-suggestions.tsx | 43 +++++++++ .../components/notes/note-page.tsx | 25 ++++++ nextjs-frontend/openapi.json | 90 +++++++++++++++++++ 13 files changed, 378 insertions(+), 5 deletions(-) create mode 100644 nextjs-frontend/components/notes/home-suggestions.tsx diff --git a/DEVLOG.md b/DEVLOG.md index 0b08b8a85..ea3320b7f 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -207,8 +207,10 @@ Todo: suggestion when it isn't sure (ai.organise_notes) - [x] Self-organising: suggested links to the topics and named things a note mentions (no model; one click; the assistant sees them as could_link) -- [ ] Self-organising, next: nest notes under their project or area -- [ ] # topics move to the SKOS topics once the graph thread splits them from entities +- [x] Self-organising: the project or area a top-level note fits under, from shared links and title words (no model; + one click; the assistant sees them as could_go_in) +- [ ] Self-organising, next: nest notes without a click when the fit is clear (decision model, like PARA filing) +- [x] # topics move to the SKOS topics once the graph thread splits them from entities (#135) - [ ] Attachments on a page, encrypted through the keyring - [ ] Object storage (S3, or an rclone remote served as S3) in the setup wizard, no local storage; a downloadable 256-bit storage key. Design proposal waiting on Adeel (changes existing installs) diff --git a/docs/notes.md b/docs/notes.md index c441d37bc..b0a869ff4 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -6,8 +6,8 @@ assistant write. The assistant is the main writer and organiser; people can do e Status: **built**: pages (free notes in a tree, a page per recording, entity, topic, collection or speaker), @ and # links with backlinks (# links topics), the tree in the left navigation, the page view with the BlockSuite editor, the model keeping titles and summaries up to date, assistant tools to find, read, write and update notes, and MCP tools to -find, read and write them ([MCP](mcp.md)), page history with restore, and suggested links to what a note names. -**Planned**: nesting notes under their project or area on their own, attachments on encrypted object storage, pages in the graph. +find, read and write them ([MCP](mcp.md)), page history with restore, suggested links to what a note names, and the project or area a note fits under. +**Planned**: nesting notes under their project or area without a click, attachments on encrypted object storage, pages in the graph. ## A page @@ -66,6 +66,11 @@ takes it when one is set up (Settings → Assistant), else the language model. W note is filed (`place_by: assistant`); otherwise its best guess waits on the note as a suggestion to accept with one click. What a person files is never refiled. +A note at the top of the tree that isn't a project, an area or archived also shows the project or area page it fits +under, with one click to put it inside: the one it links to, that links to it, that links the same topics and things, +or whose title words it uses (`GET /api/v1/notes/{id}/homes`, best first, with why). No model is asked and nothing +moves on its own; the assistant sees the same as `could_go_in` when it reads the note, and moves it with `update_note`. + ## The assistant The chat assistant keeps notes as its notebook: `find_notes`, `read_note`, `write_note` and `update_note` (Settings → diff --git a/fastapi_backend/app/api/v1/routes/notebook.py b/fastapi_backend/app/api/v1/routes/notebook.py index 0349ad86f..96a1ee543 100644 --- a/fastapi_backend/app/api/v1/routes/notebook.py +++ b/fastapi_backend/app/api/v1/routes/notebook.py @@ -16,6 +16,7 @@ from app.schemas.common import Ok from app.schemas.notebook import ( NoteHistory, + NoteHomeSuggestion, NoteLinkSuggestion, NoteLinkTarget, NotePage, @@ -162,6 +163,13 @@ def link_suggestions(pid: int, user: CurrentUser, acl: Acl, db: Db) -> list[Note return [NoteLinkSuggestion(**x) for x in notebook.suggest_links(db, _page(acl, db, pid))] +@router.get("/{pid}/homes") +def home_suggestions(pid: int, user: CurrentUser, acl: Acl, db: Db) -> list[NoteHomeSuggestion]: + """The project or area pages a free note at the top of the tree could go inside, best first, from the links and + words they share; moving it there is one click (POST /{pid}/move). No model is asked.""" + return [NoteHomeSuggestion(**x) for x in notebook.suggest_homes(db, _page(acl, db, pid))] + + def _version_out(db: DB, v: dict[str, Any], cls: type[NoteVersionItem] = NoteVersionItem) -> NoteVersionItem: who = db.one("SELECT email FROM $r", r=store.R("account", v["by"])) if v.get("by") else None return cls(**{**{k: x for k, x in v.items() if k not in ("by", "page", "doc")}, "by": (who or {}).get("email")}) diff --git a/fastapi_backend/app/domain/ai_tools.py b/fastapi_backend/app/domain/ai_tools.py index db24d0b7e..e16724538 100644 --- a/fastapi_backend/app/domain/ai_tools.py +++ b/fastapi_backend/app/domain/ai_tools.py @@ -148,7 +148,7 @@ ( "update_note", "Change a note: its title, summary, place, or its text (body replaces it; append adds to the end). Move a free " - "note in the tree with parent_id (0: the top).", + "note in the tree with parent_id (0: the top); read_note lists could_go_in, the projects and areas it fits under.", { "note_id": _I, "title": _S, @@ -848,6 +848,11 @@ def t_read_note(self, note_id=None, about=None): "links": notebook.links(self.db, p["id"]), "linked_from": [b for b in notebook.backlinks(self.db, p["space"], targets) if b["page"] != p["id"]], "could_link": [f"{x['sign']}[{x['label']}]({x['target']})" for x in notebook.suggest_links(self.db, p)] or None, + "could_go_in": [ + {"parent_id": x["page"], "title": x["title"], "place": x["place"], "why": x["why"]} + for x in notebook.suggest_homes(self.db, p) + ] + or None, } ) return out, f"Read the note {p['title']}" diff --git a/fastapi_backend/app/domain/notebook.py b/fastapi_backend/app/domain/notebook.py index c7270df7f..152477759 100644 --- a/fastapi_backend/app/domain/notebook.py +++ b/fastapi_backend/app/domain/notebook.py @@ -481,6 +481,67 @@ def suggest_links(db, p, limit=SUGGEST_MAX): return out +HOMES = ("project", "area") # where a note can be nested: under a page filed as a project or an area +HOMES_MAX = 3 +_WORD = re.compile(r"[^\W\d_]{4,}") +_GENERIC = {"note", "notes", "page", "pages", "project", "projects", "area", "areas", "plan", "plans", "idea", "ideas"} + + +def _words(text): + from .analyze import STOP + + return {w for w in (x.lower() for x in _WORD.findall(text or "")) if w not in STOP and w not in _GENERIC} + + +def suggest_homes(db, p, limit=HOMES_MAX): + """The project or area pages a free note at the top of the tree could go inside, best first: the ones it links to, + that link to it, that link the same topics and things, or whose title it names. No model is asked, and nothing + moves until someone (or the assistant) moves it. Only unnested notes that aren't projects, areas or archived. + [{page, title, place, score, why}]""" + if p.get("about") or p.get("parent") is not None or p.get("place") in (*HOMES, "archive"): + return [] + sid, pid = p["space"], int(p["id"]) + pages = db.rows("SELECT record::id(id) AS id, title, place, parent FROM note_page WHERE space = $s AND about = NONE", s=sid) + up = {x["id"]: x.get("parent") for x in pages} + + def inside(x): # x is p or somewhere under it + seen = set() + while x is not None and x not in seen: + if x == pid: + return True + seen.add(x) + x = up.get(x) + return False + + homes = {x["id"]: x for x in pages if x.get("place") in HOMES and not inside(x["id"])} + if not homes: + return [] + mine = {f"{k}:{i}" for _, k, i, _ in mentions(p.get("body"))} + theirs = {} + for r in db.rows("SELECT page, target, label FROM note_link WHERE space = $s AND page IN $h", s=sid, h=list(homes)): + theirs.setdefault(r["page"], {})[r["target"]] = r["label"] + text = _words(f"{p.get('title') or ''} {plain(MENTION.sub(' ', p.get('body') or ''))[:SUGGEST_CHARS]}") # links count once, as links + out = [] + for hid, h in homes.items(): + links, score, why = theirs.get(hid, {}), 0, [] + if f"page:{hid}" in mine: + score, why = score + 3, why + ["it links to this page"] + if f"page:{pid}" in links: + score, why = score + 2, why + ["this page links to it"] + shared = sorted(t for t in mine & set(links) if not t.startswith("page:")) + if shared: + score += len(shared) + why.append("both link " + ", ".join(links[t] for t in shared[:3])) + named = _words(h["title"]) & text + if named: + score += min(len(named), 2) + why.append("it names " + ", ".join(sorted(named)[:3])) + if score >= 2: + out.append({"page": hid, "title": h["title"], "place": h["place"], "score": score, "why": why}) + out.sort(key=lambda x: (-x["score"], HOMES.index(x["place"]), x["page"])) + return out[:limit] + + def backlinks(db, sid, targets): """The pages of namespace `sid` that link to any of these targets ("page:3", "recording:12"): [{page, title}].""" rows = db.rows( diff --git a/fastapi_backend/app/schemas/notebook.py b/fastapi_backend/app/schemas/notebook.py index 2f0e6df33..7ee253bea 100644 --- a/fastapi_backend/app/schemas/notebook.py +++ b/fastapi_backend/app/schemas/notebook.py @@ -134,3 +134,11 @@ class NoteLinkTarget(ResponseModel): class NoteLinkSuggestion(NoteLinkTarget): sign: Sign = Field(description="# for a topic, @ for anything else") + + +class NoteHomeSuggestion(ResponseModel): + page: int = Field(description="the project or area page it could go inside") + title: str + place: Literal["project", "area"] + score: int + why: list[str] = Field(description="what ties them: links between them, links they share, words of its title") diff --git a/fastapi_backend/tests/api/test_notebook.py b/fastapi_backend/tests/api/test_notebook.py index 564060765..646c5bc14 100644 --- a/fastapi_backend/tests/api/test_notebook.py +++ b/fastapi_backend/tests/api/test_notebook.py @@ -348,3 +348,42 @@ def test_link_suggestions(client, env, db, cfg): out = json.loads(box.call("read_note", {"note_id": p["id"]})[0]) assert out["could_link"] == [f"@[Ada Lovelace](entity:{ada['id']})", f"#[Capsid design](topic:{caps})"] assert client.get(f"/api/v1/notes/{_new(client, he, title='Empty')['id']}/suggestions", headers=he).json() == [] + + +def test_home_suggestions(client, env, db, cfg): + from app.domain import ai_tools + + he, hv = env["he"], env["hv"] + pods = store.ns_id(db, "pods") + ada, acme = _entity(db, "Ada Lovelace", "PERSON"), _entity(db, "Acme", "ORG") + launch = _new(client, he, title="Capsid launch", place="project", body=f"@[Acme](entity:{acme['id']}) and @[Ada](entity:{ada['id']})") + health = _new(client, he, title="Health", place="area") + _new(client, he, title="Reading list", place="resource", body=f"@[Acme](entity:{acme['id']})") # not a project or area + old = _new(client, he, title="Capsid launch retro", place="archive") + homes = lambda pid, h=hv: client.get(f"/api/v1/notes/{pid}/homes", headers=h).json() # noqa: E731 + + # it links what the project links, and names the project's title: the project first, with why + p = _new(client, he, title="Call with Acme", body=f"About the capsid launch. @[Acme](entity:{acme['id']}) is in.") + got = homes(p["id"]) + assert [(x["page"], x["place"]) for x in got] == [(launch["id"], "project")] + assert got[0]["score"] == 3 and got[0]["why"] == ["both link Acme", "it names capsid, launch"] + # a link to an area page is enough on its own + q = _new(client, he, title="Sleep", body=f"See @[Health](page:{health['id']}).") + assert [x["page"] for x in homes(q["id"])] == [health["id"]] + # one shared word isn't enough; nothing in common, nothing suggested + assert homes(_new(client, he, title="Launch party")["id"]) == [] + assert homes(_new(client, he, title="Groceries", body="milk")["id"]) == [] + # nested, filed as a project or area, archived, or a thing's page: none + client.post(f"/api/v1/notes/{p['id']}/move", headers=he, json={"parent": launch["id"]}) + assert homes(p["id"]) == [] + assert homes(launch["id"]) == [] and homes(old["id"]) == [] + # a project can't be suggested as a home for a page it sits inside + client.post(f"/api/v1/notes/{launch['id']}/move", headers=he, json={"parent": q["id"]}) + assert [x["page"] for x in homes(q["id"])] == [health["id"]] + # the assistant sees them when it reads the note, and moves it with update_note + uid = db.one("SELECT record::id(id) AS id FROM account WHERE email = 'ed@x.io'")["id"] + box = ai_tools.Toolbox(db, cfg, {"id": uid, "email": "ed@x.io"}, {pods}, {pods}, {}, None) + import json + + out = json.loads(box.call("read_note", {"note_id": q["id"]})[0]) + assert out["could_go_in"] == [{"parent_id": health["id"], "title": "Health", "place": "area", "why": ["it links to this page"]}] diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index 1ac6a40c1..619ec1b87 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -1131,6 +1131,11 @@ export type { Highlight, HighlightCreate, HighlightUpdate, + HomeSuggestionsData, + HomeSuggestionsError, + HomeSuggestionsErrors, + HomeSuggestionsResponse, + HomeSuggestionsResponses, HttpValidationError, HubLogin, HubLoginCreate, @@ -1630,6 +1635,7 @@ export type { NoteBacklink, NoteCreate, NoteHistory, + NoteHomeSuggestion, NoteLink, NoteLinkSuggestion, NoteLinkTarget, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 92139dee9..8f12230e8 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -567,6 +567,9 @@ import type { HideEntityData, HideEntityErrors, HideEntityResponses, + HomeSuggestionsData, + HomeSuggestionsErrors, + HomeSuggestionsResponses, ImportFromSourceData, ImportFromSourceErrors, ImportFromSourceResponses, @@ -3853,6 +3856,21 @@ export class Notes { }); } + /** + * Home Suggestions + * + * The project or area pages a free note at the top of the tree could go inside, best first, from the links and + * words they share; moving it there is one click (POST /{pid}/move). No model is asked. + */ + public static homeSuggestions( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/notes/{pid}/homes", + ...options, + }); + } + /** * Page History * diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index a9d1b606f..94bedc6da 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -7200,6 +7200,37 @@ export type NoteHistory = { [key: string]: unknown; }; +/** + * NoteHomeSuggestion + */ +export type NoteHomeSuggestion = { + /** + * Page + * + * the project or area page it could go inside + */ + page: number; + /** + * Title + */ + title: string; + /** + * Place + */ + place: "project" | "area"; + /** + * Score + */ + score: number; + /** + * Why + * + * what ties them: links between them, links they share, words of its title + */ + why: Array; + [key: string]: unknown; +}; + /** * NoteLink */ @@ -20179,6 +20210,38 @@ export type LinkSuggestionsResponses = { export type LinkSuggestionsResponse = LinkSuggestionsResponses[keyof LinkSuggestionsResponses]; +export type HomeSuggestionsData = { + body?: never; + path: { + /** + * Pid + */ + pid: number; + }; + query?: never; + url: "/api/v1/notes/{pid}/homes"; +}; + +export type HomeSuggestionsErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type HomeSuggestionsError = HomeSuggestionsErrors[keyof HomeSuggestionsErrors]; + +export type HomeSuggestionsResponses = { + /** + * Response Notes-Home Suggestions + * + * Successful Response + */ + 200: Array; +}; + +export type HomeSuggestionsResponse = HomeSuggestionsResponses[keyof HomeSuggestionsResponses]; + export type PageHistoryData = { body?: never; path: { diff --git a/nextjs-frontend/components/notes/home-suggestions.tsx b/nextjs-frontend/components/notes/home-suggestions.tsx new file mode 100644 index 000000000..2a23fdff7 --- /dev/null +++ b/nextjs-frontend/components/notes/home-suggestions.tsx @@ -0,0 +1,43 @@ +"use client"; + +import { useQuery } from "@tanstack/react-query"; +import { FolderInput } from "lucide-react"; + +import { Notes } from "@/app/openapi-client"; +import type { NoteHomeSuggestion } from "@/app/openapi-client/types.gen"; +import { data, useApiClient } from "@/lib/api/browser"; + +/** The project or area a note at the top of the tree fits under (from the links and words they share): one click + * puts it there. Found without a model; nothing moves on its own. */ +export function HomeSuggestion({ + pid, + version, + onMove, + busy, +}: { + pid: number; + version: string | null | undefined; + onMove: (s: NoteHomeSuggestion) => void; + busy: boolean; +}) { + const client = useApiClient(); + const q = useQuery({ + queryKey: ["note-homes", pid, version], + queryFn: () => data(Notes.homeSuggestions({ client, path: { pid } })), + staleTime: 30_000, + }); + const best = q.data?.[0]; + if (!best) return null; + return ( + + ); +} diff --git a/nextjs-frontend/components/notes/note-page.tsx b/nextjs-frontend/components/notes/note-page.tsx index 3e0d48309..8bc14ed47 100644 --- a/nextjs-frontend/components/notes/note-page.tsx +++ b/nextjs-frontend/components/notes/note-page.tsx @@ -11,6 +11,7 @@ import { Notes } from "@/app/openapi-client"; import type { NotePage as Page, NotePageDraft as PageDraft } from "@/app/openapi-client/types.gen"; import { ActivityPanel } from "@/components/costs/costs"; import type { EditorChange, LinkTarget } from "@/components/notes/block-editor"; +import { HomeSuggestion } from "@/components/notes/home-suggestions"; import { LinkSuggestions } from "@/components/notes/link-suggestions"; import { NoteHistory } from "@/components/notes/note-history"; import { PLACES, hrefFor } from "@/components/notes/links"; @@ -298,6 +299,30 @@ export function NotePage({ id, about }: { id?: number; about?: string }) { File under {PLACES.find((x) => x.value === saved.place_suggestion!.place)?.label} )} + {canEdit && saved && !saved.about && saved.parent == null && ( + { + setLinking(true); + try { + await flush(); + const out = await data(Notes.movePage({ client, path: { pid: saved.id }, body: { parent: s.page } })); + qc.setQueryData(key, out); + qc.invalidateQueries({ queryKey: ["notes-tree"] }); + } catch (err) { + toast({ + title: "Couldn’t move it", + body: err instanceof ApiError ? err.message : "Please try again.", + tone: "red", + }); + } finally { + setLinking(false); + } + }} + /> + )} {saved?.updated_at && Changed {shortDate(saved.updated_at)}}
diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 9d5fda4c0..57e22aaee 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -7361,6 +7361,53 @@ } } }, + "/api/v1/notes/{pid}/homes": { + "get": { + "tags": [ + "notes" + ], + "summary": "Home Suggestions", + "description": "The project or area pages a free note at the top of the tree could go inside, best first, from the links and\nwords they share; moving it there is one click (POST /{pid}/move). No model is asked.", + "operationId": "home_suggestions", + "parameters": [ + { + "name": "pid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Pid" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NoteHomeSuggestion" + }, + "title": "Response Notes-Home Suggestions" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, "/api/v1/notes/{pid}/history": { "get": { "tags": [ @@ -34542,6 +34589,49 @@ ], "title": "NoteHistory" }, + "NoteHomeSuggestion": { + "properties": { + "page": { + "type": "integer", + "title": "Page", + "description": "the project or area page it could go inside" + }, + "title": { + "type": "string", + "title": "Title" + }, + "place": { + "type": "string", + "enum": [ + "project", + "area" + ], + "title": "Place" + }, + "score": { + "type": "integer", + "title": "Score" + }, + "why": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Why", + "description": "what ties them: links between them, links they share, words of its title" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "page", + "title", + "place", + "score", + "why" + ], + "title": "NoteHomeSuggestion" + }, "NoteLink": { "properties": { "sign": {