Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(router): make model-router docs match shipped impl (#2329, Option A) (#2330)

rUv189e14b4756a
diff --git a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
index b88d4ed54c..bf3cdf23d8 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
@@ -4134,7 +4134,10 @@ export const hooksModelRoute: MCPTool = {
alternatives: result.alternatives,
inferenceTimeUs: result.inferenceTimeUs,
costMultiplier: result.costMultiplier,
- implementation: 'tiny-dancer-neural',
+ // Historical name kept for telemetry / dashboard schema stability.
+ // The shipped router is the heuristic + Thompson-bandit described in
+ // ruvector/model-router.ts — not a neural network. See #2329.
+ implementation: 'heuristic-thompson-bandit',
};
},
};
diff --git a/v3/@claude-flow/cli/src/ruvector/enhanced-model-router.ts b/v3/@claude-flow/cli/src/ruvector/enhanced-model-router.ts
index d4320687ff..d5e1a26b1f 100644
--- a/v3/@claude-flow/cli/src/ruvector/enhanced-model-router.ts
+++ b/v3/@claude-flow/cli/src/ruvector/enhanced-model-router.ts
@@ -257,7 +257,12 @@ const LANGUAGE_MAP: Record<string, string> = {
*/
export class EnhancedModelRouter {
private config: EnhancedModelRouterConfig;
- private tinyDancerRouter: ModelRouter;
+ // The base text-routing path delegated to here is the local
+ // heuristic + Thompson-bandit ModelRouter — NOT the @ruvector/tiny-dancer
+ // neural router that an earlier design (ADR-026) described (#2329). The
+ // public `getStats()` return still exposes the field as `tinyDancerStats`
+ // for telemetry-schema stability.
+ private baseRouter: ModelRouter;
constructor(config?: Partial<EnhancedModelRouterConfig>) {
this.config = {
@@ -281,7 +286,7 @@ export class EnhancedModelRouter {
...config,
};
- this.tinyDancerRouter = getModelRouter();
+ this.baseRouter = getModelRouter();
}
/**
@@ -451,14 +456,14 @@ export class EnhancedModelRouter {
}
}
- // Step 4: Text-based complexity + tiny-dancer routing
- const tinyDancerResult = await this.tinyDancerRouter.route(task);
+ // Step 4: Text-based complexity via the local heuristic + bandit router.
+ const baseResult = await this.baseRouter.route(task);
- // Step 5: Combine AST complexity with tiny-dancer result
- // Also boost if single tier3 keyword found
+ // Step 5: Combine AST complexity with the text-routing result.
+ // Also boost if a single tier3 keyword is found.
let finalComplexity = astComplexity !== undefined
- ? (astComplexity + tinyDancerResult.complexity) / 2
- : tinyDancerResult.complexity;
+ ? (astComplexity + baseResult.complexity) / 2
+ : baseResult.complexity;
// Boost complexity if tier3 keywords found (even just one)
if (tier3Check.matches) {
@@ -473,7 +478,7 @@ export class EnhancedModelRouter {
tier: 2,
handler: 'haiku',
model: 'haiku',
- confidence: tinyDancerResult.confidence,
+ confidence: baseResult.confidence,
complexity: finalComplexity,
reasoning: `Low complexity (${(finalComplexity * 100).toFixed(0)}%) - using haiku`,
canSkipLLM: false,
@@ -487,7 +492,7 @@ export class EnhancedModelRouter {
tier: 2,
handler: 'sonnet',
model: 'sonnet',
- confidence: tinyDancerResult.confidence,
+ confidence: baseResult.confidence,
complexity: finalComplexity,
reasoning: `Medium complexity (${(finalComplexity * 100).toFixed(0)}%) - using sonnet`,
canSkipLLM: false,
@@ -500,7 +505,7 @@ export class EnhancedModelRouter {
tier: 3,
handler: 'opus',
model: 'opus',
- confidence: tinyDancerResult.confidence,
+ confidence: baseResult.confidence,
complexity: finalComplexity,
reasoning: `High complexity (${(finalComplexity * 100).toFixed(0)}%) - using opus`,
canSkipLLM: false,
@@ -623,7 +628,10 @@ export class EnhancedModelRouter {
} {
return {
config: { ...this.config },
- tinyDancerStats: this.tinyDancerRouter.getStats(),
+ // Field name kept as `tinyDancerStats` for telemetry-schema
+ // stability; the underlying router is the local heuristic + bandit
+ // ModelRouter, not @ruvector/tiny-dancer. See #2329.
+ tinyDancerStats: this.baseRouter.getStats(),
};
}
}
diff --git a/v3/@claude-flow/cli/src/ruvector/model-router.ts b/v3/@claude-flow/cli/src/ruvector/model-router.ts
index f50b1e6042..89cb6c1f2c 100644
--- a/v3/@claude-flow/cli/src/ruvector/model-router.ts
+++ b/v3/@claude-flow/cli/src/ruvector/model-router.ts
@@ -1,20 +1,33 @@
/**
- * Intelligent Model Router using Tiny Dancer
+ * Intelligent Model Router — lexical complexity heuristic + Thompson bandit
*
- * Dynamically routes requests to optimal Claude model (haiku/sonnet/opus)
- * based on task complexity, confidence scores, and historical performance.
+ * Dynamically routes requests to the optimal Claude model (haiku/sonnet/opus)
+ * based on task complexity, uncertainty, and online-learned routing outcomes.
*
- * Features:
- * - FastGRNN-based routing decisions (<100μs)
- * - Uncertainty quantification for model escalation
- * - Circuit breaker for failover
- * - Online learning from routing outcomes
- * - Complexity scoring via embeddings
+ * Mechanism (shipped):
+ * - Complexity score = blend of lexical, semantic-depth, task-scope, and
+ * uncertainty heuristics (see `computeLexicalComplexity` and friends).
+ * Pure JS arithmetic — no model load, no tensor math.
+ * - Model selection = Thompson-sampling Beta-Bernoulli bandit with
+ * complexity-bucketed Beta(α,β) priors, persisted to
+ * `.swarm/model-router-state.json` and updated by `recordOutcome` after
+ * each routing decision.
+ * - Uncertainty quantification + a circuit breaker drive escalation when
+ * the bandit's confidence is low or downstream failures are observed.
*
* Routing Strategy:
- * - Haiku: High confidence, low complexity (fast, cheap)
- * - Sonnet: Medium confidence, moderate complexity (balanced)
- * - Opus: Low confidence, high complexity (most capable)
+ * - Haiku: high confidence, low complexity (fast, cheap)
+ * - Sonnet: medium confidence, moderate complexity (balanced)
+ * - Opus: low confidence, high complexity (most capable)
+ *
+ * Note (#2329): An earlier design (ADR-026 + this file's previous header)
+ * described a Tiny-Dancer / FastGRNN neural router with embedding-based
+ * complexity scoring. That path was never wired in — `@ruvector/tiny-dancer`
+ * is not imported here and the `embedding`-consuming branch in
+ * `computeSemanticDepth` is only reachable via the externally-callable
+ * `routeToModelFull(task, embedding)` wrapper (no internal callers). The
+ * shipped router is the heuristic + bandit described above; the neural
+ * path remains a future direction tracked in #2329.
*
* @module model-router
*/
diff --git a/v3/implementation/adrs/ADR-026-agent-booster-model-routing.md b/v3/implementation/adrs/ADR-026-agent-booster-model-routing.md
index bf6747b5ce..c58f3e4f20 100644
--- a/v3/implementation/adrs/ADR-026-agent-booster-model-routing.md
+++ b/v3/implementation/adrs/ADR-026-agent-booster-model-routing.md
@@ -7,7 +7,20 @@
## Context
-The current model routing system uses `tiny-dancer` for neural-based complexity analysis to select between `haiku`, `sonnet`, and `opus` models. While effective, this approach:
+> **Note (2026-06-09, #2329):** This ADR was authored when the design intent
+> was a `@ruvector/tiny-dancer` neural router. The shipped router in
+> `v3/@claude-flow/cli/src/ruvector/model-router.ts` is instead a lexical
+> complexity heuristic combined with a Thompson-sampling Beta-Bernoulli
+> bandit (no `@ruvector/tiny-dancer` import, no neural model load). Read
+> every `tiny-dancer` mention below as "the local heuristic + bandit
+> ModelRouter" until this ADR is rewritten or the neural path is wired
+> in. The 3-tier Agent Booster integration on top of it (the actual
+> subject of this ADR) is unaffected.
+
+The current model routing system uses the local heuristic + bandit
+`ModelRouter` (named `tiny-dancer` here for historical reasons; see note
+above) for complexity analysis to select between `haiku`, `sonnet`, and
+`opus` models. While effective, this approach:
1. Doesn't leverage AST-based analysis for code-specific tasks
2. Can't detect when tasks can be handled entirely by Agent Booster (352x faster, $0 cost)
@@ -442,7 +455,9 @@ v3/@claude-flow/cli/src/
- ADR-018: Claude Code Integration
- Agent Booster: https://github.com/anthropics/agent-booster
- agentic-flow: https://github.com/ruvnet/agentic-flow
-- tiny-dancer: Neural model router
+- tiny-dancer: design-intent name for the model-routing layer; the shipped
+ implementation is a lexical + Thompson-bandit `ModelRouter`, not a neural
+ router (see note at top of this ADR and #2329)
---