dialectic 0.1.0

package/src/types/eval.types.ts

@@ -0,0 +1,85 @@
+import { LLM_PROVIDERS } from './agent.types';
+
+export interface EvaluatorConfig {
+  id: string;
+  name: string;
+  model: string;
+  provider: typeof LLM_PROVIDERS.OPENAI | typeof LLM_PROVIDERS.OPENROUTER;
+  systemPromptPath?: string;
+  userPromptPath?: string;
+  timeout?: number; // milliseconds (ignored for execution after refactor)
+  enabled?: boolean; // default true
+}
+
+export interface EvaluatorRunOptions {
+  verbose?: boolean;
+}
+
+export interface EvaluatorInputs {
+  problem: string;
+  clarificationsMarkdown: string; // fenced code blocks including NA entries
+  finalSolution: string;
+}
+
+export interface ParsedEvaluation {
+  evaluation?: {
+    functional_completeness?: {
+      score?: number;
+      reasoning?: string;
+    };
+    non_functional?: {
+      performance_scalability?: { score?: number; reasoning?: string };
+      security?: { score?: number; reasoning?: string };
+      maintainability_evolvability?: { score?: number; reasoning?: string };
+      regulatory_compliance?: { score?: number; reasoning?: string };
+      testability?: { score?: number; reasoning?: string };
+    };
+  };
+  overall_summary?: {
+    strengths?: string;
+    weaknesses?: string;
+    overall_score?: number;
+  };
+}
+
+export interface AggregatedAverages {
+  functional_completeness: number | null; // null => N/A
+  performance_scalability: number | null;
+  security: number | null;
+  maintainability_evolvability: number | null;
+  regulatory_compliance: number | null;
+  testability: number | null;
+  overall_score: number | null;
+}
+
+export interface AggregatedJsonOutput {
+  evaluation: {
+    functional_completeness: { average_score: number | null };
+    non_functional: {
+      performance_scalability: { average_score: number | null };
+      security: { average_score: number | null };
+      maintainability_evolvability: { average_score: number | null };
+      regulatory_compliance: { average_score: number | null };
+      testability: { average_score: number | null };
+    };
+  };
+  overall_score: number | null;
+  agents: Record<string, ParsedEvaluation>; // keyed by evaluator id
+}
+
+export function isEnabledEvaluator(cfg: EvaluatorConfig): boolean {
+  return cfg.enabled !== false;
+}
+
+export function clampScoreToRange(val: unknown): number | undefined {
+  if (typeof val !== 'number' || !Number.isFinite(val)) return undefined;
+  if (val < 1) return 1;
+  if (val > 10) return 10;
+  return val;
+}
+
+export function round2(val: number): number {
+  return Math.round((val + Number.EPSILON) * 100) / 100;
+}
+
+

package/src/utils/common.ts

@@ -0,0 +1,104 @@
+import fs from 'fs';
+import path from 'path';
+import { round2 } from '../types/eval.types';
+import { EXIT_INVALID_ARGS } from './exit-codes';
+
+const FILE_ENCODING_UTF8 = 'utf-8';
+
+/**
+ * Validates that a value is a finite number and returns it, or undefined if invalid.
+ * 
+ * @param x - The value to validate as a number.
+ * @returns The number if valid and finite, otherwise undefined.
+ */
+export function numOrUndefined(x: unknown): number | undefined {
+  return typeof x === 'number' && Number.isFinite(x) ? x : undefined;
+}
+
+/**
+ * Calculates the average of an array of numbers.
+ * 
+ * @param {number[]} values - An array of numbers to average.
+ * @returns {number | null} The average rounded to 2 decimal places, or null if the array is empty.
+ */
+export function averageOrNull(values: number[]): number | null {
+  if (values.length === 0) return null;
+  const sum = values.reduce((a, b) => a + b, 0);
+  return round2(sum / values.length);
+}
+
+/**
+ * Creates a validation error with a custom error code.
+ * 
+ * This function is used throughout the CLI to create errors with specific exit codes
+ * for validation failures and invalid arguments.
+ * 
+ * @param message - The error message to associate with the error.
+ * @param code - The numeric error code indicating the exit or validation type.
+ * @returns An Error object with the specified message and an added 'code' property.
+ */
+export function createValidationError(message: string, code: number): Error {
+  const err: any = new Error(message);
+  err.code = code;
+  return err;
+}
+
+/**
+ * Reads a JSON file from the given path, validates its existence and file type, parses its contents,
+ * and returns the parsed object. Throws a validation error with an appropriate exit code if the file 
+ * does not exist, is not a regular file, or does not contain valid JSON.
+ * 
+ * @template T The expected return type for the parsed JSON object.
+ * @param filePath - The path to the JSON file, relative to the current working directory.
+ * @param errorContext - Optional context to include in error messages (e.g., "Debate file", "Config file").
+ *                       Defaults to "File" if not provided.
+ * @returns The parsed JSON object of type T.
+ * @throws {Error} Throws a validation error with a specific exit code if:
+ *   - The file does not exist (EXIT_INVALID_ARGS).
+ *   - The path is not a file (EXIT_INVALID_ARGS).
+ *   - The file contains invalid JSON (EXIT_INVALID_ARGS).
+ */
+export function readJsonFile<T>(filePath: string, errorContext: string = 'File'): T {
+  const abs = path.resolve(process.cwd(), filePath);
+  if (!fs.existsSync(abs)) {
+    throw createValidationError(`${errorContext} not found: ${abs}`, EXIT_INVALID_ARGS);
+  }
+  const stat = fs.statSync(abs);
+  if (!stat.isFile()) {
+    throw createValidationError(`Path is not a file: ${abs}`, EXIT_INVALID_ARGS);
+  }
+  const raw = fs.readFileSync(abs, FILE_ENCODING_UTF8);
+  try {
+    return JSON.parse(raw) as T;
+  } catch (parseError: unknown) {
+    const message = parseError instanceof Error ? parseError.message : 'Unknown parsing error';
+    throw createValidationError(`Invalid JSON format in ${errorContext.toLowerCase()}: ${abs} (${message})`, EXIT_INVALID_ARGS);
+  }
+}
+
+/**
+ * Writes content to a file, creating parent directories if needed.
+ * Normalizes the path relative to the current working directory and ensures
+ * all parent directories exist before writing the file.
+ * 
+ * @param relativePath - The file path relative to the current working directory.
+ * @param content - The content to write to the file.
+ * @returns Promise resolving to the absolute path of the file that was written.
+ * @throws {Error} Propagates any errors from file system operations (directory creation or file writing).
+ */
+export async function writeFileWithDirectories(relativePath: string, content: string): Promise<string> {
+  // Normalize path relative to current working directory
+  const absolutePath = path.resolve(process.cwd(), relativePath);
+  
+  // Ensure parent directories exist
+  const parentDir = path.dirname(absolutePath);
+  if (!fs.existsSync(parentDir)) {
+    fs.mkdirSync(parentDir, { recursive: true });
+  }
+  
+  // Write file with UTF-8 encoding
+  await fs.promises.writeFile(absolutePath, content, FILE_ENCODING_UTF8);
+  
+  return absolutePath;
+}
+

package/src/utils/context-formatter.ts

@@ -0,0 +1,102 @@
+import type { DebateContext, DebateRound, AgentClarifications } from '../types/debate.types';
+
+/**
+ * Formats debate history into a readable string for LLM prompts.
+ * Groups contributions by round and formats with clear labels.
+ * 
+ * @param history - Array of debate rounds to format.
+ * @returns A formatted string representation of the debate history.
+ */
+export function formatHistory(history: DebateRound[]): string {
+  return history.map(round => {
+    const contributions = round.contributions.map(c => {
+      const firstLine = c.content.split('\n')[0] || '';
+      const preview = firstLine.length > 100 ? firstLine.substring(0, 100) + '...' : firstLine;
+      return `  [${c.agentRole}] ${c.type}: ${preview}`;
+    }).join('\n');
+    return `Round ${round.roundNumber}:\n${contributions}`;
+  }).join('\n\n');
+}
+
+/**
+ * Formats a context section for inclusion in prompts.
+ * Searches backwards through rounds to find this agent's most recent summary.
+ * Falls back to full history only if includeFullHistory is true and no summary found.
+ * Returns empty string if no context available or includeFullHistory is false.
+ * 
+ * @param context - The debate context containing history.
+ * @param agentId - The agent ID to look up the summary for.
+ * @param includeFullHistory - Whether to fall back to full history when no summary is found.
+ * @returns A formatted context section, or empty string if no context.
+ */
+export function formatContextSection(context: DebateContext, agentId: string, includeFullHistory: boolean = true): string {
+  if (!context?.history || context.history.length === 0) {
+    return '';
+  }
+  
+  // Search backwards through rounds to find this agent's most recent summary
+  for (let i = context.history.length - 1; i >= 0; i--) {
+    const round = context.history[i];
+    if (!round) continue;
+    
+    const agentSummary = round.summaries?.[agentId];
+    
+    if (agentSummary) {
+      return `=== Previous Debate Context ===\n\n` +
+             `[SUMMARY from Round ${round.roundNumber}]\n` +
+             `${agentSummary.summary}\n\n` +
+             `===================================\n\n`;
+    }
+  }
+  
+  // No summary found for this agent
+  if (includeFullHistory) {
+    // Fall back to full history only if includeFullHistory is true
+    return `=== Previous Debate Rounds ===\n\n` +
+           `${formatHistory(context.history)}\n\n` +
+           `===================================\n\n`;
+  } else {
+    // Return empty string if includeFullHistory is false
+    return '';
+  }
+}
+
+/**
+ * Prepends a context section to a prompt if context is available.
+ * Adds proper formatting and separation.
+ * 
+ * @param prompt - The base prompt to prepend context to.
+ * @param context - The debate context.
+ * @param agentId - The agent ID for finding their specific summary.
+ * @param includeFullHistory - Whether to fall back to full history when no summary is found.
+ * @returns The prompt with context prepended, or the original prompt if no context.
+ */
+export function prependContext(prompt: string, context?: DebateContext, agentId?: string, includeFullHistory: boolean = true): string {
+  if (!context || !agentId) {
+    return prompt;
+  }
+  
+  // Render clarifications first (if any), then previous summaries/history
+  const clar = context.clarifications && context.clarifications.length > 0 ? formatClarifications(context.clarifications) : '';
+
+  const rest = formatContextSection(context, agentId, includeFullHistory);
+  const full = `${clar}${clar ? '\n' : ''}${rest}`.trim();
+  if (!full) return prompt;
+  return full + '\n' + prompt;
+}
+
+/**
+ * Formats Clarifications section for prompts, grouped by agent.
+ */
+export function formatClarifications(groups: AgentClarifications[]): string {
+  let text = '## Clarifications\n\n';
+  for (const group of groups) {
+    text += `### ${group.agentName} (${group.role})\n`;
+    for (const item of group.items) {
+      text += `Question (${item.id}):\n\n\`\`\`text\n${item.question}\n\`\`\`\n\n`;
+      text += `Answer:\n\n\`\`\`text\n${item.answer}\n\`\`\`\n\n`;
+    }
+  }
+  return text + '\n';
+}
+

package/src/utils/context-summarizer.ts

@@ -0,0 +1,143 @@
+import type { AgentRole, LLM_PROVIDERS } from '../types/agent.types';
+import type { SummarizationConfig, SummarizationMetadata } from '../types/debate.types';
+import { LLMProvider } from '../providers/llm-provider';
+
+/**
+ * Default model to use for summarization.
+ * Using GPT-4 for its strong summarization capabilities.
+ */
+const DEFAULT_SUMMARY_MODEL = 'gpt-4';
+
+/**
+ * Default temperature for summarization LLM calls.
+ * Lower temperature (0.3) produces more consistent, factual summaries.
+ */
+const DEFAULT_SUMMARY_TEMPERATURE = 0.3;
+
+/**
+ * Result of a summarization operation.
+ */
+export interface SummarizationResult {
+  summary: string; /** The generated summary text. */
+  metadata: SummarizationMetadata; /** Metadata about the summarization operation. */
+}
+
+/**
+ * Interface for context summarization strategies.
+ * Allows pluggable summarization implementations (e.g., length-based, semantic, hierarchical).
+ */
+export interface ContextSummarizer {
+  /**
+   * Summarizes the given content from the perspective of a specific agent role.
+   * 
+   * @param content - The full content to summarize.
+   * @param role - The agent role for perspective-based summarization.
+   * @param config - Summarization configuration (threshold, maxLength, etc.).
+   * @param systemPrompt - The system prompt to use for the LLM.
+   * @param summaryPrompt - The summarization-specific prompt template.
+   * @returns A promise resolving to the summary and metadata.
+   */
+  summarize(
+    content: string,
+    role: AgentRole,
+    config: SummarizationConfig,
+    systemPrompt: string,
+    summaryPrompt: string
+  ): Promise<SummarizationResult>;
+}
+
+/**
+ * Length-based summarization strategy using LLM.
+ * Summarizes content when it exceeds a character threshold.
+ */
+export class LengthBasedSummarizer implements ContextSummarizer {
+  private readonly model?: string;
+  private readonly temperature?: number;
+  private readonly providerName?: typeof LLM_PROVIDERS[keyof typeof LLM_PROVIDERS];
+
+  constructor(
+    private provider: LLMProvider,
+    options?: { 
+      model?: string; 
+      temperature?: number; 
+      provider?: typeof LLM_PROVIDERS[keyof typeof LLM_PROVIDERS]; 
+    }
+  ) {
+    if (options && options.model !== undefined) {
+      this.model = options.model;
+    }
+    if (options && options.temperature !== undefined) {
+      this.temperature = options.temperature;
+    }
+    if (options && options.provider !== undefined) {
+      this.providerName = options.provider;
+    }
+  }
+
+  /**
+   * Summarizes content using an LLM call with role-specific prompts.
+   * 
+   * @param content - The full content to summarize.
+   * @param role - The agent role for perspective-based summarization.
+   * @param config - Summarization configuration.
+   * @param systemPrompt - The system prompt for the LLM.
+   * @param summaryPrompt - The summarization prompt template.
+   * @returns The summary and metadata.
+   */
+  async summarize(
+    content: string,
+    _role: AgentRole,
+    config: SummarizationConfig,
+    systemPrompt: string,
+    summaryPrompt: string
+  ): Promise<SummarizationResult> {
+    const beforeChars = content.length;
+    const startTime = Date.now();
+
+    // Call LLM to generate summary using configured values with fallbacks
+    const selectedModel = this.model ?? DEFAULT_SUMMARY_MODEL;
+    const selectedTemperature = this.temperature ?? DEFAULT_SUMMARY_TEMPERATURE;
+
+    const response = await this.provider.complete({
+      model: selectedModel,
+      temperature: selectedTemperature,
+      systemPrompt,
+      userPrompt: summaryPrompt,
+    });
+
+    const latencyMs = Date.now() - startTime;
+
+    // Truncate summary to maxLength if needed
+    let summaryText = response.text.trim();
+    if (summaryText.length > config.maxLength) {
+      summaryText = summaryText.substring(0, config.maxLength);
+    }
+
+    const afterChars = summaryText.length;
+
+    const metadata: SummarizationMetadata = {
+      beforeChars,
+      afterChars,
+      method: config.method,
+      timestamp: new Date(),
+      latencyMs,
+    };
+
+    if (response.usage?.totalTokens != null) {
+      metadata.tokensUsed = response.usage.totalTokens;
+    }
+
+    // Record model, temperature, and provider used for summarization
+    metadata.model = selectedModel;
+    metadata.temperature = selectedTemperature;
+    if (this.providerName) {
+      metadata.provider = this.providerName;
+    }
+
+    return {
+      summary: summaryText,
+      metadata,
+    };
+  }
+}
+

package/src/utils/env-loader.ts

@@ -0,0 +1,46 @@
+import fs from 'fs';
+import path from 'path';
+import { writeStderr } from '../cli/index';
+import dotenv from 'dotenv';
+
+// Constants for environment file loading
+const DEFAULT_ENV_FILENAME = '.env';
+const ERROR_ENV_FILE_NOT_FOUND = 'Environment file not found';
+const WARN_DEFAULT_ENV_MISSING = 'No .env file found at';
+const ERROR_ENV_FILE_LOAD_FAILED = 'Failed to load environment file';
+
+/**
+ * Loads environment variables from a .env file using the dotenv library.
+ * 
+ * By default, attempts to load '.env' from the current working directory.
+ * If the default .env file doesn't exist, continues silently (non-breaking).
+ * If a custom env file path is specified and doesn't exist, throws an error.
+ * In verbose mode, warns about missing default .env files to stderr.
+ *
+ * @param envFilePath - Optional path to a custom .env file, relative to process.cwd()
+ * @param verbose - Whether to output verbose logging about .env file loading
+ * @throws {Error} If explicitly specified env file doesn't exist or dotenv parsing fails
+ */
+export function loadEnvironmentFile(envFilePath?: string, verbose?: boolean): void {
+  const fileName = envFilePath || DEFAULT_ENV_FILENAME;
+  const resolvedPath = path.resolve(process.cwd(), fileName);
+  const isDefaultFile = !envFilePath;
+
+  if (!fs.existsSync(resolvedPath)) {
+    if (isDefaultFile) { // Silent failure for default .env file, with optional verbose warning
+      
+      if (verbose === true) {
+        writeStderr(`${WARN_DEFAULT_ENV_MISSING} ${resolvedPath}. Continuing without loading environment variables.\n`);
+      }
+      return;
+    } else { // Error for explicitly specified env file
+      throw new Error(`${ERROR_ENV_FILE_NOT_FOUND}: ${resolvedPath}`);
+    }
+  }
+  
+  const result = dotenv.config({ path: resolvedPath });
+  
+  if (result.error) {
+    throw new Error(`${ERROR_ENV_FILE_LOAD_FAILED}: ${result.error.message}`);
+  }
+}

package/src/utils/exit-codes.ts

@@ -0,0 +1,5 @@
+export const EXIT_SUCCESS = 0;
+export const EXIT_GENERAL_ERROR = 1;
+export const EXIT_INVALID_ARGS = 2;
+export const EXIT_PROVIDER_ERROR = 3;
+export const EXIT_CONFIG_ERROR = 4;

package/src/utils/id.ts

@@ -0,0 +1,11 @@
+export function generateDebateId(now: Date = new Date()): string {
+  const pad = (n: number) => n.toString().padStart(2, '0');
+  const yyyy = now.getFullYear();
+  const MM = pad(now.getMonth() + 1);
+  const dd = pad(now.getDate());
+  const hh = pad(now.getHours());
+  const mm = pad(now.getMinutes());
+  const ss = pad(now.getSeconds());
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `deb-${yyyy}${MM}${dd}-${hh}${mm}${ss}-${rand}`;
+}

package/src/utils/logger.ts

@@ -0,0 +1,48 @@
+import { WARNING_COLOR, INFO_COLOR } from '../cli/index';
+
+// Lazy optional chalk import to avoid ESM issues in test environment
+let chalk: any;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  chalk = require('chalk');
+} catch {
+  chalk = null;
+}
+
+function color(method: string, message: string): string {
+  return chalk && chalk[method] ? chalk[method](message) : message;
+}
+
+export class Logger {
+  constructor(private verbose: boolean = false) {}
+
+  info(message: string): void {
+    console.log(color('cyan', message));
+  }
+
+  success(message: string): void {
+    console.log(color('green', message));
+  }
+
+  warn(message: string): void {
+    console.warn(color(WARNING_COLOR, message));
+  }
+
+  error(message: string): void {
+    console.error(color('red', message));
+  }
+
+  debug(message: string): void {
+    if (this.verbose) {
+      console.log(color(INFO_COLOR, message));
+    }
+  }
+
+  agentAction(agentName: string, action: string): void {
+    console.log(`[${agentName}] ${action}`);
+  }
+
+  separator(): void {
+    console.log('━'.repeat(60));
+  }
+}

package/src/utils/paths.ts

@@ -0,0 +1,10 @@
+import fs from 'fs';
+import path from 'path';
+
+export function getDebatesDir(): string {
+  const dir = path.resolve(process.cwd(), 'debates');
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}