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
50 changes: 40 additions & 10 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ merged is called built.
| New assets by kind: emails received, calendar events, files from storage, uploads, pages saved from the web, imports | built |
| Runs that finished or failed, deletions and calendar events that moved | built |
| Comments, notes written and saved, and changes to the entity graph | built |
| More kinds: sensors, chat, system events | planned |
| Sensors: readings a sensor keeps, alert and notable log patterns, devices that report for the first time ([Sensors](#sensors-as-activities)) | built |
| More kinds: chat, system events | planned |
| The timeline API (`GET /api/v1/activities`), the MCP tools `timeline` and `event_kinds`, the assistant's `timeline` | built |
| Review marks on the timeline (reviewed, important, hidden), their filters and `mark_activities` ([Timeline](timeline.md)) | built |
| The shapes of triggers, joins, an If, policy and intents, checked (`app/domain/automation_spec.py`) | built |
Expand Down Expand Up @@ -102,6 +103,9 @@ and the paths holding outside text are in `GET /api/v1/activities/kinds` (`event
| `note.created` | | `note_pages` | a `Page`: `summary`, `about` (what it's the page of), `place`, `author` (person or assistant) | Assistant wrote the note “St Mary's School” |
| `note.saved` | | `note_versions` | as `note.created`, with `version` (the page as it was before) and `why` | Sam edited the note “School trip plans” |
| `entity.changed` | | `graph` | `op` (created, renamed, merged, split, linked, unlinked, deleted, rolled back, changed), `change` (the graph's own op), `entityType`, `before` (a renamed entity's name), `version`, `count`; tagged with its entities | Sam renamed “St Marys” to “St Mary's School” |
| `sensor.reading` | | `sensor_readings` | `{type: Note, id: lens:sensor_reading/<id>, name: "<stream>: <what it said>", url: /sensors/<id>}`, `stream`, `value`, `text`, `fields` (a JSON reading's numbers), `level` (syslog), `pattern`, `label` (the line's pattern and its label); noisy | Kitchen sensor temperature: 31.2 |
| `sensor.alert` | | `log` | `{type: Note, id: lens:sensor_pattern/<id>}`, `label` (alert or notable), `pattern`, `example` (a line it fits), `count` (lines in all), `lines` (in the batch that raised it), `hour` | 192.168.1.1 logged an alert: wlan<n>: authentication failed for <mac> |
| `sensor.joined` | | `sensors` | `{type: Service, id: lens:sensor/<id>, url: /sensors/<id>}`, `sensor_type` (mqtt, syslog, ...), `device`, `status` | A new MQTT device reported: zigbee2mqtt/kitchen |
| `webhook.received` | | `log` | `{type: Note, hook: the webhook's id, payload: what was sent (JSON, a form's fields or text), content_type, query}`; the actor is the webhook (`Service`, `lens:automation_hook/<id>`, "Webhook for <automation>") | Webhook for Front door was called |

A new asset is one activity, of the most specific kind its row tells, decided by its content type and where it came
Expand Down Expand Up @@ -135,6 +139,25 @@ its text once it has been read (`recording.email`). Emails and events imported b
fields their rows had. Outside text (titles, subjects, addresses, snippets, places, file names, page addresses) is
listed in `lens.untrusted`.

#### Sensors as activities

Built (`app/domain/events_streams.py`). A sensor's actor is the sensor (`Service`, `lens:sensor/<id>`, its name); a
sensor with no namespace makes activities for admins, as its page is. Its names, streams, text and patterns are
outside text.

- `sensor.reading` is a reading the sensor keeps, as its handling stores them: `all`, `changes` (a change, and once
an hour while a value stays the same), none for `summary` or `none`, and none while it is paused or ignored. To
trigger on every change, set the sensor to store changes. It is noisy: the timeline leaves it out unless asked for.
Readings are read one sensor at a time over the index on `(sensor, at)`, and a follower whose hint names sensors
(`{"actors": ["lens:sensor/5"]}`, which an automation's trigger on one sensor gives) reads only theirs, so a busy
sensor nobody listens to is never read.
- `sensor.alert` is a log pattern ([Sensors](sensors.md#log-patterns-and-triage)) labelled alert or notable that new
lines fit, raised by the intake as it writes them: once per pattern per hour (the event log's key is the pattern
and the hour, so two processes raise it once), whether the lines are kept or dropped. A label the decision model
wasn't sure of raises none until a person settles it, and a paused or ignored sensor raises none.
- `sensor.joined` is a device or host that made itself a sensor by reporting for the first time (MQTT, syslog),
read from its `storage_source` row by `created_at`; a sensor added by hand isn't news.

### Sources and the event log

Built. A source (`events.Source`, added with `events.register_source`) reads rows Lens already keeps as activities,
Expand All @@ -148,7 +171,7 @@ so nothing is stored twice:
- `get(db, cfg, activity_id)`: one activity by its id, or null; `now(db)`, `back(db, seconds)`: positions of now and of
`seconds` ago; `key(a)`: the position `page` orders by.

A kind belongs to the source named in its `source`, and a source may list more in `kinds`. Two are built:
A kind belongs to the source named in its `source`, and a source may list more in `kinds`. These are built:

- `recordings` (`app/domain/events_content.py`) reads `recording` by `created_at`, the id breaking ties, as
`asset.added` and its children (Kinds, above). The actor is whoever added it: an automation (its first job was
Expand All @@ -164,6 +187,9 @@ A kind belongs to the source named in its `source`, and a source may list more i
- `comments` reads `comment` by `created_at`; `note_pages` reads `note_page` by `created_at`; `note_versions` reads
`note_version` by `at` (to the millisecond) and keeps one version for each page and window; `graph` reads
`graph_event` by `at`, the event number breaking ties (numbers are given out in order, so the two agree).
- `sensor_readings` (`app/domain/events_streams.py`) reads `sensor_reading` by `at` (microseconds), the id breaking
ties, one sensor at a time, as `sensor.reading`; `sensors` reads the `storage_source` rows discovery made by
`created_at`, as `sensor.joined`.
- `log` reads `event_log`: activities no row of their own records (a deletion, a webhook call), written by
`events.emit(db, kind, *, actor, obj, space, summary, target=None, tag=None, key=None, published=None, spaces=None,
audience=None, owner=None, untrusted=None)`, which gives the id (`log-<n>`). Emitting a `key` again changes
Expand Down Expand Up @@ -195,10 +221,11 @@ where the next look starts (`event_cursor:<consumer>`, a position per source).
### Timeline reads

Built. `events.page(db, cfg, viewer, before=None, flt=None, limit=50)` reads the stream newest first for a viewer
(`events.viewer(account, spaces, admin)`, spaces null for every one): `{"items": [...], "next": ...}`, where `next`
(an opaque cursor, null at the end) goes in `before` for the page after. It merges every source's `page`, applies
who may see what, and when filters thin a page out it reads on, up to five pages from each source.
`events.get(db, cfg, id, viewer)` reads one activity, null when there is none or it isn't the viewer's to see.
(`events.viewer(account, spaces, admin)`, spaces null for every one): `{"items": [...], "next": ...}`, where `next` (an
opaque cursor, null at the end) goes in `before` for the page after. It merges every source's `page` by `published`
(each source's own position breaking ties), applies who may see what, and when filters thin a page out it reads on, up
to five pages from each source. `events.get(db, cfg, id, viewer)` reads one activity, null when there is none or it
isn't the viewer's to see.

- Who sees what: `lens.audience` `owner` is its owner alone; `admins` is admins; `space` is everyone who reads one of
its namespaces (`space` or `lens.spaces`); admins read every namespace, and an activity of no namespace is for
Expand Down Expand Up @@ -287,10 +314,10 @@ phone shortcut, another service. No webhook exists until an automation with such
- What was sent becomes a `webhook.received` activity in the event log, with the payload, its content type and the
query as outside text. Its namespace is the automation's (admins see it while the automation isn't stored).
- Signed calls: a caller that signs the Standard Webhooks way (`webhook-id`, `webhook-timestamp` in seconds,
`webhook-signature: v1,<base64 HMAC-SHA256 of "<id>.<timestamp>.<body>">` keyed with the secret, as Lens signs its
own [notification webhooks](notifications.md#webhooks)) has the signature checked, and the time must be within five minutes.
A hook made with `signed=True` refuses calls that aren't signed. A call naming its message (`webhook-id`, or an
`Idempotency-Key` header) is logged once however often the sender retries it.
`webhook-signature: v1,<base64 HMAC-SHA256 of "<id>.<timestamp>.<body>">` keyed with the secret, as Lens signs its own
[notification webhooks](notifications.md#webhooks)) has the signature checked, and the time must be within five
minutes. A hook made with `signed=True` refuses calls that aren't signed. A call naming its message (`webhook-id`, or
an `Idempotency-Key` header) is logged once however often the sender retries it.
- In Docker the API runs no background work, so the worker's automations see the call on their next look (5
seconds, `events.poll_seconds`).

Expand Down Expand Up @@ -493,3 +520,6 @@ the agent can draft an event as a note.
- Writing calendar events (a new Google consent, so it changes existing installs).
- Webhook trigger: signed answers to the caller (what the run did); a rate limit shared by every API process (today
each counts its own); showing a hook's last call in the studio.
- Sensors: a threshold per reading in the intake (only readings over a value become activities, for sensors that
keep everything); a reading's unit, which sensors don't record yet; an alert as soon as a pattern is labelled, for
the lines already seen that hour.
4 changes: 4 additions & 0 deletions docs/sensors.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,10 @@ the language model when there's no Jev key) to label the busiest unlabelled patt
pattern, never per line. A label it wasn't sure of (below `decisions.act_above`) is kept with `sure: false`, for you to
settle.

Automations see sensors too ([Automations](automations.md#sensors-as-activities)): the readings a sensor keeps as
`sensor.reading`, a pattern labelled alert or notable as `sensor.alert` (once an hour while lines fit it), and a device
that reports for the first time as `sensor.joined`.

## Daily digests

With `digest` on (and a namespace), each full day (UTC) of a sensor becomes a document in its namespace: each stream's
Expand Down
4 changes: 2 additions & 2 deletions fastapi_backend/app/domain/events.py
Original file line number Diff line number Diff line change
Expand Up @@ -1033,8 +1033,8 @@ def fits(a):
def ok(a):
return fits(a) and (keep is None or a["id"] in kept)

def k(s, a):
return (a["published"], s.name, _ikey(s.key(a)[1]))
def k(s, a): # the source's own position breaks ties, so rows a millisecond apart keep its order
return (a["published"], s.name, pos_key(s.key(a)))

def fetch(s):
rows = s.page(db, cfg, at[s.name], who, sflt, limit)[:limit]
Expand Down
Loading
Loading