From cd6c6ebe981040cf5ca35b8f49a4b6cb214f4dfe Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 15:01:01 +0000 Subject: [PATCH] feat(graph): sources, sensors, people and agents as Source nodes linked to what they brought in Whoever brought an asset in (the actor of its asset.added activity: a storage source, a sensor, a person, an automation, a routine, an import hook, or Lens) is a Source node in the property graph with an ADDED relationship to the asset, part of the hierarchy, so the explorer, Cypher and the MCP graph tools answer where Lens learns about each entity. The canvas draws sources linked to what their assets mention (Brought in), and the Timeline page's Graph button opens it on the sources alone (/graph?show=actors). events_content.added_by is the one place that says who added an asset; the timeline's activities use it too. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Ln25ykE6uBDqx21WBU94SX --- README.md | 3 +- changelog.d/graph-actors.md | 6 ++ docs/graph.md | 13 ++-- docs/requirements.md | 1 + docs/timeline.md | 14 +++- fastapi_backend/app/api/v1/routes/graph.py | 2 +- fastapi_backend/app/domain/events_content.py | 19 ++++-- fastapi_backend/app/domain/graph.py | 37 ++++++++++- fastapi_backend/app/domain/graph_model.py | 66 +++++++++++++++++-- fastapi_backend/tests/api/test_graph.py | 33 ++++++++++ .../__tests__/graph-explorer.test.ts | 38 +++++++++++ .../app/openapi-client/types.gen.ts | 2 +- .../components/graph/graph-page.tsx | 8 ++- nextjs-frontend/components/graph/model.ts | 34 ++++++++-- nextjs-frontend/components/graph/shape.tsx | 10 +++ .../components/timeline/timeline-page.tsx | 28 +++++--- nextjs-frontend/openapi.json | 4 +- 17 files changed, 278 insertions(+), 40 deletions(-) create mode 100644 changelog.d/graph-actors.md diff --git a/README.md b/README.md index 3ce9b800d..b73346b39 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,8 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p recognised by voice (long recordings go to a speech provider in pieces that fit its limits), text on screen and in scans, faces (off by default), NSFW pictures flagged by a model on your own server (off by default, per namespace), low quality images enhanced before they're read (off by default), entities and topics in a knowledge graph you can explore, query with Cypher or - SPARQL, and see as it was at any version. Every entity has its own page at a wiki address + SPARQL, and see as it was at any version, where every source, sensor, person and agent is a node linked to what it + brought in. Every entity has its own page at a wiki address (`/wiki//`), and entities, topics and people are edited and merged from their lists, the graph or an asset, with Undo instead of a confirm. Names get their real types (people, places, organisations, events, works) by rules, without a model, and a decision model types the ones the rules can't. Find what is most like a passage, an diff --git a/changelog.d/graph-actors.md b/changelog.d/graph-actors.md new file mode 100644 index 000000000..457c1df8f --- /dev/null +++ b/changelog.d/graph-actors.md @@ -0,0 +1,6 @@ +**Sources, sensors, people and agents in the graph.** Whoever brought an asset in (the actor of its activity on the +timeline: a storage source, a sensor, a person, an automation, a routine, an import hook, or Lens itself) is now a +Source node in the graph with an ADDED link to the asset, so `(Source)-[:ADDED]->(Recording)-[:MENTIONS]->(Entity)` +says where Lens learns about each person, place or organisation. The canvas draws sources linked to what their assets +mention, the explorer lists an asset's source among its parents, and the Timeline page's Graph button opens the canvas +on the sources alone ([Actors in the graph](docs/timeline.md#actors-in-the-graph)). diff --git a/docs/graph.md b/docs/graph.md index b39ae697e..d57a7f06a 100644 --- a/docs/graph.md +++ b/docs/graph.md @@ -47,6 +47,7 @@ to itself and has one. On a computer the Find in graph box has the focus, so typ | Speaker | `s` | a person: 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 | +| Source | `a:`, such as `a:source/12` or `a:account/1` | who brought assets in, as the [timeline](timeline.md)'s actors: name, actor (the activity's actor id), type (Service, Person or Application), kind (source, sensor, person, hook or agent), recordings, namespaces | 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 @@ -65,10 +66,14 @@ and quiet types (dates and numbers) are left out, as in the overview graph. | ABOUT | Recording → Topic | source, weight | | NARROWER | Topic → Topic (from the broader one) | | | RELATED | Topic → Topic | | - -CONTAINS, HAS_SPEAKER, MENTIONS, SAID, ABOUT and NARROWER are the hierarchy: an entity's parents are the assets that -mention it and the people who said or wrote it; its ancestors go on up to collections and the namespace. A topic's parents -are its broader topics and the assets about it. Topics are each namespace's vocabulary ([Topics](topics.md)). +| ADDED | Source → Recording (the source brought the asset in) | | + +CONTAINS, HAS_SPEAKER, MENTIONS, SAID, ABOUT, NARROWER and ADDED are the hierarchy: an entity's parents are the assets +that mention it and the people who said or wrote it; its ancestors go on up to collections and the namespace. A topic's +parents are its broader topics and the assets about it. Topics are each namespace's vocabulary ([Topics](topics.md)). +An asset's parents are its collection and the source that added it, so `MATCH (s:Source)-[:ADDED]->(:Recording)-[:MENTIONS]->(e:Organisation) RETURN s.name, count(DISTINCT e)` +says where Lens learns about each organisation. On the canvas, a source links to what its assets mention (Brought in), +and the Timeline page's Graph button opens the canvas on the sources alone. ## Scope and rights diff --git a/docs/requirements.md b/docs/requirements.md index fff90f2f6..f3aa6b235 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -200,6 +200,7 @@ request, to another check that proves the same thing; loosening a requirement or | Low quality images enhanced before they're read, off by default | [test_enhance.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_enhance.py) `test_off_by_default_the_original_is_read`, `test_a_low_quality_image_is_read_from_its_enhanced_copy`, `test_a_good_image_is_left_as_it_is`, `test_agents_and_automations_enhance_too`, `test_the_copy_is_encrypted_where_the_files_are`; [enhance.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/enhance.test.tsx) | | Entities and topics in a knowledge graph to explore and query with Cypher or SPARQL | [test_graph.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_graph.py) `test_query`; [test_rdf.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_rdf.py) `test_sparql`; [journeys.mjs](https://github.com/adeelahmad/lense/blob/main/ci/clicks/journeys.mjs) `graph-find` | | The graph as it was at any version | [test_graph_history.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_graph_history.py) `test_the_explorer_and_cypher_as_of_a_version`, `test_the_canvas_as_of_a_version`; [test_graph_history.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_graph_history.py) `test_every_curation_is_an_event_and_every_version_replays` | +| Sources, sensors, people and agents as actors in the graph, with ADDED links to what they brought in, on the canvas, in the explorer and in Cypher | [test_graph.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_graph.py) `test_sources_are_actors_in_the_graph`; jest [graph-explorer.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/graph-explorer.test.ts) `shows a source only while something it brought in is visible` | | Every entity's own page at `/wiki//` | [test_entities.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_entities.py) `test_wiki_addresses`; [wiki-page.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/wiki-page.test.tsx); [journeys.mjs](https://github.com/adeelahmad/lense/blob/main/ci/clicks/journeys.mjs) `entity-find` | | Entities, topics and people edited and merged from their lists, the graph or an asset, with Undo instead of a confirm | [test_entities.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_entities.py) `test_suggestions_and_merge_undo`; [entities-curate.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/entities-curate.test.tsx); [topics-curate.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/topics-curate.test.tsx); [recording-entities-edit.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/recording-entities-edit.test.tsx); [journeys.mjs](https://github.com/adeelahmad/lense/blob/main/ci/clicks/journeys.mjs) `entity-merge`, `graph-merge`, `speaker-rename` | | Names get their real types (people, places, organisations, events, works) by rules, without a model; older Terms are typed on upgrade | [test_name_types.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_name_types.py) `test_names_get_the_type_their_words_give`, `test_analysis_types_people_places_and_events`, `test_the_upgrade_types_the_old_terms_and_keeps_what_people_chose` | diff --git a/docs/timeline.md b/docs/timeline.md index 5f256fd52..75396ca58 100644 --- a/docs/timeline.md +++ b/docs/timeline.md @@ -16,7 +16,8 @@ Status: in progress. The studio's timeline is built in steps; only what is merge | Ask about an item: talk to the assistant about it from the item, in the chat beside the page | built | | What each item caused (automation runs, approvals), and Approve and Decline on waiting approvals | planned | | Tagging the agent in a comment, so it answers in the thread | built | -| Sources, sensors, people and agents as actors in the graph; a For you order learned from what each person reacts to, comments on and hides | planned | +| Sources, sensors, people and agents as actors in the graph: a Source node with ADDED links, on the canvas, in the explorer and in Cypher | built | +| A For you order learned from what each person reacts to, comments on and hides | planned | ## What shows @@ -109,6 +110,17 @@ ledger against their conversation and the item's namespace; when no model is set used up, the reply says so instead. **Settings → AI assistant → Answer when tagged in a comment** (`ai.answer_comments`, on) turns it off; without a tag nothing is asked of the model. +## Actors in the graph + +Whoever brought an asset in, the actor of its `asset.added` activity (a storage source, a sensor, a person, an +automation, a routine, an import hook, or Lens itself), is a **Source** node in the [graph](graph.md) with an **ADDED** +relationship to the asset, so the graph says where Lens learns about each person, place or organisation: +`(Source)-[:ADDED]->(Recording)-[:MENTIONS]->(Entity)`. The explorer's parents of an asset are its collection and its +source; on the canvas a source links to what its assets mention (a *Brought in* edge, one per source and entity, +weighted by mentions), and the Timeline page's **Graph** button opens the canvas on the sources alone +(`/graph?show=actors`). Agents read the same through `GET /api/v1/graph/related`, `POST /api/v1/graph/query` and the +MCP graph tools. Nothing is stored for it: the nodes come from each asset's own record. + ## Review marks Each person marks activities for themselves alone; nobody else sees or sets them, admins included. diff --git a/fastapi_backend/app/api/v1/routes/graph.py b/fastapi_backend/app/api/v1/routes/graph.py index be8cb66d9..0ee496ff9 100644 --- a/fastapi_backend/app/api/v1/routes/graph.py +++ b/fastapi_backend/app/api/v1/routes/graph.py @@ -79,7 +79,7 @@ def graph_related( user: CurrentUser, acl: Acl, db: Db, - node: str = Query(description="a node id: n, c, r, s, e or e:"), + node: str = Query(description="a node id: n, c, r, s, e or e:, t, or a: for a source"), relation: Literal["children", "parents", "ancestors", "descendants", "neighbours"] = "neighbours", depth: int = Query(1, ge=1, le=8), types: str | None = Query( diff --git a/fastapi_backend/app/domain/events_content.py b/fastapi_backend/app/domain/events_content.py index 9fdaba553..572d3ec13 100644 --- a/fastapi_backend/app/domain/events_content.py +++ b/fastapi_backend/app/domain/events_content.py @@ -407,16 +407,27 @@ def _asset(db, r, types): } -def _activities(db, rows): - """The rows as activities of their kinds (a row whose created_at isn't a time is skipped).""" +def added_by(db, rows): + """{recording id: the actor that brought it in}, for recording rows carrying id, space, remote, created_by and + sensor: the asset.added activity's actor (an automation, the storage source, whoever made it, the upload's account, + a sensor, whoever queued its first job, else Lens). The graph's Source nodes come from it (graph_model.py).""" rows = [r for r in rows if r] ids = [r["id"] for r in rows] if not ids: - return [] + return {} first = _first_jobs(db, ids) uploads = {u["recording"]: u for u in db.rows("SELECT recording, account, email FROM upload WHERE recording IN $ids", ids=ids)} labels = {r["id"]: (_label_of(r, first.get(r["id"]), uploads.get(r["id"])), r.get("space")) for r in rows} who = actors(db, labels.values()) + return {rid: who[label] for rid, label in labels.items()} + + +def _activities(db, rows): + """The rows as activities of their kinds (a row whose created_at isn't a time is skipped).""" + rows = [r for r in rows if r] + if not rows: + return [] + who = added_by(db, rows) srcs = _lookup( db, "storage_source", @@ -430,7 +441,7 @@ def _activities(db, rows): published = events.stamp(r["created_at"]) except (TypeError, ValueError): continue - actor = who[labels[r["id"]]] + actor = who[r["id"]] obj = _asset(db, r, types) kind = _kind(r, obj["content_type"], (srcs.get((r.get("remote") or {}).get("source")) or {}).get("type"), actor) if kind == "email.received": diff --git a/fastapi_backend/app/domain/graph.py b/fastapi_backend/app/domain/graph.py index 039f8baa4..df9b9e968 100644 --- a/fastapi_backend/app/domain/graph.py +++ b/fastapi_backend/app/domain/graph.py @@ -65,6 +65,35 @@ def build(db, cfg, scope="global", allowed=None, as_of=None): "recordings": recs_per[r["id"]], "refs": [r["id"]], } + # who brought each asset in, as the activity stream's actors: a Source node each, linked to what they mention + from . import events_content, graph_model + + recs = db.rows("SELECT record::id(id) AS id, space, remote, created_by, sensor FROM recording WHERE space IN $s", s=nids) + src_of = {} + who = events_content.added_by(db, recs) + for r in recs: + a = who.get(r["id"]) + if not a: + continue + key = graph_model.source_node_id(a["id"]) + src_of[r["id"]] = key + n = nodes.setdefault( + key, + { + "id": key, + "kind": "source", + "label": a["name"], + "type": graph_model.actor_kind(a["id"]), + "ns": set(), + "weight": 0, + "refs": [], + }, + ) + n["weight"] += 1 + n["ns"].add(names[r["space"]]) + for n in nodes.values(): + if n["kind"] == "source": + n["ns"] = sorted(n["ns"]) counts = {r["entity"]: r["n"] for r in db.rows("SELECT entity, count() AS n FROM mentions WHERE space IN $s GROUP BY entity", s=nids)} shown = {} for r in db.rows("SELECT entity, text, count() AS n FROM mentions WHERE space IN $s GROUP BY entity, text", s=nids): @@ -123,18 +152,22 @@ def edge(a, b, k): for i in range(len(g)): for j in range(i + 1, len(g)): edge(g[i], g[j], "together") - seg_ents, seg_spk = defaultdict(set), {} - for r in db.rows("SELECT record::id(in) AS seg, entity, speaker FROM mentions WHERE space IN $s", s=nids): + seg_ents, seg_spk, seg_src = defaultdict(set), {}, {} + for r in db.rows("SELECT record::id(in) AS seg, entity, speaker, recording FROM mentions WHERE space IN $s", s=nids): n = node_of.get(r["entity"]) if n in nodes: seg_ents[r["seg"]].add(n) seg_spk[r["seg"]] = r.get("speaker") + seg_src[r["seg"]] = src_of.get(r.get("recording")) for sid, es in seg_ents.items(): who = f"s{seg_spk[sid]}" if seg_spk.get(sid) else None + src = seg_src.get(sid) es = sorted(es) for i, e in enumerate(es): if who in nodes: edge(who, e, "mentions") + if src in nodes: + edge(src, e, "added") for f in es[i + 1 :]: edge(e, f, "mentioned together") for ln in db.rows("SELECT record::id(in) AS a, record::id(out) AS b FROM same_as"): diff --git a/fastapi_backend/app/domain/graph_model.py b/fastapi_backend/app/domain/graph_model.py index 7b0645970..5318075d7 100644 --- a/fastapi_backend/app/domain/graph_model.py +++ b/fastapi_backend/app/domain/graph_model.py @@ -11,6 +11,9 @@ 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. +- `a:` Source {actor, type, kind, recordings}: who brought assets in, as the activity stream's actors + (events_content.added_by): a storage source (`a:source/12`), a sensor, a person (`a:account/1`), an automation, a + routine, an import hook or Lens itself. `kind` is source, sensor, person, hook or agent; `type` the AS2 actor type. Relationships, all directed (a query may ignore the direction): @@ -25,9 +28,11 @@ - 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) +- ADDED: Source -> Recording, the source brought the recording in -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. +CONTAINS, HAS_SPEAKER, MENTIONS, SAID, ABOUT, NARROWER and ADDED make the hierarchy that parents, children, ancestors +and descendants follow, so a topic's parents are its broader topics and the recordings about it, and a recording's +parents are its collection and the source that added 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. @@ -55,9 +60,10 @@ "ABOUT", "NARROWER", "RELATED", + "ADDED", ) -HIERARCHY = ("CONTAINS", "HAS_SPEAKER", "MENTIONS", "SAID", "ABOUT", "NARROWER") -NODE_LABELS = ("Namespace", "Collection", "Recording", "Speaker", "Entity", "Topic") +HIERARCHY = ("CONTAINS", "HAS_SPEAKER", "MENTIONS", "SAID", "ABOUT", "NARROWER", "ADDED") +NODE_LABELS = ("Namespace", "Collection", "Recording", "Speaker", "Entity", "Topic", "Source") # the overview graph's edge kinds (graph.py, the web app's legend) for the relationship types that have one KIND = { "SAID": "mentions", @@ -71,6 +77,7 @@ "ABOUT": "about", "NARROWER": "narrower", "RELATED": "related", + "ADDED": "added", } RELATIONS = ("children", "parents", "ancestors", "descendants", "neighbours") MAX_RESULTS = 2000 @@ -209,9 +216,14 @@ def build(db, scope="global", readable=None, recordings=None, as_of=None): for c in cols: g.link("CONTAINS", f"c{c['parent']}" if c.get("parent") else f"n{c['space']}", f"c{c['id']}") - for r in db.rows("SELECT record::id(id) AS id, space, collection, title, recorded_at, media FROM recording WHERE space IN $s", s=sids): + recs = [] + for r in db.rows( + "SELECT record::id(id) AS id, space, collection, title, recorded_at, media, remote, created_by, sensor FROM recording WHERE space IN $s", + s=sids, + ): if not keep(r["id"]): continue + recs.append(r) date = r.get("recorded_at") g.add( f"r{r['id']}", @@ -225,6 +237,8 @@ def build(db, scope="global", readable=None, recordings=None, as_of=None): home = f"c{r['collection']}" if r.get("collection") and f"c{r['collection']}" in g.nodes else f"n{r['space']}" g.link("CONTAINS", home, f"r{r['id']}") + _sources(g, db, recs, names) + talk = db.rows( "SELECT speaker, recording, math::sum(dur) AS ms FROM segment WHERE space IN $s AND speaker > 0 GROUP BY speaker, recording", s=sids ) @@ -320,6 +334,48 @@ def build(db, scope="global", readable=None, recordings=None, as_of=None): return g +def actor_kind(actor_id): + """What an actor is, from its id: source (a storage source), sensor, person, hook (an import hook) or agent (an + automation, a routine, the assistant, Lens).""" + table = str(actor_id or "").removeprefix("lens:").split("/")[0] + return {"source": "source", "sensor": "sensor", "account": "person", "email": "person", "import_hook": "hook"}.get(table, "agent") + + +def source_node_id(actor_id): + """The Source node of an actor: a:source/12, a:account/1, a:app.""" + return f"a:{str(actor_id).removeprefix('lens:')}" + + +def _sources(g, db, recs, names): + """A Source node for whoever brought each recording in, with an ADDED relationship to it.""" + from . import events_content + + who = events_content.added_by(db, recs) + actors, added = {}, defaultdict(list) + for r in recs: + a = who.get(r["id"]) + if not a: + continue + nid = source_node_id(a["id"]) + actors.setdefault(nid, a) + added[nid].append(r) + for nid, a in actors.items(): + ns = sorted({names[r["space"]] for r in added[nid]}) + g.add( + nid, + ["Source"], + name=a["name"], + actor=a["id"], + type=a["type"], + kind=actor_kind(a["id"]), + namespace=ns[0] if len(ns) == 1 else None, + namespaces=ns, + recordings=len(added[nid]), + ) + for r in added[nid]: + g.link("ADDED", nid, f"r{r['id']}") + + 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).""" diff --git a/fastapi_backend/tests/api/test_graph.py b/fastapi_backend/tests/api/test_graph.py index 6c09ecc14..f989a4253 100644 --- a/fastapi_backend/tests/api/test_graph.py +++ b/fastapi_backend/tests/api/test_graph.py @@ -124,3 +124,36 @@ def test_ask_in_plain_language(llm, env): bad = c.post("/api/v1/graph/ask", json={"question": "delete everything"}, headers=h) assert bad.status_code == 422 assert c.post("/api/v1/graph/query", json={"query": "MATCH (n:Namespace) RETURN count(*)"}, headers=h).json()["rows"] == [[1]] + + +def test_sources_are_actors_in_the_graph(env, db): + """Whoever brought an asset in (the activity stream's actor) is a Source node with an ADDED relationship to it, in + the explorer, in Cypher and on the canvas (docs/graph.md, docs/timeline.md).""" + from app.domain import store + + c, h = env.c, env.h["viewer"] + ed = db.one("SELECT record::id(id) AS id FROM account WHERE email = 'ed@x.io'")["id"] + db.q("UPDATE $r SET created_by = $who", r=store.R("recording", env.a), who=ed) + s = c.get("/api/v1/graph/schema", params={"scope": "ns:pods"}, headers=h).json() + assert next(x for x in s["labels"] if x["label"] == "Source")["count"] == 2 # the editor, and Lens for the rest + rel = next(r for r in s["relationships"] if r["type"] == "ADDED") + assert rel["from_to"] == ["Source->Recording"] and rel["hierarchy"] + # a recording's parents are its collection and the source that added it + up = c.get("/api/v1/graph/related", params={"node": f"r{env.a}", "relation": "parents", "scope": "ns:pods"}, headers=h).json() + src = [n for n in up["nodes"] if n["labels"] == ["Source"]] + assert len(src) == 1 and src[0]["id"] == f"a:account/{ed}" + assert src[0]["kind"] == "person" and src[0]["type"] == "Person" and src[0]["recordings"] == 1 + assert any(e["type"] == "ADDED" and e["a"] == f"a:account/{ed}" and e["b"] == f"r{env.a}" for e in up["edges"]) + # Cypher walks from the source through what it added to what that mentions + q = ( + "MATCH (s:Source)-[:ADDED]->(r:Recording)-[:MENTIONS]->(e:Organisation) " + "RETURN s.kind AS kind, s.name AS name, count(DISTINCT r) AS assets ORDER BY kind" + ) + rows = c.post("/api/v1/graph/query", json={"query": q, "scope": "ns:pods"}, headers=h).json()["rows"] + assert [r[0] for r in rows] == ["agent", "person"] and rows[0][1] == "Lens" and rows[0][2] >= 1 + # the canvas draws sources too, linked to the entities their assets mention + canvas = c.get("/api/v1/graph", params={"scope": "ns:pods"}, headers=h).json() + srcs = {n["id"]: n for n in canvas["nodes"] if n["kind"] == "source"} + assert srcs["a:app"]["label"] == "Lens" and srcs["a:app"]["type"] == "agent" and srcs["a:app"]["ns"] == ["pods"] + assert srcs["a:app"]["weight"] >= 2 + assert any(e["kind"] == "added" and "a:app" in (e["a"], e["b"]) for e in canvas["edges"]) diff --git a/nextjs-frontend/__tests__/graph-explorer.test.ts b/nextjs-frontend/__tests__/graph-explorer.test.ts index cd9fb847c..0ce7b71ea 100644 --- a/nextjs-frontend/__tests__/graph-explorer.test.ts +++ b/nextjs-frontend/__tests__/graph-explorer.test.ts @@ -134,6 +134,44 @@ describe("explored nodes", () => { }); }); +describe("sources as actors", () => { + const gmail = fromApiNode({ + id: "a:source/12", + labels: ["Source"], + name: "Work Gmail", + kind: "source", + namespaces: ["home"], + recordings: 37, + }); + const acme = fromApiNode({ + id: "e:acme", + labels: ["Entity", "Organisation"], + name: "Acme", + type: "ORG", + mentions: 4, + }); + + it("turns a Source node into a source on the canvas, sized by what it brought in", () => { + expect(gmail).toMatchObject({ + kind: "source", + type: "source", + label: "Work Gmail", + weight: 37, + ns: ["home"], + refs: [], + }); + expect(nodeHref(gmail)).toBeNull(); + }); + + it("shows a source only while something it brought in is visible", () => { + const g = { nodes: [gmail, acme], edges: [{ a: "a:source/12", b: "e:acme", w: 3, kind: "added" }] }; + const on = filterGraph(g, { groups: new Set(["source", "ORG"]), kinds: new Set(["added"]), minWeight: 1 }); + expect(on.nodes.map((n) => n.id).sort()).toEqual(["a:source/12", "e:acme"]); + const off = filterGraph(g, { groups: new Set(["source", "ORG"]), kinds: new Set(["mentions"]), minWeight: 1 }); + expect(off.nodes).toEqual([]); + }); +}); + describe("asking the graph", () => { it("tells Cypher from a question", () => { expect(looksLikeCypher("MATCH (e) RETURN e")).toBe(true); diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index cd90d53b9..b8b327119 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -41326,7 +41326,7 @@ export type GraphRelatedData = { /** * Node * - * a node id: n, c, r, s, e or e: + * a node id: n, c, r, s, e or e:, t, or a: for a source */ node: string; /** diff --git a/nextjs-frontend/components/graph/graph-page.tsx b/nextjs-frontend/components/graph/graph-page.tsx index f87ce1aed..66ce1ba69 100644 --- a/nextjs-frontend/components/graph/graph-page.tsx +++ b/nextjs-frontend/components/graph/graph-page.tsx @@ -43,6 +43,9 @@ import { useArchive } from "@/lib/hooks/session"; const DEFAULT_KINDS = new Set(EDGE_KINDS.map((k) => k.key).filter((k) => k !== "maybe the same voice")); const ALL_GROUPS = new Set(NODE_GROUPS.map((g) => g.key)); +// ?show=actors (the Timeline page's Graph button): the sources and what their assets mention, nothing else +const ACTOR_GROUPS = new Set(NODE_GROUPS.map((g) => g.key).filter((k) => k !== "speaker")); +const ACTOR_KINDS = new Set(["added"]); /** True at 1280px and up, where the node panel has its own column (below that it opens as a drawer). */ function useWide(): boolean { @@ -82,9 +85,10 @@ export function GraphPage() { const scope = scopeMode === "all" || !ns ? "global" : `ns:${ns}`; const view = params.get("view") === "table" ? "table" : "graph"; const asOf = params.get("as_of"); + const actors = params.get("show") === "actors"; - const [groups, setGroups] = useState>(ALL_GROUPS); - const [kinds, setKinds] = useState>(DEFAULT_KINDS); + const [groups, setGroups] = useState>(actors ? ACTOR_GROUPS : ALL_GROUPS); + const [kinds, setKinds] = useState>(actors ? ACTOR_KINDS : DEFAULT_KINDS); const [minWeight, setMinWeight] = useState(1); const [selected, setSelected] = useState(null); const [filtersOpen, setFiltersOpen] = useState(false); diff --git a/nextjs-frontend/components/graph/model.ts b/nextjs-frontend/components/graph/model.ts index 2251227d1..cbb6745f3 100644 --- a/nextjs-frontend/components/graph/model.ts +++ b/nextjs-frontend/components/graph/model.ts @@ -3,7 +3,7 @@ * server's layout, and typed, weighted edges. Filtering, sizing, keyboard movement and the text summary live here. */ -export type NodeKind = "speaker" | "entity" | "recording" | "collection" | "namespace" | "topic"; +export type NodeKind = "speaker" | "entity" | "recording" | "collection" | "namespace" | "topic" | "source"; export type GraphNode = { id: string; @@ -30,6 +30,7 @@ export type GraphData = { /** Node groups in the filter list, in the design's order. Speakers first, then entity types. */ export const NODE_GROUPS: { key: string; label: string; one?: string; shape: Shape }[] = [ { key: "speaker", label: "People", one: "Person", shape: "circle" }, + { key: "source", label: "Sources", one: "Source", shape: "cloud" }, { key: "PERSON", label: "Named people", one: "Named person", shape: "ring" }, { key: "ORG", label: "Organisations", shape: "square" }, { key: "PRODUCT", label: "Products", shape: "diamond" }, @@ -55,7 +56,8 @@ export type Shape = | "doc" | "folder" | "octagon" - | "tag"; + | "tag" + | "cloud"; /** Node kinds that only appear once you explore (a node's parents, ancestors…), never in the overview. */ export const STRUCTURE_KINDS = new Set(["recording", "collection", "namespace", "topic"]); @@ -92,6 +94,7 @@ export const EDGE_KINDS: { { key: "about", label: "About", dash: "5 2", width: 1.2 }, { key: "narrower", label: "Narrower", width: 1.4 }, { key: "related", label: "Related", dash: "1 2", width: 1.1 }, + { key: "added", label: "Brought in", dash: "3 2", width: 1.3 }, ]; export function edgeStyle(kind: string) { @@ -129,7 +132,7 @@ export type GraphFilter = { minWeight: number; }; -/** The visible part of the graph. Entities left with no visible link are hidden; speakers always stay. */ +/** The visible part of the graph. Entities and sources left with no visible link are hidden; speakers always stay. */ export function filterGraph( g: Pick, f: GraphFilter, @@ -139,7 +142,9 @@ export function filterGraph( (e) => inGroup.has(e.a) && inGroup.has(e.b) && f.kinds.has(e.kind) && (ALWAYS.has(e.kind) || e.w >= f.minWeight), ); const linked = new Set(edges.flatMap((e) => [e.a, e.b])); - const nodes = g.nodes.filter((n) => inGroup.has(n.id) && (n.kind !== "entity" || linked.has(n.id))); + const nodes = g.nodes.filter( + (n) => inGroup.has(n.id) && ((n.kind !== "entity" && n.kind !== "source") || linked.has(n.id)), + ); return { nodes, edges }; } @@ -196,6 +201,7 @@ export function nodeRadius( if (n.kind === "namespace") return 14; if (n.kind === "collection") return 11; if (n.kind === "recording") return 9; + if (n.kind === "source") return 12; const max = n.kind === "speaker" ? maxWeight.speaker : maxWeight.entity; const t = max > 0 ? Math.sqrt(Math.max(0, n.weight) / max) : 0; return n.kind === "speaker" ? 9 + 13 * t : 6 + 9 * t; @@ -274,6 +280,8 @@ export type ApiNode = { seconds?: number; ids?: number[]; depth?: number; + kind?: string; + recordings?: number; [key: string]: unknown; }; export type ApiEdge = { @@ -290,7 +298,12 @@ export type ApiEdge = { export function fromApiNode(n: ApiNode): GraphNode { const label = n.labels[0]?.toLowerCase(); const kind: NodeKind = - label === "speaker" || label === "recording" || label === "collection" || label === "namespace" || label === "topic" + label === "speaker" || + label === "recording" || + label === "collection" || + label === "namespace" || + label === "topic" || + label === "source" ? label : "entity"; const num = Number(n.id.replace(/^[a-z]/, "")); @@ -298,9 +311,16 @@ export function fromApiNode(n: ApiNode): GraphNode { id: n.id, kind, label: String(n.name ?? n.id), - type: kind === "entity" ? n.type : undefined, + type: kind === "entity" ? n.type : kind === "source" ? n.kind : undefined, ns: n.namespaces ?? (n.namespace ? [n.namespace] : []), - weight: kind === "entity" ? (n.mentions ?? 1) : kind === "speaker" ? (n.seconds ?? 0) / 60 : 1, + weight: + kind === "entity" + ? (n.mentions ?? 1) + : kind === "speaker" + ? (n.seconds ?? 0) / 60 + : kind === "source" + ? (n.recordings ?? 1) + : 1, refs: n.ids ?? (Number.isFinite(num) ? [num] : []), x: 0, y: 0, diff --git a/nextjs-frontend/components/graph/shape.tsx b/nextjs-frontend/components/graph/shape.tsx index 8b02d1a69..970496d45 100644 --- a/nextjs-frontend/components/graph/shape.tsx +++ b/nextjs-frontend/components/graph/shape.tsx @@ -8,6 +8,7 @@ export function nodeFill(n: Pick): string { if (n.kind === "collection") return "var(--aladdin-gold)"; if (n.kind === "namespace") return "var(--text-strong)"; if (n.kind === "topic") return "var(--aladdin-green)"; + if (n.kind === "source") return "var(--aladdin-blue)"; switch (n.type) { case "ORG": case "PERSON": @@ -99,6 +100,15 @@ export function ShapePath({ {...common} /> ); + case "cloud": + // a source: where things come in from + return ( + + ); } } diff --git a/nextjs-frontend/components/timeline/timeline-page.tsx b/nextjs-frontend/components/timeline/timeline-page.tsx index 7a84aa52a..d22c0285d 100644 --- a/nextjs-frontend/components/timeline/timeline-page.tsx +++ b/nextjs-frontend/components/timeline/timeline-page.tsx @@ -1,6 +1,7 @@ "use client"; -import { ArrowUp, CheckCheck, History, ListFilter } from "lucide-react"; +import { ArrowUp, CheckCheck, History, ListFilter, Waypoints } from "lucide-react"; +import Link from "next/link"; import { usePathname, useRouter, useSearchParams } from "next/navigation"; import { useCallback, useEffect, useMemo, useRef, useState } from "react"; @@ -252,15 +253,22 @@ export function TimelinePage() { title="Timeline" meta="What came in from every source, newest first" actions={ - +
+ + +
} />
diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 2191f6efb..d826135ad 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -19265,10 +19265,10 @@ "required": true, "schema": { "type": "string", - "description": "a node id: n, c, r, s, e or e:", + "description": "a node id: n, c, r, s, e or e:, t, or a: for a source", "title": "Node" }, - "description": "a node id: n, c, r, s, e or e:" + "description": "a node id: n, c, r, s, e or e:, t, or a: for a source" }, { "name": "relation",