Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
account, which reads the calendars shared with it or, in Google Workspace, a user's calendars through domain-wide
delegation. Calls to Google show in the activity ledger
([Google Calendar](docs/processing.md#email-imap-calendar-feeds-ical-and-google-calendar)).
- **Find a note.** The Notes page has a search box that finds notes by the words in their title, summary or text (the
pages of recordings and entities too), with the words around each match marked, and Enter opens the first. A filter
shows only Projects, Areas, Resources or Archive, and each note says which notes it's inside. Jump to (⌘K) finds notes
as well. `GET /api/v1/notes/search`; `find_notes` gives agents the words around each match
([Finding notes](docs/notes.md#finding-notes)).

## 0.10.0 <small>October 15, 2026</small> {id="0.10.0"}

Expand Down
4 changes: 4 additions & 0 deletions ci/clicks/journeys.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -670,6 +670,10 @@ export const JOURNEYS = [
from: "/",
async run(ctx) {
const { page, meter } = ctx;
// An entity is in the graph once something links it twice (graph.min_edge_weight), which takes import-file's
// pi-episode as well; a slow machine can still be reading it here, so wait for the jobs to finish (not counted)
const idle = page.getByRole("button", { name: /^Activity: (Nothing running|\d+ failed)$/ });
await madeInBackground(ctx, "/", idle, "/", "the imports' jobs finished");
await go(ctx, "Graph");
const find = page.getByRole("combobox", { name: "Find in graph" });
await page.getByRole("region", { name: "Graph" }).waitFor();
Expand Down
4 changes: 3 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -628,6 +628,7 @@ deleted.
```
GET /api/v1/notes
POST /api/v1/notes
GET /api/v1/notes/search
GET /api/v1/notes/{pid}
PATCH /api/v1/notes/{pid}
DELETE /api/v1/notes/{pid}
Expand All @@ -642,7 +643,8 @@ DELETE /api/v1/notes/{pid}/files
```

Note pages ([Notes](notes.md)), apart from the notes on a recording above. `GET /notes?ns=` is a namespace's page tree
(`all=true` adds the pages of things). `move` puts a free note inside `parent` before `before`, `history` lists what the
(`all=true` adds the pages of things). `search?q=` finds pages by the words in their title, summary or text, title
matches first, each with the words around the match ([Finding notes](notes.md#finding-notes)). `move` puts a free note inside `parent` before `before`, `history` lists what the
page was before each change, and `restore` puts an earlier version back (what it was becomes a version too). `files`
lists the files and images attached to a page; `blobs` uploads (in chunks) and reads them, and `DELETE …/files?key=`
removes one.
Expand Down
2 changes: 1 addition & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ front of the web app also needs `TRUST_PROXY_HEADERS=true` ([Authentication](aut
| `list_topics` | each namespace's vocabulary of topics ([Topics](topics.md)), by any label, top topics or the narrower ones of a topic |
| `get_topic` | one topic: its labels, definition, broader, narrower and related topics, and the recordings about it, with links |
| `suggest_topic` | suggest that recordings are about a topic; it waits for someone to accept it. Needs a write-scope token and editor access |
| `find_notes` | [notes](notes.md) by words in their title, summary or text, or by where they're filed (PARA), with links |
| `find_notes` | [notes](notes.md) by words in their title, summary or text, or by where they're filed (PARA), with the words around the match and links |
| `read_note` | a note's Markdown with its links and backlinks, by id or as the page of a thing (`recording:12`) |
| `write_note` | write a note or a thing's page, marked as written by an assistant. Needs a write-scope token and editor access |
| `create_podcast` | make a two-host learning [episode](podcasts.md) about recordings or lines in them, with an angle, a length and a style; it's made in the background. Needs a write-scope token and editor access where it goes |
Expand Down
13 changes: 13 additions & 0 deletions docs/notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,19 @@ refining it, or someone else always starts a new one. **History** on a page list
it; pick one to read it, and editors can restore it. Restoring keeps the page as it was too, so it can be undone.
`GET /api/v1/notes/{id}/history`, `GET .../history/{version}` and `POST .../history/{version}/restore`.

## Finding notes

The **Notes** page lists the free notes in view, the latest changed first, each with the notes it sits inside
("In Home lab › Parts"), where it's filed and when it changed. The box at the top finds notes by the words in their
title, one-line summary or text, the pages of recordings, entities and topics too: those with the words in the title
come first, each with the words around the match, and Enter opens the first. **Projects**, **Areas**, **Resources** and
**Archive** show only the notes filed there, with how many each has. **Jump to** (⌘K or Ctrl+K) finds notes the same
way, beside recordings, pages and settings.

`GET /api/v1/notes/search?q=&ns=&place=&free=` is the same search, in every namespace you can read unless `ns` names one;
`free=true` leaves out the pages of things. The assistant's and MCP's `find_notes` give the same words around the match
(`snippet`) and the note each is inside (`inside`).

## Access

Pages belong to a namespace: anyone with a role there reads them, editors write, move and delete them. The pages of
Expand Down
6 changes: 4 additions & 2 deletions fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -1452,8 +1452,8 @@ def _note_url(ctx: Context, pid: int) -> str:
"Find notes",
"Notes in the namespaces you can read: free notes and the pages of recordings, entities, topics, collections and "
"speakers, found by words in their title, one-line summary or text (title matches first, then the latest). Each "
"has its id, one-line summary, where it is filed (PARA: project, area, resource, archive), what it is the page of, "
"and a url.",
"has its id, one-line summary, the words around the match in its text, where it is filed (PARA: project, area, "
"resource, archive), the note it is inside, what it is the page of, and a url.",
Arg("query", "string", "words to look for", max_length=200),
Arg("namespace", "string", "only this namespace"),
Arg("place", "string", "only notes filed here", enum=notebook.PLACES),
Expand All @@ -1474,6 +1474,8 @@ def find_notes(ctx: Context, query: str | None, namespace: str | None, place: st
"place": r.get("place"),
"page_of": r.get("about"),
"namespace": names.get(r["space"]),
"inside": r.get("parent"),
"snippet": r.get("snippet"),
"updated": r.get("updated_at"),
"url": _note_url(ctx, r["id"]),
}
Expand Down
25 changes: 25 additions & 0 deletions fastapi_backend/app/api/v1/routes/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
from app.schemas.notebook import (
NoteFile,
NoteHistory,
NoteHit,
NoteHomeSuggestion,
NoteLinkSuggestion,
NoteLinkTarget,
Expand All @@ -33,9 +34,11 @@
NotePageItem,
NotePageMove,
NotePageUpdate,
NoteSearch,
NoteTree,
NoteVersion,
NoteVersionItem,
Place,
)

router = APIRouter(prefix="/notes", tags=["notes"])
Expand Down Expand Up @@ -118,6 +121,28 @@ def link_targets(
return [NoteLinkTarget(**t) for t in notebook.search_targets(db, sid, q, sign, limit)]


@router.get("/search")
def search_pages(
user: CurrentUser,
acl: Acl,
db: Db,
q: str = Query("", max_length=200, description="words in the title, one-line summary or text"),
ns: str | None = Query(None, description="only this namespace (default: every one you can read)"),
place: Place | None = Query(None, description="only notes filed here"),
free: bool = Query(False, description="only free notes, not the pages of things"),
limit: int = Query(50, ge=1, le=200),
) -> NoteSearch:
"""Pages found by their words, those with them in the title first, then the latest changed, each with the words
around the match: what the Notes page and Jump to show, and what the assistant's find_notes reads."""
names = store.space_names(db)
spaces = [acl.namespace(ns)] if ns else (list(names) if user.admin else acl.spaces())
total, hits = notebook.find(db, spaces, q, place, limit, free=free)
return NoteSearch(
total=total,
pages=[NoteHit(**{k: v for k, v in h.items() if k != "space"}, namespace=names.get(h["space"], "")) for h in hits],
)


@router.get("/about/{kind}/{key}")
def page_about(kind: str, key: int, user: CurrentUser, acl: Acl, db: Db) -> NotePage | NotePageDraft:
"""The page of a recording, entity, topic, collection or speaker: its page, or a draft while nobody has written one."""
Expand Down
2 changes: 2 additions & 0 deletions fastapi_backend/app/domain/ai_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -1138,6 +1138,8 @@ def t_find_notes(self, query=None, namespace=None, place=None, limit=10):
"place": r.get("place"),
"page_of": r.get("about"),
"namespace": names.get(r["space"]),
"inside": r.get("parent"),
"snippet": r.get("snippet"),
}
)
for r in hits
Expand Down
31 changes: 27 additions & 4 deletions fastapi_backend/app/domain/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -681,23 +681,46 @@ def labels(db, targets):
return out


def find(db, spaces, query="", place=None, limit=10):
SNIPPET = 160


def snippet(text, query, size=SNIPPET):
"""The words around the first place the text has the query, on one line, with … where it was cut; None without."""
text, q = " ".join(str(text or "").split()), " ".join(str(query or "").split())
at = text.casefold().find(q.casefold()) if q else -1
if at < 0:
return None
start = max(0, at - size // 3)
if start:
cut = text.find(" ", start)
start = cut + 1 if 0 <= cut < at else start
end = min(len(text), start + size)
if end < len(text):
cut = text.rfind(" ", at + len(q), end)
end = cut if cut > 0 else end
return ("…" if start else "") + text[start:end] + ("…" if end < len(text) else "")


def find(db, spaces, query="", place=None, limit=10, free=False):
"""Pages in these namespaces whose title, summary or text has the words, those with them in the title first, then
the latest changed. Returns (how many matched, the first `limit` without their bodies)."""
the latest changed; only free notes with `free`. Returns (how many matched, the first `limit` without their bodies,
each with the words around the match in its text as `snippet`)."""
q = " ".join(str(query or "").split()).casefold()
rows = db.rows(
"SELECT record::id(id) AS id, space, title, summary, place, about, updated_at, text FROM note_page WHERE space IN $s",
"SELECT record::id(id) AS id, space, title, summary, place, parent, about, author, updated_at, text FROM note_page "
"WHERE space IN $s",
s=list(spaces),
)
hits = [
r
for r in rows
if (not place or r.get("place") == place)
and (not free or not r.get("about"))
and (not q or any(q in str(r.get(k) or "").casefold() for k in ("title", "summary", "text")))
]
hits.sort(key=lambda r: r.get("updated_at") or "", reverse=True)
hits.sort(key=lambda r: q not in str(r["title"]).casefold())
return len(hits), [{k: v for k, v in r.items() if k != "text"} for r in hits[:limit]]
return len(hits), [{**{k: v for k, v in r.items() if k != "text"}, "snippet": snippet(r.get("text"), q)} for r in hits[:limit]]


def search_targets(db, sid, q="", sign="@", limit=20):
Expand Down
18 changes: 18 additions & 0 deletions fastapi_backend/app/schemas/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,24 @@ class NoteTree(ResponseModel):
pages: list[NotePageItem]


class NoteHit(ResponseModel):
id: int
title: str
summary: str | None = None
place: Place | None = None
parent: int | None = Field(None, description="the page it's inside, in the tree")
about: str | None = Field(None, description='what this is the page of, like "recording:12"; null for a free note')
author: Literal["person", "assistant"] = "person"
updated_at: str | None = None
namespace: str
snippet: str | None = Field(None, description="the words around the match in its text, when the text has it")


class NoteSearch(ResponseModel):
total: int = Field(description="how many pages match; `pages` has the first `limit`")
pages: list[NoteHit]


class NotePageCreate(RequestModel):
ns: str = Field(description="the namespace it goes in")
title: str = Field(min_length=1, max_length=200)
Expand Down
1 change: 1 addition & 0 deletions fastapi_backend/tests/api/test_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,7 @@ def test_note_tools(client, db, env):
found = tool(client, h, "find_notes", query="capsid")
assert [(n["note_id"], n["summary"], n["place"]) for n in found["notes"]] == [(plan, "Shipping capsids", "project")]
assert found["notes"][0]["url"].endswith(f"/notes/{plan}")
assert tool(client, h, "find_notes", query="friday")["notes"][0]["snippet"] == "Ship on Friday, see ep1."
assert tool(client, h, "find_notes", place="area")["total"] == 0
got = tool(client, h, "read_note", note_id=plan)
assert got["body"].startswith("Ship on Friday") and got["links"] == [{"target": f"recording:{a}", "name": got["links"][0]["name"]}]
Expand Down
34 changes: 34 additions & 0 deletions fastapi_backend/tests/api/test_notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,40 @@ def test_domain_helpers():
assert notebook.plain(body) == "Hi Ada and Caps, Ada twice, x\n\nsite"


def test_search(client, env, db):
he, hv, hx = env["he"], env["hv"], env["hx"]
plans = _new(client, he, title="Plans", place="project", body="Hire two people.")
_new(client, he, title="Hiring", parent=plans["id"], body="We talk to " + "lots of people " * 20 + "about capsids today.")
_new(client, he, title="Old trip", place="archive", body="Lisbon")
r = client.get("/api/v1/notes/search?q=capsids", headers=hv)
assert r.status_code == 200, r.text
out = r.json()
assert out["total"] == 1
hit = out["pages"][0]
assert (hit["title"], hit["parent"], hit["namespace"], hit["author"]) == ("Hiring", plans["id"], "pods", "person")
assert hit["snippet"].startswith("…") and hit["snippet"].endswith("about capsids today.")
# title matches first; a place narrows it; no words: everything, the latest changed first
assert [p["title"] for p in client.get("/api/v1/notes/search?q=hir", headers=hv).json()["pages"]] == ["Hiring", "Plans"]
assert [p["title"] for p in client.get("/api/v1/notes/search?place=archive", headers=hv).json()["pages"]] == ["Old trip"]
assert client.get("/api/v1/notes/search?ns=pods", headers=hv).json()["total"] == 3
# a thing's page is found too, unless only free notes are asked for
_new(client, he, title="Episode 1", about=f"recording:{env['a']}", body="capsids again")
assert client.get("/api/v1/notes/search?q=capsids", headers=hv).json()["total"] == 2
assert client.get("/api/v1/notes/search?q=capsids&free=true", headers=hv).json()["total"] == 1
# people outside the namespace find nothing in it
assert client.get("/api/v1/notes/search?q=capsids", headers=hx).json()["total"] == 0
assert client.get("/api/v1/notes/search?ns=pods", headers=hx).status_code == 404


def test_snippet():
assert notebook.snippet("one two three", "four") is None
assert notebook.snippet("one two three", "") is None
assert notebook.snippet("a short\ntext", "short") == "a short text"
long = " ".join(f"w{i}" for i in range(200))
s = notebook.snippet(long, "w100")
assert s.startswith("…w") and s.endswith("…") and "w100" in s and len(s) <= notebook.SNIPPET + 2


@pytest.fixture
def llm(cfg):
from tests import fake_llm
Expand Down
Loading
Loading