docs: add workflow automation recipes #12
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Workflow automation integrations | ||
|
|
||
| Use Neuron-JS when workflow automation needs a deterministic decision node instead of probabilistic LLM branching. | ||
|
|
||
| The pattern is simple: | ||
|
|
||
| 1. A workflow tool gathers, extracts, or classifies data. | ||
| 2. Neuron-JS validates the JSON rule script with `validateScript`. | ||
| 3. Neuron-JS validates the execution context with `validateExecutionContext`. | ||
| 4. `Synapse` executes approved rules through a developer-owned `Neuron` registry. | ||
| 5. The workflow routes side effects from `summarizeExecutionOutput` and `explainExecution`. | ||
|
|
||
| ## Recipes | ||
|
|
||
| - [n8n deterministic workflow routing](./n8n.md) | ||
| - [LangGraph deterministic decision node](./langgraph.md) | ||
|
|
||
| ## Use Neuron-JS when | ||
|
|
||
| - Business rules must be represented as JSON and executed deterministically. | ||
| - Rules need to be stored in a database, versioned, transmitted, or audited. | ||
| - An AI assistant generates rules and you need schema validation before execution. | ||
| - Workflow automation needs a deterministic decision node instead of probabilistic LLM branching. | ||
| - You need explanation traces for why a rule matched or failed. | ||
|
|
||
| ## Do not use Neuron-JS when | ||
|
|
||
| - A simple hard-coded condition is clearer and rarely changes. | ||
| - Arbitrary user code execution is required. | ||
| - A full BPMN/process engine is required. | ||
| - Non-technical users need unrestricted rule authoring without validation, tests, review, and rollback. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| # Use Neuron-JS as a LangGraph deterministic node | ||
|
|
||
| Neuron-JS fits LangGraph workflows that need LLM extraction followed by a deterministic Neuron-JS decision. | ||
|
|
||
| Target use cases: LangGraph deterministic node, deterministic guardrails for AI agents, validate LLM generated JSON rules, rules engine for AI agents. | ||
|
|
||
| ## Runnable example | ||
|
|
||
| Repository folder: [`examples/langgraph-decision-node/`](https://github.com/SebaSOFT/neuron-js/tree/main/examples/langgraph-decision-node) | ||
|
|
||
| ```bash | ||
| yarn build | ||
| node examples/langgraph-decision-node/run.ts | ||
| ``` | ||
|
|
||
| ## Pattern | ||
|
|
||
| 1. The LLM extracts/classifies structured data. | ||
| 2. LangGraph writes that structured data into graph state. | ||
| 3. Neuron-JS validates the rule script with `validateScript`. | ||
| 4. Neuron-JS validates the generated context with `validateExecutionContext`. | ||
| 5. Neuron-JS executes approved rules and returns `summarizeExecutionOutput` plus `explainExecution`. | ||
| 6. LangGraph routes the next edge from the deterministic output, not free-form LLM text. | ||
|
|
||
| ## Copy-paste node shape | ||
|
|
||
| ```typescript | ||
| import { | ||
| Neuron, | ||
| Synapse, | ||
| explainExecution, | ||
| summarizeExecutionOutput, | ||
| validateExecutionContext, | ||
| validateScript, | ||
| } from '@sebasoft/neuron-js'; | ||
|
|
||
| export async function neuronDecisionNode(state) { | ||
| const context = { | ||
| messages: [], | ||
| state: { classification: state.llmClassification }, | ||
| }; | ||
|
|
||
| const scriptValidation = validateScript(state.rules); | ||
| const contextValidation = validateExecutionContext(context); | ||
|
|
||
| if (!scriptValidation.ok || !contextValidation.ok) { | ||
| return { ...state, neuronDecision: { ok: false, errors: [...scriptValidation.errors, ...contextValidation.errors] } }; | ||
| } | ||
|
|
||
| const result = new Synapse(new Neuron()).execute(state.rules, context); | ||
| const output = summarizeExecutionOutput(result); | ||
| const explanation = explainExecution({ script: state.rules, result }); | ||
|
|
||
| return { | ||
| ...state, | ||
| neuronDecision: output, | ||
| neuronExplanation: explanation, | ||
| nextNode: result.context.state.workflow?.nextNode, | ||
| }; | ||
| } | ||
| ``` | ||
|
|
||
| Expected local output: | ||
|
|
||
| ```json | ||
| { | ||
| "ok": true, | ||
| "rulesExecuted": 1, | ||
| "nextNode": "refund-human-review", | ||
| "requiresApproval": true | ||
| } | ||
| ``` | ||
|
|
||
| ## Boundary | ||
|
|
||
| Use Neuron-JS when AI-generated or LLM-classified input needs deterministic guardrails. Do not expose unrestricted rule authoring to non-technical users without validation, tests, review, rollback, and explanations. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,59 @@ | ||||||
| # Use Neuron-JS in n8n for deterministic workflow routing | ||||||
|
|
||||||
| Neuron-JS can act as an n8n rules engine, n8n decision routing step, workflow automation decision engine, or workflow routing rules layer. | ||||||
|
|
||||||
| The value is deterministic workflow routing. n8n keeps orchestration and side effects. Neuron-JS validates and executes a JSON decision contract. | ||||||
|
|
||||||
| ## Runnable example | ||||||
|
|
||||||
| Repository folder: [`examples/n8n-code-node/`](https://github.com/SebaSOFT/neuron-js/tree/main/examples/n8n-code-node) | ||||||
|
|
||||||
| ```bash | ||||||
| yarn build | ||||||
| node examples/n8n-code-node/run.ts | ||||||
| ``` | ||||||
|
|
||||||
| ## Validation-first flow | ||||||
|
|
||||||
| ```typescript | ||||||
| import { | ||||||
| Neuron, | ||||||
| Synapse, | ||||||
| explainExecution, | ||||||
| summarizeExecutionOutput, | ||||||
| validateExecutionContext, | ||||||
| validateScript, | ||||||
| } from '@sebasoft/neuron-js'; | ||||||
|
|
||||||
| const scriptValidation = validateScript(script); | ||||||
| const contextValidation = validateExecutionContext(context); | ||||||
|
|
||||||
| if (!scriptValidation.ok || !contextValidation.ok) { | ||||||
| return [{ json: { ok: false, errors: [...scriptValidation.errors, ...contextValidation.errors] } }]; | ||||||
|
Contributor
There was a problem hiding this comment. If only one of the validations fails (e.g.,
Suggested change
|
||||||
| } | ||||||
|
|
||||||
| const result = new Synapse(new Neuron()).execute(script, context); | ||||||
| const output = summarizeExecutionOutput(result); | ||||||
| const explanation = explainExecution({ script, result }); | ||||||
|
|
||||||
| return [{ json: { ...output, explanation } }]; | ||||||
| ``` | ||||||
|
|
||||||
| ## Code node recipe | ||||||
|
|
||||||
| In self-hosted/custom n8n environments where external modules are allowed, install `@sebasoft/neuron-js` and use a Code node to execute the validated rule script. Keep credentials, HTTP requests, Slack messages, and database writes in normal n8n nodes after the deterministic route is returned. | ||||||
|
|
||||||
| Expected local output: | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "ok": true, | ||||||
| "rulesExecuted": 1, | ||||||
| "route": "human-escalation", | ||||||
| "slaHours": 2 | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ## Boundary | ||||||
|
|
||||||
| Use Neuron-JS when workflow automation needs a deterministic decision node instead of probabilistic LLM branching. Do not use it as arbitrary business-user code execution or a full workflow engine. Use controlled rule vocabulary, validation, tests, review, audit, rollback, and explanations. | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If only one of the validations fails (e.g.,
scriptValidation.okistruebutcontextValidation.okisfalse), thenscriptValidation.errorswill beundefined. Attempting to spreadundefinedusing the spread operator (...scriptValidation.errors) will throw a runtimeTypeError: Spread syntax requires all elements to be iterable. Use the nullish coalescing operator (?? []) to safely default to an empty array.