dialectic 0.1.0

package/src/providers/openrouter-provider.ts

@@ -0,0 +1,122 @@
+import OpenAI from 'openai';
+import { CompletionRequest, CompletionResponse, LLMProvider } from './llm-provider';
+
+/**
+ * OpenRouter API configuration constants
+ */
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+const OPENROUTER_HTTP_REFERER = 'dialectic';
+const OPENROUTER_X_TITLE = 'Dialectic - Multi-Agent Debate';
+
+/**
+ * OpenRouter provider implementation using OpenAI SDK with OpenRouter-specific configuration.
+ * 
+ * This provider leverages the OpenAI SDK for compatibility while using OpenRouter's API
+ * endpoint and authentication. It supports the same fallback strategy as the OpenAI provider
+ * (Responses API → Chat Completions API) and handles OpenRouter-specific response formats.
+ * 
+ * OpenRouter models are specified using their full qualified names (e.g., "openai/gpt-4",
+ * "anthropic/claude-3-sonnet") as provided by the user in their configuration.
+ */
+export class OpenRouterProvider implements LLMProvider {
+  private client: OpenAI;
+
+  /**
+   * Creates a new OpenRouter provider instance.
+   * @param apiKey - OpenRouter API key for authentication
+   */
+  constructor(apiKey: string) {
+    this.client = new OpenAI({
+      apiKey,
+      baseURL: OPENROUTER_BASE_URL,
+      defaultHeaders: {
+        'HTTP-Referer': OPENROUTER_HTTP_REFERER,
+        'X-Title': OPENROUTER_X_TITLE,
+      },
+    });
+  }
+
+  /**
+   * Makes a completion request to OpenRouter API.
+   * 
+   * Uses the same fallback strategy as OpenAI provider:
+   * 1. Attempts to use Responses API (newer interface)
+   * 2. Falls back to Chat Completions API if Responses API fails
+   * 
+   * @param request - The completion request containing model, prompts, and parameters
+   * @returns Promise resolving to completion response with text and usage metadata
+   */
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    // Try Responses API first
+    try {
+      // Build Responses API payload conditionally
+      const respPayload: any = {
+        model: request.model,
+        temperature: request.temperature,
+        input: [
+          { role: 'system', content: request.systemPrompt },
+          { role: 'user', content: request.userPrompt },
+        ],
+      };
+      if (request.maxTokens != null) respPayload.max_output_tokens = request.maxTokens;
+      if (request.stopSequences) respPayload.stop = request.stopSequences;
+
+      const resp = await (this.client as any).responses?.create?.(respPayload);
+
+      if (resp && resp.output_text) {
+        const usage = resp?.usage ?? resp?.output?.usage;
+        const out: CompletionResponse = { text: resp.output_text as string };
+        if (usage) {
+          out.usage = {
+            inputTokens: usage.input_tokens ?? usage.inputTokens,
+            outputTokens: usage.output_tokens ?? usage.outputTokens,
+            totalTokens: usage.total_tokens ?? usage.totalTokens,
+          };
+        }
+        return out;
+      }
+      // Some SDK shapes use output[0]?.content[0]?.text
+      const outText: string | undefined = resp?.output?.[0]?.content?.[0]?.text;
+      if (outText) {
+        const usage = resp?.usage ?? resp?.output?.usage;
+        const out: CompletionResponse = { text: outText };
+        if (usage) {
+          out.usage = {
+            inputTokens: usage.input_tokens ?? usage.inputTokens,
+            outputTokens: usage.output_tokens ?? usage.outputTokens,
+            totalTokens: usage.total_tokens ?? usage.totalTokens,
+          };
+        }
+        return out;
+      }
+
+      // Fallback if Responses API returned unexpected shape
+      throw new Error('Unexpected Responses API response shape');
+    } catch (_err) {
+      // Fallback to Chat Completions API
+      const chatPayload: any = {
+        model: request.model,
+        messages: [
+          { role: 'system', content: request.systemPrompt },
+          { role: 'user', content: request.userPrompt },
+        ],
+        temperature: request.temperature,
+      };
+      if (request.maxTokens != null) chatPayload.max_tokens = request.maxTokens;
+      if (request.stopSequences) chatPayload.stop = request.stopSequences;
+
+      const chat = await this.client.chat.completions.create(chatPayload);
+      const txt = chat.choices[0]?.message?.content ?? '';
+      const usage = (chat as any).usage;
+      const out: CompletionResponse = { text: txt };
+      if (usage) {
+        out.usage = {
+          inputTokens: usage.prompt_tokens ?? usage.input_tokens,
+          outputTokens: usage.completion_tokens ?? usage.output_tokens,
+          totalTokens: usage.total_tokens,
+        };
+      }
+      return out;
+    }
+  }
+}

package/src/providers/provider-factory.ts

@@ -0,0 +1,64 @@
+import { LLMProvider } from './llm-provider';
+import { OpenAIProvider } from './openai-provider';
+import { OpenRouterProvider } from './openrouter-provider';
+import { EXIT_CONFIG_ERROR } from '../utils/exit-codes';
+import { LLM_PROVIDERS } from '../types/agent.types';
+
+/**
+ * Environment variable names for API keys
+ */
+const OPENAI_API_KEY_ENV = 'OPENAI_API_KEY';
+const OPENROUTER_API_KEY_ENV = 'OPENROUTER_API_KEY';
+
+
+/**
+ * Helper function to create a provider instance with API key validation.
+ * 
+ * @param envVarName - The name of the environment variable containing the API key
+ * @param ProviderClass - The provider class constructor
+ * @returns An LLM provider instance
+ * @throws {Error} If the API key is missing or empty
+ */
+function createProviderWithApiKey<T extends LLMProvider>(
+  envVarName: string,
+  ProviderClass: new (apiKey: string) => T
+): T {
+  const apiKey = process.env[envVarName];
+  if (!apiKey || apiKey.trim() === '') {
+    const err: any = new Error(`${envVarName} is not set`);
+    err.code = EXIT_CONFIG_ERROR;
+    throw err;
+  }
+  return new ProviderClass(apiKey);
+}
+
+/**
+ * Creates an LLM provider instance based on the specified provider type.
+ * 
+ * This factory function handles provider creation and API key retrieval from environment
+ * variables. It implements fail-fast error handling with clear error messages for
+ * configuration issues.
+ * 
+ * @param providerType - The type of provider to create ("openai" or "openrouter")
+ * @returns An LLM provider instance
+ * @throws {Error} If the provider type is invalid or the required API key is missing
+ */
+export function createProvider(providerType: string): LLMProvider {
+  
+  switch (providerType) {
+    case LLM_PROVIDERS.OPENAI: {
+      return createProviderWithApiKey(OPENAI_API_KEY_ENV, OpenAIProvider);
+    }
+    
+    case LLM_PROVIDERS.OPENROUTER: {
+      return createProviderWithApiKey(OPENROUTER_API_KEY_ENV, OpenRouterProvider);
+    }
+    
+    default: {
+      const supportedTypes = Object.values(LLM_PROVIDERS).join(', ');
+      const err: any = new Error(`Unsupported provider type: ${providerType}. Supported types are: ${supportedTypes}`);
+      err.code = EXIT_CONFIG_ERROR;
+      throw err;
+    }
+  }
+}

package/src/types/agent.types.ts

@@ -0,0 +1,141 @@
+import type { SummarizationConfig } from './config.types';
+
+/**
+ * The role of the agent.
+ */
+export const AGENT_ROLES = {
+  ARCHITECT: "architect",
+  SECURITY: "security",
+  PERFORMANCE: "performance",
+  TESTING: "testing",
+  GENERALIST: "generalist",
+  KISS: "kiss",
+} as const;
+
+export type AgentRole = (typeof AGENT_ROLES)[keyof typeof AGENT_ROLES];
+
+export const LLM_PROVIDERS = {
+  OPENAI: "openai",
+  OPENROUTER: "openrouter",
+} as const;
+
+export const PROMPT_SOURCES = {
+  BUILT_IN: "built-in",
+  FILE: "file",
+} as const;
+
+export type PromptSourceType = (typeof PROMPT_SOURCES)[keyof typeof PROMPT_SOURCES];
+
+/**
+ * Configuration for an AI agent.
+ *
+ * @property id - Unique identifier for the agent.
+ * @property name - Human-readable name for the agent.
+ * @property role - The functional role of the agent (e.g., architect, security).
+ * @property model - The LLM model name to use (e.g., "gpt-4").
+ * @property provider - The LLM provider; currently only supports "openai".
+ * @property temperature - Sampling temperature for the LLM (range: 0.0 - 1.0).
+ * @property systemPromptPath - (Optional) Filesystem path to a markdown/text file containing the system prompt to prime the agent. Resolved relative to the configuration file directory.
+ * @property summaryPromptPath - (Optional) Filesystem path to a markdown/text file containing the summary prompt. Resolved relative to the configuration file directory.
+ * @property summarization - (Optional) Per-agent summarization configuration that overrides system-wide settings.
+ * @property enabled - (Optional) Whether the agent is enabled; defaults to true if omitted.
+ */
+export interface AgentConfig {
+  /** Unique identifier for the agent. */
+  id: string;
+  /** Human-readable name for the agent. */
+  name: string;
+  /** The functional role of the agent. */
+  role: AgentRole;
+  /** The LLM model name to use (e.g., "gpt-4"). */
+  model: string;
+  /** The LLM provider; supports "openai" or "openrouter". */
+  provider: typeof LLM_PROVIDERS.OPENAI | typeof LLM_PROVIDERS.OPENROUTER;
+  /** Sampling temperature for the LLM (range: 0.0 - 1.0). */
+  temperature: number;
+  /** (Optional) Filesystem path to a markdown/text file containing the system prompt to prime the agent. Resolved relative to the configuration file directory. */
+  systemPromptPath?: string;
+  /** (Optional) Filesystem path to a markdown/text file containing the summary prompt. Resolved relative to the configuration file directory. */
+  summaryPromptPath?: string;
+  /** (Optional) Filesystem path to a markdown/text file containing the clarification questions prompt. Resolved relative to the configuration file directory. */
+  clarificationPromptPath?: string;
+  /** (Optional) Per-agent summarization configuration that overrides system-wide settings. */
+  summarization?: SummarizationConfig;
+  /** (Optional) Whether the agent is enabled; defaults to true if omitted. */
+  enabled?: boolean;
+}
+
+/**
+ * Metadata for a contribution made by an agent.
+ *
+ * @property tokensUsed - (Optional) Number of tokens used in the contribution.
+ * @property latencyMs - (Optional) Latency in milliseconds for the contribution.
+ * @property model - (Optional) The LLM model used for the contribution.
+ */
+export interface ContributionMetadata {
+  tokensUsed?: number;
+  latencyMs?: number;
+  model?: string;
+}
+
+/**
+ * Represents a generic response from an agent, such as a proposal, critique, or refinement.
+ *
+ * @property content - The main textual content of the agent's response (e.g., solution, critique, or refinement).
+ * @property metadata - Metadata about the response, including token usage, latency, and model information.
+ */
+export interface AgentResponse {
+  /** The main textual content of the agent's response. */
+  content: string;
+  /** Metadata about the response, such as tokens used, latency, and model. */
+  metadata: ContributionMetadata;
+}
+
+/**
+ * Provenance information for a system prompt, indicating whether it was loaded from a file or using built-in defaults.
+ *
+ * @property source - The source of the system prompt ('built-in' for default, 'file' for loaded from filesystem).
+ * @property absPath - (Optional) The absolute filesystem path to the prompt file, if source is 'file'.
+ */
+export interface PromptSource {
+  source: PromptSourceType;
+  absPath?: string;
+}
+
+/**
+ * Metadata about an agent's prompt source for logging and persistence.
+ *
+ * @property agentId - The unique identifier of the agent.
+ * @property role - The role of the agent.
+ * @property source - Whether the prompt came from a file or built-in default.
+ * @property path - (Optional) The file path if loaded from a file.
+ */
+export interface AgentPromptMetadata {
+  agentId: string;
+  role: AgentRole;
+  source: PromptSourceType;
+  path?: string;
+}
+
+/**
+ * Metadata about a judge's prompt source for logging and persistence.
+ *
+ * @property id - The unique identifier of the judge.
+ * @property source - Whether the prompt came from a file or built-in default.
+ * @property path - (Optional) The file path if loaded from a file.
+ * @property summarySource - Whether the summary prompt came from a file or built-in default.
+ * @property summaryPath - (Optional) The file path for summary prompt if loaded from a file.
+ */
+export interface JudgePromptMetadata {
+  id: string;
+  source: PromptSourceType;
+  path?: string;
+  summarySource?: PromptSourceType;
+  summaryPath?: string;
+}
+
+//the next two are just for convenience (readability) and potential future use if we need to distinguish between different types of responses
+
+export interface Proposal extends AgentResponse {}
+
+export interface Critique extends AgentResponse {}

package/src/types/config.types.ts

@@ -0,0 +1,47 @@
+import { AgentConfig } from './agent.types';
+import { DebateConfig, SummarizationMethod } from './debate.types';
+
+export interface SummarizationConfig {
+  enabled: boolean;
+  threshold: number;
+  maxLength: number;
+  method: SummarizationMethod;
+  promptPath?: string;
+}
+
+/** Default value for summarization enabled flag */
+export const DEFAULT_SUMMARIZATION_ENABLED = true;
+
+/** Default character count threshold for triggering summarization */
+export const DEFAULT_SUMMARIZATION_THRESHOLD = 5000;
+
+/** Default maximum length for generated summaries */
+export const DEFAULT_SUMMARIZATION_MAX_LENGTH = 2500;
+
+/** Default summarization method */
+export const DEFAULT_SUMMARIZATION_METHOD: SummarizationMethod = 'length-based';
+
+/**
+ * Represents the top-level system configuration for a debate session.
+ *
+ * This interface defines the structure of the configuration file used to initialize
+ * agents, judge, and debate parameters. It is typically loaded from a JSON file.
+ *
+ * @property agents - An array of agent configurations. Each agent participates in the debate.
+ * @property judge - (Optional) The configuration for the judge agent responsible for synthesizing the final solution.
+ * @property debate - (Optional) Debate-level configuration, such as number of rounds and other settings.
+ * @property configDir - (Optional, internal) The absolute directory path of the loaded configuration file.
+ *                      This is set internally by the loader to resolve relative paths for prompts and other files.
+ *                      It is not user-provided.
+ */
+export interface SystemConfig {
+  
+  agents: AgentConfig[]; // List of agent configurations participating in the debate.
+  judge?: AgentConfig; // (Optional) Configuration for the judge agent.
+  debate?: DebateConfig; // (Optional) Debate-level configuration options.
+  /**
+   * (Internal) Directory of the loaded configuration file, used for resolving relative paths.
+   * Set by the loader, not by the user.
+   */
+  configDir?: string;
+}

package/src/types/debate.types.ts

@@ -0,0 +1,237 @@
+import { AgentRole, AgentPromptMetadata, JudgePromptMetadata, LLM_PROVIDERS } from './agent.types';
+
+/** String literal constants for termination types */
+export const TERMINATION_TYPES = {
+  FIXED: 'fixed',
+  CONVERGENCE: 'convergence',
+  QUALITY: 'quality',
+} as const;
+
+/** Union type of all termination types */
+export type TerminationType = (typeof TERMINATION_TYPES)[keyof typeof TERMINATION_TYPES];
+
+/** String literal constants for synthesis methods */
+export const SYNTHESIS_METHODS = {
+  JUDGE: 'judge',
+  VOTING: 'voting',
+  MERGE: 'merge',
+} as const;
+
+/** Union type of all synthesis methods */
+export type SynthesisMethod = (typeof SYNTHESIS_METHODS)[keyof typeof SYNTHESIS_METHODS];
+
+/** String literal constants for debate statuses */
+export const DEBATE_STATUS = {
+  PENDING: 'pending',
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+} as const;
+
+/** Union type of all debate statuses */
+export type DebateStatus = (typeof DEBATE_STATUS)[keyof typeof DEBATE_STATUS];
+
+/** String literal constants for contribution types */
+export const CONTRIBUTION_TYPES = {
+  PROPOSAL: 'proposal',
+  CRITIQUE: 'critique',
+  REFINEMENT: 'refinement',
+} as const;
+
+/** Union type of all contribution types */
+export type ContributionType = (typeof CONTRIBUTION_TYPES)[keyof typeof CONTRIBUTION_TYPES];
+
+/** String literal constants for summarization methods */
+export const SUMMARIZATION_METHODS = {
+  LENGTH_BASED: 'length-based',
+} as const;
+
+/** Union type of all summarization methods */
+export type SummarizationMethod = (typeof SUMMARIZATION_METHODS)[keyof typeof SUMMARIZATION_METHODS];
+
+/**
+ * Metadata for a summarization operation performed by an agent.
+ */
+export interface SummarizationMetadata {
+  beforeChars: number; /** Character count before summarization. */
+  afterChars: number; /** Character count after summarization. */
+  method: SummarizationMethod; /** Summarization method used. */
+  timestamp: Date; /** When the summarization occurred. */
+  latencyMs?: number; /** Optional latency in milliseconds for the summarization LLM call. */
+  tokensUsed?: number; /** Optional number of tokens used in the summarization LLM call. */
+  model?: string; /** Optional model used for the summarization. */
+  temperature?: number; /** Optional temperature used for the summarization. */
+  provider?: typeof LLM_PROVIDERS[keyof typeof LLM_PROVIDERS]; /** Optional provider used for the summarization. */
+}
+
+/**
+ * A summary generated by an agent for their perspective of the debate history.
+ */
+export interface DebateSummary {
+  agentId: string; /** Unique identifier of the agent that created the summary. */
+  agentRole: AgentRole; /** The role of the agent that created the summary. */
+  summary: string; /** The summarized content. */
+  metadata: SummarizationMetadata; /** Metadata about the summarization operation. */
+}
+
+/**
+ * Result of preparing debate context for an agent.
+ * Contains the prepared context and optional summary if summarization occurred.
+ */
+export interface ContextPreparationResult {
+  context: DebateContext; /** The prepared context for the agent. */
+  summary?: DebateSummary; /** Optional summary if summarization was performed. */
+}
+
+/**
+ * Configuration for context summarization behavior.
+ * Controls when and how agents summarize debate history to manage context size.
+ */
+export interface SummarizationConfig {
+  enabled: boolean; /** Whether summarization is enabled. */
+  threshold: number; /** Character count threshold for triggering summarization. */
+  maxLength: number; /** Maximum length of generated summary in characters. */
+  method: SummarizationMethod; /** Summarization method to use. */
+  promptPath?: string; /** Optional path to custom summarization prompt file. */
+}
+
+/**
+ * Configuration controlling how a debate is executed.
+ */
+export interface DebateConfig {
+  
+  rounds: number; /** Number of complete rounds to execute (>= 1). */
+  terminationCondition: { type: TerminationType; threshold?: number }; /** Termination condition; currently only 'fixed' is supported at runtime. */
+  synthesisMethod: SynthesisMethod; /** Method used to synthesize the final solution. */
+  includeFullHistory: boolean; /** Whether to include full debate history in the context passed to agents and judge. */
+  timeoutPerRound: number; /** Maximum time allowed per round in milliseconds. */
+  summarization?: SummarizationConfig; /** Optional system-wide summarization configuration. Agents can override with their own settings. */
+  /** Whether to run a one-time interactive clarifications phase before the debate starts. */
+  interactiveClarifications?: boolean;
+  /** Maximum number of clarification questions to accept per agent (default 5). */
+  clarificationsMaxPerAgent?: number;
+}
+
+/**
+ * In-memory (and persisted) state for a debate execution.
+ */
+export interface DebateState {
+  id: string; /** Unique debate identifier. */
+  problem: string; /** Problem statement under discussion. */
+  context?: string; /** Optional additional context for the problem. */
+  status: DebateStatus; /** Current status of the debate. */
+  currentRound: number; /** The currently active round number (1-indexed, 0 when no rounds have started). */
+  rounds: DebateRound[]; /** All executed rounds and their contributions. */
+  finalSolution?: Solution; /** Final solution, if completed. */
+  judgeSummary?: DebateSummary; /** Optional summary generated by the judge for synthesis. */
+  createdAt: Date; /** Creation timestamp. */
+  updatedAt: Date; /** Last updated timestamp. */
+  /**
+   * Provenance of system prompts used by agents and judge for this debate (persisted once per debate).
+   */
+  promptSources?: {
+    agents: AgentPromptMetadata[];
+    judge: JudgePromptMetadata;
+  };
+  /** Optional clarifications collected from agents and answered by the user before round 1. */
+  clarifications?: AgentClarifications[];
+}
+
+/**
+ * A single debate round containing contributions for all phases.
+ */
+export interface DebateRound {
+  roundNumber: number; /** Round index (1-indexed). */
+  contributions: Contribution[]; /** All contributions made within this round. */
+  summaries?: Record<string, DebateSummary>; /** Optional summaries keyed by agentId for this round. */
+  timestamp: Date; /** Timestamp when the round was created. */
+}
+
+/**
+ * A single contribution from an agent within a round.
+ */
+export interface Contribution {
+  agentId: string; /** Unique identifier of the contributing agent. */
+  agentRole: AgentRole; /** The role of the contributing agent. */
+  type: ContributionType; /** The contribution type (proposal, critique, or refinement). */
+  content: string; /** The main textual content. */
+  targetAgentId?: string; /** The agent id this critique targets (only for critiques). */
+  metadata: {
+    tokensUsed?: number; /** Optional number of tokens used. */
+    latencyMs?: number; /** Optional latency in milliseconds. */
+    model?: string; /** Optional model used for the contribution. */
+  };
+}
+
+/**
+ * Final synthesized solution returned by the judge.
+ */
+export interface Solution {
+  description: string; /** Summary description of the solution. */
+  implementation?: string; /** Optional implementation guidance or snippet. */
+  tradeoffs: string[]; /** Trade-offs considered. */
+  recommendations: string[]; /** Concrete recommendations. */
+  confidence: number; /** Confidence score (0-100). */
+  synthesizedBy: string; /** Judge agent id that performed the synthesis. */
+}
+
+/**
+ * Top-level result of a debate run including the final solution and metadata.
+ */
+export interface DebateResult {
+  debateId: string; /** Debate identifier for correlating with persisted state. */
+  solution: Solution; /** Final solution. */
+  rounds: DebateRound[]; /** Executed rounds and their contributions. */
+  /** Aggregate metadata about the debate execution. */
+  metadata: {
+    totalRounds: number; /** Number of rounds actually executed. */
+    totalTokens?: number; /** Optional total tokens used across all contributions (if computed). */
+    durationMs: number; /** Total duration in milliseconds. */
+  };
+}
+
+/**
+ * Context object provided to agents and judge.
+ */
+export interface DebateContext {
+  
+  problem: string; /** Problem statement. */
+  context?: string; /** Optional additional context for the current request. */
+  history?: DebateRound[]; /** Optional full history of rounds when enabled. */
+  includeFullHistory?: boolean; /** Whether to fall back to full history when no summary is found. */
+  clarifications?: AgentClarifications[]; /** Optional clarifications to include in prompts (grouped by agent). */
+}
+
+/**
+ * A single clarification item: a question and its answer (or "NA").
+ */
+export interface ClarificationItem {
+  id: string;
+  question: string;
+  answer: string; // may be "NA"
+}
+
+/**
+ * Group of clarifications produced by a single agent.
+ */
+export interface AgentClarifications {
+  agentId: string;
+  agentName: string;
+  role: import('./agent.types').AgentRole;
+  items: ClarificationItem[];
+}
+
+/**
+ * A single clarifying question as produced by an agent before the debate.
+ */
+export interface ClarificationQuestion {
+  id?: string;
+  text: string;
+}
+
+/**
+ * Structured response returned by an agent when asked for clarifying questions.
+ */
+export interface ClarificationQuestionsResponse {
+  questions: ClarificationQuestion[];
+}