From 3a413c7e0f783f80006cfa1ddcc8c5640babacfc Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 4 Oct 2026 11:55:52 +0000 Subject: [PATCH] feat(topics): a controlled vocabulary of topics, apart from entities Each namespace keeps topics as SKOS concepts: a label, other labels, a definition, and broader, narrower and related topics. Recordings are about topics (said by a person, or brought over when a TERM entity becomes a topic, which hides the entity until the topic is deleted). Editors create, edit, merge and delete topics through /api/v1/topics. Topics are in the property graph (Topic, ABOUT, NARROWER, RELATED; TERM entities are labelled Term there) and in RDF (/id/topic/). docs/topics.md. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_012Jo1JNziunMs8MgWJSGyyM --- CHANGELOG.md | 7 + DEVLOG.md | 23 +- docs/graph.md | 18 +- docs/rdf.md | 1 + docs/topics.md | 81 + fastapi_backend/app/api/linked_data.py | 7 + fastapi_backend/app/api/v1/router.py | 2 + fastapi_backend/app/api/v1/routes/topics.py | 162 + fastapi_backend/app/domain/deletion.py | 1 + fastapi_backend/app/domain/graph_ask.py | 4 + fastapi_backend/app/domain/graph_model.py | 93 +- fastapi_backend/app/domain/moving.py | 2 + fastapi_backend/app/domain/rdf.py | 75 +- fastapi_backend/app/domain/store.py | 8 + fastapi_backend/app/domain/topics.py | 457 +++ fastapi_backend/app/schemas/topics.py | 90 + fastapi_backend/tests/api/test_topics.py | 119 + mkdocs.yml | 1 + nextjs-frontend/app/openapi-client/index.ts | 56 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 173 + .../app/openapi-client/types.gen.ts | 571 ++++ nextjs-frontend/openapi.json | 2983 +++++++++++------ 22 files changed, 3925 insertions(+), 1009 deletions(-) create mode 100644 docs/topics.md create mode 100644 fastapi_backend/app/api/v1/routes/topics.py create mode 100644 fastapi_backend/app/domain/topics.py create mode 100644 fastapi_backend/app/schemas/topics.py create mode 100644 fastapi_backend/tests/api/test_topics.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 6803fa66a..102f197a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,13 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version ## Unreleased +- **Topics, apart from entities.** Each namespace has a controlled vocabulary of topics (SKOS): a label, other + labels, a definition, and broader, narrower and related topics. Recordings are about topics, said by a person or + brought over when a topic-like entity (type TERM) becomes a topic; the entity is hidden until the topic is deleted. + Editors create, edit, merge and delete topics through `/api/v1/topics`. Topics are in the graph (`Topic`, with + `ABOUT`, `NARROWER` and `RELATED`; TERM entities are now labelled `Term` there) and in RDF (`/id/topic/`). See + docs/topics.md. + - **Query the graph in Cypher, and walk it.** The archive is now a property graph of namespaces, collections, recordings, speakers and entities. `POST /api/v1/graph/query` runs read-only Cypher (the language of Neo4j and ISO GQL) over the namespaces you can read; `/graph/related` gives a node's parents, children, ancestors, descendants or diff --git a/DEVLOG.md b/DEVLOG.md index 121a31793..eb38893d2 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -2,6 +2,27 @@ Plans and progress for work in flight. Newest first. +## 2026-10-04 · Topics: a controlled vocabulary apart from entities + +Goal (Adeel): entities and topics are mixed (a topic is an entity of type TERM, which is also the fallback type for +anything unclassified). Separate them: topics become a SKOS controlled vocabulary per namespace (preferred and +alternative labels, a definition, broader, narrower and related topics), and recordings are about topics. Entities +stay the named things (people, organisations, places...) and later become authority records. Decided: after the graph +PRs (done, #111 #121). + +Todo: + +- [x] Vocabulary in the backend: topics with labels, definition, broader/narrower/related; recordings about topics; + create, edit, merge, delete; turn a TERM entity into a topic (and back, by deleting the topic); API with viewer + reads and editor changes; topics in the property graph (Topic, ABOUT, NARROWER, RELATED) and in RDF as SKOS +- [ ] Topics page: the tree of broader and narrower topics, a topic's recordings, edit and merge; a recording's topics +- [ ] 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 + +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. + ## 2026-10-04 · anytopdf as the conversion engine (not started: wait for Adeel's go) Goal (Adeel): use the sister project [anytopdf-rs](https://github.com/adeelahmad/anytopdf-rs) (README on its sprint2 @@ -73,7 +94,7 @@ Todo: ancestors, descendants, neighbours and paths - [x] Questions in plain language: the question becomes Cypher (shown, editable), the answer lights up on the canvas - [x] Assistant and MCP tools: graph schema, query, related, paths; proposing changes behind an approval -- [ ] Topics as a controlled vocabulary (SKOS), apart from entities (authority records); next, after the graph PRs (Adeel) +- [ ] Topics as a controlled vocabulary (SKOS), apart from entities (authority records): started, see "Topics" above ## 2026-10-03 · Assistant extensions: tools, skills, hooks, plugins diff --git a/docs/graph.md b/docs/graph.md index f0cd6fe84..f1efca325 100644 --- a/docs/graph.md +++ b/docs/graph.md @@ -5,8 +5,8 @@ live from the database (`app/domain/graph_model.py`), so it is never out of step Status: **built**: the graph model, walking it (parents, children, ancestors, descendants, neighbours, paths), read-only Cypher and asking for changes over the API; the explorer canvas (drag, one-click layouts, a node menu, -touch); questions in plain language; graph tools for the assistant and MCP. **Planned**: topics as a controlled -vocabulary (SKOS), apart from entities. +touch); questions in plain language; graph tools for the assistant and MCP; topics as each namespace's controlled +vocabulary (SKOS), apart from entities. **Planned**: topics on the explorer canvas as their own kind of node. ## The explorer @@ -36,8 +36,9 @@ Graph in the sidebar shows the graph of the scope picked at the top (one namespa | Recording | `r` | name (the title), date, media, namespace | | Speaker | `s` | name, seconds (talk time), namespace | | Entity | `e`, or `e:` in the global scope | name, type, key, mentions, namespaces, ids | +| Topic | `t`, or `t:` in the global scope | name (the label), alt, definition, recordings, namespaces, ids | -An entity has its type as a second label: `Person`, `Organisation`, `Product`, `Place`, `Event`, `Work`, `Topic`, or +An entity has its type as a second label: `Person`, `Organisation`, `Product`, `Place`, `Event`, `Work`, `Term`, or a namespace's own type (`MY_TYPE` becomes `MyType`). Every node also has `id`, `name` and `namespace`. Hidden entities and quiet types (dates and numbers) are left out, as in the overview graph. @@ -51,9 +52,13 @@ and quiet types (dates and numbers) are left out, as in the overview graph. | SPOKE_WITH | Speaker → Speaker (in the same recording) | recordings | | SAME_AS | Speaker → Speaker (said to be one person) | | | SAME_THING | Entity → Entity (linked across namespaces) | | +| ABOUT | Recording → Topic | source, weight | +| NARROWER | Topic → Topic (from the broader one) | | +| RELATED | Topic → Topic | | -CONTAINS, HAS_SPEAKER, MENTIONS and SAID are the hierarchy: an entity's parents are the recordings that mention it and -the speakers who said it; its ancestors go on up to collections and the namespace. +CONTAINS, HAS_SPEAKER, MENTIONS, SAID, ABOUT and NARROWER are the hierarchy: an entity's parents are the recordings that +mention it and the speakers who said it; its ancestors go on up to collections and the namespace. A topic's parents +are its broader topics and the recordings about it. Topics are each namespace's vocabulary ([Topics](topics.md)). ## Scope and rights @@ -147,8 +152,7 @@ MATCH (c:Collection {name: 'Interviews'})-[:CONTAINS*1..8]->(r:Recording) RETURN ## Refine later -- Topics as SKOS concepts in schemes (broader, narrower, related), apart from entities, which become authority records - with preferred and variant names and external identifiers. +- Entities as authority records, with preferred and variant names and external identifiers. - More change kinds for agents (rename, retype, hide, unlink), and Cypher write clauses mapped to proposed changes. - Collections people were given a role on (without a namespace role) aren't in the graph yet. - `EXISTS { }` subqueries and pattern predicates in `WHERE`. diff --git a/docs/rdf.md b/docs/rdf.md index 05ec5ce0b..cbc365407 100644 --- a/docs/rdf.md +++ b/docs/rdf.md @@ -18,6 +18,7 @@ URIs use the address Lens publishes (`iiif.base_url`, or the address a request a | `/id/collection/` | a collection (`dcmitype:Collection`), `dcterms:isPartOf` its parent or its namespace | | `/id/namespace/` | a namespace: a `dcmitype:Collection` and the `skos:ConceptScheme` of its entities | | `/id/entity/` | a `skos:Concept`, also `foaf:Person`, `foaf:Organization`, `dcterms:Location` or `dcmitype:Event` depending on its type | +| `/id/topic/` | a topic: a `skos:Concept` in `/id/namespace/#topics` (the namespace's `skos:ConceptScheme` of topics), with `skos:broader`, `skos:narrower` and `skos:related`; recordings about it name it as `dcterms:subject` ([Topics](topics.md)) | | `/id/speaker/` | a `foaf:Person`, `owl:sameAs` the speakers declared to be the same person | | `/id/field/` | a custom field, used as the property its values are given with | | `/ns` | the Lens vocabulary (`lens:`), in Turtle | diff --git a/docs/topics.md b/docs/topics.md new file mode 100644 index 000000000..879301cbc --- /dev/null +++ b/docs/topics.md @@ -0,0 +1,81 @@ +# Topics + +Each namespace keeps a controlled vocabulary of topics: what its recordings are about. Topics are separate from +entities. Entities are the named things a transcript mentions (people, organisations, products, places); a topic is a +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, topics in the graph and in RDF. **Planned**: a Topics page, +topic suggestions from analysis, `#` links in notes pointing at topics, and assistant and MCP tools for topics. + +## A topic + +A topic follows SKOS, the W3C standard for vocabularies: + +| Field | SKOS | What it is | +| --- | --- | --- | +| label | `skos:prefLabel` | Its name. Unique in the namespace. | +| alt | `skos:altLabel` | Other labels it goes by (synonyms, abbreviations, spellings). Unique in the namespace too. | +| definition | `skos:definition` | What it covers, in your words. | +| broader | `skos:broader` | The wider topics it belongs under. A topic can have several; it can't end up under itself. | +| narrower | `skos:narrower` | The topics that have it as broader (kept from their side). | +| related | `skos:related` | Topics that are related but not broader or narrower. Kept on both sides. | + +Recordings are **about** topics. A person says so, a topic made from an entity brings the recordings that mention +it, and (planned) analysis suggests topics for someone to accept. Each link records where it came from (`person`, +`entity`, `analysis`) and whether it holds (`accepted`) or waits (`suggested`). + +## Topics and entities + +Until now a topic was an entity of type TERM, which is also the type analysis gives anything it can't classify. Turn +such an entity into a topic (`POST /api/v1/entities/{id}/topic`): its name becomes the label, its aliases the other +labels, its description the definition, and the recordings that mention it are about the topic. The entity is hidden +while the topic exists; deleting the topic shows it again. If the namespace already has a topic of that name, the +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. + +## 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`). + +## The API + +| Call | What it does | +| --- | --- | +| `GET /api/v1/topics?ns=&q=&top=&broader=` | Topics by label, with how many recordings are about each and how many narrower topics it has. | +| `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. | +| `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. | + +## In the graph and in RDF + +In the property graph ([The graph](graph.md)) a topic is a `Topic` node `t`, and recordings link to it with +`ABOUT`; broader topics link to narrower ones with `NARROWER`, and related ones with `RELATED`. ABOUT and NARROWER are +part of the hierarchy, so a topic's ancestors are its broader topics and the recordings about it. TERM entities are +labelled `Term` there, so they aren't confused with topics. + +```cypher +// recordings about gene therapy or anything narrower +MATCH (t:Topic)-[:NARROWER*0..6]->(n:Topic)<-[:ABOUT]-(r:Recording) +WHERE toLower(t.name) = 'gene therapy' +RETURN DISTINCT r.name, n.name +``` + +In RDF ([Linked data](rdf.md)) a topic is `/id/topic/`, a `skos:Concept` in the namespace's vocabulary +`/id/namespace/#topics` (a `skos:ConceptScheme`), and recordings name the topics they are about as +`dcterms:subject`. + +## Refine later + +- 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. diff --git a/fastapi_backend/app/api/linked_data.py b/fastapi_backend/app/api/linked_data.py index f5a6f8d0e..92f9cf3d6 100644 --- a/fastapi_backend/app/api/linked_data.py +++ b/fastapi_backend/app/api/linked_data.py @@ -80,6 +80,13 @@ def entity(eid: int, request: Request, acl: Acl, db: Db, cfg: Cfg, format: str | return rdf_response(rdf.entity_graph(db, base, eid), fmt) if fmt else _see(f"{base}/entities/{eid}") +@router.get("/id/topic/{tid}") +def topic(tid: int, request: Request, acl: Acl, db: Db, cfg: Cfg, format: str | None = FORMAT) -> Response: + _member_of(acl, (db.one("SELECT space FROM $r", r=R("topic", tid)) or {}).get("space")) + base, fmt = base_url(request, cfg), wanted(request, format) + return rdf_response(rdf.topic_graph(db, base, tid), fmt) if fmt else _see(f"{base}/topics/{tid}") + + @router.get("/id/speaker/{sid}") def speaker(sid: int, request: Request, acl: Acl, db: Db, cfg: Cfg, format: str | None = FORMAT) -> Response: space = (db.one("SELECT space FROM $r", r=R("speaker", sid)) or {}).get("space") diff --git a/fastapi_backend/app/api/v1/router.py b/fastapi_backend/app/api/v1/router.py index e472f9ee7..50588f0e9 100644 --- a/fastapi_backend/app/api/v1/router.py +++ b/fastapi_backend/app/api/v1/router.py @@ -44,6 +44,7 @@ sources, speakers, templates, + topics, uploads, users, vaults, @@ -79,6 +80,7 @@ searches, speakers, entities, + topics, graph, entity_setup, metadata, diff --git a/fastapi_backend/app/api/v1/routes/topics.py b/fastapi_backend/app/api/v1/routes/topics.py new file mode 100644 index 000000000..f4126648f --- /dev/null +++ b/fastapi_backend/app/api/v1/routes/topics.py @@ -0,0 +1,162 @@ +"""Topics: each namespace's controlled vocabulary (docs/topics.md), and which recordings are about which topic. + +Reads cover the namespaces you have a role in; changes need the editor role there. Each change drops the cached +knowledge graph, which shows topics too. +""" + +from __future__ import annotations + +from fastapi import APIRouter, HTTPException, Request + +from app.api.deps import Access, Acl, CurrentUser, Db, Writer, domain_errors +from app.domain import auth, topics +from app.domain.store import DB, R +from app.schemas.common import Ok +from app.schemas.topics import ( + RecordingTopic, + TopicCreate, + TopicDetail, + TopicList, + TopicMerge, + TopicRecordings, + TopicUpdate, +) + +router = APIRouter(tags=["topics"]) + + +def _topic_space(db: DB, acl: Access, tid: int, role: str = "viewer") -> int: + row = db.one("SELECT space FROM $r", r=R("topic", int(tid))) + if not row: + raise HTTPException(404, "not found") + acl.need(row["space"], role) + return row["space"] + + +def _changed(request: Request) -> None: + request.app.state.graph_cache.clear() + + +def _detail(db: DB, acl: Access, tid: int) -> TopicDetail: + return TopicDetail.model_validate(topics.detail(db, tid)) + + +@router.get("/topics") +def list_topics( + user: CurrentUser, + acl: Acl, + db: Db, + q: str = "", + ns: str = "", + top: bool = False, + broader: int | None = None, + limit: int = 200, + offset: int = 0, +) -> TopicList: + """Topics of the namespaces you can read (or of `ns`), by label. `q` matches labels and other labels, `top` keeps + those with no broader topic, `broader` lists the narrower topics of one.""" + spaces = set(acl.roles) + if ns: + sid = acl.nsid(ns) + acl.need(sid) + spaces = {sid} + if broader is not None: + _topic_space(db, acl, broader) + return TopicList.model_validate(topics.list_topics(db, spaces, q, top, broader, limit, offset)) + + +@router.get("/topics/{tid}") +def get_topic(tid: int, user: CurrentUser, acl: Acl, db: Db) -> TopicDetail: + """A topic with its broader, narrower and related topics and the recordings about it.""" + _topic_space(db, acl, tid) + return _detail(db, acl, tid) + + +@router.post("/namespaces/{name}/topics", status_code=201) +def create_topic(name: str, body: TopicCreate, request: Request, user: Writer, acl: Acl, db: Db) -> TopicDetail: + """Add a topic to the namespace's vocabulary.""" + sid = acl.nsid(name) + acl.need(sid, "editor") + with domain_errors(): + tid = topics.create(db, sid, body.label, body.alt, body.definition, body.broader, body.related, user=user.email) + auth.audit(db, user.as_audit(), "topic.create", f"topic:{tid}", body.model_dump()) + _changed(request) + return _detail(db, acl, tid) + + +@router.patch("/topics/{tid}") +def update_topic(tid: int, body: TopicUpdate, request: Request, user: Writer, acl: Acl, db: Db) -> TopicDetail: + """Rename it, change its other labels or definition, or what it is narrower than or related to.""" + _topic_space(db, acl, tid, "editor") + changes = body.model_dump(exclude_unset=True) + with domain_errors(): + topics.update( + db, + tid, + body.label, + body.alt, + body.definition or None, + body.broader, + body.related, + user=user.email, + clear_definition="definition" in changes and not body.definition, + ) + auth.audit(db, user.as_audit(), "topic.update", f"topic:{tid}", changes) + _changed(request) + return _detail(db, acl, tid) + + +@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.""" + _topic_space(db, acl, tid, "editor") + with domain_errors(): + eid = topics.delete(db, tid) + auth.audit(db, user.as_audit(), "topic.delete", f"topic:{tid}", {"entity": eid} if eid else None) + _changed(request) + return Ok() + + +@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.""" + for t in [body.keep, *body.others]: + _topic_space(db, acl, t, "editor") + with domain_errors(): + 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) + + +@router.post("/topics/{tid}/recordings") +def tag_recordings(tid: int, body: TopicRecordings, request: Request, user: Writer, acl: Acl, db: Db) -> TopicDetail: + """Say recordings of the topic's namespace are about it (accepting suggestions too), or with `remove` that they aren't.""" + _topic_space(db, acl, tid, "editor") + with domain_errors(): + topics.tag(db, tid, body.recordings, body.remove, user=user.email) + auth.audit(db, user.as_audit(), "topic.untag" if body.remove else "topic.tag", f"topic:{tid}", {"recordings": body.recordings}) + _changed(request) + return _detail(db, acl, tid) + + +@router.get("/recordings/{rid}/topics") +def recording_topics(rid: int, user: CurrentUser, acl: Acl, db: Db) -> list[RecordingTopic]: + """The topics a recording is about, and those suggested for it.""" + acl.recording(rid) + return [RecordingTopic(**t) for t in topics.of_recording(db, rid)] + + +@router.post("/entities/{eid}/topic", status_code=201) +def entity_to_topic(eid: int, request: Request, user: Writer, acl: Acl, db: Db) -> TopicDetail: + """Make a topic-like entity (type TERM) a topic: its names become the topic's labels and the recordings that + mention it are about the topic. The entity is hidden; deleting the topic shows it again.""" + row = db.one("SELECT space FROM $r", r=R("entity", int(eid))) + if not row: + raise HTTPException(404, "not found") + acl.need(row["space"], "editor") + with domain_errors(): + tid = topics.from_entity(db, eid, user=user.email) + auth.audit(db, user.as_audit(), "topic.from_entity", f"topic:{tid}", {"entity": eid}) + _changed(request) + return _detail(db, acl, tid) diff --git a/fastapi_backend/app/domain/deletion.py b/fastapi_backend/app/domain/deletion.py index 2657b6db8..d70003fd3 100644 --- a/fastapi_backend/app/domain/deletion.py +++ b/fastapi_backend/app/domain/deletion.py @@ -26,6 +26,7 @@ OWN = ( "mentions", "term", + "topic_about", "section", "appearance", "segment", diff --git a/fastapi_backend/app/domain/graph_ask.py b/fastapi_backend/app/domain/graph_ask.py index 68e9f4949..74479cfb8 100644 --- a/fastapi_backend/app/domain/graph_ask.py +++ b/fastapi_backend/app/domain/graph_ask.py @@ -30,6 +30,10 @@ "ask": "How is Alice connected to Acme?", "cypher": "MATCH p = shortestPath((s:Speaker {name: 'Alice'})-[*..6]-(e:Entity {name: 'Acme'})) RETURN [n IN nodes(p) | n.name] AS chain", }, + { + "ask": "Which recordings are about gene therapy, or anything narrower?", + "cypher": "MATCH (t:Topic)-[:NARROWER*0..6]->(n:Topic)<-[:ABOUT]-(r:Recording) WHERE toLower(t.name) = 'gene therapy' RETURN DISTINCT r, r.name, n.name", + }, { "ask": "Everything in the Interviews collection", "cypher": "MATCH (c:Collection {name: 'Interviews'})-[:CONTAINS*1..8]->(r:Recording) RETURN r.name, r.date ORDER BY r.date DESC", diff --git a/fastapi_backend/app/domain/graph_model.py b/fastapi_backend/app/domain/graph_model.py index 32d08b10f..6ba30b00d 100644 --- a/fastapi_backend/app/domain/graph_model.py +++ b/fastapi_backend/app/domain/graph_model.py @@ -7,8 +7,10 @@ - `r` Recording {title, date, media} - `s` Speaker {seconds: talk time} - `e` Entity {type, key, mentions}, with its type as a second label (Person, Organisation, Product, Place, Event, - Work, Topic, or a namespace's own type). In the global scope, entities with the same name in different namespaces + Work, Term, or a namespace's own type). In the global scope, entities with the same name in different namespaces are one node, `e:`, as in the overview graph (graph.py); `ids` lists the entities behind it. +- `t` Topic {alt, definition, recordings}: a topic of the namespace's vocabulary (topics.py). In the global scope, + topics with the same label are one node, `t:`, like entities. Relationships, all directed (a query may ignore the direction): @@ -20,8 +22,12 @@ - SPOKE_WITH: Speaker -> Speaker, in the same recording {recordings} - SAME_AS: Speaker -> Speaker (someone said they are the same person) - SAME_THING: Entity -> Entity (linked across namespaces) +- ABOUT: Recording -> Topic, the recording is about it {source, weight} +- NARROWER: Topic -> Topic, from a broader topic to a narrower one (skos:narrower) +- RELATED: Topic -> Topic (skos:related) -CONTAINS, HAS_SPEAKER, MENTIONS and SAID make the hierarchy that parents, children, ancestors and descendants follow. +CONTAINS, HAS_SPEAKER, MENTIONS, SAID, ABOUT and NARROWER make the hierarchy that parents, children, ancestors and +descendants follow, so a topic's parents are its broader topics and the recordings about it. A projection covers whole namespaces only: the ones a caller can read, one of them (`ns:`, isolated ones too), or every shared one (`global`). Hidden entities and quiet types (dates, numbers) are left out, as in the explorer. @@ -37,9 +43,21 @@ from .entities import QUIET, TYPES R = store.R -REL_TYPES = ("CONTAINS", "HAS_SPEAKER", "MENTIONS", "SAID", "MENTIONED_WITH", "SPOKE_WITH", "SAME_AS", "SAME_THING") -HIERARCHY = ("CONTAINS", "HAS_SPEAKER", "MENTIONS", "SAID") -NODE_LABELS = ("Namespace", "Collection", "Recording", "Speaker", "Entity") +REL_TYPES = ( + "CONTAINS", + "HAS_SPEAKER", + "MENTIONS", + "SAID", + "MENTIONED_WITH", + "SPOKE_WITH", + "SAME_AS", + "SAME_THING", + "ABOUT", + "NARROWER", + "RELATED", +) +HIERARCHY = ("CONTAINS", "HAS_SPEAKER", "MENTIONS", "SAID", "ABOUT", "NARROWER") +NODE_LABELS = ("Namespace", "Collection", "Recording", "Speaker", "Entity", "Topic") # the overview graph's edge kinds (graph.py, the web app's legend) for the relationship types that have one KIND = { "SAID": "mentions", @@ -50,6 +68,9 @@ "CONTAINS": "contains", "HAS_SPEAKER": "speaks in", "MENTIONS": "mentioned in", + "ABOUT": "about", + "NARROWER": "narrower", + "RELATED": "related", } RELATIONS = ("children", "parents", "ancestors", "descendants", "neighbours") MAX_RESULTS = 2000 @@ -79,7 +100,10 @@ def __repr__(self): def type_label(t): - """An entity type as a node label: PERSON -> Person, ORG -> Organisation, a namespace's own MY_TYPE -> MyType.""" + """An entity type as a node label: PERSON -> Person, ORG -> Organisation, a namespace's own MY_TYPE -> MyType. TERM + is Term here, so it isn't mistaken for the vocabulary's topics (Topic).""" + if t == "TERM": + return "Term" if t in TYPES: return TYPES[t] return "".join(w.capitalize() for w in re.split(r"[^A-Za-z0-9]+", str(t)) if w) or "Entity" @@ -127,15 +151,16 @@ def edges(self, nid, direction="both", types=None): yield r, r.start def resolve(self, ref): - """A node id as people and agents write it: e12 (also inside a merged global entity), e:, s4, r9, c2, n1.""" + """A node id as people and agents write it: e12 or t3 (also inside a merged global entity or topic), e:, + t:, s4, r9, c2, n1.""" ref = str(ref or "").strip() if ref in self.nodes: return ref - m = re.fullmatch(r"e(\d+)", ref) + m = re.fullmatch(r"([et])(\d+)", ref) if m: - eid = int(m.group(1)) - for nid in self.by_label.get("Entity", ()): - if eid in (self.nodes[nid].props.get("ids") or ()): + i = int(m.group(2)) + for nid in self.by_label.get("Entity" if m.group(1) == "e" else "Topic", ()): + if i in (self.nodes[nid].props.get("ids") or ()): return nid raise KeyError(ref) @@ -283,9 +308,55 @@ def build(db, scope="global", readable=None, recordings=None): a, b = node_of.get(ln["a"]), node_of.get(ln["b"]) if a and b and a != b: g.link("SAME_THING", a, b) + _topics(g, db, sids, names, merged, keep, only_about=recordings is not None) return g +def _topics(g, db, sids, names, merged, keep, only_about=False): + """The vocabularies' topics, the recordings about them and how they nest. `only_about`: just the topics recordings + in the graph are about (a conversation limited to some recordings).""" + rows = db.rows("SELECT record::id(id) AS id, space, key, label, alt, definition, broader, related FROM topic WHERE space IN $s", s=sids) + about = db.rows("SELECT recording, topic, source, weight FROM topic_about WHERE space IN $s AND status = 'accepted'", s=sids) + about = [a for a in about if keep(a["recording"])] + if only_about: + wanted = {a["topic"] for a in about} + rows = [t for t in rows if t["id"] in wanted] + node_of = {} + for t in rows: + nid = f"t:{t['key']}" if merged else f"t{t['id']}" + node_of[t["id"]] = nid + n = g.nodes.get(nid) + if n is None: + g.add( + nid, + ["Topic"], + name=t["label"], + key=t["key"], + namespace=names[t["space"]], + namespaces=[names[t["space"]]], + alt=t.get("alt") or [], + definition=t.get("definition"), + recordings=0, + ids=[t["id"]], + ) + else: + n.props["namespaces"] = sorted({*n.props["namespaces"], names[t["space"]]}) + n.props["namespace"] = None if len(n.props["namespaces"]) > 1 else n.props["namespace"] + n.props["ids"] = sorted({*n.props["ids"], t["id"]}) + n.props["alt"] = sorted({*n.props["alt"], *(t.get("alt") or [])}) + for t in rows: + for b in t.get("broader") or []: + if b in node_of: + g.link("NARROWER", node_of[b], node_of[t["id"]]) + for r in t.get("related") or []: + if r in node_of and t["id"] < r: + g.link("RELATED", node_of[t["id"]], node_of[r]) + for a in about: + nid = node_of.get(a["topic"]) + if nid and g.link("ABOUT", f"r{a['recording']}", nid, source=a.get("source"), weight=a.get("weight")): + g.nodes[nid].props["recordings"] += 1 + + _ENTITY_FIELDS = "record::id(id) AS id, space, key, name, type, hidden" diff --git a/fastapi_backend/app/domain/moving.py b/fastapi_backend/app/domain/moving.py index 9a7595255..f06e834af 100644 --- a/fastapi_backend/app/domain/moving.py +++ b/fastapi_backend/app/domain/moving.py @@ -184,6 +184,8 @@ def move(db, cfg, rid, dst, rediarize=False, revoke_shares=False, by=None, colle "DELETE mentions WHERE recording = $r", "DELETE term WHERE recording = $r", "DELETE entity_override WHERE recording = $r", + # and so do topics: the recording is about the new namespace's topics, once someone says which + "DELETE topic_about WHERE recording = $r", "UPDATE ip_group SET recordings = array::complement(recordings, [$r]) WHERE space = $s AND recordings CONTAINS $r", "CREATE $g CONTENT $note", "UPDATE $rec SET space = $d, collection = $home" + (", fp_key = $k" if fp else ""), diff --git a/fastapi_backend/app/domain/rdf.py b/fastapi_backend/app/domain/rdf.py index 01ed676d2..e5228adf5 100644 --- a/fastapi_backend/app/domain/rdf.py +++ b/fastapi_backend/app/domain/rdf.py @@ -12,6 +12,9 @@ /id/entity/ a skos:Concept (also foaf:Person, foaf:Organization, dcterms:Location or dcmitype:Event by its type), with owl:sameAs to the same thing in other namespaces /id/speaker/ a foaf:Person, with owl:sameAs to the speakers declared the same person + /id/topic/ a skos:Concept of the namespace's topics (`/id/namespace/#topics`, a skos:ConceptScheme), + with its labels, definition and skos:broader, skos:narrower and skos:related topics; recordings + about it name it as dcterms:subject /id/field/ a custom field (fields.py), used as the property its values are given with The Lens vocabulary is `
/ns#` (served there, as Turtle). Refine later: a permanent vocabulary address shared by @@ -70,6 +73,13 @@ def namespace(self, name): def entity(self, eid): return URIRef(f"{self.base}/id/entity/{int(eid)}") + def topic(self, tid): + return URIRef(f"{self.base}/id/topic/{int(tid)}") + + def topics(self, name): + """A namespace's vocabulary of topics.""" + return URIRef(f"{self.namespace(name)}#topics") + def speaker(self, sid): return URIRef(f"{self.base}/id/speaker/{int(sid)}") @@ -123,9 +133,10 @@ def _namespace_name(db, sid): return (db.one("SELECT name FROM $s", s=R("space", sid)) or {}).get("name") -def add_recording(g, db, cfg, u: Uris, rid, member=False, entities=None): - """A recording's description. `member`: the requester has a role where it is (entities, access, internal fields). - `entities` collects the entities it references, for the caller to describe (add_entities).""" +def add_recording(g, db, cfg, u: Uris, rid, member=False, entities=None, topics=None): + """A recording's description. `member`: the requester has a role where it is (entities, topics, access, internal + fields). `entities` and `topics` collect the entities it references and the topics it is about, for the caller to + describe (add_entities, add_topics).""" rid = int(rid) row = db.one("SELECT space, collection, source, media, path, duration_ms, title FROM $r", r=R("recording", rid)) if not row: @@ -230,6 +241,10 @@ def add_recording(g, db, cfg, u: Uris, rid, member=False, entities=None): for i in ids: if i in shown: g.add((s, DCTERMS.references, u.entity(i))) + for t in db.values("SELECT VALUE topic FROM topic_about WHERE recording = $r AND status = 'accepted'", r=rid): + g.add((s, DCTERMS.subject, u.topic(t))) + if topics is not None: + topics.add(int(t)) defs, frow = fieldsmod.resource_fields(db, rid) vals = fieldsmod.values_of(frow) for f in defs: @@ -278,6 +293,46 @@ def add_entities(g, db, u: Uris, eids): g.add((u.entity(link["a"]), OWL.sameAs, u.entity(link["b"]))) +def add_topics(g, db, u: Uris, tids): + """Topics as SKOS concepts of their namespace's vocabulary, with how they nest and relate.""" + tids = sorted({int(t) for t in tids}) + if not tids: + return + rows = db.rows( + "SELECT record::id(id) AS id, space, label, alt, definition, broader, related FROM topic WHERE id IN $ids", + ids=[R("topic", i) for i in tids], + ) + names = {} + for t in rows: + if t["space"] not in names: + names[t["space"]] = _namespace_name(db, t["space"]) + scheme = u.topics(names[t["space"]]) + s = u.topic(t["id"]) + g.add((s, RDF.type, SKOS.Concept)) + g.add((s, RDF.type, u.vocab.Topic)) + g.add((s, SKOS.prefLabel, Literal(t["label"]))) + for a in t.get("alt") or []: + g.add((s, SKOS.altLabel, Literal(a))) + if t.get("definition"): + g.add((s, SKOS.definition, Literal(t["definition"]))) + g.add((s, SKOS.inScheme, scheme)) + g.add((scheme, RDF.type, SKOS.ConceptScheme)) + g.add((scheme, DCTERMS.title, Literal(f"Topics of {names[t['space']]}"))) + if t.get("broader"): + for b in t["broader"]: + g.add((s, SKOS.broader, u.topic(b))) + g.add((u.topic(b), SKOS.narrower, s)) + else: + g.add((s, SKOS.topConceptOf, scheme)) + g.add((scheme, SKOS.hasTopConcept, s)) + for r in t.get("related") or []: + g.add((s, SKOS.related, u.topic(r))) + for n in db.rows("SELECT record::id(id) AS id, broader FROM topic WHERE broader CONTAINSANY $t", t=tids): + for b in n.get("broader") or []: + if b in tids: + g.add((u.topic(b), SKOS.narrower, u.topic(n["id"]))) + + def add_speakers(g, db, u: Uris, space=None, ids=None): """A namespace's speakers (or the ones in `ids`) as people, linked to those declared the same person.""" if ids is not None: @@ -328,10 +383,11 @@ def add_collection(g, db, u: Uris, c, ns_name): def recording_graph(db, cfg, base, rid, member=False): u = Uris(base) g = new_graph(u) - ents = set() - add_recording(g, db, cfg, u, rid, member, ents) + ents, tops = set(), set() + add_recording(g, db, cfg, u, rid, member, ents, tops) if member: add_entities(g, db, u, ents) + add_topics(g, db, u, tops) return g @@ -348,6 +404,7 @@ def namespace_graph(db, cfg, base, sid): add_recording(g, db, cfg, u, rid, True, ents) ents |= set(db.values("SELECT VALUE record::id(id) FROM entity WHERE space = $s", s=sid)) add_entities(g, db, u, ents) + add_topics(g, db, u, db.values("SELECT VALUE record::id(id) FROM topic WHERE space = $s", s=sid)) add_speakers(g, db, u, space=sid) return g @@ -366,6 +423,13 @@ def entity_graph(db, base, eid): return g +def topic_graph(db, base, tid): + u = Uris(base) + g = new_graph(u) + add_topics(g, db, u, [tid]) + return g + + def collection_graph(db, base, cid): u = Uris(base) g = new_graph(u) @@ -392,6 +456,7 @@ def vocabulary(base): (v.Collection, "A collection of items inside a namespace."), (v.Namespace, "A namespace: a separate archive, with its own collections, people, entities and settings."), (v.Entity, "A named thing found in, or defined for, a namespace."), + (v.Topic, "A topic of a namespace's controlled vocabulary: what its items are about."), ): g.add((cls, RDF.type, OWL.Class)) g.add((cls, RDFS.comment, Literal(label, lang="en"))) diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index 78ae2702a..df673ce28 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -676,6 +676,14 @@ def close(self): "DEFINE INDEX IF NOT EXISTS term_rec ON term FIELDS recording", "DEFINE INDEX IF NOT EXISTS term_space ON term FIELDS space", "DEFINE INDEX IF NOT EXISTS term_term ON term FIELDS term", + # each namespace's controlled vocabulary of topics, and which recordings are about which topic (app/domain/topics.py) + "DEFINE TABLE IF NOT EXISTS topic SCHEMALESS", + "DEFINE INDEX IF NOT EXISTS topic_space ON topic FIELDS space", + "DEFINE INDEX IF NOT EXISTS topic_key ON topic FIELDS tkey UNIQUE", + "DEFINE TABLE IF NOT EXISTS topic_about SCHEMALESS", + "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", # 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", diff --git a/fastapi_backend/app/domain/topics.py b/fastapi_backend/app/domain/topics.py new file mode 100644 index 000000000..9ef124fe7 --- /dev/null +++ b/fastapi_backend/app/domain/topics.py @@ -0,0 +1,457 @@ +"""Topics: each namespace's controlled vocabulary of what its recordings are about, apart from its entities. + +Entities are the named things a transcript mentions (people, organisations, places...). A topic is a subject someone +chose for the vocabulary, as a SKOS concept: a preferred label, other labels it goes by, a definition, broader and +related topics. Narrower topics are the ones that name it as broader. Recordings are about topics (`topic_about`), +put there by a person, by turning an entity of type TERM into a topic, or (suggested) by analysis. + + topic {space, key, tkey: ":", label, alt: [labels], definition, broader: [ids], related: [ids], + origin: {entity}, created, updated, by} + topic_about topic_about:⟨"-"⟩ {space, recording, topic, source, weight, status, at, by} + +`source` says how a recording came to be about a topic (person, entity, analysis) and `status` whether it holds +(accepted) or waits for someone to accept it (suggested). Labels are unique within a namespace, alternative labels too. +A topic made from an entity hides that entity; deleting the topic shows it again. Callers check roles and write the +audit log. +""" + +from __future__ import annotations + +from collections import Counter + +from . import analyze, store + +R = store.R +FIELDS = "record::id(id) AS id, space, key, label, alt, definition, broader, related, origin, created, updated, by" +LABEL_MAX = 200 +ALT_MAX = 50 +DEFINITION_MAX = 2000 +LINKS_MAX = 50 +SOURCES = ("person", "entity", "analysis") +STATUSES = ("accepted", "suggested") + + +def key_of(label): + return analyze.ent_key(" ".join(str(label or "").split())) + + +def _topic(db, tid): + t = db.one(f"SELECT {FIELDS} FROM $r", r=R("topic", int(tid))) + if not t: + raise KeyError(tid) + return t + + +def _about_id(rid, tid): + return R("topic_about", f"{int(rid)}-{int(tid)}") + + +def _clean_label(label): + label = " ".join(str(label or "").split()) + if not label: + raise ValueError("Give the topic a label.") + if len(label) > LABEL_MAX: + raise ValueError(f"A label can have up to {LABEL_MAX} characters.") + return label + + +def _clean_alt(alt, label): + out, seen = [], {key_of(label)} + for a in alt or []: + a = " ".join(str(a or "").split()) + k = key_of(a) + if not k or k in seen: + continue + if len(a) > LABEL_MAX: + raise ValueError(f"A label can have up to {LABEL_MAX} characters.") + seen.add(k) + out.append(a) + if len(out) > ALT_MAX: + raise ValueError(f"A topic can have up to {ALT_MAX} other labels.") + return out + + +def _labels_taken(db, sid, keys, but=None): + """The first of `keys` another topic of the namespace already goes by, or None.""" + for t in db.rows("SELECT record::id(id) AS id, key, alt FROM topic WHERE space = $s", s=int(sid)): + if t["id"] == but: + continue + theirs = {t["key"]} | {key_of(a) for a in t.get("alt") or []} + for k in keys: + if k in theirs: + return k + return None + + +def _links(db, sid, ids, own=None, what="broader"): + ids = list(dict.fromkeys(int(i) for i in ids or [])) + if own is not None and own in ids: + raise ValueError(f"A topic can't be {what} than itself.") + if len(ids) > LINKS_MAX: + raise ValueError(f"A topic can have up to {LINKS_MAX} {what} topics.") + if ids: + found = { + t["id"]: t["space"] + for t in db.rows("SELECT record::id(id) AS id, space FROM topic WHERE id IN $ids", ids=[R("topic", i) for i in ids]) + } + for i in ids: + if i not in found: + raise KeyError(i) + if found[i] != int(sid): + raise ValueError("Broader and related topics are in the same namespace.") + return ids + + +def _broader_map(db, sid): + return { + t["id"]: list(t.get("broader") or []) + for t in db.rows("SELECT record::id(id) AS id, broader FROM topic WHERE space = $s", s=int(sid)) + } + + +def _would_loop(db, sid, tid, broader): + """True when making `broader` the broader topics of `tid` would make it broader than itself.""" + up = _broader_map(db, sid) + up[tid] = list(broader) + seen, todo = set(), list(broader) + while todo: + x = todo.pop() + if x == tid: + return True + if x not in seen: + seen.add(x) + todo.extend(up.get(x, [])) + return False + + +def _set_related(db, tid, before, after): + """Related is symmetric: keep the other side in step.""" + for o in set(after) - set(before): + db.q("UPDATE $r SET related = array::union(related ?? [], [$t])", r=R("topic", o), t=tid) + for o in set(before) - set(after): + db.q("UPDATE $r SET related = array::complement(related ?? [], [$t])", r=R("topic", o), t=tid) + + +def create(db, sid, label, alt=(), definition=None, broader=(), related=(), origin=None, user=None): + """A new topic in namespace `sid`; its id.""" + label = _clean_label(label) + alt = _clean_alt(alt, label) + key = key_of(label) + taken = _labels_taken(db, sid, [key] + [key_of(a) for a in alt]) + if taken: + raise ValueError(f"There is already a topic called {taken}.") + definition = _definition(definition) + broader = _links(db, sid, broader) + related = _links(db, sid, related, what="related") + tid = db.next_id("topic") + at = store.now() + db.q( + "CREATE $r CONTENT $d", + r=R("topic", tid), + d=store.clean( + { + "space": int(sid), + "key": key, + "tkey": f"{int(sid)}:{key}", + "label": label, + "alt": alt, + "definition": definition, + "broader": broader, + "related": related, + "origin": origin, + "created": at, + "updated": at, + "by": user, + } + ), + ) + _set_related(db, tid, [], related) + return tid + + +def _definition(text): + if text is None: + return None + text = str(text).strip() + if len(text) > DEFINITION_MAX: + raise ValueError(f"A definition can have up to {DEFINITION_MAX} characters.") + return text or None + + +def update(db, tid, label=None, alt=None, definition=None, broader=None, related=None, user=None, clear_definition=False): + """Change what is given; leave the rest.""" + t = _topic(db, tid) + sid, tid = t["space"], t["id"] + new_label = _clean_label(label) if label is not None else t["label"] + new_alt = _clean_alt(alt if alt is not None else t.get("alt"), new_label) + taken = _labels_taken(db, sid, [key_of(new_label)] + [key_of(a) for a in new_alt], but=tid) + if taken: + raise ValueError(f"There is already a topic called {taken}.") + sets = {"label": new_label, "key": key_of(new_label), "tkey": f"{sid}:{key_of(new_label)}", "alt": new_alt} + if definition is not None or clear_definition: + sets["definition"] = None if clear_definition else _definition(definition) + if broader is not None: + broader = _links(db, sid, broader, own=tid) + if _would_loop(db, sid, tid, broader): + raise ValueError("That would make the topic broader than itself.") + sets["broader"] = broader + if related is not None: + related = _links(db, sid, related, own=tid, what="related") + _set_related(db, tid, t.get("related") or [], related) + sets["related"] = related + sets["updated"] = store.now() + sets["by"] = user + db.q("UPDATE $r MERGE $d", r=R("topic", tid), d=sets) + if "definition" in sets and sets["definition"] is None: + db.q("UPDATE $r SET definition = NONE", r=R("topic", tid)) + return tid + + +def delete(db, tid): + """Delete a topic: its narrower topics move up to its broader ones, recordings stop being about it, and an entity it + was made from shows again. Returns that entity's id, if any.""" + t = _topic(db, tid) + tid = t["id"] + for n in db.rows("SELECT record::id(id) AS id, broader FROM topic WHERE space = $s AND $t IN broader", s=t["space"], t=tid): + up = [b for b in n.get("broader") or [] if b != tid] + up += [b for b in t.get("broader") or [] if b not in up and b != n["id"]] + db.q("UPDATE $r SET broader = $b", r=R("topic", n["id"]), b=up) + _set_related(db, tid, t.get("related") or [], []) + db.q("DELETE topic_about WHERE topic = $t", t=tid) + db.q("DELETE $r", r=R("topic", tid)) + eid = (t.get("origin") or {}).get("entity") + if eid and db.one("SELECT id FROM $r", r=R("entity", int(eid))): + db.q("UPDATE $r SET hidden = false, hidden_reason = NONE", r=R("entity", int(eid))) + return int(eid) + return None + + +def merge(db, keep, others, user=None): + """Fold `others` into `keep`: their labels become its other labels, their recordings are about it, and topics that + named them as broader or related name it instead.""" + k = _topic(db, keep) + keep = k["id"] + others = [int(o) for o in dict.fromkeys(others or []) if int(o) != keep] + if not others: + raise ValueError("Pick topics to merge into this one.") + gone = [_topic(db, o) for o in others] + if any(o["space"] != k["space"] for o in gone): + raise ValueError("Topics are merged within one namespace.") + alt = list(k.get("alt") or []) + broader = list(k.get("broader") or []) + related = list(k.get("related") or []) + for o in gone: + alt += [o["label"], *(o.get("alt") or [])] + broader += o.get("broader") or [] + related += o.get("related") or [] + for a in db.rows("SELECT recording, source, weight, status FROM topic_about WHERE topic = $t", t=o["id"]): + mine = db.one("SELECT status, weight FROM $r", r=_about_id(a["recording"], keep)) + if not mine or (mine.get("status") == "suggested" and a.get("status") == "accepted"): + _about( + db, k["space"], a["recording"], keep, a.get("source") or "person", a.get("weight"), a.get("status") or "accepted", user + ) + db.q("DELETE topic_about WHERE topic = $t", t=o["id"]) + ids = set(others) + for t in db.rows("SELECT record::id(id) AS id, broader, related FROM topic WHERE space = $s", s=k["space"]): + if t["id"] in ids or t["id"] == keep: + continue + b, r = t.get("broader") or [], t.get("related") or [] + if ids & set(b) or ids & set(r): + nb = list(dict.fromkeys(keep if x in ids else x for x in b)) + nr = list(dict.fromkeys(keep if x in ids else x for x in r)) + db.q("UPDATE $r SET broader = $b, related = $rel", r=R("topic", t["id"]), b=nb, rel=nr) + for o in others: + db.q("DELETE $r", r=R("topic", o)) + broader = [b for b in dict.fromkeys(broader) if b not in ids and b != keep] + if _would_loop(db, k["space"], keep, broader): + broader = list(k.get("broader") or []) + related = [r for r in dict.fromkeys(related) if r not in ids and r != keep] + db.q( + "UPDATE $r MERGE $d", + r=R("topic", keep), + d={"alt": _clean_alt(alt, k["label"])[:ALT_MAX], "broader": broader, "related": related, "updated": store.now(), "by": user}, + ) + return keep + + +def _about(db, sid, rid, tid, source, weight, status, user): + db.q( + "UPSERT $r CONTENT $d", + r=_about_id(rid, tid), + d=store.clean( + { + "space": int(sid), + "recording": int(rid), + "topic": int(tid), + "source": source, + "weight": weight, + "status": status, + "at": store.now(), + "by": user, + } + ), + ) + + +def tag(db, tid, recordings, remove=False, user=None): + """Say recordings are about a topic (accepting a suggestion too), or with `remove`, that they aren't.""" + t = _topic(db, tid) + rids = [int(r) for r in dict.fromkeys(recordings or [])] + if rids: + found = { + r["id"]: r["space"] + for r in db.rows("SELECT record::id(id) AS id, space FROM recording WHERE id IN $ids", ids=[R("recording", i) for i in rids]) + } + for r in rids: + if found.get(r) != t["space"]: + raise KeyError(r) + for r in rids: + if remove: + db.q("DELETE $r", r=_about_id(r, t["id"])) + else: + prior = db.one("SELECT source, weight FROM $r", r=_about_id(r, t["id"])) or {} + _about(db, t["space"], r, t["id"], prior.get("source") or "person", prior.get("weight"), "accepted", user) + return len(rids) + + +def from_entity(db, eid, user=None): + """Make an entity of type TERM a topic: its name the label, its aliases other labels, its description the + definition, and the recordings that mention it about it. The entity is hidden (deleting the topic shows it again). + An existing topic of that name gets the recordings instead. Returns the topic's id.""" + e = db.one("SELECT record::id(id) AS id, space, name, type, description, builtin, hidden FROM $r", r=R("entity", int(eid))) + if not e: + raise KeyError(eid) + if e.get("builtin"): + raise ValueError(f"{e['name']} is always there: it can't become a topic.") + if e.get("type") != "TERM": + raise ValueError(f"{e['name']} isn't a topic-like entity (type TERM); retype it first if it is one.") + sid = e["space"] + alt = [a["key"] for a in db.rows("SELECT key FROM entity_alias WHERE entity = $e", e=e["id"])] + row = db.one("SELECT record::id(id) AS id FROM topic WHERE tkey = $k", k=f"{sid}:{key_of(e['name'])}") + if row: + tid = row["id"] + else: + alt = [a for a in alt if not _labels_taken(db, sid, [key_of(a)])] + tid = create(db, sid, e["name"], alt, e.get("description"), origin={"entity": e["id"]}, user=user) + for m in db.rows("SELECT recording, count() AS n FROM mentions WHERE entity = $e GROUP BY recording", e=e["id"]): + prior = db.one("SELECT status FROM $r", r=_about_id(m["recording"], tid)) + if not prior or prior.get("status") != "accepted": + _about(db, sid, m["recording"], tid, "entity", m["n"], "accepted", user) + db.q("UPDATE $r SET hidden = true, hidden_reason = $why", r=R("entity", e["id"]), why=f"became topic {tid}") + return tid + + +# ---------- reading ---------- +def _counts(db, sids): + n = Counter() + for a in db.rows("SELECT topic, count() AS n FROM topic_about WHERE space IN $s AND status = 'accepted' GROUP BY topic", s=list(sids)): + n[a["topic"]] = a["n"] + return n + + +def _out(t, names, recordings=0, narrower=0): + return { + "id": t["id"], + "namespace": names.get(t["space"]), + "label": t["label"], + "alt": t.get("alt") or [], + "definition": t.get("definition"), + "broader": t.get("broader") or [], + "related": t.get("related") or [], + "recordings": recordings, + "narrower": narrower, + "from_entity": (t.get("origin") or {}).get("entity"), + "updated": t.get("updated"), + } + + +def list_topics(db, spaces, q="", top=False, broader=None, limit=200, offset=0): + """Topics of the namespaces in `spaces`, by label: {items, total}. `q` matches labels and other labels, `top` keeps + the ones with no broader topic, `broader` the narrower topics of one.""" + sids = sorted(int(s) for s in spaces or []) + if not sids: + return {"items": [], "total": 0} + names = store.space_names(db) + rows = db.rows(f"SELECT {FIELDS} FROM topic WHERE space IN $s", s=sids) + narrower = Counter(b for t in rows for b in t.get("broader") or []) + want = key_of(q) if q else "" + out = [] + for t in rows: + if want and not any(want in key_of(x) for x in [t["label"], *(t.get("alt") or [])]): + continue + if top and t.get("broader"): + continue + if broader is not None and int(broader) not in (t.get("broader") or []): + continue + out.append(t) + out.sort(key=lambda t: (t["label"].lower(), t["id"])) + counts = _counts(db, sids) + limit = max(1, min(int(limit or 200), 1000)) + page = out[int(offset or 0) : int(offset or 0) + limit] + return {"items": [_out(t, names, counts[t["id"]], narrower[t["id"]]) for t in page], "total": len(out)} + + +def detail(db, tid, spaces=None): + """One topic with its broader, narrower and related topics (labelled) and the recordings about it.""" + t = _topic(db, tid) + if spaces is not None and t["space"] not in spaces: + raise KeyError(tid) + names = store.space_names(db) + peers = {x["id"]: x for x in db.rows("SELECT record::id(id) AS id, label, broader FROM topic WHERE space = $s", s=t["space"])} + narrow = sorted((x for x in peers.values() if t["id"] in (x.get("broader") or [])), key=lambda x: x["label"].lower()) + about = db.rows( + "SELECT recording, source, weight, status, at FROM topic_about WHERE topic = $t ORDER BY status, weight DESC", t=t["id"] + ) + titles = { + r["id"]: r.get("title") + for r in ( + db.rows( + "SELECT record::id(id) AS id, title FROM recording WHERE id IN $ids", + ids=[R("recording", a["recording"]) for a in about], + ) + if about + else [] + ) + } + accepted = [a for a in about if a.get("status") == "accepted"] + out = _out(t, names, len(accepted), len(narrow)) + + def ref(i): + return {"id": i, "label": peers[i]["label"]} if i in peers else None + + out["broader"] = [x for x in map(ref, t.get("broader") or []) if x] + out["narrower"] = [{"id": x["id"], "label": x["label"]} for x in narrow] + out["related"] = [x for x in map(ref, t.get("related") or []) if x] + out["about"] = [ + { + "recording": a["recording"], + "title": titles.get(a["recording"]), + "source": a.get("source"), + "weight": a.get("weight"), + "status": a.get("status"), + } + for a in about + if a["recording"] in titles + ] + return out + + +def of_recording(db, rid, status=None): + """The topics a recording is about: [{id, label, source, weight, status}].""" + rows = db.rows("SELECT topic, source, weight, status FROM topic_about WHERE recording = $r", r=int(rid)) + if status: + rows = [a for a in rows if a.get("status") == status] + labels = { + t["id"]: t["label"] + for t in ( + db.rows("SELECT record::id(id) AS id, label FROM topic WHERE id IN $ids", ids=[R("topic", a["topic"]) for a in rows]) + if rows + else [] + ) + } + out = [ + {"id": a["topic"], "label": labels[a["topic"]], "source": a.get("source"), "weight": a.get("weight"), "status": a.get("status")} + for a in rows + if a["topic"] in labels + ] + return sorted(out, key=lambda x: (x["status"] != "accepted", x["label"].lower())) diff --git a/fastapi_backend/app/schemas/topics.py b/fastapi_backend/app/schemas/topics.py new file mode 100644 index 000000000..4dfbcfba0 --- /dev/null +++ b/fastapi_backend/app/schemas/topics.py @@ -0,0 +1,90 @@ +"""Topics: each namespace's controlled vocabulary (SKOS concepts) and the recordings about them.""" + +from __future__ import annotations + +from typing import Literal + +from pydantic import Field + +from app.schemas.common import RequestModel, ResponseModel + + +class TopicRef(ResponseModel): + id: int + label: str + + +class TopicAbout(ResponseModel): + recording: int + title: str | None = None + source: str | None = Field(None, description="how it got there: person, entity or analysis") + weight: float | None = None + status: Literal["accepted", "suggested"] | None = None + + +class TopicItem(ResponseModel): + id: int + namespace: str | None = None + label: str + alt: list[str] = Field([], description="other labels it goes by (skos:altLabel)") + definition: str | None = None + broader: list[int] = [] + related: list[int] = [] + recordings: int = Field(0, description="recordings about it (accepted)") + narrower: int = Field(0, description="topics that have it as broader") + from_entity: int | None = Field(None, description="the entity it was made from, hidden while the topic exists") + updated: str | None = None + + +class TopicList(ResponseModel): + total: int + items: list[TopicItem] + + +class TopicDetail(ResponseModel): + id: int + namespace: str | None = None + label: str + alt: list[str] = [] + definition: str | None = None + broader: list[TopicRef] = [] + narrower: list[TopicRef] = [] + related: list[TopicRef] = [] + recordings: int = 0 + from_entity: int | None = None + updated: str | None = None + about: list[TopicAbout] = [] + + +class TopicCreate(RequestModel): + label: str = Field(min_length=1, max_length=200) + alt: list[str] = [] + definition: str | None = Field(None, max_length=2000) + broader: list[int] = [] + related: list[int] = [] + + +class TopicUpdate(RequestModel): + label: str | None = Field(None, min_length=1, max_length=200) + alt: list[str] | None = None + definition: str | None = Field(None, max_length=2000, description="an empty string clears it") + broader: list[int] | None = None + related: list[int] | None = None + + +class TopicMerge(RequestModel): + keep: int + others: list[int] = Field(min_length=1) + + +class TopicRecordings(RequestModel): + recordings: list[int] = Field(min_length=1, max_length=500) + remove: bool = Field(False, description="say they aren't about it") + + +class RecordingTopic(ResponseModel): + id: int + label: str + source: str | None = None + weight: float | None = None + status: str | None = None diff --git a/fastapi_backend/tests/api/test_topics.py b/fastapi_backend/tests/api/test_topics.py new file mode 100644 index 000000000..377fe1f4f --- /dev/null +++ b/fastapi_backend/tests/api/test_topics.py @@ -0,0 +1,119 @@ +"""Topics: the vocabulary (labels, broader, narrower, related), recordings about topics, topics made from entities, +and topics in the property graph and in RDF.""" + +from __future__ import annotations + +import pytest +from rdflib import Graph, URIRef +from rdflib.namespace import SKOS + +from tests.api.test_entities import Env + + +@pytest.fixture +def env(db, cfg, folder, client): + return Env(db, cfg, folder, client) + + +def make(c, h, label, **kw): + r = c.post("/api/v1/namespaces/pods/topics", json={"label": label, **kw}, headers=h) + assert r.status_code == 201, r.text + return r.json() + + +def test_vocabulary(env): + c, ed, vi = env.c, env.h["editor"], env.h["viewer"] + assert c.post("/api/v1/namespaces/pods/topics", json={"label": "Biology"}, headers=vi).status_code == 403 + bio = make(c, ed, "Biology", definition="Living things.") + gene = make(c, ed, "Gene therapy", alt=["gene therapies", "Gene Therapy", "GT"], broader=[bio["id"]]) + assert gene["alt"] == ["gene therapies", "GT"] # the label itself isn't another label + assert gene["broader"] == [{"id": bio["id"], "label": "Biology"}] + vec = make(c, ed, "Viral vectors", broader=[gene["id"]], related=[bio["id"]]) + # labels and other labels are unique in the namespace + assert c.post("/api/v1/namespaces/pods/topics", json={"label": "gt"}, headers=ed).status_code == 400 + # a topic can't end up broader than itself + loop = c.patch(f"/api/v1/topics/{bio['id']}", json={"broader": [vec["id"]]}, headers=ed) + assert loop.status_code == 400 and "broader than itself" in loop.text + # related is symmetric + b = c.get(f"/api/v1/topics/{bio['id']}", headers=vi).json() + assert b["related"] == [{"id": vec["id"], "label": "Viral vectors"}] + assert b["narrower"] == [{"id": gene["id"], "label": "Gene therapy"}] + top = c.get("/api/v1/topics", params={"top": True}, headers=vi).json() + assert [t["label"] for t in top["items"]] == ["Biology"] and top["items"][0]["narrower"] == 1 + assert [t["label"] for t in c.get("/api/v1/topics", params={"q": "therapies"}, headers=vi).json()["items"]] == ["Gene therapy"] + # editing: rename, clear the definition + r = c.patch(f"/api/v1/topics/{bio['id']}", json={"label": "Life sciences", "definition": ""}, headers=ed).json() + assert (r["label"], r["definition"]) == ("Life sciences", None) + assert c.patch(f"/api/v1/topics/{bio['id']}", json={"label": "x"}, headers=vi).status_code == 403 + # deleting a topic moves its narrower topics up + assert c.delete(f"/api/v1/topics/{gene['id']}", headers=ed).status_code == 200 + v = c.get(f"/api/v1/topics/{vec['id']}", headers=vi).json() + assert v["broader"] == [{"id": bio["id"], "label": "Life sciences"}] + + +def test_recordings_about_topics(env): + c, ed, vi = env.c, env.h["editor"], env.h["viewer"] + t = make(c, ed, "Funding") + out = c.post(f"/api/v1/topics/{t['id']}/recordings", json={"recordings": [1, 2]}, headers=ed).json() + assert [(a["recording"], a["source"], a["status"]) for a in out["about"]] == [(1, "person", "accepted"), (2, "person", "accepted")] + assert out["recordings"] == 2 + # only the topic's namespace's recordings (call is in calls) + assert c.post(f"/api/v1/topics/{t['id']}/recordings", json={"recordings": [3]}, headers=ed).status_code == 404 + assert c.get("/api/v1/recordings/1/topics", headers=vi).json() == [ + {"id": t["id"], "label": "Funding", "source": "person", "weight": None, "status": "accepted"} + ] + c.post(f"/api/v1/topics/{t['id']}/recordings", json={"recordings": [2], "remove": True}, headers=ed) + assert c.get(f"/api/v1/topics/{t['id']}", headers=vi).json()["recordings"] == 1 + # merging: labels become other labels, recordings move over + u = make(c, ed, "Grants") + c.post(f"/api/v1/topics/{u['id']}/recordings", json={"recordings": [4]}, headers=ed) + m = c.post("/api/v1/topics/merge", json={"keep": t["id"], "others": [u["id"]]}, headers=ed).json() + assert m["alt"] == ["Grants"] and [a["recording"] for a in m["about"]] == [1, 4] + assert c.get(f"/api/v1/topics/{u['id']}", headers=vi).status_code == 404 + + +def test_topic_from_entity(env): + c, ed, vi, db = env.c, env.h["editor"], env.h["viewer"], env.db + aws = env.eid("Amazon Web Services") + mentioned_in = {m["recording"] for m in db.rows("SELECT recording FROM mentions WHERE entity = $e", e=aws)} + assert c.post(f"/api/v1/entities/{aws}/topic", headers=vi).status_code == 403 + dyno = env.eid("Dyno Therapeutics") + assert c.post(f"/api/v1/entities/{dyno}/topic", headers=ed).status_code == 400 # an organisation, not a topic + t = c.post(f"/api/v1/entities/{aws}/topic", headers=ed).json() + assert t["label"] == "Amazon Web Services" and t["from_entity"] == aws + assert {a["recording"] for a in t["about"]} == mentioned_in and {a["source"] for a in t["about"]} == {"entity"} + assert c.get(f"/api/v1/entities/{aws}", headers=vi).json()["hidden"] is True + # deleting the topic shows the entity again + c.delete(f"/api/v1/topics/{t['id']}", headers=ed) + assert c.get(f"/api/v1/entities/{aws}", headers=vi).json()["hidden"] is False + + +def test_topics_in_the_graph_and_rdf(env): + c, ed, vi = env.c, env.h["editor"], env.h["viewer"] + bio = make(c, ed, "Biology") + gene = make(c, ed, "Gene therapy", broader=[bio["id"]], alt=["GT"]) + c.post(f"/api/v1/topics/{gene['id']}/recordings", json={"recordings": [1]}, headers=ed) + q = { + "query": "MATCH (t:Topic {name: 'Biology'})-[:NARROWER*0..4]->(n:Topic)<-[a:ABOUT]-(r:Recording) RETURN r.name, n.name, a.source", + "scope": "ns:pods", + } + out = c.post("/api/v1/graph/query", json=q, headers=vi).json() + assert out["rows"] == [["ep1", "Gene therapy", "person"]] + rel = c.get("/api/v1/graph/related", params={"node": f"t{gene['id']}", "relation": "parents", "scope": "ns:pods"}, headers=vi).json() + assert {n["id"] for n in rel["nodes"]} == {f"t{gene['id']}", f"t{bio['id']}", "r1"} + schema = c.get("/api/v1/graph/schema", params={"scope": "ns:pods"}, headers=vi).json() + assert {"label": "Topic", "count": 2} in [{k: x[k] for k in ("label", "count")} for x in schema["labels"]] + # RDF: a SKOS concept in the namespace's vocabulary + r = c.get(f"/id/topic/{gene['id']}", headers={**vi, "Accept": "text/turtle"}) + assert r.status_code == 200 + g = Graph().parse(data=r.text, format="turtle") + me = next(s for s in g.subjects(SKOS.prefLabel, None) if str(s).endswith(f"/id/topic/{gene['id']}")) + assert str(next(g.objects(me, SKOS.altLabel))) == "GT" + assert str(next(g.objects(me, SKOS.broader))).endswith(f"/id/topic/{bio['id']}") + assert str(next(g.objects(me, SKOS.inScheme))).endswith("/id/namespace/pods#topics") + rec = c.get("/id/recording/1", headers={**vi, "Accept": "text/turtle"}) + rg = Graph().parse(data=rec.text, format="turtle") + subjects = {str(o) for o in rg.objects(None, URIRef("http://purl.org/dc/terms/subject"))} + assert any(s.endswith(f"/id/topic/{gene['id']}") for s in subjects) + # a stranger to the namespace gets nothing + assert c.get(f"/id/topic/{gene['id']}", headers={"Accept": "text/turtle"}).status_code == 404 diff --git a/mkdocs.yml b/mkdocs.yml index 6632044d7..163300dec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,6 +77,7 @@ nav: - Telemetry: telemetry.md - IIIF: iiif.md - Graph and Cypher: graph.md + - Topics: topics.md - Notes: notes.md - Linked data (RDF): rdf.md - Fedora repository: fedora.md diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index 72062341c..4aaabe227 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -37,6 +37,7 @@ export { Speakers, Templates, Tokens, + Topics, Uploads, Users, Vaults, @@ -407,6 +408,11 @@ export type { CreateTokenErrors, CreateTokenResponse, CreateTokenResponses, + CreateTopicData, + CreateTopicError, + CreateTopicErrors, + CreateTopicResponse, + CreateTopicResponses, CreateUserData, CreateUserError, CreateUserErrors, @@ -576,6 +582,11 @@ export type { DeleteSourceErrors, DeleteSourceResponse, DeleteSourceResponses, + DeleteTopicData, + DeleteTopicError, + DeleteTopicErrors, + DeleteTopicResponse, + DeleteTopicResponses, DeleteViewData, DeleteViewError, DeleteViewErrors, @@ -644,6 +655,11 @@ export type { EntitySetupApply, EntitySetupSave, EntitySetupView, + EntityToTopicData, + EntityToTopicError, + EntityToTopicErrors, + EntityToTopicResponse, + EntityToTopicResponses, EntityType, EntityTypeCreate, EntityTypeInfo, @@ -978,6 +994,11 @@ export type { GetTemplateErrors, GetTemplateResponse, GetTemplateResponses, + GetTopicData, + GetTopicError, + GetTopicErrors, + GetTopicResponse, + GetTopicResponses, GetUploadData, GetUploadError, GetUploadErrors, @@ -1384,6 +1405,11 @@ export type { ListTokensData, ListTokensResponse, ListTokensResponses, + ListTopicsData, + ListTopicsError, + ListTopicsErrors, + ListTopicsResponse, + ListTopicsResponses, ListUploadsData, ListUploadsResponse, ListUploadsResponses, @@ -1471,6 +1497,11 @@ export type { MergeSpeakerErrors, MergeSpeakerResponse, MergeSpeakerResponses, + MergeTopicsData, + MergeTopicsError, + MergeTopicsErrors, + MergeTopicsResponse, + MergeTopicsResponses, MessageCreate, MetadataBulk, MetadataBulkResult, @@ -1698,6 +1729,12 @@ export type { RecordingsPlace, RecordingsRetag, RecordingSummary, + RecordingTopic, + RecordingTopicsData, + RecordingTopicsError, + RecordingTopicsErrors, + RecordingTopicsResponse, + RecordingTopicsResponses, RecordingUpdate, RedeemTicketData, RedeemTicketError, @@ -2092,6 +2129,11 @@ export type { SyncFedoraResponse, SyncFedoraResponses, TagCount, + TagRecordingsData, + TagRecordingsError, + TagRecordingsErrors, + TagRecordingsResponse, + TagRecordingsResponses, TagsChanged, TelemetryExport, TelemetryStatus, @@ -2149,6 +2191,15 @@ export type { TokenResponse, TokenResponses, ToolStep, + TopicAbout, + TopicCreate, + TopicDetail, + TopicItem, + TopicList, + TopicMerge, + TopicRecordings, + TopicRef, + TopicUpdate, TranscribeClipData, TranscribeClipResponse, TranscribeClipResponses, @@ -2347,6 +2398,11 @@ export type { UpdateSourceErrors, UpdateSourceResponse, UpdateSourceResponses, + UpdateTopicData, + UpdateTopicError, + UpdateTopicErrors, + UpdateTopicResponse, + UpdateTopicResponses, UpdateUserData, UpdateUserError, UpdateUserErrors, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 6ce66c58d..3bf9fdbea 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -184,6 +184,9 @@ import type { CreateTokenData, CreateTokenErrors, CreateTokenResponses, + CreateTopicData, + CreateTopicErrors, + CreateTopicResponses, CreateUserData, CreateUserErrors, CreateUserResponses, @@ -283,6 +286,9 @@ import type { DeleteSourceData, DeleteSourceErrors, DeleteSourceResponses, + DeleteTopicData, + DeleteTopicErrors, + DeleteTopicResponses, DeleteViewData, DeleteViewErrors, DeleteViewResponses, @@ -312,6 +318,9 @@ import type { EditSegmentData, EditSegmentErrors, EditSegmentResponses, + EntityToTopicData, + EntityToTopicErrors, + EntityToTopicResponses, EstimateBatchData, EstimateBatchErrors, EstimateBatchResponses, @@ -492,6 +501,9 @@ import type { GetTemplateData, GetTemplateErrors, GetTemplateResponses, + GetTopicData, + GetTopicErrors, + GetTopicResponses, GetUploadData, GetUploadErrors, GetUploadResponses, @@ -713,6 +725,9 @@ import type { ListTemplatesResponses, ListTokensData, ListTokensResponses, + ListTopicsData, + ListTopicsErrors, + ListTopicsResponses, ListUploadsData, ListUploadsResponses, ListUsersData, @@ -757,6 +772,9 @@ import type { MergeSpeakerData, MergeSpeakerErrors, MergeSpeakerResponses, + MergeTopicsData, + MergeTopicsErrors, + MergeTopicsResponses, MoveMentionData, MoveMentionErrors, MoveMentionResponses, @@ -827,6 +845,9 @@ import type { QueueStepData, QueueStepErrors, QueueStepResponses, + RecordingTopicsData, + RecordingTopicsErrors, + RecordingTopicsResponses, RedeemTicketData, RedeemTicketErrors, RedeemTicketResponses, @@ -1011,6 +1032,9 @@ import type { SuggestTermsResponses, SyncFedoraData, SyncFedoraResponses, + TagRecordingsData, + TagRecordingsErrors, + TagRecordingsResponses, TelemetryStatusData, TelemetryStatusResponses, TestBridgeData, @@ -1155,6 +1179,9 @@ import type { UpdateSourceData, UpdateSourceErrors, UpdateSourceResponses, + UpdateTopicData, + UpdateTopicErrors, + UpdateTopicResponses, UpdateUserData, UpdateUserErrors, UpdateUserResponses, @@ -4875,6 +4902,152 @@ export class Entities { } } +export class Topics { + /** + * List Topics + * + * Topics of the namespaces you can read (or of `ns`), by label. `q` matches labels and other labels, `top` keeps + * those with no broader topic, `broader` lists the narrower topics of one. + */ + public static listTopics( + options?: Options, + ): RequestResult { + return (options?.client ?? client).get({ + url: "/api/v1/topics", + ...options, + }); + } + + /** + * Delete Topic + * + * Delete it: its narrower topics move up, recordings stop being about it, and an entity it was made from shows again. + */ + public static deleteTopic( + options: Options, + ): RequestResult { + return (options.client ?? client).delete({ + url: "/api/v1/topics/{tid}", + ...options, + }); + } + + /** + * Get Topic + * + * A topic with its broader, narrower and related topics and the recordings about it. + */ + public static getTopic( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/topics/{tid}", + ...options, + }); + } + + /** + * Update Topic + * + * Rename it, change its other labels or definition, or what it is narrower than or related to. + */ + public static updateTopic( + options: Options, + ): RequestResult { + return (options.client ?? client).patch({ + url: "/api/v1/topics/{tid}", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Create Topic + * + * Add a topic to the namespace's vocabulary. + */ + public static createTopic( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/namespaces/{name}/topics", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Merge Topics + * + * Fold topics into one: their labels become its other labels and their recordings are about it. + */ + public static mergeTopics( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/topics/merge", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Tag Recordings + * + * Say recordings of the topic's namespace are about it (accepting suggestions too), or with `remove` that they aren't. + */ + public static tagRecordings( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/topics/{tid}/recordings", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Recording Topics + * + * The topics a recording is about, and those suggested for it. + */ + public static recordingTopics( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/resources/{rid}/topics", + ...options, + }); + } + + /** + * Entity To Topic + * + * Make a topic-like entity (type TERM) a topic: its names become the topic's labels and the recordings that + * mention it are about the topic. The entity is hidden; deleting the topic shows it again. + */ + public static entityToTopic( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/entities/{eid}/topic", + ...options, + }); + } +} + export class Graph { /** * Graph Schema diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 7108c3b04..15625e931 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -9779,6 +9779,33 @@ export type RecordingSummary = { [key: string]: unknown; }; +/** + * RecordingTopic + */ +export type RecordingTopic = { + /** + * Id + */ + id: number; + /** + * Label + */ + label: string; + /** + * Source + */ + source?: string | null; + /** + * Weight + */ + weight?: number | null; + /** + * Status + */ + status?: string | null; + [key: string]: unknown; +}; + /** * RecordingUpdate * @@ -13008,6 +13035,263 @@ export type ToolStep = { [key: string]: unknown; }; +/** + * TopicAbout + */ +export type TopicAbout = { + /** + * Recording + */ + recording: number; + /** + * Title + */ + title?: string | null; + /** + * Source + * + * how it got there: person, entity or analysis + */ + source?: string | null; + /** + * Weight + */ + weight?: number | null; + /** + * Status + */ + status?: "accepted" | "suggested" | null; + [key: string]: unknown; +}; + +/** + * TopicCreate + */ +export type TopicCreate = { + /** + * Label + */ + label: string; + /** + * Alt + */ + alt?: Array; + /** + * Definition + */ + definition?: string | null; + /** + * Broader + */ + broader?: Array; + /** + * Related + */ + related?: Array; +}; + +/** + * TopicDetail + */ +export type TopicDetail = { + /** + * Id + */ + id: number; + /** + * Namespace + */ + namespace?: string | null; + /** + * Label + */ + label: string; + /** + * Alt + */ + alt?: Array; + /** + * Definition + */ + definition?: string | null; + /** + * Broader + */ + broader?: Array; + /** + * Narrower + */ + narrower?: Array; + /** + * Related + */ + related?: Array; + /** + * Recordings + */ + recordings?: number; + /** + * From Entity + */ + from_entity?: number | null; + /** + * Updated + */ + updated?: string | null; + /** + * About + */ + about?: Array; + [key: string]: unknown; +}; + +/** + * TopicItem + */ +export type TopicItem = { + /** + * Id + */ + id: number; + /** + * Namespace + */ + namespace?: string | null; + /** + * Label + */ + label: string; + /** + * Alt + * + * other labels it goes by (skos:altLabel) + */ + alt?: Array; + /** + * Definition + */ + definition?: string | null; + /** + * Broader + */ + broader?: Array; + /** + * Related + */ + related?: Array; + /** + * Recordings + * + * recordings about it (accepted) + */ + recordings?: number; + /** + * Narrower + * + * topics that have it as broader + */ + narrower?: number; + /** + * From Entity + * + * the entity it was made from, hidden while the topic exists + */ + from_entity?: number | null; + /** + * Updated + */ + updated?: string | null; + [key: string]: unknown; +}; + +/** + * TopicList + */ +export type TopicList = { + /** + * Total + */ + total: number; + /** + * Items + */ + items: Array; + [key: string]: unknown; +}; + +/** + * TopicMerge + */ +export type TopicMerge = { + /** + * Keep + */ + keep: number; + /** + * Others + */ + others: Array; +}; + +/** + * TopicRecordings + */ +export type TopicRecordings = { + /** + * Recordings + */ + recordings: Array; + /** + * Remove + * + * say they aren't about it + */ + remove?: boolean; +}; + +/** + * TopicRef + */ +export type TopicRef = { + /** + * Id + */ + id: number; + /** + * Label + */ + label: string; + [key: string]: unknown; +}; + +/** + * TopicUpdate + */ +export type TopicUpdate = { + /** + * Label + */ + label?: string | null; + /** + * Alt + */ + alt?: Array | null; + /** + * Definition + * + * an empty string clears it + */ + definition?: string | null; + /** + * Broader + */ + broader?: Array | null; + /** + * Related + */ + related?: Array | null; +}; + /** * TunnelStatus */ @@ -20975,6 +21259,293 @@ export type FindGraphPathResponses = { export type FindGraphPathResponse = FindGraphPathResponses[keyof FindGraphPathResponses]; +export type ListTopicsData = { + body?: never; + path?: never; + query?: { + /** + * Q + */ + q?: string; + /** + * Ns + */ + ns?: string; + /** + * Top + */ + top?: boolean; + /** + * Broader + */ + broader?: number | null; + /** + * Limit + */ + limit?: number; + /** + * Offset + */ + offset?: number; + }; + url: "/api/v1/topics"; +}; + +export type ListTopicsErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type ListTopicsError = ListTopicsErrors[keyof ListTopicsErrors]; + +export type ListTopicsResponses = { + /** + * Successful Response + */ + 200: TopicList; +}; + +export type ListTopicsResponse = ListTopicsResponses[keyof ListTopicsResponses]; + +export type DeleteTopicData = { + body?: never; + path: { + /** + * Tid + */ + tid: number; + }; + query?: never; + url: "/api/v1/topics/{tid}"; +}; + +export type DeleteTopicErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type DeleteTopicError = DeleteTopicErrors[keyof DeleteTopicErrors]; + +export type DeleteTopicResponses = { + /** + * Successful Response + */ + 200: Ok; +}; + +export type DeleteTopicResponse = DeleteTopicResponses[keyof DeleteTopicResponses]; + +export type GetTopicData = { + body?: never; + path: { + /** + * Tid + */ + tid: number; + }; + query?: never; + url: "/api/v1/topics/{tid}"; +}; + +export type GetTopicErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type GetTopicError = GetTopicErrors[keyof GetTopicErrors]; + +export type GetTopicResponses = { + /** + * Successful Response + */ + 200: TopicDetail; +}; + +export type GetTopicResponse = GetTopicResponses[keyof GetTopicResponses]; + +export type UpdateTopicData = { + body: TopicUpdate; + path: { + /** + * Tid + */ + tid: number; + }; + query?: never; + url: "/api/v1/topics/{tid}"; +}; + +export type UpdateTopicErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type UpdateTopicError = UpdateTopicErrors[keyof UpdateTopicErrors]; + +export type UpdateTopicResponses = { + /** + * Successful Response + */ + 200: TopicDetail; +}; + +export type UpdateTopicResponse = UpdateTopicResponses[keyof UpdateTopicResponses]; + +export type CreateTopicData = { + body: TopicCreate; + path: { + /** + * Name + */ + name: string; + }; + query?: never; + url: "/api/v1/namespaces/{name}/topics"; +}; + +export type CreateTopicErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type CreateTopicError = CreateTopicErrors[keyof CreateTopicErrors]; + +export type CreateTopicResponses = { + /** + * Successful Response + */ + 201: TopicDetail; +}; + +export type CreateTopicResponse = CreateTopicResponses[keyof CreateTopicResponses]; + +export type MergeTopicsData = { + body: TopicMerge; + path?: never; + query?: never; + url: "/api/v1/topics/merge"; +}; + +export type MergeTopicsErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type MergeTopicsError = MergeTopicsErrors[keyof MergeTopicsErrors]; + +export type MergeTopicsResponses = { + /** + * Successful Response + */ + 200: TopicDetail; +}; + +export type MergeTopicsResponse = MergeTopicsResponses[keyof MergeTopicsResponses]; + +export type TagRecordingsData = { + body: TopicRecordings; + path: { + /** + * Tid + */ + tid: number; + }; + query?: never; + url: "/api/v1/topics/{tid}/recordings"; +}; + +export type TagRecordingsErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type TagRecordingsError = TagRecordingsErrors[keyof TagRecordingsErrors]; + +export type TagRecordingsResponses = { + /** + * Successful Response + */ + 200: TopicDetail; +}; + +export type TagRecordingsResponse = TagRecordingsResponses[keyof TagRecordingsResponses]; + +export type RecordingTopicsData = { + body?: never; + path: { + /** + * Rid + */ + rid: number; + }; + query?: never; + url: "/api/v1/resources/{rid}/topics"; +}; + +export type RecordingTopicsErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type RecordingTopicsError = RecordingTopicsErrors[keyof RecordingTopicsErrors]; + +export type RecordingTopicsResponses = { + /** + * Response Topics-Recording Topics + * + * Successful Response + */ + 200: Array; +}; + +export type RecordingTopicsResponse = RecordingTopicsResponses[keyof RecordingTopicsResponses]; + +export type EntityToTopicData = { + body?: never; + path: { + /** + * Eid + */ + eid: number; + }; + query?: never; + url: "/api/v1/entities/{eid}/topic"; +}; + +export type EntityToTopicErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type EntityToTopicError = EntityToTopicErrors[keyof EntityToTopicErrors]; + +export type EntityToTopicResponses = { + /** + * Successful Response + */ + 201: TopicDetail; +}; + +export type EntityToTopicResponse = EntityToTopicResponses[keyof EntityToTopicResponses]; + export type GraphSchemaData = { body?: never; path?: never; diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 9ee6e98fb..43789870c 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -10819,120 +10819,60 @@ } } }, - "/api/v1/graph/schema": { + "/api/v1/topics": { "get": { "tags": [ - "graph" + "topics" ], - "summary": "Graph Schema", - "description": "What the graph holds in this scope: labels, relationship types (and what they join), properties and counts, with\nexample queries. Agents read this before writing Cypher.", - "operationId": "graph_schema", + "summary": "List Topics", + "description": "Topics of the namespaces you can read (or of `ns`), by label. `q` matches labels and other labels, `top` keeps\nthose with no broader topic, `broader` lists the narrower topics of one.", + "operationId": "list_topics", "parameters": [ { - "name": "scope", + "name": "q", "in": "query", "required": false, "schema": { "type": "string", - "description": "\"global\" (every shared namespace you can read) or \"ns:\"", - "default": "global", - "title": "Scope" - }, - "description": "\"global\" (every shared namespace you can read) or \"ns:\"" - } - ], - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "type": "object", - "additionalProperties": true, - "title": "Response Graph-Graph Schema" - } - } - } - }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } + "default": "", + "title": "Q" } - } - } - } - }, - "/api/v1/graph/related": { - "get": { - "tags": [ - "graph" - ], - "summary": "Graph Related", - "description": "Nodes related to one node, nearest first, with the relationships between them.", - "operationId": "graph_related", - "parameters": [ - { - "name": "node", - "in": "query", - "required": true, - "schema": { - "type": "string", - "description": "a node id: n, c, r, s, e or e:", - "title": "Node" - }, - "description": "a node id: n, c, r, s, e or e:" }, { - "name": "relation", + "name": "ns", "in": "query", "required": false, "schema": { - "enum": [ - "children", - "parents", - "ancestors", - "descendants", - "neighbours" - ], "type": "string", - "default": "neighbours", - "title": "Relation" + "default": "", + "title": "Ns" } }, { - "name": "depth", + "name": "top", "in": "query", "required": false, "schema": { - "type": "integer", - "maximum": 8, - "minimum": 1, - "default": 1, - "title": "Depth" + "type": "boolean", + "default": false, + "title": "Top" } }, { - "name": "types", + "name": "broader", "in": "query", "required": false, "schema": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "description": "relationship types to follow, comma separated (default: the hierarchy, or any for neighbours)", - "title": "Types" - }, - "description": "relationship types to follow, comma separated (default: the hierarchy, or any for neighbours)" + "title": "Broader" + } }, { "name": "limit", @@ -10940,23 +10880,19 @@ "required": false, "schema": { "type": "integer", - "maximum": 2000, - "minimum": 1, "default": 200, "title": "Limit" } }, { - "name": "scope", + "name": "offset", "in": "query", "required": false, "schema": { - "type": "string", - "description": "\"global\" (every shared namespace you can read) or \"ns:\"", - "default": "global", - "title": "Scope" - }, - "description": "\"global\" (every shared namespace you can read) or \"ns:\"" + "type": "integer", + "default": 0, + "title": "Offset" + } } ], "responses": { @@ -10965,9 +10901,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "additionalProperties": true, - "title": "Response Graph-Graph Related" + "$ref": "#/components/schemas/TopicList" } } } @@ -10985,104 +10919,23 @@ } } }, - "/api/v1/graph/paths": { + "/api/v1/topics/{tid}": { "get": { "tags": [ - "graph" + "topics" ], - "summary": "Graph Paths", - "description": "Paths from a to b, shortest first: every simple path up to max_depth hops, or just the shortest ones.", - "operationId": "graph_paths", + "summary": "Get Topic", + "description": "A topic with its broader, narrower and related topics and the recordings about it.", + "operationId": "get_topic", "parameters": [ { - "name": "a", - "in": "query", - "required": true, - "schema": { - "type": "string", - "title": "A" - } - }, - { - "name": "b", - "in": "query", + "name": "tid", + "in": "path", "required": true, - "schema": { - "type": "string", - "title": "B" - } - }, - { - "name": "max_depth", - "in": "query", - "required": false, - "schema": { - "type": "integer", - "maximum": 8, - "minimum": 1, - "default": 4, - "title": "Max Depth" - } - }, - { - "name": "limit", - "in": "query", - "required": false, "schema": { "type": "integer", - "maximum": 100, - "minimum": 1, - "default": 10, - "title": "Limit" - } - }, - { - "name": "types", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Types" - } - }, - { - "name": "directed", - "in": "query", - "required": false, - "schema": { - "type": "boolean", - "default": false, - "title": "Directed" - } - }, - { - "name": "shortest", - "in": "query", - "required": false, - "schema": { - "type": "boolean", - "default": false, - "title": "Shortest" + "title": "Tid" } - }, - { - "name": "scope", - "in": "query", - "required": false, - "schema": { - "type": "string", - "description": "\"global\" (every shared namespace you can read) or \"ns:\"", - "default": "global", - "title": "Scope" - }, - "description": "\"global\" (every shared namespace you can read) or \"ns:\"" } ], "responses": { @@ -11091,9 +10944,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "additionalProperties": true, - "title": "Response Graph-Graph Paths" + "$ref": "#/components/schemas/TopicDetail" } } } @@ -11109,25 +10960,34 @@ } } } - } - }, - "/api/v1/graph/query": { - "post": { + }, + "patch": { "tags": [ - "graph" + "topics" + ], + "summary": "Update Topic", + "description": "Rename it, change its other labels or definition, or what it is narrower than or related to.", + "operationId": "update_topic", + "parameters": [ + { + "name": "tid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Tid" + } + } ], - "summary": "Graph Query", - "description": "Run a read-only Cypher query over the graph you can read: {columns, rows, nodes, edges, truncated}. Nodes and\nrelationships it returns are also listed in nodes and edges, ready to draw. Read-only tokens may query.", - "operationId": "graph_query", "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GraphQuery" + "$ref": "#/components/schemas/TopicUpdate" } } - }, - "required": true + } }, "responses": { "200": { @@ -11135,9 +10995,7 @@ "content": { "application/json": { "schema": { - "additionalProperties": true, - "type": "object", - "title": "Response Graph-Graph Query" + "$ref": "#/components/schemas/TopicDetail" } } } @@ -11153,79 +11011,32 @@ } } } - } - }, - "/api/v1/graph/ask": { - "post": { + }, + "delete": { "tags": [ - "graph" + "topics" ], - "summary": "Ask Graph", - "description": "A question in plain language: the language model writes read-only Cypher, Lens runs it over the graph you can\nread, and you get the answer with the query that found it ({question, cypher, explanation, result}).", - "operationId": "ask_graph", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GraphQuestion" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "additionalProperties": true, - "type": "object", - "title": "Response Graph-Ask Graph" - } - } - } - }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } + "summary": "Delete Topic", + "description": "Delete it: its narrower topics move up, recordings stop being about it, and an entity it was made from shows again.", + "operationId": "delete_topic", + "parameters": [ + { + "name": "tid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Tid" } } - } - } - }, - "/api/v1/graph/changes": { - "post": { - "tags": [ - "graph" ], - "summary": "Propose Graph Change", - "description": "Ask for a change to the graph. Proposed by default, for someone with editor access to accept in Proposed\nchanges; `apply` makes it at once, and it can still be undone. Both need editor access to the two namespaces; read-only\ntokens can't ask.", - "operationId": "propose_graph_change", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChangeAsk" - } - } - }, - "required": true - }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "additionalProperties": true, - "type": "object", - "title": "Response Graph-Propose Graph Change" + "$ref": "#/components/schemas/Ok" } } } @@ -11243,55 +11054,14 @@ } } }, - "/api/v1/namespaces/{name}/entity-setup": { - "get": { - "tags": [ - "entities" - ], - "summary": "Get Entity Setup", - "description": "The namespace's entity setup, the collections (you see) with their own, and the types entities may have.", - "operationId": "get_entity_setup", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" - } - } - ], - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EntitySetupView" - } - } - } - }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } - } - } - } - }, - "put": { + "/api/v1/namespaces/{name}/topics": { + "post": { "tags": [ - "entities" + "topics" ], - "summary": "Save Entity Setup", - "description": "Save the namespace's setup, or (with `collection`) one collection's own.", - "operationId": "save_entity_setup", + "summary": "Create Topic", + "description": "Add a topic to the namespace's vocabulary.", + "operationId": "create_topic", "parameters": [ { "name": "name", @@ -11308,18 +11078,18 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntitySetupSave" + "$ref": "#/components/schemas/TopicCreate" } } } }, "responses": { - "200": { + "201": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntitySetup" + "$ref": "#/components/schemas/TopicDetail" } } } @@ -11337,41 +11107,31 @@ } } }, - "/api/v1/namespaces/{name}/entity-setup/collections/{cid}": { - "delete": { + "/api/v1/topics/merge": { + "post": { "tags": [ - "entities" + "topics" ], - "summary": "Clear Entity Setup", - "description": "The collection follows its parents' setup again.", - "operationId": "clear_entity_setup", - "parameters": [ - { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" + "summary": "Merge Topics", + "description": "Fold topics into one: their labels become its other labels and their recordings are about it.", + "operationId": "merge_topics", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TopicMerge" + } } }, - { - "name": "cid", - "in": "path", - "required": true, - "schema": { - "type": "integer", - "title": "Cid" - } - } - ], + "required": true + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Ok" + "$ref": "#/components/schemas/TopicDetail" } } } @@ -11389,22 +11149,22 @@ } } }, - "/api/v1/namespaces/{name}/entity-setup/apply": { + "/api/v1/topics/{tid}/recordings": { "post": { "tags": [ - "entities" + "topics" ], - "summary": "Apply Entity Setup", - "description": "Analyse the recordings of the namespace (or of a collection and those inside it) again, so their entities follow\nthe setup as it is now.", - "operationId": "apply_entity_setup", + "summary": "Tag Recordings", + "description": "Say recordings of the topic's namespace are about it (accepting suggestions too), or with `remove` that they aren't.", + "operationId": "tag_recordings", "parameters": [ { - "name": "name", + "name": "tid", "in": "path", "required": true, "schema": { - "type": "string", - "title": "Name" + "type": "integer", + "title": "Tid" } } ], @@ -11413,7 +11173,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntitySetupApply" + "$ref": "#/components/schemas/TopicRecordings" } } } @@ -11424,7 +11184,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntitySetupApplied" + "$ref": "#/components/schemas/TopicDetail" } } } @@ -11442,42 +11202,36 @@ } } }, - "/api/v1/namespaces/{name}/entity-types": { - "post": { + "/api/v1/resources/{rid}/topics": { + "get": { "tags": [ - "entities" + "topics" ], - "summary": "Create Entity Type", - "description": "A type of the namespace's own, e.g. \"Client\" or \"Project\"; its code is the name in capitals.", - "operationId": "create_entity_type", + "summary": "Recording Topics", + "description": "The topics a recording is about, and those suggested for it.", + "operationId": "recording_topics", "parameters": [ { - "name": "name", + "name": "rid", "in": "path", "required": true, "schema": { - "type": "string", - "title": "Name" + "type": "integer", + "title": "Rid" } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EntityTypeCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntityTypeInfo" + "type": "array", + "items": { + "$ref": "#/components/schemas/RecordingTopic" + }, + "title": "Response Topics-Recording Topics" } } } @@ -11495,50 +11249,32 @@ } } }, - "/api/v1/namespaces/{name}/entity-types/{code}": { - "patch": { + "/api/v1/entities/{eid}/topic": { + "post": { "tags": [ - "entities" + "topics" ], - "summary": "Update Entity Type", - "operationId": "update_entity_type", + "summary": "Entity To Topic", + "description": "Make a topic-like entity (type TERM) a topic: its names become the topic's labels and the recordings that\nmention it are about the topic. The entity is hidden; deleting the topic shows it again.", + "operationId": "entity_to_topic", "parameters": [ { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" - } - }, - { - "name": "code", + "name": "eid", "in": "path", "required": true, "schema": { - "type": "string", - "title": "Code" + "type": "integer", + "title": "Eid" } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EntityTypeUpdate" - } - } - } - }, "responses": { - "200": { + "201": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntityTypeInfo" + "$ref": "#/components/schemas/TopicDetail" } } } @@ -11554,32 +11290,28 @@ } } } - }, - "delete": { + } + }, + "/api/v1/graph/schema": { + "get": { "tags": [ - "entities" + "graph" ], - "summary": "Delete Entity Type", - "description": "Only a type no entity has.", - "operationId": "delete_entity_type", + "summary": "Graph Schema", + "description": "What the graph holds in this scope: labels, relationship types (and what they join), properties and counts, with\nexample queries. Agents read this before writing Cypher.", + "operationId": "graph_schema", "parameters": [ { - "name": "name", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Name" - } - }, - { - "name": "code", - "in": "path", - "required": true, + "name": "scope", + "in": "query", + "required": false, "schema": { "type": "string", - "title": "Code" - } + "description": "\"global\" (every shared namespace you can read) or \"ns:\"", + "default": "global", + "title": "Scope" + }, + "description": "\"global\" (every shared namespace you can read) or \"ns:\"" } ], "responses": { @@ -11588,7 +11320,9 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Ok" + "type": "object", + "additionalProperties": true, + "title": "Response Graph-Graph Schema" } } } @@ -11606,13 +11340,752 @@ } } }, - "/api/v1/resources/{rid}/metadata": { + "/api/v1/graph/related": { "get": { "tags": [ - "metadata" + "graph" ], - "summary": "Get Recording Metadata", - "operationId": "get_recording_metadata", + "summary": "Graph Related", + "description": "Nodes related to one node, nearest first, with the relationships between them.", + "operationId": "graph_related", + "parameters": [ + { + "name": "node", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "a node id: n, c, r, s, e or e:", + "title": "Node" + }, + "description": "a node id: n, c, r, s, e or e:" + }, + { + "name": "relation", + "in": "query", + "required": false, + "schema": { + "enum": [ + "children", + "parents", + "ancestors", + "descendants", + "neighbours" + ], + "type": "string", + "default": "neighbours", + "title": "Relation" + } + }, + { + "name": "depth", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 8, + "minimum": 1, + "default": 1, + "title": "Depth" + } + }, + { + "name": "types", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "relationship types to follow, comma separated (default: the hierarchy, or any for neighbours)", + "title": "Types" + }, + "description": "relationship types to follow, comma separated (default: the hierarchy, or any for neighbours)" + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 2000, + "minimum": 1, + "default": 200, + "title": "Limit" + } + }, + { + "name": "scope", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "\"global\" (every shared namespace you can read) or \"ns:\"", + "default": "global", + "title": "Scope" + }, + "description": "\"global\" (every shared namespace you can read) or \"ns:\"" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true, + "title": "Response Graph-Graph Related" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/graph/paths": { + "get": { + "tags": [ + "graph" + ], + "summary": "Graph Paths", + "description": "Paths from a to b, shortest first: every simple path up to max_depth hops, or just the shortest ones.", + "operationId": "graph_paths", + "parameters": [ + { + "name": "a", + "in": "query", + "required": true, + "schema": { + "type": "string", + "title": "A" + } + }, + { + "name": "b", + "in": "query", + "required": true, + "schema": { + "type": "string", + "title": "B" + } + }, + { + "name": "max_depth", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 8, + "minimum": 1, + "default": 4, + "title": "Max Depth" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 100, + "minimum": 1, + "default": 10, + "title": "Limit" + } + }, + { + "name": "types", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Types" + } + }, + { + "name": "directed", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": false, + "title": "Directed" + } + }, + { + "name": "shortest", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": false, + "title": "Shortest" + } + }, + { + "name": "scope", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "\"global\" (every shared namespace you can read) or \"ns:\"", + "default": "global", + "title": "Scope" + }, + "description": "\"global\" (every shared namespace you can read) or \"ns:\"" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true, + "title": "Response Graph-Graph Paths" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/graph/query": { + "post": { + "tags": [ + "graph" + ], + "summary": "Graph Query", + "description": "Run a read-only Cypher query over the graph you can read: {columns, rows, nodes, edges, truncated}. Nodes and\nrelationships it returns are also listed in nodes and edges, ready to draw. Read-only tokens may query.", + "operationId": "graph_query", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GraphQuery" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "type": "object", + "title": "Response Graph-Graph Query" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/graph/ask": { + "post": { + "tags": [ + "graph" + ], + "summary": "Ask Graph", + "description": "A question in plain language: the language model writes read-only Cypher, Lens runs it over the graph you can\nread, and you get the answer with the query that found it ({question, cypher, explanation, result}).", + "operationId": "ask_graph", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GraphQuestion" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "type": "object", + "title": "Response Graph-Ask Graph" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/graph/changes": { + "post": { + "tags": [ + "graph" + ], + "summary": "Propose Graph Change", + "description": "Ask for a change to the graph. Proposed by default, for someone with editor access to accept in Proposed\nchanges; `apply` makes it at once, and it can still be undone. Both need editor access to the two namespaces; read-only\ntokens can't ask.", + "operationId": "propose_graph_change", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChangeAsk" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "type": "object", + "title": "Response Graph-Propose Graph Change" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/namespaces/{name}/entity-setup": { + "get": { + "tags": [ + "entities" + ], + "summary": "Get Entity Setup", + "description": "The namespace's entity setup, the collections (you see) with their own, and the types entities may have.", + "operationId": "get_entity_setup", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntitySetupView" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "put": { + "tags": [ + "entities" + ], + "summary": "Save Entity Setup", + "description": "Save the namespace's setup, or (with `collection`) one collection's own.", + "operationId": "save_entity_setup", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntitySetupSave" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntitySetup" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/namespaces/{name}/entity-setup/collections/{cid}": { + "delete": { + "tags": [ + "entities" + ], + "summary": "Clear Entity Setup", + "description": "The collection follows its parents' setup again.", + "operationId": "clear_entity_setup", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + }, + { + "name": "cid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Cid" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/namespaces/{name}/entity-setup/apply": { + "post": { + "tags": [ + "entities" + ], + "summary": "Apply Entity Setup", + "description": "Analyse the recordings of the namespace (or of a collection and those inside it) again, so their entities follow\nthe setup as it is now.", + "operationId": "apply_entity_setup", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntitySetupApply" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntitySetupApplied" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/namespaces/{name}/entity-types": { + "post": { + "tags": [ + "entities" + ], + "summary": "Create Entity Type", + "description": "A type of the namespace's own, e.g. \"Client\" or \"Project\"; its code is the name in capitals.", + "operationId": "create_entity_type", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntityTypeCreate" + } + } + } + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntityTypeInfo" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/namespaces/{name}/entity-types/{code}": { + "patch": { + "tags": [ + "entities" + ], + "summary": "Update Entity Type", + "operationId": "update_entity_type", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + }, + { + "name": "code", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Code" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntityTypeUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntityTypeInfo" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "entities" + ], + "summary": "Delete Entity Type", + "description": "Only a type no entity has.", + "operationId": "delete_entity_type", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + }, + { + "name": "code", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Code" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/resources/{rid}/metadata": { + "get": { + "tags": [ + "metadata" + ], + "summary": "Get Recording Metadata", + "operationId": "get_recording_metadata", "parameters": [ { "name": "rid", @@ -36915,18 +37388,70 @@ "type": "null" } ], - "title": "Role", - "description": "your role on it: through its namespace or its collection (an admin of the collection is an owner)" + "title": "Role", + "description": "your role on it: through its namespace or its collection (an admin of the collection is an owner)" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "space", + "media_kind" + ], + "title": "RecordingSummary" + }, + "RecordingTopic": { + "properties": { + "id": { + "type": "integer", + "title": "Id" + }, + "label": { + "type": "string", + "title": "Label" + }, + "source": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Source" + }, + "weight": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Weight" + }, + "status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Status" } }, "additionalProperties": true, "type": "object", "required": [ "id", - "space", - "media_kind" + "label" ], - "title": "RecordingSummary" + "title": "RecordingTopic" }, "RecordingUpdate": { "properties": { @@ -41462,16 +41987,280 @@ "version": { "anyOf": [ { - "type": "integer" + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Version", + "description": "the template version it was made with" + }, + "model": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Model" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "key" + ], + "title": "StepOutput" + }, + "StepQueued": { + "properties": { + "ok": { + "type": "boolean", + "title": "Ok", + "default": true + }, + "queued": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "string" + } + ], + "title": "Queued", + "description": "how many recordings were queued, or \"scanning\"" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "queued" + ], + "title": "StepQueued" + }, + "StepRun": { + "properties": { + "started_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Started At" + }, + "finished_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Finished At" + }, + "seconds": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Seconds", + "description": "how long it took" + }, + "outcome": { + "anyOf": [ + { + "type": "string", + "enum": [ + "running", + "done", + "skipped", + "failed" + ] + }, + { + "type": "null" + } + ], + "title": "Outcome" + }, + "note": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Note", + "description": "its last message, why it skipped, or its error" + }, + "worker": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Worker" + }, + "log_from": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Log From", + "description": "its first line in the run's log (GET /jobs/{jid}/log numbers lines from 0)" + }, + "log_to": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Log To", + "description": "the line after its last one" + }, + "outputs": { + "items": { + "$ref": "#/components/schemas/StepOutput" + }, + "type": "array", + "title": "Outputs", + "description": "the outputs it saved" + } + }, + "additionalProperties": true, + "type": "object", + "title": "StepRun" + }, + "StopResult": { + "properties": { + "ok": { + "type": "boolean", + "title": "Ok", + "default": true + }, + "stopping": { + "type": "boolean", + "title": "Stopping", + "description": "an answer was being written, and stops after its current piece or step" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "stopping" + ], + "title": "StopResult" + }, + "Stream": { + "properties": { + "id": { + "type": "string", + "title": "Id" + }, + "name": { + "type": "string", + "title": "Name" + }, + "kind": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Kind", + "description": "number, boolean, json, text or log" + }, + "fields": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Fields", + "description": "the numbers a JSON stream carries" + }, + "last_value": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Last Value" + }, + "last_text": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Text" + }, + "last_at": { + "anyOf": [ + { + "type": "string" }, { "type": "null" } ], - "title": "Version", - "description": "the template version it was made with" + "title": "Last At" }, - "model": { + "count": { + "type": "integer", + "title": "Count", + "default": 0 + }, + "stored": { + "type": "integer", + "title": "Stored", + "default": 0 + }, + "dropped": { + "type": "integer", + "title": "Dropped", + "default": 0 + }, + "created_at": { "anyOf": [ { "type": "string" @@ -41480,46 +42269,87 @@ "type": "null" } ], - "title": "Model" + "title": "Created At" } }, "additionalProperties": true, "type": "object", "required": [ - "key" + "id", + "name" ], - "title": "StepOutput" + "title": "Stream" }, - "StepQueued": { + "Suggestion": { + "properties": { + "handling": { + "additionalProperties": true, + "type": "object", + "title": "Handling" + }, + "reason": { + "type": "string", + "title": "Reason" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "handling", + "reason" + ], + "title": "Suggestion" + }, + "TagCount": { + "properties": { + "tag": { + "type": "string", + "title": "Tag" + }, + "recordings": { + "type": "integer", + "title": "Recordings" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "tag", + "recordings" + ], + "title": "TagCount" + }, + "TagsChanged": { "properties": { "ok": { "type": "boolean", "title": "Ok", "default": true }, - "queued": { - "anyOf": [ - { - "type": "integer" - }, - { - "type": "string" - } - ], - "title": "Queued", - "description": "how many recordings were queued, or \"scanning\"" + "changed": { + "type": "integer", + "title": "Changed", + "description": "how many recordings' tags changed" } }, "additionalProperties": true, "type": "object", "required": [ - "queued" + "changed" ], - "title": "StepQueued" + "title": "TagsChanged" }, - "StepRun": { + "TelemetryExport": { "properties": { - "started_at": { + "at": { + "type": "number", + "title": "At" + }, + "ok": { + "type": "boolean", + "title": "Ok" + }, + "error": { "anyOf": [ { "type": "string" @@ -41528,9 +42358,24 @@ "type": "null" } ], - "title": "Started At" + "title": "Error" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "at", + "ok" + ], + "title": "TelemetryExport" + }, + "TelemetryStatus": { + "properties": { + "enabled": { + "type": "boolean", + "title": "Enabled" }, - "finished_at": { + "endpoint": { "anyOf": [ { "type": "string" @@ -41539,73 +42384,65 @@ "type": "null" } ], - "title": "Finished At" + "title": "Endpoint" }, - "seconds": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ], - "title": "Seconds", - "description": "how long it took" + "traces": { + "type": "boolean", + "title": "Traces" }, - "outcome": { - "anyOf": [ - { - "type": "string", - "enum": [ - "running", - "done", - "skipped", - "failed" - ] - }, - { - "type": "null" - } - ], - "title": "Outcome" + "metrics": { + "type": "boolean", + "title": "Metrics" }, - "note": { + "last_traces": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/TelemetryExport" }, { "type": "null" } - ], - "title": "Note", - "description": "its last message, why it skipped, or its error" + ] }, - "worker": { + "last_metrics": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/TelemetryExport" }, { "type": "null" } - ], - "title": "Worker" + ] + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "enabled", + "traces", + "metrics" + ], + "title": "TelemetryStatus", + "description": "What the API process does with telemetry now; each worker follows the same settings on its own." + }, + "TelemetryTestResult": { + "properties": { + "ok": { + "type": "boolean", + "title": "Ok" }, - "log_from": { + "error": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Log From", - "description": "its first line in the run's log (GET /jobs/{jid}/log numbers lines from 0)" + "title": "Error" }, - "log_to": { + "ms": { "anyOf": [ { "type": "integer" @@ -41614,53 +42451,51 @@ "type": "null" } ], - "title": "Log To", - "description": "the line after its last one" - }, - "outputs": { - "items": { - "$ref": "#/components/schemas/StepOutput" - }, - "type": "array", - "title": "Outputs", - "description": "the outputs it saved" - } - }, - "additionalProperties": true, - "type": "object", - "title": "StepRun" - }, - "StopResult": { - "properties": { - "ok": { - "type": "boolean", - "title": "Ok", - "default": true - }, - "stopping": { - "type": "boolean", - "title": "Stopping", - "description": "an answer was being written, and stops after its current piece or step" + "title": "Ms" } }, "additionalProperties": true, "type": "object", "required": [ - "stopping" + "ok" ], - "title": "StopResult" + "title": "TelemetryTestResult" }, - "Stream": { + "Template": { "properties": { "id": { - "type": "string", + "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" }, - "kind": { + "kind": { + "type": "string", + "enum": [ + "prompt", + "report", + "export" + ], + "title": "Kind" + }, + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Description" + }, + "current": { + "type": "integer", + "title": "Current" + }, + "created_at": { "anyOf": [ { "type": "string" @@ -41669,36 +42504,41 @@ "type": "null" } ], - "title": "Kind", - "description": "number, boolean, json, text or log" + "title": "Created At" }, - "fields": { + "updated_at": { "anyOf": [ { - "items": { - "type": "string" - }, - "type": "array" + "type": "string" }, { "type": "null" } ], - "title": "Fields", - "description": "the numbers a JSON stream carries" + "title": "Updated At" }, - "last_value": { + "version": { + "type": "integer", + "title": "Version" + }, + "body": { + "type": "string", + "title": "Body" + }, + "schema": { "anyOf": [ { - "type": "number" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Last Value" + "title": "Schema", + "description": "JSON schema the model's answer must match (prompts)" }, - "last_text": { + "system": { "anyOf": [ { "type": "string" @@ -41707,9 +42547,9 @@ "type": "null" } ], - "title": "Last Text" + "title": "System" }, - "last_at": { + "notes": { "anyOf": [ { "type": "string" @@ -41718,24 +42558,9 @@ "type": "null" } ], - "title": "Last At" - }, - "count": { - "type": "integer", - "title": "Count", - "default": 0 - }, - "stored": { - "type": "integer", - "title": "Stored", - "default": 0 - }, - "dropped": { - "type": "integer", - "title": "Dropped", - "default": 0 + "title": "Notes" }, - "created_at": { + "created_by": { "anyOf": [ { "type": "string" @@ -41744,86 +42569,128 @@ "type": "null" } ], - "title": "Created At" + "title": "Created By" + }, + "history": { + "items": { + "$ref": "#/components/schemas/TemplateVersionInfo" + }, + "type": "array", + "title": "History", + "default": [] } }, "additionalProperties": true, "type": "object", "required": [ "id", - "name" + "name", + "kind", + "current", + "version", + "body" ], - "title": "Stream" + "title": "Template" }, - "Suggestion": { + "TemplateCreate": { "properties": { - "handling": { - "additionalProperties": true, - "type": "object", - "title": "Handling" + "name": { + "type": "string", + "title": "Name" }, - "reason": { + "kind": { "type": "string", - "title": "Reason" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "handling", - "reason" - ], - "title": "Suggestion" - }, - "TagCount": { - "properties": { - "tag": { + "enum": [ + "prompt", + "report", + "export" + ], + "title": "Kind" + }, + "body": { "type": "string", - "title": "Tag" + "title": "Body", + "default": "" }, - "recordings": { - "type": "integer", - "title": "Recordings" - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "tag", - "recordings" - ], - "title": "TagCount" - }, - "TagsChanged": { - "properties": { - "ok": { - "type": "boolean", - "title": "Ok", - "default": true + "schema": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Schema" }, - "changed": { - "type": "integer", - "title": "Changed", - "description": "how many recordings' tags changed" + "system": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "System" + }, + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Description" } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", "required": [ - "changed" + "name", + "kind" ], - "title": "TagsChanged" + "title": "TemplateCreate" }, - "TelemetryExport": { + "TemplatePreview": { "properties": { - "at": { - "type": "number", - "title": "At" - }, "ok": { "type": "boolean", "title": "Ok" }, + "kind": { + "anyOf": [ + { + "type": "string", + "enum": [ + "prompt", + "report", + "export" + ] + }, + { + "type": "null" + } + ], + "title": "Kind" + }, + "rendered": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Rendered" + }, + "result": { + "title": "Result" + }, "error": { "anyOf": [ { @@ -41839,74 +42706,78 @@ "additionalProperties": true, "type": "object", "required": [ - "at", "ok" ], - "title": "TelemetryExport" + "title": "TemplatePreview" }, - "TelemetryStatus": { + "TemplatePreviewRequest": { "properties": { - "enabled": { - "type": "boolean", - "title": "Enabled" + "recording": { + "type": "integer", + "title": "Recording" }, - "endpoint": { + "template": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Endpoint" + "title": "Template" }, - "traces": { - "type": "boolean", - "title": "Traces" + "version": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Version" }, - "metrics": { - "type": "boolean", - "title": "Metrics" + "kind": { + "anyOf": [ + { + "type": "string", + "enum": [ + "prompt", + "report", + "export" + ] + }, + { + "type": "null" + } + ], + "title": "Kind" }, - "last_traces": { + "body": { "anyOf": [ { - "$ref": "#/components/schemas/TelemetryExport" + "type": "string" }, { "type": "null" } - ] + ], + "title": "Body" }, - "last_metrics": { + "schema": { "anyOf": [ { - "$ref": "#/components/schemas/TelemetryExport" + "additionalProperties": true, + "type": "object" }, { "type": "null" } - ] - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "enabled", - "traces", - "metrics" - ], - "title": "TelemetryStatus", - "description": "What the API process does with telemetry now; each worker follows the same settings on its own." - }, - "TelemetryTestResult": { - "properties": { - "ok": { - "type": "boolean", - "title": "Ok" + ], + "title": "Schema" }, - "error": { + "system": { "anyOf": [ { "type": "string" @@ -41915,28 +42786,35 @@ "type": "null" } ], - "title": "Error" + "title": "System" }, - "ms": { + "filename": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Ms" + "title": "Filename" + }, + "run": { + "type": "boolean", + "title": "Run", + "description": "also call the model (prompts only)", + "default": false } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", "required": [ - "ok" + "recording" ], - "title": "TelemetryTestResult" + "title": "TemplatePreviewRequest", + "description": "A saved template (`template`, optional `version`), or the unsaved text in the editor (`body` and friends)." }, - "Template": { + "TemplateSummary": { "properties": { "id": { "type": "integer", @@ -41970,17 +42848,6 @@ "type": "integer", "title": "Current" }, - "created_at": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Created At" - }, "updated_at": { "anyOf": [ { @@ -41992,13 +42859,28 @@ ], "title": "Updated At" }, - "version": { + "versions": { "type": "integer", - "title": "Version" - }, + "title": "Versions", + "default": 0 + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "name", + "kind", + "current" + ], + "title": "TemplateSummary" + }, + "TemplateVersionCreate": { + "properties": { "body": { "type": "string", - "title": "Body" + "title": "Body", + "default": "" }, "schema": { "anyOf": [ @@ -42010,8 +42892,7 @@ "type": "null" } ], - "title": "Schema", - "description": "JSON schema the model's answer must match (prompts)" + "title": "Schema" }, "system": { "anyOf": [ @@ -42035,71 +42916,35 @@ ], "title": "Notes" }, - "created_by": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Created By" - }, - "history": { - "items": { - "$ref": "#/components/schemas/TemplateVersionInfo" - }, - "type": "array", - "title": "History", - "default": [] + "publish": { + "type": "boolean", + "title": "Publish", + "description": "make this the current version", + "default": true } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", - "required": [ - "id", - "name", - "kind", - "current", - "version", - "body" - ], - "title": "Template" + "title": "TemplateVersionCreate" }, - "TemplateCreate": { + "TemplateVersionInfo": { "properties": { - "name": { - "type": "string", - "title": "Name" - }, - "kind": { - "type": "string", - "enum": [ - "prompt", - "report", - "export" - ], - "title": "Kind" - }, - "body": { - "type": "string", - "title": "Body", - "default": "" + "version": { + "type": "integer", + "title": "Version" }, - "schema": { + "notes": { "anyOf": [ { - "additionalProperties": true, - "type": "object" + "type": "string" }, { "type": "null" } ], - "title": "Schema" + "title": "Notes" }, - "system": { + "created_at": { "anyOf": [ { "type": "string" @@ -42108,9 +42953,9 @@ "type": "null" } ], - "title": "System" + "title": "Created At" }, - "description": { + "created_by": { "anyOf": [ { "type": "string" @@ -42119,196 +42964,264 @@ "type": "null" } ], - "title": "Description" + "title": "Created By" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "version" + ], + "title": "TemplateVersionInfo" + }, + "TermSuggestion": { + "properties": { + "word": { + "type": "string", + "title": "Word" + }, + "count": { + "type": "integer", + "title": "Count", + "description": "how often it's said" + }, + "recordings": { + "type": "integer", + "title": "Recordings", + "description": "in how many recordings" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "word", + "count", + "recordings" + ], + "title": "TermSuggestion" + }, + "TicketRequest": { + "properties": { + "ticket": { + "type": "string", + "title": "Ticket" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "ticket" + ], + "title": "TicketRequest" + }, + "TokenLimits": { + "properties": { + "default_days": { + "type": "integer", + "title": "Default Days" + }, + "max_days": { + "type": "integer", + "title": "Max Days" + }, + "never_expire": { + "type": "boolean", + "title": "Never Expire", + "description": "keys may be made that never expire (days: 0)" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "default_days", + "max_days", + "never_expire" + ], + "title": "TokenLimits", + "description": "How long API keys may last, set by admins (the tokens settings)." + }, + "TokenPair": { + "properties": { + "access_token": { + "type": "string", + "title": "Access Token" + }, + "refresh_token": { + "type": "string", + "title": "Refresh Token" + }, + "token_type": { + "type": "string", + "const": "bearer", + "title": "Token Type", + "default": "bearer" + }, + "expires_in": { + "type": "integer", + "title": "Expires In", + "description": "seconds until the access token expires" + }, + "user": { + "$ref": "#/components/schemas/UserPublic" } }, - "additionalProperties": false, + "additionalProperties": true, "type": "object", "required": [ - "name", - "kind" + "access_token", + "refresh_token", + "expires_in", + "user" ], - "title": "TemplateCreate" + "title": "TokenPair" }, - "TemplatePreview": { + "ToolStep": { "properties": { - "ok": { - "type": "boolean", - "title": "Ok" - }, - "kind": { - "anyOf": [ - { - "type": "string", - "enum": [ - "prompt", - "report", - "export" - ] - }, - { - "type": "null" - } - ], - "title": "Kind" - }, - "rendered": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Rendered" + "tool": { + "type": "string", + "title": "Tool" }, - "result": { - "title": "Result" + "args": { + "additionalProperties": true, + "type": "object", + "title": "Args", + "default": {} }, - "error": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Error" + "summary": { + "type": "string", + "title": "Summary", + "default": "" } }, "additionalProperties": true, "type": "object", "required": [ - "ok" + "tool" ], - "title": "TemplatePreview" + "title": "ToolStep" }, - "TemplatePreviewRequest": { + "TopicAbout": { "properties": { "recording": { "type": "integer", "title": "Recording" }, - "template": { + "title": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Template" + "title": "Title" }, - "version": { + "source": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Version" + "title": "Source", + "description": "how it got there: person, entity or analysis" }, - "kind": { + "weight": { "anyOf": [ { - "type": "string", - "enum": [ - "prompt", - "report", - "export" - ] + "type": "number" }, { "type": "null" } ], - "title": "Kind" + "title": "Weight" }, - "body": { + "status": { "anyOf": [ { - "type": "string" + "type": "string", + "enum": [ + "accepted", + "suggested" + ] }, { "type": "null" } ], - "title": "Body" + "title": "Status" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "recording" + ], + "title": "TopicAbout" + }, + "TopicCreate": { + "properties": { + "label": { + "type": "string", + "maxLength": 200, + "minLength": 1, + "title": "Label" }, - "schema": { - "anyOf": [ - { - "additionalProperties": true, - "type": "object" - }, - { - "type": "null" - } - ], - "title": "Schema" + "alt": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Alt", + "default": [] }, - "system": { + "definition": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 2000 }, { "type": "null" } ], - "title": "System" + "title": "Definition" }, - "filename": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Filename" + "broader": { + "items": { + "type": "integer" + }, + "type": "array", + "title": "Broader", + "default": [] }, - "run": { - "type": "boolean", - "title": "Run", - "description": "also call the model (prompts only)", - "default": false + "related": { + "items": { + "type": "integer" + }, + "type": "array", + "title": "Related", + "default": [] } }, "additionalProperties": false, "type": "object", "required": [ - "recording" + "label" ], - "title": "TemplatePreviewRequest", - "description": "A saved template (`template`, optional `version`), or the unsaved text in the editor (`body` and friends)." + "title": "TopicCreate" }, - "TemplateSummary": { + "TopicDetail": { "properties": { "id": { "type": "integer", "title": "Id" }, - "name": { - "type": "string", - "title": "Name" - }, - "kind": { - "type": "string", - "enum": [ - "prompt", - "report", - "export" - ], - "title": "Kind" - }, - "description": { + "namespace": { "anyOf": [ { "type": "string" @@ -42317,13 +43230,21 @@ "type": "null" } ], - "title": "Description" + "title": "Namespace" }, - "current": { - "type": "integer", - "title": "Current" + "label": { + "type": "string", + "title": "Label" }, - "updated_at": { + "alt": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Alt", + "default": [] + }, + "definition": { "anyOf": [ { "type": "string" @@ -42332,55 +43253,49 @@ "type": "null" } ], - "title": "Updated At" + "title": "Definition" }, - "versions": { + "broader": { + "items": { + "$ref": "#/components/schemas/TopicRef" + }, + "type": "array", + "title": "Broader", + "default": [] + }, + "narrower": { + "items": { + "$ref": "#/components/schemas/TopicRef" + }, + "type": "array", + "title": "Narrower", + "default": [] + }, + "related": { + "items": { + "$ref": "#/components/schemas/TopicRef" + }, + "type": "array", + "title": "Related", + "default": [] + }, + "recordings": { "type": "integer", - "title": "Versions", + "title": "Recordings", "default": 0 - } - }, - "additionalProperties": true, - "type": "object", - "required": [ - "id", - "name", - "kind", - "current" - ], - "title": "TemplateSummary" - }, - "TemplateVersionCreate": { - "properties": { - "body": { - "type": "string", - "title": "Body", - "default": "" - }, - "schema": { - "anyOf": [ - { - "additionalProperties": true, - "type": "object" - }, - { - "type": "null" - } - ], - "title": "Schema" }, - "system": { + "from_entity": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "System" + "title": "From Entity" }, - "notes": { + "updated": { "anyOf": [ { "type": "string" @@ -42389,26 +43304,32 @@ "type": "null" } ], - "title": "Notes" + "title": "Updated" }, - "publish": { - "type": "boolean", - "title": "Publish", - "description": "make this the current version", - "default": true + "about": { + "items": { + "$ref": "#/components/schemas/TopicAbout" + }, + "type": "array", + "title": "About", + "default": [] } }, - "additionalProperties": false, + "additionalProperties": true, "type": "object", - "title": "TemplateVersionCreate" + "required": [ + "id", + "label" + ], + "title": "TopicDetail" }, - "TemplateVersionInfo": { + "TopicItem": { "properties": { - "version": { + "id": { "type": "integer", - "title": "Version" + "title": "Id" }, - "notes": { + "namespace": { "anyOf": [ { "type": "string" @@ -42417,9 +43338,22 @@ "type": "null" } ], - "title": "Notes" + "title": "Namespace" }, - "created_at": { + "label": { + "type": "string", + "title": "Label" + }, + "alt": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Alt", + "description": "other labels it goes by (skos:altLabel)", + "default": [] + }, + "definition": { "anyOf": [ { "type": "string" @@ -42428,9 +43362,49 @@ "type": "null" } ], - "title": "Created At" + "title": "Definition" }, - "created_by": { + "broader": { + "items": { + "type": "integer" + }, + "type": "array", + "title": "Broader", + "default": [] + }, + "related": { + "items": { + "type": "integer" + }, + "type": "array", + "title": "Related", + "default": [] + }, + "recordings": { + "type": "integer", + "title": "Recordings", + "description": "recordings about it (accepted)", + "default": 0 + }, + "narrower": { + "type": "integer", + "title": "Narrower", + "description": "topics that have it as broader", + "default": 0 + }, + "from_entity": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "From Entity", + "description": "the entity it was made from, hidden while the topic exists" + }, + "updated": { "anyOf": [ { "type": "string" @@ -42439,141 +43413,180 @@ "type": "null" } ], - "title": "Created By" + "title": "Updated" } }, "additionalProperties": true, "type": "object", "required": [ - "version" + "id", + "label" ], - "title": "TemplateVersionInfo" + "title": "TopicItem" }, - "TermSuggestion": { + "TopicList": { "properties": { - "word": { - "type": "string", - "title": "Word" - }, - "count": { + "total": { "type": "integer", - "title": "Count", - "description": "how often it's said" + "title": "Total" }, - "recordings": { - "type": "integer", - "title": "Recordings", - "description": "in how many recordings" + "items": { + "items": { + "$ref": "#/components/schemas/TopicItem" + }, + "type": "array", + "title": "Items" } }, "additionalProperties": true, "type": "object", "required": [ - "word", - "count", - "recordings" + "total", + "items" ], - "title": "TermSuggestion" + "title": "TopicList" }, - "TicketRequest": { + "TopicMerge": { "properties": { - "ticket": { - "type": "string", - "title": "Ticket" + "keep": { + "type": "integer", + "title": "Keep" + }, + "others": { + "items": { + "type": "integer" + }, + "type": "array", + "minItems": 1, + "title": "Others" } }, "additionalProperties": false, "type": "object", "required": [ - "ticket" + "keep", + "others" ], - "title": "TicketRequest" + "title": "TopicMerge" }, - "TokenLimits": { + "TopicRecordings": { "properties": { - "default_days": { - "type": "integer", - "title": "Default Days" - }, - "max_days": { - "type": "integer", - "title": "Max Days" + "recordings": { + "items": { + "type": "integer" + }, + "type": "array", + "maxItems": 500, + "minItems": 1, + "title": "Recordings" }, - "never_expire": { + "remove": { "type": "boolean", - "title": "Never Expire", - "description": "keys may be made that never expire (days: 0)" + "title": "Remove", + "description": "say they aren't about it", + "default": false } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", "required": [ - "default_days", - "max_days", - "never_expire" + "recordings" ], - "title": "TokenLimits", - "description": "How long API keys may last, set by admins (the tokens settings)." + "title": "TopicRecordings" }, - "TokenPair": { + "TopicRef": { "properties": { - "access_token": { - "type": "string", - "title": "Access Token" - }, - "refresh_token": { - "type": "string", - "title": "Refresh Token" - }, - "token_type": { - "type": "string", - "const": "bearer", - "title": "Token Type", - "default": "bearer" - }, - "expires_in": { + "id": { "type": "integer", - "title": "Expires In", - "description": "seconds until the access token expires" + "title": "Id" }, - "user": { - "$ref": "#/components/schemas/UserPublic" + "label": { + "type": "string", + "title": "Label" } }, "additionalProperties": true, "type": "object", "required": [ - "access_token", - "refresh_token", - "expires_in", - "user" + "id", + "label" ], - "title": "TokenPair" + "title": "TopicRef" }, - "ToolStep": { + "TopicUpdate": { "properties": { - "tool": { - "type": "string", - "title": "Tool" + "label": { + "anyOf": [ + { + "type": "string", + "maxLength": 200, + "minLength": 1 + }, + { + "type": "null" + } + ], + "title": "Label" }, - "args": { - "additionalProperties": true, - "type": "object", - "title": "Args", - "default": {} + "alt": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Alt" }, - "summary": { - "type": "string", - "title": "Summary", - "default": "" + "definition": { + "anyOf": [ + { + "type": "string", + "maxLength": 2000 + }, + { + "type": "null" + } + ], + "title": "Definition", + "description": "an empty string clears it" + }, + "broader": { + "anyOf": [ + { + "items": { + "type": "integer" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Broader" + }, + "related": { + "anyOf": [ + { + "items": { + "type": "integer" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Related" } }, - "additionalProperties": true, + "additionalProperties": false, "type": "object", - "required": [ - "tool" - ], - "title": "ToolStep" + "title": "TopicUpdate" }, "TunnelStatus": { "properties": {