From 53b20cb3ebb9db65b45f7d7681c8a4d6942fc18a Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 06:08:59 +0000 Subject: [PATCH] feat(workflows): an entity filter node Keeps a list's entities by type, a stop list of names, length, a pattern or how often they're said, between extraction and saving. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016j3Y4Dh3DLGwyFYBH23QML --- README.md | 2 +- docs/processing.md | 6 +- docs/requirements.md | 1 + fastapi_backend/app/domain/flow.py | 64 ++++++++++++++++- fastapi_backend/app/domain/workflows.py | 2 +- fastapi_backend/tests/api/test_flow.py | 43 ++++++++++- .../__tests__/workflow-flow.test.ts | 29 ++++++++ .../components/workflows/node-settings.tsx | 72 +++++++++++++++++++ .../components/workflows/workflow-model.ts | 38 ++++++++++ 9 files changed, 250 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index a897e69e9..ca97db235 100644 --- a/README.md +++ b/README.md @@ -158,7 +158,7 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p namespaces), then tell you in your own chat app, ask the model or the agent, use a tool, call a web address (its credentials kept sealed), run a workflow, pipeline or routine, or change assets and notes. A Classify node in a workflow sorts an asset into labels, - content types or topics, acting only on a sure answer. Anything that reaches outside Lens or changes more than what + content types or topics, acting only on a sure answer, and an Entity filter node keeps the entities you want. 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; the studio to draw them diff --git a/docs/processing.md b/docs/processing.md index b9f469e35..35ef925a7 100644 --- a/docs/processing.md +++ b/docs/processing.md @@ -696,8 +696,10 @@ node passes what it makes along its connections. - **Entities:** Extract entities (rules) runs the extractor analyze uses (the rules, or spaCy), plus your terms (`Name|TYPE`) and regular expressions (`TYPE: pattern`); Extract entities (LLM) asks the model for structured entities and keeps, - corrects or adds to any passed in; Merge joins lists; Save entities makes them the asset's entities (people's - corrections kept) and redoes keywords and chapters. + corrects or adds to any passed in; Merge joins lists; Entity filter keeps the entities you want (only some types, + without others, without names on a stop list, names at least so long or matching a pattern, or said at least so + many times; anything in the list that isn't an entity is left out); Save entities makes them the asset's entities + (people's corrections kept) and redoes keywords and chapters. - **AI and logic:** LLM prompt (a prompt template, with what came in as `{{ input }}`), Classify (which of your labels, the content types or the namespace's topics fits the asset, or what came in as text; it passes on `choice`, `confidence`, `sure` and `ranked`, so a Condition or Switch can branch on them; [classifying](#classifying)), Pick diff --git a/docs/requirements.md b/docs/requirements.md index b5bff08fd..43177e3fd 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -179,6 +179,7 @@ request, to another check that proves the same thing; loosening a requirement or |---|---| | Pipelines and workflows on a canvas | [test_workflows.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_workflows.py) `test_workflows_run_in_pipelines_drawn_as_graphs`; [workflow-canvas.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-canvas.test.ts); [journeys.mjs](https://github.com/adeelahmad/lense/blob/main/ci/clicks/journeys.mjs) `pipeline-create`, `workflow-create` | | A Classify node in workflows chooses from labels, content types or topics, and acting on a sure answer keeps something | [test_classify.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_classify.py) `test_a_workflow_classifies`; [workflow-flow.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-flow.test.ts) `chooses from labels, content types or topics, and acting on a sure answer keeps something` | +| An Entity filter node keeps a list's entities by type, stop list, length, pattern or how often they're said | [test_flow.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_flow.py) `test_entity_filter_keeps_the_entities_asked_for`; [workflow-flow.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-flow.test.ts) `an entity filter says what it keeps and refuses lowercase types` | | Routines on a schedule | [test_routines.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_routines.py) `test_routines_are_checked_and_run_when_due`, `test_schedules`; [journeys.mjs](https://github.com/adeelahmad/lense/blob/main/ci/clicks/journeys.mjs) `routine-create`; [baseline.json](https://github.com/adeelahmad/lense/blob/main/ci/clicks/baseline.json) `routine-create` ≤ 2 clicks | | Batch runs over a collection | [test_batches.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_batches.py) `test_collections_and_batches` | | Notifications to webhooks, Slack, Discord and Matterbridge | [test_notifications.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notifications.py) `test_owners_manage_targets_and_a_test_is_signed`, `test_runs_that_end_are_sent_once_to_matterbridge` | diff --git a/fastapi_backend/app/domain/flow.py b/fastapi_backend/app/domain/flow.py index 2e3634cf1..f9bc0cfb8 100644 --- a/fastapi_backend/app/domain/flow.py +++ b/fastapi_backend/app/domain/flow.py @@ -26,6 +26,11 @@ - `template`: renders a template with what came in as `input` (and the recording or namespaces); `json` reads the result as JSON. - `filter`: keeps the items of a list that pass a test (or a match tree). +- `entity_filter`: keeps the entities of a list ({name, type}, as extract nodes pass them on) that are of the types + it keeps (`types`) and not of those it skips (`skip_types`), aren't named in `skip_names` (a stop list, matched as + entities are joined: case and spacing aside), have names at least `min_length` characters long that match + `pattern` (a regular expression, case aside, checked as a match tree's are), and are said at least `min_mentions` times (their + `mentions`, else how often the list names them). Anything in the list that isn't an entity is left out. - `for_each`: runs its `body` (a graph) once per item of a list and passes on the list of what the body returned; an item the body returned nothing for is left out (so it maps and filters). The body starts from `arg` nodes: `item`, `index` and `input` (all of what came in). @@ -55,9 +60,11 @@ OPS = ("exists", "empty", "equals", "not_equals", "contains", "gt", "lt") MAX_NODES, MAX_DEPTH, MAX_STEPS = 100, 5, 20000 MAX_ITEMS, MAX_ROUNDS, MAX_CASES, MAX_FIELDS = 1000, 50, 20, 50 +MAX_NAMES = 500 # names in an entity filter's stop list +TYPE_RX = re.compile(r"^[A-Z][A-Z_]{0,30}$") PRIMITIVES = ( - "input", "pick", "condition", "switch", "merge", "set", "template", "filter", "for_each", "repeat", "group", "custom", - "arg", "return", + "input", "pick", "condition", "switch", "merge", "set", "template", "filter", "entity_filter", "for_each", "repeat", + "group", "custom", "arg", "return", ) # fmt: skip CONFIG = { "input": set(), @@ -68,6 +75,7 @@ "set": {"inputs", "fields", "keep"}, "template": {"template", "json"}, "filter": {"path", "op", "value", "match"}, + "entity_filter": {"types", "skip_types", "skip_names", "pattern", "min_length", "min_mentions"}, "for_each": {"path", "body", "max_items"}, "repeat": {"body", "max_rounds", "until"}, "group": {"body"}, @@ -464,6 +472,8 @@ def _check_primitive(db, kit, nid, t, cfg, body, depth, here): _check_template(nid, f["template"]) elif t == "template": _check_template(nid, cfg.get("template")) + elif t == "entity_filter": + _check_entity_filter(nid, cfg) elif t == "for_each": if cfg.get("path") and not PATH_RX.match(str(cfg["path"])): raise ValueError(f"for each {nid}: give a path to the list, like action_items, or none") @@ -507,6 +517,52 @@ def _check_template(nid, body): raise ValueError(f"template node {nid}: {e}") from None +def _check_entity_filter(nid, cfg): + from . import match + + for k in ("types", "skip_types"): + v = cfg.get(k) + if v is not None and (not isinstance(v, list) or not all(TYPE_RX.match(str(x)) for x in v)): + raise ValueError(f"entity filter {nid}: types are names in capitals, e.g. PERSON, ORG") + names = cfg.get("skip_names") + if names is not None and ( + not isinstance(names, list) or len(names) > MAX_NAMES or not all(isinstance(x, str) and x.strip() for x in names) + ): + raise ValueError(f"entity filter {nid}: names to skip are up to {MAX_NAMES} lines of text") + if cfg.get("pattern") is not None: + try: + match._pattern_value(cfg["pattern"]) + except ValueError as e: + raise ValueError(f"entity filter {nid}: {e}") from None + for k, hi in (("min_length", 200), ("min_mentions", 10000)): + if cfg.get(k) is not None and not _whole(cfg[k], 1, hi): + raise ValueError(f"entity filter {nid}: {k.replace('_', ' ')} is a whole number from 1 to {hi}") + + +def entity_filter(c, items): + """The entities of `items` an entity filter node keeps (its settings `c`), in their order.""" + from . import match + + ents = [x for x in items if is_entity(x)] if isinstance(items, list) else [] + keep, skip = set(c.get("types") or []), set(c.get("skip_types") or []) + stop = {analyze.ent_key(x) for x in c.get("skip_names") or []} + counts: dict[str, int] = {} + for e in ents: + counts[analyze.ent_key(e["name"])] = counts.get(analyze.ent_key(e["name"]), 0) + 1 + out = [] + for e in ents: + name, key = e["name"].strip(), analyze.ent_key(e["name"]) + said = e["mentions"] if _num(e.get("mentions")) else counts[key] + if (keep and e["type"] not in keep) or e["type"] in skip or key in stop: + continue + if len(name) < (c.get("min_length") or 1) or said < (c.get("min_mentions") or 1): + continue + if c.get("pattern") and not match._search(c["pattern"], name): + continue + out.append(e) + return out + + def _check_custom(db, kit, nid, cfg, depth, here): from . import custom_nodes @@ -675,6 +731,10 @@ def _step(run, f, node, vals, args, returned, trace): kept = [x for x in v if passes(c, x, run.extra.get("env"))] if isinstance(v, list) else [] run.say(f"{name}: kept {len(kept)}") return {"out": kept} + if t == "entity_filter": + kept = entity_filter(c, v) + run.say(f"{name}: kept {len(kept)} of {len(v) if isinstance(v, list) else 0}") + return {"out": kept} if t == "for_each": items = dig(v, c["path"]) if c.get("path") else v if items is None: diff --git a/fastapi_backend/app/domain/workflows.py b/fastapi_backend/app/domain/workflows.py index b4278bac1..ac696084e 100644 --- a/fastapi_backend/app/domain/workflows.py +++ b/fastapi_backend/app/domain/workflows.py @@ -64,7 +64,7 @@ } ENTITY_TYPES = ("PERSON", "ORG", "PRODUCT", "PLACE", "EVENT", "WORK", "TERM", "DATE", "NUMBER") PATH_RX = flow.PATH_RX -TYPE_RX = re.compile(r"^[A-Z][A-Z_]{0,30}$") +TYPE_RX = flow.TYPE_RX MAX_RULES = 500 ENTITY_SCHEMA = { "type": "object", diff --git a/fastapi_backend/tests/api/test_flow.py b/fastapi_backend/tests/api/test_flow.py index 83fcd9dc1..d5fb13243 100644 --- a/fastapi_backend/tests/api/test_flow.py +++ b/fastapi_backend/tests/api/test_flow.py @@ -1,4 +1,4 @@ -"""The workflow engine: ports, switch, set and template, loops (for each, repeat), groups, custom nodes (made of +"""The workflow engine: ports, switch, set and template, entity filters, loops (for each, repeat), groups, custom nodes (made of primitives, versioned, pinned, private or shared) and dry runs from the canvas.""" from __future__ import annotations @@ -132,6 +132,47 @@ def test_for_each_and_repeat(db, cfg, rec): flow.MAX_STEPS = old +def test_entity_filter_keeps_the_entities_asked_for(db, cfg, rec): + ents = [ + {"name": "Alice", "type": "PERSON", "seg": 0}, + {"name": "alice ", "type": "PERSON", "seg": 2}, + {"name": "Dave", "type": "PERSON", "seg": 1}, + {"name": "Q", "type": "TERM", "seg": 1}, + {"name": "Acme Corp", "type": "ORG", "mentions": 5}, + {"name": "Friday", "type": "DATE", "seg": 0}, + "not an entity", + ] + keep = lambda **c: [e["name"] for e in flow.entity_filter(c, ents)] # noqa: E731 + assert keep() == ["Alice", "alice ", "Dave", "Q", "Acme Corp", "Friday"] + assert keep(types=["PERSON", "ORG"]) == ["Alice", "alice ", "Dave", "Acme Corp"] + assert keep(skip_types=["DATE", "TERM"], skip_names=["DAVE"]) == ["Alice", "alice ", "Acme Corp"] + assert keep(min_mentions=2) == ["Alice", "alice ", "Acme Corp"] # said twice, or counted by extraction + assert keep(min_length=5, pattern="^a") == ["Alice", "alice ", "Acme Corp"] # case aside, Q too short + assert flow.entity_filter({}, "text") == [] + + # on the canvas: between extraction and saving, and checked like the rest + graph = g( + [ + node("in", "input"), + node("rules", "extract_rules", terms=["Capsid|PRODUCT"]), + node("people", "entity_filter", types=["PERSON", "PRODUCT"], skip_names=["capsid"]), + node("o", "output", key="people"), + ], + [edge("in", "rules"), edge("rules", "people"), edge("people", "o")], + ) + run(db, cfg, rec, graph) + assert {e["name"] for e in outputs(db, rec)["people"]} == {"Dave"} + for bad, said in ( + ({"types": ["person"]}, "names in capitals"), + ({"skip_names": [""]}, "lines of text"), + ({"pattern": "(a+)+"}, "repeats a part"), + ({"min_mentions": 0}, "whole number from 1"), + ): + graph["nodes"][2]["config"] = bad + with pytest.raises(ValueError, match=said): + workflows.validate_graph(db, graph) + + def test_graphs_are_checked(db): def problem(nodes, edges): with pytest.raises(ValueError) as e: diff --git a/nextjs-frontend/__tests__/workflow-flow.test.ts b/nextjs-frontend/__tests__/workflow-flow.test.ts index 9a7f5868d..cb59f7d2f 100644 --- a/nextjs-frontend/__tests__/workflow-flow.test.ts +++ b/nextjs-frontend/__tests__/workflow-flow.test.ts @@ -153,3 +153,32 @@ describe("classify", () => { ); }); }); + +describe("entity filter", () => { + const names = { template: () => undefined, field: () => undefined }; + const wf = (config: Record): WfGraph => ({ + nodes: [ + { id: "in", type: "input", config: {} }, + { id: "f", type: "entity_filter", config }, + { id: "o", type: "save_entities", config: {} }, + ], + edges: [ + { source: "in", target: "f" }, + { source: "f", target: "o" }, + ], + }); + + it("an entity filter says what it keeps and refuses lowercase types", () => { + expect(inScope("entity_filter", "recording") && inScope("entity_filter", "graph")).toBe(true); + expect(problems(wf({}), kind)).toEqual({}); + expect(problems(wf({ types: ["person"] }), kind).f).toMatch(/in capitals/); + expect(problems(wf({ min_mentions: 0 }), kind).f).toMatch(/whole numbers/); + expect( + nodeSummary( + { id: "f", type: "entity_filter", config: { types: ["PERSON"], skip_names: ["Thanks"], min_mentions: 2 } }, + names, + ), + ).toBe("PERSON · not Thanks · said 2+ times"); + expect(nodeSummary({ id: "f", type: "entity_filter", config: {} }, names)).toBe("all types"); + }); +}); diff --git a/nextjs-frontend/components/workflows/node-settings.tsx b/nextjs-frontend/components/workflows/node-settings.tsx index 7ee98c2a4..a1220b56c 100644 --- a/nextjs-frontend/components/workflows/node-settings.tsx +++ b/nextjs-frontend/components/workflows/node-settings.tsx @@ -386,6 +386,78 @@ export function NodeSettings({ )} + {node.type === "entity_filter" && ( + <> + + {({ id, describedBy }) => ( + set({ types: typesOf(e.target.value).length ? typesOf(e.target.value) : undefined })} + /> + )} + + + {({ id, describedBy }) => ( + + set({ skip_types: typesOf(e.target.value).length ? typesOf(e.target.value) : undefined }) + } + /> + )} + + String(v)} + parse={(lines) => set({ skip_names: lines.length ? lines : undefined })} + /> + + {({ id, describedBy }) => ( + set({ pattern: e.target.value || undefined })} + /> + )} + + + {({ id, describedBy }) => ( + set({ min_length: num(e.target.value) })} + /> + )} + + + {({ id, describedBy }) => ( + set({ min_mentions: num(e.target.value) })} + /> + )} + + + )} + {node.type === "extract_llm" && ( <> diff --git a/nextjs-frontend/components/workflows/workflow-model.ts b/nextjs-frontend/components/workflows/workflow-model.ts index ebcffdd38..c0ae0a1a0 100644 --- a/nextjs-frontend/components/workflows/workflow-model.ts +++ b/nextjs-frontend/components/workflows/workflow-model.ts @@ -9,6 +9,7 @@ import { CheckCheck, FileText, Group, + ListFilter, ListTree, Puzzle, Repeat, @@ -344,6 +345,18 @@ export const NODES: Record = { gives: "the items that pass", group: "Data", }, + entity_filter: { + label: "Entity filter", + describe: + "Keeps the entities of a list by type, name, length or how often they’re said, e.g. people only, without a stop list", + icon: ListFilter, + tone: "green", + inputs: 1, + outputs: ["out"], + takes: "entities[]", + gives: "the entities kept", + group: "Entities", + }, apply_changes: { label: "Apply changes", describe: "Merges or links the pairs it’s sure of and proposes the rest for someone to accept; all can be undone", @@ -380,6 +393,7 @@ export const PRIMITIVES = [ "set", "template", "filter", + "entity_filter", "for_each", "repeat", "group", @@ -791,6 +805,20 @@ export function nodeSummary( .replace(/\s+/g, " ") .slice(0, 60) + (c.json ? " · JSON" : "") ); + case "entity_filter": { + const types = (c.types as string[] | undefined) ?? []; + const skip = [ + ...((c.skip_types as string[] | undefined) ?? []), + ...((c.skip_names as string[] | undefined) ?? []), + ]; + const parts = [ + types.length ? types.join(", ") : "all types", + skip.length ? `not ${skip.slice(0, 3).join(", ")}${skip.length > 3 ? "…" : ""}` : "", + c.min_mentions ? `said ${Number(c.min_mentions)}+ times` : "", + c.pattern ? `/${String(c.pattern)}/` : "", + ]; + return parts.filter(Boolean).join(" · "); + } case "for_each": return `each of ${c.path ? String(c.path) : "the list"}${c.max_items ? ` · up to ${Number(c.max_items)}` : ""}`; case "repeat": @@ -957,6 +985,16 @@ export function problems( fail(`Start each path with an input: ${ins.join(", ")}.`); else if (ins.some((x) => !NAME_RX.test(x))) fail("Input names are lowercase letters, digits and _."); } else if (n.type === "template" && !String(c.template ?? "").trim()) fail("Write the template."); + else if ( + n.type === "entity_filter" && + [c.types, c.skip_types].some((v) => ((v as string[] | undefined) ?? []).some((x) => !TYPE_RX.test(x))) + ) + fail("Types are names in capitals, e.g. PERSON, ORG."); + else if ( + n.type === "entity_filter" && + [c.min_length, c.min_mentions].some((v) => v != null && (!Number.isInteger(v) || Number(v) < 1)) + ) + fail("Counts are whole numbers from 1."); else if (n.type === "ask_model" && !String(c.prompt ?? "").trim()) fail("Write its prompt."); else if (n.type === "call_tool" && !/^[a-z][a-z0-9_]{1,40}$/.test(String(c.tool ?? ""))) fail("Name the tool it calls.");