@cascadeflow/n8n-nodes-cascadeflow 0.6.6 → 0.7.0

package/README.md

@@ -16,7 +16,9 @@
 
 </div>
 
-**Intelligent AI model cascading for n8n workflows.**
+**Intelligent AI model cascading for n8n workflows with domain understanding.**
+
+![cascadeflow Domain Routing](../../../.github/assets/n8n-CF-domains.jpg)
 
 This is an n8n community node that brings cascadeflow's intelligent AI model cascading to n8n workflows.
 
@@ -26,9 +28,9 @@ This is an n8n community node that brings cascadeflow's intelligent AI model cas
 
 ## How It Works
 
-The CascadeFlow node is a **Language Model sub-node** that sits between your AI models and downstream n8n nodes (like Basic LLM Chain, Chain, or any node that accepts Language Model inputs):
+The cascadeflow node is a **Language Model sub-node** that sits between your AI models and downstream n8n nodes (like Basic LLM Chain, Chain, or any node that accepts Language Model inputs):
 
-![CascadeFlow n8n Workflow](../../../.github/assets/n8n-CF.png)
+![cascadeflow n8n Workflow](../../../.github/assets/n8n-CF.png)
 
 **Architecture:**
 
@@ -39,7 +41,7 @@ The CascadeFlow node is a **Language Model sub-node** that sits between your AI
 └──────┬──────┘
        │
        ├──────► ┌──────────────┐
-       │        │  CascadeFlow │
+       │        │  cascadeflow │
        │        │     Node     │ ────► ┌──────────────┐
        │        └──────────────┘       │ Basic Chain  │
        ├──────► Quality checks         │ Chain        │
@@ -53,13 +55,13 @@ The CascadeFlow node is a **Language Model sub-node** that sits between your AI
 
 **Flow:**
 1. Query goes to cheap drafter model first
-2. CascadeFlow validates the response quality
+2. cascadeflow validates the response quality
 3. If quality passes → return drafter response (fast + cheap ✅)
 4. If quality fails → escalate to verifier model (slower but accurate ⚠️)
 
 **Result:** 70-80% of queries accept the drafter, saving 40-85% on costs.
 
-> **ℹ️ Note:** CascadeFlow works with n8n Chain nodes but **not with AI Agent nodes**, as n8n only allows whitelisted models for Agent inputs. Use with Basic LLM Chain, Chain, or other nodes that accept Language Model connections.
+> **ℹ️ Note:** Use **CascadeFlow (Model)** with n8n Chain/LLM nodes, and **CascadeFlow Agent** for agent workflows (tool calling + multi-step). The Agent node adds trace metadata and supports tool routing.
 
 ## Installation
 
@@ -94,15 +96,15 @@ RUN cd /usr/local/lib/node_modules/n8n && npm install @cascadeflow/n8n-nodes-cas
    - Configure one as your **drafter** (cheap model like `gpt-4o-mini` or `claude-3-5-haiku-20241022`)
    - Configure one as your **verifier** (powerful model like `gpt-4o` or `claude-3-5-sonnet-20241022`)
 
-2. **Add the CascadeFlow node**
+2. **Add the cascadeflow node**
    - Connect the drafter model to the **Drafter** input
    - Connect the verifier model to the **Verifier** input
-   - Adjust the **Quality Threshold** (default: 0.7)
+   - Optionally adjust the **Quality Threshold** (default: 0.4, and per-complexity thresholds are enabled by default)
 
 3. **Connect to a Chain node**
-   - The CascadeFlow node outputs a Language Model connection
+   - The cascadeflow node outputs a Language Model connection
    - Connect it to nodes that accept AI models (Basic LLM Chain, Chain, etc.)
-   - **Note:** Does not work with AI Agent nodes (n8n limitation)
+   - For agent workflows, use the **CascadeFlow Agent** node (connect tools to its `Tools` input).
 
 ### Example Workflow
 
@@ -115,10 +117,10 @@ RUN cd /usr/local/lib/node_modules/n8n && npm install @cascadeflow/n8n-nodes-cas
          v
 ┌──────────────────┐       ┌──────────────────┐
 │  OpenAI Model    │──────►│                  │
-│  gpt-4o-mini     │       │  CascadeFlow     │       ┌──────────────────┐
+│  gpt-4o-mini     │       │  cascadeflow     │       ┌──────────────────┐
 └──────────────────┘       │  Node            │──────►│ Basic LLM Chain  │
                            │                  │       │                  │
-┌──────────────────┐       │  Threshold: 0.7  │       └──────────────────┘
+┌──────────────────┐       │  Threshold: 0.4  │       └──────────────────┘
 │  OpenAI Model    │──────►│                  │
 │  gpt-4o          │       └──────────────────┘
 └──────────────────┘
@@ -130,28 +132,86 @@ RUN cd /usr/local/lib/node_modules/n8n && npm install @cascadeflow/n8n-nodes-cas
 
 #### Quality Threshold (0-1)
 
-Controls how aggressively to accept drafter responses:
+Controls how aggressively to accept drafter responses when **Use Complexity Thresholds** is disabled.
+
+Defaults to **0.4** to match the `simple` tier in CascadeFlow's default per-complexity thresholds.
 
-- **0.5-0.6**: Very aggressive (maximum cost savings, ~80-90% acceptance)
-- **0.7** (default): Balanced (good quality + savings, ~70-80% acceptance)
-- **0.8-0.9**: Conservative (highest quality, ~50-60% acceptance)
+If you enable **Use Complexity Thresholds** (default), acceptance is driven by:
+- trivial: 0.25
+- simple: 0.4
+- moderate: 0.55
+- hard: 0.7
+- expert: 0.8
 
 Lower threshold = more cost savings, higher threshold = better quality assurance.
 
+## Multi-Domain Cascading (Optional)
+
+cascadeflow supports **intelligent domain-specific cascading** - automatically detecting the type of query and routing it to a specialized model for that domain.
+
+### How It Works
+
+1. **Enable Domain Cascading** in the node settings
+2. **Toggle individual domains** you want to support
+3. **Connect domain-specific models** to the new input ports that appear
+
+When a query comes in, cascadeflow:
+1. Detects the domain (e.g., "Write a Python function" → Code domain)
+2. Routes to the specialized model for that domain (if connected)
+3. Falls back to drafter → verifier cascade if no domain model is available
+
+### Supported Domains
+
+| Domain | Description | Example Queries |
+|--------|-------------|-----------------|
+| **Code** | Programming, debugging, code generation | "Write a Python function...", "Debug this code..." |
+| **Math** | Mathematical reasoning, calculations, proofs | "Solve this equation...", "Prove that..." |
+| **Data** | Data analysis, statistics, pandas/SQL | "Analyze this dataset...", "Write a SQL query..." |
+| **Creative** | Creative writing, stories, poetry | "Write a short story...", "Compose a poem..." |
+| **Legal** | Legal documents, contracts, regulations | "Draft a contract...", "Explain this law..." |
+| **Medical** | Healthcare, medical knowledge, clinical | "What are the symptoms of...", "Explain this diagnosis..." |
+| **Financial** | Finance, accounting, investment analysis | "Analyze this stock...", "Calculate ROI..." |
+| **Science** | Scientific knowledge, research, experiments | "Explain quantum...", "How does photosynthesis..." |
+
+### Setup Example
+
+```
+┌──────────────────┐
+│  Claude Haiku    │──► Drafter (default cheap model)
+└──────────────────┘
+┌──────────────────┐
+│  GPT-4o          │──► Verifier (default powerful model)
+└──────────────────┘
+┌──────────────────┐         ┌──────────────────┐
+│  DeepSeek Coder  │──► Code │                  │
+└──────────────────┘         │                  │
+┌──────────────────┐         │   cascadeflow    │──► Chain
+│  Qwen Math       │──► Math │      Node        │
+└──────────────────┘         │                  │
+┌──────────────────┐         │                  │
+│  Claude Sonnet   │──► Legal│                  │
+└──────────────────┘         └──────────────────┘
+```
+
+### When to Use Domain Cascading
+
+- **Use it when**: You have domain-specific models that excel in certain areas (e.g., DeepSeek for code, specialized medical models)
+- **Skip it when**: Your drafter/verifier combination handles all domains well enough
+
 ## Flow Visualization
 
 ### Viewing Cascade Decisions in Real-Time
 
-CascadeFlow provides detailed logging of every cascade decision in n8n's UI:
+cascadeflow provides detailed logging of every cascade decision in n8n's UI:
 
-1. **Execute your workflow** with the CascadeFlow node
-2. **Click on the downstream Chain node** after execution (the node that receives CascadeFlow output)
+1. **Execute your workflow** with the cascadeflow node
+2. **Click on the downstream Chain node** after execution (the node that receives cascadeflow output)
 3. **Navigate to the "Logs" tab**
 
 You'll see detailed flow information like:
 
 ```
-🎯 CascadeFlow: Trying drafter model...
+🎯 cascadeflow: Trying drafter model...
    📊 Quality validation: confidence=0.85, method=heuristic
    🎯 Alignment: 0.82
 
@@ -170,7 +230,7 @@ You'll see detailed flow information like:
 Or when escalating:
 
 ```
-🎯 CascadeFlow: Trying drafter model...
+🎯 cascadeflow: Trying drafter model...
    📊 Quality validation: confidence=0.62, method=heuristic
 
 ┌────────────────────────────────────────────────┐
@@ -241,7 +301,7 @@ Note: Requires Ollama installed locally
 
 **Example: Claude Haiku + GPT-4o**
 
-| Scenario | Traditional (GPT-4o only) | CascadeFlow (Haiku + GPT-4o) | Savings |
+| Scenario | Traditional (GPT-4o only) | cascadeflow (Haiku + GPT-4o) | Savings |
 |----------|---------------------------|------------------------------|---------|
 | Simple Q&A (75% acceptance) | $0.0025 | $0.0008 | 68% |
 | Complex query (25% escalation) | $0.0025 | $0.0025 | 0% (correctly escalated) |
@@ -249,12 +309,12 @@ Note: Requires Ollama installed locally
 
 **Monthly savings (10,000 queries):**
 - Traditional (GPT-4o only): $25.00
-- CascadeFlow (Haiku + GPT-4o): $11.50
+- cascadeflow (Haiku + GPT-4o): $11.50
 - **You save: $13.50/month** (54% savings)
 
 **Monthly savings (100,000 queries):**
 - Traditional (GPT-4o only): $250.00
-- CascadeFlow (Haiku + GPT-4o): $115.00
+- cascadeflow (Haiku + GPT-4o): $115.00
 - **You save: $135.00/month** (54% savings)
 
 ## Example Workflows
@@ -270,7 +330,7 @@ Note: Requires Ollama installed locally
          v
 ┌─────────────────────────────────────┐
 │  Claude Haiku ────┐                 │
-│                   │  CascadeFlow    │       ┌──────────────────┐
+│                   │  cascadeflow    │       ┌──────────────────┐
 │  Claude Sonnet ───┴─► Node          │──────►│  Basic Chain     │
 └─────────────────────────────────────┘       │  (responds)      │
                                                └──────┬───────────┘
@@ -292,7 +352,7 @@ Note: Requires Ollama installed locally
          v
 ┌────────────────────────────────────────┐
 │  GPT-4o-mini ─────┐                    │
-│                   │  CascadeFlow       │       ┌──────────────────┐
+│                   │  cascadeflow       │       ┌──────────────────┐
 │  GPT-4o ──────────┴─► Node             │──────►│  Basic Chain     │
 └────────────────────────────────────────┘       │  (generates)     │
                                                   └──────┬───────────┘
@@ -314,7 +374,7 @@ Note: Requires Ollama installed locally
          v
 ┌─────────────────────────────────────┐
 │  Ollama qwen2.5 ──┐                 │
-│                   │  CascadeFlow    │       ┌──────────────────┐
+│                   │  cascadeflow    │       ┌──────────────────┐
 │  GPT-4o ──────────┴─► Node          │──────►│  Basic Chain     │
 └─────────────────────────────────────┘       │  (reviews code)  │
                                                └──────┬───────────┘
@@ -334,7 +394,7 @@ Note: Requires Ollama installed locally
 **To see the actual cascade flow and which model was used:**
 
 1. Execute your workflow
-2. Click on the downstream Chain node after execution (the node that receives CascadeFlow output)
+2. Click on the downstream Chain node after execution (the node that receives cascadeflow output)
 3. Navigate to the **"Logs"** tab
 4. You'll see detailed flow information showing:
    - Whether the drafter was accepted or escalated to verifier
@@ -345,7 +405,7 @@ Note: Requires Ollama installed locally
 
 The logs provide complete visibility into the cascade decision-making process, showing exactly which path was taken for each request.
 
-> **ℹ️ Important:** CascadeFlow does **not work with AI Agent nodes** in n8n, as n8n only allows whitelisted models for Agent inputs. Use with Basic LLM Chain, Chain, or other nodes that accept Language Model connections.
+> **ℹ️ Important:** If you need agent-style tool orchestration, use the **CascadeFlow Agent** node. It is designed for n8n agent flows and records a step-by-step trace in `response_metadata.cf.trace`.
 
 ## Compatibility
 
@@ -372,17 +432,17 @@ The logs provide complete visibility into the cascade decision-making process, s
 
 **Solution:**
 1. Make sure your workflow has executed successfully
-2. Click on the **Chain node that receives the CascadeFlow output** (Basic LLM Chain, Chain, etc.)
+2. Click on the **Chain node that receives the cascadeflow output** (Basic LLM Chain, Chain, etc.)
 3. Navigate to the **"Logs"** tab (not the "Output" tab)
-4. The logs appear in the downstream node, not the CascadeFlow node itself
+4. The logs appear in the downstream node, not the cascadeflow node itself
 
 ### Issue: "This node cannot be connected" when connecting to AI Agent
 
-**Solution:** This is expected. CascadeFlow does **not work with AI Agent nodes** because n8n only allows whitelisted models for Agent inputs. Use CascadeFlow with:
+**Solution:** Use the **CascadeFlow Agent** node for agent workflows. Use the **CascadeFlow (Model)** node for Chain/LLM workflows.
 - ✅ Basic LLM Chain
 - ✅ Chain
 - ✅ Other nodes that accept Language Model connections
-- ❌ AI Agent (not supported)
+- ✅ CascadeFlow Agent (agent workflows)
 
 ### Issue: Always escalating to verifier
 
@@ -404,11 +464,11 @@ The logs provide complete visibility into the cascade decision-making process, s
 
 ## Version History
 
-### v0.6.6 (Latest)
+### v0.6.7 (Latest)
 
-- **Removed semantic validation**: Disabled ML-based semantic validation to prevent out-of-memory crashes in n8n environments
-- **Shorter domain labels**: Domain input labels simplified (Code, Math, Data, etc.) for better readability
-- **Updated documentation**: Cleaned up README and version history
+- **Multi-domain cascading docs**: Added documentation for 8-domain intelligent cascading
+- **Removed semantic validation**: Disabled ML-based semantic validation to prevent out-of-memory crashes
+- **Shorter domain labels**: Domain input labels simplified (Code, Math, Data, etc.)
 
 ### v0.6.4
 

package/dist/nodes/CascadeFlowAgent/CascadeFlowAgent.node.d.ts

@@ -0,0 +1,34 @@
+import type { INodeType, INodeTypeDescription, ISupplyDataFunctions, SupplyData } from 'n8n-workflow';
+import { CascadeChatModel } from '../LmChatCascadeFlow/LmChatCascadeFlow.node';
+type ToolRoutingMode = 'cascade' | 'verifier';
+export interface ToolRoutingRule {
+    toolName: string;
+    routing: ToolRoutingMode;
+}
+export interface ToolLike {
+    name?: string;
+    description?: string;
+    invoke?: (args: any) => Promise<any>;
+    call?: (args: any) => Promise<any>;
+    run?: (args: any) => Promise<any>;
+}
+export declare class CascadeFlowAgentExecutor {
+    private cascadeModel;
+    private maxIterations;
+    private toolMap;
+    private routingRules;
+    constructor(cascadeModel: CascadeChatModel, tools: ToolLike[], routingRules: ToolRoutingRule[], maxIterations: number);
+    private normalizeMessages;
+    private extractToolCalls;
+    private executeTool;
+    private resolveRouting;
+    private buildTraceEntry;
+    invoke(input: any, options?: any): Promise<any>;
+    stream(input: any, options?: any): AsyncGenerator<any>;
+}
+export declare class CascadeFlowAgent implements INodeType {
+    description: INodeTypeDescription;
+    supplyData(this: ISupplyDataFunctions): Promise<SupplyData>;
+}
+export {};
+//# sourceMappingURL=CascadeFlowAgent.node.d.ts.map

package/dist/nodes/CascadeFlowAgent/CascadeFlowAgent.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CascadeFlowAgent.node.d.ts","sourceRoot":"","sources":["../../../nodes/CascadeFlowAgent/CascadeFlowAgent.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,EACX,MAAM,cAAc,CAAC;AAQtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,6CAA6C,CAAC;AAE/E,KAAK,eAAe,GAAG,SAAS,GAAG,UAAU,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,eAAe,CAAC;CAC1B;AAQD,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACnC;AAED,qBAAa,wBAAwB;IAKjC,OAAO,CAAC,YAAY;IAGpB,OAAO,CAAC,aAAa;IAPvB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,YAAY,CAA+B;gBAGzC,YAAY,EAAE,gBAAgB,EACtC,KAAK,EAAE,QAAQ,EAAE,EACjB,YAAY,EAAE,eAAe,EAAE,EACvB,aAAa,EAAE,MAAM;IAQ/B,OAAO,CAAC,iBAAiB;IA8EzB,OAAO,CAAC,gBAAgB;YA4CV,WAAW;IAqBzB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,eAAe;IAkBjB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IA4D9C,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC;CAc9D;AAED,qBAAa,gBAAiB,YAAW,SAAS;IAChD,WAAW,EAAE,oBAAoB,CAwM/B;IAEI,UAAU,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;CAgFlE"}