feat(n8n): CascadeFlow Agent node + model highlighting (#102)

* feat(n8n): add CascadeFlow Agent node

* fix(n8n): lazy-load models to highlight actually used nodes

* chore(ci): fix python formatting/lint (black+ruff)

* test(n8n): add agent executor tests + run n8n tests in CI

* chore(ci): pin ruff + sync import sorting

* docs(n8n): remove outdated defaults + delete planning docs

* fix: resolve duplicate ruff per-file ignores

* test(ci): stabilize proxy concurrency test on macos

Author: saschabuehrle

.github/workflows/test.yml

@@ -143,6 +143,14 @@ jobs:
       - name: Lint n8n package
         run: pnpm --filter @cascadeflow/n8n-nodes-cascadeflow lint
 
+      - name: Smoke load built n8n nodes
+        run: |
+          node -e "require('./packages/integrations/n8n/dist/nodes/LmChatCascadeFlow/LmChatCascadeFlow.node.js')"
+          node -e "require('./packages/integrations/n8n/dist/nodes/CascadeFlowAgent/CascadeFlowAgent.node.js')"
+
+      - name: Test n8n package
+        run: pnpm --filter @cascadeflow/n8n-nodes-cascadeflow test
+
   # Python Code Quality
   lint-python:
     name: Python Code Quality
@@ -164,7 +172,8 @@ jobs:
           # Pin Black to the last version that supports Python 3.9.
           # The repo supports Python >=3.9, and newer Black releases may format
           # differently (or drop 3.9), causing CI-only formatting failures.
-          pip install "black==25.11.0" ruff mypy types-PyYAML
+          # Pin Ruff to avoid CI-only lint drift as Ruff evolves.
+          pip install "black==25.11.0" "ruff==0.15.0" mypy types-PyYAML
 
       - name: Check formatting with Black
         run: black --check cascadeflow tests examples

README.md

@@ -370,6 +370,7 @@ cascadeflow is a **Language Model sub-node** that connects two AI Chat Model nod
 
 - ✅ Works with any AI Chat Model node (OpenAI, Anthropic, Ollama, Azure, etc.)
 - ✅ Mix providers (e.g., Ollama drafter + GPT-4o verifier)
+- ✅ Includes a CascadeFlow Agent node for tool-based agent workflows (drafter/verifier + tools + trace)
 - ✅ Real-time flow visualization in Logs tab
 - ✅ Detailed metrics: confidence scores, latency, cost savings
 

docs/guides/n8n_integration.md

@@ -78,7 +78,7 @@ cascadeflow is a **Language Model sub-node** that sits between your AI model nod
 ✅ **Flexible** - Use any combination of models from different providers
 ✅ **Universal** - Compatible with OpenAI, Anthropic, Ollama, Azure, Google, and more
 
-> **ℹ️ 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.
 
 ---
 
@@ -142,7 +142,7 @@ First, add and configure two AI Chat Model nodes in your workflow:
 1. Add a **Basic LLM Chain** or **Chain** node
 2. Connect the cascadeflow node to it (Model input)
 3. Configure your chain as usual
-4. **Note:** Does not work with AI Agent nodes (n8n limitation)
+4. For agent workflows, use the **CascadeFlow Agent** node (connect tools to its `Tools` input).
 
 ### Step 4: Execute and View Results
 
@@ -160,7 +160,7 @@ First, add and configure two AI Chat Model nodes in your workflow:
 │  gpt-4o-mini     │       │  cascadeflow     │       ┌──────────────────┐
 └──────────────────┘       │  Node            │──────►│ Basic LLM Chain  │
                            │                  │       │                  │
-┌──────────────────┐       │  Threshold: 0.7  │       └──────────────────┘
+┌──────────────────┐       │  Threshold: 0.4  │       └──────────────────┘
 │  OpenAI Model    │──────►│                  │
 │  gpt-4o          │       └──────────────────┘
 └──────────────────┘
@@ -185,11 +185,16 @@ The cascadeflow node has **two inputs** that accept AI Language Model connection
 
 ### Quality Threshold (0-1)
 
-Controls how aggressively to accept drafter responses:
+Controls how aggressively to accept drafter responses when **Use Complexity Thresholds** is disabled.
 
-- **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)
+Defaults to **0.4** to match the `simple` tier in CascadeFlow's default per-complexity thresholds.
+
+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.
 
@@ -292,7 +297,7 @@ cascadeflow provides detailed logging of every cascade decision directly in n8n'
 
 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`.
 
 ---
 
@@ -329,7 +334,7 @@ The logs provide complete visibility into the cascade decision-making process, s
 **Configuration:**
 - Drafter: Claude 3.5 Haiku
 - Verifier: Claude 3.5 Sonnet
-- Quality Threshold: 0.75
+- Quality Threshold (if complexity thresholds are disabled): 0.75
 
 ---
 
@@ -396,7 +401,7 @@ The logs provide complete visibility into the cascade decision-making process, s
 **Configuration:**
 - Drafter: Ollama qwen2.5:3b (local, free)
 - Verifier: GPT-4o (cloud)
-- Quality Threshold: 0.7
+- Quality Threshold (if complexity thresholds are disabled): 0.7
 - Savings: ~99% on drafter calls
 
 ---
@@ -503,6 +508,7 @@ You can connect models from different providers:
 
 ### 5. Use Different Thresholds for Different Use Cases
 
+If you disable **Use Complexity Thresholds**, you can tune **Quality Threshold** per workflow:
 - **Customer support**: 0.75 (prioritize quality)
 - **Content drafts**: 0.6 (prioritize speed/cost)
 - **Code review**: 0.7 (balance)
@@ -517,7 +523,7 @@ You can connect models from different providers:
 ```
 Drafter: Claude 3.5 Haiku
 Verifier: GPT-4o
-Quality Threshold: 0.7
+Use Complexity Thresholds: enabled (default)
 Expected Savings: ~73% average
 Why: Haiku's fast drafts + GPT-4o's reasoning
 ```
@@ -527,7 +533,7 @@ Why: Haiku's fast drafts + GPT-4o's reasoning
 ```
 Drafter: GPT-4o-mini
 Verifier: GPT-4o
-Quality Threshold: 0.7
+Use Complexity Thresholds: enabled (default)
 Expected Savings: ~85% average
 Why: Both from same provider, excellent efficiency
 ```
@@ -547,7 +553,7 @@ Why: Consistent Anthropic quality
 ```
 Drafter: Ollama qwen2.5:3b (local, free)
 Verifier: GPT-4o (cloud)
-Quality Threshold: 0.7
+Use Complexity Thresholds: enabled (default)
 Expected Savings: ~99% on accepted drafts
 Note: Requires Ollama installed locally
 ```
@@ -574,11 +580,11 @@ Note: Requires Ollama installed locally
 
 ### 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
 

packages/integrations/n8n/N8N_COMPATIBILITY_VALIDATION.md

@@ -47,7 +47,6 @@
 - **Implementation:** ✅ VALIDATED
   - Dynamic import of `@cascadeflow/ml` with try/catch
   - Falls back to simple validation if unavailable
-  - Configurable via node properties (boolean toggle)
   - Does not crash n8n if package missing
 - **N8N Compatibility:** ✅ Full compatibility - graceful degradation verified
 
@@ -89,9 +88,8 @@
 - **Status:** ✅ VALIDATED
 - **Properties Added:**
   1. `qualityThreshold` (number, 0-1): Quality threshold configuration ✅
-  2. `useSemanticValidation` (boolean): Semantic ML validation toggle ✅
-  3. `useAlignmentScoring` (boolean): Query-response alignment toggle ✅
-  4. `useComplexityRouting` (boolean): Complexity-based routing toggle ✅
+  2. `useAlignmentScoring` (boolean): Query-response alignment toggle ✅
+  3. `useComplexityRouting` (boolean): Complexity-based routing toggle ✅
 - **N8N Compatibility:** ✅ All properties use standard n8n types (number, boolean)
 
 ### Metadata in Response
@@ -165,6 +163,7 @@
 - ✅ Optional dependencies handled gracefully (no hard failure when `@cascadeflow/core` is absent).
 
 ### Agent Validation
+- ✅ `CascadeFlow Agent` provides an `ai_agent` output for n8n agent workflows.
 - ✅ Cascade routing works with n8n's dual-input model graph (drafter + verifier).
 - ✅ Lazy-loading for verifier model remains intact for performance.
 - ✅ Domain routing and noted limitations are documented and stable.

packages/integrations/n8n/README.md

@@ -61,7 +61,7 @@ The cascadeflow node is a **Language Model sub-node** that sits between your AI
 
 **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
 
@@ -99,12 +99,12 @@ RUN cd /usr/local/lib/node_modules/n8n && npm install @cascadeflow/n8n-nodes-cas
 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
    - 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
 
@@ -120,7 +120,7 @@ RUN cd /usr/local/lib/node_modules/n8n && npm install @cascadeflow/n8n-nodes-cas
 │  gpt-4o-mini     │       │  cascadeflow     │       ┌──────────────────┐
 └──────────────────┘       │  Node            │──────►│ Basic LLM Chain  │
                            │                  │       │                  │
-┌──────────────────┐       │  Threshold: 0.7  │       └──────────────────┘
+┌──────────────────┐       │  Threshold: 0.4  │       └──────────────────┘
 │  OpenAI Model    │──────►│                  │
 │  gpt-4o          │       └──────────────────┘
 └──────────────────┘
@@ -132,11 +132,16 @@ 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.
 
-- **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)
+Defaults to **0.4** to match the `simple` tier in CascadeFlow's default per-complexity thresholds.
+
+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.
 
@@ -400,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
 
@@ -433,11 +438,11 @@ The logs provide complete visibility into the cascade decision-making process, s
 
 ### 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