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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions docs/processing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
64 changes: 62 additions & 2 deletions fastapi_backend/app/domain/flow.py
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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(),
Expand All @@ -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"},
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion fastapi_backend/app/domain/workflows.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
43 changes: 42 additions & 1 deletion fastapi_backend/tests/api/test_flow.py
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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:
Expand Down
29 changes: 29 additions & 0 deletions nextjs-frontend/__tests__/workflow-flow.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -153,3 +153,32 @@ describe("classify", () => {
);
});
});

describe("entity filter", () => {
const names = { template: () => undefined, field: () => undefined };
const wf = (config: Record<string, unknown>): 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");
});
});
72 changes: 72 additions & 0 deletions nextjs-frontend/components/workflows/node-settings.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -386,6 +386,78 @@ export function NodeSettings({
</>
)}

{node.type === "entity_filter" && (
<>
<Field label="Keep only these types" optional hint="e.g. PERSON, ORG; empty keeps every type">
{({ id, describedBy }) => (
<Input
id={id}
aria-describedby={describedBy}
mono
defaultValue={typesText(c.types)}
onChange={(e) => set({ types: typesOf(e.target.value).length ? typesOf(e.target.value) : undefined })}
/>
)}
</Field>
<Field label="Leave out these types" optional hint="e.g. DATE, NUMBER">
{({ id, describedBy }) => (
<Input
id={id}
aria-describedby={describedBy}
mono
defaultValue={typesText(c.skip_types)}
onChange={(e) =>
set({ skip_types: typesOf(e.target.value).length ? typesOf(e.target.value) : undefined })
}
/>
)}
</Field>
<Lines
label="Leave out these names"
hint="One per line; case and spacing don’t matter"
placeholder={"Thanks\nOkay"}
value={(c.skip_names as string[] | undefined) ?? []}
show={(v) => String(v)}
parse={(lines) => set({ skip_names: lines.length ? lines : undefined })}
/>
<Field label="Name matches" optional hint="A regular expression, case aside, e.g. ^[A-Z] or corp|inc">
{({ id, describedBy }) => (
<Input
id={id}
aria-describedby={describedBy}
mono
value={String(c.pattern ?? "")}
onChange={(e) => set({ pattern: e.target.value || undefined })}
/>
)}
</Field>
<Field label="At least this long" optional hint="Characters in the name">
{({ id, describedBy }) => (
<Input
id={id}
aria-describedby={describedBy}
type="number"
min={1}
value={c.min_length == null ? "" : String(c.min_length)}
onChange={(e) => set({ min_length: num(e.target.value) })}
/>
)}
</Field>
<Field label="Said at least" optional hint="Times: its mentions, else how often the list names it">
{({ id, describedBy }) => (
<Input
id={id}
aria-describedby={describedBy}
type="number"
min={1}
value={c.min_mentions == null ? "" : String(c.min_mentions)}
onChange={(e) => set({ min_mentions: num(e.target.value) })}
/>
)}
</Field>
</>
)}

{node.type === "extract_llm" && (
<>
<Field label="Types" optional hint="What to look for, e.g. PERSON, ORG, PRODUCT; empty for all">
Expand Down
38 changes: 38 additions & 0 deletions nextjs-frontend/components/workflows/workflow-model.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import {
CheckCheck,
FileText,
Group,
ListFilter,
ListTree,
Puzzle,
Repeat,
Expand Down Expand Up @@ -344,6 +345,18 @@ export const NODES: Record<string, Info> = {
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",
Expand Down Expand Up @@ -380,6 +393,7 @@ export const PRIMITIVES = [
"set",
"template",
"filter",
"entity_filter",
"for_each",
"repeat",
"group",
Expand Down Expand Up @@ -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":
Expand Down Expand Up @@ -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.");
Expand Down
Loading