@goodandready/dsh-moa 0.2.73 → 0.2.75

package/lib/pipeline/escalation.js

@@ -0,0 +1,160 @@
+/**
+ * Dynamic Consensus Threshold & Multi-Judge Escalation (#300)
+ *
+ * Detects divergence among candidate outputs (Disagreement Metric).
+ * When candidate consensus is weak or contradictory, automatically escalates:
+ * - auto_upgrade: upgrades from lightweight/fast judge to flagship/senior judge
+ * - council_majority: convenes a 3-judge panel with majority voting
+ */
+
+import { calculateSimilarity } from './early-consensus.js'
+
+/**
+ * Calculates the Disagreement Metric (0.0 to 1.0) across candidate outputs.
+ * 0.0 means perfect consensus (identical solutions).
+ * 1.0 means total divergence (completely distinct solutions).
+ *
+ * @param {Array<object>} candidateOutputs
+ * @returns {number} Disagreement metric between 0.0 and 1.0
+ */
+export function calculateDisagreementMetric(candidateOutputs = []) {
+  if (!Array.isArray(candidateOutputs) || candidateOutputs.length < 2) {
+    return 0.0
+  }
+
+  const validTexts = candidateOutputs
+    .filter((c) => c && typeof c.text === 'string' && c.text.trim())
+    .map((c) => c.text)
+
+  if (validTexts.length < 2) return 0.0
+
+  let totalSim = 0
+  let pairs = 0
+
+  for (let i = 0; i < validTexts.length; i++) {
+    for (let j = i + 1; j < validTexts.length; j++) {
+      totalSim += calculateSimilarity(validTexts[i], validTexts[j])
+      pairs++
+    }
+  }
+
+  if (pairs === 0) return 0.0
+  const avgSim = totalSim / pairs
+  const disagreement = Math.max(0.0, Math.min(1.0, 1.0 - avgSim))
+  return Number(disagreement.toFixed(4))
+}
+
+/**
+ * Evaluates whether candidate divergence warrants judge escalation.
+ *
+ * @param {object} params
+ * @param {Array<object>} params.candidateOutputs - Array of successful candidate results
+ * @param {object} params.primaryJudge - Primary configured judge slot
+ * @param {Array<object>} [params.fallbackJudges=[]] - Chain of backup judges
+ * @param {object} [params.escalationJudge] - Explicit flagship upgrade judge
+ * @param {string} [params.policy='single'] - 'single' | 'auto_upgrade' | 'council_majority'
+ * @param {number} [params.threshold=0.40] - Disagreement threshold to trigger escalation
+ * @returns {object} Escalation decision and effective judge(s)
+ */
+export function evaluateJudgeEscalation({
+  candidateOutputs = [],
+  primaryJudge = { provider: '', model: '' },
+  fallbackJudges = [],
+  escalationJudge = null,
+  policy = 'single',
+  threshold = 0.40,
+} = {}) {
+  const normPolicy = String(policy || 'single').toLowerCase()
+
+  if (normPolicy === 'single' || !Array.isArray(candidateOutputs) || candidateOutputs.length < 2) {
+    return {
+      escalated: false,
+      escalatedType: 'none',
+      judge: primaryJudge,
+      councilJudges: [primaryJudge],
+      disagreement: 0.0,
+      threshold,
+      reason: 'Standard single judge evaluation',
+    }
+  }
+
+  const disagreement = calculateDisagreementMetric(candidateOutputs)
+  const isTriggered = disagreement >= threshold
+
+  if (!isTriggered) {
+    return {
+      escalated: false,
+      escalatedType: 'none',
+      judge: primaryJudge,
+      councilJudges: [primaryJudge],
+      disagreement,
+      threshold,
+      reason: `Consensus adequate: disagreement ${(disagreement * 100).toFixed(1)}% < threshold ${(threshold * 100).toFixed(1)}%`,
+    }
+  }
+
+  if (normPolicy === 'auto_upgrade') {
+    // Pick designated escalationJudge, or the first available fallbackJudge
+    let targetJudge = null
+    if (escalationJudge && escalationJudge.model) {
+      targetJudge = escalationJudge
+    } else if (Array.isArray(fallbackJudges) && fallbackJudges.length > 0 && fallbackJudges[0]?.model) {
+      targetJudge = fallbackJudges[0]
+    } else {
+      targetJudge = primaryJudge
+    }
+
+    const upgraded = targetJudge.model !== primaryJudge.model || targetJudge.provider !== primaryJudge.provider
+    return {
+      escalated: upgraded,
+      escalatedType: upgraded ? 'auto_upgrade' : 'none',
+      judge: targetJudge,
+      originalJudge: primaryJudge,
+      councilJudges: [targetJudge],
+      disagreement,
+      threshold,
+      reason: upgraded
+        ? `High candidate divergence (${(disagreement * 100).toFixed(1)}% >= ${(threshold * 100).toFixed(1)}%): upgraded judge to ${targetJudge.provider ? targetJudge.provider + ':' : ''}${targetJudge.model}`
+        : `High divergence detected (${(disagreement * 100).toFixed(1)}%), but no senior fallback judge configured`,
+    }
+  }
+
+  if (normPolicy === 'council_majority') {
+    const council = [primaryJudge]
+    if (escalationJudge && escalationJudge.model && escalationJudge.model !== primaryJudge.model) {
+      council.push(escalationJudge)
+    }
+    if (Array.isArray(fallbackJudges)) {
+      for (const fb of fallbackJudges) {
+        if (council.length >= 3) break
+        if (fb && fb.model && !council.some((c) => c.model === fb.model && c.provider === fb.provider)) {
+          council.push(fb)
+        }
+      }
+    }
+
+    const hasMulti = council.length > 1
+    return {
+      escalated: hasMulti,
+      escalatedType: hasMulti ? 'council_majority' : 'none',
+      judge: council[0],
+      originalJudge: primaryJudge,
+      councilJudges: council,
+      disagreement,
+      threshold,
+      reason: hasMulti
+        ? `High candidate divergence (${(disagreement * 100).toFixed(1)}% >= ${(threshold * 100).toFixed(1)}%): assembled ${council.length}-judge council`
+        : `High divergence detected, but fewer than 2 judges available for council`,
+    }
+  }
+
+  return {
+    escalated: false,
+    escalatedType: 'none',
+    judge: primaryJudge,
+    councilJudges: [primaryJudge],
+    disagreement,
+    threshold,
+    reason: 'Standard single judge',
+  }
+}

package/lib/pipeline/manifest-stack.js

@@ -0,0 +1,287 @@
+/**
+ * Stack-Aware Dynamic Persona Evolution from Project Manifests (#308)
+ *
+ * Scans project manifests (package.json, Cargo.toml, pyproject.toml, requirements.txt, go.mod)
+ * in the workspace root to infer primary programming languages, frameworks, ORMs,
+ * and test suites. Evolves candidate proposers into specialized domain experts
+ * (e.g. React Optimization, TypeScript Strict Safety, Accessibility, FastAPI Async)
+ * to maximize architectural hypothesis diversity.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Scans workspace root manifests to detect project languages and dependencies.
+ *
+ * @param {string} cwd - Workspace root directory
+ * @returns {object} Detected stack information
+ */
+export function detectProjectStack(cwd = process.cwd()) {
+  const stack = {
+    primaryLanguage: 'unknown',
+    frameworks: [],
+    libraries: [],
+    manifestFound: false,
+    stackSummary: '',
+  }
+
+  if (!cwd || typeof cwd !== 'string') return stack
+
+  // 1. Node / JavaScript / TypeScript (package.json)
+  const pkgPath = path.join(cwd, 'package.json')
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const raw = fs.readFileSync(pkgPath, 'utf8')
+      const pkg = JSON.parse(raw)
+      stack.manifestFound = true
+      stack.primaryLanguage = 'javascript'
+
+      const allDeps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+        ...(pkg.peerDependencies || {}),
+      }
+
+      if (allDeps.typescript || fs.existsSync(path.join(cwd, 'tsconfig.json'))) {
+        stack.primaryLanguage = 'typescript'
+        stack.libraries.push('typescript')
+      }
+
+      // Frameworks
+      if (allDeps.next) stack.frameworks.push('next.js')
+      else if (allDeps.react) stack.frameworks.push('react')
+
+      if (allDeps.nuxt) stack.frameworks.push('nuxt')
+      else if (allDeps.vue) stack.frameworks.push('vue')
+
+      if (allDeps['@sveltejs/kit']) stack.frameworks.push('sveltekit')
+      else if (allDeps.svelte) stack.frameworks.push('svelte')
+
+      if (allDeps['@angular/core']) stack.frameworks.push('angular')
+      if (allDeps['@nestjs/core']) stack.frameworks.push('nestjs')
+      if (allDeps.fastify) stack.frameworks.push('fastify')
+      if (allDeps.express) stack.frameworks.push('express')
+
+      // Styling & UI
+      if (allDeps.tailwindcss) stack.libraries.push('tailwindcss')
+
+      // ORM & Data
+      if (allDeps.prisma || allDeps['@prisma/client']) stack.libraries.push('prisma')
+      if (allDeps['drizzle-orm']) stack.libraries.push('drizzle')
+      if (allDeps.typeorm) stack.libraries.push('typeorm')
+      if (allDeps.mongoose) stack.libraries.push('mongoose')
+
+      // Validation
+      if (allDeps.zod) stack.libraries.push('zod')
+      if (allDeps.valibot) stack.libraries.push('valibot')
+
+      // Testing
+      if (allDeps.vitest) stack.libraries.push('vitest')
+      if (allDeps.jest) stack.libraries.push('jest')
+      if (allDeps.playwright || allDeps['@playwright/test']) stack.libraries.push('playwright')
+    } catch {
+      // safe fallback on corrupted package.json
+    }
+  }
+
+  // 2. Rust (Cargo.toml)
+  const cargoPath = path.join(cwd, 'Cargo.toml')
+  if (fs.existsSync(cargoPath)) {
+    try {
+      const content = fs.readFileSync(cargoPath, 'utf8')
+      stack.manifestFound = true
+      stack.primaryLanguage = 'rust'
+
+      if (content.includes('axum')) stack.frameworks.push('axum')
+      if (content.includes('actix-web')) stack.frameworks.push('actix-web')
+      if (content.includes('tokio')) stack.libraries.push('tokio')
+      if (content.includes('serde')) stack.libraries.push('serde')
+      if (content.includes('sqlx')) stack.libraries.push('sqlx')
+      if (content.includes('diesel')) stack.libraries.push('diesel')
+    } catch {
+      // safe fallback
+    }
+  }
+
+  // 3. Python (pyproject.toml, requirements.txt)
+  const pyprojectPath = path.join(cwd, 'pyproject.toml')
+  const reqPath = path.join(cwd, 'requirements.txt')
+  if (fs.existsSync(pyprojectPath) || fs.existsSync(reqPath)) {
+    try {
+      const pyContent = (fs.existsSync(pyprojectPath) ? fs.readFileSync(pyprojectPath, 'utf8') : '') +
+        '\n' + (fs.existsSync(reqPath) ? fs.readFileSync(reqPath, 'utf8') : '')
+      stack.manifestFound = true
+      if (stack.primaryLanguage === 'unknown') stack.primaryLanguage = 'python'
+
+      if (pyContent.includes('fastapi')) stack.frameworks.push('fastapi')
+      if (pyContent.includes('django')) stack.frameworks.push('django')
+      if (pyContent.includes('flask')) stack.frameworks.push('flask')
+      if (pyContent.includes('pydantic')) stack.libraries.push('pydantic')
+      if (pyContent.includes('sqlalchemy')) stack.libraries.push('sqlalchemy')
+      if (pyContent.includes('pytest')) stack.libraries.push('pytest')
+      if (pyContent.includes('torch')) stack.libraries.push('pytorch')
+      if (pyContent.includes('pandas')) stack.libraries.push('pandas')
+    } catch {
+      // safe fallback
+    }
+  }
+
+  // 4. Go (go.mod)
+  const goModPath = path.join(cwd, 'go.mod')
+  if (fs.existsSync(goModPath)) {
+    try {
+      const goContent = fs.readFileSync(goModPath, 'utf8')
+      stack.manifestFound = true
+      if (stack.primaryLanguage === 'unknown') stack.primaryLanguage = 'go'
+
+      if (goContent.includes('gin-gonic/gin')) stack.frameworks.push('gin')
+      if (goContent.includes('gofiber/fiber')) stack.frameworks.push('fiber')
+      if (goContent.includes('labstack/echo')) stack.frameworks.push('echo')
+      if (goContent.includes('gorm.io/gorm')) stack.libraries.push('gorm')
+      if (goContent.includes('stretchr/testify')) stack.libraries.push('testify')
+    } catch {
+      // safe fallback
+    }
+  }
+
+  // Build summary string
+  const parts = []
+  if (stack.primaryLanguage !== 'unknown') parts.push(stack.primaryLanguage)
+  if (stack.frameworks.length > 0) parts.push(`framework: ${stack.frameworks.join(', ')}`)
+  if (stack.libraries.length > 0) parts.push(`libs: ${stack.libraries.slice(0, 4).join(', ')}`)
+  stack.stackSummary = parts.join(' | ')
+
+  return stack
+}
+
+/**
+ * Returns specialized domain personas based on detected stack.
+ *
+ * @param {object} stackInfo
+ * @returns {Array<string>} Array of specialized persona role descriptions
+ */
+export function getStackPersonaSpecialties(stackInfo = {}) {
+  const lang = stackInfo.primaryLanguage || 'unknown'
+  const frameworks = Array.isArray(stackInfo.frameworks) ? stackInfo.frameworks : []
+  const libs = Array.isArray(stackInfo.libraries) ? stackInfo.libraries : []
+
+  // React / Next.js / Frontend
+  if (frameworks.includes('react') || frameworks.includes('next.js') || frameworks.includes('vue') || frameworks.includes('svelte')) {
+    return [
+      'Component Architecture, Hooks & Re-render Optimization Specialist',
+      libs.includes('typescript') || lang === 'typescript'
+        ? 'TypeScript Strict Typing, Generic Invariants & Defensive Schema Expert'
+        : 'State Management, Data Flow & Edge-Case Specialist',
+      'Accessibility (a11y), Semantic UI & Modern CSS Performance Reviewer',
+    ]
+  }
+
+  // Python / FastAPI / Django
+  if (lang === 'python') {
+    return [
+      frameworks.includes('fastapi')
+        ? 'FastAPI Async Concurrency & High-Throughput REST Architect'
+        : 'Pythonic Clean Architecture & Idiomatic Object Design Specialist',
+      libs.includes('pydantic')
+        ? 'Pydantic V2 Schema Validation & Type-Safe Domain Modeler'
+        : 'Defensive Data Integrity & Error Boundary Engineer',
+      libs.includes('pytest')
+        ? 'Pytest Fixtures, Mocking & Comprehensive Edge-Case Test Engineer'
+        : 'Performance Profiling & Memory Leak Auditor',
+    ]
+  }
+
+  // Rust
+  if (lang === 'rust') {
+    return [
+      'Rust Zero-Cost Abstractions & Concurrency Architect',
+      'Rust Memory Safety, Error Handling & Lifetime Specialist',
+      'Rust Idiomatic API & Performance Specialist',
+    ]
+  }
+
+  // Go
+  if (lang === 'go') {
+    return [
+      'Go Idiomatic Concurrency & Channel Synchronization Architect',
+      'Go Interface Design, Error Wrapping & Zero-Allocation Specialist',
+      'Go Production Reliability & Table-Driven Unit Testing Specialist',
+    ]
+  }
+
+  // General TypeScript / Node
+  if (lang === 'typescript') {
+    return [
+      'TypeScript Strict Type Safety & Clean Architecture Specialist',
+      'Async Flow, Micro-Optimization & Error Boundary Engineer',
+      'Maintainability, Modularity & Test Coverage Auditor',
+    ]
+  }
+
+  // Universal Default
+  return [
+    'System Architecture & Core Correctness Engineer',
+    'Edge-Case Analysis & Defensive Error Handling Specialist',
+    'Clean Code, Maintainability & Documentation Specialist',
+  ]
+}
+
+/**
+ * Assigns stack-aware specialized personas to candidate proposer slots.
+ *
+ * @param {Array<object>} references - Proposer slots
+ * @param {object} stackInfo - Output of detectProjectStack
+ * @param {object} [options]
+ * @param {boolean} [options.enabled=true] - Whether stack-aware personas are enabled
+ * @returns {{ references: Array<object>, isSpecialized: boolean, stackSummary: string }}
+ */
+export function assignStackAwarePersonas(references = [], stackInfo = {}, options = {}) {
+  const { enabled = true } = options
+
+  if (!enabled || !Array.isArray(references) || references.length === 0) {
+    return {
+      references: Array.isArray(references) ? references : [],
+      isSpecialized: false,
+      stackSummary: stackInfo.stackSummary || '',
+    }
+  }
+
+  const specialties = getStackPersonaSpecialties(stackInfo)
+  const evolved = references.map((slot, idx) => {
+    // If user already specified a custom non-default persona, preserve it
+    const hasCustom = slot.role_persona && slot.role_persona !== 'general' && slot.role_persona !== 'proposer'
+    if (hasCustom) {
+      return { ...slot }
+    }
+
+    const specialty = specialties[idx % specialties.length]
+    return {
+      ...slot,
+      role_persona: specialty,
+      stackSpecialization: specialty,
+    }
+  })
+
+  return {
+    references: evolved,
+    isSpecialized: Boolean(stackInfo.manifestFound),
+    stackSummary: stackInfo.stackSummary || '',
+  }
+}
+
+/**
+ * Formats a directive summarizing the project stack for injection into judge or synthesis prompts.
+ *
+ * @param {object} stackInfo
+ * @returns {string|null}
+ */
+export function formatStackAwareDirective(stackInfo = {}) {
+  if (!stackInfo || !stackInfo.manifestFound || !stackInfo.stackSummary) {
+    return null
+  }
+
+  return `### Project Stack & Architecture Context
+- Detected Environment: ${stackInfo.stackSummary}
+- Verification Requirement: All proposals must adhere to the conventions and idiomatic idioms of this technology stack.`
+}

package/lib/pipeline/runner.js

@@ -1,3 +1,5 @@
+import { evaluateJudgeEscalation } from './escalation.js'
+import { calculateSelfConsistencyAgreement } from './self-consistency.js'
 import { pruneCandidateEnsemble, formatPruningDirective } from './context-pruner.js'
 import { buildAstCompositeMergeDirective } from '../moa-ast-merge.js'
 import { runVisualMoaConsensus } from '../moa-visual-consensus.js'
@@ -106,6 +108,13 @@ export async function runMoAPipeline({
   })
   const syntaxDirective = syntaxResult.filterApplied ? formatSyntaxDirective(referenceOutputs, { blind: ctxStage.isBlindEvaluation }) : null
 
+  if (ctxStage.selfConsistencyExpanded && successfulRefs.length > 1) {
+    const scAgreement = calculateSelfConsistencyAgreement(successfulRefs)
+    if (typeof onProgress === 'function') {
+      onProgress(`🎯 *Self-Consistency Agreement: ${(scAgreement.agreementRatio * 100).toFixed(0)}% (${scAgreement.isStrongConsensus ? 'Strong consensus' : 'Divergent sampling'}) across ${scAgreement.sampleCount} samples*\n`)
+    }
+  }
+
   // Stage 3: Clarifying Questions Branch
   if (ctxStage.needsQuestions) {
     return await stageClarifyingQuestions({
@@ -190,11 +199,56 @@ export async function runMoAPipeline({
     return { error: new Error('Turn aborted') }
   }
 
+  // Pre-Stage 6: Dynamic Consensus Threshold & Multi-Judge Escalation (#300)
+  const escalationResult = evaluateJudgeEscalation({
+    candidateOutputs: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+    primaryJudge: ctxStage.primaryJudge,
+    fallbackJudges: ctxStage.fallbackJudges,
+    escalationJudge: ctxStage.escalationJudge,
+    policy: ctxStage.escalationPolicy,
+    threshold: ctxStage.escalationDisagreementThreshold,
+  })
+
+  let effectivePrimaryJudge = ctxStage.primaryJudge
+  let effectiveFallbackJudges = ctxStage.fallbackJudges
+  let effectiveJudgesChain = ctxStage.judgesChain
+  let effectivePreset = preset
+
+  if (escalationResult.escalated) {
+    emitEvent(ctx, MOA_EVENTS.JUDGE_ESCALATION, {
+      runId,
+      policy: ctxStage.escalationPolicy,
+      disagreement: escalationResult.disagreement,
+      threshold: escalationResult.threshold,
+      escalatedType: escalationResult.escalatedType,
+      originalJudge: escalationResult.originalJudge,
+      escalatedJudge: escalationResult.judge,
+      councilJudges: escalationResult.councilJudges,
+    })
+    if (typeof onProgress === 'function') {
+      onProgress(`⚖️ *Judge Escalation (${escalationResult.escalatedType}): ${escalationResult.reason}*\n`)
+    }
+
+    if (escalationResult.escalatedType === 'auto_upgrade') {
+      effectivePrimaryJudge = escalationResult.judge
+      effectiveFallbackJudges = ctxStage.fallbackJudges.filter(
+        (j) => !(j.provider === escalationResult.judge.provider && j.model === escalationResult.judge.model)
+      )
+      effectiveJudgesChain = [effectivePrimaryJudge, ...effectiveFallbackJudges]
+    } else if (escalationResult.escalatedType === 'council_majority') {
+      effectivePreset = {
+        ...preset,
+        multi_judge_enabled: true,
+        judge_models: escalationResult.councilJudges,
+      }
+    }
+  }
+
   // Stage 6: Multi-Judge Panel
   const mjRes = await stageMultiJudge({
-    preset,
+    preset: effectivePreset,
     successfulRefs: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
-    referenceOutputs, primaryJudge: ctxStage.primaryJudge,
+    referenceOutputs, primaryJudge: effectivePrimaryJudge,
     userPrompt, judgeCriteria: ctxStage.judgeCriteria, prices, maxTokens: ctxStage.maxTokens,
     callLlm, signal, onProgress, cwd, runId, isRefinement: ctxStage.isRefinement,
     isFastMode: ctxStage.isFastMode, collectedCtx: ctxStage.collectedCtx, startTime,
@@ -253,7 +307,7 @@ export async function runMoAPipeline({
     }
   }
 
-  const fileScoringDirective = [rawFileDirective, visualResult?.directive, adversarialTddResult?.directive, syntaxDirective, pruningDirective].filter(Boolean).join("\n\n") || null
+  const fileScoringDirective = [rawFileDirective, visualResult?.directive, adversarialTddResult?.directive, syntaxDirective, pruningDirective, ctxStage.stackAwareDirective, ctxStage.developerPreferencesDirective].filter(Boolean).join("\n\n") || null
 
   // Stage 7: Synthesis Phase
   const synthRes = await stageSynthesis({
@@ -263,9 +317,9 @@ export async function runMoAPipeline({
     judgeCriteria: ctxStage.judgeCriteria,
     isCuratorSynthesis: ctxStage.isCuratorSynthesis, isBlindEvaluation: ctxStage.isBlindEvaluation,
     priorTurnBaseline: ctxStage.priorTurnBaseline, compositeMergeDirective, fileScoringDirective,
-    multiJudgeResult, preset, prices, maxTokens: ctxStage.maxTokens, isFastMode: ctxStage.isFastMode,
-    primaryJudge: ctxStage.primaryJudge, fallbackJudges: ctxStage.fallbackJudges,
-    judgesChain: ctxStage.judgesChain, aggTemp: ctxStage.aggTemp,
+    multiJudgeResult, preset: effectivePreset, prices, maxTokens: ctxStage.maxTokens, isFastMode: ctxStage.isFastMode,
+    primaryJudge: effectivePrimaryJudge, fallbackJudges: effectiveFallbackJudges,
+    judgesChain: effectiveJudgesChain, aggTemp: ctxStage.aggTemp,
     aggTimeoutSec: ctxStage.aggTimeoutSec, isStreamAggregator: ctxStage.isStreamAggregator,
     onStreamDelta, signal, callLlm, onProgress, cwd, runId, isRefinement: ctxStage.isRefinement,
     collectedCtx: ctxStage.collectedCtx, startTime,

package/lib/pipeline/self-consistency.js

@@ -0,0 +1,135 @@
+/**
+ * Self-Consistency Temperature Sampling for Single Models (#301)
+ *
+ * Allows users with a single model slot (e.g., local Ollama/vLLM or a single API key)
+ * to benefit from Mixture of Agents ensemble diversity by generating parallel samples
+ * at varying temperatures and complementary system personas, followed by consistency voting.
+ */
+
+import { ROLE_PERSONA_PROMPTS } from '../moa-prompts.js'
+
+export const DEFAULT_SELF_CONSISTENCY_TEMPERATURES = Object.freeze([0.2, 0.6, 0.9])
+export const DEFAULT_SELF_CONSISTENCY_PERSONAS = Object.freeze(['proposer', 'challenger', 'minimalist'])
+
+/**
+ * Expands a single reference model into multiple parallel proposer slots
+ * with distinct temperatures and complementary reasoning personas.
+ *
+ * @param {Array<object>} referenceModels - Original reference model slots
+ * @param {object} [options]
+ * @param {boolean} [options.enabled=false] - Whether self-consistency expansion is enabled
+ * @param {number} [options.samples=3] - Number of candidate samples to generate (2-10)
+ * @param {Array<number>} [options.temperatures] - Array of temperatures for samples
+ * @param {Array<string>} [options.personas] - Array of persona role names
+ * @returns {{ references: Array<object>, isExpanded: boolean, sampleCount: number }}
+ */
+export function expandSelfConsistencySlots(referenceModels = [], options = {}) {
+  const {
+    enabled = false,
+    samples = 3,
+    temperatures = DEFAULT_SELF_CONSISTENCY_TEMPERATURES,
+    personas = DEFAULT_SELF_CONSISTENCY_PERSONAS,
+  } = options
+
+  // Expansion applies only when explicitly enabled or requested
+  if (!enabled) {
+    return {
+      references: Array.isArray(referenceModels) ? referenceModels : [],
+      isExpanded: false,
+      sampleCount: Array.isArray(referenceModels) ? referenceModels.length : 0,
+    }
+  }
+
+  const rawList = Array.isArray(referenceModels) && referenceModels.length > 0
+    ? referenceModels
+    : [{ provider: '', model: '' }]
+
+  // Only expand when a single model slot is configured
+  if (rawList.length !== 1) {
+    return {
+      references: rawList,
+      isExpanded: false,
+      sampleCount: rawList.length,
+    }
+  }
+
+  const baseSlot = rawList[0] || {}
+  const count = Math.min(10, Math.max(2, Number(samples) || 3))
+  const expandedList = []
+
+  for (let i = 0; i < count; i++) {
+    const temp = Array.isArray(temperatures) && typeof temperatures[i] === 'number'
+      ? temperatures[i]
+      : (DEFAULT_SELF_CONSISTENCY_TEMPERATURES[i % DEFAULT_SELF_CONSISTENCY_TEMPERATURES.length] || 0.6)
+
+    const role = Array.isArray(personas) && personas[i]
+      ? personas[i]
+      : (DEFAULT_SELF_CONSISTENCY_PERSONAS[i % DEFAULT_SELF_CONSISTENCY_PERSONAS.length] || 'proposer')
+
+    expandedList.push({
+      ...baseSlot,
+      label: baseSlot.label
+        ? `${baseSlot.label} [T=${temp}, ${role}]`
+        : `Sample ${i + 1} (${baseSlot.model || 'model'}, T=${temp})`,
+      temperature: temp,
+      role_persona: role,
+      sampleIndex: i + 1,
+      isSelfConsistencySample: true,
+    })
+  }
+
+  return {
+    references: expandedList,
+    isExpanded: true,
+    sampleCount: expandedList.length,
+  }
+}
+
+/**
+ * Calculates majority agreement and self-consistency metrics across candidate outputs.
+ *
+ * @param {Array<object>} candidateOutputs - Array of successful candidate results
+ * @returns {{ agreementRatio: number, isStrongConsensus: boolean, sampleCount: number }}
+ */
+export function calculateSelfConsistencyAgreement(candidateOutputs = []) {
+  if (!Array.isArray(candidateOutputs) || candidateOutputs.length < 2) {
+    return {
+      agreementRatio: 1.0,
+      isStrongConsensus: true,
+      sampleCount: Array.isArray(candidateOutputs) ? candidateOutputs.length : 0,
+    }
+  }
+
+  const texts = candidateOutputs
+    .filter((c) => c && typeof c.text === 'string' && c.text.trim())
+    .map((c) => c.text.trim().toLowerCase().replace(/\s+/g, ' '))
+
+  if (texts.length < 2) {
+    return {
+      agreementRatio: 1.0,
+      isStrongConsensus: true,
+      sampleCount: texts.length,
+    }
+  }
+
+  // Count exact and near-match clusters
+  let maxClusterSize = 1
+  for (let i = 0; i < texts.length; i++) {
+    let clusterSize = 1
+    for (let j = 0; j < texts.length; j++) {
+      if (i === j) continue
+      // If texts are very similar (> 85% overlap)
+      if (texts[i] === texts[j] || (texts[i].length > 20 && texts[j].includes(texts[i].slice(0, 40)))) {
+        clusterSize++
+      }
+    }
+    if (clusterSize > maxClusterSize) maxClusterSize = clusterSize
+  }
+
+  const agreementRatio = Number((maxClusterSize / texts.length).toFixed(2))
+  return {
+    agreementRatio,
+    isStrongConsensus: agreementRatio >= 0.66,
+    sampleCount: texts.length,
+  }
+}