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 @@ -23,6 +23,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
same editor as its own page, and an entity's has **Merge** and **Maybe the same**. The node menu has **Edit…** and
**Merge into another…**, which merges the node into the one clicked next (entities and speakers of one namespace;
entities of two namespaces are linked as the same thing), each with **Undo** ([The graph](docs/graph.md)).
- **Undo topic merges and deletes.** Merging or deleting a topic happens at once, with **Undo** on its notice instead
of a confirm step: the topics come back with their labels, recordings, broader and related topics and pages. A
topic's drawer has a find box to merge another topic in, and topics merge on the graph canvas too. The API answers
a merge or delete with an `undo` id (`POST /api/v1/topics/changes/{id}/undo`) and lists recent ones
([Topics](docs/topics.md)).

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

Expand Down
2 changes: 1 addition & 1 deletion docs/graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ to itself and has one. On a computer the Find in graph box has the focus, so typ
topics), and an entity's has **Merge**, a find box where Enter merges the entity picked into it, and **Maybe the
same**, its likely doubles. From the node menu, **Edit…** does the same and **Merge into another…** merges the node
into the one you pick next: entities of one namespace are merged, entities of two namespaces are linked as the same
thing, and speakers of one namespace are merged. Each happens at once with **Undo** on its notice. A node that joins
thing, and speakers and topics of one namespace are merged. Each happens at once with **Undo** on its notice. A node that joins
entities of several namespaces (all shared) offers **Edit in** each namespace. Looking at an earlier version, the
graph is read-only.
- **Route**: add stops from the node menu; the route follows the shortest path between each pair of stops, laid out
Expand Down
25 changes: 18 additions & 7 deletions docs/topics.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,16 @@ assistant and MCP tools for topics.
**Topics** in the navigation shows a namespace's vocabulary as a tree: top topics first, each opening onto its
narrower ones (a topic under two broader topics shows under both). Search finds topics by any of their labels. Pick
a topic to edit it in a drawer: its labels, definition, broader and related topics, its narrower topics, and the
recordings about it, where suggested ones can be accepted or removed. The drawer also merges topics and deletes one.
Editors add topics at the top or under another with **+**.
recordings about it, where suggested ones can be accepted or removed. **Merge** in the drawer opens a find box: type
part of a label and pick (or press Enter) to merge that topic into this one at once. **Delete** deletes it at once.
Both say what they did with **Undo** on the message, so there is no confirm step. Editors add topics at the top or
under another with **+**.

A recording's **Entities** tab starts with its topics: editors add one from the vocabulary, take one off, or accept
or dismiss a suggestion. An entity of type Term has **Make a topic** in its drawer. On the graph canvas topics are
green tags, with About, Narrower and Related edges; ask the graph (for example `MATCH (t:Topic) RETURN t`) or open a
recording's children to bring them in.
recording's children to bring them in. Editors edit a topic from the graph (**Edit…** on a node's menu, or **Edit**
in its panel) and merge one into another with **Merge into another…** and a click on the one to keep.

## A topic

Expand Down Expand Up @@ -66,11 +69,16 @@ recordings join it.
Deleting a topic moves its narrower topics up to its broader ones. Merging topics makes the others' labels the kept
topic's other labels and brings their recordings over.

Either can be undone: the topics come back with their ids, labels, definitions, recordings and note pages, the
broader and related lists they were taken out of are put back, and a topic made from an entity hides that entity
again. Whatever changed since stays. Undo is refused when another topic has taken one of their labels meanwhile:
rename that one first.

## Rights

Reading needs a role in the namespace; changing the vocabulary or which recordings are about a topic needs the editor
role there. Every change is in the audit log (`topic.create`, `topic.update`, `topic.delete`, `topic.merge`,
`topic.tag`, `topic.untag`, `topic.from_entity`).
`topic.tag`, `topic.untag`, `topic.from_entity`, `topic.merge.undo`, `topic.delete.undo`).

## The API

Expand All @@ -80,8 +88,10 @@ role there. Every change is in the audit log (`topic.create`, `topic.update`, `t
| `GET /api/v1/topics/{id}` | A topic with its broader, narrower and related topics and the recordings about it. |
| `POST /api/v1/namespaces/{name}/topics` | Add a topic `{label, alt, definition, broader, related}`. |
| `PATCH /api/v1/topics/{id}` | Change any of those; an empty definition clears it. |
| `DELETE /api/v1/topics/{id}` | Delete it. |
| `POST /api/v1/topics/merge` `{keep, others}` | Merge topics into one. |
| `DELETE /api/v1/topics/{id}` | Delete it; the answer's `undo` takes it back. |
| `POST /api/v1/topics/merge` `{keep, others}` | Merge topics into one; the answer's `undo` takes it back. |
| `GET /api/v1/namespaces/{name}/topics/changes` | The latest merges and deletes, newest first, each with whether it was undone. |
| `POST /api/v1/topics/changes/{id}/undo` | Take a merge or a delete back. |
| `POST /api/v1/topics/{id}/recordings` `{recordings, remove}` | Say recordings are about it, or aren't. |
| `GET /api/v1/resources/{id}/topics` | The topics a recording is about, and those suggested. |
| `POST /api/v1/entities/{id}/topic` | Make a TERM entity a topic. |
Expand All @@ -108,7 +118,8 @@ In RDF ([Linked data](rdf.md)) a topic is `/id/topic/<id>`, a `skos:Concept` in

- Vocabularies shared by several namespaces, and imported schemes (LCSH, Wikidata) linked with `skos:exactMatch`.
- Entities as authority records: variant names and external identifiers.
- History and undo for topic merges and deletes.
- A page listing the latest topic merges and deletes, to undo one after its message has gone.
- Picking several topics on the Topics page to merge them in one go.

## Notes, the assistant and agents

Expand Down
44 changes: 36 additions & 8 deletions fastapi_backend/app/api/v1/routes/topics.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,13 @@
from app.schemas.topics import (
RecordingTopic,
TopicCandidate,
TopicChange,
TopicCreate,
TopicDeleted,
TopicDetail,
TopicList,
TopicMerge,
TopicMerged,
TopicRecordings,
TopicSkip,
TopicUpdate,
Expand Down Expand Up @@ -129,26 +132,51 @@ def update_topic(tid: int, body: TopicUpdate, request: Request, user: Writer, ac


@router.delete("/topics/{tid}")
def delete_topic(tid: int, request: Request, user: Writer, acl: Acl, db: Db) -> Ok:
"""Delete it: its narrower topics move up, recordings stop being about it, and an entity it was made from shows again."""
def delete_topic(tid: int, request: Request, user: Writer, acl: Acl, db: Db) -> TopicDeleted:
"""Delete it: its narrower topics move up, recordings stop being about it, and an entity it was made from shows
again. `undo` takes it back (POST /topics/changes/{undo}/undo)."""
_topic_space(db, acl, tid, "curate")
with domain_errors():
eid = topics.delete(db, tid)
eid, cid = topics.delete(db, tid, user=user.email)
auth.audit(db, user.as_audit(), "topic.delete", f"topic:{tid}", {"entity": eid} if eid else None)
_changed(request)
return Ok()
return TopicDeleted(undo=cid)


@router.post("/topics/merge")
def merge_topics(body: TopicMerge, request: Request, user: Writer, acl: Acl, db: Db) -> TopicDetail:
"""Fold topics into one: their labels become its other labels and their recordings are about it."""
def merge_topics(body: TopicMerge, request: Request, user: Writer, acl: Acl, db: Db) -> TopicMerged:
"""Fold topics into one: their labels become its other labels and their recordings are about it. `undo` takes it
back (POST /topics/changes/{undo}/undo)."""
for t in [body.keep, *body.others]:
_topic_space(db, acl, t, "curate")
with domain_errors():
topics.merge(db, body.keep, body.others, user=user.email)
cid = topics.merge(db, body.keep, body.others, user=user.email)
auth.audit(db, user.as_audit(), "topic.merge", f"topic:{body.keep}", {"others": body.others})
_changed(request)
return _detail(db, acl, body.keep)
return TopicMerged(**_detail(db, acl, body.keep).model_dump(), undo=cid)


@router.get("/namespaces/{name}/topics/changes")
def list_topic_changes(name: str, user: CurrentUser, acl: Acl, db: Db, limit: int = 50) -> list[TopicChange]:
"""The namespace's latest topic merges and deletes, newest first, each with whether it was undone."""
sid = acl.nsid(name)
acl.need(sid, "viewer")
return [TopicChange(**c) for c in topics.changes(db, sid, min(max(limit, 1), 200))]


@router.post("/topics/changes/{cid}/undo")
def undo_topic_change(cid: int, request: Request, user: Writer, acl: Acl, db: Db) -> Ok:
"""Take back a merge or a delete: the topics come back with their labels, recordings and pages. What changed
since stays. Refused (400) when another topic has taken one of their labels meanwhile."""
row = db.one("SELECT space FROM $r", r=R("topic_change", int(cid)))
if not row:
raise HTTPException(404, "not found")
acl.need(row["space"], "curate")
with domain_errors():
out = topics.undo(db, cid, user=user.email)
auth.audit(db, user.as_audit(), f"topic.{out['kind']}.undo", f"topic_change:{cid}", {"topics": out["topics"]})
_changed(request)
return Ok()


@router.post("/topics/{tid}/recordings")
Expand Down
3 changes: 3 additions & 0 deletions fastapi_backend/app/domain/store.py
Original file line number Diff line number Diff line change
Expand Up @@ -1142,6 +1142,9 @@ def close(self):
"DEFINE INDEX IF NOT EXISTS topic_about_rec ON topic_about FIELDS recording",
"DEFINE INDEX IF NOT EXISTS topic_about_topic ON topic_about FIELDS topic",
"DEFINE INDEX IF NOT EXISTS topic_about_space ON topic_about FIELDS space",
# merges and deletes of topics, kept so they can be undone (app/domain/topics.py)
"DEFINE TABLE IF NOT EXISTS topic_change SCHEMALESS",
"DEFINE INDEX IF NOT EXISTS topic_change_space ON topic_change FIELDS space",
# Note: on 2.x, CONTAINS against an indexed field also returns nothing; use string::contains() there.
# settings, people and access
"DEFINE TABLE IF NOT EXISTS app_setting SCHEMALESS",
Expand Down
Loading
Loading