dialectic 0.1.0

package/src/cli/commands/report.ts

@@ -0,0 +1,265 @@
+import { Command } from 'commander';
+import { EXIT_INVALID_ARGS, EXIT_GENERAL_ERROR } from '../../utils/exit-codes';
+import { infoUser, writeStderr } from '../index';
+import { loadConfig } from './debate';
+import { SystemConfig } from '../../types/config.types';
+import { DebateState } from '../../types/debate.types';
+import { AgentConfig, AGENT_ROLES, LLM_PROVIDERS } from '../../types/agent.types';
+import { generateDebateReport } from '../../utils/report-generator';
+import { createValidationError, readJsonFile, writeFileWithDirectories } from '../../utils/common';
+
+// Error message constants
+const ERROR_INVALID_DEBATE_JSON = 'Invalid debate JSON';
+const ERROR_MISSING_FIELD = 'missing or invalid';
+const ERROR_MISSING_ID_FIELD = `${ERROR_INVALID_DEBATE_JSON}: ${ERROR_MISSING_FIELD} id field`;
+const ERROR_MISSING_PROBLEM_FIELD = `${ERROR_INVALID_DEBATE_JSON}: ${ERROR_MISSING_FIELD} problem field`;
+const ERROR_MISSING_STATUS_FIELD = `${ERROR_INVALID_DEBATE_JSON}: ${ERROR_MISSING_FIELD} status field`;
+const ERROR_MISSING_ROUNDS_FIELD = `${ERROR_INVALID_DEBATE_JSON}: ${ERROR_MISSING_FIELD} rounds array`;
+
+/**
+ * Revives Date objects in a debate state that were serialized as strings.
+ * 
+ * @param debateState - The debate state to revive dates in.
+ */
+function reviveDatesInDebateState(debateState: DebateState): void {
+  // Revive top-level dates
+  if (debateState.createdAt && typeof debateState.createdAt === 'string') {
+    debateState.createdAt = new Date(debateState.createdAt);
+  }
+  if (debateState.updatedAt && typeof debateState.updatedAt === 'string') {
+    debateState.updatedAt = new Date(debateState.updatedAt);
+  }
+  
+  // Revive round timestamps
+  for (const round of debateState.rounds) {
+    if (round.timestamp && typeof round.timestamp === 'string') {
+      round.timestamp = new Date(round.timestamp);
+    }
+  }
+}
+
+/**
+ * Loads and validates a debate state from a JSON file.
+ * 
+ * @param debatePath - Path to the debate JSON file.
+ * @returns The loaded and validated DebateState.
+ * @throws {Error} If the file doesn't exist, is invalid JSON, or lacks required fields.
+ */
+function loadAndValidateDebateState(debatePath: string): DebateState {
+  const debate: DebateState = readJsonFile<DebateState>(debatePath, 'Debate file');
+  
+  // Validate required fields
+  if (!debate.id || typeof debate.id !== 'string') {
+    throw createValidationError(ERROR_MISSING_ID_FIELD, EXIT_INVALID_ARGS);
+  }
+  if (!debate.problem || typeof debate.problem !== 'string') {
+    throw createValidationError(ERROR_MISSING_PROBLEM_FIELD, EXIT_INVALID_ARGS);
+  }
+  if (!debate.status || typeof debate.status !== 'string') {
+    throw createValidationError(ERROR_MISSING_STATUS_FIELD, EXIT_INVALID_ARGS);
+  }
+  if (!Array.isArray(debate.rounds)) {
+    throw createValidationError(ERROR_MISSING_ROUNDS_FIELD, EXIT_INVALID_ARGS);
+  }
+  
+  // Revive Date objects if they were serialized as strings
+  reviveDatesInDebateState(debate);
+  
+  return debate;
+}
+
+/**
+ * Extracts unique agent IDs and roles from the debate state by examining all contributions.
+ * 
+ * @param debateState - The debate state to extract agent IDs from.
+ * @returns Map of agent IDs to their roles.
+ */
+function extractAgentInfoFromDebate(debateState: DebateState): Map<string, string> {
+  const agentInfo = new Map<string, string>();
+  
+  for (const round of debateState.rounds) {
+    for (const contribution of round.contributions) {
+      if (contribution.agentId && contribution.agentRole) {
+        // Only set if not already set (first occurrence wins)
+        if (!agentInfo.has(contribution.agentId)) {
+          agentInfo.set(contribution.agentId, contribution.agentRole);
+        }
+      }
+    }
+  }
+  
+  return agentInfo;
+}
+
+/**
+ * Creates minimal agent configurations from debate state when config file is not provided.
+ * 
+ * @param debateState - The debate state to extract agent information from.
+ * @returns Array of minimal agent configurations.
+ */
+function createMinimalAgentConfigsFromDebate(debateState: DebateState): AgentConfig[] {
+  const agentInfo = extractAgentInfoFromDebate(debateState);
+  const agentConfigs: AgentConfig[] = [];
+  
+  for (const [agentId, role] of agentInfo.entries()) {
+    // Validate role is a valid AgentRole, default to 'architect' if invalid
+    const validRoleValues = Object.values(AGENT_ROLES) as string[];
+    const validRole = validRoleValues.includes(role) 
+      ? (role as typeof AGENT_ROLES[keyof typeof AGENT_ROLES])
+      : AGENT_ROLES.ARCHITECT;
+    
+    // Create minimal config with only required fields
+    agentConfigs.push({
+      id: agentId,
+      name: agentId, // Use ID as name fallback
+      role: validRole,
+      model: 'N/A',
+      provider: LLM_PROVIDERS.OPENAI,
+      temperature: 0.5 // Default temperature
+    });
+  }
+  
+  return agentConfigs;
+}
+
+/**
+ * Creates a minimal judge configuration when config file is not provided.
+ * 
+ * @param debateState - The debate state (may contain judge info in finalSolution).
+ * @returns Minimal judge configuration.
+ */
+function createMinimalJudgeConfigFromDebate(debateState: DebateState): AgentConfig {
+  // Extract judge ID from finalSolution if available
+  const judgeId = debateState.finalSolution?.synthesizedBy || 'judge-main';
+  
+  return {
+    id: judgeId,
+    name: judgeId,
+    role: AGENT_ROLES.GENERALIST,
+    model: 'N/A',
+    provider: LLM_PROVIDERS.OPENAI,
+    temperature: 0.3 // Default judge temperature
+  };
+}
+
+/**
+ * Matches agent configurations from the config file with agent IDs found in the debate state.
+ * 
+ * @param sysConfig - The system configuration containing agent configs.
+ * @param agentIds - Array of agent IDs found in the debate state.
+ * @returns Array of agent configurations that match the agent IDs in the debate.
+ */
+function matchAgentConfigsFromSysConfig(sysConfig: SystemConfig, agentIds: string[]): AgentConfig[] {
+  return agentIds
+    .map((agentId) => sysConfig.agents.find((a) => a.id === agentId))
+    .filter((config): config is AgentConfig => config !== undefined);
+}
+
+/**
+ * Writes the report content to stdout or a file.
+ * 
+ * If no output path is provided, writes to stdout (for piping/redirection).
+ * If an output path is provided, creates parent directories if needed and writes the file,
+ * overwriting any existing file at that path.
+ * 
+ * @param reportContent - The markdown report content to write.
+ * @param outputPath - Optional path to output file. If not provided, writes to stdout.
+ * @throws {Error} If file writing fails.
+ */
+async function writeReport(reportContent: string, outputPath?: string): Promise<void> {
+  if (!outputPath) {
+    // Write to stdout (allows piping: report --debate file.json > output.md)
+    process.stdout.write(reportContent);
+    return;
+  }
+  
+  // Write to file (handles path normalization and directory creation)
+  const writtenPath = await writeFileWithDirectories(outputPath, reportContent);
+  infoUser(`Generated report: ${writtenPath}`);
+}
+
+/**
+ * Registers the 'report' CLI command, which generates a markdown report from a saved debate state.
+ * 
+ * This command loads a debate state JSON file, loads the corresponding configuration file,
+ * matches agent configurations with agent IDs found in the debate, and generates a markdown report.
+ * 
+ * @param program - Commander.js program object to which the command is added.
+ * 
+ * Command-line Options:
+ *   --debate <path>      Required: Path to debate JSON file (DebateState format).
+ *   --config <path>      Optional: Path to configuration file. If not provided, creates minimal configs from debate state.
+ *   --output <path>      Optional: Path to output markdown file. If not provided, writes to stdout.
+ *   -v, --verbose        Optional: Enable verbose mode for report generation.
+ * 
+ * Behavior:
+ *   - Loads and validates the debate state file.
+ *   - If --config is provided: loads configuration file and matches agent/judge configs with IDs found in debate state.
+ *   - If --config is not provided: creates minimal agent/judge configs from debate state (no validation of IDs).
+ *   - Generates markdown report using generateDebateReport.
+ *   - Writes report to file or stdout.
+ * 
+ * Errors:
+ *   - Exits with explicit error codes and user-friendly messages on invalid arguments,
+ *     missing files, or report generation failures.
+ */
+export function reportCommand(program: Command) {
+  program
+    .command('report')
+    .requiredOption('--debate <path>', 'Path to debate JSON file (DebateState)')
+    .option('--config <path>', 'Path to configuration file (default: ./debate-config.json)')
+    .option('-o, --output <path>', 'Path to output markdown file (default: stdout)')
+    .option('-v, --verbose', 'Verbose mode for report generation')
+    .description('Generate a markdown report from a saved debate state')
+    .action(async (options: any) => {
+      try {
+        // Load and validate debate state
+        const debateState = loadAndValidateDebateState(options.debate);
+        
+        let agentConfigs: AgentConfig[];
+        let judgeConfig: AgentConfig;
+        
+        // Only load config if --config is explicitly provided
+        if (options.config) {
+          // Load configuration to get agent and judge configs
+          const sysConfig = await loadConfig(options.config);
+          
+          // Extract agent IDs from debate state
+          const agentInfo = extractAgentInfoFromDebate(debateState);
+          const agentIds = Array.from(agentInfo.keys());
+          
+          // Match agent configs with agent IDs from debate
+          agentConfigs = matchAgentConfigsFromSysConfig(sysConfig, agentIds);
+          
+          // Get judge config (loadConfig ensures judge is always present, either from config or defaults)
+          // This check is defensive but should never fail in practice
+          if (!sysConfig.judge) {
+            throw createValidationError('Configuration missing judge definition', EXIT_INVALID_ARGS);
+          }
+          judgeConfig = sysConfig.judge;
+        } else {
+          // No config provided - create minimal configs from debate state
+          agentConfigs = createMinimalAgentConfigsFromDebate(debateState);
+          judgeConfig = createMinimalJudgeConfigFromDebate(debateState);
+        }
+        
+        // Generate report
+        const reportContent = generateDebateReport(
+          debateState,
+          agentConfigs,
+          judgeConfig,
+          debateState.problem,
+          { verbose: options.verbose || false }
+        );
+        
+        // Write report
+        await writeReport(reportContent, options.output);
+      } catch (err: any) {
+        const code = typeof err?.code === 'number' ? err.code : EXIT_GENERAL_ERROR;
+        writeStderr((err?.message || 'Unknown error') + '\n');
+        // Rethrow for runCli catch to set process exit when direct run
+        throw Object.assign(new Error(err?.message || 'Unknown error'), { code });
+      }
+    });
+}
+

package/src/cli/index.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { debateCommand, loadConfig as loadDebateConfig } from './commands/debate';
+import { evalCommand } from './commands/eval';
+import { reportCommand } from './commands/report';
+import { EXIT_GENERAL_ERROR } from '../utils/exit-codes';
+
+// Color constants for CLI output
+export const WARNING_COLOR = 'yellow';
+export const INFO_COLOR = 'gray';
+export const PROGRAM_NAME = 'dialectic';
+
+// Lazy optional chalk import for colored output
+let chalk: any;
+try { chalk = require('chalk'); } catch { chalk = null; }
+
+function color(method: string, msg: string): string {
+  return chalk && chalk[method] ? chalk[method](msg) : msg;
+}
+
+/**
+ * Outputs a warning message to stderr with consistent formatting.
+ * Used for user-facing warnings throughout the CLI.
+ */
+export function warnUser(message: string): void {
+  process.stderr.write(color(WARNING_COLOR, message) + '\n');
+}
+
+/**
+ * Outputs an info message to stderr with consistent formatting.
+ * Used for user-facing informational messages throughout the CLI.
+ */
+export function infoUser(message: string): void {
+  process.stderr.write(color(INFO_COLOR, message) + '\n');
+}
+
+/**
+ * Outputs a diagnostic/verbose message to stderr without coloring.
+ * Used for structured diagnostic output that should not interfere with stdout piping.
+ */
+export function writeStderr(message: string): void {
+  process.stderr.write(message);
+}
+
+/**
+ * Runs the CLI for the multi-agent debate system.
+ *
+ * This function sets up the command-line interface using Commander,
+ * registers available commands (such as 'debate'), and parses the provided arguments.
+ * It is intended to be called with the argument vector (argv) excluding the node and script name.
+ *
+ * @param argv - The array of command-line arguments to parse (excluding 'node' and script name).
+ * @throws Any error encountered during command parsing.
+ */
+export async function runCli(argv: string[]) {
+  const program = new Command();
+  program.name(PROGRAM_NAME).description('Multi-agent debate system').version('0.1.0');
+
+  // Register commands
+  debateCommand(program);
+  evalCommand(program);
+  reportCommand(program);
+
+  await program.parseAsync(['node', PROGRAM_NAME, ...argv]);
+}
+
+// If called directly from node
+if (require.main === module) {
+  runCli(process.argv.slice(2)).catch((err: any) => {
+    // Map generic error when not already code-tagged
+    const code = typeof err?.code === 'number' ? err.code : EXIT_GENERAL_ERROR;
+    const msg = err?.message || 'Unknown error';
+    process.stderr.write(msg + '\n');
+    process.exit(code);
+  });
+}
+
+// Re-export config loader for tests
+export const loadConfig = loadDebateConfig;

package/src/core/agent.ts

@@ -0,0 +1,198 @@
+import { AgentConfig, Proposal, Critique, ContributionMetadata } from '../types/agent.types';
+import { DebateContext, ContextPreparationResult, ClarificationQuestionsResponse } from '../types/debate.types';
+import { LLMProvider } from '../providers/llm-provider';
+import { CompletionResponse, CompletionUsage } from '../providers/llm-provider';
+
+
+
+/**
+ * Abstract base class representing an AI agent in the multi-agent debate system.
+ *
+ * Agents are responsible for generating proposals, critiquing other agents' proposals,
+ * and refining their own proposals based on received critiques. Each agent is configured
+ * with a specific role, LLM model, and provider, and interacts with an LLMProvider to
+ * generate its outputs.
+ *
+ * Additionally, agents manage context summarization to handle large debate histories.
+ *
+ * Subclasses must implement the core debate methods:
+ *  - propose: Generate a solution proposal for a given problem.
+ *  - critique: Critique another agent's proposal.
+ *  - refine: Refine an original proposal by incorporating critiques.
+ *  - shouldSummarize: Determine if context summarization is needed.
+ *  - prepareContext: Prepare and potentially summarize the debate context.
+ *
+ * The base class provides a utility method, callLLM, to standardize LLM interactions,
+ * capturing latency and usage metadata.
+ *
+ * @template Proposal - The type representing a proposal response.
+ * @template Critique - The type representing a critique response.
+ */
+export abstract class Agent {
+  /**
+   * Constructs an Agent.
+   * @param config - The agent's configuration, including model, role, and prompts.
+   * @param provider - The LLMProvider instance used for LLM interactions.
+   */
+  constructor(public config: AgentConfig, protected provider: LLMProvider) {}
+
+  /**
+   * Generates a proposal for the given problem.
+   * @param problem - The software design problem to solve.
+   * @param context - The current debate context, including history and state.
+   * @returns A Promise resolving to a Proposal object containing the agent's solution and metadata.
+   */
+  abstract propose(problem: string, context: DebateContext): Promise<Proposal>;
+
+  /**
+   * Critiques a given proposal from another agent.
+   * @param proposal - The proposal to critique.
+   * @param context - The current debate context.
+   * @returns A Promise resolving to a Critique object containing the agent's review and metadata.
+   */
+  abstract critique(proposal: Proposal, context: DebateContext): Promise<Critique>;
+
+  /**
+   * Refines the agent's original proposal by addressing critiques and incorporating suggestions.
+   * @param originalProposal - The original proposal to refine.
+   * @param critiques - Array of critiques to address.
+   * @param context - The current debate context.
+   * @returns A Promise resolving to a new Proposal object with the refined solution and metadata.
+   */
+  abstract refine(originalProposal: Proposal, critiques: Critique[], context: DebateContext): Promise<Proposal>;
+
+  /**
+   * Determines whether the debate context should be summarized based on configured thresholds.
+   * 
+   * @param context - The current debate context to evaluate.
+   * @returns True if summarization should occur, false otherwise.
+   */
+  abstract shouldSummarize(context: DebateContext): boolean;
+
+  /**
+   * Prepares the debate context for the agent, potentially summarizing it if needed.
+   * 
+   * This method evaluates whether summarization is necessary and, if so, generates
+   * a concise summary of the debate history from the agent's perspective.
+   * 
+   * @param context - The current debate context.
+   * @param roundNumber - The current round number (1-indexed).
+   * @returns A promise resolving to the context preparation result.
+   */
+  abstract prepareContext( context: DebateContext, roundNumber: number ): Promise<ContextPreparationResult>;
+
+  /**
+   * Requests role-specific clarifying questions before the debate starts.
+   * Implementations should return ONLY structured questions; zero or more items are allowed.
+   *
+   * @param problem - The software design problem to clarify.
+   * @param context - The current debate context.
+   */
+  abstract askClarifyingQuestions(problem: string, context: DebateContext): Promise<ClarificationQuestionsResponse>;
+
+  /**
+   * Template method for generating proposals.
+   * Subclasses should call this method from their `propose` implementation after preparing prompts.
+   *
+   * @final
+   * @param _context - The current debate context (unused in base implementation).
+   * @param systemPrompt - The system prompt to use for the LLM.
+   * @param userPrompt - The user prompt to use for the LLM.
+   * @returns A Promise resolving to a Proposal object containing the agent's solution and metadata.
+   */
+  protected async proposeImpl(
+
+    _context: DebateContext,
+    systemPrompt: string,
+    userPrompt: string
+  ): Promise<Proposal> {
+    const { text, usage, latencyMs } = await this.callLLM(systemPrompt, userPrompt);
+    const metadata: ContributionMetadata = { latencyMs, model: this.config.model };
+    if (usage?.totalTokens != null) metadata.tokensUsed = usage.totalTokens;
+    return { content: text, metadata };
+  }
+
+  /**
+   * Template method for generating critiques.
+   * Subclasses should call this method from their `critique` implementation after preparing prompts.
+   *
+   * @final
+   * @param _proposal - The proposal to critique.
+   * @param _context - The current debate context.
+   * @param systemPrompt - The system prompt to use for the LLM.
+   * @param userPrompt - The user prompt to use for the LLM.
+   * @returns A Promise resolving to a Critique object containing the agent's review and metadata.
+   */
+  protected async critiqueImpl(
+    _proposal: Proposal,
+    _context: DebateContext,
+    systemPrompt: string,
+    userPrompt: string
+  ): Promise<Critique> {
+    const { text, usage, latencyMs } = await this.callLLM(systemPrompt, userPrompt);
+    const metadata: ContributionMetadata = { latencyMs, model: this.config.model };
+    if (usage?.totalTokens != null) metadata.tokensUsed = usage.totalTokens;
+    return { content: text, metadata };
+  }
+
+  /**
+   * Template method for refining proposals.
+   * Subclasses should call this method from their `refine` implementation after preparing prompts.
+   *
+   * @final
+   * @param _originalProposal - The original proposal to refine.
+   * @param _critiques - Array of critiques to address.
+   * @param _context - The current debate context.
+   * @param systemPrompt - The system prompt to use for the LLM.
+   * @param userPrompt - The user prompt to use for the LLM.
+   * @returns A Promise resolving to a refined Proposal object with updated content and metadata.
+   */
+  protected async refineImpl(
+    _originalProposal: Proposal,
+    _critiques: Critique[],
+    _context: DebateContext,
+    systemPrompt: string,
+    userPrompt: string
+  ): Promise<Proposal> {
+    const { text, usage, latencyMs } = await this.callLLM(systemPrompt, userPrompt);
+    const metadata: ContributionMetadata = { latencyMs, model: this.config.model };
+    if (usage?.totalTokens != null) metadata.tokensUsed = usage.totalTokens;
+    return { content: text, metadata };
+  }
+
+  /**
+   * Helper method to call the underlying LLM provider with the specified prompts.
+   * Measures latency and returns the generated text, usage statistics, and latency.
+   *
+   * @param systemPrompt - The system prompt to prime the LLM.
+   * @param userPrompt - The user prompt representing the agent's request.
+   * @returns A Promise resolving to an AgentLLMResponse containing text, usage metadata, and latency.
+   */
+  protected async callLLM(systemPrompt: string, userPrompt: string): Promise<AgentLLMResponse> {
+    const started = Date.now();
+    const res : CompletionResponse = await this.provider.complete({
+      model: this.config.model,
+      temperature: this.config.temperature,
+      systemPrompt,
+      userPrompt,
+    });
+    const latencyMs = Date.now() - started;
+    const response: AgentLLMResponse = { text: res.text, latencyMs };
+    if (res.usage) response.usage = res.usage;
+    return response;
+  }
+}
+
+
+/**
+ * Represents the response from an LLM call made by an agent.
+ *
+ * @property text - The main textual output generated by the LLM.
+ * @property usage - (Optional) Token usage statistics for the LLM call.
+ * @property latencyMs - The time taken (in milliseconds) to complete the LLM call.
+ */
+export interface AgentLLMResponse {
+  text: string;
+  usage?: CompletionUsage;
+  latencyMs: number;
+}

package/src/core/clarifications.ts

@@ -0,0 +1,34 @@
+import { Agent } from './agent';
+import { AgentClarifications } from '../types/debate.types';
+
+/**
+ * Collects clarifying questions from each agent, enforcing a per-agent limit and returning
+ * normalized groups with empty answers to be filled by the CLI.
+ *
+ * @param problem - The problem statement to clarify
+ * @param agents - List of agents participating
+ * @param maxPerAgent - Maximum number of questions allowed per agent
+ * @param warn - Warning output function for user-facing messages
+ */
+export async function collectClarifications( problem: string, agents: Agent[], maxPerAgent: number, warn: (message: string) => void ): Promise<AgentClarifications[]>
+{
+  const agentPromises = agents.map(async (a) => {
+    const ctx = { problem } as any;
+    const res = await a.askClarifyingQuestions(problem, ctx);
+    const list = Array.isArray(res?.questions) ? res.questions : [];
+    const truncated = list.slice(0, maxPerAgent);
+    if (list.length > maxPerAgent) {
+      warn(`Agent ${a.config.name} returned ${list.length} questions; limited to ${maxPerAgent}.`);
+    }
+    return {
+      agentId: a.config.id,
+      agentName: a.config.name,
+      role: a.config.role,
+      items: truncated.map((q) => ({ id: q.id!, question: q.text, answer: '' }))
+    };
+  });
+
+  return Promise.all(agentPromises);
+}
+
+