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
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,9 +193,9 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
to group under a broader one, making the changes they're sure of and proposing the rest, each one undoable. Anything that reaches outside Lens or changes
more than what set it off asks first, until you let it run on its own: on the Approvals page or, for a change inside
Lens, with a yes in the chat it told you in; agents can decline an approval but never give one. Each automation has
limits and budgets, and agents make, try and run them over MCP and in the assistant, or draft one from a sentence. An
automation's workflow is drawn and tried on the workflow canvas, with its actions in the palette, and the studio
lists your automations, builds one in When, If and Then (tested on a recent activity before you save it), and shows
limits and budgets, and agents make, try and run them over MCP and in the assistant, draft one from a sentence, or
start from one of five starters that stay off until you turn them on. An automation's workflow is drawn and tried
on the workflow canvas, with its actions in the palette, and the studio lists your automations, builds one in When, If and Then (tested on a recent activity before you save it), and shows
its runs, what's coming up, its variables and its costs.
([Processing](docs/processing.md#workflows-and-the-canvas),
[converting assets](docs/processing.md#converting-assets), [notifications](docs/notifications.md),
Expand Down
1 change: 1 addition & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,7 @@ GET /api/v1/automations
POST /api/v1/automations
GET /api/v1/automations/actions
POST /api/v1/automations/draft
GET /api/v1/automations/starters
GET /api/v1/automations/{id}
PATCH /api/v1/automations/{id}
DELETE /api/v1/automations/{id}
Expand Down
19 changes: 19 additions & 0 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ merged is called built.
| Describing an automation in words: a draft from a sentence (`POST /api/v1/automations/draft`) | built |
| The studio: the list at `/automations` and the When, If and Then builder, with a test panel ([The studio](#the-studio)) | built |
| An automation's page: its runs, what's coming up, its variables and its costs, in tabs ([An automation's page](#an-automations-page)) | built |
| Starters: five ready-made drafts, switched off, to open, change and save (`GET /api/v1/automations/starters`, [Starters](#starters)) | built |

## The studio

Expand Down Expand Up @@ -1198,6 +1199,21 @@ Nothing is saved: try the draft (`POST /automations/test`), change it, then save
ledger](activity.md) for you and its namespaces, and isn't made once a budget they count for, or everything's, is
used up.

### Starters

Built (`app/domain/automation_starters.py`). `GET /api/v1/automations/starters` lists ready-made drafts, each
`{id, name, description, draft}`, with `draft` what `POST /automations` takes, switched off. Nothing is stored: a
starter is saved only when someone saves it, and runs only once it is turned on. The description says what to change
first, such as the school's address.

| Starter | What it does |
| --- | --- |
| Tell me about school emails | An email from an address with “school” in it tells you in your chat app; posting it to the `family` Matterbridge room asks you first |
| Router alerts | An alert in a sensor's log whose name has “router” in it tells you, at most once an hour |
| Morning digest | Every weekday at 07:00 (UTC until you change it) the agent sums up yesterday's timeline items you haven't reviewed, then tells you |
| No reply in two days | An email whose start asks something, with no email in your Sent mailbox within two days, reminds you; any email you send in that time calls it off |
| Webhook to note | A call to its webhook writes a note with what was sent |

### Agents

Built. Over [MCP](mcp.md) an agent uses `automations` (list them, read one with its latest runs, or one run),
Expand Down Expand Up @@ -1353,6 +1369,9 @@ held run until you pick.
- Deleted automations kept for a time, then removed with their runs (today they stay until restored).
- The studio: dragging actions and rows to reorder them (today the arrows move an action); sharing an automation as a
file; a builder laid out for phones first.
- Starters: "No reply in two days" matching the reply to the same conversation (emails carry no thread yet, so any
email you send calls it off); a starter picking its sensor, room or address from what is connected, instead of a
word to change.
- Credentials in the headers of a saved event workflow an automation follows (`workflow`) sealed too (today only a
graph saved with the automation is; the workflow's are sent as written).
- Webhook triggers: a trigger option for a hook that takes only signed calls (`token_for(..., signed=True)`), and a
Expand Down
2 changes: 2 additions & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,8 @@ request, to another check that proves the same thing; loosening a requirement or
| 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` |
| Starter automations come switched off, each one saving as it is, and changing nothing until someone turns it on | [test_automation_starters.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_starters.py) `test_every_starter_saves_as_it_is_and_stays_off`, `test_the_school_starter_tells_me_at_once_and_asks_before_posting_to_the_family` |
| From an email to a yes: an automation tells you at once, asks before posting to the family, carries the post out on approval, and its run shows on the timeline | [test_automation_journey.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_journey.py) `test_an_email_runs_an_automation_that_tells_me_asks_before_posting_and_shows_on_the_timeline` |
| An automation's workflow is drawn and tried on the canvas: its actions in the palette, their settings drawn from each action's params, Decide's ports and the leaf rule | [workflow-canvas.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-canvas.test.ts) `give a decide node a port per option, then unsure`, `keep the leaf rule: nothing after an action that reaches outside Lens or waits`, `say what the backend would reject in their settings`; [automation-nodes-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automation-nodes-ui.test.tsx) `sets an action up from the catalog, its params drawn from its schema`; [schema-form.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/schema-form.test.tsx) `opens the variable picker on {{ and puts the pick in with Enter` |
| In the web app, automations are listed with what sets each off in words, and built in When, If and Then with a test on a recent activity, problems next to their fields | [automations-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automations-ui.test.tsx) `the list reads each automation, and Delete is undone from its toast`, `the builder adds a trigger with a condition and an action, then saves it switched off`, `the test panel runs the draft on a recent activity and says what it would do`, `API problems go next to what they are about`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_lists_read_the_triggers_in_words_and_say_when_it_runs_next` |
| An automation's page shows its runs a page at a time with each one's log, what's coming up, its variables to edit and its costs | [automation-detail.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automation-detail.test.tsx) `Runs pages back with before, and a run opens to what it did and its log`, `a run held over a budget can run once or be skipped`, `Coming up lists its times, and says why when there are none`, `Variables set from the keyboard, and Clear is undone from its toast` |
Expand Down
2 changes: 2 additions & 0 deletions fastapi_backend/app/api/v1/router.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
admin,
auth,
automation_hooks,
automation_starters,
automation_vars,
automations,
backups,
Expand Down Expand Up @@ -100,6 +101,7 @@
activity,
activities,
automation_hooks,
automation_starters,
automation_vars, # before namespaces: /namespaces/{name}/automation-vars
automations,
budgets,
Expand Down
20 changes: 20 additions & 0 deletions fastapi_backend/app/api/v1/routes/automation_starters.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
"""Starter automations (docs/automations.md, Starters): ready-made drafts, switched off, that the studio opens in its
builder and agents read before saving their own. Nothing is stored until someone saves one. Automation ids use the
int convertor, so this static path never collides with /automations/{id}."""

from __future__ import annotations

from fastapi import APIRouter

from app.api.deps import CurrentUser
from app.domain import automation_starters
from app.schemas.automation_starters import AutomationStarter, AutomationStarters

router = APIRouter(prefix="/automations", tags=["automations"])


@router.get("/starters")
def list_starters(user: CurrentUser) -> AutomationStarters:
"""Starter automations: each a draft to open, change and save (POST /automations), switched off until you turn
it on."""
return AutomationStarters(starters=[AutomationStarter(**s) for s in automation_starters.starters()])
139 changes: 139 additions & 0 deletions fastapi_backend/app/domain/automation_starters.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
"""Starter automations (docs/automations.md, Starters): ready-made drafts a person opens in the studio, changes and
saves. Nothing is stored or switched on: each is what POST /api/v1/automations takes, with `enabled` false, so picking
one changes nothing that runs until the person saves it and turns it on. Each starter's checks run in the tests, so a
change to the contract that breaks one fails there."""

from __future__ import annotations

import copy
from typing import Any


def _node(nid: str, t: str, **config: Any) -> dict[str, Any]:
return {"id": nid, "type": t, "config": config}


def _edge(a: str, b: str) -> dict[str, str]:
return {"source": a, "target": b}


def _graph(*steps: dict[str, Any], chain: bool = False) -> dict[str, Any]:
"""What happened, then each step: in a row when `chain`, else each straight after it."""
nodes = [_node("in", "input"), *steps]
edges = [_edge(nodes[i].get("id") if chain else "in", s["id"]) for i, s in enumerate(steps)]
return {"nodes": nodes, "edges": edges}


def _notify(nid: str, text: str, to: str = "me") -> dict[str, Any]:
return _node(nid, "action", action="notify", params={"to": to, "text": text})


STARTERS: list[dict[str, Any]] = [
{
"id": "school-emails",
"name": "Tell me about school emails",
"description": "An email from the school's address tells you in your chat app, and posting it to the family "
"room waits for your yes. Change “school” to the school's address.",
"draft": {
"triggers": [
{
"as": "mail",
"on": "event",
"kinds": ["email.received"],
"where": {"all": [{"path": "object.from.0", "op": "contains", "value": "school"}]},
}
],
"graph": _graph(
_notify("tell", "School email: {{ event.object.subject }}"),
_notify("family", "From school: {{ event.object.subject }}", to="gateway:family"),
),
},
},
{
"id": "router-alerts",
"name": "Router alerts",
"description": "An alert in the router's log tells you, at most once an hour. Change “router” to your sensor's name.",
"draft": {
"triggers": [
{
"as": "alert",
"on": "event",
"kinds": ["sensor.alert"],
"where": {"all": [{"path": "actor.name", "op": "contains", "value": "router"}]},
}
],
"limits": {"max_per_hour": 1},
"graph": _graph(_notify("tell", "{{ event.summary }}")),
},
},
{
"id": "morning-digest",
"name": "Morning digest",
"description": "Every weekday at 7:00 the agent sums up yesterday's timeline items you haven't reviewed, and tells you.",
"draft": {
"triggers": [{"as": "morning", "on": "schedule", "cron": "0 7 * * 1-5", "timezone": "UTC"}],
"graph": _graph(
_node(
"digest",
"action",
action="ask_agent",
params={
"instructions": "Read yesterday's timeline items I haven't reviewed and sum them up in a few "
"short lines, the ones that need me first."
},
),
_notify("tell", "Your morning digest:\n{{ steps.digest.answer }}"),
chain=True,
),
},
},
{
"id": "no-reply",
"name": "No reply in two days",
"description": "An email that asks you something, with no email sent from your mailbox within two days, "
"reminds you. Any email you send in that time calls it off.",
"draft": {
"triggers": [
{
"as": "mail",
"on": "event",
"kinds": ["email.received"],
"where": {"all": [{"path": "object.snippet", "op": "contains", "value": "?"}]},
},
{
"as": "sent",
"on": "event",
"kinds": ["email.received"],
"where": {"all": [{"path": "object.mailbox", "op": "contains", "value": "Sent"}]},
},
],
"join": {"mode": "absent", "after": "mail", "missing": "sent", "within": "2d"},
"graph": _graph(_notify("remind", "No reply yet to {{ event.object.from.0 }}: {{ event.object.subject }}")),
},
},
{
"id": "webhook-note",
"name": "Webhook to note",
"description": "A call to its webhook writes a note with what was sent. Its address shows once you save it.",
"draft": {
"triggers": [{"as": "hook", "on": "webhook"}],
"graph": _graph(
_node(
"note",
"action",
action="write_note",
params={"text": "{{ event.object }}", "title": "From the webhook, {{ now_local }}"},
)
),
},
},
]


def starters() -> list[dict[str, Any]]:
"""Every starter, each with its draft named and switched off, as POST /api/v1/automations takes it."""
out = []
for s in STARTERS:
draft = {"name": s["name"], "enabled": False, "join": {"mode": "any"}, **copy.deepcopy(s["draft"])}
out.append({"id": s["id"], "name": s["name"], "description": s["description"], "draft": draft})
return out
20 changes: 20 additions & 0 deletions fastapi_backend/app/schemas/automation_starters.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
"""Starter automations (docs/automations.md, Starters): drafts to open in the studio, change and save."""

from __future__ import annotations

from typing import Any

from pydantic import Field

from app.schemas.common import ResponseModel


class AutomationStarter(ResponseModel):
id: str
name: str
description: str = Field(description="what it does, and what to change before turning it on")
draft: dict[str, Any] = Field(description="what POST /automations takes, switched off")


class AutomationStarters(ResponseModel):
starters: list[AutomationStarter]
Loading
Loading