mcp-rubber-duck 1.2.5 → 1.4.0

package/src/tools/duck-iterate.ts

@@ -0,0 +1,253 @@
+import { ProviderManager } from '../providers/manager.js';
+import { IterationRound, IterationResult } from '../config/types.js';
+import { logger } from '../utils/logger.js';
+
+export interface DuckIterateArgs {
+  prompt: string;
+  iterations?: number;
+  providers: [string, string];
+  mode: 'refine' | 'critique-improve';
+}
+
+const DEFAULT_ITERATIONS = 3;
+const CONVERGENCE_THRESHOLD = 0.8; // 80% similarity indicates convergence
+
+export async function duckIterateTool(
+  providerManager: ProviderManager,
+  args: Record<string, unknown>
+) {
+  const {
+    prompt,
+    iterations = DEFAULT_ITERATIONS,
+    providers,
+    mode,
+  } = args as unknown as DuckIterateArgs;
+
+  // Validate inputs
+  if (!prompt || typeof prompt !== 'string') {
+    throw new Error('Prompt is required');
+  }
+
+  if (!providers || !Array.isArray(providers) || providers.length !== 2) {
+    throw new Error('Exactly 2 providers are required for iteration');
+  }
+
+  if (!mode || !['refine', 'critique-improve'].includes(mode)) {
+    throw new Error('Mode must be either "refine" or "critique-improve"');
+  }
+
+  if (iterations < 1 || iterations > 10) {
+    throw new Error('Iterations must be between 1 and 10');
+  }
+
+  // Validate providers exist
+  const providerNames = providerManager.getProviderNames();
+  for (const p of providers) {
+    if (!providerNames.includes(p)) {
+      throw new Error(`Provider "${p}" not found`);
+    }
+  }
+
+  logger.info(`Starting ${mode} iteration with ${providers.join(' <-> ')} for ${iterations} rounds`);
+
+  const rounds: IterationRound[] = [];
+  let lastResponse = '';
+  let converged = false;
+
+  // Round 1: Initial generation by provider A
+  const initialResponse = await providerManager.askDuck(providers[0], prompt);
+  const providerAInfo = providerManager.getProvider(providers[0]);
+
+  rounds.push({
+    round: 1,
+    provider: providers[0],
+    nickname: providerAInfo.nickname,
+    role: 'generator',
+    content: initialResponse.content,
+    timestamp: new Date(),
+  });
+
+  lastResponse = initialResponse.content;
+  logger.info(`Round 1: ${providers[0]} generated initial response`);
+
+  // Subsequent rounds: Alternate between providers
+  for (let i = 2; i <= iterations; i++) {
+    const isProviderA = i % 2 === 1;
+    const currentProvider = isProviderA ? providers[0] : providers[1];
+    const providerInfo = providerManager.getProvider(currentProvider);
+
+    const iterationPrompt = buildIterationPrompt(prompt, lastResponse, mode, i, rounds);
+
+    const response = await providerManager.askDuck(currentProvider, iterationPrompt);
+
+    // Check for convergence
+    if (checkConvergence(lastResponse, response.content)) {
+      converged = true;
+      logger.info(`Convergence detected at round ${i}`);
+    }
+
+    const role = mode === 'refine' ? 'refiner' : (i % 2 === 0 ? 'critic' : 'refiner');
+
+    rounds.push({
+      round: i,
+      provider: currentProvider,
+      nickname: providerInfo.nickname,
+      role,
+      content: response.content,
+      timestamp: new Date(),
+    });
+
+    lastResponse = response.content;
+    logger.info(`Round ${i}: ${currentProvider} ${role === 'critic' ? 'critiqued' : 'refined'}`);
+
+    if (converged) {
+      break;
+    }
+  }
+
+  const result: IterationResult = {
+    prompt,
+    mode,
+    providers,
+    rounds,
+    finalResponse: lastResponse,
+    totalIterations: rounds.length,
+    converged,
+  };
+
+  // Format output
+  const formattedOutput = formatIterationResult(result);
+
+  logger.info(`Iteration completed: ${rounds.length} rounds, converged: ${converged}`);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: formattedOutput,
+      },
+    ],
+  };
+}
+
+function buildIterationPrompt(
+  originalPrompt: string,
+  previousResponse: string,
+  mode: 'refine' | 'critique-improve',
+  round: number,
+  previousRounds: IterationRound[]
+): string {
+  if (mode === 'refine') {
+    return `You are refining a response through iterative improvement.
+
+ORIGINAL TASK:
+${originalPrompt}
+
+PREVIOUS RESPONSE (Round ${round - 1}):
+${previousResponse}
+
+YOUR TASK:
+Improve upon the previous response. Make it:
+- More accurate
+- More complete
+- Clearer and better structured
+- More practical and actionable
+
+Provide your improved version directly. Do not explain what you changed - just give the improved response.`;
+  } else {
+    // critique-improve mode
+    const isEvenRound = round % 2 === 0;
+
+    if (isEvenRound) {
+      // Critic round
+      return `You are a critical reviewer evaluating a response.
+
+ORIGINAL TASK:
+${originalPrompt}
+
+RESPONSE TO CRITIQUE:
+${previousResponse}
+
+YOUR TASK:
+Provide a thorough critique of this response:
+1. Identify specific weaknesses, errors, or gaps
+2. Point out unclear or confusing parts
+3. Suggest concrete improvements
+4. Note any missing considerations
+
+Be constructive but thorough. Format as a bulleted critique.`;
+    } else {
+      // Improvement round based on critique
+      const lastCritique = previousRounds[previousRounds.length - 1]?.content || '';
+      const lastGoodResponse = previousRounds[previousRounds.length - 2]?.content || previousResponse;
+
+      return `You are improving a response based on critical feedback.
+
+ORIGINAL TASK:
+${originalPrompt}
+
+PREVIOUS RESPONSE:
+${lastGoodResponse}
+
+CRITIQUE RECEIVED:
+${lastCritique}
+
+YOUR TASK:
+Create an improved response that addresses the critique points while maintaining the strengths of the original. Provide only the improved response, not meta-commentary.`;
+    }
+  }
+}
+
+function checkConvergence(previous: string, current: string): boolean {
+  // Simple similarity check based on length and common words
+  const prevWords = new Set(previous.toLowerCase().split(/\s+/));
+  const currWords = new Set(current.toLowerCase().split(/\s+/));
+
+  const intersection = new Set([...prevWords].filter(x => currWords.has(x)));
+  const union = new Set([...prevWords, ...currWords]);
+
+  const similarity = intersection.size / union.size;
+
+  // Also check if lengths are similar
+  const lengthRatio = Math.min(previous.length, current.length) / Math.max(previous.length, current.length);
+
+  return similarity > CONVERGENCE_THRESHOLD && lengthRatio > 0.8;
+}
+
+function formatIterationResult(result: IterationResult): string {
+  let output = `🔄 **Iterative Refinement Results**\n`;
+  output += `═══════════════════════════════════════\n\n`;
+  output += `**Mode:** ${result.mode}\n`;
+  output += `**Providers:** ${result.providers.join(' ↔ ')}\n`;
+  output += `**Iterations:** ${result.totalIterations}`;
+  if (result.converged) {
+    output += ` (converged early ✓)`;
+  }
+  output += `\n\n`;
+
+  // Show each round
+  output += `**Iteration History:**\n`;
+  output += `─────────────────────────────────────\n`;
+
+  for (const round of result.rounds) {
+    const roleEmoji = round.role === 'generator' ? '🎯' :
+                      round.role === 'critic' ? '🔍' : '✨';
+    output += `\n${roleEmoji} **Round ${round.round}: ${round.nickname}** (${round.role})\n`;
+
+    // Truncate long content for display
+    const displayContent = round.content.length > 500
+      ? round.content.substring(0, 500) + '...[truncated]'
+      : round.content;
+    output += `${displayContent}\n`;
+  }
+
+  // Final response
+  output += `\n═══════════════════════════════════════\n`;
+  output += `🏁 **Final Response:**\n`;
+  output += `─────────────────────────────────────\n`;
+  output += `${result.finalResponse}\n`;
+  output += `\n═══════════════════════════════════════\n`;
+  output += `📊 ${result.totalIterations} rounds completed\n`;
+
+  return output;
+}

package/src/tools/duck-judge.ts

@@ -0,0 +1,301 @@
+import { ProviderManager } from '../providers/manager.js';
+import { DuckResponse, JudgeEvaluation } from '../config/types.js';
+import { logger } from '../utils/logger.js';
+
+export interface DuckJudgeArgs {
+  responses: DuckResponse[];
+  judge?: string;
+  criteria?: string[];
+  persona?: string;
+}
+
+interface ParsedJudgment {
+  rankings: Array<{
+    provider: string;
+    score: number;
+    justification: string;
+  }>;
+  criteria_scores?: Record<string, Record<string, number>>;
+  summary: string;
+}
+
+const DEFAULT_CRITERIA = ['accuracy', 'completeness', 'clarity'];
+
+export async function duckJudgeTool(
+  providerManager: ProviderManager,
+  args: Record<string, unknown>
+) {
+  const {
+    responses,
+    judge,
+    criteria = DEFAULT_CRITERIA,
+    persona,
+  } = args as unknown as DuckJudgeArgs;
+
+  // Validate inputs
+  if (!responses || !Array.isArray(responses) || responses.length === 0) {
+    throw new Error('At least one response is required to judge');
+  }
+
+  if (responses.length === 1) {
+    throw new Error('At least two responses are required for comparison');
+  }
+
+  // Determine judge provider
+  const judgeProvider = judge || providerManager.getProviderNames()[0];
+  if (!judgeProvider) {
+    throw new Error('No judge provider available');
+  }
+
+  logger.info(`Starting judgment with ${judgeProvider} on ${responses.length} responses`);
+
+  // Build the judgment prompt
+  const prompt = buildJudgePrompt(responses, criteria, persona);
+
+  // Get judgment from the judge duck
+  const judgeResponse = await providerManager.askDuck(judgeProvider, prompt);
+
+  // Parse the judgment
+  const evaluation = parseJudgment(
+    judgeResponse.content,
+    judgeResponse.provider,
+    judgeResponse.nickname,
+    responses,
+    criteria
+  );
+
+  // Format output
+  const formattedOutput = formatJudgeResult(evaluation);
+
+  logger.info(
+    `Judgment completed by ${judgeProvider}: #1 is ${evaluation.rankings[0]?.provider || 'unknown'}`
+  );
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: formattedOutput,
+      },
+    ],
+  };
+}
+
+function buildJudgePrompt(
+  responses: DuckResponse[],
+  criteria: string[],
+  persona?: string
+): string {
+  const criteriaList = criteria.map((c, i) => `${i + 1}. ${c}`).join('\n');
+
+  const responsesText = responses.map((r, i) =>
+    `--- Response ${i + 1} (${r.nickname} / ${r.provider}) ---\n${r.content}\n`
+  ).join('\n');
+
+  const personaText = persona
+    ? `You are a ${persona} evaluating these responses.\n\n`
+    : '';
+
+  return `${personaText}You are a judge evaluating ${responses.length} responses to the same prompt.
+
+RESPONSES TO EVALUATE:
+${responsesText}
+
+EVALUATION CRITERIA:
+${criteriaList}
+
+INSTRUCTIONS:
+1. Evaluate each response against ALL criteria
+2. Assign a score from 0-100 for each response
+3. Rank responses from best to worst
+4. Provide a brief justification for each ranking
+5. Give a final summary
+
+Respond with ONLY a JSON object in this exact format:
+{
+  "rankings": [
+    {"provider": "<provider name>", "score": <0-100>, "justification": "<brief explanation>"},
+    {"provider": "<provider name>", "score": <0-100>, "justification": "<brief explanation>"}
+  ],
+  "criteria_scores": {
+    "<provider>": {${criteria.map(c => `"${c}": <0-100>`).join(', ')}}
+  },
+  "summary": "<overall assessment and recommendation>"
+}
+
+IMPORTANT:
+- Rankings must be ordered from highest score to lowest
+- Use the exact provider names from the responses
+- Do NOT include any text before or after the JSON
+- Do NOT use markdown code blocks`;
+}
+
+function matchProvider(
+  judgeProviderName: string,
+  originalResponses: DuckResponse[]
+): DuckResponse | undefined {
+  const nameLower = judgeProviderName.toLowerCase();
+
+  // Try exact match first
+  const exactMatch = originalResponses.find(r => r.provider.toLowerCase() === nameLower);
+  if (exactMatch) return exactMatch;
+
+  // Try matching by provider name contained in judge's response
+  const containsMatch = originalResponses.find(r =>
+    nameLower.includes(r.provider.toLowerCase()) ||
+    nameLower.includes(r.nickname.toLowerCase())
+  );
+  if (containsMatch) return containsMatch;
+
+  // Try matching by nickname
+  const nicknameMatch = originalResponses.find(r =>
+    r.nickname.toLowerCase() === nameLower
+  );
+  if (nicknameMatch) return nicknameMatch;
+
+  return undefined;
+}
+
+function parseJudgment(
+  response: string,
+  judgeProvider: string,
+  judgeNickname: string,
+  originalResponses: DuckResponse[],
+  criteria: string[]
+): JudgeEvaluation {
+  const evaluation: JudgeEvaluation = {
+    judge: judgeProvider,
+    judgeNickname: judgeNickname,
+    prompt: '', // Will be filled by caller if needed
+    criteria,
+    rankings: [],
+    criteriaScores: {},
+    summary: '',
+    rawResponse: response,
+  };
+
+  try {
+    // Try to extract JSON from the response
+    const jsonMatch = response.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      logger.warn(`No JSON found in judge response from ${judgeProvider}`);
+      return createFallbackEvaluation(evaluation, originalResponses, response);
+    }
+
+    const parsed = JSON.parse(jsonMatch[0]) as ParsedJudgment;
+    const matchedProviders = new Set<string>();
+
+    // Parse rankings
+    if (Array.isArray(parsed.rankings)) {
+      for (const [index, r] of parsed.rankings.entries()) {
+        const matched = matchProvider(r.provider, originalResponses);
+        if (matched && !matchedProviders.has(matched.provider)) {
+          matchedProviders.add(matched.provider);
+          evaluation.rankings.push({
+            provider: matched.provider,
+            nickname: matched.nickname,
+            rank: index + 1,
+            score: typeof r.score === 'number' ? Math.max(0, Math.min(100, r.score)) : 0,
+            justification: r.justification?.toString() || '',
+          });
+        }
+      }
+    }
+
+    // Parse criteria scores
+    if (parsed.criteria_scores && typeof parsed.criteria_scores === 'object') {
+      evaluation.criteriaScores = parsed.criteria_scores;
+    }
+
+    // Parse summary
+    if (parsed.summary) {
+      evaluation.summary = parsed.summary.toString();
+    }
+
+  } catch (error) {
+    logger.warn(`Failed to parse JSON judgment from ${judgeProvider}:`, error);
+    return createFallbackEvaluation(evaluation, originalResponses, response);
+  }
+
+  // Ensure all original responses are represented
+  const rankedProviders = new Set(evaluation.rankings.map(r => r.provider));
+  for (const resp of originalResponses) {
+    if (!rankedProviders.has(resp.provider)) {
+      evaluation.rankings.push({
+        provider: resp.provider,
+        nickname: resp.nickname,
+        rank: evaluation.rankings.length + 1,
+        score: 0,
+        justification: 'Not evaluated by judge',
+      });
+    }
+  }
+
+  return evaluation;
+}
+
+function createFallbackEvaluation(
+  evaluation: JudgeEvaluation,
+  originalResponses: DuckResponse[],
+  rawResponse: string
+): JudgeEvaluation {
+  // Create a basic evaluation when parsing fails
+  evaluation.rankings = originalResponses.map((r, index) => ({
+    provider: r.provider,
+    nickname: r.nickname,
+    rank: index + 1,
+    score: 50,
+    justification: 'Unable to parse judge response',
+  }));
+  evaluation.summary = `Judge evaluation parsing failed. Raw response available for review.`;
+  evaluation.rawResponse = rawResponse;
+  return evaluation;
+}
+
+function formatJudgeResult(evaluation: JudgeEvaluation): string {
+  let output = `⚖️ **Judge Evaluation**\n`;
+  output += `═══════════════════════════════════════\n\n`;
+  output += `**Judge:** ${evaluation.judgeNickname} (${evaluation.judge})\n`;
+  output += `**Criteria:** ${evaluation.criteria.join(', ')}\n\n`;
+
+  // Rankings
+  output += `**Rankings:**\n`;
+  output += `─────────────────────────────────────\n`;
+
+  for (const ranking of evaluation.rankings) {
+    const medal = ranking.rank === 1 ? '🥇' : ranking.rank === 2 ? '🥈' : ranking.rank === 3 ? '🥉' : '  ';
+    const bar = '█'.repeat(Math.floor(ranking.score / 10));
+    const emptyBar = '░'.repeat(10 - Math.floor(ranking.score / 10));
+
+    output += `${medal} **#${ranking.rank} ${ranking.nickname}** (${ranking.provider})\n`;
+    output += `   Score: ${bar}${emptyBar} ${ranking.score}/100\n`;
+    output += `   💭 "${ranking.justification}"\n\n`;
+  }
+
+  // Criteria breakdown if available
+  if (Object.keys(evaluation.criteriaScores).length > 0) {
+    output += `**Criteria Breakdown:**\n`;
+    output += `─────────────────────────────────────\n`;
+
+    for (const [provider, scores] of Object.entries(evaluation.criteriaScores)) {
+      output += `📊 **${provider}:**\n`;
+      for (const [criterion, score] of Object.entries(scores)) {
+        const criterionScore = typeof score === 'number' ? score : 0;
+        output += `   • ${criterion}: ${criterionScore}/100\n`;
+      }
+      output += `\n`;
+    }
+  }
+
+  // Summary
+  if (evaluation.summary) {
+    output += `**Summary:**\n`;
+    output += `─────────────────────────────────────\n`;
+    output += `${evaluation.summary}\n\n`;
+  }
+
+  output += `═══════════════════════════════════════\n`;
+  output += `📋 Evaluated ${evaluation.rankings.length} responses\n`;
+
+  return output;
+}

package/src/tools/duck-vote.ts

@@ -0,0 +1,87 @@
+import { ProviderManager } from '../providers/manager.js';
+import { ConsensusService } from '../services/consensus.js';
+import { VoteResult } from '../config/types.js';
+import { logger } from '../utils/logger.js';
+
+export interface DuckVoteArgs {
+  question: string;
+  options: string[];
+  voters?: string[];
+  require_reasoning?: boolean;
+}
+
+export async function duckVoteTool(
+  providerManager: ProviderManager,
+  args: Record<string, unknown>
+) {
+  const {
+    question,
+    options,
+    voters,
+    require_reasoning = true,
+  } = args as unknown as DuckVoteArgs;
+
+  // Validate inputs
+  if (!question || typeof question !== 'string') {
+    throw new Error('Question is required');
+  }
+
+  if (!options || !Array.isArray(options) || options.length < 2) {
+    throw new Error('At least 2 options are required');
+  }
+
+  if (options.length > 10) {
+    throw new Error('Maximum 10 options allowed');
+  }
+
+  // Get voters (all providers if not specified)
+  const voterNames = voters && voters.length > 0
+    ? voters
+    : providerManager.getProviderNames();
+
+  if (voterNames.length === 0) {
+    throw new Error('No voters available');
+  }
+
+  logger.info(`Starting vote with ${voterNames.length} voters on: "${question}"`);
+
+  const consensusService = new ConsensusService();
+  const votePrompt = consensusService.buildVotePrompt(
+    question,
+    options,
+    require_reasoning
+  );
+
+  // Get votes from all ducks in parallel
+  const responses = await providerManager.compareDucks(votePrompt, voterNames);
+
+  // Parse votes
+  const votes: VoteResult[] = responses.map(response => {
+    return consensusService.parseVote(
+      response.content,
+      response.provider,
+      response.nickname,
+      options
+    );
+  });
+
+  // Aggregate results
+  const aggregatedResult = consensusService.aggregateVotes(question, options, votes);
+
+  // Format output
+  const formattedOutput = consensusService.formatVoteResult(aggregatedResult);
+
+  logger.info(
+    `Vote completed: ${aggregatedResult.consensusLevel} consensus, ` +
+    `winner: ${aggregatedResult.winner || 'none'}`
+  );
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: formattedOutput,
+      },
+    ],
+  };
+}