From 9273d5ce83b487f3c2e8cafadd2bb645d9a7cbff Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 11:45:04 +0000 Subject: [PATCH 1/2] feat(workflows): a classify node on the canvas A Classify node picks one of your labels, a content type or a topic for the recording (or for what came in) and passes on the choice, how sure and every label ranked; set to act, a sure answer sets the content type, suggests the topic or adds the tag, so the node keeps something by itself. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01GKv2oVRvFRdiSf4USLsM1N --- CHANGELOG.md | 4 ++ docs/processing.md | 17 +++-- fastapi_backend/app/domain/workflows.py | 58 +++++++++++++++- fastapi_backend/tests/api/test_classify.py | 53 ++++++++++++++ .../__tests__/workflow-flow.test.ts | 30 ++++++++ .../components/workflows/node-settings.tsx | 69 +++++++++++++++++++ .../components/workflows/workflow-model.ts | 44 +++++++++++- 7 files changed, 264 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a480174bb..ed591d3f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -74,6 +74,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version language model, logged in the activity ledger; with `apply`, an editor's sure answer sets the content type, suggests the topic or adds the tag (`POST /classify`, the MCP and assistant tool `classify`; [Classifying](docs/processing.md#classifying)). +- **Classify in workflows.** A Classify node on the workflow canvas picks one of your labels, a content type or a topic + for the asset (or for what came in) and passes on the choice, how sure and every label ranked, for a Condition + or Switch to branch on; set to act, a sure answer sets the content type, suggests the topic or adds the tag + ([Workflows and the canvas](docs/processing.md#workflows-and-the-canvas)). ## 0.13.0 October 16, 2026 {id="0.13.0"} diff --git a/docs/processing.md b/docs/processing.md index 17b4d2392..5685b9b0c 100644 --- a/docs/processing.md +++ b/docs/processing.md @@ -362,7 +362,9 @@ does), the topic is suggested for it, waiting for someone to accept it (one it a from stays as it is), or the label given is added as a tag (at most 40 characters). `applied` says which, and it is in the audit log. The MCP and assistant tools never apply; the assistant can then suggest the topic (`suggest_topic`). -Planned, not built yet: a classify step in workflows, classifying many assets at once, and labels with examples. +Workflows classify too, with a Classify node ([Workflows and the canvas](#workflows-and-the-canvas)), so a pipeline +can classify every asset it runs on. Planned, not built yet: classifying many assets at once from the API, and labels +with examples. ## Background work @@ -593,11 +595,14 @@ node passes what it makes along its connections. 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. -- **AI and logic:** LLM prompt (a prompt template, with what came in as `{{ input }}`), Pick (a path like - `action_items.0.text`), Condition (yes and no branches; one test, or a [match tree](automations.md#match-trees) of - several) and Merge. -- **Keeping results:** Save output (`outputs.`), Set field (a custom field, kept in the metadata history) and - Save entities. +- **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 + (a path like `action_items.0.text`), Condition (yes and no branches; one test, or a + [match tree](automations.md#match-trees) of several) and Merge. +- **Keeping results:** Save output (`outputs.`), Set field (a custom field, kept in the metadata history), Save + entities, and a Classify node set to act on a sure answer (it sets the content type, suggests the topic or adds the + tag; a try on the canvas only says what it would do). A pipeline runs a workflow as a Workflow step, pinned to the workflow's published version when the run is queued (`POST /api/v1/workflows/{id}/run` runs one on an asset). Pipelines can be drawn on the canvas too: a connection diff --git a/fastapi_backend/app/domain/workflows.py b/fastapi_backend/app/domain/workflows.py index 3f0b07474..d6957eb39 100644 --- a/fastapi_backend/app/domain/workflows.py +++ b/fastapi_backend/app/domain/workflows.py @@ -16,6 +16,9 @@ - `field`: sets a custom field of the recording to the value, checked like an edit (and kept in its history). - `save_entities`: makes the entities passed in the recording's entities (in place of what analyze found), with people's corrections kept, then redoes keywords and sections as analyze does. +- `classify`: which of some labels (or the content types, or the namespace's topics) fits the asset, or what came + in as text, as classify.py says: passes on {choice, confidence, sure, ranked, by}. With `apply` it acts on a sure + answer (sets the content type, suggests the topic, adds the tag), so it keeps something. Positions are only for the canvas. @@ -26,11 +29,14 @@ from __future__ import annotations +import json import re from . import ( analyze, automation_nodes, + classify as classifymod, + decide, fields as fieldmod, flow, llm, @@ -44,7 +50,7 @@ ) R = store.R -OWN_NODES = ("llm", "extract_rules", "extract_llm", "output", "field", "save_entities") +OWN_NODES = ("llm", "extract_rules", "extract_llm", "classify", "output", "field", "save_entities") TERMINAL = {"output", "field", "save_entities", "apply_changes"} OPS = flow.OPS OWN_CONFIG = { @@ -54,6 +60,7 @@ "output": {"key"}, "field": {"field"}, "save_entities": set(), + "classify": {"labels", "vocabulary", "question", "of", "apply"}, } ENTITY_TYPES = ("PERSON", "ORG", "PRODUCT", "PLACE", "EVENT", "WORK", "TERM", "DATE", "NUMBER") PATH_RX = flow.PATH_RX @@ -131,6 +138,29 @@ def _check_config(db, nid, t, cfg): fieldmod.get(db, int(cfg.get("field") or 0)) except (KeyError, TypeError, ValueError): raise ValueError(f"field node {nid}: choose a custom field") from None + elif t == "classify": + _check_classify(nid, cfg) + + +def _check_classify(nid, cfg): + labels, vocab = cfg.get("labels"), cfg.get("vocabulary") + if (labels is None) == (vocab is None): + raise ValueError(f"classify node {nid}: give labels, or choose content types or topics") + try: + if vocab is not None and vocab not in classifymod.VOCABULARIES: + raise ValueError(f"choose from {' or '.join(classifymod.VOCABULARIES)}") + if labels is not None: + if not isinstance(labels, list): + raise ValueError("labels are lines like science: research and medicine") + classifymod._labels(labels) + except ValueError as e: + raise ValueError(f"classify node {nid}: {e}") from None + if cfg.get("question") is not None and not isinstance(cfg["question"], str): + raise ValueError(f"classify node {nid}: the question is text") + if cfg.get("of", "resource") not in ("resource", "input"): + raise ValueError(f"classify node {nid}: it classifies the asset or what comes in") + if cfg.get("apply") and cfg.get("of") == "input": + raise ValueError(f"classify node {nid}: only the asset's classification can be acted on") def _check_types(nid, cfg): @@ -366,6 +396,8 @@ def _run_node(r, f, node, value, vals): if after != (row.get("fields") or {}): metadata.save_fields(db, cfg, rid, after, r.extra["by"]) r.say(f"set {fd['label']}") + elif t == "classify": + return {"out": _classify(r, c, upstream, name)} elif t == "save_entities": if not isinstance(value, list): raise ValueError(f"{name}: needs a list of entities") @@ -376,6 +408,27 @@ def _run_node(r, f, node, value, vals): return {} +def _classify(r, c, upstream, name): + """A classify node: the asset, or what came in as text.""" + rid, text, space = r.extra["rid"], None, None + if c.get("of") == "input": # its topics are the recording's namespace's + text = upstream if isinstance(upstream, str) else json.dumps(upstream, ensure_ascii=False, default=str) + rid, space = None, r.db.values("SELECT VALUE space FROM $r", r=R("recording", int(rid)))[0] + try: + res = classifymod.classify( + r.db, r.cfg, rid=rid, text=text, labels=c.get("labels"), vocab=c.get("vocabulary"), question=c.get("question"), + apply=bool(c.get("apply")) and not r.dry, user=r.extra.get("by"), space=space, + ) # fmt: skip + except decide.Undecided as e: + raise ValueError(f"{name}: nothing could answer ({e})") from None + sure = f"{round(res['confidence'] * 100)}% sure" + if c.get("apply") and r.dry and res["sure"]: + r.say(f"{name}: {res['choice']} ({sure}); would act on it") + else: + r.say(f"{name}: {res['choice']} ({sure}){'; ' + res['applied'].replace('_', ' ') if res['applied'] else ''}") + return {k: v for k, v in res.items() if k not in ("vocabulary", "question", "applied") and v is not None} + + RUN_BY = {"graph": "organises the graph; a routine runs it", "event": "is what an automation does; its automation runs it"} @@ -441,7 +494,8 @@ def _fit(f, v): KITS = { "recording": flow.Kit( "recording", OWN_NODES, OWN_CONFIG, _check_config, _run_node, TERMINAL - {"apply_changes"}, - "a workflow needs an output, field or save entities node, or it keeps nothing", + "a workflow needs an output, field or save entities node (or a classify node that acts), or it keeps nothing", + keeps=lambda n: n["type"] == "classify" and bool((n.get("config") or {}).get("apply")), ), "graph": flow.Kit( "graph", organize.OWN_NODES, organize.CONFIG, _check_config, organize.run_node, {"apply_changes"}, diff --git a/fastapi_backend/tests/api/test_classify.py b/fastapi_backend/tests/api/test_classify.py index 23fe170f1..e796020a4 100644 --- a/fastapi_backend/tests/api/test_classify.py +++ b/fastapi_backend/tests/api/test_classify.py @@ -173,3 +173,56 @@ def test_agents_classify(client, db, cfg, env, jev): assert summary == "Classified as science (70% sure)" and got["sure"] is False with pytest.raises(ValueError, match="isn't available"): box.t_classify(recording_id=env["call"], labels=["a", "b"]) + + +def test_a_workflow_classifies(client, db, cfg, env, jev): + from app.domain import workflows + + ep2 = env["ep2"] + + def node(nid, t, **config): + return {"id": nid, "type": t, "config": config} + + def graph(*nodes): + return {"nodes": [node("in", "input"), *nodes], "edges": [{"source": a["id"], "target": b["id"]} for a, b in zip( + [node("in", "input"), *nodes], nodes, strict=False + )]} # fmt: skip + + # what it passes on goes on to the next node; one that acts on a sure answer keeps something by itself + desk = node("c", "classify", labels=["security: exploits and attacks", "health"], question="Which desk?") + wid = workflows.create(db, "Desk", graph(desk, node("o", "output", key="desk"))) + jev.answer = {"type": "choice", "choice": "security", "confidence": 0.9, "probabilities": {"security": 0.9, "health": 0.1}} + said = [] + workflows.run(db, cfg, ep2, wid, say=said.append) + out = db.one("SELECT * FROM $o", o=R("output", f"{ep2}-desk"))["value"] + assert (out["choice"], out["sure"], out["by"]) == ("security", True, "jev") and [x["label"] for x in out["ranked"]] == [ + "security", + "health", + ] + assert "Which desk?" == jev.seen[-1][1]["questions"]["q"]["instructions"] and any("security (90% sure)" in s for s in said) + acts = node("c", "classify", vocabulary="topic", apply=True) + wid = workflows.create(db, "Topics", graph(acts)) + jev.answer = {"type": "choice", "choice": "Gene therapy", "confidence": 0.9, "probabilities": {"Gene therapy": 0.9}} + # a try keeps nothing + tried = workflows.try_graph(db, cfg, graph(acts), rid=ep2) + assert tried["error"] is None and any("would act on it" in s for s in tried["log"]) + assert not [t for t in topics.of_recording(db, ep2) if t["source"] == "classify"] + workflows.run(db, cfg, ep2, wid) + assert [(t["label"], t["status"]) for t in topics.of_recording(db, ep2) if t["source"] == "classify"] == [("Gene therapy", "suggested")] + # what came in, as text + text = node("c", "classify", labels=["question", "statement"], of="input") + tried = workflows.try_graph( + db, cfg, graph(node("t", "template", template="Is it on Friday?"), text, node("o", "output", key="k")), rid=ep2 + ) + assert tried["error"] is None and "Is it on" in json.loads(jev.seen[-1][1]["state"])["text"] + # checked when saved + for bad, why in ( + (node("c", "classify"), "give labels"), + (node("c", "classify", labels=["one"]), "at least two"), + (node("c", "classify", vocabulary="colour"), "content_type or topic"), + (node("c", "classify", vocabulary="topic", of="input", apply=True), "only the asset"), + ): + with pytest.raises(ValueError, match=why): + workflows.create(db, "Bad", graph(bad, node("o", "output", key="k"))) + with pytest.raises(ValueError, match="keeps nothing"): + workflows.create(db, "Keeps nothing", graph(node("c", "classify", vocabulary="topic"))) diff --git a/nextjs-frontend/__tests__/workflow-flow.test.ts b/nextjs-frontend/__tests__/workflow-flow.test.ts index dc72c2bf4..9a7f5868d 100644 --- a/nextjs-frontend/__tests__/workflow-flow.test.ts +++ b/nextjs-frontend/__tests__/workflow-flow.test.ts @@ -7,6 +7,7 @@ import { portsOf, problems, inScope, + nodeSummary, replaceSelection, starterTool, withBody, @@ -123,3 +124,32 @@ describe("tool graphs", () => { expect(problems(recording, () => undefined, "tool", "custom").keep).toBe("This node isn’t for tools."); }); }); + +describe("classify", () => { + const names = { template: () => undefined, field: () => undefined }; + const wf = (config: Record, keep = true): WfGraph => ({ + nodes: [ + { id: "in", type: "input", config: {} }, + { id: "c", type: "classify", config }, + ...(keep ? [{ id: "o", type: "output", config: { key: "desk" } }] : []), + ], + edges: [{ source: "in", target: "c" }, ...(keep ? [{ source: "c", target: "o" }] : [])], + }); + + it("chooses from labels, content types or topics, and acting on a sure answer keeps something", () => { + expect(inScope("classify", "recording")).toBe(true); + expect(inScope("classify", "graph")).toBe(false); + expect(problems(wf(defaultConfig("classify")), kind)).toEqual({}); + expect(problems(wf({}), kind).c).toMatch(/Give labels/); + expect(problems(wf({ labels: ["a: one", "a: two"] }), kind).c).toMatch(/at least two/); + expect(problems(wf({ vocabulary: "topic", of: "input", apply: true }), kind).c).toMatch(/Only the asset/); + expect(problems(wf({ vocabulary: "topic" }, false), kind)[""]).toMatch(/keeps nothing/); + expect(problems(wf({ vocabulary: "topic", apply: true }, false), kind)).toEqual({}); + expect(nodeSummary({ id: "c", type: "classify", config: { labels: ["security: attacks", "health"] } }, names)).toBe( + "security, health", + ); + expect(nodeSummary({ id: "c", type: "classify", config: { vocabulary: "topic", apply: true } }, names)).toBe( + "The namespace’s topics · acts when sure", + ); + }); +}); diff --git a/nextjs-frontend/components/workflows/node-settings.tsx b/nextjs-frontend/components/workflows/node-settings.tsx index 94ac13ef2..7ee98c2a4 100644 --- a/nextjs-frontend/components/workflows/node-settings.tsx +++ b/nextjs-frontend/components/workflows/node-settings.tsx @@ -6,6 +6,7 @@ import type { FieldDef, TemplateSummary } from "@/app/openapi-client/types.gen"; import { FlowSettings } from "@/components/workflows/flow-settings"; import { OPS, + VOCABULARIES, infoFor, paramRef, type BodyKind, @@ -423,6 +424,74 @@ export function NodeSettings({ )} + {node.type === "classify" && ( + <> + + {({ id, describedBy }) => ( + set({ question: e.target.value || undefined })} + /> + )} + + + {({ id, describedBy }) => ( +