Skip to main content

Cluster generation workflow step

Motivation​

Cluster Sets are now standalone entities and cluster generation no longer needs to be owned by an AI query. Workflows should be able to create Cluster Sets directly so clustering can be composed with other workflow steps and reused outside chat.

Workflow step​

The clusterSet.create workflow action:

  • accepts exactly one memories datasource, a clustering prompt, and an optional title;
  • creates one pending ClusterSet with auto_process: true;
  • waits for carrot-ai to process and quantify it;
  • completes when the ClusterSet is quantified, or fails when it is failed;
  • returns the ClusterSet ID plus small summary metadata such as title, cluster count, memory count, and account coverage on completion.

The step must not create an AiQuery or chat, duplicate clustering logic in carrot-automations, return sample memories or the full cluster payload, or split generation and quantification into separate workflow steps.

Implementation boundary​

carrot-automations owns the workflow step contract and creates a pending ClusterSet with auto_process: true. created_by_workflow_id records the workflow definition that created it. The separate workflow trigger data stores the execution and step IDs needed to resume that exact step. The ClusterSet insert requests the asynchronous carrot-ai processor, which owns cluster generation and quantification.

The step initially returns a running result with the ClusterSet ID. Terminal ClusterSet events resume the workflow and expose lightweight summary metadata. This keeps ClusterSet as the first-class artifact and avoids reintroducing an AiQuery dependency solely to trigger clustering.