From f6b503660594d3a47d48ddbb2c14ada65144cc4f Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 16:00:20 +0000 Subject: [PATCH 1/2] feat(timeline): a For you order learned from each person's reactions, comments and marks, each item saying why Latest stays the default; order=for_you on GET /api/v1/activities, the MCP timeline tool and the assistant reorders the 200 newest items by recency times the person's own affinity for each item's actor, kind and entities, with why by id, and the Timeline page gets a Latest / For you toggle with the why line under each placed item. No model call, nothing stored. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Ln25ykE6uBDqx21WBU94SX --- README.md | 3 +- changelog.d/for-you.md | 6 + docs/requirements.md | 1 + docs/timeline.md | 36 ++++- fastapi_backend/app/api/mcp_tools.py | 13 +- .../app/api/v1/routes/activities.py | 26 +++- fastapi_backend/app/domain/ai_tools.py | 17 ++- fastapi_backend/app/domain/for_you.py | 138 ++++++++++++++++++ fastapi_backend/app/schemas/activities.py | 4 + .../tests/api/test_timeline_for_you.py | 89 +++++++++++ .../__tests__/timeline-model.test.ts | 12 +- .../__tests__/timeline-ui.test.tsx | 26 ++++ nextjs-frontend/app/openapi-client/sdk.gen.ts | 3 +- .../app/openapi-client/types.gen.ts | 14 ++ nextjs-frontend/components/timeline/item.tsx | 9 ++ nextjs-frontend/components/timeline/model.ts | 12 +- .../components/timeline/timeline-page.tsx | 34 ++++- nextjs-frontend/openapi.json | 26 +++- 18 files changed, 445 insertions(+), 24 deletions(-) create mode 100644 changelog.d/for-you.md create mode 100644 fastapi_backend/app/domain/for_you.py create mode 100644 fastapi_backend/tests/api/test_timeline_for_you.py diff --git a/README.md b/README.md index 662b6747a..c55ea0f65 100644 --- a/README.md +++ b/README.md @@ -209,7 +209,8 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p the assistant, and people review on the Timeline page (and Latest on Home), marking what they've seen, reacting with an emoji and commenting in threads everyone who sees the item shares (agents too, over MCP), and asking the assistant about any item from the item; a comment that tags @lens gets the agent's answer in the thread, with - every change it proposes waiting for a yes. Automations act + every change it proposes waiting for a yes, and a For you order learned from each person's own reactions, comments + and marks says why each item is where it is. Automations act on that stream, on a schedule, at a time or when their own webhook is called, alone or with their triggers joined (all of them, a number of times, one that doesn't come in time, or a batch): they test conditions (text, patterns, numbers, lists, times, days, whether a value changed and whether something like it happened before in their diff --git a/changelog.d/for-you.md b/changelog.d/for-you.md new file mode 100644 index 000000000..196ef06fb --- /dev/null +++ b/changelog.d/for-you.md @@ -0,0 +1,6 @@ +**For you on the timeline.** Next to Latest, the Timeline page has a **For you** order that puts what you care for +most first, learned cheaply from your own reactions, comments and marks (important lifts, hidden sinks) summed over +each item's source, kind and entities, with a line under each item saying why ("You often react to Work Gmail"). +Nobody else's signals touch your order, no model is called, and Latest stays the default. Agents ask for it with +`order=for_you` on `GET /api/v1/activities`, in the MCP `timeline` tool and in the assistant +([For you](docs/timeline.md#for-you)). diff --git a/docs/requirements.md b/docs/requirements.md index fcb9d7079..063447ce5 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -203,6 +203,7 @@ request, to another check that proves the same thing; loosening a requirement or | 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` | +| A For you order of the timeline, learned from each person's own reactions, comments and marks, each item saying why, with Latest the default; through the API, MCP, the assistant and the page | [test_timeline_for_you.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_timeline_for_you.py) `test_for_you_learns_from_reactions_comments_and_marks_and_says_why`, `test_agents_read_for_you_too`; jest [timeline-model.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/timeline-model.test.ts) `keep the For you order as a view, not a filter`, [timeline-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/timeline-ui.test.tsx) `For you: the toggle goes in the address, each placed line says why, and Latest stays the default` | | 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 75396ca58..48c7cf5c6 100644 --- a/docs/timeline.md +++ b/docs/timeline.md @@ -17,7 +17,7 @@ Status: in progress. The studio's timeline is built in steps; only what is merge | 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 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 | +| A For you order learned from what each person reacts to, comments on, marks important and hides, each item saying why | built | ## What shows @@ -32,6 +32,9 @@ unless you ask for them by kind. - Newest first. **Older** reads the next page. While the tab is visible the page looks for new items every 15 seconds; when there are some, a **3 new** pill at the top brings them in, so the list never jumps under you. +- **Latest** / **For you** above the filters: Latest is the stream as it is; For you puts what you care for most + first, learned from your own reactions, comments and marks, with a line under each item it placed saying why + ([For you](#for-you)). Latest is the default, and the choice lives in the address like a filter (`?order=for_you`). - A run of the same source or person and the same kind, each within 30 minutes of the one before, is one line ("Work Gmail received 37 emails"), so a first mailbox sync reads as one line. A click opens it to its items. - Each line has an icon by kind, the summary (a link to what it is about), who did it, the namespace, the kind and @@ -145,11 +148,12 @@ Marks change nothing else: an activity you hid still triggers automations and st ## Agents -- MCP: `timeline` takes `unreviewed: true` for what you haven't marked reviewed and has your marks in `marks`; - `mark_activities` marks activities by id (`ids`, and `reviewed`, `important` or `hidden`), for the person it acts - for, with a token that has the write scope ([MCP](mcp.md)). -- The assistant: `timeline` takes `unreviewed` and lists each activity's marks; `mark_activities` marks them for the - person. After it has read text from outside Lens (the timeline's own titles count), hiding or marking reviewed +- MCP: `timeline` takes `unreviewed: true` for what you haven't marked reviewed and has your marks in `marks`, and + `order: for_you` for the [For you](#for-you) order with `why` by id; `mark_activities` marks activities by id + (`ids`, and `reviewed`, `important` or `hidden`), for the person it acts for, with a token that has the write + scope ([MCP](mcp.md)). +- The assistant: `timeline` takes `unreviewed` and `order` and lists each activity's marks and, for you, its `why`; + `mark_activities` marks them for the person. After it has read text from outside Lens (the timeline's own titles count), hiding or marking reviewed waits for the person's yes, since that text may have asked for it; marking important or bringing things back acts at once ([Chat](assistant.md)). - MCP, on the feed: `react_to_activity` (`id`, `emoji`, `on`) reacts for the person it acts for, `activity_comments` @@ -158,6 +162,24 @@ Marks change nothing else: an activity you hid still triggers automations and st what people wrote: agents read them as data, never as instructions. A comment an agent writes with `@lens` in it gets the assistant's answer like anyone's, as the person the token acts for. +## For you + +For you is a cheap, explainable order of the timeline, learned from each person's own signals and nothing else: +nobody's reactions or marks change anyone else's order, and no model is called. + +- The signals are your own reactions (+1 each), comments (+2), important marks (+2) and hidden marks (โˆ’3), the most + recent 200 of each. Each is summed over the actor, the kind and the tagged entities of the activity it was on, so + a ๐Ÿ‘ on an email from Work Gmail about St Mary's School counts for Work Gmail, for emails and for the school. +- An item's score is its recency (halving every two days) times 1 + tanh(affinity รท 4), with affinity the sum of + your weights on its actor, kind and entities: a strong affinity doubles its score, a strongly negative one halves + it. An item with no signal in common keeps its recency alone. +- A page takes the 200 newest items from where it starts, orders them by score and shows the best `limit`; **Older** + moves past all 200. With no signals yet, For you is Latest, and the page says so. +- `why` on the page names the strongest signal that placed each item ("You often react to Work Gmail", "About St + Mary's School, which you often react to", "You hid items from Dropbox before"), shown under the item. +- `GET /api/v1/activities?order=for_you` is the same for agents, with `why` by id; the other filters apply as in + Latest. Nothing is stored: the order is made on each read from three small queries and arithmetic. + ## How marks, reactions and comments are kept One `event_mark` row per person and activity, keyed by a hash of the two, with the three flags and when they were @@ -177,6 +199,8 @@ counts are two grouped queries. Nothing of this costs a model call. back to it. - Server-sent updates instead of the page polling for new items. +- For you counts opens too, once the page reports them, and could cache each person's affinity for a minute rather + than summing it on every read; per-source mute (a lasting "hide everything from this") is next. - Saved filter views. - A daily digest of unreviewed items, as an automation starter. - Marks on activities whose rows are gone (an event log entry past `events.keep_days`, a deleted asset) stay until diff --git a/fastapi_backend/app/api/mcp_tools.py b/fastapi_backend/app/api/mcp_tools.py index 9b66b74c5..7a8add012 100644 --- a/fastapi_backend/app/api/mcp_tools.py +++ b/fastapi_backend/app/api/mcp_tools.py @@ -60,6 +60,7 @@ feeds, filetree, florence, + for_you, graph_history, integrations, library, @@ -3637,6 +3638,13 @@ def set_mail_routing(ctx: Context, account: int, rules: list[str], watch: int | max_length=20000, ), Arg("unreviewed", "boolean", "only those you haven't marked reviewed"), + Arg( + "order", + "string", + "latest (newest first) or for_you: the 200 newest, the limit of them the person's own reactions, comments and " + "marks say they care for most first, each with why; next moves past all 200", + enum=for_you.ORDERS, + ), Arg("before", "string", "the next of the page before", max_length=4000), Arg("limit", "integer", "activities at most", default=20, minimum=1, maximum=200), ) @@ -3651,6 +3659,7 @@ def timeline( q: str | None, where: str | None, unreviewed: bool | None, + order: str | None, before: str | None, limit: int, ) -> dict[str, Any]: @@ -3658,7 +3667,9 @@ def timeline( ctx.acl, kinds, [actor] if actor else None, [namespace] if namespace else None, tag, since, until, q, where ) who = activity_routes.viewer(ctx.db, ctx.user, ctx.acl) - return activity_routes.timeline(ctx.db, ctx.cfg, who, flt, before, limit, {"reviewed": False} if unreviewed else None) + return activity_routes.timeline( + ctx.db, ctx.cfg, who, flt, before, limit, {"reviewed": False} if unreviewed else None, order or "latest" + ) @tool( diff --git a/fastapi_backend/app/api/v1/routes/activities.py b/fastapi_backend/app/api/v1/routes/activities.py index 1b42226c8..21eb3c049 100644 --- a/fastapi_backend/app/api/v1/routes/activities.py +++ b/fastapi_backend/app/api/v1/routes/activities.py @@ -6,13 +6,13 @@ from __future__ import annotations import json -from typing import Any +from typing import Any, Literal from fastapi import APIRouter, HTTPException, Query from app.api.deps import Access, Acl, Cfg, CurrentUser, Db, Principal, Writer, domain_errors from app.api.v1.routes.comments import _comments_out -from app.domain import auth, comment_agent, comments, event_marks, event_reactions, events, events_content, store +from app.domain import auth, comment_agent, comments, event_marks, event_reactions, events, events_content, for_you, store from app.schemas.activities import ( ActivityKind, ActivityMark, @@ -91,12 +91,20 @@ def timeline( before: str | None, limit: int, marked: dict[str, bool] | None = None, + order: str = "latest", ) -> dict[str, Any]: """A page of the timeline with the namespaces it names, the viewer's own marks on it, everyone's reactions and how many comments each item has; `marked` ({reviewed, important, hidden}: true or false) keeps the activities - whose marks are so.""" + whose marks are so. `order` for_you reorders the newest items by the viewer's own signals (for_you.py), with + `why` by id.""" + if order not in for_you.ORDERS: + raise HTTPException(422, f"order is {' or '.join(for_you.ORDERS)}") with domain_errors(): - page = events.page(db, cfg, who, before, flt, limit, keep=event_marks.keeper(db, who["account"], marked)) + keep = event_marks.keeper(db, who["account"], marked) + if order == "for_you": + page = for_you.page(db, cfg, who, flt, before, limit, keep) + else: + page = events.page(db, cfg, who, before, flt, limit, keep=keep) names = store.space_names(db) used = {s for a in page["items"] for s in events.spaces_of(a)} ids = [a["id"] for a in page["items"]] @@ -128,14 +136,20 @@ def list_activities( hidden: bool | None = Query(None, description="only those you hid (true) or haven't (false)"), before: str | None = Query(None, max_length=4000, description="the next of the page before"), limit: int = Query(50, ge=1, le=200), + order: Literal["latest", "for_you"] = Query( + "latest", + description="latest: newest first; for_you: the 200 newest from `before` on, the `limit` of them that your own " + "reactions, comments and marks say you care for most first, each with `why`; `next` moves past all 200", + ), ) -> ActivityPage: """What happened in Lens, newest first: new assets and everything else the stream holds, each an Activity Streams 2.0 activity with a Lens kind. Give `next` as `before` for the page after. Noisy kinds (like sensor readings) are left out unless named in `kinds`. Text from outside Lens is listed in each activity's `lens.untrusted`. `marks` - has your own marks on the page's activities; `reviewed`, `important` and `hidden` filter by them.""" + has your own marks on the page's activities; `reviewed`, `important` and `hidden` filter by them. `order=for_you` + puts what you react to, comment on and mark important first, and what you hid last (docs/timeline.md, For you).""" flt = filters(acl, kinds, actor, namespace, tag, since, until, q, where) marked = event_marks.want(reviewed, important, hidden) - return ActivityPage(**timeline(db, cfg, viewer(db, user, acl), flt, before, limit, marked)) + return ActivityPage(**timeline(db, cfg, viewer(db, user, acl), flt, before, limit, marked, order)) @router.get("/kinds", response_model_exclude_unset=True) diff --git a/fastapi_backend/app/domain/ai_tools.py b/fastapi_backend/app/domain/ai_tools.py index edf17dc6a..ac1be0249 100644 --- a/fastapi_backend/app/domain/ai_tools.py +++ b/fastapi_backend/app/domain/ai_tools.py @@ -24,6 +24,7 @@ extensions, entity_map, events, + for_you, find as findmod, graph_ask, graph_model, @@ -129,6 +130,7 @@ "What happened in Lens, newest first (new assets, and every other kind of activity there is): who did it, what " "it is about, when, and a one-line summary. Optionally by kinds (such as asset.added), namespace, entity tag, " "time (since, until: ISO 8601), words in the summary, unreviewed (those the person hasn't marked reviewed); " + "order for_you puts what the person reacts to, comments on and marks important first (each with why); " "give next as before for more.", { "kinds": {"type": "array", "items": _S}, @@ -138,6 +140,7 @@ "until": _S, "q": _S, "unreviewed": {"type": "boolean"}, + "order": {"type": "string", "enum": ["latest", "for_you"]}, "before": _S, "limit": _I, }, @@ -1650,7 +1653,9 @@ def _about_allowed(self, a): """Whether an activity is about the assets of a conversation about some assets (any, in one that isn't).""" return self.allowed is None or events.ref_id((a.get("object") or {}).get("id"), "recording") in self.allowed - def t_timeline(self, kinds=None, namespace=None, tag=None, since=None, until=None, q=None, unreviewed=None, before=None, limit=20): + def t_timeline( + self, kinds=None, namespace=None, tag=None, since=None, until=None, q=None, unreviewed=None, order=None, before=None, limit=20 + ): names = store.space_names(self.db) spaces = self.readable if namespace: @@ -1659,7 +1664,14 @@ def t_timeline(self, kinds=None, namespace=None, tag=None, since=None, until=Non raise ValueError(f"namespace {namespace} isn't in this conversation") flt = {"kinds": kinds or None, "tag": tag, "since": since, "until": until, "q": q, "spaces": sorted(spaces) if namespace else None} keep = event_marks.keeper(self.db, self.account, {"reviewed": False} if unreviewed else None) - page = events.page(self.db, self.cfg, self._viewer(), before, {k: v for k, v in flt.items() if v}, min(int(limit or 20), 50), keep) + flt, limit = {k: v for k, v in flt.items() if v}, min(int(limit or 20), 50) + if order and order not in for_you.ORDERS: + raise ValueError(f"order is {' or '.join(for_you.ORDERS)}") + if order == "for_you": + page = for_you.page(self.db, self.cfg, self._viewer(), flt, before, limit, keep) + else: + page = events.page(self.db, self.cfg, self._viewer(), before, flt, limit, keep) + why = page.get("why") or {} items = [a for a in page["items"] if self._about_allowed(a)] # a conversation about some assets: only what is about them marks = event_marks.of(self.db, self.account, [a["id"] for a in items]) out = [ @@ -1672,6 +1684,7 @@ def t_timeline(self, kinds=None, namespace=None, tag=None, since=None, until=Non "object": a["object"], "namespace": names.get(a.get("space")), **({"marked": [f for f in event_marks.FLAGS if marks[a["id"]][f]]} if a["id"] in marks else {}), + **({"why": why[a["id"]]} if a["id"] in why else {}), } for a in items ] diff --git a/fastapi_backend/app/domain/for_you.py b/fastapi_backend/app/domain/for_you.py new file mode 100644 index 000000000..d5a2ce83b --- /dev/null +++ b/fastapi_backend/app/domain/for_you.py @@ -0,0 +1,138 @@ +"""For you: the timeline in an order learned from each person's own signals (docs/timeline.md, For you). + +Latest is the stream as it is, newest first. For you takes a page's worth of the newest items (up to WINDOW) and +reorders it by a cheap local score, recency times affinity: how much the person has reacted to, commented on and +marked important items from the same actor, of the same kind and about the same entities, less what they hid. Each +item's `why` says which of those put it where it is, so the order is explainable. No model call: three small queries +for the person's signals, one look-up of the activities they were on, and arithmetic. Signals are the person's own +(their reactions, comments and marks), never anyone else's, and nothing is stored: the score is made on each read. +""" + +from __future__ import annotations + +import math + +from . import events + +HALF_LIFE_HOURS = 48.0 # an item's recency halves every two days +WINDOW = 200 # the newest items one page scores (the most events.page gives) +SIGNALS = 200 # the most recent rows of each kind of signal that count +WEIGHTS = {"reaction": 1.0, "comment": 2.0, "important": 2.0, "hidden": -3.0} +SCALE = 4.0 # affinity this strong doubles (or, negative, halves) an item's score +ORDERS = ("latest", "for_you") + + +def signals(db, account): + """[(activity id, weight)]: the person's most recent reactions, comments (on an activity, or on an asset, which is + on its arrival) and important or hidden marks, each weighed.""" + if account is None: + return [] + out = [] + for r in db.rows(f"SELECT activity, at FROM event_reaction WHERE account = $a ORDER BY at DESC LIMIT {SIGNALS}", a=account): + out.append((r["activity"], WEIGHTS["reaction"])) + for r in db.rows( + f"SELECT activity, recording, created_at FROM comment WHERE account = $a AND author IS NONE ORDER BY created_at DESC LIMIT {SIGNALS}", + a=account, + ): + aid = r.get("activity") or (f"create-recording-{r['recording']}" if r.get("recording") is not None else None) + if aid: + out.append((aid, WEIGHTS["comment"])) + for r in db.rows( + "SELECT activity, important, hidden, at FROM event_mark WHERE account = $a AND (important = true OR hidden = true) " + f"ORDER BY at DESC LIMIT {SIGNALS}", + a=account, + ): + if r.get("hidden"): + out.append((r["activity"], WEIGHTS["hidden"])) + elif r.get("important"): + out.append((r["activity"], WEIGHTS["important"])) + return [(a, w) for a, w in out if isinstance(a, str)] + + +def affinity(db, cfg, who): + """{actor: {id: weight}, kind: {name: weight}, entity: {id: (weight, name)}, n}: the person's signals summed + over the actor, kind and tagged entities of the activities they were on; `n` is how many counted.""" + sig = signals(db, who.get("account")) + acts = events.get_many(db, cfg, [a for a, _ in sig], who) if sig else {} + out = {"actor": {}, "kind": {}, "entity": {}, "n": 0} + for aid, w in sig: + a = acts.get(aid) + if not a: + continue + out["n"] += 1 + actor = (a.get("actor") or {}).get("id") + if actor: + out["actor"][actor] = out["actor"].get(actor, 0.0) + w + out["kind"][a["kind"]] = out["kind"].get(a["kind"], 0.0) + w + for t in a.get("tag") or []: + if isinstance(t, dict) and t.get("id"): + out["entity"][t["id"]] = out["entity"].get(t["id"], 0.0) + w + return out + + +def _label(kind): + try: + return events.kind_info(kind)["label"].lower() + except KeyError: + return kind + + +def _why(what, name, w): + if w > 0: + return { + "actor": f"You often react to {name}", + "kind": f"You often react to {name} items", + "entity": f"About {name}, which you often react to", + }[what] + return { + "actor": f"You hid items from {name} before", + "kind": f"You hid {name} items before", + "entity": f"You hid items about {name} before", + }[what] + + +def score(a, aff, now): + """(score, why) for one activity: recency (half-life HALF_LIFE_HOURS) times 1 + tanh(affinity / SCALE), with + affinity the sum of the person's weights on its actor, kind and entities; `why` names the strongest of them, or + is None when none of them has a weight.""" + try: + age = max(0.0, (now - events._parse(a["published"])).total_seconds()) / 3600 + except (KeyError, TypeError, ValueError): + age = 0.0 + recency = 0.5 ** (age / HALF_LIFE_HOURS) + parts = [] + actor = a.get("actor") or {} + w = aff["actor"].get(actor.get("id"), 0.0) + if w: + parts.append((w, "actor", actor.get("name") or actor.get("id"))) + w = aff["kind"].get(a.get("kind"), 0.0) + if w: + parts.append((w, "kind", _label(a["kind"]))) + for t in a.get("tag") or []: + w = aff["entity"].get(t.get("id"), 0.0) if isinstance(t, dict) else 0.0 + if w: + parts.append((w, "entity", t.get("name") or t.get("id"))) + total = sum(p[0] for p in parts) + why = None + if parts: + w, what, name = max(parts, key=lambda p: abs(p[0])) + why = _why(what, name, w) + return recency * (1 + math.tanh(total / SCALE)), why + + +def rank(items, aff, now=None): + """The activities best first by `score`, ties the newest first: [(activity, why)].""" + now = now or events._parse(events.stamp()) + scored = [(score(a, aff, now), a) for a in items] + scored.sort(key=lambda x: (x[0][0], x[1].get("published") or ""), reverse=True) + return [(a, why) for (_, why), a in scored] + + +def page(db, cfg, who, flt, before, limit, keep=None): + """A For you page: the WINDOW newest items from `before` on (or `limit`, when more), reordered by score, the best + `limit` of them, with `why` by id for those a signal placed; `next` moves past the whole window, so Older reads + on from where the window ended.""" + limit = max(1, min(int(limit), WINDOW)) + got = events.page(db, cfg, who, before, flt, max(limit, WINDOW), keep) + ranked = rank(got["items"], affinity(db, cfg, who))[:limit] + return {"items": [a for a, _ in ranked], "next": got["next"], "why": {a["id"]: w for a, w in ranked if w}} diff --git a/fastapi_backend/app/schemas/activities.py b/fastapi_backend/app/schemas/activities.py index 42ede96fa..1d6072c26 100644 --- a/fastapi_backend/app/schemas/activities.py +++ b/fastapi_backend/app/schemas/activities.py @@ -73,6 +73,10 @@ class ActivityPage(ResponseModel): marks: dict[str, ActivityMark] = Field(default_factory=dict, description="your marks on items, by id (those you marked)") reactions: dict[str, list[Reaction]] = Field(default_factory=dict, description="everyone's reactions on items, by id (those with any)") comments: dict[str, int] = Field(default_factory=dict, description="how many comments items have, by id (those with any)") + why: dict[str, str] = Field( + default_factory=dict, + description="with order=for_you: why an item is where it is, by id, for those your own signals placed", + ) class ReactIn(RequestModel): diff --git a/fastapi_backend/tests/api/test_timeline_for_you.py b/fastapi_backend/tests/api/test_timeline_for_you.py new file mode 100644 index 000000000..3599a478c --- /dev/null +++ b/fastapi_backend/tests/api/test_timeline_for_you.py @@ -0,0 +1,89 @@ +"""For you (docs/timeline.md, For you): the timeline reordered by each person's own reactions, comments and marks, +with why each item is where it is; Latest stays the default; agents ask for it over MCP and in the assistant.""" + +from __future__ import annotations + +import json + +from app.domain import ai_tools, for_you, store +from tests.helpers import login, make_user, seed + +URL = "/api/v1/activities" +ASSETS = {"kinds": "asset.added"} + + +def _env(client, db, cfg, folder): + ids = seed(db, cfg, folder) + root = make_user(db, "root@x.io", "root password 1", admin=True) + vi = make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + # the two episodes were brought in by Vi, the call by Lens itself + for rid in ids[:2]: + db.q("UPDATE $r SET created_by = $who", r=store.R("recording", rid), who=vi) + return { + "ids": [f"create-recording-{i}" for i in ids], + "root": root, + "vi": vi, + "hr": login(client, "root@x.io", "root password 1"), + "hv": login(client, "vi@x.io", "viewer password 1"), + } + + +def _ids(page): + return [a["id"] for a in page["items"]] + + +def test_for_you_learns_from_reactions_comments_and_marks_and_says_why(client, db, cfg, folder): + env = _env(client, db, cfg, folder) + pods1, pods2, call = env["ids"] + h = env["hr"] + latest = client.get(URL, params=ASSETS, headers=h).json() + assert _ids(latest) == [call, pods2, pods1] and "why" not in latest or latest.get("why") == {} + # with no signals yet, For you is Latest, with nothing to explain + page = client.get(URL, params={**ASSETS, "order": "for_you"}, headers=h).json() + assert _ids(page) == [call, pods2, pods1] and page["why"] == {} + # a ๐Ÿ‘ on the first episode lifts what Vi brought in: the second episode comes before the newer call + client.post(f"{URL}/{pods1}/react", json={"emoji": "๐Ÿ‘"}, headers=h) + page = client.get(URL, params={**ASSETS, "order": "for_you"}, headers=h).json() + assert _ids(page) == [pods2, pods1, call] + assert page["why"][pods2] == "You often react to vi" and page["why"][pods1] == page["why"][pods2] + assert page["why"][call] == "You often react to import received items" # the kind: the strongest signal it shares + # the same with a comment and an important mark; the order is the person's own: Vi's own view is untouched + assert _ids(client.get(URL, params={**ASSETS, "order": "for_you"}, headers=env["hv"]).json()) == [pods2, pods1] + # hiding the first episode outweighs the ๐Ÿ‘: what Vi brought in goes last, and why says so + client.post(f"{URL}/{pods1}/mark", json={"hidden": True}, headers=h) + page = client.get(URL, params={**ASSETS, "order": "for_you"}, headers=h).json() + assert _ids(page) == [call, pods2, pods1] and page["why"][pods2] == "You hid items from vi before" + # the page's other fields are there as in Latest, and paging moves past the window + assert page["marks"][pods1]["hidden"] is True and page["reactions"][pods1][0]["emoji"] == "๐Ÿ‘" + one = client.get(URL, params={**ASSETS, "order": "for_you", "limit": 1}, headers=h).json() + assert _ids(one) == [call] and one["next"] is None + assert client.get(URL, params={**ASSETS, "order": "newest"}, headers=h).status_code == 422 + # the pieces: signals, affinity and scores + aff = for_you.affinity(db, cfg, {"account": env["root"], "spaces": None, "admin": True}) + assert aff["n"] == 2 and aff["actor"][f"lens:account/{env['vi']}"] == -2.0 and list(aff["kind"].values()) == [-2.0] + s, why = for_you.score( + {"published": "2026-01-01T00:00:00.000Z", "kind": "x", "actor": {}, "tag": []}, + aff, + for_you.events._parse("2026-01-03T00:00:00.000Z"), + ) + assert abs(s - 0.5) < 1e-9 and why is None + + +def test_agents_read_for_you_too(client, db, cfg, folder): + from tests.api.test_mcp import tool + + env = _env(client, db, cfg, folder) + pods1, pods2, call = env["ids"] + h = env["hr"] + client.post(f"{URL}/{pods2}/comments", json={"text": "Keep these coming"}, headers=h) + got = tool(client, h, "timeline", kinds=["asset.added"], order="for_you") + assert [a["id"] for a in got["items"]] == [pods2, pods1, call] and got["why"][pods1] == "You often react to vi" + # the assistant's tool says why on each item it placed + spaces = {store.ns_id(db, "pods"), store.ns_id(db, "calls")} + box = ai_tools.Toolbox(db, cfg, {"id": env["root"], "email": "root@x.io"}, spaces, set(), {}, None, admin=True) + out, said = box.call("timeline", {"kinds": ["asset.added"], "order": "for_you"}) + acts = json.loads(out)["activities"] + assert [a["id"] for a in acts] == [pods2, pods1, call] + assert acts[0]["why"] == "You often react to vi" and acts[2]["why"] == "You often react to import received items" + assert said.startswith("Read 3") + assert "order is latest or for_you" in box.call("timeline", {"order": "best"})[0] diff --git a/nextjs-frontend/__tests__/timeline-model.test.ts b/nextjs-frontend/__tests__/timeline-model.test.ts index b9c231128..fe468f8cf 100644 --- a/nextjs-frontend/__tests__/timeline-model.test.ts +++ b/nextjs-frontend/__tests__/timeline-model.test.ts @@ -56,15 +56,25 @@ describe("filters in the address", () => { q: "school trip", unreviewed: true, important: true, + order: "for_you" as const, }; const p = toParams(f); expect(p.toString()).toBe( - "kinds=email.received%2Cfile.added&actor=lens%3Asource%2F12&ns=family&tag=St+Mary%27s+School&from=2026-10-01&to=2026-10-15&automation=4&q=school+trip&unreviewed=1&important=1", + "kinds=email.received%2Cfile.added&actor=lens%3Asource%2F12&ns=family&tag=St+Mary%27s+School&from=2026-10-01&to=2026-10-15&automation=4&q=school+trip&unreviewed=1&important=1&order=for_you", ); expect(fromParams(p)).toEqual(f); expect(filterCount(f)).toBe(10); }); + it("keep the For you order as a view, not a filter", () => { + const f = { ...NO_FILTERS, order: "for_you" as const }; + expect(toParams(f).toString()).toBe("order=for_you"); + expect(isFiltered(f)).toBe(false); + expect(filterCount(f)).toBe(0); + expect(toQuery(f)).toEqual({ hidden: false, order: "for_you" }); + expect(fromParams(new URLSearchParams("order=best")).order).toBe("latest"); + }); + it("leave out what isn't set, and drop what is malformed", () => { expect(toParams(NO_FILTERS).toString()).toBe(""); expect(isFiltered(NO_FILTERS)).toBe(false); diff --git a/nextjs-frontend/__tests__/timeline-ui.test.tsx b/nextjs-frontend/__tests__/timeline-ui.test.tsx index bb72934ed..f7ea6d133 100644 --- a/nextjs-frontend/__tests__/timeline-ui.test.tsx +++ b/nextjs-frontend/__tests__/timeline-ui.test.tsx @@ -355,6 +355,32 @@ test("filters in the address make the query, and an empty address brings back th expect(replace).not.toHaveBeenCalled(); }); +test("For you: the toggle goes in the address, each placed line says why, and Latest stays the default", async () => { + const first = wrap(); + await screen.findByRole("list", { name: "Timeline" }); + expect(m(Activities.listActivities).mock.calls[0][0].query.order).toBeUndefined(); + expect(screen.queryAllByTestId("why")).toHaveLength(0); + await act(async () => fireEvent.click(screen.getByRole("radio", { name: "For you" }))); + expect(replace).toHaveBeenLastCalledWith("/timeline?order=for_you"); + first.unmount(); + // in that order the page comes ranked, with why on what the person's signals placed + search = "order=for_you"; + m(Activities.listActivities).mockImplementation(({ query }) => + ok( + query.since + ? { items: [], next: null, namespaces: {}, marks: {} } + : { ...PAGE, items: [ITEMS[3], ...ITEMS.slice(0, 3)], why: { u1: "You often react to Adeel" } }, + ), + ); + wrap(); + const list = await screen.findByRole("list", { name: "Timeline" }); + expect(m(Activities.listActivities).mock.calls.at(-1)?.[0].query.order).toBe("for_you"); + const rows = within(list).getAllByTestId("timeline-row"); + expect(rows[0]).toHaveTextContent("You often react to Adeel"); + expect(within(rows[1]).queryByTestId("why")).not.toBeInTheDocument(); + expect(screen.getByRole("radio", { name: "For you" })).toHaveAttribute("aria-checked", "true"); +}); + test("Home's Latest card lists what you haven't reviewed", async () => { m(Activities.listActivities).mockReturnValue( ok({ items: ITEMS.slice(0, 2), next: null, namespaces: { "3": "family" } }), diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 2aa0665f2..96486be04 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -4290,7 +4290,8 @@ export class Activities { * What happened in Lens, newest first: new assets and everything else the stream holds, each an Activity Streams * 2.0 activity with a Lens kind. Give `next` as `before` for the page after. Noisy kinds (like sensor readings) are * left out unless named in `kinds`. Text from outside Lens is listed in each activity's `lens.untrusted`. `marks` - * has your own marks on the page's activities; `reviewed`, `important` and `hidden` filter by them. + * has your own marks on the page's activities; `reviewed`, `important` and `hidden` filter by them. `order=for_you` + * puts what you react to, comment on and mark important first, and what you hid last (docs/timeline.md, For you). */ public static listActivities( options?: Options, diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index fd35b9630..5ee90e82a 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -522,6 +522,14 @@ export type ActivityPage = { comments?: { [key: string]: number; }; + /** + * Why + * + * with order=for_you: why an item is where it is, by id, for those your own signals placed + */ + why?: { + [key: string]: string; + }; [key: string]: unknown; }; @@ -32977,6 +32985,12 @@ export type ListActivitiesData = { * Limit */ limit?: number; + /** + * Order + * + * latest: newest first; for_you: the 200 newest from `before` on, the `limit` of them that your own reactions, comments and marks say you care for most first, each with `why`; `next` moves past all 200 + */ + order?: "latest" | "for_you"; }; url: "/api/v1/activities"; }; diff --git a/nextjs-frontend/components/timeline/item.tsx b/nextjs-frontend/components/timeline/item.tsx index 9cd462c11..118d07e5d 100644 --- a/nextjs-frontend/components/timeline/item.tsx +++ b/nextjs-frontend/components/timeline/item.tsx @@ -200,6 +200,8 @@ type RowProps = { social?: (a: Activity) => ReactNode; /** Plain rows with no toggles (Home's card). */ compact?: boolean; + /** With the For you order: why an item is where it is (the page's `why`), shown under the line. */ + whyOf?: (id: string) => string | undefined; }; /** The mark a group shows: reviewed or important once every item is. */ @@ -231,6 +233,7 @@ export const TimelineRow = forwardRef(function Timeline commentsOf, social, compact, + whyOf, }, ref, ) { @@ -244,6 +247,7 @@ export const TimelineRow = forwardRef(function Timeline const summary = groupSummary(group, labels[first.kind]); const reactions = reactionsOf ? sumReactions(group.items.map((a) => reactionsOf(a.id))) : []; const comments = commentsOf ? group.items.reduce((n, a) => n + commentsOf(a.id), 0) : 0; + const why = whyOf?.(first.id); const onKey = (e: KeyboardEvent) => { if (e.target !== e.currentTarget) return; if (e.key === "Enter" || e.key === "o") { @@ -318,6 +322,11 @@ export const TimelineRow = forwardRef(function Timeline )} + {why && ( + + {why} + + )} {!compact && onMark(ids, flags)} />} diff --git a/nextjs-frontend/components/timeline/model.ts b/nextjs-frontend/components/timeline/model.ts index 1e66d8d28..aa0726e34 100644 --- a/nextjs-frontend/components/timeline/model.ts +++ b/nextjs-frontend/components/timeline/model.ts @@ -24,8 +24,12 @@ export type Filters = { q: string; unreviewed: boolean; important: boolean; + /** Latest (newest first) or For you: the newest reordered by what you react to, comment on and mark. */ + order: Order; }; +export type Order = "latest" | "for_you"; + export const NO_FILTERS: Filters = { kinds: [], actor: [], @@ -37,6 +41,7 @@ export const NO_FILTERS: Filters = { q: "", unreviewed: false, important: false, + order: "latest", }; const DATE = /^\d{4}-\d{2}-\d{2}$/; @@ -61,6 +66,7 @@ export function fromParams(p: URLSearchParams): Filters { q: (p.get("q") ?? "").trim(), unreviewed: p.get("unreviewed") === "1", important: p.get("important") === "1", + order: p.get("order") === "for_you" ? "for_you" : "latest", }; } @@ -77,11 +83,13 @@ export function toParams(f: Filters): URLSearchParams { if (f.q) p.set("q", f.q); if (f.unreviewed) p.set("unreviewed", "1"); if (f.important) p.set("important", "1"); + if (f.order === "for_you") p.set("order", "for_you"); return p; } +/** Whether any filter is set; the order is a view, not a filter. */ export function isFiltered(f: Filters): boolean { - return toParams(f).toString() !== ""; + return toParams({ ...f, order: "latest" }).toString() !== ""; } /** How many filters are set, for the phone's Filters button. */ @@ -113,6 +121,7 @@ export type ListQuery = { reviewed?: boolean; important?: boolean; hidden: boolean; + order?: Order; }; /** The automation filter as a match tree: what the automation did (its actor) or what one of its runs caused. */ @@ -138,6 +147,7 @@ export function toQuery(f: Filters): ListQuery { if (f.automation) q.where = automationWhere(f.automation); if (f.unreviewed) q.reviewed = false; if (f.important) q.important = true; + if (f.order === "for_you") q.order = "for_you"; return q; } diff --git a/nextjs-frontend/components/timeline/timeline-page.tsx b/nextjs-frontend/components/timeline/timeline-page.tsx index d22c0285d..b5fd0ae58 100644 --- a/nextjs-frontend/components/timeline/timeline-page.tsx +++ b/nextjs-frontend/components/timeline/timeline-page.tsx @@ -1,6 +1,6 @@ "use client"; -import { ArrowUp, CheckCheck, History, ListFilter, Waypoints } from "lucide-react"; +import { ArrowUp, CheckCheck, History, ListFilter, Sparkles, Waypoints } from "lucide-react"; import Link from "next/link"; import { usePathname, useRouter, useSearchParams } from "next/navigation"; import { useCallback, useEffect, useMemo, useRef, useState } from "react"; @@ -31,6 +31,7 @@ import { Social } from "@/components/timeline/social"; import { useCommentCounts, useReactions } from "@/components/timeline/use-social"; import { useKinds, useMarks, useNewItems, useTimeline } from "@/components/timeline/use-timeline"; import { Button } from "@/components/ui/button"; +import { Segmented } from "@/components/ui/tabs"; import { Drawer } from "@/components/ui/dialog"; import { SearchInput } from "@/components/ui/field"; import { EmptyState, PageHeader, SkeletonRows } from "@/components/ui/states"; @@ -115,14 +116,16 @@ export function TimelinePage() { reactions: Record; comments: Record; ns: Record; + why: Record; }>({ items: [], marks: {}, reactions: {}, comments: {}, ns: {}, + why: {}, }); - useEffect(() => setExtra({ items: [], marks: {}, reactions: {}, comments: {}, ns: {} }), [qs]); + useEffect(() => setExtra({ items: [], marks: {}, reactions: {}, comments: {}, ns: {}, why: {} }), [qs]); const loaded = useMemo(() => (pages ?? []).flatMap((p) => p.items), [pages]); const all = useMemo(() => mergeNew(loaded, extra.items), [loaded, extra.items]); @@ -143,6 +146,12 @@ export function TimelinePage() { () => Object.assign({}, ...(pages ?? []).map((p) => p.comments ?? {}), extra.comments) as Record, [pages, extra.comments], ); + const forYou = filters.order === "for_you"; + const why = useMemo( + () => Object.assign({}, ...(pages ?? []).map((p) => p.why ?? {}), extra.why) as Record, + [pages, extra.why], + ); + const whyOf = useCallback((id: string) => (forYou ? why[id] : undefined), [forYou, why]); const marks = useMarks(serverMarks); const reactions = useReactions(serverReactions); const counts = useCommentCounts(serverComments); @@ -161,6 +170,7 @@ export function TimelinePage() { reactions: { ...x.reactions, ...(d?.reactions ?? {}) }, comments: { ...x.comments, ...(d?.comments ?? {}) }, ns: { ...x.ns, ...(d?.namespaces ?? {}) }, + why: { ...x.why, ...(d?.why ?? {}) }, })); window.scrollTo?.({ top: 0, behavior: "smooth" }); }; @@ -251,7 +261,7 @@ export function TimelinePage() {