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 @@ -48,6 +48,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
`ABOUT`, `NARROWER` and `RELATED`; TERM entities are now labelled `Term` there) and in RDF (`/id/topic/<id>`). See
docs/topics.md.

- **Topics in notes and for agents.** `#` in a note links a topic, found by any of its labels, and every topic has
a page of its own. The assistant can find topics, read one with its recordings and suggest a topic for recordings;
the MCP server has `list_topics`, `get_topic` and `suggest_topic`. Their suggestions wait for someone to accept.

- **Topic suggestions.** Analysis suggests the vocabulary's topics for recordings whose summary or transcript says
one of their labels, for people to accept or dismiss (a dismissed one isn't suggested again). The Topics page lists
what summaries say recordings are about that no topic covers yet, to add as a topic or skip. No model is called.
Expand Down
2 changes: 1 addition & 1 deletion DEVLOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ Todo:
- [x] Topics page: the tree of broader and narrower topics, a topic's recordings, edit and merge; a recording's topics
- [x] Analysis suggests topics (summary topics and keywords matched to the vocabulary; new ones as suggestions to
accept); a namespace can keep its vocabulary fixed or open, as entities do
- [ ] # links in notes point at topics; assistant and MCP tools for topics
- [x] # links in notes point at topics; assistant and MCP tools for topics

Refine later: shared vocabularies across namespaces and imported schemes (LCSH, Wikidata) with exactMatch; entities as
authority records (variant names, external identifiers); topic history and undo for merges; a namespace setting
Expand Down
3 changes: 2 additions & 1 deletion docs/graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,8 @@ namespaces; `ids` lists the entities behind it, and `e<id>` finds the merged nod
## The assistant and MCP

The assistant in Chat has the graph as tools, over the namespaces of the chat (or every shared one): `graph_schema`,
`graph_query` (Cypher), `graph_related` and `graph_paths`. They only read.
`graph_query` (Cypher), `graph_related` and `graph_paths`. They only read. For topics it has `find_topics`,
`topic_recordings` and `suggest_topic` ([Topics](topics.md)).

The MCP server (docs/mcp.md) has the same four, marked read-only, and `propose_graph_change`, which needs a
write-scope token and editor access; the change waits in Proposed changes unless `apply` makes it at once, and can be
Expand Down
8 changes: 6 additions & 2 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,14 +44,17 @@ front of the web app also needs `TRUST_PROXY_HEADERS=true` ([Authentication](aut
| `get_transcript` | a recording's lines in order (speaker, time, text, link), a page at a time, from a line or a time window |
| `fetch` | a recording's whole text at once, as `[m:ss] Speaker: …` lines |
| `cite` | a citation for a moment (a line or a second, and a few lines from there): the words, who said them, the recording and date, the time, the link, and all of it as Markdown |
| `list_entities` | people, organisations, products, places, events, works and topics mentioned, by name, type, namespace or recording |
| `list_entities` | people, organisations, products, places, events, works and terms mentioned, by name, type, namespace or recording |
| `get_entity` | one entity: its names, how often and when it is mentioned, what it is mentioned with, who mentions it most, and the lines that mention it |
| `explore_graph` | the knowledge graph around an entity (`e12`) or a speaker (`s3`), one or two steps out |
| `find_path` | the shortest chain of links between two of them, with lines that show each link |
| `graph_schema` | what the property graph holds (labels, relationships, properties, counts) and example Cypher ([The graph](graph.md)) |
| `graph_query` | read-only Cypher over the graph of one namespace or every shared one: columns, rows, and the nodes and relationships found |
| `graph_related` | a node's parents, children, ancestors, descendants or neighbours |
| `graph_paths` | the paths between two nodes, shortest first |
| `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 |
| `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 |

Results are JSON (as `structuredContent`, and the same as text). Links open the recording's page in the web app at
Expand All @@ -60,7 +63,8 @@ argument, something it can't read) come back as a tool result with `isError`, so
person's to read answers "not found", as the API does. `search` and `fetch` follow the shape ChatGPT's connectors
expect (`results` with `id`, `title`, `url`; `fetch` by that `id`).

Every tool reads, except `propose_graph_change`, which records an undoable change (proposed by default).
Every tool reads, except `suggest_topic`, which adds suggestions people accept or dismiss, and `propose_graph_change`,
which records an undoable change (proposed by default).
Importing, editing and curating stay in the web app and the API.

## Protocol
Expand Down
16 changes: 9 additions & 7 deletions docs/notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@
Every resource, entity and topic in Lens has a page of its own, and next to them sit free notes that people and the
assistant write. The assistant is the main writer and organiser; people can do everything it can.

Status: **built**: pages (free notes in a tree, a page per recording, entity, collection or speaker), @ and # links
with backlinks, the tree in the left navigation, the page view with the BlockSuite editor, the model keeping titles
and summaries up to date, and assistant tools to find, read, write and update notes. **Planned**: MCP tools, page
history, linking notes to entities and topics and nesting them under their project or area on their own, attachments on encrypted object storage, pages in the graph, # links to SKOS topics.
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, and assistant tools to find, read, write and update notes.
**Planned**: MCP tools, page history, linking notes to entities and topics and nesting them under their project or
area on their own, attachments on encrypted object storage, pages in the graph.

## A page

Expand All @@ -32,11 +33,12 @@ nothing written on it is lost.
The body links with mention tokens, which the editor and the assistant both write:

```text
@[Weekly call](recording:12) @[Ada Lovelace](entity:5) @[Plans](page:3) #[Capsids](entity:9)
@[Weekly call](recording:12) @[Ada Lovelace](entity:5) @[Plans](page:3) #[Capsid design](topic:9)
```

`@` links resources, people and other pages; `#` links topics (entities of type Topic, until topics become a SKOS
vocabulary of their own; see [the graph](graph.md)). `GET /api/v1/notes/targets?ns=&sign=&q=` offers what to link.
`@` links resources, people and other pages; `#` links topics, the namespace's vocabulary ([Topics](topics.md)),
found by any of their labels. Links written to terms (`#[Capsids](entity:9)`) before topics existed still work.
`GET /api/v1/notes/targets?ns=&sign=&q=` offers what to link.
Links are kept as rows (`note_link`), so every page lists its backlinks; links to things that are gone or that the
reader can't see show without a name.

Expand Down
15 changes: 13 additions & 2 deletions docs/topics.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ subject someone chose for the vocabulary, like "Gene therapy" or "Funding".

Status: **built**: the vocabulary (labels, definitions, broader, narrower and related topics), recordings about
topics, topics made from topic-like entities, the API, the Topics page, a recording's topics, topics in the graph
(and on its canvas) and in RDF, and topic suggestions from analysis. **Planned**: `#` links in notes pointing at
topics, and assistant and MCP tools for topics.
(and on its canvas) and in RDF, topic suggestions from analysis, `#` links in notes, a page per topic, and
assistant and MCP tools for topics.

## In the web app

Expand Down Expand Up @@ -109,3 +109,14 @@ 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.

## Notes, the assistant and agents

In notes, `#` links a topic (`#[Capsid design](topic:9)`), found by any of its labels, and every topic has a page of
its own (**Page** in its drawer) that lists the notes linking to it. Deleting or merging a topic keeps its page, as a
free note.

The assistant in Chat finds topics (`find_topics`), reads one with its recordings (`topic_recordings`) and, for
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.
116 changes: 108 additions & 8 deletions fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,11 @@
from app.api.v1.routes import namespaces as namespace_routes
from app.api.v1.routes import recordings as recording_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 analyze, graph_history, library, rdf, render, store
from app.domain import entities as ents
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.search import SearchResults
Expand Down Expand Up @@ -75,14 +77,16 @@ class Arg:
def schema(self) -> dict[str, Any]:
if self.type == "string[]":
s: dict[str, Any] = {"type": "array", "items": {"type": "string", **({"enum": list(self.enum)} if self.enum else {})}}
elif self.type == "integer[]":
s = {"type": "array", "items": {"type": "integer"}, "maxItems": self.maximum or 500}
else:
s = {"type": self.type}
if self.enum:
s["enum"] = list(self.enum)
s["description"] = self.description
if self.minimum is not None:
s["minimum"] = self.minimum
if self.maximum is not None:
if self.maximum is not None and self.type != "integer[]":
s["maximum"] = self.maximum
if self.max_length is not None:
s["maxLength"] = self.max_length
Expand Down Expand Up @@ -137,6 +141,19 @@ def parse(self, value: Any) -> Any:
if bad:
raise ToolError(f"{self.name}: {', '.join(bad)} isn't one of {', '.join(self.enum)}")
return value or self.default
elif t == "integer[]":
if isinstance(value, str):
value = [x.strip() for x in value.split(",") if x.strip()]
if not isinstance(value, list) or not all(
(isinstance(x, int) and not isinstance(x, bool)) or (isinstance(x, str) and re.fullmatch(r"\d+", x)) for x in value
):
raise ToolError(f"{self.name} is a list of whole numbers")
value = [int(x) for x in value]
if self.maximum is not None and len(value) > self.maximum:
raise ToolError(f"{self.name} has at most {self.maximum} items")
if self.required and not value:
raise ToolError(f"{self.name} is required")
return value or self.default
if self.enum and t != "string[]" and value not in self.enum:
raise ToolError(f"{self.name} is one of {', '.join(self.enum)}")
if self.minimum is not None and value < self.minimum:
Expand Down Expand Up @@ -689,7 +706,7 @@ def _entity_row(e: dict[str, Any]) -> dict[str, Any]:
@tool(
"list_entities",
"Find entities",
"Entities: the people, organisations, products, places, events, works and topics mentioned in recordings, the most "
"Entities: the people, organisations, products, places, events, works and terms mentioned in recordings, the most "
"mentioned first. Find one by name with query; its entity_id opens it in get_entity and the graph.",
Arg("query", "string", "a name, or part of one", max_length=200),
Arg("types", "string[]", "only these types", enum=ENTITY_TYPES),
Expand Down Expand Up @@ -940,9 +957,10 @@ def _gscope(namespace: str | None) -> str:
@tool(
"graph_schema",
"What the graph holds",
"The archive as a property graph: node labels (Namespace, Collection, Recording, Speaker, Entity and its type) with "
"their properties and counts, relationship types (CONTAINS, HAS_SPEAKER, MENTIONS, SAID, MENTIONED_WITH, "
"SPOKE_WITH, SAME_AS, SAME_THING) and what they join, and example Cypher. Read it before graph_query.",
"The archive as a property graph: node labels (Namespace, Collection, Recording, Speaker, Entity and its type, "
"Topic) with their properties and counts, relationship types (CONTAINS, HAS_SPEAKER, MENTIONS, SAID, "
"MENTIONED_WITH, SPOKE_WITH, SAME_AS, SAME_THING, ABOUT, NARROWER, RELATED) and what they join, and example "
"Cypher. Read it before graph_query.",
Arg("namespace", "string", "one namespace (else every namespace that shares its graph)"),
)
def graph_schema(ctx: Context, namespace: str | None) -> dict[str, Any]:
Expand All @@ -969,9 +987,10 @@ def graph_query(ctx: Context, query: str, namespace: str | None, limit: int) ->
@tool(
"graph_related",
"Walk the graph from a node",
"A node's parents, children, ancestors or descendants (along CONTAINS, HAS_SPEAKER, MENTIONS and SAID: namespace "
"> collection > recording > speaker and entity), or its neighbours over any relationship, nearest first. Nodes "
"are n<id>, c<id>, r<id>, s<id> and e<id> (e:<key> for an entity across namespaces).",
"A node's parents, children, ancestors or descendants (along CONTAINS, HAS_SPEAKER, MENTIONS, SAID, ABOUT and "
"NARROWER: namespace > collection > recording > speaker, entity and topic > narrower topic), or its neighbours "
"over any relationship, nearest first. Nodes are n<id>, c<id>, r<id>, s<id>, e<id> (e:<key> for an entity across "
"namespaces) and t<id>.",
Arg("node", "string", "the node id", required=True, max_length=200),
Arg("relation", "string", "which way to walk", required=True, enum=("parents", "children", "ancestors", "descendants", "neighbours")),
Arg("depth", "integer", "steps out (ancestors, descendants, neighbours)", default=1, minimum=1, maximum=8),
Expand Down Expand Up @@ -1027,6 +1046,87 @@ def graph_paths(ctx: Context, from_node: str, to_node: str, max_depth: int, shor
)


@tool(
"list_topics",
"Find topics",
"Topics: each namespace's controlled vocabulary of what its recordings are about (SKOS concepts), by label, with "
"other labels, a definition, broader topics and how many recordings are about each. query matches any label.",
Arg("query", "string", "a label, or part of one", max_length=200),
Arg("namespace", "string", "only this namespace"),
Arg("top", "boolean", "only topics with no broader topic", default=False),
Arg("broader_id", "integer", "only the narrower topics of this one"),
Arg("limit", "integer", "how many", default=50, minimum=1, maximum=200),
Arg("offset", "integer", "skip this many (for the next page)", default=0, minimum=0),
)
def list_topics(
ctx: Context, query: str | None, namespace: str | None, top: bool, broader_id: int | None, limit: int, offset: int
) -> dict[str, Any]:
res = topic_routes.list_topics(ctx.user, ctx.acl, ctx.db, query or "", namespace or "", top, broader_id, limit, offset)
out: dict[str, Any] = {
"total": res.total,
"topics": [
{
"topic_id": t.id,
"label": t.label,
"namespace": t.namespace,
"also": t.alt or None,
"definition": t.definition,
"broader_ids": t.broader or None,
"narrower": t.narrower,
"recordings": t.recordings,
}
for t in res.items
],
}
if offset + len(res.items) < res.total:
out["next_offset"] = offset + len(res.items)
return out


@tool(
"get_topic",
"Get a topic",
"One topic: its labels and definition, its broader, narrower and related topics, and the recordings about it "
"(accepted, and suggested ones waiting for someone), each with a url.",
Arg("topic_id", "integer", "the topic (from list_topics or the graph's t<id>)", required=True),
)
def get_topic(ctx: Context, topic_id: int) -> dict[str, Any]:
d = topic_routes.get_topic(topic_id, ctx.user, ctx.acl, ctx.db)
return {
"topic_id": d.id,
"label": d.label,
"namespace": d.namespace,
"also": d.alt or None,
"definition": d.definition,
"broader": [{"topic_id": x.id, "label": x.label} for x in d.broader],
"narrower": [{"topic_id": x.id, "label": x.label} for x in d.narrower],
"related": [{"topic_id": x.id, "label": x.label} for x in d.related],
"recordings": [{"recording_id": a.recording, "title": a.title, "status": a.status, "url": ctx.link(a.recording)} for a in d.about],
}


@tool(
"suggest_topic",
"Suggest a topic for recordings",
"Say recordings are about a topic, as a suggestion that waits for someone to accept it on the recording or the "
"topic. What they accepted or dismissed stays. Needs a token with the write scope and editor access.",
Arg("topic_id", "integer", "the topic", required=True),
Arg("recording_ids", "integer[]", "the recordings, in the topic's namespace", required=True, maximum=500),
writes=True,
)
def suggest_topic(ctx: Context, topic_id: int, recording_ids: list[int]) -> dict[str, Any]:
if not ctx.user.can_write:
raise ToolError("this token is read-only: ask for a token with the write scope to suggest topics")
row = ctx.db.one("SELECT space FROM $r", r=R("topic", int(topic_id)))
if not row:
raise KeyError(topic_id)
ctx.acl.need(row["space"], "editor")
for rid in recording_ids:
ctx.acl.recording(rid)
made = topicmod.propose(ctx.db, topic_id, recording_ids, "assistant", ctx.user.email)
return {"suggested_for": made, "waiting": "for someone to accept on the recording or the topic"}


@tool(
"propose_graph_change",
"Propose a change to the graph",
Expand Down
2 changes: 1 addition & 1 deletion fastapi_backend/app/api/v1/routes/notebook.py
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ def link_targets(

@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, collection or speaker: its page, or a draft while nobody has written one."""
"""The page of a recording, entity, topic, collection or speaker: its page, or a draft while nobody has written one."""
thing = f"{kind}:{key}"
with domain_errors():
notebook._about(thing)
Expand Down
Loading
Loading