dialectic 0.1.0

package/src/core/state-manager.ts

@@ -0,0 +1,322 @@
+import fs from 'fs';
+import path from 'path';
+import { Contribution, DebateRound, DebateState, Solution, DebateSummary, DEBATE_STATUS, AgentClarifications } from '../types/debate.types';
+
+// File-level constants to eliminate magic strings and improve clarity
+const DEFAULT_DEBATES_DIR = 'debates';
+const FILE_EXTENSION_JSON = '.json';
+const FILE_ENCODING_UTF8 = 'utf-8';
+const ID_PREFIX = 'deb-';
+const JSON_SPACE = 2;
+
+/**
+ * StateManager persists and retrieves debate state to the filesystem
+ * while keeping an in-memory cache for fast access.
+ */
+export class StateManager {
+  private debates: Map<string, DebateState> = new Map();
+  private baseDir: string;
+
+  /**
+   * @param baseDir - Base directory where debate JSON files are stored (defaults to ./debates).
+   */
+  constructor(baseDir: string = path.resolve(process.cwd(), DEFAULT_DEBATES_DIR)) {
+    this.baseDir = baseDir;
+    this.ensureDirectoryExists();
+  }
+
+  /**
+   * Creates a new debate entry, initializes state, and persists it.
+   * @param problem - Problem statement for the debate.
+   * @param context - Optional additional context.
+   * @returns The created DebateState.
+   */
+  async createDebate(problem: string, context?: string): Promise<DebateState> {
+    const now = new Date();
+    const state: DebateState = {
+      id: this.generateId(now),
+      problem,
+      // Conditional spread: only include context property if defined (avoids explicit undefined with exactOptionalPropertyTypes)
+      ...(context !== undefined && { context }),
+      status: DEBATE_STATUS.RUNNING,
+      currentRound: 0,
+      rounds: [],
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    this.debates.set(state.id, state);
+    await this.save(state);
+    return state;
+  }
+
+  /**
+   * Adds a contribution to the current round of the specified debate and persists the updated state.
+   *
+   * @param debateId - The unique identifier of the debate to which the contribution should be added.
+   * @param contribution - The Contribution object to append to the current round.
+   * @throws {Error} If the debate with the given ID does not exist.
+   * @throws {Error} If there is no active round for the debate (i.e., beginRound has not been called).
+   *
+   * This method locates the debate in the in-memory cache, verifies that a round is active,
+   * appends the contribution to the current round's contributions array, updates the debate's
+   * updatedAt timestamp, and persists the state to disk.
+   */
+  async addContribution(debateId: string, contribution: Contribution): Promise<void> {
+    // Direct in-memory access: only active debates can be modified (don't load completed debates from disk)
+    const state = this.debates.get(debateId);
+    if (!state) throw new Error(`Debate ${debateId} not found`);
+
+    const round: DebateRound | undefined = state.rounds[state.currentRound - 1];
+    if (!round)  throw new Error(`No active round for debate ${debateId}. Call beginRound() before adding contributions.`);
+
+    round.contributions.push(contribution);
+    state.updatedAt = new Date();
+    await this.save(state);
+  }
+
+  /**
+   * Adds a summary to the current round of the specified debate and persists the updated state.
+   * 
+   * Summaries are generated by agents when context becomes too large and needs to be condensed.
+   * Each agent's summary is stored by their agentId for easy lookup.
+   *
+   * @param debateId - The unique identifier of the debate to which the summary should be added.
+   * @param summary - The DebateSummary object to add to the current round (keyed by agentId).
+   * @throws {Error} If the debate with the given ID does not exist.
+   * @throws {Error} If there is no active round for the debate (i.e., beginRound has not been called).
+   *
+   * This method locates the debate in the in-memory cache, verifies that a round is active,
+   * initializes the summaries Record if not present, stores the summary by agentId,
+   * updates the debate's updatedAt timestamp, and persists the state to disk.
+   */
+  async addSummary(debateId: string, summary: DebateSummary): Promise<void> {
+    const state = this.debates.get(debateId);
+    if (!state) throw new Error(`Debate ${debateId} not found`);
+
+    const round: DebateRound | undefined = state.rounds[state.currentRound - 1];
+    if (!round) throw new Error(`No active round for debate ${debateId}. Call beginRound() before adding summaries.`);
+
+    // Initialize summaries Record if not present
+    if (!round.summaries) {
+      round.summaries = {};
+    }
+
+    // Store summary by agentId
+    round.summaries[summary.agentId] = summary;
+    state.updatedAt = new Date();
+    await this.save(state);
+  }
+
+  /**
+   * Adds a judge summary to the debate state.
+   * @param debateId - The unique identifier of the debate.
+   * @param summary - The judge summary to store.
+   * @throws {Error} If the debate with the given ID does not exist in memory.
+   *
+   * This method stores the judge summary in the debate state, updates the updatedAt timestamp,
+   * and persists the state to disk.
+   */
+  async addJudgeSummary(debateId: string, summary: DebateSummary): Promise<void> {
+    const state = this.debates.get(debateId);
+    if (!state) throw new Error(`Debate ${debateId} not found`);
+
+    state.judgeSummary = summary;
+    state.updatedAt = new Date();
+    await this.save(state);
+  }
+
+  /**
+   * Persists clarifications (Q&A) collected before round 1.
+   * @param debateId - The unique identifier of the debate.
+   * @param clarifications - Grouped clarifications by agent.
+   */
+  async setClarifications(debateId: string, clarifications: AgentClarifications[]): Promise<void> {
+    const state = this.debates.get(debateId);
+    if (!state) throw new Error(`Debate ${debateId} not found`);
+    state.clarifications = clarifications;
+    state.updatedAt = new Date();
+    await this.save(state);
+  }
+
+  /**
+   * Marks the specified debate as completed, attaches the final solution, updates the status and timestamp,
+   * and persists the updated debate state to disk.
+   *
+   * @param debateId - The unique identifier of the debate to complete.
+   * @param solution - The final Solution object synthesized by the judge.
+   * @throws {Error} If the debate with the given ID does not exist in memory.
+   *
+   * This method sets the debate's status to COMPLETED, assigns the provided solution to the
+   * finalSolution property, updates the updatedAt timestamp, and saves the state.
+   */
+  async completeDebate(debateId: string, solution: Solution): Promise<void> {
+    const state = this.debates.get(debateId);
+    if (!state) throw new Error(`Debate ${debateId} not found`);
+
+    state.status = DEBATE_STATUS.COMPLETED;
+    state.finalSolution = solution;
+    state.updatedAt = new Date();
+    await this.save(state);
+  }
+
+  /**
+   * Marks a debate as failed and persists the updated status.
+   *
+   * @param debateId - The unique identifier of the debate to fail.
+   * @param _error - The error that caused the debate to fail (unused).
+   * @throws {Error} If the debate with the given ID does not exist in memory.
+   *
+   * This method sets the debate's status to FAILED, updates the updatedAt timestamp, and saves the state.
+   * If the debate does not exist, this method does nothing.
+   */
+  async failDebate(debateId: string, _error: Error): Promise<void> {
+    const state = this.debates.get(debateId);
+    if (!state) return;
+    state.status = DEBATE_STATUS.FAILED;
+    state.updatedAt = new Date();
+    await this.save(state);
+  }
+
+  /**
+   * Retrieves a debate by id from in-memory cache, falling back to disk if needed.
+   *
+   * @param debateId - The unique identifier of the debate to retrieve.
+   * @returns The DebateState object if found, or null if not found.
+   *
+   * This method first checks the in-memory cache, then attempts to load from disk if not found.
+   * It revives date fields for createdAt/updatedAt.
+   */
+  async getDebate(debateId: string): Promise<DebateState | null> {
+    const inMem = this.debates.get(debateId);
+    if (inMem) return inMem;
+
+    const filePath = this.getFilePath(debateId);
+    if (!fs.existsSync(filePath)) return null;
+    const raw = await fs.promises.readFile(filePath, FILE_ENCODING_UTF8);
+    const parsed = JSON.parse(raw);
+    // Revive top-level dates; round timestamps remain as serialized strings unless separately revived.
+    parsed.createdAt = new Date(parsed.createdAt);
+    parsed.updatedAt = new Date(parsed.updatedAt);
+    return parsed as DebateState;
+  }
+
+  /**
+   * Lists all debates stored on disk, sorted by most recent creation time.
+   *
+   * This method scans the base directory for all debate JSON files, loads each debate state,
+   * and returns an array of DebateState objects sorted in descending order by their createdAt timestamp.
+   *
+   * Notes:
+   * - Only files with the expected JSON extension are considered.
+   * - If a debate file cannot be loaded or parsed, it is skipped.
+   * - Debates are loaded using getDebate, which revives date fields.
+   * 
+   * @returns {Promise<DebateState[]>} - An array of DebateState objects, most recent first.
+   */
+  async listDebates(): Promise<DebateState[]> {
+    const files = fs.existsSync(this.baseDir) ? await fs.promises.readdir(this.baseDir) : [];
+    const debates: DebateState[] = [];
+    for (const file of files) {
+      if (!file.endsWith(FILE_EXTENSION_JSON)) continue;
+      const id = file.replace(new RegExp(`${FILE_EXTENSION_JSON.replace('.', '\\.')}$`), '');
+      const d = await this.getDebate(id);
+      if (d) debates.push(d);
+    }
+    return debates.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+  }
+
+  /**
+   * Starts a new round for the specified debate, increments currentRound, and persists state.
+   *
+   * This method locates the debate in the in-memory cache, creates a new round object,
+   * appends it to the state's rounds array, updates the currentRound counter, updates the
+   * updatedAt timestamp, and persists the state to disk.
+   * 
+   * @param debateId - The unique identifier of the debate to begin a round for.
+   * @returns The newly created DebateRound object.
+   */
+  async beginRound(debateId: string): Promise<DebateRound> {
+    const state = this.debates.get(debateId);
+    if (!state) throw new Error(`Debate ${debateId} not found`);
+
+    const round: DebateRound = {
+      roundNumber: state.rounds.length + 1,
+      contributions: [],
+      timestamp: new Date(),
+    };
+
+    state.rounds.push(round);
+    state.currentRound = round.roundNumber;
+    state.updatedAt = new Date();
+    await this.save(state);
+    return round;
+  }
+
+  /**
+   * Persists the debate state to disk in JSON format.
+   * 
+   * @param state - The DebateState object to save.
+   */
+  private async save(state: DebateState): Promise<void> {
+    const filePath = this.getFilePath(state.id);
+    const serialized = JSON.stringify(state, null, JSON_SPACE);
+    await fs.promises.writeFile(filePath, serialized, FILE_ENCODING_UTF8);
+  }
+
+  /**
+   * Persists the prompt source provenance for a debate (agents and judge) and saves the state.
+   * Intended to be called once per debate initialization.
+   */
+  async setPromptSources(debateId: string, sources: DebateState['promptSources']): Promise<void> {
+    const state = this.debates.get(debateId);
+    if (!state) throw new Error(`Debate ${debateId} not found`);
+    if (sources) {
+      state.promptSources = sources;
+    } else {
+      delete state.promptSources;
+    }
+    state.updatedAt = new Date();
+    await this.save(state);
+  }
+
+  /**
+   * Ensures the base directory exists on disk.
+   */
+  private ensureDirectoryExists() {
+    if (!fs.existsSync(this.baseDir)) {
+      // Use recursive mkdir to create nested directories if needed
+      fs.mkdirSync(this.baseDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Computes the absolute file path for the JSON file corresponding to a given debate id.
+   *
+   * The file is stored in the base directory with the debate id as the filename and a .json extension.
+   *
+   * @param debateId - The unique identifier of the debate.
+   * @returns The absolute file path where the debate state is persisted.
+   */
+  private getFilePath(debateId: string): string {
+    return path.join(this.baseDir, `${debateId}${FILE_EXTENSION_JSON}`);
+  }
+
+  /**
+   * Generates a unique debate id using a timestamp and a short random suffix.
+   * 
+   * @param now - The current date and time.
+   * @returns The unique debate id.
+   */
+  private generateId(now: 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 `${ID_PREFIX}${yyyy}${MM}${dd}-${hh}${mm}${ss}-${rand}`;
+  }
+}

package/src/eval/evaluator-agent.ts

@@ -0,0 +1,130 @@
+import { LLMProvider, CompletionResponse } from '../providers/llm-provider';
+import { createProvider } from '../providers/provider-factory';
+import { writeStderr } from '../cli/index';
+import { EvaluatorConfig, EvaluatorInputs } from '../types/eval.types';
+
+export interface EvaluatorResult {
+  id: string;
+  rawText: string;
+  latencyMs: number;
+  usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number };
+}
+
+/**
+ * EvaluatorAgent
+ *
+ * This class represents an evaluator agent that uses a language model (LLM) provider to evaluate a software solution or debate.
+ * It encapsulates the agent's configuration, associated model, prompt templates, and low-level logic to perform a deterministic evaluation.
+ *
+ * Usage:
+ *   - Instantiate via static fromConfig() or directly via the constructor.
+ *   - Call evaluate(inputs) to perform evaluation and receive response/result details.
+ */
+export class EvaluatorAgent {
+  /** Unique identifier for the evaluator agent */
+  readonly id: string;
+  /** Human-readable agent name */
+  readonly name: string;
+  /** Model name used for the LLM invocation */
+  readonly model: string;
+  /** LLMProvider instance (e.g., OpenAI, Azure, etc.) */
+  readonly provider: LLMProvider;
+  /** Resolved system prompt string used for the LLM */
+  readonly resolvedSystemPrompt: string;
+  /** Resolved user prompt template (with placeholders) for evaluation */
+  readonly resolvedUserPromptTemplate: string;
+
+  /**
+   * Fixed temperature value for model calls to ensure deterministic evaluation.
+   * This is set to a low value (0.1) to reduce randomness/variance in LLM output.
+   */
+  private static readonly FIXED_TEMPERATURE = 0.1;
+
+  /**
+   * Constructs an EvaluatorAgent instance.
+   *
+   * @param config - EvaluatorConfig object defining agent identity and settings.
+   * @param provider - Instantiated LLMProvider for this agent.
+   * @param resolvedSystemPrompt - The system prompt string for agent context.
+   * @param resolvedUserPromptTemplate - The user prompt template with placeholders.
+   */
+  constructor(
+    config: EvaluatorConfig,
+    provider: LLMProvider,
+    resolvedSystemPrompt: string,
+    resolvedUserPromptTemplate: string
+  ) {
+    this.id = config.id;
+    this.name = config.name;
+    this.model = config.model;
+    this.provider = provider;
+    this.resolvedSystemPrompt = resolvedSystemPrompt;
+    this.resolvedUserPromptTemplate = resolvedUserPromptTemplate;
+  }
+
+  /**
+   * Creates an EvaluatorAgent instance from an EvaluatorConfig, resolving the provider.
+   *
+   * @param cfg - The EvaluatorConfig object.
+   * @param resolvedSystemPrompt - The preloaded system prompt.
+   * @param resolvedUserPromptTemplate - The preloaded user prompt template.
+   * @returns A new EvaluatorAgent instance.
+   */
+  static fromConfig(
+    cfg: EvaluatorConfig,
+    resolvedSystemPrompt: string,
+    resolvedUserPromptTemplate: string
+  ): EvaluatorAgent {
+    const provider = createProvider(cfg.provider);
+    return new EvaluatorAgent(cfg, provider, resolvedSystemPrompt, resolvedUserPromptTemplate);
+  }
+
+  /**
+   * Renders the user prompt by replacing placeholders with actual inputs.
+   *
+   * @param inputs - The evaluation inputs (problem, clarifications, and solution).
+   * @returns The rendered user prompt string.
+   */
+  private renderUserPrompt(inputs: EvaluatorInputs): string {
+    return this.resolvedUserPromptTemplate
+      .replace('{problem}', inputs.problem)
+      .replace('{clarifications}', inputs.clarificationsMarkdown)
+      .replace('{final_solution}', inputs.finalSolution);
+  }
+
+  /**
+   * Performs the evaluation using the underlying LLMProvider.
+   *
+   * @param inputs - The inputs required for evaluation (problem, clarifications, finalSolution).
+   * @returns The evaluation result, including raw text, latency, and optional usage data.
+   * @throws An error if LLM call fails.
+   */
+  async evaluate(inputs: EvaluatorInputs): Promise<EvaluatorResult> {
+    const userPrompt = this.renderUserPrompt(inputs);
+    const systemPrompt = this.resolvedSystemPrompt;
+    const started = Date.now();
+
+    const llmCall = this.provider.complete({
+      model: this.model,
+      temperature: EvaluatorAgent.FIXED_TEMPERATURE,
+      systemPrompt,
+      userPrompt,
+    });
+
+    try {
+      const res: CompletionResponse = await llmCall;
+      const latencyMs = Date.now() - started;
+      return {
+        id: this.id,
+        rawText: res.text,
+        latencyMs,
+        ...(res.usage !== undefined && { usage: res.usage }),
+      };
+    } catch (err: any) {
+      writeStderr(`[${this.id}] Evaluation failed: ${err?.message ?? 'unknown error'}\n`);
+      throw err;
+    }
+  }
+}
+
+

package/src/eval/prompts/system.md

@@ -0,0 +1,41 @@
+You are an expert software design evaluator and reviewer.
+Your role is to critically assess the quality, soundness, and completeness of a proposed software design solution. Act as an impartial but rigorously critical reviewer—similar to a professional peer reviewer in software engineering.
+
+You need to assess the solution on the following qualities and provide score for each quality in the range of 1 to 10:
+- Functional completeness (functional_completeness): how well does the the suggested solution address the problem statement. Does it cover all cases? Does it take into account edge cases?
+    - A score of 1 indicates nothing is addressed, there is no indication of the problem being solved.
+    - A score of 5 indicates most problems and points raised in the problem description are addressed in some way.
+    - A score of 10 indicates all problems are addressed, and other implied/assumed issues or inconsistencies are also addressed. The solution is bullet proof from a functional point of view.
+- Performance and Scalbility (performance_scalability): how well does the proposed architecture/solution address declared or assumed runtime load and scale.
+    - A score of 1 indicates no performance consideration at all. The proposed solution seems to be negligent in how it addresses scale and runtime performance (latency and resource consumption).
+    - A score of 5 indicates some consideration is given to performance and scaling options. Decisions were made to accommodate some volume of users and/or processing.
+    - A score of 10 indicates the design fully covers all known and implied (even if unmentioned) performance considerations. It explicitly addresses latency, it takes into account future scaling and provides a solution that minimizes latency and resource use.
+- Security (security): how well does the proposed architecture/solution address declated or assumed security and privacy issues.
+    - A score of 1 indicates no security consideration were taken into account. The design seems to neglect security issues and may in fact contain security issues.
+    - A score of 5 indidcates the solution seems to have taken into account security issues (e.g. privacy, access control, authentication).
+    - A score of 10 indicates the solution covers all possible security issues and explicitly addresses them in the proposed solution. The offered solution explicilty mentions security aspects as part of the decision reasoning.
+- Maintainability (maintainability_evolvability): how well does the proposed solution/architecture address potential changes and maintenance issues. Does it take into account troubleshooting? does it decompose responsibilities? does it address potential "blast radius" of future changes and tries to reduce impact of changes?
+    - A score of 1 indicates a solution that is highly coupled. No indication of thought about future evolution or decomposition.
+    - A score of 5 indicates the solution proposed involves some degree of decomposition to components, with clear boundaries and responsibilities, focusing changes in specific places.
+    - A score of 10 indicates a solution that takes evolution as an explicit reason to design choices, defining and declaring clear component responsibilites and clear scalable interfaces between components.
+- Regulatory Compoliance (regulatory_compliance): does the solution take into account any possible regulatory impact on the solution (data privacy laws, data protection laws, GDPR, etc)? Does the solution address and indicate this has gone into the reasoning process?
+- Testability (testability): does the solution proposed lend itself to being tested in a scalable manner? can changes be tested easily and independently for different components? Does the solution address also 3rd party integrations?
+    - A score of 1 indicates no indication of testing taken. Solution is convoluted and requires a difficult setup in order to test functionality properly.
+    - A score of 5 indicates the solution takes testing into account, allowing for isolated testing of changes of specific parts of the system.
+    - A score of 10 indicates the solution take testing as a primary consideration, and explicitly addresses and proposes how to tackle different kinds of tests, with relatively low overhead, and accessible to continously run.
+
+Guidelines:
+⦁	Identify strengths, weaknesses, and trade-offs in the proposed solution.
+⦁	Focus on defensible reasoning, not just positive feedback.
+⦁	For each score you assign, provide concrete justification based on the proposal.
+⦁	Be skeptical: reward completeness and clarity, penalise ambiguity, missing assumptions, or unjustified claims.
+⦁	Before scoring, internally compare the proposed design against typical professional standards (for example: completeness of requirements coverage, handling of non-functional concerns, clarity of assumptions and constraints).
+⦁	Use the following scale as a guideline:
+⦁	10 = exceptional, exemplary in every respect
+⦁	8-9 = strong and well reasoned, with minor weaknesses
+⦁	5-7 = acceptable but with clear gaps or risks
+⦁	1-4 = poor, flawed, or incomplete
+⦁	Output ONLY a single valid JSON object conforming exactly to the requested schema.
+⦁	Do not include any text outside the JSON object.
+⦁	Scores must be integers in the range 1 to 10.
+⦁	If you cannot reasonably infer a score for a field, omit that field.

package/src/eval/prompts/user.md

@@ -0,0 +1,64 @@
+Evaluate the following debate outcome in terms of the software design’s quality and soundness.
+
+Problem:
+"""
+{problem}
+"""
+
+Clarifications (if any):
+{clarifications}
+
+Final Solution Description:
+"""
+{final_solution}
+"""
+
+In your evaluation, focus on:
+- How well the solution satisfies the problem requirements and constraints.
+- How clearly and convincingly it discusses or justifies trade-offs.
+- Whether it acknowledges potential risks, limitations, or missing elements.
+- The realism and implementability of the design decisions.
+
+Return ONLY a single JSON object matching this schema:
+{
+  "evaluation": {
+    "functional_completeness": {
+      "score": <integer 1..10>,
+      "reasoning": "<string>"
+    },
+    "non_functional": {
+      "performance_scalability": {
+        "score": <integer 1..10>,
+        "reasoning": "<string>"
+      },
+      "security": {
+        "score": <integer 1..10>,
+        "reasoning": "<string>"
+      },
+      "maintainability_evolvability": {
+        "score": <integer 1..10>,
+        "reasoning": "<string>"
+      },
+      "regulatory_compliance": {
+        "score": <integer 1..10>,
+        "reasoning": "<string>"
+      },
+      "testability": {
+        "score": <integer 1..10>,
+        "reasoning": "<string>"
+      }
+    }
+  },
+  "overall_summary": {
+    "strengths": "<brief strengths>",
+    "weaknesses": "<brief weaknesses>",
+    "overall_score": <integer 1..10>
+  }
+}
+
+Rules:
+- Be concise but specific in reasoning; avoid generic praise such as “looks good”.
+- Highlight gaps, contradictions, implicit assumptions, or missing aspects wherever they appear.
+- Scores must be integers between 1 and 10.
+- If you cannot provide a score for a field, omit that field instead of guessing.
+- Output only the JSON object. Do not wrap it in code fences.

package/src/providers/llm-provider.ts

@@ -0,0 +1,25 @@
+export interface CompletionRequest {
+  model: string;
+  systemPrompt: string;
+  userPrompt: string;
+  temperature: number;
+  maxTokens?: number;
+  stopSequences?: string[];
+}
+
+export interface CompletionUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+
+export interface CompletionResponse {
+  text: string;
+  usage?: CompletionUsage;
+}
+
+export interface LLMProvider {
+  complete(request: CompletionRequest): Promise<CompletionResponse>;
+  stream?(request: CompletionRequest): AsyncIterator<string>;
+  generateEmbedding?(text: string): Promise<number[]>;
+}

package/src/providers/openai-provider.ts

@@ -0,0 +1,84 @@
+import OpenAI from 'openai';
+import { CompletionRequest, CompletionResponse, LLMProvider } from './llm-provider';
+
+export class OpenAIProvider implements LLMProvider {
+  private client: OpenAI;
+
+  constructor(apiKey: string) {
+    this.client = new OpenAI({ apiKey });
+  }
+
+  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;
+    }
+  }
+}