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 @@ -31,6 +31,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
- **Edit entities from a recording.** In a recording's **Entities** tab, the pencil next to an entity opens its side
panel, so editors rename, retype, hide or merge it without leaving the recording
([Entities](docs/processing.md#entities-and-the-graph-explorer)).
- **Agents edit and merge entities and topics.** The MCP server has `edit_entity`, `edit_topic`, `merge_topics`,
`delete_topic`, `undo_topic_change` and `undo_graph_change` (with a write-scope token and editor access), and the
assistant proposes topic merges, renames, definitions and deletes for the person to approve
(`propose_topic_change`) ([MCP](docs/mcp.md), [Topics](docs/topics.md)).

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

Expand Down
5 changes: 3 additions & 2 deletions docs/assistant.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,9 @@ When the configured model supports function calling, chat becomes an agent.
`ai.max_steps` and `ai.max_transcript_reads`.
- **Citations:** every moment a tool returns is numbered, so answers cite [n] across everything the assistant read.
- **Visible steps:** each tool call streams as a step, for example 'Searched for "refund": 42 matches'.
- **Approvals:** running a template on recordings and changing entities (merging, renaming, retyping, describing one
and the other ways it's said, hiding one, or adding one to a namespace's fixed list) don't happen directly.
- **Approvals:** running a template on recordings, changing entities (merging, renaming, retyping, describing one
and the other ways it's said, hiding one, or adding one to a namespace's fixed list) and changing topics (merging,
renaming, describing or deleting one; [Topics](topics.md)) don't happen directly.
They become approval cards (with the batch estimate) that the person approves, approves on a sample, or declines
(`POST /api/v1/approvals/<id>`). Viewers only get the read tools.
- **Check sources** (`POST /api/v1/chats/<id>/messages/<id>/check`) re-checks every cited claim against the lines it
Expand Down
2 changes: 1 addition & 1 deletion docs/chat-rooms.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ That's all. Without an account given, it answers as the admin who turned it on.
proposes (running work, changing settings) wait for approval in the web app, as in Chat; its answer says so and
links to the conversation, through the Cloudflare tunnel while one is up (Settings › Remote access), so the link
opens away from home too.
- **Approving in the room.** Reversible changes (merging, renaming or retyping entities, new namespaces) can be
- **Approving in the room.** Reversible changes (merging, renaming or retyping entities, changing topics, new namespaces) can be
approved right there: the answer says "Reply “yes” to do it", and "yes" (or "no") does it (or declines it). With
several waiting, "yes all" or "yes 12". Only the chat usernames listed may talk to Lens and approve, so it needs
that list; **Approving in the room: only in the web app** turns it off. Settings, imports, batch runs, extensions
Expand Down
12 changes: 10 additions & 2 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,12 @@ front of the web app also needs `TRUST_PROXY_HEADERS=true` ([Authentication](aut
| `install_settings` | whether other devices on the network reach Lens and its edition (full or lean), whether the machine's upgrade agent can change them, and the install line to run when it can't. Admins only |
| `set_install_settings` | open Lens to the network or keep it to this machine, or change the edition: the machine sets itself up again and Lens restarts ([Updates](updates.md#setting-the-machine-up-again)). Admins only, with a write-scope token |
| `propose_graph_change` | ask for two entities to be merged or linked; it waits in Proposed changes unless `apply` makes it at once (it can be undone). Needs a write-scope token and editor access |
| `undo_graph_change` | take back a merge or link `propose_graph_change` made. Needs a write-scope token and editor access |
| `edit_entity` | rename an entity, change its type, describe it, set the other ways it's said, or hide or show it. Needs a write-scope token and editor access |
| `edit_topic` | rename a topic, set its other labels, definition, broader and related topics. Needs a write-scope token and editor access |
| `merge_topics` | fold topics into one; its `undo_id` takes it back. Needs a write-scope token and editor access |
| `delete_topic` | delete a topic; its `undo_id` takes it back. Needs a write-scope token and editor access |
| `undo_topic_change` | take back `merge_topics` or `delete_topic` by its `undo_id` ([Topics](topics.md#a-topic)). Needs a write-scope token and editor access |

Results are JSON (as `structuredContent`, and the same as text). Links open the recording's page in the web app at
that moment (`/resources/<id>?t=<seconds>`), on the address the client used. Mistakes the agent can fix (a wrong
Expand All @@ -86,11 +92,13 @@ person's to read answers "not found", as the API does. `search` and `fetch` foll
expect (`results` with `id`, `title`, `url`; `fetch` by that `id`).

Every tool reads, except `suggest_topic`, which adds suggestions people accept or dismiss, `propose_graph_change`,
which records an undoable change (proposed by default), `write_note`, which adds a note, `create_podcast`, which
which records an undoable change (proposed by default), `undo_graph_change`, `edit_entity`, `edit_topic`,
`merge_topics`, `delete_topic` and `undo_topic_change`, which curate entities and topics as an editor does in the web
app (merges and deletes can be undone), `write_note`, which adds a note, `create_podcast`, which
queues an episode, `set_nsfw` and `mark_nsfw`, which change [NSFW classification](nsfw.md) (owners or admins, and
editors), `set_file_storage`, which changes where new files are kept (admins), and `set_monitoring` and
`set_install_settings`, which have the machine change how Lens runs (admins).
Importing, editing and curating stay in the web app and the API.
Importing stays in the web app and the API.

### What the archive says is data

Expand Down
5 changes: 5 additions & 0 deletions docs/topics.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,3 +131,8 @@ The assistant in Chat finds topics (`find_topics`), reads one with its recording
editors, suggests a topic for recordings (`suggest_topic`). The MCP server has the same as `list_topics`, `get_topic`
and `suggest_topic` (with a write-scope token). Suggestions from either wait for someone to accept them, with
`assistant` as their source; what people accepted or dismissed stays as it is.

Asked to tidy the vocabulary, the assistant proposes merging, renaming, describing or deleting a topic
(`propose_topic_change`), which happens only when the person approves it, in Chat or with a yes in a chat room. With
a write-scope token, agents edit, merge and delete topics over MCP (`edit_topic`, `merge_topics`, `delete_topic`) and
take a merge or delete back with `undo_topic_change`.
155 changes: 154 additions & 1 deletion fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
from app.api.v1.routes import namespaces as namespace_routes
from app.api.v1.routes import notebook as note_routes
from app.api.v1.routes import recordings as recording_routes
from app.api.v1.routes import routines as routine_routes
from app.api.v1.routes import search as search_routes
from app.api.v1.routes import topics as topic_routes
from app.domain import (
Expand All @@ -55,9 +56,10 @@
from app.domain import speakers as spk
from app.domain import topics as topicmod
from app.domain.store import DB
from app.schemas.entities import EntityList
from app.schemas.entities import EntityHide, EntityList, EntityRename, EntityRetype, EntityUpdate
from app.schemas.notebook import NotePage
from app.schemas.search import SearchResults
from app.schemas.topics import TopicMerge, TopicUpdate

R = store.R
FETCH_CHARS = 100_000 # the most of a transcript fetch returns; get_transcript pages through the rest
Expand Down Expand Up @@ -1289,6 +1291,157 @@ def propose_graph_change(ctx: Context, kind: str, a: str, b: str, reason: str |
return graph_routes.propose_graph_change(ctx.request, body, ctx.user, ctx.acl, ctx.db)


@tool(
"undo_graph_change",
"Undo a graph change",
"Take back a merge or link made by propose_graph_change (with apply, or once accepted): its id is the change's. "
"Needs a token with the write scope and editor access.",
Arg("change_id", "integer", "the change (propose_graph_change's id)", required=True),
writes=True,
)
def undo_graph_change(ctx: Context, change_id: int) -> dict[str, Any]:
_writer(ctx, "undo changes")
routine_routes.undo_graph_change(change_id, ctx.user, ctx.acl, ctx.db)
ctx.request.app.state.graph_cache.clear()
return {"undone": change_id}


# ---------- editing entities and topics (docs/graph.md, docs/topics.md) ----------
def _writer(ctx: Context, what: str) -> None:
if not ctx.user.can_write:
raise ToolError(f"this token is read-only: ask for a token with the write scope to {what}")


@tool(
"edit_entity",
"Edit an entity",
"Rename an entity (the old name stays one of the ways it's said), change its type, describe it, set the other ways "
"it's said, or hide it (hidden false shows it again). Give only what changes. Renaming to another entity's name is "
"refused: merge them with propose_graph_change instead. Needs a token with the write scope and editor access.",
Arg("entity_id", "integer", "the entity (from list_entities or the graph's e<id>)", required=True),
Arg("new_name", "string", "its new name", max_length=200),
Arg("new_type", "string", "its new type: PERSON, ORG, PRODUCT, PLACE, EVENT, WORK, TERM or one of the namespace's own", max_length=40),
Arg("description", "string", "what it is, in a sentence or two", max_length=2000),
Arg("aliases", "string[]", "the other ways it's said (these replace the ones it has)"),
Arg("hidden", "boolean", "hide it from lists and the graph, or show it again"),
writes=True,
)
def edit_entity(
ctx: Context,
entity_id: int,
new_name: str | None,
new_type: str | None,
description: str | None,
aliases: list[str] | None,
hidden: bool | None,
) -> dict[str, Any]:
_writer(ctx, "edit entities")
if new_name is None and new_type is None and description is None and aliases is None and hidden is None:
raise ToolError("say what changes: new_name, new_type, description, aliases or hidden")
args = (ctx.request, ctx.user, ctx.acl, ctx.db)
if new_name is not None:
entity_routes.rename_entity(entity_id, EntityRename(name=new_name), *args)
if new_type is not None:
entity_routes.retype_entities(EntityRetype(ids=[entity_id], type=new_type), *args)
if description is not None or aliases is not None:
body = EntityUpdate(**{k: v for k, v in (("description", description), ("aliases", aliases)) if v is not None})
entity_routes.update_entity(entity_id, body, *args)
if hidden is not None:
entity_routes.hide_entity(entity_id, *args, body=EntityHide(hidden=hidden))
d = entity_routes.get_entity(entity_id, ctx.user, ctx.acl, ctx.db)
return store.clean(
{"entity_id": d.id, "name": d.name, "type": d.type, "description": d.description, "aliases": d.aliases or None, "hidden": d.hidden}
)


def _topic_out(d: Any) -> dict[str, Any]:
return store.clean(
{
"topic_id": d.id,
"label": d.label,
"also": d.alt or None,
"definition": d.definition,
"broader": [{"topic_id": x.id, "label": x.label} for x in d.broader] or None,
"related": [{"topic_id": x.id, "label": x.label} for x in d.related] or None,
}
)


@tool(
"edit_topic",
"Edit a topic",
"Rename a topic, set its other labels or its definition, or what it is narrower than (broader_ids) or related to. "
"Give only what changes; lists replace the ones it has. Needs a token with the write scope and editor access.",
Arg("topic_id", "integer", "the topic (from list_topics or the graph's t<id>)", required=True),
Arg("label", "string", "its new label", max_length=200),
Arg("also", "string[]", "its other labels: synonyms, abbreviations, spellings"),
Arg("definition", "string", "what it covers", max_length=2000),
Arg("broader_ids", "integer[]", "the topics it is narrower than", maximum=50),
Arg("related_ids", "integer[]", "the topics it is related to", maximum=50),
writes=True,
)
def edit_topic(
ctx: Context,
topic_id: int,
label: str | None,
also: list[str] | None,
definition: str | None,
broader_ids: list[int] | None,
related_ids: list[int] | None,
) -> dict[str, Any]:
_writer(ctx, "edit topics")
given = {"label": label, "alt": also, "definition": definition, "broader": broader_ids, "related": related_ids}
body = TopicUpdate(**{k: v for k, v in given.items() if v is not None})
if not body.model_fields_set:
raise ToolError("say what changes: label, also, definition, broader_ids or related_ids")
return _topic_out(topic_routes.update_topic(topic_id, body, ctx.request, ctx.user, ctx.acl, ctx.db))


@tool(
"merge_topics",
"Merge topics",
"Fold other topics of the same namespace into one: their labels become its other labels and the recordings about "
"them are about it. undo_id takes it back with undo_topic_change. Needs a token with the write scope and editor "
"access.",
Arg("keep_id", "integer", "the topic that stays", required=True),
Arg("other_ids", "integer[]", "the topics merged into it", required=True, maximum=50),
writes=True,
)
def merge_topics(ctx: Context, keep_id: int, other_ids: list[int]) -> dict[str, Any]:
_writer(ctx, "merge topics")
d = topic_routes.merge_topics(TopicMerge(keep=keep_id, others=other_ids), ctx.request, ctx.user, ctx.acl, ctx.db)
return {**_topic_out(d), "recordings": d.recordings, "undo_id": d.undo}


@tool(
"delete_topic",
"Delete a topic",
"Delete a topic: its narrower topics move up to its broader ones and recordings stop being about it. undo_id takes "
"it back with undo_topic_change. Needs a token with the write scope and editor access.",
Arg("topic_id", "integer", "the topic", required=True),
writes=True,
)
def delete_topic(ctx: Context, topic_id: int) -> dict[str, Any]:
_writer(ctx, "delete topics")
out = topic_routes.delete_topic(topic_id, ctx.request, ctx.user, ctx.acl, ctx.db)
return {"deleted": topic_id, "undo_id": out.undo}


@tool(
"undo_topic_change",
"Undo a topic merge or delete",
"Take back a merge_topics or delete_topic (by its undo_id): the topics come back with their labels, recordings and "
"pages. Refused when another topic has taken one of their labels since. Needs a token with the write scope and "
"editor access.",
Arg("undo_id", "integer", "what merge_topics or delete_topic gave back", required=True),
writes=True,
)
def undo_topic_change(ctx: Context, undo_id: int) -> dict[str, Any]:
_writer(ctx, "undo changes")
topic_routes.undo_topic_change(undo_id, ctx.request, ctx.user, ctx.acl, ctx.db)
return {"undone": undo_id}


# ---------- notes (docs/notes.md) ----------
def _note_url(ctx: Context, pid: int) -> str:
return f"{ctx.web}/notes/{pid}"
Expand Down
1 change: 1 addition & 0 deletions fastapi_backend/app/api/v1/routes/chats.py
Original file line number Diff line number Diff line change
Expand Up @@ -422,4 +422,5 @@ def decide_approval(aid: int, body: ApprovalDecision, user: Writer, acl: Acl, db
except (ValueError, PermissionError, KeyError) as e:
raise HTTPException(400, str(e)) from None
auth.audit(db, user.as_audit(), "assistant.approval", f"approval:{aid}", {"decision": body.decision, **out})
request.app.state.graph_cache.clear() # an approved entity or topic change shows in the graph at once
return out
Loading
Loading