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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
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, a For you order learned from each person's own reactions, comments
and marks says why each item is where it is, each person mutes a source or a kind for themselves, with nothing
deleted, and an opened item shows what it caused, the runs and approvals, with Approve and Decline right there.
deleted, and saves the filters they read often as views, and an opened item shows what it caused, the runs and approvals, with Approve and Decline right there.
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,
Expand Down
3 changes: 3 additions & 0 deletions changelog.d/timeline-saved-views.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
The timeline has saved views: a name for a set of filters and an order, picked from a Views menu on the page, saved
from what the page shows with a name guessed from the filters, and listed, saved and deleted by agents over the API
and MCP (`timeline_views`, `save_timeline_view`, `delete_timeline_view`). Each person's views are their own.
1 change: 1 addition & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,7 @@ For an app that speaks OpenAI's API rather than MCP, the namespace can also answ
| `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 |
| `activity_mutes`, `mute_activities` | the person's mutes on the timeline, and mute a source or person (`actor`) or a kind (`kind`), for good or `until` a time, or lift one with `on` false ([Muting](timeline.md#muting)); nothing is deleted. Muting needs a write-scope token |
| `timeline_views`, `save_timeline_view`, `delete_timeline_view` | the person's saved views of the timeline (a name for its filters and order), save one or change one by `id`, and delete one ([Saved views](timeline.md#saved-views)); saving and deleting need 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 |
| `activity_caused` | what an activity caused ([Timeline](timeline.md#what-an-item-caused)): the runs it started of the automations the person manages, with their status, and the approvals those asked the person for, each as `approvals` shows it; on an approval's own activity, that approval |
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,7 @@ request, to another check that proves the same thing; loosening a requirement or
| An asset moved to another namespace is `asset.moved`, a Move seen where it is now, and a sensor a person pauses, ignores, resumes or sets back to new is `sensor.changed`, an Update with the status it had before, seen in its namespace or by admins; a change that changes nothing logs nothing | [test_timeline_verbs.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_timeline_verbs.py) `test_moving_an_asset_is_a_move_seen_where_it_is_now`, `test_switching_a_sensor_is_an_update_with_what_it_was` |
| An opened timeline item shows what it caused, the runs it started of the automations the person manages and the approvals those asked for, with Approve and Decline on waiting ones; `GET /activities/{id}/caused`, `approvals?activity=`, MCP `activity_caused` and the assistant | [test_timeline_caused.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_timeline_caused.py) `test_an_item_lists_what_it_caused_and_the_waiting_approval_is_decided_there`, `test_agents_read_what_an_item_caused_too`; jest [timeline-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/timeline-ui.test.tsx) `an opened item shows what it caused, and a waiting approval is approved there` |
| One timeline item by its id in the address (`/timeline?item=<id>`), opened above the timeline with its actions and a way back, which is where a comment on an item, a reaction and an approval's "because" link | jest [timeline-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/timeline-ui.test.tsx) `the address can name one item, opened above the timeline, with a way back`; [test_timeline_social.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_timeline_social.py) `test_comments_on_a_logged_activity_follow_its_audience` |
| Saved views of the timeline: its filters and order under a name, each person's own, picked from the page's Views menu and through the API and MCP | [test_timeline_views.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_timeline_views.py) `test_timeline_views_are_saved_renamed_changed_and_deleted_by_their_maker_alone`, `test_agents_list_save_and_delete_timeline_views`; jest [timeline-model.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/timeline-model.test.ts) `a saved view keeps the filters and order as they are, and offers a name from them`, [timeline-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/timeline-ui.test.tsx) `Views: one click shows a saved view, and the filters shown now are saved under a guessed name`, `Views: the view the filters match is named on the button, and deleting it can be undone` |
| 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
20 changes: 19 additions & 1 deletion docs/timeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ Status: in progress. The studio's timeline is built in steps; only what is merge
| A For you order learned from what each person reacts to, comments on, marks important and hides, each item saying why | built |
| Muting a source, person or kind, for good or until a time, for yourself alone; `mute_activities` for agents | built |
| Moves and switches as their own verbs: an asset moved to another namespace (`asset.moved`, a Move) and a sensor paused, ignored or resumed (`sensor.changed`, an Update with what it was) | built |
| Saved views: the filters and order under a name, one click away in the page's Views menu, each person's own; `timeline_views`, `save_timeline_view` and `delete_timeline_view` for agents | built |

## What shows

Expand Down Expand Up @@ -215,6 +216,24 @@ page) does not; a For you page scores only what is left.
person a token acts for, with the write scope to mute. The assistant's `mute_activities` acts at once, but after
it has read text from outside Lens it asks first, as hiding does, since that text may have asked for it.

## Saved views

A saved view is a name for a set of filters and an order ("Work mail to review": the work namespace, Email received,
Unreviewed), so a timeline you read often is one click away. Views are each person's own: nobody else sees them.

- **Views** beside the order lists your views; picking one sets the filters and order it saved (and the address, so
it can still be linked). When the filters shown match a view, the button carries its name.
- **Save these filters as a view** offers a name made from the filters ("work · Email received · Unreviewed"); Enter
saves it, Escape leaves it. After picking a view and changing the filters, **Save these filters into “Work mail”**
updates it. **Delete** takes it away, with Undo.
- `GET`, `POST /api/v1/activities/views` and `PATCH`, `DELETE /api/v1/activities/views/{id}` list, save, rename or
re-save, and delete them, up to 100 each. A view's `state` has the timeline's filters: `kinds`, `actor` and
`namespace` (lists), `tag`, `from_day` and `to_day` (days, `YYYY-MM-DD`), `automation`, `q`, `unreviewed`,
`important` and `order` (`latest` or `for_you`). They are saved views of their own kind, beside the Library's views
and saved searches, which they don't show among.
- Over MCP, `timeline_views` lists them, `save_timeline_view` (`name`, `state`, and `id` to change one) saves one and
`delete_timeline_view` deletes one; an agent reads what a view shows by giving its filters to `timeline`.

## For you

For you is a cheap, explainable order of the timeline, learned from each person's own signals and nothing else:
Expand Down Expand Up @@ -259,7 +278,6 @@ per source page; they go when the person is removed. Nothing of this costs a mod
- A muted actor's own line in the Filters, and a snooze of your own length from the page.
- A file changed in its source and read again is `asset.added` once more; linking the new activity to the
asset's earlier one as a `file.changed` Update, rather than a second Create, is to come.
- Saved filter views.
- Marks on activities whose rows are gone (an event log entry past `events.keep_days`, a deleted asset) stay until
the person is removed; a tidy could drop them. Reactions and comments on such activities likewise.
- The agent's reply in a thread is plain text with links; the answer's excerpts could open at their moment, as in
Expand Down
50 changes: 50 additions & 0 deletions fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@
from app.domain import speakers as spk
from app.domain import topics as topicmod
from app.domain.store import DB
from app.schemas.activities import TimelineViewState
from app.schemas.automation_vars import TemplatePreviewIn
from app.schemas.automations import (
AutomationCreate,
Expand Down Expand Up @@ -3863,6 +3864,55 @@ def activity_mutes(ctx: Context) -> dict[str, Any]:
return {"mutes": event_mutes.of(ctx.db, ctx.user.id)}


@tool(
"timeline_views",
"Your saved views of the timeline",
"The person's saved views of the timeline (docs/timeline.md, Saved views): each a name for a set of filters (kinds, "
"actor, namespace, tag, from_day, to_day, automation, q, unreviewed, important) and an order (latest or for_you), "
"the latest changed first. Give a view's filters to timeline to read what it shows. Nobody else sees them.",
)
def timeline_views(ctx: Context) -> dict[str, Any]:
return {"views": [v.model_dump() for v in activity_routes.timeline_views(ctx.db, ctx.user)]}


@tool(
"save_timeline_view",
"Save a view of the timeline",
"Save a set of timeline filters and an order under a name for the person you act for, as a view the Timeline page "
"offers in its Views menu; with id, rename that view or save new filters into it. state has the keys kinds, actor, "
"namespace (lists), tag, from_day and to_day (YYYY-MM-DD), automation (an id), q, unreviewed, important and order "
"(latest or for_you); a key left out is unset. The answer is the view. Needs a token with the write scope.",
Arg("name", "string", "its name, unique among their timeline views", max_length=60),
Arg("state", "object", "the filters and order (JSON)"),
Arg("id", "integer", "a view of theirs to change; left out: a new view"),
writes=True,
)
def save_timeline_view(ctx: Context, name: str | None, state: dict[str, Any] | None, id: int | None) -> dict[str, Any]: # noqa: A002 - the API's name
if not ctx.user.can_write:
raise ToolError("this token is read-only: ask for a token with the write scope to save a view")
if id is None and not name:
raise ToolError("a new view needs a name")
try:
st = TimelineViewState(**(state or {})).model_dump() if state is not None or id is None else None
except ValidationError as e:
raise ToolError(f"state: {e.errors()[0]['loc']} {e.errors()[0]['msg']}") from None
return activity_routes.save_view(ctx.db, ctx.acl, ctx.user, name, st, id).model_dump()


@tool(
"delete_timeline_view",
"Delete a view of the timeline",
"Delete one of the person's saved views of the timeline, by id. Needs a token with the write scope.",
Arg("id", "integer", "the view's id", required=True),
writes=True,
)
def delete_timeline_view(ctx: Context, id: int) -> dict[str, Any]: # noqa: A002 - the API's name
if not ctx.user.can_write:
raise ToolError("this token is read-only: ask for a token with the write scope to delete a view")
activity_routes.remove_view(ctx.db, ctx.acl, ctx.user, id, "timeline")
return {"ok": True}


@tool(
"mute_activities",
"Mute a source or a kind",
Expand Down
54 changes: 54 additions & 0 deletions fastapi_backend/app/api/v1/routes/activities.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@

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.api.v1.routes.views import change as change_view
from app.api.v1.routes.views import remove as remove_view
from app.domain import (
auth,
comment_agent,
Expand All @@ -24,6 +26,7 @@
events_content,
for_you,
store,
views,
)
from app.schemas.activities import (
ActivityKind,
Expand All @@ -39,6 +42,9 @@
ReactIn,
ReactionsOut,
StreamActivity,
TimelineView,
TimelineViewCreate,
TimelineViewUpdate,
)
from app.schemas.comments import ActivityCommentCreate, Comment, CommentUpdate
from app.schemas.common import Ok
Expand Down Expand Up @@ -217,6 +223,54 @@ def mute_activities(body: MuteIn, user: Writer, db: Db) -> MutesOut:
return MutesOut(mutes=[Mute(**m) for m in mutes])


# ---------- saved views: the timeline's filters and order under a name, the person's own (docs/timeline.md) ----------
def timeline_views(db: Any, user: Principal) -> list[TimelineView]:
"""The person's timeline views, the latest changed first."""
return [
TimelineView(**{k: v[k] for k in ("id", "name", "state", "created_at", "updated_at")})
for v in views.visible(db, user.id, set(), "timeline")
]


def save_view(
db: Any, acl: Access, user: Principal, name: str | None, state: dict[str, Any] | None, vid: int | None = None
) -> TimelineView:
"""Create a timeline view (no `vid`), or rename it or save new filters into it; the view as it is now."""
if vid is None:
with domain_errors():
vid = views.create(db, user.id, name, None, state or {}, False, kind="timeline")
else:
change_view(db, acl, user, vid, "timeline", name, None, state)
v = views.get(db, vid, "timeline")
return TimelineView(**{k: v[k] for k in ("id", "name", "state", "created_at", "updated_at")})


@router.get("/views")
def list_timeline_views(user: CurrentUser, db: Db) -> list[TimelineView]:
"""Your saved views of the timeline: each a name for its filters and order, the latest changed first. Nobody else
sees them."""
return timeline_views(db, user)


@router.post("/views")
def create_timeline_view(body: TimelineViewCreate, user: Writer, acl: Acl, db: Db) -> TimelineView:
"""Save the timeline's filters and order under a name, unique among your timeline views (up to 100)."""
return save_view(db, acl, user, body.name, body.state.model_dump())


@router.patch("/views/{vid}")
def update_timeline_view(vid: int, body: TimelineViewUpdate, user: Writer, acl: Acl, db: Db) -> TimelineView:
"""Rename it, or save what the timeline shows now into it. Yours only."""
return save_view(db, acl, user, body.name, body.state.model_dump() if body.state else None, vid)


@router.delete("/views/{vid}")
def delete_timeline_view(vid: int, user: Writer, acl: Acl, db: Db) -> Ok:
"""Delete it. Yours only."""
remove_view(db, acl, user, vid, "timeline")
return Ok()


@router.get("/{activity_id}", response_model_exclude_unset=True)
def get_activity(activity_id: str, user: CurrentUser, acl: Acl, db: Db, cfg: Cfg) -> StreamActivity:
"""One activity by its id, like create-recording-7."""
Expand Down
7 changes: 4 additions & 3 deletions fastapi_backend/app/domain/views.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
"""Saved views: of the Library (its tab, filters and sort) or of a search (its words and filters), under a name, with
the namespace they show (or every one). Kind ``library`` is a Library view, ``search`` a saved search.
"""Saved views: of the Library (its tab, filters and sort), of a search (its words and filters) or of the timeline (its
filters and order), under a name, with the namespace they show (or every one). Kind ``library`` is a Library view,
``search`` a saved search, ``timeline`` a timeline view (always its maker's alone: it names namespaces in its filters).

A view is its maker's. Shared with its namespace, everyone with a role there sees it, and the namespace's owners may
delete it; only its maker changes it.
Expand All @@ -11,7 +12,7 @@

R = store.R
MAX_VIEWS = 100 # per person, of each kind
KINDS = {"library": "view", "search": "saved search"}
KINDS = {"library": "view", "search": "saved search", "timeline": "timeline view"}
FIELDS = "record::id(id) AS id, account, kind ?? 'library' AS kind, name, space, shared ?? false AS shared, state, created_at, updated_at"


Expand Down
Loading
Loading