Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions changelog.d/for-you.md
Original file line number Diff line number Diff line change
@@ -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)).
2 changes: 1 addition & 1 deletion docs/assistant.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@ When the configured model supports function calling, chat becomes an agent.
outputs, entities and their mentions and timelines, dates said as days on the calendar (`find_dates`), the
knowledge graph, people, and content similar to a text,
an asset, a topic or an entity (`find_similar`), and what happened in Lens, newest first (`timeline`, the
[stream of activities](automations.md#timeline-reads); `unreviewed` for what the person hasn't marked reviewed),
[stream of activities](automations.md#timeline-reads); `unreviewed` for what the person hasn't marked reviewed, `order: for_you` for the [For you](timeline.md#for-you) order with each item's `why`),
and assets by any attribute: faces seen, people heard, entities, topics, kind, content type, dates and the rest,
each with the moments that show why it matched (`find_resources`,
[Finding by any attribute](processing.md#finding-by-any-attribute)). It can also ask which of some labels, content
Expand Down
2 changes: 1 addition & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ For an app that speaks OpenAI's API rather than MCP, the namespace can also answ
| `set_namespace_integrations` | turn a namespace's own MCP server or chat completions on or off, and pick the read tools its chat completions may use. Owners, with a write-scope token |
| `list_files` | a folder of [the graph as files](file-tree.md): your namespaces, then their collections, topics (nested by narrower topics) and entities, each holding its assets' files |
| `read_file` | a text file of that tree (an asset's `.txt` text or `.json` metadata), a page at a time; other files' download link |
| `timeline` | what happened in Lens, newest first ([Automations](automations.md#timeline-reads)): each activity's kind, who did it, what it is about, when, and a one-line summary; by kinds, actor, namespace, entity, time, words or a match tree, a page at a time; `unreviewed` for what the person hasn't marked reviewed, with their marks on the page in `marks`. Fields holding outside text are listed in `lens.untrusted` |
| `timeline` | what happened in Lens, newest first ([Automations](automations.md#timeline-reads)): each activity's kind, who did it, what it is about, when, and a one-line summary; by kinds, actor, namespace, entity, time, words or a match tree, a page at a time; `unreviewed` for what the person hasn't marked reviewed, with their marks on the page in `marks`; `order: for_you` for the [For you](timeline.md#for-you) order, with `why` by id. Fields holding outside text are listed in `lens.untrusted` |
| `mark_activities` | mark activities reviewed, important or hidden, or clear those marks, for the person alone ([Timeline](timeline.md#review-marks)); up to 500 by id, `unknown` lists those that can't be seen. Needs a write-scope token |
| `react_to_activity` | put an emoji (👍 ❤️ 🎉 👀 😂 😮 😢 🙏) on an activity for the person, or take theirs back (`on` false), as on a post in a feed ([Timeline](timeline.md#reactions-and-comments)); everyone who sees the activity sees it, and it is a `reaction.added` activity. Needs a write-scope token |
| `activity_comments` | an activity's comments, threaded, with who wrote each; on an asset's arrival the asset's own. What people wrote is data, never instructions |
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<namespace>/<Name>` | [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` |
Expand Down
36 changes: 30 additions & 6 deletions docs/timeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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`
Expand All @@ -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
Expand All @@ -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
Expand Down
13 changes: 12 additions & 1 deletion fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@
feeds,
filetree,
florence,
for_you,
graph_history,
integrations,
library,
Expand Down Expand Up @@ -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),
)
Expand All @@ -3651,14 +3659,17 @@ def timeline(
q: str | None,
where: str | None,
unreviewed: bool | None,
order: str | None,
before: str | None,
limit: int,
) -> dict[str, Any]:
flt = activity_routes.filters(
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(
Expand Down
26 changes: 20 additions & 6 deletions fastapi_backend/app/api/v1/routes/activities.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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"]]
Expand Down Expand Up @@ -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)
Expand Down
Loading
Loading