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: 4 additions & 2 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ merged is called built.
| The timeline API (`GET /api/v1/activities`), the MCP tools `timeline` and `event_kinds`, the assistant's `timeline` | built |
| The shapes of triggers, joins, an If, policy and intents, checked (`app/domain/automation_spec.py`) | built |
| The action registry with risk from each action's effect, and one action, `log_line` (`app/domain/actions.py`) | built |
| Settings → Automations: how often followers look and how long the event log is kept | built |
| Storing and running automations, schedules and timers, joins, the real actions, approvals, variables, the timeline page, the studio | planned |

## Contract
Expand Down Expand Up @@ -98,7 +99,7 @@ A kind belongs to the source named in its `source`, and a source may list more i
audience=None, owner=None, untrusted=None)`, which gives the id (`log-<n>`). Emitting a `key` again changes
nothing and gives the first id, so a retry never doubles an activity. Inside `with events.caused_by({"automation":
4, "run": 51, "depth": 1}):` what is emitted carries that cause. It is read by `(logged_at, id)` and paged by
`published`, and its rows are kept for `events.keep_days` (30).
`published`, and its rows are kept for `events.keep_days` (30; Settings → Automations).

### Following the stream

Expand All @@ -118,7 +119,8 @@ where the next look starts (`event_cursor:<consumer>`, a position per source).
(an activity's id, say), with a `CREATE` of `event_claim:<hash>` only one process wins. `events.unclaimed(db,
consumer, keys)` lists the keys nobody has claimed yet, in one query. Claims go after a day.
- `events.emit` wakes the followers in its process; a follower waits between looks with `g = events.generation()`
before the look and `events.wait(events.poll_seconds(cfg), stop, since=g)` after it (`events.poll_seconds`, 5).
before the look and `events.wait(events.poll_seconds(cfg), stop, since=g)` after it (`events.poll_seconds`, 5;
Settings → Automations).

### Timeline reads

Expand Down
11 changes: 10 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ provider and key, a local model, the AI assistant, search (word search and searc
video, OCR, faces and objects, [NSFW classification](nsfw.md), workers, sign-in, components (and the edition, full or
lean), access and embedding (whether other devices on the network reach Lens, embed frame ancestors, text and transcript
upload limit, allowed hosts, trusted proxies, session length), remote access, email, chat rooms, notifications,
telemetry, the Fedora repository, sensors, file shares, uploads, storage, documents, API keys, and IIIF and metadata. The API
automations, telemetry, the Fedora repository, sensors, file shares, uploads, storage, documents, API keys, and IIIF and metadata. The API
refuses an allowed-host list that leaves out the address you are using.

The sections are in groups: AI and search, Speech and voices, Media and documents, Chat and email, Security and
Expand Down Expand Up @@ -461,6 +461,15 @@ Where namespaces may send notifications ([Notifications](notifications.md)). Set
| `notifications.poll_seconds` | 5 | how often the notifier looks for news, 1–3600 |
| `notifications.max_attempts` | 6 | how many times a message is tried, 1–20 |

## Automations

The stream of activities automations follow ([Automations](automations.md#contract)). Settings → Automations:

| Setting | Default | |
|---|---|---|
| `events.poll_seconds` | 5 | how often followers look for new activities when nothing wakes them, 1–3600 |
| `events.keep_days` | 30 | how long activities with no row of their own (the event log) are kept, 1–3650 days |

## Trusted proxies

IP groups ([Access](access.md#ip-groups)) match the visitor's address. The server takes it from the connection or,
Expand Down
1 change: 1 addition & 0 deletions fastapi_backend/app/domain/ops_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
"ai",
"reports",
"notifications",
"events",
"workers",
"decisions",
"voice",
Expand Down
14 changes: 14 additions & 0 deletions fastapi_backend/app/domain/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@
# repo is a startup setting only (what gets installed isn't chosen in the web app)
"updates": ("check", "check_hours", "auto_install", "email"),
"activity": None,
"events": None,
"backups": None,
"encryption": None,
"fedora": None,
Expand Down Expand Up @@ -476,6 +477,8 @@ def _check(section, key, value, default):
return _updates_setting(key, value)
if section == "activity":
return _activity_setting(key, value)
if section == "events":
return _events_setting(key, value)
if section == "backups":
return _backup_setting(key, value)
if section == "fedora":
Expand Down Expand Up @@ -1014,6 +1017,17 @@ def _activity_setting(key, value):
raise ValueError(f"unknown setting activity.{key}")


def _events_setting(key, value):
"""The stream of activities automations follow (docs/automations.md)."""
limits = {"keep_days": (1, 3650, "a whole number of days"), "poll_seconds": (1, 3600, "a whole number of seconds")}
if key not in limits:
raise ValueError(f"unknown setting events.{key}")
lo, hi, what = limits[key]
if not (isinstance(value, int) and not isinstance(value, bool) and lo <= value <= hi):
raise ValueError(f"events.{key} is {what} from {lo} to {hi}")
return value


def _backup_setting(key, value):
from . import schedule

Expand Down
17 changes: 17 additions & 0 deletions fastapi_backend/tests/api/test_activities.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,3 +114,20 @@ def look(): # the API's follower, or the worker's
look()
look()
assert sorted(handled) == sorted(new)


def test_the_stream_is_set_up_in_the_web_app(app, client, db, cfg):
make_user(db, "root@x.io", "root password 1", admin=True)
h = login(client, "root@x.io", "root password 1")
assert events.section(app.state.settings.current()) == {"keep_days": 30, "poll_seconds": 5}
assert client.put("/api/v1/settings/events", json={"keep_days": 90, "poll_seconds": 2}, headers=h).status_code == 200
cfg = app.state.settings.current()
assert (events.section(cfg)["keep_days"], events.poll_seconds(cfg)) == (90, 2)
assert client.get("/api/v1/settings", headers=h).json()["events"]["values"] == {"keep_days": 90, "poll_seconds": 2}
for bad in ({"keep_days": 0}, {"poll_seconds": 3601}, {"keep_days": "30"}, {"poll_seconds": True}, {"tick": 1}):
assert client.put("/api/v1/settings/events", json=bad, headers=h).status_code == 400, bad
# the admin assistant reads and changes the same section
box = ai_tools.Toolbox(db, cfg, {"id": 1, "email": "root@x.io"}, set(), set(), {}, None, admin=True, act=True)
assert box.t_read_settings("events")[0]["values"] == {"keep_days": 90, "poll_seconds": 2}
assert box.t_change_settings("events", {"keep_days": 7})[0]["status"] == "done"
assert box.t_read_settings("events")[0]["values"]["keep_days"] == 7
9 changes: 8 additions & 1 deletion nextjs-frontend/__tests__/settings-find.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { fireEvent, render, screen, waitFor } from "@testing-library/react";
import "@testing-library/jest-dom";

import { findSettings, hitHref, SETTINGS_GROUPS } from "@/components/settings/find";
import { SECTIONS } from "@/components/settings/model";
import { fieldId, fieldsOf, SECTIONS } from "@/components/settings/model";
import { SettingsShell } from "@/components/settings/settings-shell";
import { TooltipProvider } from "@/components/ui/tooltip";

Expand Down Expand Up @@ -74,6 +74,13 @@ describe("finding a setting", () => {
expect(hits.some((h) => h.section === "transcription" && h.fields.some((f) => f.key === "engine"))).toBe(true);
});

it("finds the stream automations follow in Automations, under System", () => {
const hits = findSettings("activities", true);
const auto = hits.find((h) => h.section === "automations")!;
expect(auto.group).toBe("System");
expect(fieldsOf("automations").map((f) => fieldId(f))).toEqual(["events.poll_seconds", "events.keep_days"]);
});

it("finds only People for people who aren't admins", () => {
expect(findSettings("speak", false).map((h) => h.section)).toEqual(["speakers"]);
expect(findSettings("telegram", false)).toEqual([]);
Expand Down
12 changes: 12 additions & 0 deletions nextjs-frontend/components/settings/bodies.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -469,6 +469,18 @@ export function SectionBody({ ctx }: { ctx: BodyCtx }) {
</p>
</>
);
case "automations":
return (
<>
<div className="grid gap-3 sm:grid-cols-2">
<F ctx={ctx} id="events.poll_seconds" />
<F ctx={ctx} id="events.keep_days" />
</div>
<p className="text-[12.5px] leading-[1.45] text-fg-secondary">
Agents read the same stream with the timeline tool (MCP and the assistant) or GET /api/v1/activities.
</p>
</>
);
case "encryption":
return <EncryptionBody ctx={ctx} />;
case "backups":
Expand Down
12 changes: 11 additions & 1 deletion nextjs-frontend/components/settings/find.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,17 @@ export const SETTINGS_GROUPS: { label: string; sections: SectionId[] }[] = [
{ label: "Files and devices", sections: ["storage", "shares", "smb", "nfs", "fedora", "sensors"] },
{
label: "System",
sections: ["updates", "backups", "components", "workers", "logs", "telemetry", "analytics", "startup"],
sections: [
"updates",
"backups",
"components",
"workers",
"automations",
"logs",
"telemetry",
"analytics",
"startup",
],
},
];

Expand Down
27 changes: 27 additions & 0 deletions nextjs-frontend/components/settings/model.ts
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ export type SectionId =
| "video"
| "nsfw"
| "workers"
| "automations"
| "components"
| "access"
| "remote-access"
Expand Down Expand Up @@ -389,6 +390,13 @@ export const SECTIONS: SectionSpec[] = [
backend: ["iiif"],
description: "How assets are published as IIIF Manifests and Collections.",
},
{
id: "automations",
label: "Automations",
backend: ["events"],
description:
"The stream of activities automations follow (new assets and what else happens in Lens): how often followers look for new ones, and how long activities with no row of their own are kept.",
},
{
id: "startup",
label: "Set at startup",
Expand Down Expand Up @@ -2670,6 +2678,25 @@ export const FIELDS: FieldSpec[] = [
max: 20,
hint: "A failed send waits 30 seconds, then four times longer each time, up to 6 hours",
},
// Automations (the stream of activities)
{
section: "events",
key: "poll_seconds",
label: "Look for new activities every (seconds)",
kind: "int",
min: 1,
max: 3600,
hint: "New assets wake followers on this server at once; this is how often they look anyway",
},
{
section: "events",
key: "keep_days",
label: "Keep logged activities (days)",
kind: "int",
min: 1,
max: 3650,
hint: "Activities with no row of their own, such as an automation’s; new assets and other rows stay as long as they do",
},
// Usage analytics (Google Analytics opt-in)
{
section: "analytics",
Expand Down
2 changes: 2 additions & 0 deletions nextjs-frontend/components/settings/settings-shell.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ import {
RefreshCw,
Network,
ScrollText,
Workflow,
} from "lucide-react";
import Link from "next/link";
import { useRouter, useSearchParams } from "next/navigation";
Expand Down Expand Up @@ -87,6 +88,7 @@ const ICON: Record<AnySectionId, LucideIcon> = {
video: Clapperboard,
nsfw: EyeOff,
workers: Cpu,
automations: Workflow,
components: PackageCheck,
access: ShieldCheck,
"remote-access": Cloud,
Expand Down
Loading