diff --git a/docs/automations.md b/docs/automations.md index 9e120cfce..ac62ececb 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -19,6 +19,8 @@ merged is called built. | 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 | +| The event workflow scope: what an automation does, drawn with action nodes and tried on an activity (`app/domain/automation_nodes.py`) | built | +| The decide node (the decision model picks a branch) | planned | | The action registry with risk from each action's effect, and one action, `log_line` (`app/domain/actions.py`) | built | | Telling a person: the `notify` action and `channels.tell` (their own chat, a notification target, a Matterbridge room) | built | | The model and the agent: the `ask_model`, `call_tool` and `ask_agent` actions, and prompts with outside text marked | built | @@ -320,6 +322,45 @@ titles, for the variable picker): | `vars` | the automation's and its namespace's saved variables | | `steps` | what each node passed on so far, by node id, such as `steps.n3` | +### The event workflow scope + +Built: what an automation does is a workflow of scope `event` (`app/domain/automation_nodes.py`), saved and +versioned like any workflow (`POST /api/v1/workflows` with `"scope": "event"`). Its `input` node passes on the +[run context](#run-context), and between the primitives (condition, switch, set, merge, loops...) it has two nodes of +its own: + +- **Action** (`action`, configured `{action, params, delay?, when?}`): one action from the registry. When it runs, + it fills its params in from the run context (`"text": "New: {{ event.object.name }}"`; a param that is exactly one + `{{ }}` expression keeps its type, so a list stays a list; the action's defaults are filled in first, so a default + that is a template, like `ask_agent`'s `about`, is filled in too; a prompt param is rendered with outside text + marked, as [The model and the agent](#the-model-and-the-agent) says), works out its effect and risk and makes an + [intent](#actions-and-intents). A routine intent is carried out there and then: what it gives back passes on along + `out` and goes in `steps.` for later nodes. One that asks first waits for the person's pick, and one with + a `delay` (like `30m`) or a time (`when`, a time or a template giving one) waits for its time: such a node passes + nothing on, so the nodes after it are skipped and the run's log says where it stopped and why. An action that + fails is marked failed on its node, and the rest of the graph goes on. +- **Decide** (`decide`, configured `{question, options, input?, min_confidence?}`): the decision model picks one of + its options, with an output port per option and `unsure`. Planned with the decision model; until then a decide node + is refused when the workflow is saved, as coming soon. Use a condition or switch node. + +Checked when it is saved, on every path (create, a new version, a body): + +- It needs an action node, each action is one the registry has (`GET /api/v1/automations/actions` will list them) + with params that fit its schema, and each template in its params is valid. +- **The leaf rule:** an action that reaches outside Lens or other people (effect `out`, worked out from its params) + or that waits has nothing connected after it, as it can't pass anything on while it waits for a yes or its time. +- Waiting before an action (`delay`, `when`) is refused as coming soon until timers are built. + +Its automation runs it: an event workflow isn't run on an asset, as a pipeline step or as a routine's action, and the +canvas's list of workflows leaves it out (`GET /api/v1/workflows?scope=event` lists them). + +**Try it** with `POST /api/v1/workflows/test` (admins): `{"scope": "event", "graph": ..., "kind": "asset.added"}` +runs it on that kind's sample, and `"activity": ""` on a real activity you can see. Nothing is kept and nothing is +sent: each action says what it would do (`would write “New: Call with the school” to the run log`), and `intents` +lists each one with its params, effect, risk, status (`done`, `waiting`, `scheduled` or `failed`) and what it gave +back. Text from outside Lens (`lens.untrusted` on the activity, or what a node passed on when its output says +`untrusted`, like a web page's answer) that reaches an action's params marks its intent `untrusted`. + ### Actions and intents Built: the registry (`app/domain/actions.py`). An action is registered with `actions.register(ActionSpec(name, @@ -480,6 +521,8 @@ the agent can draft an event as a note. channel; web push; private chats through Matterbridge (it can't tell them from rooms); with several people let in, "me" is whoever last wrote privately, until each chat user has a Lens account of their own; telling which links in a message the person's template wrote, so they stay when the run read outside text. +- The canvas draws and edits event workflows (today they are saved and tried through the API). +- An action's outputs in the variable picker, typed from its `output` schema. - The model and the agent: per-node model picks in the studio; streaming an agent's steps into the run's log as they happen; a namespace assistant's memory for automations (`remember` is left out today); approving an agent's proposals from the chat app it told you in; count the automation's own budget once budgets take `automation:`. diff --git a/docs/processing.md b/docs/processing.md index 6b7353053..cd0cddf95 100644 --- a/docs/processing.md +++ b/docs/processing.md @@ -538,7 +538,8 @@ log. ### Organising the graph -A workflow's scope is either assets (above) or the graph. Graph workflows have their own nodes: +A workflow's scope is assets (above), the graph, or an event: an automation's workflow, run by its automation +([The event workflow scope](automations.md#the-event-workflow-scope)). Graph workflows have their own nodes: - **Candidates** finds pairs of entities that may be one thing, by the same rules as the merge suggestions (same letters, acronym, spelling, sounds alike, one name inside the other): inside each namespace (merge) or across diff --git a/fastapi_backend/app/api/v1/routes/workflows.py b/fastapi_backend/app/api/v1/routes/workflows.py index dfbe1a6bd..0a36f95d4 100644 --- a/fastapi_backend/app/api/v1/routes/workflows.py +++ b/fastapi_backend/app/api/v1/routes/workflows.py @@ -2,11 +2,13 @@ from __future__ import annotations +from typing import Literal + from fastapi import APIRouter, HTTPException from app.api.deps import Acl, AdminWriter, Cfg, CurrentUser, Db, Writer, domain_errors from app.api.v1.routes.custom_nodes import me -from app.domain import auth, custom_nodes, flow, jobs, store, workflows +from app.domain import auth, custom_nodes, events, flow, jobs, store, workflows from app.schemas.common import Created, Ok from app.schemas.pipelines import JobQueued from app.schemas.templates import VersionSaved @@ -25,7 +27,7 @@ router = APIRouter(prefix="/workflows", tags=["workflows"]) -DYNAMIC = {"switch": "outputs", "set": "inputs", "group": "both", "custom": "both"} +DYNAMIC = {"switch": "outputs", "set": "inputs", "group": "both", "custom": "both", "decide": "outputs"} def _node_type(t): @@ -40,19 +42,19 @@ def _node_type(t): input_ports=ins, dynamic=DYNAMIC.get(t), primitive=t in flow.PRIMITIVES, - keeps=t in workflows.TERMINAL, + keeps=t in workflows.TERMINAL or t == "action", ) @router.get("") -def list_workflows(user: CurrentUser, db: Db) -> WorkflowCatalog: +def list_workflows(user: CurrentUser, db: Db, scope: Literal["recording", "graph", "tool", "event"] | None = None) -> WorkflowCatalog: """Saved workflows, plus the nodes a workflow can be built from: the primitives, each scope's own nodes, and the - custom nodes you can use.""" + custom nodes you can use. Automations' workflows (scope event) are listed only when asked for with scope.""" return WorkflowCatalog( node_types=[_node_type(t) for t in workflows.NODE_TYPES], operators=list(workflows.OPS), entity_types=list(workflows.ENTITY_TYPES), - workflows=workflows.list_workflows(db), + workflows=workflows.list_workflows(db, scope), custom_nodes=custom_nodes.visible(db, me(user)), ) @@ -60,18 +62,41 @@ def list_workflows(user: CurrentUser, db: Db) -> WorkflowCatalog: @router.post("/test") def try_workflow(body: WorkflowTryRequest, user: AdminWriter, acl: Acl, db: Db, cfg: Cfg) -> WorkflowTry: """Run a graph (saved or not) once without keeping anything: what each node passed on, for the canvas. Nodes - that would save something say what they would save; models are still asked.""" + that would save something say what they would save; models are still asked. An automation's workflow (scope + event) runs on an activity (by id) or a kind's sample, and its actions say what they would do (intents).""" spaces = None if body.scope == "recording": if body.recording is None: raise HTTPException(400, "choose an asset to try it on") acl.recording(body.recording, "process") + elif body.scope == "event": + return _try_event(body, user, acl, db, cfg) else: spaces = [acl.namespace(n) for n in body.namespaces] if body.namespaces else sorted(store.space_names(db)) with domain_errors(): return WorkflowTry(**workflows.try_graph(db, cfg, body.graph.model_dump(), body.scope, body.recording, spaces, user.email)) +def _try_event(body: WorkflowTryRequest, user, acl, db, cfg) -> WorkflowTry: + spaces = [acl.namespace(n) for n in body.namespaces] if body.namespaces else None + if body.activity: + a = events.get(db, cfg, body.activity, events.viewer(user.id, acl.readable(), user.admin)) + if a is None: + raise HTTPException(404, "no such activity") + elif body.kind: + try: + a = events.kind_info(body.kind)["sample"] + except KeyError: + raise HTTPException(400, f"no kind {body.kind}; GET /api/v1/activities/kinds lists them") from None + if a is None: + raise HTTPException(400, f"{body.kind} has no sample to try it on; give an activity") + else: + raise HTTPException(400, "give an activity (its id) or a kind of activity to try it on") + who = {"id": user.id, "email": user.email, "name": user.name, "admin": user.admin} + with domain_errors(): + return WorkflowTry(**workflows.try_graph(db, cfg, body.graph.model_dump(), "event", spaces=spaces, user=who, activity=a)) + + @router.post("") def create_workflow(body: WorkflowCreate, user: AdminWriter, db: Db) -> Created: with domain_errors(): @@ -117,7 +142,7 @@ def run_workflow(wid: int, body: WorkflowRunRequest, user: Writer, acl: Acl, db: except KeyError: raise HTTPException(400, "no such workflow") from None if w["scope"] != "recording": - raise HTTPException(400, "this workflow organises the graph; a routine runs it") + raise HTTPException(400, f"this workflow {workflows.RUN_BY.get(w['scope'], 'runs elsewhere')}") return JobQueued( job=jobs.add_steps(db, body.recording, [{"type": "workflow", "workflow": wid, "version": w["version"]}], by=user.email) ) diff --git a/fastapi_backend/app/domain/automation_nodes.py b/fastapi_backend/app/domain/automation_nodes.py new file mode 100644 index 000000000..b11ce6a05 --- /dev/null +++ b/fastapi_backend/app/domain/automation_nodes.py @@ -0,0 +1,442 @@ +"""What an automation does: the nodes of a workflow of scope `event` (docs/automations.md, The event workflow scope). + +The workflow's `input` node passes on the run context (automation_spec.CONTEXT: the event, each trigger's event, the +automation, the person it acts for, now, what each node passed on so far in `steps`...). Between the primitives +(flow.py) there are two nodes of its own: + +- `action`: one action from the catalog (actions.py), configured `{action, params, delay?, when?}`. When it runs, it + renders its params against the run context (`{{ event.object.name }}`; a param that is exactly one expression keeps + its type), works out its effect and risk (`actions.resolve_risk`, with the automation's policy for the node) and + makes an intent (`automation_spec.check_intent`). A routine intent is carried out there and then, and what it gives + back passes on and goes in `steps.`. One that asks first waits for the person's pick, and one with a delay + (or a time, `when`) waits for its time: such a node passes nothing on, so the nodes after it are skipped and the + run says why. +- `decide`: asks the decision model which of its options fits, with an output port per option and `unsure`. It comes + with the conditions module (match.check_decide, match.run_decide); until then a decide node is refused as coming + soon. + +The leaf rule (`check_graph`, on every path a graph is saved by): an action that reaches outside Lens or other people +(effect `out`, worked out from its params when it is saved) or that waits has nothing wired after it, since it can't +pass anything on while it waits for a yes or its time. + +`Intents` collects what a run's action nodes mean to do, and is where the automations module keeps them and hands the +waiting ones on (to approvals and timers). `context` builds the run context. +""" + +from __future__ import annotations + +import datetime as dt +import importlib +import re + +from . import actions, automation_spec, flow, store, templates + +OWN_NODES = ("action", "decide") +CONFIG = {"action": {"action", "params", "delay", "when"}, "decide": {"question", "options", "input", "min_confidence"}} +NEEDS = "an automation's workflow needs an action node, or it does nothing" +WHOLE_RX = re.compile(r"^\{\{\s*([^{}]+?)\s*\}\}$") +NAMES_RX = re.compile(r"\{[{%](.*?)[%}]\}", re.S) +WORD_RX = re.compile(r"[A-Za-z_][A-Za-z0-9_]*") +READS = {"event", "events", "steps"} # context keys that can hold text from outside Lens + + +def _templated(v): + return isinstance(v, str) and ("{{" in v or "{%" in v) + + +def _strings(value): + """Every string in a value (dicts and lists walked).""" + if isinstance(value, str): + yield value + elif isinstance(value, dict): + for v in value.values(): + yield from _strings(v) + elif isinstance(value, list): + for v in value: + yield from _strings(v) + + +def module(name): + """A module of the studio built in its own step (timers, variables, approvals, automation_hooks), or None while + it isn't there yet, so this module calls it once it lands and keeps its baseline until then.""" + try: + return importlib.import_module(f"{__package__}.{name}") + except ModuleNotFoundError as e: + if e.name != f"{__package__}.{name}": + raise + return None + + +def provided(name, fn): + """`fn` of the module `name`, or None while that module (or that function) isn't there.""" + return getattr(module(name), fn, None) + + +def _timers(): + """The time module's `later` (docs/automations.md, Time), or None.""" + return provided("timers", "later") + + +def _match_fn(name): + return provided("match", name) + + +# ---------- checking ---------- +def check_config(db, nid, t, cfg): + """A node's settings: ValueError naming the first problem.""" + if t == "decide": + check_decide = _match_fn("check_decide") + if check_decide is None: + raise ValueError(f"decide node {nid}: deciding with the model is coming soon; use a condition or switch node") + check_decide(nid, cfg) + return + name = cfg.get("action") + try: + spec = actions.get(name) if isinstance(name, str) else None + except KeyError: + spec = None + if spec is None: + raise ValueError(f"action node {nid}: choose an action (GET /api/v1/automations/actions lists them)") + try: + actions.check_params(spec, cfg.get("params")) + except ValueError as e: + raise ValueError(f"action node {nid}: {e}") from None + for s in _strings(cfg.get("params") or {}): + if _templated(s): + try: + templates.check(s) + except templates.TemplateProblem as e: + raise ValueError(f"action node {nid}: {e}") from None + delay, when = cfg.get("delay"), cfg.get("when") + if delay is not None and when is not None: + raise ValueError(f"action node {nid}: wait for a delay or until a time (when), not both") + if delay is not None and automation_spec.check_duration(delay, what=f"action node {nid}'s delay") == 0: + raise ValueError(f"action node {nid}: a delay is more than 0, like 30m") + if when is not None: + if not isinstance(when, str) or not when.strip(): + raise ValueError(f"action node {nid}: when is a time like 2026-10-16T07:30:00Z, or a template giving one") + if not _templated(when): + try: + _iso(when) + except ValueError: + raise ValueError(f"action node {nid}: when is a time like 2026-10-16T07:30:00Z, or a template giving one") from None + if (delay is not None or when is not None) and _timers() is None: + raise ValueError(f"action node {nid}: waiting before an action is coming soon") + + +def ports(node): + """A decide node's output ports: one per option, then unsure. Other nodes have the default ports.""" + if node["type"] != "decide": + return None + options = (node.get("config") or {}).get("options") + names = [str(k) for k in options] if isinstance(options, dict) else [] + return ["in"], [*names, "unsure"], set() + + +def keeps(node): + """An action node is what an automation's workflow does (it passes things on, so it isn't terminal).""" + return node["type"] == "action" + + +def _waits(c): + return c.get("delay") is not None or c.get("when") is not None + + +def effect(c): + """The effect an action node's params give it (out when it can't be told).""" + try: + spec = actions.get(c.get("action")) + except KeyError: + return "out" + try: + params = actions.check_params(spec, c.get("params")) + except ValueError: + params = dict(c.get("params") or {}) + return actions.effect_of(spec, params) + + +def check_graph(nodes, edges): + """The leaf rule: an action that reaches outside Lens or other people, or that waits, has nothing after it.""" + after = {e["source"] for e in edges} + for n in nodes: + if n["type"] != "action" or n["id"] not in after: + continue + c = n["config"] + if _waits(c): + why = "waits before it acts" + elif effect(c) == "out": + why = "reaches outside Lens or other people, so it asks you first" + else: + continue + raise ValueError(f"action node {n['id']} {why}: it passes nothing on, so connect nothing after it") + + +# ---------- the run context ---------- +def _iso(t): + d = dt.datetime.fromisoformat(str(t).strip().replace("Z", "+00:00")) + return (d if d.tzinfo else d.replace(tzinfo=dt.timezone.utc)).astimezone(dt.timezone.utc) + + +def _z(d): + return d.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + + +def context(db, cfg, automation, run, trigger, event, events, user, now=None): + """The run context (docs/automations.md, Run context). `automation` is {id, name, version, spaces} (spaces None: + every namespace), `run` {id, dry}, `trigger` {as, on, timezone?}, `user` the account the automation acts for. The + variables module builds it when it is there; until then this gives the same keys, with no saved variables.""" + from . import events as ev + + build = provided("variables", "context") + if build is not None: + return build(db, cfg, automation, run, trigger, event, events, user) + spaces = automation.get("spaces") + names = store.space_names(db) + here = [s for s in ev.spaces_of(event or {}) if spaces is None or s in spaces] + sid = here[0] if here else (sorted(spaces)[0] if spaces else None) + return { + "event": event or {}, + "events": dict(events or {}), + "trigger": {"as": trigger.get("as"), "on": trigger.get("on")}, + "automation": { + "id": automation.get("id"), + "name": automation.get("name"), + "version": automation.get("version"), + "spaces": None if spaces is None else sorted(spaces), + }, + "run": {"id": run.get("id"), "dry": bool(run.get("dry"))}, + "namespace": {"id": sid, "name": names.get(sid)} if sid is not None else None, + "user": {"id": (user or {}).get("id"), "name": (user or {}).get("name"), "email": (user or {}).get("email")}, + "now": _z(now or dt.datetime.now(dt.timezone.utc)), + "timezone": trigger.get("timezone") or "UTC", + "vars": {}, + "steps": {}, + } + + +def untrusted(ctx): + """Whether the run read text from outside Lens: an activity it started from marks some of its fields untrusted, or + a node that ran passed on outside text (its output says `untrusted`, like a web page's answer).""" + acts = [ctx.get("event") or {}, *((ctx.get("events") or {}).values())] + for a in acts: + for x in a if isinstance(a, list) else [a]: + if isinstance(x, dict) and ((x.get("lens") or {}).get("untrusted")): + return True + return any(isinstance(out, dict) and out.get("untrusted") for out in (ctx.get("steps") or {}).values()) + + +def _reads_outside(params, ctx): + """Whether rendered params may carry outside text: a template in them names the event, the events or what nodes + passed on (steps), and the run read outside text.""" + if not untrusted(ctx): + return False + for s in _strings(params): + if _templated(s) and any(set(WORD_RX.findall(inner)) & READS for inner in NAMES_RX.findall(s)): + return True + return False + + +def render(value, ctx, where="params"): + """Params with their templates filled in from the run context: a string that is exactly one expression keeps its + type (a list stays a list), others render as text (templates.render_body, sandboxed). The variables module renders + when it is there.""" + fn = provided("variables", "render") + if fn is not None: + return fn(value, ctx, untrusted_paths(ctx)) + return _render(value, ctx, where) + + +def untrusted_paths(ctx): + """The run context's paths that hold outside text: each activity's `lens.untrusted`, under event and events.""" + out = [] + ev = ctx.get("event") or {} + out += [f"event.{p}" for p in (ev.get("lens") or {}).get("untrusted") or []] + for alias, a in (ctx.get("events") or {}).items(): + if isinstance(a, dict): + out += [f"events.{alias}.{p}" for p in (a.get("lens") or {}).get("untrusted") or []] + return out + + +def _render(value, ctx, where): + if isinstance(value, dict): + return {k: _render(v, ctx, f"{where}.{k}") for k, v in value.items()} + if isinstance(value, list): + return [_render(v, ctx, f"{where}.{k}") for k, v in enumerate(value)] + if not _templated(value): + return value + whole = WHOLE_RX.match(value.strip()) + try: + if whole: + return _expression(whole.group(1), ctx) + return templates.render_body(value, ctx, "prompt") + except templates.TemplateProblem as e: + raise ValueError(f"{where}: {e}") from None + + +def _expression(expr, ctx): + """One `{{ }}` expression's value, its type kept.""" + from jinja2 import TemplateSyntaxError, Undefined + from jinja2.exceptions import SecurityError, UndefinedError + + try: + got = templates._env(False).compile_expression(expr, undefined_to_none=False)(**ctx) + except SecurityError as e: + raise templates.TemplateProblem(f"not allowed in templates: {e}") from None + except TemplateSyntaxError as e: + raise templates.TemplateProblem(e.message or "it isn't a template") from None + except (UndefinedError, TypeError, ValueError) as e: + raise templates.TemplateProblem(str(e)) from None + if isinstance(got, Undefined): + raise templates.TemplateProblem(f"{expr.strip()} is not defined") + return got + + +# ---------- running ---------- +class Intents: + """What one run's action nodes mean to do. `user` is the account the automation acts for, `policy` its policy + ({node: ask or auto}), `automation` and `run` its ids (None in a try), `spaces` its namespaces (None: every one). + `keep(intent, extra)` keeps each one (the automations module stores it; extra holds the node's path in the graph, + what it gave back and any error), `hand_off(intent)` passes a waiting or scheduled one on (to approvals or + timers) and may give back what to keep with it. A dry run keeps nothing and hands nothing on.""" + + def __init__(self, db, cfg, user=None, policy=None, automation=None, run=None, spaces=None, dry=False, keep=None, hand_off=None): + self.db, self.cfg, self.user, self.policy = db, cfg, user or {}, dict(policy or {}) + self.automation, self.run, self.spaces, self.dry = automation, run, spaces, bool(dry) + self._keep, self._hand_off = keep, hand_off + self.items: list[dict] = [] + self.failed: dict[str, str] = {} # node path: why + self._seen: dict[str, int] = {} + + def key(self, nid): + """A key for the next intent of node `nid`: -, then -2, -3 for more from the same node (in a loop).""" + n = self._seen[nid] = self._seen.get(nid, 0) + 1 + base = f"{self.run if self.run is not None else 'try'}-{nid}" + return base if n == 1 else f"{base}-{n}" + + def add(self, intent, path, result=None, error=None): + item = {**intent, "path": path, **({"result": result} if result is not None else {}), **({"error": error} if error else {})} + self.items.append(item) + if error: + self.failed[path] = error + if self._keep is not None and not self.dry: + self._keep(intent, {"path": path, "result": result, "error": error}) + return item + + def hand_off(self, intent): + if self._hand_off is None or self.dry: + return None + return self._hand_off(intent) + + def counts(self): + out: dict[str, int] = {} + for i in self.items: + out[i["status"]] = out.get(i["status"], 0) + 1 + return out + + +def run_node(r, f, node, value, vals): + """What an automation's own nodes do: {output port: value}; nothing for an action that waits.""" + if node["type"] == "decide": + run_decide = _match_fn("run_decide") + if run_decide is None: + raise ValueError(f"{flow._label(node)}: deciding with the model is coming soon") + out = run_decide(r, f, node, value) + _steps(r)[node["id"]] = {"choice": next(iter(out), None)} + return out + return _action(r, f, node) + + +def _steps(r): + ctx = r.ctx if isinstance(r.ctx, dict) else {} + return ctx.setdefault("steps", {}) + + +def _action(r, f, node): + c, nid, name = node["config"], node["id"], flow._label(node) + path = f.prefix + nid + box: Intents = r.extra["intents"] + ctx = r.ctx if isinstance(r.ctx, dict) else {} + spec = actions.get(c["action"]) + raw = c.get("params") or {} + intent = { + "key": box.key(nid), + "action": spec.name, + "params": dict(raw), + "effect": "out", + "risk": "ask", + "untrusted": untrusted(ctx), + "spaces": sorted(box.spaces) + if box.spaces is not None + else [s for s in [((ctx.get("namespace") or {}).get("id"))] if s is not None], + "run_as": box.user.get("id") if isinstance(box.user.get("id"), int) else None, + "node": nid, + "automation": box.automation, + "run": box.run, + "when": None, + "status": "failed", + } + try: + filled = actions.check_params(spec, raw) # defaults first, so a default that is a template is filled in too + prompts = set(actions.prompt_params(spec)) + params = actions.check_params( + spec, + { + k: actions.render_prompt(v, ctx, r.cfg) if k in prompts and isinstance(v, str) else render(v, ctx, f"params.{k}") + for k, v in filled.items() + }, + ) + intent["params"] = params + intent["untrusted"] = _reads_outside(filled, ctx) + intent["effect"] = actions.effect_of(spec, params) + intent["risk"] = actions.resolve_risk(spec, params, {**ctx, "node": nid}, box.policy) + if c.get("delay") is not None: + seconds = automation_spec.check_duration(c["delay"]) + intent["when"] = _z(_iso(ctx.get("now") or _z(dt.datetime.now(dt.timezone.utc))) + dt.timedelta(seconds=seconds)) + elif c.get("when") is not None: + got = render(c["when"], ctx, "when") + try: + intent["when"] = _z(_iso(got)) + except (TypeError, ValueError): + raise ValueError(f"when gave {str(got)[:60]!r}, not a time") from None + intent = automation_spec.check_intent(intent) + except (KeyError, ValueError) as e: + why = str(e)[:500] or type(e).__name__ + r.say(f"{name}: failed: {why}") + box.add({**intent, "status": "failed"}, path, error=why) + return {} + said = actions.describe(spec.name, intent["params"]) + if intent["when"]: + intent["status"] = "scheduled" + kept = box.hand_off(intent) + box.add(intent, path, result=kept) + r.say(f"{name}: {'would wait' if box.dry else 'waits'} until {intent['when']} to {said[:1].lower()}{said[1:]}") + r.say(f"stopped at {nid}: waiting until {intent['when']}") + return {} + if intent["risk"] == "ask": + intent["status"] = "waiting" + kept = box.hand_off(intent) + box.add(intent, path, result=kept) + r.say(f"{name}: {'would ask' if box.dry else 'asks'} you first: {said}") + r.say(f"stopped at {nid}: waiting for your pick") + return {} + try: + out = actions.perform(r.db, r.cfg, intent, box.user, dry=box.dry) + except Exception as e: # noqa: BLE001 - recorded on the intent; the rest of the graph goes on + why = f"{type(e).__name__}: {e}"[:500] + intent["status"] = "failed" + box.add(intent, path, error=why) + r.say(f"{name}: failed: {why}") + return {} + intent["status"] = "done" + box.add(intent, path, result=out) + r.say(f"{name}: {'would ' + said[:1].lower() + said[1:] if box.dry else said}") + _steps(r)[nid] = out + return {"out": out} + + +def finish(trace, box): + """The trace with each action that failed marked failed, with why (flow.py saw it pass nothing on).""" + for path, why in box.failed.items(): + if path in trace: + trace[path] = {**trace[path], "status": "failed", "error": why} + return trace diff --git a/fastapi_backend/app/domain/flow.py b/fastapi_backend/app/domain/flow.py index 2a535d4ba..2e3634cf1 100644 --- a/fastapi_backend/app/domain/flow.py +++ b/fastapi_backend/app/domain/flow.py @@ -10,7 +10,9 @@ value on only along yes or along no, a switch only along the case that matched, so the nodes after the other ports are skipped, and so are the ones after those. -The primitives, in every workflow (a scope adds its own nodes: workflows.py, organize.py): +The primitives, in every workflow (a scope adds its own nodes: workflows.py, organize.py, tool_nodes.py, +automation_nodes.py). A scope's Kit may also give its nodes their own ports (`ports`), count nodes that pass things on +as what the workflow does (`keeps`), and add a check of the whole graph (`check_graph`). - `input`: where a workflow starts (the recording, or the namespaces a routine runs over). - `pick`: one part of the value, by a dotted path (`action_items.0.text`). @@ -80,11 +82,18 @@ class Kit: """What a scope adds to the primitives: its node types and their settings, a check for those settings, how they - run, which keep something (a top-level graph needs one), and what a top-level graph's input is called.""" + run, which keep something (a top-level graph needs one), and what a top-level graph's input is called. - def __init__(self, scope, types, config, check, run, terminal, needs): + Three optional hooks change the defaults for the kit's own nodes: `ports(node)` gives a node's (input ports, output + ports, input ports that take several edges), or None for the default (`in` and `out`; none out for a terminal + node); `keeps(node)` says whether a node counts as doing something even though it passes things on (a terminal + node always does); `check_graph(nodes, edges)` checks rules about the whole graph, and every body in it, once its + nodes and edges are checked (ValueError naming the first problem).""" + + def __init__(self, scope, types, config, check, run, terminal, needs, ports=None, keeps=None, check_graph=None): self.scope, self.types, self.config, self.check, self.run = scope, tuple(types), config, check, run self.terminal, self.needs = set(terminal), needs + self.ports, self.keeps, self.check_graph = ports, keeps, check_graph @property def all_types(self): @@ -196,6 +205,10 @@ def ports(node, kit, defs=None): if t == "custom": d = (defs or {}).get((c.get("node"), c.get("version"))) return (list(d["inputs"]), list(d["outputs"]), set()) if d else ([], [], set()) + if kit.ports is not None and t in kit.types and t not in PRIMITIVES: + got = kit.ports(node) + if got is not None: + return got if t in kit.terminal: return ["in"], [], set() return ["in"], ["out"], set() @@ -321,23 +334,32 @@ def check_graph(db, graph, kit, body=None, depth=0, where=""): raise ValueError(f"connect input {missing[0]} of {n['type']} node {n['id']}{where}") if len(order(out_nodes, out_edges)) != len(out_nodes): raise ValueError(f"the workflow has a loop{where}; use a for each or repeat node to go over things again") + if kit.check_graph is not None: + kit.check_graph(out_nodes, out_edges) if body in LOOP_ARGS: if "out" not in body_ports({"nodes": out_nodes})[1]: raise ValueError(f"the body{where} needs a return node called out: what it gives back") - elif body and not body_ports({"nodes": out_nodes})[1] and not any(n["type"] in kit.terminal for n in out_nodes): + elif body and not body_ports({"nodes": out_nodes})[1] and not any(_does(kit, n) for n in out_nodes): raise ValueError(f"the body{where} needs a return node, or it gives nothing back") if not body and not keeps(db, out_nodes, kit): raise ValueError(kit.needs) return {"nodes": out_nodes, "edges": out_edges} +def _does(kit, n): + """Whether a node keeps something, or does something the kit counts as such (its `keeps` hook).""" + if n["type"] in kit.terminal: + return True + return kit.keeps is not None and n["type"] in kit.types and n["type"] not in PRIMITIVES and bool(kit.keeps(n)) + + def keeps(db, nodes, kit): """Whether checked nodes keep something: a node that saves, here, in a body or in a custom node.""" from . import custom_nodes for n in nodes: c = n["config"] - if n["type"] in kit.terminal: + if _does(kit, n): return True if n["type"] in BODIES and keeps(db, c["body"]["nodes"], kit): return True diff --git a/fastapi_backend/app/domain/pipelines.py b/fastapi_backend/app/domain/pipelines.py index f0ab6a5df..1239ae528 100644 --- a/fastapi_backend/app/domain/pipelines.py +++ b/fastapi_backend/app/domain/pipelines.py @@ -58,7 +58,7 @@ def validate_steps(db, steps): except (KeyError, TypeError, ValueError): raise ValueError("workflow step: choose a workflow") from None if w["scope"] != "recording": - raise ValueError(f"workflow step: {w['name']} organises the graph; run it from a routine") + raise ValueError(f"workflow step: {w['name']} {workflows.RUN_BY.get(w['scope'], 'runs elsewhere')}") need = {"llm": "prompt", "export": "export", "report": "report"}.get(t) if need and (s.get("template") or t != "report"): try: diff --git a/fastapi_backend/app/domain/routines.py b/fastapi_backend/app/domain/routines.py index 397b5d81b..0428231af 100644 --- a/fastapi_backend/app/domain/routines.py +++ b/fastapi_backend/app/domain/routines.py @@ -155,6 +155,8 @@ def _check_action(db, k, a): w = workflows.get(db, int(a.get("workflow") or 0), a.get("version")) except (KeyError, TypeError, ValueError): raise ValueError(f"action {k}: choose a workflow") from None + if w["scope"] == "event": + raise ValueError(f"action {k}: {w['name']} {workflows.RUN_BY['event']}") if a.get("propose_only") and w["scope"] != "graph": raise ValueError(f"action {k}: propose_only is for workflows that organise the graph") return store.clean(a) diff --git a/fastapi_backend/app/domain/workflows.py b/fastapi_backend/app/domain/workflows.py index 63d4fe2a7..cb3033494 100644 --- a/fastapi_backend/app/domain/workflows.py +++ b/fastapi_backend/app/domain/workflows.py @@ -19,15 +19,29 @@ Positions are only for the canvas. -A workflow's scope says what it runs on: `recording` (the nodes above, run by pipelines) or `graph` (run over -namespaces, usually by a routine, to organise their entities: see organize.py for its nodes). +A workflow's scope says what it runs on: `recording` (the nodes above, run by pipelines), `graph` (run over +namespaces, usually by a routine, to organise their entities: see organize.py for its nodes) or `event` (what an +automation does when it runs, from the run context: see automation_nodes.py for its action and decide nodes). """ from __future__ import annotations import re -from . import analyze, fields as fieldmod, flow, llm, metadata, organize, pipelines, store, telemetry, templates, tool_nodes +from . import ( + analyze, + automation_nodes, + fields as fieldmod, + flow, + llm, + metadata, + organize, + pipelines, + store, + telemetry, + templates, + tool_nodes, +) R = store.R OWN_NODES = ("llm", "extract_rules", "extract_llm", "output", "field", "save_entities") @@ -197,17 +211,20 @@ def history(db, wid): return db.rows("SELECT version, notes, created_at, created_by FROM workflow_version WHERE workflow = $w ORDER BY version DESC", w=wid) -def list_workflows(db): +def list_workflows(db, scope=None): + """Saved workflows, with the pipelines that run each: those of `scope`, or (None) every one but automations' + (scope event), which are made and changed with their automation.""" used = {} for p in db.rows("SELECT record::id(id) AS id, name, current FROM pipeline"): v = db.one("SELECT steps FROM $r", r=R("pipeline_version", f"{p['id']}-{p['current']}")) or {} for s in v.get("steps") or []: if isinstance(s, dict) and s.get("type") == "workflow" and p["name"] not in used.get(s.get("workflow"), []): used.setdefault(s.get("workflow"), []).append(p["name"]) - return [ + out = [ {**w, "scope": w.get("scope") or "recording", "pipelines": used.get(w["id"], [])} for w in db.rows("SELECT record::id(id) AS id, name, description, scope, current, updated_at FROM workflow ORDER BY id") ] + return [w for w in out if (w["scope"] == scope if scope else w["scope"] != "event")] def _segments(db, rid): @@ -301,7 +318,7 @@ def run(db, cfg, rid, wid, version=None, say=print, user=None): def _run(db, cfg, rid, wid, version, say, user): w = get(db, wid, version) if w["scope"] != "recording": - raise ValueError(f"workflow {w['name']} organises the graph; a routine runs it, not a pipeline") + raise ValueError(f"workflow {w['name']} {RUN_BY.get(w['scope'], 'runs elsewhere')}, not a pipeline") r = flow.Run( db, cfg, KITS["recording"], templates.context(db, cfg, rid), say, user=user, origin={"workflow": w["id"], "workflow_version": w["version"]}, rid=rid, by=user or f"workflow:{w['id']}", @@ -361,11 +378,18 @@ def _run_node(r, f, node, value, vals): return {} -def try_graph(db, cfg, graph, scope="recording", rid=None, spaces=None, user=None): - """Run a graph without keeping anything (a dry run, from the canvas): {trace, log, error}. Nodes that would save - something say what they'd save; models are still asked.""" +RUN_BY = {"graph": "organises the graph; a routine runs it", "event": "is what an automation does; its automation runs it"} + + +def try_graph(db, cfg, graph, scope="recording", rid=None, spaces=None, user=None, activity=None): + """Run a graph without keeping anything (a dry run, from the canvas): {trace, log, error, steps, intents}. Nodes + that would save something say what they'd save; models are still asked. An automation's workflow (scope event) + runs on `activity` (an activity, such as a kind's sample) as the person `user` (an account), over `spaces`; its + actions say what they would do, and `intents` lists them.""" graph = validate_graph(db, graph, scope) log = [] + if scope == "event": + return _try_event(db, cfg, graph, spaces, user, activity, log) if scope == "recording": if rid is None: raise ValueError("choose an asset to try it on") @@ -382,6 +406,25 @@ def try_graph(db, cfg, graph, scope="recording", rid=None, spaces=None, user=Non return {"trace": r.trace, "log": log[-200:], "error": error, "steps": r.steps} +def _try_event(db, cfg, graph, spaces, user, activity, log): + if not isinstance(activity, dict): + raise ValueError("choose an activity, or a kind of activity, to try it on") + who = user if isinstance(user, dict) else {} + auto = {"id": None, "name": "Try", "version": None, "spaces": None if spaces is None else sorted(spaces)} + ctx = automation_nodes.context( + db, cfg, auto, {"id": None, "dry": True}, {"as": "event", "on": "event"}, activity, {"event": activity}, who + ) + box = automation_nodes.Intents(db, cfg, user=who, spaces=auto["spaces"], dry=True) + r = flow.Run(db, cfg, KITS["event"], ctx, log.append, dry=True, user=who.get("email"), intents=box) + error = None + try: + flow.run_graph(r, graph) + except Exception as e: # shown on the canvas, on the node that failed + error = str(e)[:500] or type(e).__name__ + trace = automation_nodes.finish(r.trace, box) + return {"trace": trace, "log": log[-200:], "error": error, "steps": r.steps, "intents": box.items} + + def _fit(f, v): """A model's value shaped for a field: lists joined for text, one item for a single choice.""" if isinstance(v, dict): @@ -411,8 +454,14 @@ def _fit(f, v): "tool", tool_nodes.OWN_NODES, tool_nodes.CONFIG, lambda db, nid, t, cfg: tool_nodes.check_config(db, nid, t, cfg), tool_nodes.run_node, set(), "a tool's graph is the body of a tool", ), + # what an automation does (automation_nodes.py): from the run context, its actions and decide nodes + "event": flow.Kit( + "event", automation_nodes.OWN_NODES, automation_nodes.CONFIG, automation_nodes.check_config, automation_nodes.run_node, + set(), automation_nodes.NEEDS, ports=automation_nodes.ports, keeps=automation_nodes.keeps, + check_graph=automation_nodes.check_graph, + ), } # fmt: skip SCOPES = {s: k.all_types for s, k in KITS.items()} RECORDING_NODES = SCOPES["recording"] -NODE_TYPES = RECORDING_NODES + tuple(t for s in ("graph", "tool") for t in SCOPES[s] if t not in RECORDING_NODES) -CONFIG = {**flow.CONFIG, **OWN_CONFIG, **organize.CONFIG, **tool_nodes.CONFIG} +NODE_TYPES = RECORDING_NODES + tuple(dict.fromkeys(t for s in ("graph", "tool", "event") for t in SCOPES[s] if t not in RECORDING_NODES)) +CONFIG = {**flow.CONFIG, **OWN_CONFIG, **organize.CONFIG, **tool_nodes.CONFIG, **automation_nodes.CONFIG} diff --git a/fastapi_backend/app/schemas/workflows.py b/fastapi_backend/app/schemas/workflows.py index d5d944b5e..b6207cda8 100644 --- a/fastapi_backend/app/schemas/workflows.py +++ b/fastapi_backend/app/schemas/workflows.py @@ -33,7 +33,10 @@ class WorkflowSummary(ResponseModel): id: int name: str description: str | None = None - scope: str = Field("recording", description="recording (run by pipelines) or graph (run over namespaces by routines)") + scope: str = Field( + "recording", + description="recording (run by pipelines), graph (run over namespaces by routines) or event (what an automation does)", + ) current: int updated_at: str | None = None pipelines: list[str] = Field(default_factory=list, description="pipelines whose current version runs it") @@ -43,7 +46,7 @@ class WorkflowCatalog(ResponseModel): node_types: list[NodeType] operators: list[str] = Field(description="what a condition node can test") entity_types: list[str] - scopes: list[str] = Field(default_factory=lambda: ["recording", "graph"]) + scopes: list[str] = Field(default_factory=lambda: ["recording", "graph", "event"]) workflows: list[WorkflowSummary] custom_nodes: list[dict[str, Any]] = Field(default_factory=list, description="the custom nodes you can use") @@ -74,7 +77,7 @@ class WorkflowCreate(RequestModel): name: str graph: WorkflowGraph description: str | None = None - scope: Literal["recording", "graph"] = "recording" + scope: Literal["recording", "graph", "event"] = "recording" class WorkflowVersionCreate(RequestModel): @@ -95,9 +98,13 @@ class WorkflowRunRequest(RequestModel): class WorkflowTryRequest(RequestModel): graph: WorkflowGraph - scope: Literal["recording", "graph"] = "recording" + scope: Literal["recording", "graph", "event"] = "recording" recording: int | None = Field(None, description="the asset to try a recording workflow on") - namespaces: list[str] = Field(default_factory=list, description="the namespaces to try a graph workflow over (default: all)") + namespaces: list[str] = Field( + default_factory=list, description="the namespaces to try a graph workflow over, or an automation's workflow in (default: all)" + ) + activity: str | None = Field(None, description="an automation's workflow: the activity to try it on, by its id") + kind: str | None = Field(None, description="an automation's workflow: try it on this kind of activity's sample") class NodeTrace(ResponseModel): @@ -113,3 +120,8 @@ class WorkflowTry(ResponseModel): log: list[str] error: str | None = None steps: int + intents: list[dict[str, Any]] = Field( + default_factory=list, + description="an automation's workflow: what its action nodes would do (status done: at once; waiting: asks you first; " + "scheduled: waits for its time; failed), with each one's params, effect, risk and what it would give back (result)", + ) diff --git a/fastapi_backend/tests/api/test_event_workflows.py b/fastapi_backend/tests/api/test_event_workflows.py new file mode 100644 index 000000000..359c3cac6 --- /dev/null +++ b/fastapi_backend/tests/api/test_event_workflows.py @@ -0,0 +1,97 @@ +"""An automation's workflow (scope event) over the API (docs/automations.md, The event workflow scope): saved with its +own checks and the leaf rule, kept out of the canvas's list, never run by a pipeline or a routine, and tried on an +activity or a kind's sample, with what each action would do.""" + +from __future__ import annotations + +from app.domain import ingest +from tests.helpers import login, make_user, seed + +URL = "/api/v1/workflows" + + +def node(nid, t, **config): + return {"id": nid, "type": t, "config": config} + + +def edge(a, b, branch=None): + return {"source": a, "target": b, **({"branch": branch} if branch else {})} + + +LOG = { + "nodes": [node("i", "input"), node("a", "action", action="log_line", params={"text": "new: {{ event.object.name }}"})], + "edges": [edge("i", "a")], +} + + +def _root(client, db): + make_user(db, "root@x.io", "root password 1", admin=True) + return login(client, "root@x.io", "root password 1") + + +def test_event_workflows_are_checked_and_kept_apart(client, db, cfg): + h = _root(client, db) + rec = ingest.import_text(db, cfg, "pods", "Alice: Hello.", title="Hello") + cat = client.get(URL, headers=h).json() + types = {n["type"]: n for n in cat["node_types"]} + assert types["action"]["scopes"] == ["event"] and types["action"]["keeps"] and types["action"]["outputs"] == ["out"] + assert types["decide"]["dynamic"] == "outputs" and "event" in cat["scopes"] + + def problem(graph): + r = client.post(URL, headers=h, json={"name": "x", "scope": "event", "graph": graph}) + assert r.status_code == 400, r.text + return r.json()["detail"] + + assert "needs an action node" in problem({"nodes": [node("i", "input")], "edges": []}) + assert "choose an action" in problem({"nodes": [node("i", "input"), node("a", "action", action="nope")], "edges": [edge("i", "a")]}) + assert "text" in problem({"nodes": [node("i", "input"), node("a", "action", action="log_line", params={})], "edges": [edge("i", "a")]}) + assert "coming soon" in problem( + {"nodes": [node("i", "input"), node("d", "decide", question="Urgent?", options=["yes", "no"])], "edges": [edge("i", "d")]} + ) + wid = client.post(URL, headers=h, json={"name": "Say it", "scope": "event", "graph": LOG}).json()["id"] + # the canvas's list leaves it out; asked for by scope, it's there + assert all(w["id"] != wid for w in client.get(URL, headers=h).json()["workflows"]) + assert [w["id"] for w in client.get(URL, params={"scope": "event"}, headers=h).json()["workflows"]] == [wid] + assert client.get(f"{URL}/{wid}", headers=h).json()["scope"] == "event" + # its automation runs it: not on an asset, nor as a pipeline step or a routine's action + for path, body in ( + ("/api/v1/pipelines", {"name": "p", "steps": [{"type": "workflow", "workflow": wid}]}), + ("/api/v1/routines", {"name": "r", "actions": [{"type": "workflow", "workflow": wid}]}), + ): + r = client.post(path, headers=h, json=body) + assert r.status_code == 400 and "its automation runs it" in r.json()["detail"], r.text + r = client.post(f"{URL}/{wid}/run", headers=h, json={"recording": rec}) + assert r.status_code == 400 and "its automation runs it" in r.json()["detail"] + + +def test_an_event_workflow_is_tried_on_an_activity_or_a_sample(client, db, cfg, folder): + ids = seed(db, cfg, folder) + h = _root(client, db) + make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + t = client.post(f"{URL}/test", headers=h, json={"scope": "event", "kind": "asset.added", "graph": LOG}).json() + assert t["error"] is None and t["trace"]["a"]["status"] == "done", t + [it] = t["intents"] + assert ( + it["action"] == "log_line" + and it["status"] == "done" + and it["effect"] == "read" + and it["result"]["line"] == "new: Call with the school" + ) + assert it["untrusted"] is True and it["params"] == {"text": "new: Call with the school", "level": "info"} + assert any("would write" in line for line in t["log"]), t["log"] + # on a real activity, by its id + one = f"create-recording-{ids[0]}" + t = client.post(f"{URL}/test", headers=h, json={"scope": "event", "activity": one, "graph": LOG}).json() + title = client.get(f"/api/v1/activities/{one}", headers=h).json()["object"]["name"] + assert t["intents"][0]["result"]["line"] == f"new: {title}" + # what it can't be tried on + for body, code, words in ( + ({"activity": "create-recording-999"}, 404, "no such activity"), + ({"kind": "email.nope"}, 400, "no kind email.nope"), + ({}, 400, "give an activity"), + ): + r = client.post(f"{URL}/test", headers=h, json={"scope": "event", "graph": LOG, **body}) + assert r.status_code == code and words in r.json()["detail"], r.text + # only an admin tries workflows + hv = login(client, "vi@x.io", "viewer password 1") + assert client.post(f"{URL}/test", headers=hv, json={"scope": "event", "kind": "asset.added", "graph": LOG}).status_code == 403 diff --git a/fastapi_backend/tests/api/test_flow.py b/fastapi_backend/tests/api/test_flow.py index d18714bd5..83fcd9dc1 100644 --- a/fastapi_backend/tests/api/test_flow.py +++ b/fastapi_backend/tests/api/test_flow.py @@ -205,9 +205,9 @@ def test_custom_nodes_are_shared_versioned_and_pinned(client, new_client, db, cf assert (got["inputs"], got["outputs"], got["scopes"], got["keeps"]) == ( ["in"], ["match", "other"], - ["recording", "graph", "tool"], + ["recording", "graph", "tool", "event"], False, - ) # primitives only: tool graphs too + ) # primitives only: tool graphs and automations' too assert got["graph"]["nodes"][2]["config"]["value"] == {"$param": "word"} and got["editable"] # private: the owner and admins see it, nobody else @@ -346,5 +346,5 @@ def test_catalog_lists_ports_and_primitives(client, db): h = login(client, "root@x.io", "root password 1") types = {n["type"]: n for n in client.get("/api/v1/workflows", headers=h).json()["node_types"]} assert types["switch"]["dynamic"] == "outputs" and types["switch"]["primitive"] - assert types["for_each"]["scopes"] == ["recording", "graph", "tool"] and types["output"]["keeps"] + assert types["for_each"]["scopes"] == ["recording", "graph", "tool", "event"] and types["output"]["keeps"] assert types["arg"]["inputs"] == 0 and types["return"]["outputs"] == [] and types["merge"]["inputs"] == -1 diff --git a/fastapi_backend/tests/domain/test_automation_nodes.py b/fastapi_backend/tests/domain/test_automation_nodes.py new file mode 100644 index 000000000..ed08447b4 --- /dev/null +++ b/fastapi_backend/tests/domain/test_automation_nodes.py @@ -0,0 +1,306 @@ +"""An automation's workflow (scope event, docs/automations.md): its action and decide nodes are checked on every save, +with the leaf rule; action params render from the run context; routine intents are carried out and pass their output +on, intents that ask first or wait pass nothing on (and the nodes after them are skipped); a failing action is marked +failed and the rest of the graph goes on; and a try keeps nothing.""" + +from __future__ import annotations + +import pytest + +from app.domain import actions, automation_nodes, events, flow, match, workflows +from app.domain.actions import ActionSpec + +SAMPLE = events.kind_info("asset.added")["sample"] +USER = {"id": 1, "email": "sam@x.io", "name": "Sam", "admin": True} + + +def node(nid, t, **config): + return {"id": nid, "type": t, "config": config} + + +def edge(a, b, port=None): + return {"source": a, "target": b, **({"port": port} if port else {})} + + +def graph(*nodes, edges=()): + return {"nodes": [node("in", "input"), *nodes], "edges": list(edges)} + + +@pytest.fixture +def made(): + """Two actions for the tests: `tell` (out to a room, self to "me") and `tag` (changes an asset in Lens), both + remembering what they were asked to do; and one that always fails.""" + done = [] + + def perform(db, cfg, intent, user, dry): + done.append((intent["action"], intent["params"], user["email"], dry)) + return {"ok": True, "said": intent["params"].get("text") or intent["params"].get("object")} + + def broken(db, cfg, intent, user, dry): + raise RuntimeError("the line is down") + + specs = [ + ActionSpec( + name="tell", + label="Tell someone", + group="Messages", + params={"type": "object", "properties": {"to": {"type": "string", "default": "me"}, "text": {"type": "string"}}}, + required=("text",), + effect=lambda p: "self" if p.get("to") == "me" else "out", + perform=perform, + describe=lambda p: f"Tell {p.get('to')} “{p.get('text')}”", + ), + ActionSpec( + name="tag", + label="Tag an asset", + group="Lens", + params={"type": "object", "properties": {"object": {"type": "string"}, "tags": {"type": "array"}}}, + required=("object",), + effect="lens", + perform=perform, + ), + ActionSpec( + name="broken", + label="Always fails", + group="Run", + params={"type": "object", "properties": {}}, + effect="read", + perform=broken, + ), + ] + for s in specs: + actions.register(s) + yield done + for s in specs: + actions._ACTIONS.pop(s.name, None) + + +def _try(db, cfg, g, activity=SAMPLE, spaces=None): + return workflows.try_graph(db, cfg, g, "event", spaces=spaces, user=USER, activity=activity) + + +def _problem(db, g): + with pytest.raises(ValueError) as e: + workflows.validate_graph(db, g, "event") + return str(e.value) + + +def test_event_workflows_are_checked_on_save(db, made): + assert "needs an action node" in _problem(db, graph(node("p", "pick", path="event"), edges=[edge("in", "p")])) + assert "choose an action" in _problem(db, graph(node("a", "action", action="nope"), edges=[edge("in", "a")])) + assert "needs Line (text)" in _problem(db, graph(node("a", "action", action="log_line"), edges=[edge("in", "a")])) + assert "has no param colour" in _problem( + db, graph(node("a", "action", action="log_line", params={"text": "x", "colour": "red"}), edges=[edge("in", "a")]) + ) + assert "line 1" in _problem(db, graph(node("a", "action", action="log_line", params={"text": "{{ x "}), edges=[edge("in", "a")])) + assert "action node has no setting retry" in _problem( + db, graph(node("a", "action", action="log_line", params={"text": "x"}, retry=3), edges=[edge("in", "a")]) + ) + # a templated param stands for any type until it runs + ok = graph( + node("a", "action", action="tag", params={"object": "{{ event.object.id }}", "tags": "{{ event.tag }}"}), edges=[edge("in", "a")] + ) + assert workflows.validate_graph(db, ok, "event")["nodes"][1]["config"]["params"]["tags"] == "{{ event.tag }}" + # waiting before an action comes with the time module; until then it is refused, as are both kinds of wait + waits = graph(node("a", "action", action="log_line", params={"text": "x"}, delay="5m"), edges=[edge("in", "a")]) + assert "coming soon" in _problem(db, waits) + assert "not both" in _problem( + db, + graph( + node("a", "action", action="log_line", params={"text": "x"}, delay="5m", when="2026-10-16T07:00:00Z"), edges=[edge("in", "a")] + ), + ) + assert "can't point back" in _problem( + db, graph(node("a", "action", action="log_line", params={"text": "x"}, delay="-5m"), edges=[edge("in", "a")]) + ) + # deciding with the model comes with the conditions module + assert "coming soon" in _problem( + db, + graph( + node("d", "decide", question="Urgent?", options={"yes": "urgent"}), + node("a", "action", action="log_line", params={"text": "x"}), + edges=[edge("in", "d"), edge("d", "a", "yes")], + ), + ) + # the event scope's nodes are its own: an action is refused in a recording workflow + with pytest.raises(ValueError, match="node types are"): + workflows.validate_graph(db, graph(node("a", "action", action="log_line", params={"text": "x"}), edges=[edge("in", "a")])) + + +def test_the_leaf_rule_holds_on_every_save_path(db, made): + after = node("l", "action", action="log_line", params={"text": "after"}) + out = graph(node("a", "action", action="tell", params={"to": "family", "text": "hi"}), after, edges=[edge("in", "a"), edge("a", "l")]) + assert "reaches outside Lens or other people" in _problem(db, out) + # a templated reach counts as out, as an effect that can't be worked out does + tpl = graph( + node("a", "action", action="tell", params={"to": "{{ vars.room }}", "text": "hi"}), after, edges=[edge("in", "a"), edge("a", "l")] + ) + assert "reaches outside Lens" in _problem(db, tpl) + # in a body too + body = {"nodes": [node("x", "arg", name="item"), node("a", "action", action="tell", params={"to": "family", "text": "hi"}), + node("r", "return", name="out")], "edges": [edge("x", "a"), edge("a", "r")]} # fmt: skip + looped = graph(node("f", "for_each", path="event.tag", body=body), edges=[edge("in", "f")]) + assert "action node a reaches outside Lens" in _problem(db, looped) + # a message to the person themselves, or a change in Lens, may have nodes after it + mine = graph(node("a", "action", action="tell", params={"text": "hi"}), after, edges=[edge("in", "a"), edge("a", "l")]) + assert workflows.validate_graph(db, mine, "event") + # an out action at the end is fine, and so is a body whose only node is an action (it does something) + assert workflows.validate_graph( + db, graph(node("a", "action", action="tell", params={"to": "family", "text": "hi"}), edges=[edge("in", "a")]), "event" + ) + group = { + "nodes": [node("x", "arg", name="in"), node("a", "action", action="tell", params={"to": "family", "text": "hi"})], + "edges": [edge("x", "a")], + } + assert workflows.validate_graph(db, graph(node("g", "group", body=group), edges=[edge("in", "g")]), "event") + # and the workflow API checks the same (its routes call validate_graph with the workflow's scope) + wid = workflows.create(db, "School emails", mine, scope="event") + with pytest.raises(ValueError, match="reaches outside Lens"): + workflows.save_version(db, wid, out) + + +def test_actions_render_from_the_run_context_and_pass_their_output_on(db, cfg, made): + g = graph( + node("a", "action", action="tag", params={"object": "{{ event.object.id }}", "tags": "{{ [event.object.media, event.space] }}"}), + node("b", "action", action="tell", params={"text": "Tagged {{ steps.a.said }} in {{ namespace.name }}"}), + node("l", "action", action="log_line", params={"text": "{{ event.summary }}"}), + edges=[edge("in", "a"), edge("a", "b"), edge("in", "l")], + ) + out = _try(db, cfg, g) + assert out["error"] is None and [t["status"] for t in out["trace"].values()] == ["done"] * 4 + by = {i["node"]: i for i in out["intents"]} + # one expression keeps its type; others render as text + assert by["a"]["params"] == {"object": "lens:recording/7", "tags": ["audio", 1]} and by["a"]["effect"] == "lens" + # a change to the event's own object in the automation's namespaces is routine; so is telling the person + assert by["a"]["risk"] == "routine" and by["b"]["risk"] == "routine" and by["b"]["effect"] == "self" + assert by["b"]["params"]["text"] == "Tagged lens:recording/7 in pods" and by["b"]["result"]["ok"] is True + # params made from the event's outside text are marked so; a fixed one isn't + assert by["l"]["untrusted"] is True and by["l"]["params"]["text"] == SAMPLE["summary"] + assert {i["key"] for i in out["intents"]} == {"try-a", "try-b", "try-l"} and all(i["status"] == "done" for i in out["intents"]) + # a try is dry: every action was asked what it would do, as the person + assert {(a, dry, who) for a, _, who, dry in made} == {("tag", True, "sam@x.io"), ("tell", True, "sam@x.io")} + assert any(line.startswith("action b: would tell me") for line in out["log"]) + + +def test_prompts_mark_outside_text_and_template_defaults_are_filled_in(db, cfg, made): + def ask(db, cfg, intent, user, dry): + return {"reply": "a web page said so", "untrusted": True} + + spec = ActionSpec( + name="ask", + label="Ask the model", + group="AI", + params={ + "type": "object", + "properties": {"prompt": {"type": "string", "format": "prompt"}, "about": {"type": "object", "default": "{{ event }}"}}, + }, + required=("prompt",), + effect="read", + perform=ask, + ) + actions.register(spec) + try: + g = graph( + node("a", "action", action="ask", params={"prompt": "Sum up {{ event.object.name }} for {{ user.name }}"}), + node("s", "action", action="log_line", params={"text": "{{ steps.a.reply }}"}), + node("f", "action", action="log_line", params={"text": "fixed"}), + edges=[edge("in", "a"), edge("a", "s"), edge("a", "f")], + ) + out = _try(db, cfg, g) + by = {i["node"]: i for i in out["intents"]} + prompt = by["a"]["params"]["prompt"] + # in a prompt, what the run read from outside Lens is marked as data; the person's own words stay as written + assert prompt.startswith("Sum up ( options?: Options, - ): RequestResult { - return (options?.client ?? client).get({ + ): RequestResult { + return (options?.client ?? client).get({ url: "/api/v1/workflows", ...options, }); @@ -8940,7 +8941,8 @@ export class Workflows { * Try Workflow * * Run a graph (saved or not) once without keeping anything: what each node passed on, for the canvas. Nodes - * that would save something say what they would save; models are still asked. + * that would save something say what they would save; models are still asked. An automation's workflow (scope + * event) runs on an activity (by id) or a kind's sample, and its actions say what they would do (intents). */ public static tryWorkflow( options: Options, diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 650c94254..0166ad4ce 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -21439,7 +21439,7 @@ export type WorkflowCreate = { /** * Scope */ - scope?: "recording" | "graph"; + scope?: "recording" | "graph" | "event"; }; /** @@ -21497,7 +21497,7 @@ export type WorkflowSummary = { /** * Scope * - * recording (run by pipelines) or graph (run over namespaces by routines) + * recording (run by pipelines), graph (run over namespaces by routines) or event (what an automation does) */ scope?: string; /** @@ -21541,6 +21541,14 @@ export type WorkflowTry = { * Steps */ steps: number; + /** + * Intents + * + * an automation's workflow: what its action nodes would do (status done: at once; waiting: asks you first; scheduled: waits for its time; failed), with each one's params, effect, risk and what it would give back (result) + */ + intents?: Array<{ + [key: string]: unknown; + }>; [key: string]: unknown; }; @@ -21552,7 +21560,7 @@ export type WorkflowTryRequest = { /** * Scope */ - scope?: "recording" | "graph"; + scope?: "recording" | "graph" | "event"; /** * Recording * @@ -21562,9 +21570,21 @@ export type WorkflowTryRequest = { /** * Namespaces * - * the namespaces to try a graph workflow over (default: all) + * the namespaces to try a graph workflow over, or an automation's workflow in (default: all) */ namespaces?: Array; + /** + * Activity + * + * an automation's workflow: the activity to try it on, by its id + */ + activity?: string | null; + /** + * Kind + * + * an automation's workflow: try it on this kind of activity's sample + */ + kind?: string | null; }; /** @@ -35123,10 +35143,24 @@ export type SetRecordingContentTypeResponse = SetRecordingContentTypeResponses[k export type ListWorkflowsData = { body?: never; path?: never; - query?: never; + query?: { + /** + * Scope + */ + scope?: "recording" | "graph" | "tool" | "event" | null; + }; url: "/api/v1/workflows"; }; +export type ListWorkflowsErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type ListWorkflowsError = ListWorkflowsErrors[keyof ListWorkflowsErrors]; + export type ListWorkflowsResponses = { /** * Successful Response diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 53c57818c..0a6d6d491 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -22111,8 +22111,32 @@ "workflows" ], "summary": "List Workflows", - "description": "Saved workflows, plus the nodes a workflow can be built from: the primitives, each scope's own nodes, and the\ncustom nodes you can use.", + "description": "Saved workflows, plus the nodes a workflow can be built from: the primitives, each scope's own nodes, and the\ncustom nodes you can use. Automations' workflows (scope event) are listed only when asked for with scope.", "operationId": "list_workflows", + "parameters": [ + { + "name": "scope", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "enum": [ + "recording", + "graph", + "tool", + "event" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Scope" + } + } + ], "responses": { "200": { "description": "Successful Response", @@ -22123,6 +22147,16 @@ } } } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } } } }, @@ -22133,14 +22167,14 @@ "summary": "Create Workflow", "operationId": "create_workflow", "requestBody": { + "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowCreate" } } - }, - "required": true + } }, "responses": { "200": { @@ -22172,7 +22206,7 @@ "workflows" ], "summary": "Try Workflow", - "description": "Run a graph (saved or not) once without keeping anything: what each node passed on, for the canvas. Nodes\nthat would save something say what they would save; models are still asked.", + "description": "Run a graph (saved or not) once without keeping anything: what each node passed on, for the canvas. Nodes\nthat would save something say what they would save; models are still asked. An automation's workflow (scope\nevent) runs on an activity (by id) or a kind's sample, and its actions say what they would do (intents).", "operationId": "try_workflow", "requestBody": { "content": { @@ -65682,7 +65716,8 @@ "type": "string", "enum": [ "recording", - "graph" + "graph", + "event" ], "title": "Scope", "default": "recording" @@ -65772,7 +65807,7 @@ "scope": { "type": "string", "title": "Scope", - "description": "recording (run by pipelines) or graph (run over namespaces by routines)", + "description": "recording (run by pipelines), graph (run over namespaces by routines) or event (what an automation does)", "default": "recording" }, "current": { @@ -65839,6 +65874,15 @@ "steps": { "type": "integer", "title": "Steps" + }, + "intents": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array", + "title": "Intents", + "description": "an automation's workflow: what its action nodes would do (status done: at once; waiting: asks you first; scheduled: waits for its time; failed), with each one's params, effect, risk and what it would give back (result)" } }, "additionalProperties": true, @@ -65859,7 +65903,8 @@ "type": "string", "enum": [ "recording", - "graph" + "graph", + "event" ], "title": "Scope", "default": "recording" @@ -65882,7 +65927,31 @@ }, "type": "array", "title": "Namespaces", - "description": "the namespaces to try a graph workflow over (default: all)" + "description": "the namespaces to try a graph workflow over, or an automation's workflow in (default: all)" + }, + "activity": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Activity", + "description": "an automation's workflow: the activity to try it on, by its id" + }, + "kind": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Kind", + "description": "an automation's workflow: try it on this kind of activity's sample" } }, "additionalProperties": false,