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
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
only in the automation's namespaces and only as its person may see them. `changed` in a trigger's where or an If
compares each activity with the last one, and trying an automation keeps nothing
([Looking back](docs/automations.md#looking-back)).
- **Automations wait for their triggers together.** An automation's join runs it when all of its triggers came within
a time (for the same sender, say), when one came a number of times, when one didn't come in time after another (no
reply within two days), or once for a batch collected over a time. What it waits on outlasts a restart, and switching
the automation off drops it ([Joins](docs/automations.md#joins)).
- **Specs from transcripts.** Turn a voice session or a meeting into a technical spec, saved as a note linked to it:
the model writes the spec, then lists every named decision, every "no" and "not that, this", every constraint and
every gap the speaker left to decide later, each with its quote and a link to the moment it was said; a quote the
Expand Down
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,8 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
calendar events, files, feed posts, what people say to Lens, sensor readings, notes, graph changes, runs, budget
warnings) is kept as a stream of activities in W3C Activity Streams form, which agents read through the API, MCP and
the assistant, and people review on the Timeline page (and Latest on Home), marking what they've seen. Automations act
on that stream, on a schedule, at a time or when their own webhook is called: they test conditions (text, patterns,
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
namespaces), then tell you in
your own chat app, ask the model or the agent, use a tool, call a web address (its credentials kept sealed), run a
Expand Down Expand Up @@ -230,7 +231,7 @@ These are open pull requests, not yet part of Lens:

Next, and not in a pull request yet; each links to where it is tracked:

- **The automations studio:** drawing automations in the web app, joins, and the decide node, where a decision model
- **The automations studio:** drawing automations in the web app, and the decide node, where a decision model
picks the branch ([automations](docs/automations.md)).
- **Timeline:** what each item caused, and Approve and Decline on waiting approvals ([timeline](docs/timeline.md)).
- **Notes:** nesting a note under its project or area without a click, pages in the graph, and wiki addresses for
Expand Down
55 changes: 46 additions & 9 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ merged is called built.
| Match trees: one condition language for triggers, an automation's If and workflow nodes | built |
| Operators for times, lists, text patterns and changes (`in`, `matches`, `within`, `changed`...) | built |
| Looking back over the stream in an automation's If (`seen`) | built |
| Joins: `all`, `count`, `absent` and `batch`, completed as the stream brings each trigger's activities and as their timers fire ([Joins](#joins)) | built |
| Activities, the kinds catalog, the event log, following the stream, timeline reads (`app/domain/events.py`) | built |
| New assets as `asset.added` (the `recordings` source) | built |
| New assets by kind: emails received, calendar events, files from storage, uploads, pages saved from the web, imports | built |
Expand Down Expand Up @@ -49,7 +50,7 @@ merged is called built.
| Running automations: following the stream, limits, budgets, runs as `automation.ran`, trying and running now, the API (`app/domain/automations.py`) | built |
| Automations for agents: the MCP tools and the assistant's, switching on and running now by approval | built |
| Describing an automation in words: a draft from a sentence (`POST /api/v1/automations/draft`) | built |
| Joins, the studio | planned |
| The studio | planned |

## Contract

Expand Down Expand Up @@ -415,7 +416,8 @@ tree, `path` (when given) is the part of the value the tree tests. Graphs saved
### Automations: triggers and joins

Built as shapes with checks (`app/domain/automation_spec.py`), saved ([Saving automations](#saving-automations)) and
run ([Running automations](#running-automations)) for triggers on `event` and `manual` and the join `any`. Each check gives a cleaned copy, or a ValueError naming the first problem.
run ([Running automations](#running-automations)), joins included. Each check gives a cleaned copy, or a ValueError
naming the first problem.

```json
{"name": "School emails", "enabled": true, "spaces": [3], "run_as": 1,
Expand All @@ -441,6 +443,35 @@ run ([Running automations](#running-automations)) for triggers on `event` and `m
- `check_policy(p, nodes, allow_auto=False)`: `{action node id: ask or auto}`. Only a person in a signed-in session
lets a node run on its own; everywhere else (agents, drafts, the workflow API) `auto` is refused.

#### Joins

Built (`match.join_step`). Running automations hands each activity a trigger matched (after its guards and its
claim) to `match.join_step(db, cfg, automation, alias, activity)`, which gives a list of completions, each
`{"as": alias, "events": {alias: activity or [activities]}, "event": the last}`, and each completion fires the
automation: its If and graph see every trigger's activity in `events` (`{{ events.mail.object.subject }}`), and
`event` is the last. Triggers a join doesn't name fire on their own, as with `any`. Windows are measured between the
activities' `published` times.

| Mode | Example | Completes |
| --- | --- | --- |
| `any` | `{"mode": "any"}` | at once, for each activity |
| `all` | `{"mode": "all", "within": "1d", "key": "object.from.0"}`: an email from the school and a calendar event from the same sender within a day | when every trigger has an activity within `within` of the others (on the same `key`); each trigger's latest one goes in `events`, then it starts again |
| `count` | `{"mode": "count", "of": "login", "at_least": 3, "within": "5m", "key": "actor.id"}`: three failed logins from one device in five minutes | when `of` has `at_least` activities within `within` (per `key`), with the list of them; then it counts again |
| `absent` | `{"mode": "absent", "after": "mail", "missing": "reply", "within": "2d", "key": "object.thread"}`: no reply within two days | when `within` passes after `after` with no `missing` on the same key published after it, with the first `after` activity; a `missing` one in time cancels it |
| `batch` | `{"mode": "batch", "of": "alert", "within": "1h"}`: the hour's alerts, acted on once | `within` after the first activity, with every one collected (up to 500), by trigger |

- What a join waits on is kept in `automation_state` (kind `join`) with small copies of the activities (long text
cut), written so two processes at once lose nothing (a version on each row). A row expires `within` after its
newest activity, or a day after an `absent` or `batch` timer's time.
- `absent` and `batch` set [timers](#timers) for their automation (`absent-<automation>-<key>`,
`batch-<automation>`), so they outlast a restart and fire once; their handlers, `join.absent` and `join.batch`
(`match.TIMER_HANDLERS`), fire the automation. A `missing` activity in time calls its timer off. A timer that ends
without firing (the automation is switched off, or Lens was off past `automations.catch_up`) drops what it waited
on, so the next activity starts afresh; one that can't be set (the automation has 1000 timers waiting) drops it
too, with a line in the log.
- `match.describe_join(join)` reads a join in words: `all of the triggers within 10 minutes, for the same
object.from`; `3 times login within 5 minutes`; `mail, then no reply within 2 days`.

### Webhook trigger

Built (`app/domain/automation_hooks.py`, `POST /api/v1/automations/hooks/{token}`). A trigger `{"on": "webhook"}`
Expand Down Expand Up @@ -1024,9 +1055,9 @@ person who made it (`run_as`), with their permissions, in namespaces they can ed
value, and saving that again keeps it.
- **Checks** when it is saved: the triggers, the join and the If as in [the contract](#automations-triggers-and-joins),
the graph, the namespaces, `limits` (`cooldown`, like `10m`, default `0s`; `max_per_hour`, 1 to 3600, default 60)
and the policy. Joins other than `any` are refused as coming soon until joins are built. Saving sets the timers of
its `schedule` and `at` triggers ([Schedule, at and relative triggers](#schedule-at-and-relative-triggers)), and
switching it off or deleting it calls them off.
and the policy. Saving sets the timers of its `schedule` and `at` triggers ([Schedule, at and relative
triggers](#schedule-at-and-relative-triggers)), and switching it off or deleting it calls them off, with any its
joins set.
- **Webhook triggers** get their address when the automation is saved ([Webhook trigger](#webhook-trigger)): the
answer's `hooks` gives each new one's `url` and signing `secret`, shown this once, and the trigger keeps the hook's
id. Saving it again keeps its address; a webhook trigger dropped (or changed to another kind) loses it at once.
Expand Down Expand Up @@ -1060,8 +1091,8 @@ is `{draft, dropped, unmapped}`:
- `dropped` says what in the model's draft didn't fit and why: a trigger, its `where`, the If, an action that doesn't
exist or params that don't fit its schema. With no trigger left it runs when you run it; with no action left it has
no Then yet.
- `unmapped` lists what the sentence asked for that it couldn't express, such as "when both arrive" (joins are
planned).
- `unmapped` lists what the sentence asked for that it couldn't express, such as "when both arrive" (a draft
doesn't make joins yet; add one before saving).

Nothing is saved: try the draft (`POST /automations/test`), change it, then save it. The call counts in the [activity
ledger](activity.md) for you and its namespaces, and isn't made once a budget they count for, or everything's, is
Expand Down Expand Up @@ -1099,8 +1130,9 @@ Each new activity is checked against each trigger that listens for its kind (a w

Then it is claimed (for the automation, trigger and activity together), so it runs each automation once, even with the
API and a worker both following. **`automations.fire(db, cfg, automation_id, alias, activity, events=None, dry=False)`**
is the one way every trigger starts a run (the stream with its webhook calls, run now, and later the clock, timers and
joins); it gives the run's id, or none when nothing ran. A run goes:
is the one way every trigger starts a run (the stream with its webhook calls, run now, the clock, timers and joins);
with a join other than `any`, the claimed activity goes to the join first ([Joins](#joins)) and the automation fires
when it completes. It gives the run's id, or none when nothing ran. A run goes:

1. **Its person**: if the person it acts for lost their account, their admin role (for one that works everywhere) or
the right to edit one of its namespaces, the run fails saying so, and the automation is switched off.
Expand Down Expand Up @@ -1143,8 +1175,13 @@ held run until you pick.

## Refine later

- A draft from a sentence that makes joins ("when both arrive", "if no reply within 2 days").
- Switching an automation off and on keeps what an `all` or `count` join was waiting on, until its window passes; a
changed join keeps the old one's rows until they expire.

- Variables inside match values (`{"var": "vars.threshold"}`), once saved variables are built.
- Statistical conditions, such as a reading above its 7-day average.
- Sequences longer than two steps ("A, then B, then C").
- The canvas shows and edits match trees on condition, filter and switch nodes (today it edits one test; a tree
saved through the API is kept).
- A `?format=as2` JSON-LD view and per-actor outboxes for ActivityPub; SurrealDB `DEFINE EVENT` for Update verbs that
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,7 @@ request, to another check that proves the same thing; loosening a requirement or
| What reaches outside Lens, or changes more than what set it off, asks first: on the Approvals page or with a yes in chat; agents decline but never approve | [test_automation_spec.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_spec.py) `test_risk_follows_the_effect`; [test_approvals.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_approvals.py) `test_approve_carries_the_action_out_and_the_run_records_it`, `test_agents_over_mcp_list_and_decline_but_never_approve`; [test_approvals_chat.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_approvals_chat.py) `test_a_yes_in_my_chat_decides_an_action_inside_lens`; [approvals-page.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/approvals-page.test.tsx) `groups what waits, puts the first in focus, and Enter approves it` |
| Conditions test text, patterns, numbers, lists, times, days and whether a value changed, checked as they're saved and read in words | [test_match_ops.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_ops.py) `test_each_test_passes_what_it_should`, `test_checks_refuse_values_a_test_cant_use`, `test_a_pattern_reads_a_long_value_only_so_far_and_gives_up_when_slow`, `test_changed_compares_with_the_last_value_seen`, `test_the_added_tests_read_in_words` |
| Conditions look back over what happened in the automation's namespaces, as its person may see it, and compare each activity with the last one; a dry run keeps nothing | [test_match_seen.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_seen.py) `test_seen_finds_what_happened_in_the_window`, `test_an_if_looks_back_and_reads_the_context`, `test_seen_is_only_for_an_automations_if`; [test_automation_conditions.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_conditions.py) `test_the_if_looks_back_in_the_automations_namespaces`, `test_changed_in_a_where_compares_with_the_last_activity`, `test_the_if_and_a_condition_node_agree_and_dry_runs_keep_nothing` |
| Joins wait for an automation's triggers together: all of them, a number of times, one that doesn't come in time, or a batch, on timers that outlast a restart | [test_match_joins.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_joins.py) `test_all_waits_for_every_trigger_within_the_window_on_the_same_key`, `test_count_fires_once_per_crossing_then_counts_again`, `test_absent_waits_with_a_timer_and_the_missing_one_cancels_it`, `test_batch_collects_then_runs_once`, `test_two_writers_at_once_lose_nothing`; [test_automation_conditions.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_conditions.py) `test_an_absent_join_waits_on_a_timer_and_switching_off_drops_it` |
| Each automation has limits and budgets | [test_automation_runs.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_runs.py) `test_the_if_limits_and_dry_runs`, `test_a_run_over_budget_is_held_for_the_persons_pick` |
| Agents make, try and run automations over MCP and in the assistant, or draft one from a sentence | [test_automation_tools.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_tools.py) `test_agents_save_try_and_run_automations_over_mcp`, `test_the_assistant_saves_at_once_and_asks_to_switch_on_or_run`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_an_automation_is_drafted_from_a_sentence` |

Expand Down
8 changes: 4 additions & 4 deletions fastapi_backend/app/domain/automations.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@
- What its runs left: `last_run_at`, `last_status`, `counters` ({runs, skipped, limited, missed}).
- `removed_at`: deleted (switched off and hidden; restore brings it back).

Parts of the studio built in their own steps are called once they are there (automation_nodes.provided): schedules
and times (timers), webhooks (automation_hooks) and joins other than any (match.join_step). Until then a trigger or
join that needs one is refused as coming soon.
Parts of the studio built in their own steps are called through automation_nodes.provided: schedules and times
(timers), webhooks (automation_hooks) and joins other than any (match.join_step, whose absent and batch modes wait
on timers). A trigger or join whose part isn't there is refused as coming soon.
"""

from __future__ import annotations
Expand Down Expand Up @@ -981,7 +981,7 @@ def _route(db, cfg, a, t, act, who, sec):
if a["join"]["mode"] != "any":
step = provided("match", "join_step")
done = step(db, cfg, a, t["as"], act) if step is not None else []
return sum(1 for c in done if fire(db, cfg, a["id"], t["as"], c.get("event") or act, c.get("events")) is not None)
return sum(1 for c in done if fire(db, cfg, a["id"], c.get("as") or t["as"], c.get("event") or act, c.get("events")) is not None)
return 1 if fire(db, cfg, a["id"], t["as"], act, {t["as"]: act}) is not None else 0


Expand Down
Loading
Loading