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
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
- **Templates.** Notes inside a namespace's Templates note are templates: **New note from a template…** on the Notes
page and in Jump to starts a note from one, with its text, drawings, files and filing. Any note's menu in the tree can
also **Make a copy** ([Templates](docs/notes.md#templates)).
- **A note says where it is.** Above a note's title, **Notes › namespace ›** each note it's inside, every one a link;
under its text, **Inside this note** lists the notes inside it with **Add a note inside**. The text now starts in line
with the title, the word count shows next to Saved, and Pin, History, Download and Delete are in the note's **⋯**
menu. **Costs and activity** is folded at the bottom ([On a note](docs/notes.md#on-a-note)).
- **Automations for agents.** Agents list, save, try and run automations through the MCP tools `automations`,
`automation_actions`, `save_automation`, `test_automation` and `run_automation`, with problems in plain words. The
assistant saves them switched off and asks before switching one on or running it
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,11 +126,11 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
[long recordings](docs/speech-providers.md#long-recordings); [checks](docs/requirements.md#understand-it))
- **Learn from it.** Make a two-host podcast episode about what you pick, every claim cited and checked against its
source, read aloud in two voices. Keep notes beside every asset, entity and topic, written by you or the assistant, in
a tree where notes are renamed, moved, copied and pinned (pins are your own), with today's note one click away,
templates to start from, a search by their words, a download as Markdown, and Undo and Recently deleted instead of a
confirm. Export an asset or a collection as an evidence PDF with everything Lens found about it, or the parts you
pick. ([Podcasts](docs/podcasts.md), [notes](docs/notes.md),
[evidence PDFs](docs/api.md#evidence-pdfs); [checks](docs/requirements.md#learn-from-it))
a tree where notes are renamed, moved, copied and pinned (pins are your own) and each note shows the notes it's
inside and the ones inside it, with today's note one click away, templates to start from, a search by their words, a
download as Markdown, and Undo and Recently deleted instead of a confirm. Export an asset or a collection as an
evidence PDF with everything Lens found about it, or the parts you pick. ([Podcasts](docs/podcasts.md),
[notes](docs/notes.md), [evidence PDFs](docs/api.md#evidence-pdfs); [checks](docs/requirements.md#learn-from-it))
- **Automate it.** Pipelines and workflows on a canvas, routines on a schedule, batch runs over a collection, and
notifications to webhooks, Slack, Discord and Matterbridge. Everything that happens in Lens (new assets, emails,
calendar events, files, what people say to Lens, sensor readings, notes, graph changes, runs, budget warnings) is kept
Expand Down
10 changes: 6 additions & 4 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -842,10 +842,12 @@ DELETE /api/v1/notes/{pid}/files
```

Note pages ([Notes](notes.md)), apart from the notes on an asset above. `GET /notes?ns=` is a namespace's page tree
(`all=true` adds the pages of things). `today` gives the namespace's note for `date`, made the first time it's asked
for ([Today's note](notes.md#todays-note)). `templates` lists the notes inside the namespace's Templates note, and
`POST /notes/templates` makes that note the first time; `copy` makes a new note from a page, with its text, drawings,
files and filing ([Templates](notes.md#templates)). `search?q=` finds pages by the words in their title, summary or text, title
(`all=true` adds the pages of things). `GET /notes/{pid}` gives a page with its text, links, backlinks, `path` (the
notes it's inside, from the top) and `children` (the notes inside it) ([On a note](notes.md#on-a-note)). `today` gives
the namespace's note for `date`, made the first time it's asked for ([Today's note](notes.md#todays-note)).
`templates` lists the notes inside the namespace's Templates note, and `POST /notes/templates` makes that note the first
time; `copy` makes a new note from a page, with its text, drawings, files and filing ([Templates](notes.md#templates)).
`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)). `DELETE /notes/{pid}`
moves a page to recently deleted for 30 days: `deleted` lists them, `restore` puts one back where it was and
`DELETE /notes/deleted/{pid}` deletes one for good ([Deleting](notes.md#deleting-and-putting-back)). `move` puts a
Expand Down
11 changes: 11 additions & 0 deletions docs/notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,17 @@ draft with its name and the pages that already link to it. A page follows its as
thing is deleted, or an entity is merged into another, its page stays as a free note at the top of the tree, so
nothing written on it is lost.

## On a note

Above the title, a note says where it is: **Notes › namespace ›** each note it's inside, every one a link. Next to that
are how many words it has, whether it's saved, and its **⋯** menu: **Add a note inside**, **Pin**, **History**,
**Download as Markdown** and **Delete** (with Undo). The text starts in line with the title. Under the text, **Inside
this note** lists the notes inside it in the tree's order, with **Add a note inside**, then the notes that link to it;
**Costs and activity** is folded at the bottom and loads when opened.

`GET /api/v1/notes/{pid}` gives `path` (the notes it's inside, from the top) and `children` (the notes inside it); the
assistant's and MCP's `read_note` give them as `path` and `notes_inside`.

## Entity pages

Every entity (a person, organisation, product, place, event, work or term) has a page of its own, named by its name
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ request, to another check that proves the same thing; loosening a requirement or
| A tree of notes renamed, moved and pinned (pins are your own), today's note one click away, and a search | [test_notebook.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notebook.py) `test_tree`, `test_pins`, `test_search`; [notes-tree.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/notes-tree.test.tsx); [notes-today.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/notes-today.test.tsx) `is one click from the Notes page` |
| A note, or all of a namespace's notes, downloaded as Markdown in folders that follow the tree | [test_notebook.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notebook.py) `test_markdown_export`; [notes-tree.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/notes-tree.test.tsx) `downloads a note as Markdown`; [notes-find.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/notes-find.test.tsx) `downloads every note as Markdown from its menu` |
| Templates a note starts from, and a copy of any note | [test_notebook.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notebook.py) `test_templates_and_copies`; [notes-templates.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/notes-templates.test.tsx); [notes-tree.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/notes-tree.test.tsx) `makes a copy beside the note and opens it` |
| A note shows the notes it's inside and the notes inside it, to people and agents | [test_notebook.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notebook.py) `test_path_and_children`, `test_assistant_keeps_notes`; [test_mcp.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_mcp.py) `test_note_tools`; [note-page.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/note-page.test.tsx) |
| Undo and Recently deleted instead of a confirm | [test_notebook.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notebook.py) `test_recently_deleted`; [notes-delete.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/notes-delete.test.tsx) |
| An asset or a collection exported as an evidence PDF, whole or the parts you pick | [test_evidence.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_evidence.py) `test_a_collection_as_one_evidence_pdf`, `test_everything_lens_found_goes_in`, `test_picking_the_parts`; [evidence-parts.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/evidence-parts.test.tsx) |

Expand Down
5 changes: 4 additions & 1 deletion fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -1683,7 +1683,8 @@ def find_notes(ctx: Context, query: str | None, namespace: str | None, place: st
@tool(
"read_note",
"Read a note",
"A note's Markdown, with what it links to and the notes linking to it: by note_id, or the page of a thing "
"A note's Markdown, with what it links to, the notes linking to it, the notes it is inside (path, from the top) and "
"the notes inside it: by note_id, or the page of a thing "
'(about, like "recording:12", "entity:5" or "topic:9"). Links in the Markdown are written @[label](kind:id) and, for '
"topics, #[label](topic:id).",
Arg("note_id", "integer", "the note (from find_notes)"),
Expand Down Expand Up @@ -1716,6 +1717,8 @@ def read_note(ctx: Context, note_id: int | None, about: str | None) -> dict[str,
"body": _cut(p.body, FETCH_CHARS),
"links": [{"target": x.target, "name": x.name} for x in p.links] or None,
"linked_from": [{"note_id": b.page, "title": b.title} for b in p.backlinks] or None,
"path": [{"note_id": c.id, "title": c.title} for c in p.path] or None,
"notes_inside": [{"note_id": c.id, "title": c.title} for c in p.children] or None,
"url": _note_url(ctx, p.id),
}
)
Expand Down
2 changes: 2 additions & 0 deletions fastapi_backend/app/api/v1/routes/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,8 @@ def _out(acl: Access, db: DB, p: dict[str, Any], user: Principal) -> NotePage:
created_by=(writer or {}).get("email"),
links=out_links,
backlinks=[b for b in _backlinks(acl, db, p["space"], targets) if b["page"] != p["id"]],
path=notebook.path(db, p),
children=notebook.children(db, p) if not p.get("about") else [],
can_edit=user.can_write and auth.allows(acl.roles, p["space"], "editor"),
)

Expand Down
5 changes: 4 additions & 1 deletion fastapi_backend/app/domain/ai_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,8 @@
),
(
"read_note",
"Read a note's Markdown, with its links and the notes linking to it: by note_id, or the page of a thing "
"Read a note's Markdown, with its links, the notes linking to it, the notes it's inside (path) and the notes "
"inside it: by note_id, or the page of a thing "
'(about, like "recording:12" or "entity:5").',
{"note_id": _I, "about": _S},
[],
Expand Down Expand Up @@ -1752,6 +1753,8 @@ def t_read_note(self, note_id=None, about=None):
"body": (p.get("body") or "")[:20_000],
"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"]],
"path": [{"id": x["id"], "title": x["title"]} for x in notebook.path(self.db, p)] or None,
"notes_inside": [{"id": x["id"], "title": x["title"]} for x in notebook.children(self.db, p)] or None,
"could_link": [f"{x['sign']}[{x['label']}]({x['target']})" for x in notebook.suggest_links(self.db, p)] or None,
"files": [{"name": f.get("name"), "type": f["type"], "size": f["size"]} for f in notebook.files(self.db, p["id"])] or None,
"could_go_in": [
Expand Down
23 changes: 23 additions & 0 deletions fastapi_backend/app/domain/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,29 @@ def _check_parent(db, sid, pid, parent):
return int(parent)


def path(db, p):
"""The notes p is inside, from the top of the tree down to its parent: [{id, title}], for breadcrumbs."""
out, at = [], p.get("parent")
while at is not None and len(out) <= DEPTH_MAX:
row = db.one("SELECT record::id(id) AS id, title, parent FROM $r", r=R("note_page", int(at)))
if not row:
break
out.append({"id": row["id"], "title": row["title"]})
at = row.get("parent")
return out[::-1]


def children(db, p):
"""The notes inside p, in the tree's order: [{id, title, updated_at}]."""
rows = db.rows(
"SELECT record::id(id) AS id, title, position, updated_at FROM note_page WHERE space = $s AND parent = $p AND about = NONE",
s=p["space"],
p=int(p["id"]),
)
rows.sort(key=lambda r: (r.get("position") or 0, r["id"]))
return [{"id": r["id"], "title": r["title"], "updated_at": r.get("updated_at")} for r in rows]


def _last_position(db, sid, parent):
rows = db.values(
"SELECT VALUE position FROM note_page WHERE space = $s AND parent = $p AND about = NONE",
Expand Down
8 changes: 8 additions & 0 deletions fastapi_backend/app/schemas/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,12 @@ class NoteBacklink(ResponseModel):
updated_at: str | None = None


class NoteCrumb(ResponseModel):
id: int
title: str
updated_at: str | None = None


class NoteVersionItem(ResponseModel):
id: int
at: str = Field(description="when the page changed from this")
Expand Down Expand Up @@ -79,6 +85,8 @@ class NotePage(NotePageItem):
created_by: str | None = Field(None, description="its writer's email")
links: list[NoteLink] = []
backlinks: list[NoteBacklink] = []
path: list[NoteCrumb] = Field([], description="the notes it's inside, from the top of the tree down to its parent")
children: list[NoteCrumb] = Field([], description="the notes inside it, in the tree's order")
can_edit: bool = False


Expand Down
4 changes: 3 additions & 1 deletion fastapi_backend/tests/api/test_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -474,14 +474,16 @@ def test_note_tools(client, db, env):
plan = notebook.create(
db, pods, None, "Capsid plan", f"Ship on Friday, see @[ep1](recording:{a}).", "Shipping capsids", place="project"
)
notebook.create(db, pods, None, "Hiring", "Two roles open.")
hiring = notebook.create(db, pods, None, "Hiring", "Two roles open.", parent=plan)
notebook.create(db, calls, None, "Capsid call notes", "Not for pods viewers.")
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["notes_inside"] == [{"note_id": hiring, "title": "Hiring"}] and "path" not in got
assert tool(client, h, "read_note", note_id=hiring)["path"] == [{"note_id": plan, "title": "Capsid plan"}]
assert got["body"].startswith("Ship on Friday") and got["links"] == [{"target": f"recording:{a}", "name": got["links"][0]["name"]}]
assert tool(client, h, "read_note", about=f"recording:{a}") == {
"page_of": f"recording:{a}",
Expand Down
24 changes: 24 additions & 0 deletions fastapi_backend/tests/api/test_notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,26 @@ def test_tree(client, env):
assert sorted((p["title"], p["parent"]) for p in tree) == [("Budget", None), ("Hiring", None)]


def test_path_and_children(client, env):
"""A note says which notes it's inside, from the top down, and lists the notes inside it in the tree's order."""
he, hv = env["he"], env["hv"]
top = _new(client, he, title="Home lab")
mid = _new(client, he, title="Pi 5", parent=top["id"])
leaf = _new(client, he, title="Shopping list", parent=mid["id"])
second = _new(client, he, title="Cases", parent=mid["id"])
client.post(f"/api/v1/notes/{second['id']}/move", headers=he, json={"parent": mid["id"], "before": leaf["id"]})
got = client.get(f"/api/v1/notes/{leaf['id']}", headers=hv).json()
assert [(c["id"], c["title"]) for c in got["path"]] == [(top["id"], "Home lab"), (mid["id"], "Pi 5")]
assert got["children"] == []
got = client.get(f"/api/v1/notes/{mid['id']}", headers=hv).json()
assert [c["title"] for c in got["path"]] == ["Home lab"]
assert [c["title"] for c in got["children"]] == ["Cases", "Shopping list"]
assert client.get(f"/api/v1/notes/{top['id']}", headers=hv).json()["path"] == []
# a thing's page isn't in the tree, so nothing is inside it
page = _new(client, he, title="About the call", about=f"recording:{env['a']}")
assert (page["path"], page["children"]) == ([], [])


def test_links_and_backlinks(client, env, db):
he, a = env["he"], env["a"]
term, person = _entity(db, "Capsids", "TERM"), _entity(db, "Ada Lovelace", "PERSON")
Expand Down Expand Up @@ -278,6 +298,10 @@ def call(name, **args):
got = call("read_note", note_id=w["note_id"])
assert got["body"].endswith("Alice sends them.") and got["summary"] == "When the samples ship"
assert got["links"] == [{"sign": "@", "target": f"recording:{env['a']}", "label": "ep1"}]
assert "path" not in got and "notes_inside" not in got # at the top, with nothing inside
kid = call("write_note", namespace="pods", title="Samples", body="Two boxes.", parent_id=w["note_id"])["note_id"]
assert call("read_note", note_id=w["note_id"])["notes_inside"] == [{"id": kid, "title": "Samples"}]
assert call("read_note", note_id=kid)["path"] == [{"id": w["note_id"], "title": "Shipping"}]
assert call("read_note", about=f"recording:{env['a']}")["note"] is None
assert [n["id"] for n in call("find_notes", query="alice")["notes"]] == [w["note_id"]]
assert call("find_notes", place="area")["notes"] == []
Expand Down
Loading
Loading