@learning-commons/evaluators 0.2.0 → 0.4.0

package/dist/batch/cli.js

@@ -0,0 +1,3940 @@
+#!/usr/bin/env node
+import * as fs2 from 'fs';
+import { readFileSync, mkdirSync, writeFileSync } from 'fs';
+import * as path from 'path';
+import { dirname, join } from 'path';
+import { exec } from 'child_process';
+import prompts from 'prompts';
+import pLimit from 'p-limit';
+import { randomUUID } from 'crypto';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { generateText, Output } from 'ai';
+import { z } from 'zod';
+import nlp from 'compromise';
+import { syllable } from 'syllable';
+import { parse } from 'csv-parse/sync';
+
+// src/telemetry/client.ts
+var TelemetryClient = class {
+  config;
+  logger;
+  constructor(config) {
+    this.config = config;
+    this.logger = config.logger;
+  }
+  /**
+   * Send telemetry event to analytics service
+   *
+   * Fire-and-forget: Errors are logged but don't throw.
+   */
+  async send(event) {
+    if (!this.config.enabled) {
+      return;
+    }
+    try {
+      const headers = {
+        "Content-Type": "application/json",
+        "X-Client-ID": this.config.clientId
+      };
+      if (this.config.partnerKey) {
+        headers["X-API-Key"] = this.config.partnerKey;
+      }
+      const response = await fetch(this.config.endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(event),
+        // Don't block SDK operations on slow networks
+        signal: AbortSignal.timeout(5e3)
+        // 5 second timeout
+      });
+      if (!response.ok) {
+        this.logger.warn(
+          `[Telemetry] Failed to send event: ${response.status} ${response.statusText}`
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.name !== "TimeoutError" && error.name !== "AbortError") {
+          this.logger.warn(`[Telemetry] Error sending event: ${error.message}`);
+        }
+      }
+    }
+  }
+};
+var __filename$1 = fileURLToPath(import.meta.url);
+var __dirname$1 = dirname(__filename$1);
+var cachedClientId;
+function generateClientId() {
+  if (cachedClientId) {
+    return cachedClientId;
+  }
+  const configFile = getConfigFilePath();
+  try {
+    const data = JSON.parse(readFileSync(configFile, "utf-8"));
+    if (data?.telemetry?.clientId) {
+      cachedClientId = data.telemetry.clientId;
+      return cachedClientId;
+    }
+  } catch {
+  }
+  const clientId = randomUUID();
+  try {
+    mkdirSync(dirname(configFile), { recursive: true });
+    writeFileSync(configFile, JSON.stringify({ telemetry: { clientId } }, null, 2));
+  } catch {
+  }
+  cachedClientId = clientId;
+  return cachedClientId;
+}
+function getConfigFilePath() {
+  const configDir = process.platform === "win32" ? join(process.env.APPDATA ?? homedir(), "learning-commons") : join(homedir(), ".config", "learning-commons");
+  return join(configDir, "config.json");
+}
+var cachedVersion;
+function getSDKVersion() {
+  if (cachedVersion) {
+    return cachedVersion;
+  }
+  const possiblePaths = [
+    join(__dirname$1, "../../package.json"),
+    // From src/
+    join(__dirname$1, "../package.json")
+    // From dist/
+  ];
+  for (const path2 of possiblePaths) {
+    try {
+      const pkg = JSON.parse(readFileSync(path2, "utf-8"));
+      cachedVersion = pkg.version || "0.0.0";
+      return cachedVersion;
+    } catch {
+      continue;
+    }
+  }
+  cachedVersion = "0.0.0";
+  return cachedVersion;
+}
+
+// src/errors.ts
+var EvaluatorError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "EvaluatorError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ConfigurationError = class extends EvaluatorError {
+  constructor(message) {
+    super(message, "CONFIGURATION_ERROR");
+    this.name = "ConfigurationError";
+  }
+};
+var ValidationError = class extends EvaluatorError {
+  constructor(message) {
+    super(message, "VALIDATION_ERROR");
+    this.name = "ValidationError";
+  }
+};
+var APIError = class extends EvaluatorError {
+  constructor(message, statusCode, retryable = false, code) {
+    super(message, code);
+    this.statusCode = statusCode;
+    this.retryable = retryable;
+    this.name = "APIError";
+  }
+};
+var AuthenticationError = class extends APIError {
+  constructor(message, statusCode) {
+    super(message, statusCode, false, "AUTHENTICATION_ERROR");
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends APIError {
+  constructor(message, retryAfter) {
+    super(message, 429, true, "RATE_LIMIT_ERROR");
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+};
+var NetworkError = class extends APIError {
+  constructor(message, retryable = true) {
+    super(message, void 0, retryable, "NETWORK_ERROR");
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends APIError {
+  constructor(message = "Request timed out") {
+    super(message, 408, true, "TIMEOUT_ERROR");
+    this.name = "TimeoutError";
+  }
+};
+function parseProviderError(error) {
+  if (error instanceof Error) {
+    const message = error.message;
+    const statusMatch = message.match(/\b(4\d{2}|5\d{2})\b/);
+    const statusCode = statusMatch ? parseInt(statusMatch[1]) : void 0;
+    return {
+      message,
+      statusCode,
+      code: error.name !== "Error" ? error.name : void 0
+    };
+  }
+  return {
+    message: String(error)
+  };
+}
+function wrapProviderError(error, defaultMessage = "API request failed") {
+  const { message, statusCode, code } = parseProviderError(error);
+  if (statusCode === 401 || statusCode === 403) {
+    return new AuthenticationError(
+      message.includes("API key") ? message : "Invalid API key",
+      statusCode
+    );
+  }
+  if (statusCode === 429) {
+    const retryAfterMatch = message.match(/retry[- ]after[:\s]+(\d+)/i);
+    const retryAfter = retryAfterMatch ? parseInt(retryAfterMatch[1]) * 1e3 : void 0;
+    return new RateLimitError(
+      message.includes("rate limit") ? message : "Rate limit exceeded",
+      retryAfter
+    );
+  }
+  if (message.includes("ECONNREFUSED") || message.includes("ENOTFOUND") || message.includes("ETIMEDOUT") || message.includes("network") || message.includes("Network")) {
+    return new NetworkError(message);
+  }
+  if (message.includes("timeout") || message.includes("timed out")) {
+    return new TimeoutError(message);
+  }
+  return new APIError(
+    message || defaultMessage,
+    statusCode,
+    statusCode ? statusCode >= 500 : false,
+    // 5xx errors are retryable
+    code
+  );
+}
+
+// src/logger.ts
+var ConsoleLogger = class {
+  constructor(level = 2 /* WARN */) {
+    this.level = level;
+  }
+  debug(message, context) {
+    if (this.level <= 0 /* DEBUG */) {
+      console.debug(`[DEBUG] ${message}`, context || "");
+    }
+  }
+  info(message, context) {
+    if (this.level <= 1 /* INFO */) {
+      console.info(`[INFO] ${message}`, context || "");
+    }
+  }
+  warn(message, context) {
+    if (this.level <= 2 /* WARN */) {
+      console.warn(`[WARN] ${message}`, context || "");
+    }
+  }
+  error(message, context) {
+    if (this.level <= 3 /* ERROR */) {
+      console.error(`[ERROR] ${message}`, context || "");
+    }
+  }
+};
+var SilentLogger = class {
+  debug() {
+  }
+  info() {
+  }
+  warn() {
+  }
+  error() {
+  }
+};
+function createLogger(customLogger, level = 2 /* WARN */) {
+  if (customLogger) {
+    return customLogger;
+  }
+  if (level === 4 /* SILENT */) {
+    return new SilentLogger();
+  }
+  return new ConsoleLogger(level);
+}
+
+// src/evaluators/base.ts
+var VALIDATION_LIMITS = {
+  /** Minimum text length in characters */
+  MIN_TEXT_LENGTH: 10,
+  /** Maximum text length in characters (100K chars ≈ 25K tokens) */
+  MAX_TEXT_LENGTH: 1e5
+};
+var BaseEvaluator = class {
+  telemetryClient;
+  logger;
+  config;
+  /**
+   * Static metadata for the evaluator
+   *
+   * Concrete evaluators MUST define this property.
+   *
+   * @example
+   * ```typescript
+   * class MyEvaluator extends BaseEvaluator {
+   *   static readonly metadata = {
+   *     id: 'my-evaluator',
+   *     name: 'My Evaluator',
+   *     description: 'Does something useful',
+   *     supportedGrades: ['3', '4', '5'],
+   *     requiresGoogleKey: true,
+   *     requiresOpenAIKey: false,
+   *   };
+   * }
+   * ```
+   */
+  static metadata;
+  constructor(config) {
+    this.logger = createLogger(config.logger, config.logLevel ?? 2 /* WARN */);
+    this.validateApiKeys(config);
+    const telemetryConfig = this.normalizeTelemetryConfig(config.telemetry);
+    this.config = {
+      maxRetries: config.maxRetries ?? 2,
+      telemetry: telemetryConfig
+    };
+    if (this.config.telemetry.enabled) {
+      this.telemetryClient = new TelemetryClient({
+        endpoint: "https://api.learningcommons.org/evaluators-telemetry/v1/events",
+        partnerKey: config.partnerKey,
+        clientId: generateClientId(),
+        enabled: true,
+        logger: this.logger
+      });
+    }
+  }
+  /**
+   * Get metadata for this evaluator instance
+   * @throws {ConfigurationError} If the subclass has not defined static metadata
+   */
+  get metadata() {
+    const meta = this.constructor.metadata;
+    if (!meta) {
+      throw new ConfigurationError(
+        `${this.constructor.name} must define a static readonly metadata block.`
+      );
+    }
+    return meta;
+  }
+  /**
+   * Validate that required API keys are provided based on metadata
+   * @throws {ConfigurationError} If required API keys are missing
+   */
+  validateApiKeys(config) {
+    if (this.metadata.requiresGoogleKey && !config.googleApiKey) {
+      throw new ConfigurationError(
+        `Google API key is required for ${this.metadata.name} evaluator. Pass googleApiKey in config.`
+      );
+    }
+    if (this.metadata.requiresOpenAIKey && !config.openaiApiKey) {
+      throw new ConfigurationError(
+        `OpenAI API key is required for ${this.metadata.name} evaluator. Pass openaiApiKey in config.`
+      );
+    }
+  }
+  /**
+   * Normalize telemetry config to standard format
+   */
+  normalizeTelemetryConfig(telemetry) {
+    if (telemetry === false) {
+      return {
+        enabled: false,
+        recordInputs: false
+      };
+    }
+    if (telemetry === true || telemetry === void 0) {
+      return {
+        enabled: true,
+        recordInputs: false
+      };
+    }
+    return {
+      enabled: telemetry.enabled ?? true,
+      recordInputs: telemetry.recordInputs ?? false
+    };
+  }
+  /**
+   * Get the evaluator type identifier from metadata
+   * @returns The evaluator type ID (e.g., "vocabulary", "sentence-structure")
+   */
+  getEvaluatorType() {
+    return this.metadata.id;
+  }
+  /**
+   * Validate text meets requirements
+   * Default implementation - can be overridden by concrete evaluators
+   *
+   * @throws {ValidationError} If text is invalid
+   */
+  validateText(text) {
+    this.logger.debug("Validating text input", {
+      evaluator: this.getEvaluatorType(),
+      operation: "validateText",
+      textLength: text.length
+    });
+    const trimmedText = text.trim();
+    if (!trimmedText) {
+      throw new ValidationError("Text cannot be empty or contain only whitespace");
+    }
+    if (trimmedText.length < VALIDATION_LIMITS.MIN_TEXT_LENGTH) {
+      throw new ValidationError(
+        `Text is too short. Minimum length is ${VALIDATION_LIMITS.MIN_TEXT_LENGTH} characters, received ${trimmedText.length} characters`
+      );
+    }
+    if (trimmedText.length > VALIDATION_LIMITS.MAX_TEXT_LENGTH) {
+      throw new ValidationError(
+        `Text is too long. Maximum length is ${VALIDATION_LIMITS.MAX_TEXT_LENGTH.toLocaleString()} characters, received ${trimmedText.length.toLocaleString()} characters`
+      );
+    }
+  }
+  /**
+   * Validate grade is in supported range
+   * Default implementation - can be overridden by concrete evaluators
+   *
+   * @param grade - Grade level to validate
+   * @param validGrades - Set of valid grades for this evaluator
+   * @throws {ValidationError} If grade is invalid
+   */
+  validateGrade(grade, validGrades) {
+    this.logger.debug("Validating grade input", {
+      evaluator: this.getEvaluatorType(),
+      operation: "validateGrade",
+      grade
+    });
+    if (!validGrades.has(grade)) {
+      const validList = Array.from(validGrades).sort((a, b) => {
+        if (a === "K") return -1;
+        if (b === "K") return 1;
+        return parseInt(a, 10) - parseInt(b, 10);
+      }).join(", ");
+      throw new ValidationError(
+        `Invalid grade "${grade}". Supported grades for this evaluator: ${validList}`
+      );
+    }
+  }
+  /**
+   * Send telemetry event to analytics service
+   * Common helper for all evaluators
+   */
+  async sendTelemetry(params) {
+    if (!this.telemetryClient) {
+      return;
+    }
+    await this.telemetryClient.send({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sdk_version: getSDKVersion(),
+      evaluator_type: this.getEvaluatorType(),
+      grade: params.grade,
+      status: params.status,
+      error_code: params.errorCode,
+      latency_ms: params.latencyMs,
+      text_length_chars: params.textLength,
+      provider: params.provider,
+      token_usage: params.tokenUsage,
+      metadata: params.metadata,
+      // Include input text only if recording is enabled
+      input_text: this.config.telemetry.recordInputs ? params.inputText : void 0
+    });
+  }
+};
+var DEFAULT_MODELS = {
+  openai: "gpt-4o",
+  anthropic: "claude-sonnet-4-5-20250929",
+  google: "gemini-2.5-pro"
+};
+var VercelAIProvider = class {
+  constructor(config) {
+    this.config = config;
+    if (config.type === "custom") {
+      throw new Error(
+        "VercelAIProvider does not support custom type. Use config.customProvider directly."
+      );
+    }
+  }
+  /**
+   * Generate structured output using Vercel AI SDK's generateText with output
+   */
+  async generateStructured(request) {
+    const model = await this.getModel(request.model);
+    const startTime = Date.now();
+    const { output, usage } = await generateText({
+      model,
+      messages: request.messages,
+      output: Output.object({ schema: request.schema }),
+      temperature: request.temperature ?? 0,
+      maxRetries: this.config.maxRetries ?? 0,
+      ...request.maxTokens !== void 0 ? { maxTokens: request.maxTokens } : {}
+    });
+    return {
+      data: output,
+      model: request.model || this.getDefaultModel(),
+      usage: {
+        inputTokens: usage.inputTokens || 0,
+        outputTokens: usage.outputTokens || 0
+      },
+      latencyMs: Date.now() - startTime
+    };
+  }
+  /**
+   * Generate plain text using Vercel AI SDK's generateText
+   */
+  async generateText(messages, temperature) {
+    const model = await this.getModel();
+    const startTime = Date.now();
+    const { text, usage } = await generateText({
+      model,
+      messages,
+      temperature: temperature ?? this.config.temperature ?? 0,
+      maxRetries: this.config.maxRetries ?? 0
+    });
+    return {
+      text,
+      usage: {
+        inputTokens: usage.inputTokens || 0,
+        outputTokens: usage.outputTokens || 0
+      },
+      latencyMs: Date.now() - startTime
+    };
+  }
+  /**
+   * Get the configured language model.
+   * Uses dynamic imports so consumers only need to install the provider packages they use.
+   */
+  async getModel(requestModel) {
+    const modelId = requestModel || this.config.model || this.getDefaultModel();
+    const apiKey = this.config.apiKey;
+    switch (this.config.type) {
+      case "openai": {
+        const { createOpenAI } = await import('@ai-sdk/openai').catch(() => {
+          throw new Error(
+            "To use the OpenAI provider, install its adapter: npm install @ai-sdk/openai"
+          );
+        });
+        return createOpenAI(apiKey ? { apiKey } : {})(modelId);
+      }
+      case "anthropic": {
+        const { createAnthropic } = await import('@ai-sdk/anthropic').catch(() => {
+          throw new Error(
+            "To use the Anthropic provider, install its adapter: npm install @ai-sdk/anthropic"
+          );
+        });
+        return createAnthropic(apiKey ? { apiKey } : {})(modelId);
+      }
+      case "google": {
+        const { createGoogleGenerativeAI } = await import('@ai-sdk/google').catch(() => {
+          throw new Error(
+            "To use the Google provider, install its adapter: npm install @ai-sdk/google"
+          );
+        });
+        return createGoogleGenerativeAI(apiKey ? { apiKey } : {})(modelId);
+      }
+      default:
+        throw new Error(`Unsupported provider type: ${this.config.type}`);
+    }
+  }
+  /**
+   * Get default model for the configured provider
+   */
+  getDefaultModel() {
+    const providerType = this.config.type;
+    if (providerType === "custom") {
+      throw new Error("Cannot get default model for custom provider type");
+    }
+    return DEFAULT_MODELS[providerType];
+  }
+};
+function createProvider(config) {
+  if (config.type === "custom" && config.customProvider) {
+    return config.customProvider;
+  }
+  return new VercelAIProvider(config);
+}
+var TextComplexityLevel = z.enum([
+  "Slightly complex",
+  "Moderately complex",
+  "Very complex",
+  "Exceedingly complex"
+]);
+
+// src/schemas/vocabulary.ts
+var VocabularyComplexitySchema = z.object({
+  tier_2_words: z.string().describe("List of Tier 2 words (academic words)"),
+  tier_3_words: z.string().describe("List of Tier 3 words (domain-specific)"),
+  archaic_words: z.string().describe("List of Archaic words"),
+  other_complex_words: z.string().describe("List of Other Complex words"),
+  complexity_score: TextComplexityLevel.describe(
+    "The complexity of the text vocabulary"
+  ),
+  reasoning: z.string().describe("Detailed reasoning for the complexity rating")
+});
+function calculateFleschKincaidGrade(text) {
+  return calculateReadabilityMetrics(text).fleschKincaidGrade;
+}
+function calculateReadabilityMetrics(text) {
+  const doc = nlp(text);
+  const sentences = doc.sentences().length;
+  const terms = doc.terms();
+  const words = terms.length;
+  const characters = text.replace(/\s/g, "").length;
+  const allWords = terms.out("array");
+  const totalSyllables = allWords.reduce((sum, word) => sum + syllable(word), 0);
+  const avgWordsPerSentence = sentences > 0 ? words / sentences : 0;
+  const avgSyllablesPerWord = words > 0 ? totalSyllables / words : 0;
+  const fkGrade = 0.39 * avgWordsPerSentence + 11.8 * avgSyllablesPerWord - 15.59;
+  return {
+    sentenceCount: sentences,
+    wordCount: words,
+    characterCount: characters,
+    syllableCount: totalSyllables,
+    avgWordsPerSentence,
+    avgSyllablesPerWord,
+    fleschKincaidGrade: Math.round(Math.max(0, fkGrade) * 100) / 100
+  };
+}
+
+// src/features/sentence-features.ts
+function safeDivision(numerator, denominator) {
+  return denominator === 0 ? 0 : numerator / denominator;
+}
+function standardDeviation(values) {
+  if (values.length <= 1) return 0;
+  const mean = values.reduce((sum, val) => sum + val, 0) / values.length;
+  const squaredDiffs = values.map((val) => Math.pow(val - mean, 2));
+  const variance = squaredDiffs.reduce((sum, val) => sum + val, 0) / values.length;
+  return Math.sqrt(variance);
+}
+function categorizeSentenceLengths(wordCounts) {
+  if (!wordCounts || wordCounts.length === 0) {
+    return {
+      percent_short_sentences: 0,
+      percent_medium_sentences: 0,
+      percent_long_sentences: 0,
+      percent_very_long_sentences: 0
+    };
+  }
+  let short = 0, medium = 0, long = 0, veryLong = 0;
+  for (const count of wordCounts) {
+    if (count <= 10) short++;
+    else if (count <= 20) medium++;
+    else if (count <= 30) long++;
+    else veryLong++;
+  }
+  const total = wordCounts.length;
+  return {
+    percent_short_sentences: short / total * 100,
+    percent_medium_sentences: medium / total * 100,
+    percent_long_sentences: long / total * 100,
+    percent_very_long_sentences: veryLong / total * 100
+  };
+}
+function addEngineeredFeatures(analysis) {
+  const numSentences = analysis.num_sentences;
+  const numWords = analysis.num_words;
+  const avg_words_per_sentence = safeDivision(numWords, numSentences);
+  const sentence_length_variation = standardDeviation(analysis.sentence_word_counts);
+  const lengthCategories = categorizeSentenceLengths(analysis.sentence_word_counts);
+  const percent_simple_sentences = safeDivision(analysis.num_simple_sentences, numSentences) * 100;
+  const percent_compound_sentences = safeDivision(analysis.num_compound_sentences, numSentences) * 100;
+  const percent_complex_sentences = safeDivision(analysis.num_complex_sentences, numSentences) * 100;
+  const percent_compound_complex_sentences = safeDivision(analysis.num_compound_complex_sentences, numSentences) * 100;
+  const percent_other_sentences = safeDivision(analysis.num_other_sentences, numSentences) * 100;
+  const percent_words_in_simple_sentences = safeDivision(analysis.words_in_simple_sentences, numWords) * 100;
+  const percent_words_in_compound_sentences = safeDivision(analysis.words_in_compound_sentences, numWords) * 100;
+  const percent_words_in_complex_sentences = safeDivision(analysis.words_in_complex_sentences, numWords) * 100;
+  const percent_words_in_compound_complex_sentences = safeDivision(analysis.words_in_compound_complex_sentences, numWords) * 100;
+  const percent_words_in_other_sentences = safeDivision(analysis.words_in_other_sentences, numWords) * 100;
+  const avg_subordinates_per_sentence = safeDivision(analysis.num_subordinate_clauses, numSentences);
+  const avg_clauses_per_sentence = safeDivision(analysis.num_total_clauses, numSentences);
+  const percent_sentences_with_subordinate = safeDivision(analysis.num_sentences_with_subordinate, numSentences) * 100;
+  const percent_sentences_with_multiple_subordinates = safeDivision(analysis.num_sentences_with_multiple_subordinates, numSentences) * 100;
+  const percent_sentences_with_embedded_clauses = safeDivision(analysis.num_sentences_with_embedded_clauses, numSentences) * 100;
+  const prep_phrase_density = safeDivision(analysis.num_prepositional_phrases, numWords) * 100;
+  const participle_phrase_density = safeDivision(analysis.num_participle_phrases, numWords) * 100;
+  const appositive_phrase_density = safeDivision(analysis.num_appositive_phrases, numWords) * 100;
+  const total_transitions = analysis.num_simple_transitions + analysis.num_sophisticated_transitions;
+  const avg_transitions_per_sentence = safeDivision(total_transitions, numSentences);
+  const percent_sophisticated_transitions = safeDivision(analysis.num_sophisticated_transitions, total_transitions) * 100;
+  const percent_sentences_w_one_concept = safeDivision(analysis.num_one_concept_sentences, numSentences) * 100;
+  const percent_sentences_w_multi_concept = safeDivision(analysis.num_multi_concept_sentences, numSentences) * 100;
+  const percent_cleft_sentences = safeDivision(analysis.num_cleft_sentences, numSentences) * 100;
+  return {
+    ...analysis,
+    avg_words_per_sentence,
+    sentence_length_variation,
+    ...lengthCategories,
+    percent_simple_sentences,
+    percent_compound_sentences,
+    percent_complex_sentences,
+    percent_compound_complex_sentences,
+    percent_other_sentences,
+    percent_words_in_simple_sentences,
+    percent_words_in_compound_sentences,
+    percent_words_in_complex_sentences,
+    percent_words_in_compound_complex_sentences,
+    percent_words_in_other_sentences,
+    avg_subordinates_per_sentence,
+    avg_clauses_per_sentence,
+    percent_sentences_with_subordinate,
+    percent_sentences_with_multiple_subordinates,
+    percent_sentences_with_embedded_clauses,
+    prep_phrase_density,
+    participle_phrase_density,
+    appositive_phrase_density,
+    avg_transitions_per_sentence,
+    percent_sophisticated_transitions,
+    percent_sentences_w_one_concept,
+    percent_sentences_w_multi_concept,
+    percent_cleft_sentences
+  };
+}
+var FEATURE_COLS = [
+  // Foundational & Distributional
+  "avg_words_per_sentence",
+  "sentence_length_variation",
+  "percent_short_sentences",
+  "percent_medium_sentences",
+  "percent_long_sentences",
+  "percent_very_long_sentences",
+  "flesch_kincaid_grade",
+  // Sentence Structure (Grammatical Type)
+  "percent_simple_sentences",
+  "percent_compound_sentences",
+  "percent_complex_sentences",
+  "percent_compound_complex_sentences",
+  "percent_other_sentences",
+  // Word Distribution
+  "percent_words_in_simple_sentences",
+  "percent_words_in_complex_sentences",
+  "percent_words_in_compound_sentences",
+  "percent_words_in_compound_complex_sentences",
+  "percent_words_in_other_sentences",
+  // Clausal & Subordination
+  "avg_subordinates_per_sentence",
+  "avg_clauses_per_sentence",
+  "percent_sentences_with_subordinate",
+  "percent_sentences_with_multiple_subordinates",
+  "percent_sentences_with_embedded_clauses",
+  // Phrase Density
+  "prep_phrase_density",
+  "participle_phrase_density",
+  "appositive_phrase_density",
+  // Cohesion & Transitions
+  "avg_transitions_per_sentence",
+  "percent_sophisticated_transitions",
+  // Conceptual & Other
+  "percent_sentences_w_one_concept",
+  "percent_sentences_w_multi_concept",
+  "percent_cleft_sentences",
+  "max_clauses_in_any_sentence",
+  // Grades 5-12
+  "num_sentences",
+  "num_simple_sentences",
+  "num_compound",
+  "num_basic_complex",
+  "num_advanced_complex",
+  "percentage_simple",
+  "percentage_compound",
+  "percentage_basic_complex",
+  "percentage_advanced_complex"
+];
+function featuresToJSON(features, decimals = 1, castToInt = true) {
+  const payload = {};
+  for (const col of FEATURE_COLS) {
+    const value = features[col];
+    if (typeof value === "number") {
+      const rounded = Math.round(value * Math.pow(10, decimals)) / Math.pow(10, decimals);
+      payload[col] = castToInt ? Math.round(rounded) : rounded;
+    } else {
+      payload[col] = null;
+    }
+  }
+  return JSON.stringify(payload, null, 2);
+}
+
+// ../../evals/prompts/vocabulary/background-knowledge.txt
+var background_knowledge_default = `
+Review the following text, which is an educational text written for students in the following grade band: {grade}.
+
+Your job is to give me a background knowledge assumption; that is: what topics, if any, from the text students are likely to be familiar with based on a standard progression of topics in US public school education, as well as topics, if any the student is not likely to be familiar with.
+
+Make sure your response is concise (between 1 - 3 lines max) and is about the topics themselves, not about any other aspect of the text (e.g. flowery language, complicated sentence structure, etc.).
+
+Here's an example:
+[START EXAMPLE]
+Grade Band: 11th
+Text: I went to the woods because I wished to live deliberately, to front only the essential facts of life, and see if I could not
+learn what it had to teach, and not, when I came to die, discover that I had not lived. I did not wish to live what was
+not life, living is so dear; nor did I wish to practise resignation, unless it was quite necessary. I wanted to live deep and suck out all the marrow of life, to live so sturdily and Spartan-like as to put to rout all that was not life, to cut a broad swath and shave close, to drive life into a corner, and reduce it to its lowest terms, and, if it proved to be mean, why then to get the whole and genuine meanness of it, and publish its meanness to the world; or if it were sublime, to
+know it by experience, and be able to give a true account of it in my next excursion. For most men, it appears to me,
+are in a strange uncertainty about it, whether it is of the devil or of God, and have somewhat hastily concluded that it
+is the chief end of man here to "glorify God and enjoy him forever."
+
+Background Knowledge Assumption: Assume they've studied American Transcendentalists like Thoreau and Emerson, including the mid-19th-century context of nature-focused philosophy.
+[END EXAMPLE]
+
+You should assume that the student is an average US public school who is learning from common core curriculum. When you respond, just respond with the background knowledge assumption and nothing else.
+
+You can use the following list of topics that we know are covered for each grade level, although use your best judgement if you know there are other topics out there that students are likely to have covered. And this doesn't cover higher grade levels, so you'll have to again use your judgement for, say, what background knowledge a 9th grader is likely to have:
+[BEGIN TOPICS]
+[
+    K: [
+        "Toys and Play", "Weather Wonders", "Trees are Alive", "Enjoying and Appreciating Trees",
+        "The Five Senses: How do our senses help us learn?", "Once Upon a Farm: What makes a good story?",
+        "America, Then and Now: How has life in America changed over time?", "The Continents: What makes the world fascinating?",
+        "Needs of Plants and Animals", "Pushes and Pulls", "Sunlight and Weather", "Learning and Working Together",
+        "How Do People Learn and Work Together?", "Where Do We Live?", "What Does it Mean to Be an American?",
+        "How Has Our World Changed?", "Why Do People Have Jobs?"
+    ],
+    1: [
+        "Tools and Work", "A Study of the Sun, Moon, and Stars", "Birds' Amazing Bodies", "Caring for Birds",
+        "A World of Books: How do books change lives around the world?", "Creature Features: What can we discover about animals' unique features?",
+        "Powerful Forces: How do people respond to the powerful force of the wind?", "Cinderella Stories: Why do people around the world admire Cinderella?",
+        "Animal and Plant Defenses", "Light and Sounds", "Spinning Earth", "Our Place in the World",
+        "What Are the Rights and Responsibilities of Citizens?", "How Can We Describe Where We Live?",
+        "How Do We Celebrate Our Country?", "How Does the Past Shape Our Lives?", "Why Do People Work?"
+    ],
+    2: [
+        "Schools and Community", "Fossils Tell of Earth's Changes", "The Secret World of Pollination", "Providing for Pollinators",
+        "A Season of Change: How does change impact people and nature?", "The American West: What was life like in the West for early Americans?",
+        "Civil Rights Heroes: How can people respond to injustice?", "Good Eating: How does food nourish us?",
+        "Plant and Animal Relationships", "Properties of Matter", "Changing Landforms", "Exploring Who We Are",
+        "Why Is It Important to Learn About the Past?", "How Does Geography Help Us Understand Our World?",
+        "How Do We Get What We Want and Need?", "Why Do We Need Government?", "How Can People Make a Difference in Our World?"
+    ],
+    "3": [
+        "Overcoming Learning Challenges Near and Far", "Adaptations and the Wide World of Frogs", "Exploring Literary Classics",
+        "Water Around the World", "Ocean/Sea Exploration", "Outer Space", "Immigration", "Art/Being an Artist",
+        "Balancing Forces", "Inheritance and Traits", "Environments and Survival", "Weather and Climate",
+        "Communities", "Why Does It Matter Where We Live?", "What Is Our Relationship With Our Environment?",
+        "What Makes a Community Unique?", "How Does the Past Impact the Present?", "Why Do Governments and Citizens Need Each Other?",
+        "How Do People in a Community Meet Their Wants and Needs?"
+    ],
+    4: [
+        "Poetry", "Animal Defense Mechanisms", "The American Revolution",
+        "Responding to Inequality: Ratifying the 19th Amendment (covers gender and racial inequality)",
+        "A Great Heart: What does it mean to have a great heart, literally and figuratively?",
+        "Extreme Settings: How does a challenging setting or physical environment change a person?",
+        "American Revolution/Multiple Perspectives", "Myths/Myth Making", "Energy Conversions", "Vision and Light",
+        "Earth's Features", "Waves, Energy, and Information", "Regions of the United States",
+        "How Does America Use Its Strengths and Face Its Challenges?", "Why Have People Moved to and From the Northeast?",
+        "How Has the Southeast Changed Over Time?", "How Does the Midwest Reflect the Spirit of America?",
+        "How Does the Southwest Reflect Its Diverse Past and Unique Environment?", "What Draws People to the West?"
+    ],
+    5: [
+        "Human Rights", "Biodiversity in the Rainforest", "Athlete Leaders of Social Change",
+        "Impact of Natural Disasters", "Cultures in Conflict: How do cultural beliefs and values guide people?",
+        "Word Play: How and why do writers play with words?", "A War Between Us: How did the Civil War impact people?",
+        "Breaking Barriers: How can sports influence individuals and societies?", "Patterns of Earth and Sky",
+        "Modeling Matter", "The Earth System", "Ecosystem Restoration", "U.S. History: Making a New Nation",
+        "How Were the Lives of Native Peoples Influenced by Where They Lived?",
+        "What Happened When Diverse Cultures Crossed Paths?", "What Is the Impact of People Settling in a New Place?",
+        "Why Would a Nation Want to Become Independent?", "What Does the Revolutionary Era Tell Us About Our Nation Today?",
+        "How Does the Constitution Help Us Understand What It Means to Be an American?",
+        "What Do the Early Years of the United States Reveal About the Character of the Nation?",
+        "What Was the Effect of the Civil War on U.S. Society?"
+    ],
+    6: [
+        "Greek Mythology", "Critical Problems and Design Solutions", "American Indian Boarding Schools",
+        "Remarkable Accomplishments in Space Science", "Resilience in the Great Depression: How can enduring tremendous hardship contribute to personal transformation?",
+        "A Hero's Journey: What is the significance and power of the hero's journey?",
+        "Narrating the Unknown: How did the social and environmental factors in the unknown world of Jamestown shape its development and decline?",
+        "Courage in Crisis: How can the challenges of a hostile environment inspire heroism?",
+        "Microbiome", "Metabolism", "Metabolism Engineering", "Traits and Reproduction", "Thermal Energy",
+        "Ocean, Atmosphere, and Climate", "Weather Patterns", "Earth's Changing Climate",
+        "Earth's Changing Climate: Engineering Internship", "The First Americans (up to 1492)",
+        "Exploration and Colonization", "English Colonies", "American Revolution", "First Governments and the Constitution",
+        "The Early American Republic", "Political and Geographic Changes (1828-1850)", "Life in the North and South (1820-1860)",
+        "Division and Civil War (1821-1865)", "Reconstruction (1865-1896)", "The West (1858-1896)",
+        "New Industry and a Changing Society", "Expansion and War", "The 1920s and 1930s", "World War II",
+        "The Cold War", "Civil Rights and American Society", "America Since the 1970s"
+    ],
+    7: [
+        "The Lost Children of Sudan (Genocide, Genocide in Sudan)", "Epidemics", "Harlem Renaissance", "Plastic Pollution",
+        "Identity in the Middle Ages: How does society both support and limit the development of identity?",
+        "Americans All: How did World War II affect individuals?", "Language and Power: What is the power of language?",
+        "Fever: How can times of crisis affect citizens and society?", "Geology on Mars", "Plane Motion", "Plane Motion Engineering",
+        "Rock Formations", "Phase Change", "Phase Change Engineering", "Chemical Reactions", "Populations and Resources",
+        "Matter and Energy in Ecosystems", "Early Humans and Agricultural Revolution", "Fertile Crescent",
+        "Ancient Egypt and Kush", "The Israelites", "Ancient Greece", "Ancient South Asia", "Early China, Korea, and Japan",
+        "Ancient Rome", "Rise of Christian Kingdoms", "The Americas", "Medieval Europe", "The Rise of Islamic Empires",
+        "China in the Middle Ages", "Korea and Japan in the Middle Ages", "African Civilizations", "New Ways of Thinking",
+        "Age of Exploration and Trade", "Revolutions and Empires", "The Modern World"
+    ],
+    8: [
+        "Folklore of Latin America", "Food Choices", "The Holocaust", "Japanese American Internment",
+        "The Poetics and Power of Storytelling: What is the power of storytelling?",
+        "The Great War: How do literature and art illuminate the effects of World War I?", "What Is Love?",
+        "Teens as Change Agents: How do people effect social change?", "Harnessing Human Energy",
+        "Force and Motion", "Force and Motion Engineering", "Magnetic Fields", "Light Waves", "Earth, Moon, and Sun",
+        "Natural Selection", "Natural Selection Engineering", "Evolutionary History", "The World in Spatial Terms",
+        "Places and Regions", "Physical Geography", "Population Geography", "Economic Geography",
+        "Political Geography", "Human-Environment Geography", "What is Economics?", "Markets, Money, and Businesses",
+        "Government and the Economy", "The Global Economy"
+    ]
+]
+[END TOPICS]
+
+Here is the text:
+[BEGIN TEXT]
+{text}
+[END TEXT]
+`;
+
+// src/prompts/vocabulary/background-knowledge.ts
+function getBackgroundKnowledgePrompt(text, grade) {
+  return background_knowledge_default.replaceAll("{grade}", grade).replaceAll("{text}", text);
+}
+
+// ../../evals/prompts/vocabulary/grades-3-4-system.txt
+var grades_3_4_system_default = "\nYou are an expert curriculum designer. Your job is to rate the complexity of a text's vocabulary relative to the grade level.\n\nYou will be given a rubric (with levels from least to most complex: slightly complex, moderately complex, very complex, exceedingly complex) as well as guidelines for interpreting the rubric.\nIMPORTANT: You should only pay attention to the vocabulary. Do not evaluate any other element of the text's complexity (e.g. sentence structure, meaning, etc.)\n\n**Resource 1: Qualitative Text Complexity rubric (SAP)**\n1.  **Level 1: Slightly complex**\n    *   Original Definition: Vocabulary that is almost entirely not complex: contemporary, conversational, and/or familiar. A very low proportion of complex words (archaic, subject-specific, academic) is OK -- i.e. doesn't need to be 0.\n    *   Summary definition: Overall, vocabulary is easy to understand and does not impede comprehension of the bulk of the text (including main idea and supporting claims). 1-2 quick pauses for processing by the student are ok here!\n2.  **Level 2: Moderately complex**\n    *   Original Definition: Vocabulary that is mostly not complex: contemporary, conversational, and/or familiar. A low proportion of complex words (archaic, subject-specific, academic) is OK\n    *   Summary definition: Overall, vocabulary generally allows students to comprehend the bulk of the text with little difficulty, though there may be occasional pauses for clarification. Several quick pauses or occasional prolonged pauses may occur.\n3.  **Level 3: Very complex**\n    *   Original Definition: Vocabulary that is often complex: unfamiliar, archaic, subject-specific, and/or overly academic\n    *   Summary definition: Overall, vocabulary often presents challenges that may slow down comprehension but does not completely block the comprehension of the bulk of the text.\n4.  **Level 4: Exceedingly complex**\n    *   Original Definition: Vocabulary that is mostly complex: unfamiliar, archaic, subject-specific, and/or overly academic. May be ambiguous or purposefully misleading.\n    *   Summary definition: Overall, vocabulary is so complex that it makes comprehension of the bulk of the text very challenging and requires careful effort to interpret.\n\n**Resource 2: Flesch-Kincaid Grade Level**\nUse the Flesch-Kincaid (FK) Grade Level as light guidance of the approximate grade level based on readability. The metric alone does not provide final information of vocabulary complexity, but a ballpark of the difficulty of the entire text.\n*   grade 2-3: 1.98-5.34\n*   grade 4-5: 4.51-7.73\n*   grade 6-8: 6.51-10.34\n*   grade 9-10: 8.32-12.12\n*   grade 11-College: 10.34-14.2\n\n**Guidelines for Interpretation and Reasoning**\n\nYour reasoning is the most critical part of your analysis. It's not enough to simply count complex words. You must analyze their impact on a student at the specified grade level. Use the following principles to guide your judgment:\n\n1.  **Density and Cumulative Effect:** Do not just count complex words; evaluate their concentration. A short text with a high density of challenging Tier 2 words (e.g., `peculiar`, `mischievous`, `courageous` for a 4th grader) can be more overwhelming than a longer text with a few scattered Tier 3 words. A constant barrage of unfamiliar words can elevate complexity from `very` to `exceedingly`.\n2.  **Contextual Scaffolding:** Assess how the text supports new vocabulary.\n    *   Are new, complex terms explicitly defined or explained with simple examples (e.g., \"volume... to see if it is big enough to hold a liter of food\")?\n    *   Is the surrounding language simple and conversational, making the meaning of new words easier to infer?\n    *   Strong scaffolding can lower the complexity rating. A text with many Tier 3 words that are well-explained might only be `moderately complex`.\n3.  **Abstract vs. Concrete Vocabulary:** Differentiate between words for abstract concepts and words for concrete things. A text built on abstract Tier 2 words (e.g., `relationships`, `performance`, `non-physical`) can be more challenging than a text that introduces Tier 3 labels for concrete things or people (e.g., `Sumerians`, `polonium`).\n4.  **Conceptual Load:** Consider the cognitive load of the vocabulary. A list of many new, multi-syllabic, conceptually-heavy terms (e.g., `Paleolithic`, `Mesolithic`, `Neolithic` for a 3rd grader) can be `very complex` even if the terms are briefly defined, because the student must process multiple new concepts at once.\n5.  **Calibrating the Top Levels:** Be precise in your use of `very complex` vs. `exceedingly complex`.\n    *   **Very complex:** The vocabulary creates significant hurdles and slows the reader down, but the main ideas of the text are still accessible with effort.\n    *   **Exceedingly complex:** The vocabulary is so dense, technical, or abstract that it acts as a barrier, making it nearly impossible for the target student to grasp the bulk of the text's meaning without extensive outside help. Reserve this for texts saturated with advanced terminology.\n6.  **Consider Background Knowledge:** Pay close attention to the provided `student_background_knowledge`. Do not classify a word as complex if the student is likely to be familiar with it (e.g., 'oxygen' for a 3rd grader who has learned about the human body).\n\n**Final Analysis Format**\n\nProvide these information as your final analysis:\n1.  **Complex vocabulary:**\n    *   Tier 2 words: Words that are commonly used in academic settings and more complex than colloquial, or everyday language and often have multiple meanings.\n    *   Tier 3 words: Overly academic or domain-specific words.\n    *   Archaic words: Words, or uses of words that are not commonly used in modern conversational language. E.g., \"The jury retired to deliberate on their verdict.\" The use of \"retire\" to mean withdrawing to a private place is an archaic use.\n    *   Other complex words: All other words that can increase complexity of the text (e.g., idioms, unfamiliar proper nouns that function as vocabulary).\n2.  **Vocabulary complexity:** one of: slightly complex, moderately complex, very complex, exceedingly complex\n3.  **Your reasoning of the complexity:** A detailed explanation of your rating, referencing the principles above.\n";
+
+// ../../evals/prompts/vocabulary/other-grades-system.txt
+var other_grades_system_default = "\nYou are an expert curriculum designer. Your job involves reading text snippets intended for students in K-12 and evaluating the complexity of the vocabulary in each text.\n\nYou will be given a rubric (with options 1, 2, 3, 4) as well as guidelines for interpreting the rubric.\n\nIMPORTANT: You should only pay attention to the vocabulary. Do not evaluate any other element of the text's complexity (e.g. sentence structure, meainng, etc.)\nIMPORTANT: Rely on the supplied rubric and annotation guidelines along. Do not introduce any new crtieria for evaluating the complexity of a text's vocabulary.\n\nPlease first reason out loud about the vocabulary complexity of the text and then provide an answer between 1 and 4 (whole numbers only). Provide the answer as an integer (not a float).\n";
+
+// src/prompts/vocabulary/system.ts
+function getSystemPrompt(grade) {
+  if (grade === "3" || grade === "4") {
+    return grades_3_4_system_default;
+  }
+  return other_grades_system_default;
+}
+
+// ../../evals/prompts/vocabulary/grades-3-4-user.txt
+var grades_3_4_user_default = "\nBelow is the text you need to evaluate. Let's think step by step in order to predict the output of the vocabulary complexity task.\n\n- It is intended for grade {student_grade_level}.\n\n- You can assume the student has the following background knowledge about the text \u2014 this background knowledge influences which words from the text are familiar versus unfamiliar for the student: {student_background_knowledge}\n\n- Text Flesch-Kincaid grade level: {fk_level}\n\n- Text to evaluate: [BEGIN TEXT]\n{text}\n[END TEXT]\n";
+
+// ../../evals/prompts/vocabulary/other-grades-user.txt
+var other_grades_user_default = `
+Your job is to rate the complexity of a text's vocabulary (relative to the intended level of the text) according to a rubric and annotation guide. Stick to the rubric and annotation guide exactly \u2014 do not introduce any additional criteria or lenses for judging the complexity of the text.
+
+[BEGIN ANNOTATION GUIDE AND RUBRIC]
+Instructions
+For the following task, please assume that:
+    - The student is on grade level and proficient in all core content areas, including reading fluency, comprehension, science, & social studies. (example).
+    - The student is moving through a common progression of topics (detailed here).
+    - The student is fluent in speaking English.
+    - The student has an "average" amount of background knowledge on topics not commonly covered in curriculum.
+    - The student will use this material for independent reading/work, without direct instruction.
+    - The text is reasonable for the given grade level.
+
+Please do not consider the presence of figurative language when scoring Vocabulary. For example: with a phrase like "kicked the bucket," consider only the qualities of the words themselves ("kicked", "the" and "bucket").
+
+Please do be sure to consider:
+- all of the different types of vocabulary (listed below)
+- the overall proportion of complex words in the text - including repeated complex words.
+- the resulting holistic complexity of the vocabulary (described in the Summary section below).
+
+Level 1:
+Rubric: Vocabulary that is almost entirely not complex: contemporary, conversational, and/or familiar. That said, a very low proportion of complex words (archaic, subject-specific, academic) is OK -- i.e. doesn't need to be 0.
+
+Level 2:
+Rubric: Vocabulary that is mostly not complex: contemporary, conversational, and/or familiar. A low proportion of complex words (archaic, subject-specific, academic) is OK, but if it's very low, the text is probably level 1.
+
+Level 3:
+Rubric: Vocabulary that is often complex: unfamiliar, archaic, subject-specific, and/or overly academic
+
+Level 4:
+Rubric: Vocabulary that is mostly complex: unfamiliar, archaic, subject-specific, and/or overly academic. May be ambiguous or purposefully misleading
+
+And here are some relevant definitions:
+    - Conversational: Everyday language.
+    - Familiar: Words that the student is likely to have seen/heard, from everyday life or their curriculum. Reminder: assume an "average" level of background knowledge.
+    - Unfamiliar: Words the student has probably not heard, or are being used in an unfamiliar way.
+        - For ex: 4th graders are familiar with the word "table" but may not be familiar with the use of the word with respect to data ("a table of data").
+        - Note:
+            - Words with in-line definitions (via appositives, or because they can be easily inferred from other parts of the text) should be evaluated as less unfamiliar.
+            - For ex: "The pharaoh, a powerful ruler of ancient Egypt, was buried in a grand tomb."
+                - The word "pharaoh" might be unfamiliar or subject-specific, but since is defined within the text, you can consider it a more familiar word.
+        - Unfamiliar proper nouns:
+            - A person's name, even if unfamiliar, generally does not add to complexity.
+            - Other unfamiliar proper nouns (eg locations, organizations) do add to complexity.
+
+- Subject-specific: Words that are specific to a subject or field of study that are essential for understanding concepts and engaging with the content.
+- Overly-academic: Words that are excessively formal, complex, or specialized.
+    - For ex: "The agrarian societal structure of the Neolithic Revolution precipitated a paradigm shift in agriculture"
+- Archaic: A word that was common in the past but is now rarely/almost never used. Could also be a word used in an archaic way.
+    - For ex: "After a long day of court proceedings, the jury 'retired' to deliberate on their verdict."
+        - The word "retire" meaning to stop working may be familiar to a student, but "retire" meaning "withdrawing to a private place" is an archaic use.
+
+
+Examples
+The student is on-grade-level:
+- Consider a 6th grade passage about earth systems. Per NGSS standards, students are introduced to earth systems starting in 2nd grade. They encounter words like: wind, water, river, lake, solids, and liquids. For our rating purposes, we would assume most students following 2nd have encountered these words. In 5th grade, they dive more fully into earth systems concepts, learning vocabulary words like geosphere, sediment, biosphere, atmosphere, ecosystems, organisms and climate. While rating, we would consider the words listed in the NGSS standards as more familiar following that grade level.  If the same passage were intended for 3rd graders, though, then the subject-specific vocabulary is likely to be unfamiliar.
+
+Figurative Language
+- Kicked the bucket.
+- The pen is mightier than the sword.
+- The classroom was a zoo.
+- He ran faster than the speed of light.
+[END ANNOTATION GUIDE AND RUBRIC]
+
+Here are a couple examples of texts that have already been scored along with justification for their scores, which you can use as exemplars:
+[BEGIN EXAMPLES]
+
+*** EXAMPLE 1 ***
+The following text was intended for grade level 11 and received a complexity level of 1.
+
+Here is the background knowledge assumption for that text: N/A
+
+Here is the text:
+// START TEXT //
+"In a recent lecture, "Is Nothing Sacred?", Salman Rushdie, one of the most censored authors of our time, talked about the importance of books. He grew up in a household in India where books were as sacred as bread. If anyone in the household dropped a piece of bread or a book, the person not only picked it up, but also kissed the object by way of apologizing for clumsy disrespect.
+
+He goes on to say that he had kissed many books before he had kissed a girl. Bread and books were for his household, and for many like his, food for the body and the soul. This image of the kissing of the book one had accidentally dropped made an impression on me. It speaks to the love and respect many people have for them.
+
+I grew up in a small town in New Mexico, and we had very few books in our household. The first one I remember reading was my catechism book. Before I went to school to learn English, my mother taught me catechism in Spanish.
+
+I remember the questions and answers I had to learn, and I remember the well-thumbed, frayed volume which was sacred to me.
+
+Growing up with few books in the house created in me a desire and a need for them. When I started school, I remember visiting the one room library of our town and standing in front of the dusty shelves. In reality there were only a few shelves and not over a thousand books, but I wanted to read them all. There was food for my soul in the books, that much I realized."
+// END TEXT //
+
+Here is the reasoning for that complexity level:
+// START REASONING //
+This text is a 1 for vocabulary, because the vocabulary that is used is familiar and accessible for a proficient 11th grader. Most of the words used in the text are very common everyday vocabulary for describing growing up, family life, and the importance of reading. A few examples of these very common words are: small town, book, school, learn, food, kissed, image, respect, love, speaks. There are many more in the text. In this text there are only a few "juicier" or more complex words, you can think of those as words that are less familiar, have a more abstract or nuanced meaning, or carry a very large concept. Less commonly spoken words that were used in the text were: frayed, volume, censored, clumsy, sacred. These are still well within reach of a proficient 11th grader, and would still be considered familiar, because they will have encountered them in past reading or academic studies. In the text there are a couple of words that are outliers, but they are not essential to the understanding of the larger text. One of these words or hyphenated compound phrase is well-frayed. A compound phrase is a phrase consisting of multiple words that work together to create a specific meaning or idea, often acting as a single unit in a sentence. If the meaning of individual words is familiar, it is typically quite easy for proficient readers to generalize the larger meaning that the author is implying with their word choice. In this case, proficient students will be accustomed to the phrase well, with the secondary meaning of very, rather than a description of positivity or health; and they will be accustomed to the use frayed, as in worn, aged, or damaged from use. Making the leap to identify the meaning of "well-frayed" as a book that is very used, will take only moments for a proficient 11th grader. Another word that stands out in the text is the word catechism, which might be new for many students based on their personal background or location, but a full understanding of what a catechism book contains is not essential for understanding the paragraph or whole text. The reader can make it through using minimum context clues to know that the catechism must be something important to his family. The type of book he learned to read before going to school is not critical for comprehension, it's enough to understand that reading was so important in his family, his mother started instruction before he even started school. Additionally, it's important to know that having one unknown word for an 11th grade reading, does not merit a rating higher than one.
+
+It is worth noting that another reason this text is a 1, is that the content or topic of the passage is so familiar and covered extensively in K-12 education, i.e. reading is important, loving books, growing up; that coupled with the simple vocabulary choices, getting to the meaning of the overall text, and even the paragraphs, would be incredibly easy for a proficient 11th grader.
+// END REASONING //
+*** EXAMPLE 2 ***
+The following text was intended for grade level 5 and received a complexity level of 2.
+
+Here is the background knowledge assumption for that text: Background Knowledge Assumption: Students are likely familiar with the concept of natural disasters, including hurricanes, and basic atmospheric concepts like high and low pressure from their studies on weather and climate. They may not be familiar with the specific formation processes of hurricanes or the global terminology differences (hurricane, typhoon, cyclone).
+
+Here is the text:
+// START TEXT //
+Great whirling storms roar out of the oceans in many parts of the world. They are called by several names\u2014hurricane, typhoon, and cyclone are the three most familiar ones. But no matter what they are called, they are all the same sort of storm. They are born in the same way, in tropical waters. They develop the same way, feeding on warm, moist air. And they do the same kind of damage, both ashore and at sea. Other storms may cover a bigger area or have higher winds, but none can match both the size and the fury of hurricanes. They are earth's mightiest storms.
+
+Like all storms, they take place in the atmosphere, the envelope of air that surrounds the earth and presses on its surface. The pressure at any one place is always changing. There are days when air is sinking and the atmosphere presses harder on the surface. These are the times of high pressure. There are days when a lot of air is rising and the atmosphere does not press down as hard. These are times of low pressure. Low-pressure areas over warm oceans give birth to hurricanes.
+// END TEXT //
+
+Here is the reasoning for that complexity level:
+// START REASONING //
+I scored this a 2 because of the density of subject-specific vocabulary related to weather and climate, which is often covered in lower grade levels. This adds to the complexity above a 1, but it is not a level 3 because of the familiarity with the topic, which implies some familiarity with the vocabulary as well. The specific formation process and the vocabulary used to explain the processes are also subject-specfiic but not famliar, which would make the second paragraph a level 3 in the rubric language, but when considering the language used in the overall SUMMARY below the rubric, this new content and vocabulary would cause quick pauses and/or occasional prolonged pauses but would not cause the reader to slow down to due to challenging overall comprehension of the key ideas and supporting claims. This is especially the case because the second paragraph builds upon prior knowledge and familiar vocabulary use, so it is not entirely new information and vocabulary. While there is subject-specific vocabulary used, overly academic vocabulary is NOT used and is more conversational in nature, such as "great whiring storms" and "born" / "giving birth" to storm  (although this is the way storms are described!) rather than more technical terms which made comprehension easier due to the accessibility of the vocabulary (even if used in other contexts before reading this text). Words such as "a lot" and "bigger" are more conversational, and while technical, unfamiliar words are provided, such as "hurricane," "typhoon," and "cyclone," knowing and understanding their differences is not necessary to grasp the main idea. The processes by which they are formed are what need to be retained while reading the entire text, and familiarity with the bulk of the vocabulary used would allow for that to happen without too much struggle to make meaning of it. Additionally, the text does not contain any archaic vocabulary or ambiguous words, which prevents it from reaching a rating of 4, although it is not necessary that they text have such vocabulary to meet a level 4, the frequent inclusion of such vocabulary makes it more likely to land at least a 3 or 4.
+// END REASONING //
+
+*** EXAMPLE 3 ***
+The following text was intended for grade level 6 and received a complexity level of 3.
+
+Here is the background knowledge assumption for that text: Background Knowledge Assumption: Students are likely familiar with basic Earth science concepts such as rocks, minerals, and fossils, as well as natural processes like volcanic eruptions and earthquakes. They may not be familiar with more advanced topics like plate tectonics or the specific branches of geology such as mineralogy, petrology, and seismology.
+
+Here is the text:
+// START TEXT //
+Geology is the scientific study of Earth. Geologists study the planet\u2014its formation, its internal structure, its materials, its chemical and physical processes, and its history. Mountains, valleys, plains, sea floors, minerals, rocks, fossils, and the processes that create and destroy each of these are all the domain of the geologist. Geology is divided into two broad categories of study: physical geology and historical geology.
+
+Physical geology is concerned with the processes occurring on or below the surface of Earth and the materials on which they operate. These processes include volcanic eruptions, landslides, earthquakes, and floods. Materials include rocks, air, seawater, soils, and sediment. Physical geology further divides into more specific branches, each of which deals with its own part of Earth's materials, landforms, and processes. Mineralogy and petrology investigate the composition and origin of minerals and rocks. Volcanologists study lava, rocks, and gases on live, dormant, and extinct volcanoes. Seismologists use instruments to monitor and predict earthquakes and volcanic eruptions.
+
+Historical geology is concerned with the chronology of events, both physical and biological, that have taken place in Earth's history. Paleontologists study fossils (remains of ancient life) for evidence of the evolution of life on Earth. Fossils not only relate evolution, but also speak of the environment in which the organism lived. Corals in rocks at the top of the Grand Canyon in Arizona, for example, show a shallow sea flooded the area around 290 million years ago. In addition, by determining the ages and types of rocks around the world, geologists piece together continental and oceanic history over the past few billion years. Plate tectonics (the study of the movement of the sections of Earth's crust) adds to Earth's story with details of the changing configuration of the continents and oceans.
+// END TEXT //
+
+Here is the reasoning for that complexity level:
+// START REASONING //
+To determine the complexity rating of this text based on the vocabulary present, I used the annotation guide, scoring rubric, and examples to set the expectations for rating. During the first read of the text, I "bolded" and categorized the more challenging vocabulary words according to the following complexity groupings: archaic, unfamiliar, archaic, subject-specific, and/or overly academic. On the second read, I considered the main idea or "gist" that students need to acquire understanding of. I then referenced the previously mentioned tools\u2013annotation guide, scoring rubric, and examples to remind myself of the expectations for rating.  I agreed that readers would have familiarity with basic concepts of geology; however, I also considered the definitions provided for words such as Geology, Geologists, Physical Geology, Historical Geology, Mineralogy, and Petrology. I considered how students might pause for clarification and for how long. After reviewing the Annotation Guide while considering, I narrowed the rating down because the definitions provided throughout the text of more complex words should make the meaning of the text more accessible for readers, which is why although the words are subject-specific, I rated this text as a 3 instead of a 2-less complex or a 4\u2013more complex. I read the text one final time to ensure clarity around my rating, scored and wrote the justification.
+// END REASONING //
+[END EXAMPLES]
+
+Below is the text you need to evaluate. It is intended for grade {student_grade_level}.
+
+As you read the text, you can assume the student has the following background knowledge about the text \u2014 this background knowledge influences which words from the text are familiar versus unfamiliar for the student: {student_background_knowledge}
+
+[BEGIN TEXT]
+{text}
+[END TEXT]
+
+In your response, when specifying the level of complexity, be sure to use only a single integer (e.g. 2) and don't include any other text (e.g. don't say "level 2").
+`;
+
+// src/prompts/vocabulary/user.ts
+function getUserPrompt(text, studentGradeLevel, studentBackgroundKnowledge, fkLevel) {
+  const template = studentGradeLevel === "3" || studentGradeLevel === "4" ? grades_3_4_user_default : other_grades_user_default;
+  return template.replaceAll("{student_grade_level}", studentGradeLevel).replaceAll("{student_background_knowledge}", studentBackgroundKnowledge).replaceAll("{fk_level}", fkLevel.toString()).replaceAll("{text}", text);
+}
+
+// src/evaluators/vocabulary.ts
+var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
+  static metadata = {
+    id: "vocabulary",
+    name: "Vocabulary",
+    description: "Evaluates vocabulary complexity of educational texts relative to grade level",
+    supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
+    requiresGoogleKey: true,
+    requiresOpenAIKey: true
+  };
+  grades34ComplexityProvider;
+  otherGradesComplexityProvider;
+  backgroundKnowledgeProvider;
+  constructor(config) {
+    super(config);
+    this.grades34ComplexityProvider = createProvider({
+      type: "google",
+      model: "gemini-2.5-pro",
+      apiKey: config.googleApiKey,
+      maxRetries: this.config.maxRetries
+    });
+    this.otherGradesComplexityProvider = createProvider({
+      type: "openai",
+      model: "gpt-4.1-2025-04-14",
+      apiKey: config.openaiApiKey,
+      maxRetries: this.config.maxRetries
+    });
+    this.backgroundKnowledgeProvider = createProvider({
+      type: "openai",
+      model: "gpt-4o-2024-11-20",
+      apiKey: config.openaiApiKey,
+      maxRetries: this.config.maxRetries
+    });
+  }
+  /**
+   * Evaluate vocabulary complexity for a given text and grade level
+   *
+   * @param text - The text to evaluate
+   * @param grade - The target grade level (3-12)
+   * @returns Evaluation result with complexity score and detailed analysis
+   * @throws {ValidationError} If text is empty, too short/long, or grade is invalid
+   * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+   */
+  async evaluate(text, grade) {
+    this.logger.info("Starting vocabulary evaluation", {
+      evaluator: "vocabulary",
+      operation: "evaluate",
+      grade,
+      textLength: text.length
+    });
+    const startTime = Date.now();
+    const stageDetails = [];
+    const complexityProviderName = grade === "3" || grade === "4" ? "google:gemini-2.5-pro" : "openai:gpt-4.1-2025-04-14";
+    try {
+      this.validateText(text);
+      this.validateGrade(grade, new Set(_VocabularyEvaluator.metadata.supportedGrades));
+      this.logger.debug("Stage 1: Generating background knowledge", {
+        evaluator: "vocabulary",
+        operation: "background_knowledge"
+      });
+      const bgResponse = await this.getBackgroundKnowledgeAssumption(text, grade);
+      stageDetails.push({
+        stage: "background_knowledge",
+        provider: "openai:gpt-4o-2024-11-20",
+        latency_ms: bgResponse.latencyMs,
+        token_usage: {
+          input_tokens: bgResponse.usage.inputTokens,
+          output_tokens: bgResponse.usage.outputTokens
+        }
+      });
+      const fkLevel = calculateFleschKincaidGrade(text);
+      const complexityResponse = await this.evaluateComplexity(
+        text,
+        grade,
+        bgResponse.knowledge.assumption,
+        fkLevel
+      );
+      stageDetails.push({
+        stage: "complexity_evaluation",
+        provider: complexityProviderName,
+        latency_ms: complexityResponse.latencyMs,
+        token_usage: {
+          input_tokens: complexityResponse.usage.inputTokens,
+          output_tokens: complexityResponse.usage.outputTokens
+        }
+      });
+      const latencyMs = Date.now() - startTime;
+      const totalTokenUsage = {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      };
+      const result = {
+        score: complexityResponse.data.complexity_score,
+        reasoning: complexityResponse.data.reasoning,
+        metadata: {
+          model: `openai:gpt-4o-2024-11-20 + ${complexityProviderName}`,
+          processingTimeMs: latencyMs
+        },
+        _internal: complexityResponse.data
+      };
+      this.sendTelemetry({
+        status: "success",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: `openai:gpt-4o-2024-11-20 + ${complexityProviderName}`,
+        tokenUsage: totalTokenUsage,
+        metadata: {
+          stage_details: stageDetails
+        },
+        inputText: text
+      }).catch(() => {
+      });
+      this.logger.info("Vocabulary evaluation completed successfully", {
+        evaluator: "vocabulary",
+        operation: "evaluate",
+        grade,
+        score: result.score,
+        processingTimeMs: latencyMs
+      });
+      return result;
+    } catch (error) {
+      const latencyMs = Date.now() - startTime;
+      this.logger.error("Vocabulary evaluation failed", {
+        evaluator: "vocabulary",
+        operation: "evaluate",
+        grade,
+        error: error instanceof Error ? error : void 0,
+        processingTimeMs: latencyMs,
+        completedStages: stageDetails.length
+      });
+      const totalTokenUsage = stageDetails.length > 0 ? {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      } : void 0;
+      this.sendTelemetry({
+        status: "error",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: `openai:gpt-4o-2024-11-20 + ${complexityProviderName}`,
+        tokenUsage: totalTokenUsage,
+        errorCode: error instanceof Error ? error.name : "UnknownError",
+        metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
+        inputText: text
+      }).catch(() => {
+      });
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+      throw wrapProviderError(error, "Vocabulary evaluation failed");
+    }
+  }
+  /**
+   * Stage 1: Generate background knowledge assumption
+   *
+   * Estimates what topics the student at the given grade level would be familiar with
+   * based on Common Core curriculum progression.
+   */
+  async getBackgroundKnowledgeAssumption(text, grade) {
+    const prompt = getBackgroundKnowledgePrompt(text, grade);
+    const response = await this.backgroundKnowledgeProvider.generateText(
+      [{ role: "user", content: prompt }],
+      0
+      // temperature = 0 for consistency
+    );
+    return {
+      knowledge: {
+        assumption: response.text.trim(),
+        grade
+      },
+      usage: response.usage,
+      latencyMs: response.latencyMs
+    };
+  }
+  /**
+   * Stage 2: Evaluate vocabulary complexity
+   *
+   * Uses the Qual Text Complexity rubric (SAP) and background knowledge to evaluate vocabulary complexity.
+   * Grades 3-4 use Gemini 2.5 Pro; grades 5-12 use GPT-4.1.
+   */
+  async evaluateComplexity(text, grade, backgroundKnowledge, fkLevel) {
+    const systemPrompt = getSystemPrompt(grade);
+    const userPrompt = getUserPrompt(text, grade, backgroundKnowledge, fkLevel);
+    const provider = grade === "3" || grade === "4" ? this.grades34ComplexityProvider : this.otherGradesComplexityProvider;
+    const response = await provider.generateStructured({
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt }
+      ],
+      schema: VocabularyComplexitySchema,
+      temperature: 0
+    });
+    return {
+      data: response.data,
+      usage: response.usage,
+      latencyMs: response.latencyMs
+    };
+  }
+};
+var SentenceAnalysisSchema = z.object({
+  reasoning: z.string().describe("Step-by-step reasoning for the analysis"),
+  // Foundational
+  num_sentences: z.number().int().describe("Total number of sentences in the text"),
+  num_words: z.number().int().describe("Total number of words in the text"),
+  flesch_kincaid_grade: z.number().describe("Flesch-Kincaid Grade Level number"),
+  // Sentence Type
+  num_simple_sentences: z.number().int().describe("Number of simple sentences"),
+  num_compound_sentences: z.number().int().describe("Number of compound sentences"),
+  num_complex_sentences: z.number().int().describe("Number of complex sentences"),
+  num_compound_complex_sentences: z.number().int().describe("Number of compound-complex sentences"),
+  num_other_sentences: z.number().int().describe("Number of other sentence types"),
+  // Subordination
+  num_independent_clauses: z.number().int(),
+  num_subordinate_clauses: z.number().int(),
+  num_total_clauses: z.number().int(),
+  num_sentences_with_subordinate: z.number().int(),
+  num_sentences_with_multiple_subordinates: z.number().int(),
+  num_sentences_with_embedded_clauses: z.number().int(),
+  // Informational Phrases
+  num_prepositional_phrases: z.number().int(),
+  num_participle_phrases: z.number().int(),
+  num_appositive_phrases: z.number().int(),
+  // Cohesion
+  num_simple_transitions: z.number().int(),
+  num_sophisticated_transitions: z.number().int(),
+  // Sentence Type Density
+  words_in_simple_sentences: z.number().int(),
+  words_in_compound_sentences: z.number().int(),
+  words_in_complex_sentences: z.number().int(),
+  words_in_compound_complex_sentences: z.number().int(),
+  words_in_other_sentences: z.number().int(),
+  // Additional Features
+  sentence_word_counts: z.array(z.number().int()),
+  num_one_concept_sentences: z.number().int(),
+  num_multi_concept_sentences: z.number().int(),
+  num_cleft_sentences: z.number().int(),
+  max_clauses_in_any_sentence: z.number().int(),
+  // Grades 5-12 specific
+  num_compound: z.number().int().describe("Number of compound sentences"),
+  num_basic_complex: z.number().int().describe("Number of basic complex sentences"),
+  num_advanced_complex: z.number().int().describe("Number of advanced complex sentences"),
+  percentage_simple: z.number().describe("Percentage of simple sentences"),
+  percentage_compound: z.number().describe("Percentage of compound sentences"),
+  percentage_basic_complex: z.number().describe("Percentage of basic complex sentences"),
+  percentage_advanced_complex: z.number().describe("Percentage of advanced complex sentences")
+});
+var ComplexityClassificationSchema = z.object({
+  reasoning: z.string().describe("Detailed pedagogically appropriate reasoning"),
+  answer: TextComplexityLevel
+});
+
+// ../../evals/prompts/sentence-structure/analysis-system.txt
+var analysis_system_default = "You are an expert in grammar and literacy.";
+
+// ../../evals/prompts/sentence-structure/analysis-user.txt
+var analysis_user_default = `
+# Task
+I am going to give you a text, and I need you to look through the text sentence-by-sentence to perform a comprehensive grammatical analysis. Use the computational counts as a reference; they can be incorrect in ambiguous cases.
+
+# Definitions
+* Sentences: Count a complete grammatical unit ending in a terminal punctuation mark.
+* Words: Count any sequence of characters separated by a space as one word. Treat hyphenated words (e.g., "state-of-the-art") and numbers (e.g., "2025") as single words.
+* Independent Clauses: Clauses that can stand alone as a complete sentence.
+* Subordinate Clauses: Clauses that are dependent on the main clause and cannot stand alone as a complete sentence.
+* Simple Sentences: Sentences with one independent clause and no subordinate clauses.
+* Compound Sentences: Sentences with two or more independent clauses and no subordinate clauses.
+* Complex Sentences: Sentences with one independent clause and at least one subordinate clause.
+* Compound-Complex Sentences: Sentences with two or more independent clauses and at least one subordinate clause.
+* Other / Non-Canonical Sentences: Sentences that cannot be reliably classified as simple, compound, complex, or compound-complex (e.g., sentence fragments, run-ons, elliptical responses, headlines, imperatives lacking an explicit subject, or stylized dialogue tags).
+* Subordinate Clauses: Clauses that are dependent on the main clause and cannot stand alone as a complete sentence.
+* Embedded Clauses: Clauses that are nested within another clause.
+* Prepositional Phrases: Phrases that begin with a preposition and end with a noun phrase.
+* Participle Phrases: Phrases that begin with a participle and end with a noun phrase.
+* Appositive Phrases: Phrases that rename or identify a noun phrase.
+* Simple Transitions: Basic coordinating conjunctions and chronological adverbs. Examples: 'and', 'but', 'or', 'so', 'then', 'next', 'first'.
+* Sophisticated Transitions: Conjunctive adverbs and phrases signaling logical relationships. Examples: 'however', 'therefore', 'consequently', 'as a result', 'for example', 'although'.
+* One-Concept Sentence: A sentence with ZERO subordinate clauses AND ZERO transition words/phrases (neither simple nor sophisticated).
+* Multi-Concept Sentence: Any sentence that has \u22651 subordinate clause OR \u22651 transition word/phrase (or both).
+* Basic Complex Sentences: Sentences with exactly one independent clause and at one dependent (subordinate) clause.
+* Advanced Complex Sentences: Sentences with two or more of any of those following (can include a mix, doesn't have to be two of the same type) subordinate phrases, clauses, transition words, or any other meaningful "interruptions" to the flow of the sentence (like not-only-but-also constructions, dashes, semicolons, and lengthy appositives). A sentence can be advanced complex if it has just one subordinate phrase or clause alongside a transition phrase, like: "For example, the British favored trade with Hong Kong, assuming favorable trade conditions.
+
+# Computational Counts
+Use these as reference, your internal heuristics can be more reliable.
+{ground_truth_counts}
+
+# Text to Analyze
+[BEGIN TEXT]
+{text}
+[END TEXT]
+
+IMPORTANT: Your response should be a single JSON object with the following structure. Do not produce anything outside of the JSON object.
+
+{format_instructions}
+`;
+
+// src/prompts/sentence-structure/analysis.ts
+function getSystemPromptAnalysis() {
+  return analysis_system_default;
+}
+function getUserPromptAnalysis(text, groundTruthCounts) {
+  return analysis_user_default.replace("{text}", text).replace("{ground_truth_counts}", groundTruthCounts).replace("{format_instructions}", "");
+}
+
+// ../../evals/prompts/sentence-structure/complexity-system.txt
+var complexity_system_default = "You are an expert in grammar and literacy, and understand K-12 and Qualitative Text Complexity rubric (SAP).";
+
+// ../../evals/prompts/sentence-structure/complexity-user.txt
+var complexity_user_default = '\nYour task is to perform a text complexity analysis for a Grade {grade} student. You will be given a text excerpt and a set of quantitative sentence-level statistics for that text.\n\nYou must integrate both the qualitative aspects of the text and the quantitative statistics to make your final judgment. Do not rely on the numbers alone.\n\n1.  Read the TEXT EXCERPT to understand its topic, conceptual load, and overall structure.\n2.  Review the TEXT STATISTICS as a guide for complexity level.\n3.  Synthesize your findings in your reasoning. Explain how the structure (qualitative) interact with the text statistics (quantitative) to determine the complexity. For example, a text with simple sentences might still be complex if the topic is very dense or abstract.\n\nYour final answer must be one of ["Slightly Complex," "Moderately Complex," "Very Complex", "Exceedingly Complex"].\n\n# GRADE {grade} RUBRIC\n{rubric}\n\n# TEXT EXCERPT\n[BEGIN TEXT]\n{excerpt}\n[END TEXT]\n\n# TEXT STATISTICS\n{sentence_features}\n\n# OUTPUT FORMAT\n{format_instructions}\n';
+
+// ../../evals/prompts/sentence-structure/rubric-grade-3.txt
+var rubric_grade_3_default = '\n    **Instructions for Analysis:** First, evaluate if the text meets the criteria for "Slightly Complex" or "Exceedingly Complex". If it does not fit into these categories, then decide between "Moderately Complex" and "Very Complex".\n\n    **Slightly Complex:**\n    * **Description:** The text consists of simple, straightforward language and sentence structures.\n    * **Statistical Guidelines:** The text is likely "Slightly Complex" if it meets at least TWO of the following criteria:\n        * **Sentence Type:** Primarily simple sentences. (`percent_simple_sentences` is typically > 60%).\n        * **Sentence Length:** Short sentences. (`avg_sentence_length` is typically < 12 words).\n        * **Subordination:** Very low use of clauses. (`percent_sentences_with_subordinate` is typically < 25%).\n\n    **Moderately Complex:**\n    * **Description:** The text shows a mix of simple and more complex sentences, introducing some variety in structure without being overly demanding.\n    * **Statistical Guidelines:** If the text is not "Slightly Complex", consider "Moderately Complex" if it generally aligns with these ranges:\n        * **Sentence Type:** A balanced mix of sentence types. (`percent_simple_sentences` is typically between 40% and 60%).\n        * **Sentence Length:** Medium length sentences. (`avg_sentence_length` is typically between 12 and 16 words).\n        * **Subordination:** A moderate use of clauses. (`percent_sentences_with_subordinate` is typically between 25% and 45%).\n\n    **Very Complex:**\n    * **Description:** The text features more elaborate sentences with multiple clauses and ideas, requiring more effort from the reader to parse. This is often the default category for grade-level text that isn\'t simple or exceptionally difficult.\n    * **Statistical Guidelines:** If the text is more complex than "Moderately" but does not meet the "Exceedingly" criteria, it is likely "Very Complex". Key indicators include:\n        * **Sentence Type:** Complex structures are common. (`percent_simple_sentences` is a minority, typically < 40%).\n        * **Sentence Length:** Longer sentences are frequent. (`avg_sentence_length` is typically between 16 and 19 words).\n        * **Subordination:** Subordinate clauses are a key feature. (`percent_sentences_with_subordinate` is typically > 45%).\n\n    **Exceedingly Complex:**\n    * **Description:** The text is dense with very long, intricate sentences and a high degree of subordination, making it exceptionally challenging for this grade level.\n    * **Statistical Guidelines:** The text is "Exceedingly Complex" if it shows an extreme combination of sentence length and structural density. It should meet at least **TWO** of the following criteria, including at least **ONE** from the "Structural Density" group.\n        * **Structural Density Indicators:**\n            * High Subordination: `percent_sentences_with_subordinate` is extensive (typically > 50%).\n            * Multiple Subordinates: `percent_sentences_with_multiple_subordinates` is consistently present (typically > 12%).\n            * High Syntactic Complexity: `percent_compound_complex_sentences` is significant (typically > 15%).\n        * **Length Indicators:**\n            * Extreme Sentence Length: `avg_sentence_length` is very long (typically > 19 words).\n            * Low Simplicity: `percent_simple_sentences` is very low (typically < 30%).\n            * Concentrated Length: `percent_very_long_sentences` is notable (typically > 10%).\n';
+
+// ../../evals/prompts/sentence-structure/rubric-grade-4.txt
+var rubric_grade_4_default = '\n    **Instructions for Analysis:** First, evaluate if the text meets the criteria for "Slightly Complex" or "Exceedingly Complex". If it does not fit into these categories, then decide between "Moderately Complex" and "Very Complex".\n\n    **Slightly Complex:**\n    * **Description:** The text uses clear, direct language with basic sentence structures appropriate for developing readers.\n    * **Statistical Guidelines:** The text is likely "Slightly Complex" if it meets at least TWO of the following criteria:\n        * **Sentence Type:** Dominated by simple sentences. (`percent_simple_sentences` is typically > 55%).\n        * **Sentence Length:** Short to medium sentences. (`avg_sentence_length` is typically < 13 words).\n        * **Subordination:** Infrequent use of clauses. (`percent_sentences_with_subordinate` is typically < 30%).\n\n    **Moderately Complex:**\n    * **Description:** The text contains a variety of sentence structures, including compound and complex sentences, but remains accessible.\n    * **Statistical Guidelines:** If the text is not "Slightly Complex", consider "Moderately Complex" if it generally aligns with these ranges:\n        * **Sentence Type:** A healthy mix of sentence types. (`percent_simple_sentences` is typically between 40% and 55%).\n        * **Sentence Length:** Medium length sentences. (`avg_sentence_length` is typically between 13 and 17 words).\n        * **Subordination:** A moderate number of clauses. (`percent_sentences_with_subordinate` is typically between 30% and 50%).\n\n    **Very Complex:**\n    * **Description:** The text is characterized by longer sentences and the regular use of dependent clauses, requiring readers to track multiple ideas. This is the default for challenging, on-grade-level texts.\n    * **Statistical Guidelines:** If the text is more complex than "Moderately" but does not meet the "Exceedingly" criteria, it is likely "Very Complex". Key indicators include:\n        * **Sentence Type:** Simple sentences are a clear minority. (`percent_simple_sentences` is typically < 40%).\n        * **Sentence Length:** Sentences are consistently long. (`avg_sentence_length` is typically between 17 and 22 words).\n        * **Subordination:** Subordination is a major feature. (`percent_sentences_with_subordinate` is typically > 50%).\n        * **Multiple Subordination:** Sentences with multiple clauses appear more often. (`percent_sentences_with_multiple_subordinates` is typically > 8%).\n\n    **Exceedingly Complex:**\n    * **Description:** The text\'s structure is highly sophisticated and dense, marked by extensive use of embedded clauses and long, flowing sentences that are well above grade-level expectations.\n    * **Statistical Guidelines:** A text is "Exceedingly Complex" if its structure is highly sophisticated and dense. It should meet at least **TWO** of the following criteria, including at least **ONE** from the "Structural Density" group.\n        * **Structural Density Indicators:**\n            * High Subordination: `percent_sentences_with_subordinate` is very high (typically > 60%).\n            * Multiple Subordinates: `percent_sentences_with_multiple_subordinates` is high and consistent (typically > 15%).\n            * High Syntactic Complexity: `percent_compound_complex_sentences` is a notable feature (typically > 20%).\n        * **Length Indicators:**\n            * Extreme Sentence Length: `avg_sentence_length` is exceptionally long (typically > 22 words).\n            * Low Simplicity: `percent_simple_sentences` is very low (typically < 25%).\n            * Concentrated Length: `percent_very_long_sentences` is significant (typically > 15%).\n';
+
+// ../../evals/prompts/sentence-structure/rubric-grades-5-12.txt
+var rubric_grades_5_12_default = "\n    **Slightly Complex:** A text is in the Slightly Complex bucket if it has at least 50% simple sentences. If it doesn't, the text is a higher level of complexity. If the % of simple sentences is >= 50% and the % of compound sentences is >= 20%, the text is Moderately Complex, otherwise, the text is Slightly Complex. Slightly Complex texts NEVER have advanced complex sentences \u2014 the presence of an advanced complex sentence always leads to a higher level of complexity than Slightly.\n    **For Moderately Complex:** These texts can take on any distribution of sentence types as long as there aren't more than 2 advanced complex sentences and as long as there aren't so many simple sentences that the text becomes Slightly Complex. That means Moderately Complex texts may have many simple sentences (although not so many that the text is Slightly Complex), compound sentences, and/or basic complex sentences. It's also possible for a moderately complex text to contain one or two advanced complex sentences, as long as there aren't more than 2. If there are more than 2, then the text is either Very or Exceedingly complex.\n    **Very Complex:** These texts contain 3 or more advanced complex sentences (unless the percentage of advanced complex sentences is >= 65)%, in which case the text becomes Exceedingly Complex). They may still contain many simple, compound, and basic complex sentences, but a text is not Very Complex unless there are 3 or more advanced complex sentences.\n    **Exceedingly Complex:** These texts have 65%+ of their sentences being advanced complex sentences.\n";
+
+// src/prompts/sentence-structure/complexity.ts
+function getSystemPromptComplexity() {
+  return complexity_system_default;
+}
+function getRubricForGrade(grade) {
+  if (grade === "3") {
+    return rubric_grade_3_default;
+  } else if (grade === "4") {
+    return rubric_grade_4_default;
+  } else {
+    return rubric_grades_5_12_default;
+  }
+}
+function getUserPromptComplexity(sentenceFeatures, grade, excerpt) {
+  const rubric = getRubricForGrade(grade);
+  return complexity_user_default.replace("{sentence_features}", sentenceFeatures).replace("{grade}", grade).replace("{rubric}", rubric).replace("{excerpt}", excerpt).replace("{format_instructions}", "");
+}
+
+// src/evaluators/sentence-structure.ts
+function normalizeLabel(label) {
+  if (!label) {
+    return null;
+  }
+  const normalized = label.trim().toLowerCase().replace(/_/g, " ");
+  const mapping = {
+    "slightly complex": "Slightly complex",
+    "moderately complex": "Moderately complex",
+    "very complex": "Very complex",
+    "exceedingly complex": "Exceedingly complex",
+    "extremely complex": "Exceedingly complex"
+  };
+  return mapping[normalized] ?? null;
+}
+var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseEvaluator {
+  static metadata = {
+    id: "sentence-structure",
+    name: "Sentence Structure",
+    description: "Evaluates sentence structure complexity based on grammatical features",
+    supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
+    requiresGoogleKey: false,
+    requiresOpenAIKey: true
+  };
+  analysisProvider;
+  complexityProvider;
+  constructor(config) {
+    super(config);
+    this.analysisProvider = createProvider({
+      type: "openai",
+      model: "gpt-4o",
+      apiKey: config.openaiApiKey,
+      maxRetries: this.config.maxRetries
+    });
+    this.complexityProvider = createProvider({
+      type: "openai",
+      model: "gpt-4o",
+      apiKey: config.openaiApiKey,
+      maxRetries: this.config.maxRetries
+    });
+  }
+  /**
+   * Evaluate sentence structure complexity for a given text and grade level
+   *
+   * @param text - The text to evaluate
+   * @param grade - The target grade level (3-12)
+   * @returns Evaluation result with complexity score and detailed analysis
+   * @throws {ValidationError} If text is empty, too short/long, or grade is invalid
+   * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+   */
+  async evaluate(text, grade) {
+    this.logger.info("Starting sentence structure evaluation", {
+      evaluator: "sentence-structure",
+      operation: "evaluate",
+      grade,
+      textLength: text.length
+    });
+    const startTime = Date.now();
+    const stageDetails = [];
+    try {
+      this.validateText(text);
+      this.validateGrade(grade, new Set(_SentenceStructureEvaluator.metadata.supportedGrades));
+      this.logger.debug("Stage 1: Analyzing sentence structure", {
+        evaluator: "sentence-structure",
+        operation: "sentence_analysis"
+      });
+      const analysisResponse = await this.analyzeSentenceStructure(text);
+      stageDetails.push({
+        stage: "sentence_analysis",
+        provider: "openai:gpt-4o",
+        latency_ms: analysisResponse.latencyMs,
+        token_usage: {
+          input_tokens: analysisResponse.usage.inputTokens,
+          output_tokens: analysisResponse.usage.outputTokens
+        }
+      });
+      const features = addEngineeredFeatures(analysisResponse.data);
+      this.logger.debug("Stage 2: Classifying complexity", {
+        evaluator: "sentence-structure",
+        operation: "complexity_classification"
+      });
+      const complexityResponse = await this.classifyComplexity(features, grade, text);
+      stageDetails.push({
+        stage: "complexity_classification",
+        provider: "openai:gpt-4o",
+        latency_ms: complexityResponse.latencyMs,
+        token_usage: {
+          input_tokens: complexityResponse.usage.inputTokens,
+          output_tokens: complexityResponse.usage.outputTokens
+        }
+      });
+      const latencyMs = Date.now() - startTime;
+      const totalTokenUsage = {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      };
+      const result = {
+        score: complexityResponse.data.answer,
+        reasoning: complexityResponse.data.reasoning,
+        metadata: {
+          model: "openai:gpt-4o",
+          processingTimeMs: latencyMs
+        },
+        _internal: {
+          sentenceAnalysis: analysisResponse.data,
+          features,
+          complexity: complexityResponse.data
+        }
+      };
+      this.sendTelemetry({
+        status: "success",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: "openai:gpt-4o",
+        tokenUsage: totalTokenUsage,
+        metadata: {
+          stage_details: stageDetails
+        },
+        inputText: text
+      }).catch(() => {
+      });
+      this.logger.info("Sentence structure evaluation completed successfully", {
+        evaluator: "sentence-structure",
+        operation: "evaluate",
+        grade,
+        score: result.score,
+        processingTimeMs: latencyMs
+      });
+      return result;
+    } catch (error) {
+      const latencyMs = Date.now() - startTime;
+      this.logger.error("Sentence structure evaluation failed", {
+        evaluator: "sentence-structure",
+        operation: "evaluate",
+        grade,
+        error: error instanceof Error ? error : void 0,
+        processingTimeMs: latencyMs,
+        completedStages: stageDetails.length
+      });
+      const totalTokenUsage = stageDetails.length > 0 ? {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      } : void 0;
+      this.sendTelemetry({
+        status: "error",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: "openai:gpt-4o",
+        tokenUsage: totalTokenUsage,
+        errorCode: error instanceof Error ? error.name : "UnknownError",
+        metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
+        inputText: text
+      }).catch(() => {
+      });
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+      throw wrapProviderError(error, "Sentence structure evaluation failed");
+    }
+  }
+  /**
+   * Stage 1: Analyze sentence grammatical structure
+   *
+   * Analyzes sentence types, clauses, phrases, transitions, and other grammatical features
+   */
+  async analyzeSentenceStructure(text) {
+    const metrics = calculateReadabilityMetrics(text);
+    const gtCountsStr = [
+      `num_sentences: ${metrics.sentenceCount}`,
+      `num_words: ${metrics.wordCount}`,
+      `num_char: ${metrics.characterCount}`,
+      `num_syllable: ${metrics.syllableCount}`,
+      `flesch_kincaid_grade: ${metrics.fleschKincaidGrade}`
+    ].join("\n");
+    const userPrompt = getUserPromptAnalysis(text, gtCountsStr);
+    const response = await this.analysisProvider.generateStructured({
+      messages: [
+        { role: "system", content: getSystemPromptAnalysis() },
+        { role: "user", content: userPrompt }
+      ],
+      schema: SentenceAnalysisSchema,
+      temperature: 0
+    });
+    return {
+      data: response.data,
+      usage: response.usage,
+      latencyMs: response.latencyMs
+    };
+  }
+  /**
+   * Stage 2: Classify sentence structure complexity
+   *
+   * Uses engineered features and grade-specific rubric to classify complexity level
+   */
+  async classifyComplexity(features, grade, excerpt) {
+    const featuresJSON = featuresToJSON(features, 1, true);
+    const userPrompt = getUserPromptComplexity(featuresJSON, grade, excerpt);
+    const response = await this.complexityProvider.generateStructured({
+      messages: [
+        { role: "system", content: getSystemPromptComplexity() },
+        { role: "user", content: userPrompt }
+      ],
+      schema: ComplexityClassificationSchema,
+      temperature: 0
+    });
+    const normalizedAnswer = normalizeLabel(response.data.answer);
+    if (!normalizedAnswer) {
+      throw new Error(
+        `Failed to normalize complexity label. Received unexpected value: "${response.data.answer}". Expected one of: Slightly Complex, Moderately Complex, Very Complex, Exceedingly Complex, Extremely Complex.`
+      );
+    }
+    return {
+      data: {
+        ...response.data,
+        answer: normalizedAnswer
+      },
+      usage: response.usage,
+      latencyMs: response.latencyMs
+    };
+  }
+};
+var GradeBand = z.enum(["K-1", "2-3", "4-5", "6-8", "9-10", "11-CCR"]);
+var GradeLevelAppropriatenessSchema = z.object({
+  reasoning: z.string().describe(
+    "Your reasoning for your answer in numbered bullet points for 4 steps with a 4th bullet point for synthesis."
+  ),
+  grade: GradeBand.describe("The appropriate grade level for the text"),
+  alternative_grade: GradeBand.describe("An alternative grade level for the text"),
+  scaffolding_needed: z.string().describe("Scaffolding needed for the text to be appropriate for the alternative grade")
+});
+
+// ../../evals/prompts/grade-level-appropriateness/system.txt
+var system_default = "\nYou are an expert in English literature education for K-12.\nYour job is to help evaluate the grade level appropriateness of a given text.\n\nYou will be given a text and you should determine which grade level the text is appropriate for (grade levels include: K-1, 2-3, 4-5, 6-8, 9-10, 11-CCR)\n\nIMPORTANT: You should pay attention to the vocabulary used, topics of the text and readability of text.\n\nPlease first reason out loud about the vocabulary complexity of the text and then provide an answer between grade level options: K-1, 2-3, 4-5, 6-8, 9-10, 11-CCR.\n\n";
+
+// ../../evals/prompts/grade-level-appropriateness/user.txt
+var user_default = '\nUse these steps to determine appropriate grade level for a text:\n1. Calculate word count and Flesch-Kincaid Grade Level of the text, and generate a grade band.\nHere are the bands guideline for word count\n\n2-3: 200-800 words\n4-5: 200-800 words\n6-8: 400-1000 words\n9-10: 500-1500 words\n11-12: 1501 words and more\n\nHere is the formula for Flesch-Kincaid Grade Level:\nFlesch-Kincaid Grade Level = 0.39 * (total words / total sentences) + 11.8 * (total syllables / total words) - 15.59\n\n\n2. Determine the qualitative complexity using this text complexity rubric:\nTEXT STRUCTURE\n\nExceedingly Complex\n    \u2022	Deep, intricate, often ambiguous connections between many ideas/processes/events\n    \u2022	Organization is intricate or discipline-specific\n    \u2022	Text features are essential for understanding\n    \u2022	Graphics are intricate, extensive, and integral to meaning; may convey unique information\n\nVery Complex\n    \u2022	Expanded ideas/processes/events with implicit or subtle connections\n    \u2022	Organization may have multiple pathways or discipline-specific traits\n    \u2022	Text features directly enhance understanding\n    \u2022	Graphics support or are integral to understanding\n\nModerately Complex\n    \u2022	Some implicit/subtle connections between ideas/events\n    \u2022	Organization is evident and generally sequential or chronological\n    \u2022	Text features enhance understanding\n    \u2022	Graphics are mostly supplementary\n\nSlightly Complex\n    \u2022	Explicit and clear connections between ideas/events\n    \u2022	Organization is chronological, sequential, or predictable\n    \u2022	Text features help navigation but are not essential\n    \u2022	Graphics are simple, not necessary, but may assist understanding\n\n\u2E3B\n\nLANGUAGE FEATURES\n\nExceedingly Complex\n    \u2022	Dense, abstract, ironic, and/or figurative language\n    \u2022	Complex, unfamiliar, archaic, subject-specific, or ambiguous vocabulary\n    \u2022	Mainly complex sentences with multiple subordinate clauses and transitions\n\nVery Complex\n    \u2022	Fairly complex; some abstract, ironic, and/or figurative language\n    \u2022	Some unfamiliar, archaic, or overly academic vocabulary\n    \u2022	Many complex sentences with subordinate phrases/clauses\n\nModerately Complex\n    \u2022	Mostly explicit language with some complex meaning\n    \u2022	Mostly familiar and conversational vocabulary\n    \u2022	Primarily simple and compound sentences, with some complex ones\n\nSlightly Complex\n    \u2022	Explicit, literal, straightforward language\n    \u2022	Contemporary, familiar, conversational vocabulary\n    \u2022	Mainly simple sentences\n\n\u2E3B\n\nPURPOSE\n\nExceedingly Complex\n    \u2022	Subtle, intricate, and difficult to determine\n    \u2022	Includes many theoretical or abstract elements\n\nVery Complex\n    \u2022	Implicit or subtle, fairly easy to infer\n    \u2022	More theoretical or abstract than concrete\n\nModerately Complex\n    \u2022	Implied but easy to identify based on context or source\n\nSlightly Complex\n    \u2022	Explicitly stated, clear, concrete, and narrowly focused\n\n\u2E3B\n\nKNOWLEDGE DEMANDS\n\nExceedingly Complex\n    \u2022	Requires extensive discipline-specific or theoretical knowledge\n    \u2022	Many references/allusions to other texts or ideas\n\nVery Complex\n    \u2022	Requires moderate discipline-specific knowledge\n    \u2022	Some references/allusions to other texts or ideas\n\nModerately Complex\n    \u2022	Requires common knowledge and some discipline-specific knowledge\n    \u2022	Few references/allusions\n\nSlightly Complex\n    \u2022	Requires everyday, practical knowledge\n    \u2022	No references/allusions\n\n3. Background knowledge:\nAt which grade level would student have enough background knowledge to understand the text?\n\n4. Use your judgement of the above three steps. First use the quantitative signal to get first signal of the appropriate grade level range, then use qualitative analysis to refine your decisions and consider if student at such grade will have enough background knowledge to arrive at a final grade level band. Also consider if the text can be for a lower grade with additional scaffolding.\n\n<begin of text to evaluate>\n<text>{text}</text>\n<end of text to evaluate>\n\nWhen providing your response, first think out loud of your reasoning and then provide your answer from one of the grade band options above. Your reasoning and answer needs to be in JSON format. Strictly follow the following format for your response.\n\nYour final answer should be in the "grade" property for the target grade band for the text aimed for independent reading.  If there is alternative appropriate grade students can read and comprehend with scaffold (eg. picture, graph, additional context, etc) or for read-aloud purposes for lower grade, provide it in the "alternative_grade" property and provide the types of scaffolding in the "scaffolding_needed" property.\n\nIn your reasoning, provide numbered bullet points for each of the analyses in each of the 3 steps. At the end, give me the 4th bullet point called "synthesis" to summarize your analysis from the above 3 steps that help you arrive at the final decision.\n\n{format_instructions}\n';
+
+// src/prompts/grade-level-appropriateness/index.ts
+function getSystemPrompt2() {
+  return system_default;
+}
+function getUserPrompt2(text) {
+  return user_default.replace("{text}", text).replace("{format_instructions}", "");
+}
+
+// src/evaluators/grade-level-appropriateness.ts
+var GradeLevelAppropriatenessEvaluator = class extends BaseEvaluator {
+  static metadata = {
+    id: "grade-level-appropriateness",
+    name: "Grade Level Appropriateness",
+    description: "Determines appropriate grade level for text with scaffolding recommendations",
+    supportedGrades: [],
+    // No grade parameter required - evaluates what grade the text is appropriate for
+    requiresGoogleKey: true,
+    requiresOpenAIKey: false
+  };
+  provider;
+  constructor(config) {
+    super(config);
+    this.provider = createProvider({
+      type: "google",
+      model: "gemini-2.5-pro",
+      apiKey: config.googleApiKey,
+      maxRetries: this.config.maxRetries
+    });
+  }
+  /**
+   * Evaluate grade level appropriateness for a given text
+   *
+   * @param text - The text to evaluate
+   * @returns Evaluation result with grade recommendations and scaffolding suggestions
+   * @throws {ValidationError} If text is empty or too short/long
+   * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+   */
+  async evaluate(text) {
+    this.logger.info("Starting grade level appropriateness evaluation", {
+      evaluator: "grade-level-appropriateness",
+      operation: "evaluate",
+      textLength: text.length
+    });
+    const startTime = Date.now();
+    try {
+      this.validateText(text);
+      this.logger.debug("Evaluating grade level appropriateness", {
+        evaluator: "grade-level-appropriateness",
+        operation: "grade_evaluation"
+      });
+      const userPrompt = getUserPrompt2(text);
+      const response = await this.provider.generateStructured({
+        messages: [
+          { role: "system", content: getSystemPrompt2() },
+          { role: "user", content: userPrompt }
+        ],
+        schema: GradeLevelAppropriatenessSchema,
+        temperature: 0.25
+      });
+      const latencyMs = Date.now() - startTime;
+      const tokenUsage = {
+        input_tokens: response.usage.inputTokens,
+        output_tokens: response.usage.outputTokens
+      };
+      const result = {
+        score: response.data.grade,
+        reasoning: response.data.reasoning,
+        metadata: {
+          model: "google:gemini-2.5-pro",
+          processingTimeMs: latencyMs
+        },
+        _internal: response.data
+      };
+      this.sendTelemetry({
+        status: "success",
+        latencyMs,
+        textLength: text.length,
+        provider: "google:gemini-2.5-pro",
+        tokenUsage,
+        // No metadata.stage_details for single-stage evaluator
+        inputText: text
+      }).catch(() => {
+      });
+      this.logger.info("Grade level appropriateness evaluation completed successfully", {
+        evaluator: "grade-level-appropriateness",
+        operation: "evaluate",
+        grade: result.score,
+        processingTimeMs: latencyMs
+      });
+      return result;
+    } catch (error) {
+      const latencyMs = Date.now() - startTime;
+      this.logger.error("Grade level appropriateness evaluation failed", {
+        evaluator: "grade-level-appropriateness",
+        operation: "evaluate",
+        error: error instanceof Error ? error : void 0,
+        processingTimeMs: latencyMs
+      });
+      this.sendTelemetry({
+        status: "error",
+        latencyMs,
+        textLength: text.length,
+        provider: "google:gemini-2.5-pro",
+        errorCode: error instanceof Error ? error.name : "UnknownError",
+        inputText: text
+      }).catch(() => {
+      });
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+      throw wrapProviderError(error, "Grade level appropriateness evaluation failed");
+    }
+  }
+};
+var SmkOutputSchema = z.object({
+  identified_topics: z.array(z.string()).describe("List of major subjects/concepts found in the text."),
+  curriculum_check: z.string().describe("Whether the topics are standard K-8 or specialized high school level."),
+  assumptions_and_scaffolding: z.string().describe("What the author assumes the reader knows vs. what is explained."),
+  friction_analysis: z.string().describe("Whether difficulty comes from vocabulary/structure or actual knowledge demands."),
+  complexity_score: TextComplexityLevel.describe("The subject matter knowledge complexity level of the text"),
+  reasoning: z.string().describe("A brief synthesis of why the text fits the chosen complexity level.")
+});
+
+// ../../evals/prompts/subject-matter-knowledge/system.txt
+var system_default2 = `
+To perform the task of evaluating text complexity based on Subject Matter Knowledge (SMK), strictly adhere to the following instructions.
+Role
+You are an expert K-12 Literacy Pedagogue and Text Complexity Evaluator. Your specific focus is analyzing Subject Matter Knowledge (SMK) demands according to the Common Core Qualitative Text Complexity Rubric.
+Objective
+Analyze a provided text relative to a target grade_level. You must determine the extent of background knowledge required to comprehend the text. You must distinguish between Common/Standard knowledge (generally lower/moderate complexity) and Specialized/Theoretical knowledge (generally higher complexity).
+Input Data
+text: The passage to analyze.
+grade_level: The target student grade (integer).
+fk_score: Flesch-Kincaid Grade Level. Note: Use this only as a loose proxy for sentence structure. Do not let a high FK score artificially inflate the Subject Matter Knowledge score if the concepts remain simple.
+
+1. The Rubric: Subject Matter Knowledge (SMK)
+1. Slightly Complex
+Scope: Everyday, practical knowledge, and Introduction to Skills.
+Concept Type: Concrete, directly observable, and familiar.
+Key Indicator: "How-to" texts involving familiar objects (e.g., drawing a cupboard, playing a game, family life). Even if specific terms (like "scale" or "measure") are used, if the application is on a common object, it remains Slightly Complex.
+2. Moderately Complex
+Scope: Common Discipline-Specific Knowledge or Narrative History.
+Definition: Topics widely introduced in K-8 curricula (Basic American History, Geography, Earth Science, Biology).
+Key Characteristic: The text bridges concrete descriptions with abstract themes (e.g., using farming to discuss justice), OR narrates historical events via sensory details.
+Spatial Reasoning: Texts requiring mental manipulation of maps/routes are generally Moderate, unless the object is a familiar household item (see Slightly Complex).
+3. Very Complex
+Scope: Specialized Discipline-Specific, Engineering Mechanics, or Political Theory.
+Definition: Topics characteristic of High School (9-12) curricula requiring abstract mental models.
+Key Characteristic: Requires understanding mechanisms (how physics works/propulsion), chemical composition, or undefined political stakes (specific treaties, alliances, or secularization without context).
+4. Exceedingly Complex
+Scope: Professional or Academic knowledge.
+
+2. The Expert Mental Model (Decision Logic)
+Use these refined rules to categorize cases.
+Rule A: The "Layers of Meaning" Check
+Concrete -> Abstract (Moderate): The text describes concrete things (farming) to argue an abstract point (justice, rights).
+Concrete -> Concrete (Slightly): The text describes concrete things (lines, paper) to achieve a concrete result (drawing a cupboard). Do not over-rank practical instructions.
+Rule B: The Science & Engineering Boundary
+Observational (Moderate): Habitats, Water Cycle, observable traits, simple definitions.
+Mechanistic/Theoretical (Very): Engineering mechanics (how propulsion works via reaction), Instrumentation (using a spectroscope), or Chemical/Atomic theory.
+Test: Does the text explain how a machine functions using physical principles? If yes, it is Very Complex.
+Rule C: The History/Social Studies Boundary
+General/Narrative (Moderate):
+Sensory: Battle descriptions focusing on sights/sounds (flashes, smoke).
+Standard Topics: Immigration, Slavery, Government, Geography. Lists of nationalities or religions are "Common Knowledge" for Grades 6-8.
+Political/Contextual (Very):
+Implicit Context: Texts assuming knowledge of specific political factions, treaties, or the causes of events without explanation (e.g., "The Allies," "The Front," "The secularization of the clergy").
+Test: If the reader must know why two groups are fighting or the specific political history of a revolution to understand the text, it is Very Complex.
+Rule D: The "Technical vs. Practical" Trap
+Scenario: A text teaches a technical skill (e.g., Technical Drawing/Technology) but applies it to a familiar object (a cupboard).
+Decision: Slightly Complex.
+Reasoning: Do not confuse "Technical Vocabulary" (scale, thick lines) with "Theoretical Complexity." If the underlying concept is familiar (furniture), the SMK load is low.
+
+3. Critical Calibration Examples
+Text: "Make a rough sketch... How many shelves should the cupboard have?" (Grade 2) -> Slightly Complex.
+Reasoning: (Rule D/Rule A) Although it mentions "scale" and "technology," the task is concrete and relies on everyday knowledge.
+Text: "Hydraulic propulsion works by sucking water at the bow and forcing it sternward." (Grade 10) -> Very Complex.
+Reasoning: (Rule B) Explains a mechanism using physics principles.
+Text: "The Allies fight the enemy's cavalry; we remember the hospitality to priests during the Revolution." (Grade 6) -> Very Complex.
+Reasoning: (Rule C) Assumes undefined knowledge of WWI alliances and the specific political history of the French Revolution.
+Text: "Immigrants from Poland, Italy, and Russia arrived. Most were Catholic or Orthodox." (Grade 7) -> Moderately Complex.
+Reasoning: (Rule C) Standard K-8 topic. Lists of nationalities are content vocabulary, not specialized theory.
+
+4. Output Format
+Return your analysis in a valid JSON object. Do not include markdown formatting.
+Keys:
+- identified_topics: List[str] identifying the core subjects.
+- curriculum_check: String explaining if the topics are "Standard/General" (typical for K-8) or "Specialized/High School" (typical for 9-12).
+- assumptions_and_scaffolding: String analyzing what the author assumes the reader knows vs what is explained.
+- friction_analysis: String discussing the gap between Concrete description and Abstract meaning.
+- complexity_score: String (One of: slightly_complex, moderately_complex, very_complex, exceedingly_complex).
+- reasoning: String synthesizing the decision.
+
+`;
+
+// ../../evals/prompts/subject-matter-knowledge/user.txt
+var user_default2 = "Analyze:\nText: {text}\nGrade: {grade}\nFK Score: {fk_score}";
+
+// src/prompts/subject-matter-knowledge/index.ts
+function getSystemPrompt3() {
+  return system_default2;
+}
+function getUserPrompt3(text, grade, fkScore) {
+  return user_default2.replaceAll("{text}", text).replaceAll("{grade}", grade).replaceAll("{fk_score}", fkScore.toString());
+}
+
+// src/evaluators/smk.ts
+var SmkEvaluator = class _SmkEvaluator extends BaseEvaluator {
+  static metadata = {
+    id: "subject-matter-knowledge",
+    name: "Subject Matter Knowledge",
+    description: "Evaluates background knowledge demands of educational texts relative to grade level",
+    supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
+    requiresGoogleKey: true,
+    requiresOpenAIKey: false
+  };
+  provider;
+  constructor(config) {
+    super(config);
+    this.provider = createProvider({
+      type: "google",
+      model: "gemini-3-flash-preview",
+      apiKey: config.googleApiKey,
+      maxRetries: this.config.maxRetries
+    });
+  }
+  /**
+   * Evaluate subject matter knowledge complexity for a given text and grade level
+   *
+   * @param text - The text to evaluate
+   * @param grade - The target grade level (3-12)
+   * @returns Evaluation result with complexity score and detailed analysis
+   * @throws {ValidationError} If text is empty, too short/long, or grade is invalid
+   * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+   */
+  async evaluate(text, grade) {
+    this.logger.info("Starting SMK evaluation", {
+      evaluator: "subject-matter-knowledge",
+      operation: "evaluate",
+      grade,
+      textLength: text.length
+    });
+    const startTime = Date.now();
+    const stageDetails = [];
+    try {
+      this.validateText(text);
+      this.validateGrade(grade, new Set(_SmkEvaluator.metadata.supportedGrades));
+      this.logger.debug("Evaluating subject matter knowledge complexity", {
+        evaluator: "subject-matter-knowledge",
+        operation: "smk_evaluation"
+      });
+      const fkScore = calculateFleschKincaidGrade(text);
+      const response = await this.evaluateSmk(text, grade, fkScore);
+      stageDetails.push({
+        stage: "smk_evaluation",
+        provider: "google:gemini-3-flash-preview",
+        latency_ms: response.latencyMs,
+        token_usage: {
+          input_tokens: response.usage.inputTokens,
+          output_tokens: response.usage.outputTokens
+        }
+      });
+      const latencyMs = Date.now() - startTime;
+      const totalTokenUsage = {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      };
+      const result = {
+        score: response.data.complexity_score,
+        reasoning: response.data.reasoning,
+        metadata: {
+          model: "google:gemini-3-flash-preview",
+          processingTimeMs: latencyMs
+        },
+        _internal: response.data
+      };
+      this.sendTelemetry({
+        status: "success",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: "google:gemini-3-flash-preview",
+        tokenUsage: totalTokenUsage,
+        metadata: {
+          stage_details: stageDetails
+        },
+        inputText: text
+      }).catch(() => {
+      });
+      this.logger.info("SMK evaluation completed successfully", {
+        evaluator: "subject-matter-knowledge",
+        operation: "evaluate",
+        grade,
+        score: result.score,
+        processingTimeMs: latencyMs
+      });
+      return result;
+    } catch (error) {
+      const latencyMs = Date.now() - startTime;
+      this.logger.error("SMK evaluation failed", {
+        evaluator: "subject-matter-knowledge",
+        operation: "evaluate",
+        grade,
+        error: error instanceof Error ? error : void 0,
+        processingTimeMs: latencyMs,
+        completedStages: stageDetails.length
+      });
+      const totalTokenUsage = stageDetails.length > 0 ? {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      } : void 0;
+      this.sendTelemetry({
+        status: "error",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: "google:gemini-3-flash-preview",
+        tokenUsage: totalTokenUsage,
+        errorCode: error instanceof Error ? error.name : "UnknownError",
+        metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
+        inputText: text
+      }).catch(() => {
+      });
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+      throw wrapProviderError(error, "SMK evaluation failed");
+    }
+  }
+  /**
+   * Run the SMK evaluation LLM call
+   */
+  async evaluateSmk(text, grade, fkScore) {
+    const response = await this.provider.generateStructured({
+      messages: [
+        { role: "system", content: getSystemPrompt3() },
+        { role: "user", content: getUserPrompt3(text, grade, fkScore) }
+      ],
+      schema: SmkOutputSchema,
+      temperature: 0
+    });
+    return {
+      data: response.data,
+      usage: response.usage,
+      latencyMs: response.latencyMs
+    };
+  }
+};
+var ConventionalityOutputSchema = z.object({
+  conventionality_features: z.array(z.string()).describe("The specific language features driving the complexity (e.g., literal narrative, concrete actions, sustained irony, abstract qualities) with direct quotes from the text."),
+  grade_context: z.string().describe("How the conventionality demands compare to general expectations for the provided target grade."),
+  instructional_insights: z.string().describe("Actionable pedagogical suggestions for scaffolding the conventionality features in the classroom."),
+  complexity_score: TextComplexityLevel.describe("The conventionality complexity level of the text"),
+  reasoning: z.string().describe("A detailed explanation of the rating, citing specific features in the text and referencing the expert guardrails.")
+});
+
+// ../../evals/prompts/conventionality/system.txt
+var system_default3 = `Role
+You are an expert reading teacher and text complexity evaluator. Your task is to evaluate the "Conventionality" of a text and assign it a complexity level based on a 4-point scale, carefully factoring in the target grade level.
+
+Objective
+Measure how explicit, literal, and straightforward the text's meaning is, versus how abstract, ironic, figurative, or archaic it is. Focus on the hiddenness of the meaning, the use of conceptual framing, the reliance on abstract reasoning, and the familiarity of the expression for the target grade.
+
+Complexity Levels
+- Slightly Complex: Explicit, literal, straightforward, easy to understand. Meaning is entirely on the surface. The language is concrete, and the meaning is clear and procedural, mostly referring to observable materials and actions. Contains no symbolic or ironic language, and conceptual interpretation is not required. Contains limited figurative language that is common and easy to comprehend at the target grade level.
+- Moderately Complex: Largely explicit and easy to understand with some occasions for more complex meaning. May contain a noticeable amount of archaic/dated phrasing, formal historical prose, vocabulary demands, background knowledge requirements, or expressions that are less familiar to the target grade level, which might make the text feel vague or slightly challenging.
+- Very Complex: Fairly complex; contains sustained abstract language, conceptual framing, rhetorical idealization, ironic comparisons, or central metaphors that drive the meaning of the text. Addresses concepts, beliefs, and abstract qualities rather than just concrete objects. The tone or underlying message requires interpretation, even if the surface message is clear.
+- Exceedingly Complex: Dense and complex; contains considerable abstract, ironic, and/or figurative language. Meaning is heavily hidden, deeply conceptual, or relies heavily on complex rhetorical devices.
+
+Essential Evaluation Rules
+1. Concrete & Procedural Texts: Texts that are highly concrete, clear, and procedural (e.g., describing observable materials, mechanical processes, or physical actions) should typically be rated "Slightly Complex."
+
+2. Grade-Level Anchoring and Vague Narratives: Always consider the target grade. A literal historical narrative that might be straightforward for older students can be "Moderately Complex" for younger students (e.g., 4th graders) if it involves less familiar expressions, older contexts (e.g., wagon loads, traveling by horseback), vocabulary demands, and background knowledge requirements that make the text feel vague or slightly demanding for that age group.
+
+3. Rhetorical Idealization and Abstract Qualities: If an entire argument or narrative is built around abstract qualities (e.g., national character, bravery, liberty) and uses repeated figurative language or personification to portray a subject in a certain idealized way, rate the text as "Very Complex." Even if the figurative language is easy to interpret, the need to interpret the rhetorical tone and sustained abstract focus elevates the complexity beyond level two.
+
+4. Common Idioms and Grade-Level Appropriateness: Do NOT elevate a text to "Moderately Complex" simply because it contains a few common idiomatic expressions. If these expressions are widely known and easy for the target grade to understand without making the text feel vague, the text remains "Slightly Complex."
+
+5. Conversational and Hypothetical Framing: Using a second-person conversational hook (e.g., "Imagine you are...") to explain a concept is a standard, literal device for engaging readers. It does not constitute complex conceptual framing.
+
+6. Sustained vs. Occasional Impact: If abstract language, figurative phrasing, irony, or conceptual framing is sustained throughout the text and central to the argument/meaning, the text is Very Complex. Reserve Moderately Complex for texts where the explicit meaning dominates but the expression, vocabulary, or archaic language provides a moderate conventionality challenge.
+
+7. Central Metaphors and Conceptual Framing: When an author uses a central metaphor to explain a concept or uses figurative phrasing to explain how things "work," this abstract reasoning drives the meaning, elevating the text to Very Complex.
+
+8. Irony and Abstract Comparisons: Texts that rely on sustained irony, especially through comparative arguments, are inherently Very Complex for younger students.
+
+9. Isolate Conventionality from Vocabulary: Do not inflate the Conventionality score just because the text uses archaic, dated, or highly academic vocabulary. 
+
+Input Format
+You will receive:
+- text: The passage to evaluate.
+- grade_level: The target student grade level.
+- fk_score: The Flesch-Kincaid readability score.
+
+Output Format
+Provide a JSON object containing ONLY the following keys:
+- complexity_score: (String) One of the 4 scale levels exactly as formatted: 'slightly_complex', 'moderately_complex', 'very_complex', or 'exceedingly_complex'.
+- reasoning: (String) A detailed explanation of the rating, citing specific features in the text and referencing the expert guardrails (e.g., noting if the text relies on abstract qualities/rhetorical idealization, if vocabulary/background knowledge demands make a literal text vague for the grade level, or if it is strictly concrete/procedural).
+- conventionality_features: (List of Strings) The specific language features driving the complexity (e.g., literal narrative, concrete actions, less familiar expressions, sustained irony, abstract qualities, rhetorical idealization, archaic phrasing) with direct quotes from the text.
+- grade_context: (String) How the conventionality demands compare to general expectations for the provided target grade.
+- instructional_insights: (String) Actionable pedagogical suggestions for scaffolding the conventionality features in the classroom.`;
+
+// ../../evals/prompts/conventionality/user.txt
+var user_default3 = "Analyze:\nText: {text}\nGrade: {grade}\nFK Score: {fk_score}";
+
+// src/prompts/conventionality/index.ts
+function getSystemPrompt4() {
+  return system_default3;
+}
+function getUserPrompt4(text, grade, fkScore) {
+  return user_default3.replaceAll("{text}", text).replaceAll("{grade}", grade).replaceAll("{fk_score}", fkScore.toString());
+}
+
+// src/evaluators/conventionality.ts
+var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvaluator {
+  static metadata = {
+    id: "conventionality",
+    name: "Conventionality",
+    description: "Evaluates how explicit, literal, and straightforward a text's meaning is relative to grade level",
+    supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
+    requiresGoogleKey: true,
+    requiresOpenAIKey: false
+  };
+  provider;
+  constructor(config) {
+    super(config);
+    this.provider = createProvider({
+      type: "google",
+      model: "gemini-3-flash-preview",
+      apiKey: config.googleApiKey,
+      maxRetries: this.config.maxRetries
+    });
+  }
+  /**
+   * Evaluate conventionality complexity for a given text and grade level
+   *
+   * @param text - The text to evaluate
+   * @param grade - The target grade level (3-12)
+   * @returns Evaluation result with complexity score and detailed analysis
+   * @throws {ValidationError} If text is empty, too short/long, or grade is invalid
+   * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+   */
+  async evaluate(text, grade) {
+    this.logger.info("Starting Conventionality evaluation", {
+      evaluator: "conventionality",
+      operation: "evaluate",
+      grade,
+      textLength: text.length
+    });
+    const startTime = Date.now();
+    const stageDetails = [];
+    try {
+      this.validateText(text);
+      this.validateGrade(grade, new Set(_ConventionalityEvaluator.metadata.supportedGrades));
+      this.logger.debug("Evaluating conventionality complexity", {
+        evaluator: "conventionality",
+        operation: "conventionality_evaluation"
+      });
+      const fkScore = calculateFleschKincaidGrade(text);
+      const response = await this.evaluateConventionality(text, grade, fkScore);
+      stageDetails.push({
+        stage: "conventionality_evaluation",
+        provider: "google:gemini-3-flash-preview",
+        latency_ms: response.latencyMs,
+        token_usage: {
+          input_tokens: response.usage.inputTokens,
+          output_tokens: response.usage.outputTokens
+        }
+      });
+      const latencyMs = Date.now() - startTime;
+      const totalTokenUsage = {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      };
+      const result = {
+        score: response.data.complexity_score,
+        reasoning: response.data.reasoning,
+        metadata: {
+          model: "google:gemini-3-flash-preview",
+          processingTimeMs: latencyMs
+        },
+        _internal: response.data
+      };
+      this.sendTelemetry({
+        status: "success",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: "google:gemini-3-flash-preview",
+        tokenUsage: totalTokenUsage,
+        metadata: {
+          stage_details: stageDetails
+        },
+        inputText: text
+      }).catch(() => {
+      });
+      this.logger.info("Conventionality evaluation completed successfully", {
+        evaluator: "conventionality",
+        operation: "evaluate",
+        grade,
+        score: result.score,
+        processingTimeMs: latencyMs
+      });
+      return result;
+    } catch (error) {
+      const latencyMs = Date.now() - startTime;
+      this.logger.error("Conventionality evaluation failed", {
+        evaluator: "conventionality",
+        operation: "evaluate",
+        grade,
+        error: error instanceof Error ? error : void 0,
+        processingTimeMs: latencyMs,
+        completedStages: stageDetails.length
+      });
+      const totalTokenUsage = stageDetails.length > 0 ? {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      } : void 0;
+      this.sendTelemetry({
+        status: "error",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: "google:gemini-3-flash-preview",
+        tokenUsage: totalTokenUsage,
+        errorCode: error instanceof Error ? error.name : "UnknownError",
+        metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
+        inputText: text
+      }).catch(() => {
+      });
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+      throw wrapProviderError(error, "Conventionality evaluation failed");
+    }
+  }
+  /**
+   * Run the Conventionality evaluation LLM call
+   */
+  async evaluateConventionality(text, grade, fkScore) {
+    const response = await this.provider.generateStructured({
+      messages: [
+        { role: "system", content: getSystemPrompt4() },
+        { role: "user", content: getUserPrompt4(text, grade, fkScore) }
+      ],
+      schema: ConventionalityOutputSchema,
+      temperature: 0
+    });
+    return {
+      data: response.data,
+      usage: response.usage,
+      latencyMs: response.latencyMs
+    };
+  }
+};
+
+// src/batch/evaluator.ts
+var EVALUATOR_MAP = /* @__PURE__ */ new Map([
+  [GradeLevelAppropriatenessEvaluator.metadata.id, GradeLevelAppropriatenessEvaluator],
+  [SmkEvaluator.metadata.id, SmkEvaluator],
+  [VocabularyEvaluator.metadata.id, VocabularyEvaluator],
+  [SentenceStructureEvaluator.metadata.id, SentenceStructureEvaluator],
+  [ConventionalityEvaluator.metadata.id, ConventionalityEvaluator]
+]);
+var EVALUATOR_GROUPS = [
+  {
+    id: "text-complexity",
+    name: "Text Complexity Analysis",
+    description: "Evaluates vocabulary complexity, sentence structure, subject matter knowledge, conventionality, and grade-level appropriateness",
+    evaluatorIds: [
+      GradeLevelAppropriatenessEvaluator.metadata.id,
+      SmkEvaluator.metadata.id,
+      VocabularyEvaluator.metadata.id,
+      SentenceStructureEvaluator.metadata.id,
+      ConventionalityEvaluator.metadata.id
+    ],
+    requiresGoogleKey: true,
+    requiresOpenAIKey: true,
+    maxInputRows: 50
+  }
+];
+function getAvailableGroups() {
+  return [...EVALUATOR_GROUPS];
+}
+var BatchEvaluator = class {
+  config;
+  limit;
+  evaluatorInstances = /* @__PURE__ */ new Map();
+  isCancelled = false;
+  completedResults = [];
+  constructor(config) {
+    this.config = {
+      concurrency: 3,
+      maxRetries: 2,
+      telemetry: false,
+      ...config
+    };
+    this.limit = pLimit(this.config.concurrency);
+  }
+  /**
+   * Cancel ongoing evaluation.
+   * Returns partial results collected so far.
+   */
+  cancel() {
+    this.isCancelled = true;
+    return [...this.completedResults];
+  }
+  /**
+   * Initialize evaluator instances for the given IDs
+   */
+  initializeEvaluators(evaluatorIds) {
+    for (const id of evaluatorIds) {
+      if (this.evaluatorInstances.has(id)) continue;
+      const EvaluatorClass = EVALUATOR_MAP.get(id);
+      if (!EvaluatorClass) {
+        throw new Error(`Unknown evaluator: ${id}`);
+      }
+      const evaluator = new EvaluatorClass({
+        googleApiKey: this.config.googleApiKey,
+        openaiApiKey: this.config.openaiApiKey,
+        maxRetries: this.config.maxRetries,
+        telemetry: this.config.telemetry
+      });
+      this.evaluatorInstances.set(id, evaluator);
+    }
+  }
+  /**
+   * Create tasks from inputs and evaluator IDs
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  createTasks(inputs, evaluatorIds) {
+    const tasks = [];
+    for (const input of inputs) {
+      for (const evaluatorId of evaluatorIds) {
+        tasks.push({
+          text: input.text,
+          grade: input.grade,
+          evaluatorId,
+          rowIndex: input.rowIndex,
+          originalRow: input.originalRow
+        });
+      }
+    }
+    return tasks;
+  }
+  /**
+   * Execute a single evaluation task
+   */
+  async executeTask(task, onProgress) {
+    if (this.isCancelled) {
+      const batchResult = {
+        rowIndex: task.rowIndex,
+        text: task.text,
+        grade: task.grade,
+        evaluatorId: task.evaluatorId,
+        status: "error",
+        error: "Cancelled by user",
+        processingTimeMs: 0,
+        originalRow: task.originalRow
+      };
+      return batchResult;
+    }
+    const startTime = Date.now();
+    const evaluator = this.evaluatorInstances.get(task.evaluatorId);
+    if (!evaluator) {
+      const batchResult = {
+        rowIndex: task.rowIndex,
+        text: task.text,
+        grade: task.grade,
+        evaluatorId: task.evaluatorId,
+        status: "error",
+        error: `Evaluator not initialized: ${task.evaluatorId}`,
+        processingTimeMs: 0,
+        originalRow: task.originalRow
+      };
+      this.completedResults.push(batchResult);
+      if (onProgress) onProgress(batchResult);
+      return batchResult;
+    }
+    try {
+      const result = await evaluator.evaluate(task.text, task.grade);
+      const batchResult = {
+        rowIndex: task.rowIndex,
+        text: task.text,
+        grade: task.grade,
+        evaluatorId: task.evaluatorId,
+        status: "success",
+        score: result.score,
+        reasoning: result.reasoning,
+        processingTimeMs: Date.now() - startTime,
+        originalRow: task.originalRow
+      };
+      this.completedResults.push(batchResult);
+      if (onProgress) onProgress(batchResult);
+      return batchResult;
+    } catch (error) {
+      const batchResult = {
+        rowIndex: task.rowIndex,
+        text: task.text,
+        grade: task.grade,
+        evaluatorId: task.evaluatorId,
+        status: "error",
+        error: error instanceof Error ? error.message : String(error),
+        processingTimeMs: Date.now() - startTime,
+        originalRow: task.originalRow
+      };
+      this.completedResults.push(batchResult);
+      if (onProgress) onProgress(batchResult);
+      return batchResult;
+    }
+  }
+  /**
+   * Calculate summary statistics
+   */
+  calculateSummary(results, durationMs) {
+    const summary = {
+      totalTasks: results.length,
+      successful: results.filter((r) => r.status === "success").length,
+      failed: results.filter((r) => r.status === "error").length,
+      durationMs,
+      resultsPerEvaluator: {}
+    };
+    const evaluatorIds = Array.from(new Set(results.map((r) => r.evaluatorId)));
+    for (const id of evaluatorIds) {
+      const evalResults = results.filter((r) => r.evaluatorId === id);
+      summary.resultsPerEvaluator[id] = {
+        successful: evalResults.filter((r) => r.status === "success").length,
+        failed: evalResults.filter((r) => r.status === "error").length
+      };
+    }
+    return summary;
+  }
+  /**
+   * Run batch evaluation for an evaluator group.
+   *
+   * @param inputs - Array of input rows
+   * @param groupId - The evaluator group to run (see getAvailableGroups())
+   * @param onProgress - Optional callback invoked after each task completes
+   * @returns Batch evaluation results and summary
+   */
+  async evaluate(inputs, groupId, onProgress) {
+    const startTime = Date.now();
+    const group = EVALUATOR_GROUPS.find((g) => g.id === groupId);
+    if (!group) {
+      throw new Error(
+        `Unknown evaluator group: "${groupId}". Available: ${EVALUATOR_GROUPS.map((g) => g.id).join(", ")}`
+      );
+    }
+    if (inputs.length > group.maxInputRows) {
+      throw new Error(
+        `Input exceeds limit for "${group.id}": ${inputs.length} rows (max ${group.maxInputRows}). Split into smaller batches.`
+      );
+    }
+    this.isCancelled = false;
+    this.completedResults = [];
+    this.initializeEvaluators(group.evaluatorIds);
+    const tasks = this.createTasks(inputs, group.evaluatorIds);
+    const settledResults = await Promise.allSettled(
+      tasks.map((task) => this.limit(() => this.executeTask(task, onProgress)))
+    );
+    const results = settledResults.filter((r) => r.status === "fulfilled").map((r) => r.value);
+    const durationMs = Date.now() - startTime;
+    const summary = this.calculateSummary(results, durationMs);
+    return { results, summary };
+  }
+};
+function findColumn(row, columnName) {
+  const normalizedTarget = columnName.toLowerCase().trim();
+  for (const key of Object.keys(row)) {
+    if (key.toLowerCase().trim() === normalizedTarget) {
+      return key;
+    }
+  }
+  return void 0;
+}
+function parseCSV(csvPath) {
+  if (!fs2.existsSync(csvPath)) {
+    throw new Error(`CSV file not found: ${csvPath}`);
+  }
+  const records = parse(fs2.readFileSync(csvPath, "utf-8"), {
+    columns: true,
+    skip_empty_lines: true,
+    trim: true
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  });
+  if (records.length === 0) {
+    throw new Error("CSV file is empty");
+  }
+  const firstRow = records[0];
+  const textColumn = findColumn(firstRow, "text");
+  const gradeColumn = findColumn(firstRow, "grade");
+  if (!textColumn) {
+    throw new Error('CSV must have a "text" column (case-insensitive)');
+  }
+  if (!gradeColumn) {
+    throw new Error('CSV must have a "grade" column (case-insensitive)');
+  }
+  const inputs = [];
+  for (let i = 0; i < records.length; i++) {
+    const row = records[i];
+    const text = row[textColumn];
+    const grade = row[gradeColumn];
+    if (!text || !grade) {
+      console.warn(`Warning: skipping row ${i + 2} \u2014 missing text or grade`);
+      continue;
+    }
+    inputs.push({
+      text: String(text).trim(),
+      grade: String(grade).trim(),
+      rowIndex: i + 2,
+      // 1-based, offset by 1 for the header row
+      originalRow: row
+    });
+  }
+  return inputs;
+}
+
+// src/batch/report-template.html
+var report_template_default = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Evaluation Report</title>
+  <style>
+    :root {
+      --primary:          #242423;
+      --secondary:        #6B6A64;
+      --informational:    #125B3A;
+      --informational-bg: #E0F5EC;
+      --border:           #e2e8f0;
+      --neutral-bg:       #f1f5f9;
+      --neutral-muted:    #64748b;
+      --on-band:          #177A4D;
+      --within-reach:     #B79F15;
+      --off-target:       #C4352D;
+      --card-bg:          rgba(255,255,255,0.6);
+      --card-shadow:      0 4px 10px 0 rgba(36,36,35,0.1);
+      --radius:           8px;
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      background: #F4F6F8;
+      color: var(--primary);
+      font-size: 14px;
+      line-height: 1.5;
+    }
+
+    .container { max-width: 1200px; margin: 0 auto; padding: 32px 40px; }
+
+    /* \u2500\u2500 Header \u2500\u2500 */
+    header.report-header { margin-bottom: 24px; }
+    header.report-header h1 { font-size: 20px; font-weight: 600; margin: 0 0 4px 0; color: var(--primary); }
+    header.report-header .subtitle { font-size: 14px; color: var(--secondary); }
+
+    /* \u2500\u2500 Cards \u2500\u2500 */
+    .card { background: var(--card-bg); border-radius: var(--radius); box-shadow: var(--card-shadow); margin-bottom: 20px; overflow: hidden; }
+    .card-body { padding: 16px 20px; }
+    .card-label { font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; color: var(--secondary); margin-bottom: 16px; }
+    .card-label-sm { font-size: 11px; text-transform: uppercase; letter-spacing: 0.05em; color: var(--secondary); }
+
+    /* \u2500\u2500 Tabs \u2500\u2500 */
+    .tabs { display: flex; border-bottom: 1px solid var(--border); }
+    .tab-btn { padding: 12px 20px; font-size: 14px; font-weight: 500; background: none; border: none; border-bottom: 2px solid transparent; margin-bottom: -1px; cursor: pointer; color: var(--secondary); transition: color 0.15s, border-color 0.15s; }
+    .tab-btn:hover { color: var(--primary); }
+    .tab-btn.active { color: var(--primary); border-bottom-color: var(--on-band); }
+    .tab-panel { display: none; }
+    .tab-panel.active { display: block; }
+    .tab-content { padding: 20px 28px; }
+
+    /* \u2500\u2500 Layout grids \u2500\u2500 */
+    .grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin-bottom: 20px; }
+    .grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; margin-bottom: 20px; }
+    .grid-4 { display: grid; grid-template-columns: repeat(2, 1fr); gap: 20px 32px; }
+    .flex-col { display: flex; flex-direction: column; gap: 4px; }
+
+    /* \u2500\u2500 Tags \u2500\u2500 */
+    .tag { display: inline-block; padding: 4px 10px; border-radius: 6px; font-size: 12px; font-weight: 600; }
+    .tag-on-band      { background: var(--on-band);      color: #fff; }
+    .tag-within-reach { background: var(--within-reach);  color: #fff; }
+    .tag-off-target   { background: var(--off-target);    color: #fff; }
+    .tag-informational{ background: var(--neutral-bg); color: var(--neutral-muted); }
+
+    /* \u2500\u2500 GLA stat cards \u2500\u2500 */
+    .gla-card .top-stripe { height: 4px; }
+    .gla-card.on-band     .top-stripe  { background: var(--on-band); }
+    .gla-card.within-reach .top-stripe  { background: var(--within-reach); }
+    .gla-card.off-target  .top-stripe  { background: var(--off-target); }
+    .gla-card.on-band     .card-label-sm { color: var(--on-band); }
+    .gla-card.within-reach .card-label-sm { color: var(--within-reach); }
+    .gla-card.off-target  .card-label-sm { color: var(--off-target); }
+    .gla-card .big-num { font-size: 28px; font-weight: 700; margin: 6px 0; }
+    .gla-card.on-band     .big-num { color: var(--on-band); }
+    .gla-card.within-reach .big-num { color: var(--within-reach); }
+    .gla-card.off-target  .big-num { color: var(--off-target); }
+    .gla-card .desc { font-size: 13px; color: var(--secondary); }
+
+    /* \u2500\u2500 Complexity dimension summary bars \u2500\u2500 */
+    .cx-dim-track { height: 10px; background: var(--border); border-radius: 99px; overflow: hidden; }
+    .cx-dim-fill  { height: 100%; border-radius: 99px; background: var(--neutral-muted); transition: width 0.4s ease; }
+
+    /* \u2500\u2500 Insights \u2500\u2500 */
+    .number-icon { display: inline-flex; align-items: center; justify-content: center; width: 28px; height: 28px; border-radius: 50%; background: var(--primary); color: #fff; font-size: 14px; font-weight: 600; flex-shrink: 0; }
+    .insight-row { display: flex; align-items: flex-start; gap: 12px; margin-bottom: 10px; }
+    .insight-text { flex: 1; font-size: 14px; color: var(--primary); }
+    .disclaimer { font-size: 13px; color: var(--secondary); margin-top: 12px; }
+
+    /* \u2500\u2500 Grade level distribution (CSS bars) \u2500\u2500 */
+    .dist-chart { margin-top: 8px; }
+    .dist-row { display: flex; align-items: center; margin-bottom: 10px; }
+    .dist-row .band { width: 60px; font-size: 12px; font-weight: 600; color: var(--primary); flex-shrink: 0; }
+    .dist-row .bars { flex: 1; height: 24px; display: flex; }
+    .dist-row .bar-on  { background: var(--on-band); }
+    .dist-row .bar-wr  { background: var(--within-reach); }
+    .dist-row .bar-off { background: var(--off-target); }
+    .dist-row .bars > .bar-seg:first-child { border-radius: 4px 0 0 4px; }
+    .dist-row .bars > .bar-seg:last-child  { border-radius: 0 4px 4px 4px; }
+    .dist-row .bars > .bar-seg.bar-off:last-child { border-radius: 0 4px 4px 0; }
+    .dist-row .bars > .bar-seg.bar-off:only-child  { border-radius: 4px; }
+    .dist-row .bars > .bar-seg:only-child  { border-radius: 4px; }
+    .dist-legend { display: flex; justify-content: center; gap: 24px; margin-top: 16px; font-size: 12px; color: var(--primary); }
+    .dist-legend span { display: inline-flex; align-items: center; gap: 6px; }
+    .dist-legend .dot { width: 10px; height: 10px; border-radius: 2px; flex-shrink: 0; }
+
+    /* \u2500\u2500 Bar segment tooltips \u2500\u2500 */
+    .bar-seg { position: relative; cursor: default; }
+    .bar-seg::after {
+      content: attr(data-tip);
+      position: absolute;
+      bottom: calc(100% + 6px);
+      left: 50%;
+      transform: translateX(-50%);
+      background: var(--primary);
+      color: #fff;
+      padding: 5px 9px;
+      border-radius: 5px;
+      font-size: 12px;
+      white-space: nowrap;
+      pointer-events: none;
+      opacity: 0;
+      transition: opacity 0.12s;
+      z-index: 20;
+    }
+    .bar-seg::before {
+      content: '';
+      position: absolute;
+      bottom: calc(100% + 1px);
+      left: 50%;
+      transform: translateX(-50%);
+      border: 5px solid transparent;
+      border-top-color: var(--primary);
+      opacity: 0;
+      transition: opacity 0.12s;
+      pointer-events: none;
+      z-index: 20;
+    }
+    .bar-seg:hover::after,
+    .bar-seg:hover::before { opacity: 1; }
+
+    /* \u2500\u2500 Heatmap \u2500\u2500 */
+    .heatmap-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    .heatmap-table th { padding: 10px 16px; text-align: left; font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; color: var(--neutral-muted); border-bottom: 2px solid var(--border); }
+    .heatmap-table td { padding: 10px 16px; border-bottom: 1px solid var(--border); }
+    .heatmap-table td:first-child { font-weight: 600; color: var(--primary); }
+    .heatmap-table .cell-num { text-align: center; }
+    .heatmap-table tr:last-child td { border-bottom: none; }
+    .heatmap-cell { display: inline-block; padding: 5px 12px; border-radius: 6px; font-size: 13px; font-weight: 600; background: var(--neutral-bg); color: var(--neutral-muted); }
+
+    /* \u2500\u2500 Full results table \u2500\u2500 */
+    .results-scroll { overflow-x: auto; overflow-y: auto; max-height: 600px; }
+    table.data-table { width: 100%; border-collapse: collapse; font-size: 13px; min-width: 100%; white-space: nowrap; }
+    table.data-table th {
+      padding: 10px 16px; text-align: left; font-size: 12px; font-weight: 600;
+      color: var(--primary); background: var(--neutral-bg);
+      border-bottom: 2px solid var(--border);
+      position: sticky; top: 0; z-index: 3; white-space: nowrap;
+    }
+    table.data-table td {
+      padding: 10px 16px; border-bottom: 1px solid var(--border);
+      vertical-align: top; white-space: normal;
+      color: var(--primary);
+    }
+    table.data-table tr:last-child td { border-bottom: none; }
+    table.data-table tbody tr:hover td { background: rgba(0,0,0,0.02); }
+    table.data-table tbody tr:hover td.frozen { background: var(--neutral-bg); }
+    /* Frozen (sticky-left) columns */
+    table.data-table th.frozen,
+    table.data-table td.frozen { position: sticky; background: var(--neutral-bg); z-index: 2; }
+    table.data-table td.frozen { background: #fff; }
+    table.data-table th.frozen { z-index: 4; }
+    table.data-table th.frozen-last,
+    table.data-table td.frozen-last { border-right: 2px solid var(--border); }
+    table.data-table th.group-start,
+    table.data-table td.group-start { border-left: 2px solid var(--border); }
+    /* Text cell \u2014 3-line clamp, full text on hover */
+    table.data-table .cell-text { cursor: help; }
+    table.data-table .cell-text-inner {
+      display: -webkit-box;
+      -webkit-line-clamp: 3;
+      -webkit-box-orient: vertical;
+      overflow: hidden;
+      white-space: normal;
+    }
+    /* Reasoning cells \u2014 2-line clamp, full text on hover */
+    table.data-table .cell-reasoning { font-size: 12px; color: var(--secondary); cursor: help; }
+    table.data-table .cell-reasoning-inner {
+      display: -webkit-box;
+      -webkit-line-clamp: 2;
+      -webkit-box-orient: vertical;
+      overflow: hidden;
+      white-space: normal;
+    }
+
+    /* \u2500\u2500 Empty / no-data \u2500\u2500 */
+    .no-data { padding: 40px; text-align: center; color: var(--secondary); font-size: 15px; }
+  </style>
+</head>
+<body>
+
+  <div class="container">
+    <header class="report-header" id="app-header"></header>
+    <div class="card" style="margin-bottom:0; overflow:visible;">
+      <div class="tabs" id="tab-bar"></div>
+      <div id="tab-summary" class="tab-panel active"></div>
+      <div id="tab-results" class="tab-panel"></div>
+    </div>
+  </div>
+
+  <script>
+    // ---------------------------------------------------------------------------
+    // MOCK DATA \u2014 used when the template is opened directly in a browser so
+    // designers can see a realistic preview without running the CLI.
+    // This constant is never referenced when real data has been injected.
+    // ---------------------------------------------------------------------------
+    const MOCK_REPORT_DATA = {
+      meta: {
+        reportId: 'sample_content_batch_20260301T1430',
+        generatedAt: 'Mar 1, 2026 2:30 PM',
+        csvPath: '/Users/designer/Documents/interventionhelper_content_batch_03-01.csv',
+        evaluatorIds: ['grade-level-appropriateness', 'subject-matter-knowledge', 'vocabulary', 'sentence-structure', 'conventionality'],
+        evaluatorNames: ['Grade Level Appropriateness', 'Subject Matter Knowledge', 'Vocabulary', 'Sentence Structure', 'Conventionality'],
+        totalRows: 300,
+        processedRows: 287,
+        erroredRows: 13,
+      },
+      gradeLevelStats: {
+        onBand: 172, adjacent: 85, offTarget: 30,
+        onBandPct: 60, adjacentPct: 30, offTargetPct: 10,
+        hasData: true,
+      },
+      complexityStats: [
+        {
+          evaluatorId: 'subject-matter-knowledge', name: 'Subject Matter Knowledge',
+          average: 2.6, label: 'Moderately complex',
+          distribution: [28, 98, 110, 51],
+        },
+        {
+          evaluatorId: 'vocabulary', name: 'Vocabulary',
+          average: 2.4, label: 'Moderately complex',
+          distribution: [45, 120, 95, 27],
+        },
+        {
+          evaluatorId: 'sentence-structure', name: 'Sentence Structure',
+          average: 1.9, label: 'Slightly complex',
+          distribution: [88, 105, 72, 22],
+        },
+        {
+          evaluatorId: 'conventionality', name: 'Conventionality',
+          average: 1.7, label: 'Slightly complex',
+          distribution: [112, 118, 45, 12],
+        },
+      ],
+      gradeBandDistribution: {
+        bands: ['K-1', '2-3', '4-5', '6-8', '9-10', '11-CCR'],
+        data: [
+          { onBand: 0,  adjacent: 0,  offTarget: 0,  total: 0  },
+          { onBand: 32, adjacent: 18, offTarget: 5,  total: 55 },
+          { onBand: 58, adjacent: 22, offTarget: 8,  total: 88 },
+          { onBand: 48, adjacent: 25, offTarget: 10, total: 83 },
+          { onBand: 22, adjacent: 14, offTarget: 5,  total: 41 },
+          { onBand: 12, adjacent: 6,  offTarget: 2,  total: 20 },
+        ],
+      },
+      complexityHeatmap: {
+        bands: ['K-1', '2-3', '4-5', '6-8', '9-10', '11-CCR'],
+        evaluators: ['Subject Matter Knowledge', 'Vocabulary', 'Sentence Structure', 'Conventionality'],
+        evaluatorIds: ['subject-matter-knowledge', 'vocabulary', 'sentence-structure', 'conventionality'],
+        values: [
+          [null, null, null, null],
+          [1.8,  1.6,  1.4,  1.3 ],
+          [2.3,  2.1,  1.8,  1.7 ],
+          [2.7,  2.5,  2.2,  2.0 ],
+          [3.1,  2.9,  2.6,  2.4 ],
+          [3.4,  3.2,  2.8,  2.6 ],
+        ],
+      },
+      insights: [
+        'Review texts marked as Off Target \u2014 they may need content revision or grade-level adjustment before distribution.',
+        'Texts evaluated as Adjacent may benefit from light scaffolding strategies such as vocabulary pre-teaching.',
+        'Higher grade bands tend to show greater text complexity. Consider whether complexity aligns with instructional goals.',
+      ],
+      fullResults: {
+        originalColumns: ['row_id', 'text', 'grade', 'source'],
+        hasGLA: true,
+        complexityEvaluators: [
+          { evaluatorId: 'subject-matter-knowledge', name: 'Subject Matter Knowledge', prefix: 'subject_matter_knowledge' },
+          { evaluatorId: 'vocabulary',               name: 'Vocabulary',               prefix: 'vocabulary'               },
+          { evaluatorId: 'sentence-structure',       name: 'Sentence Structure',       prefix: 'sentence_structure'       },
+          { evaluatorId: 'conventionality',          name: 'Conventionality',          prefix: 'conventionality'          },
+        ],
+        rows: [
+          {
+            row_id: '1', grade: '5', source: 'science_unit_3',
+            text: 'The water cycle describes how water evaporates from surfaces, rises into the atmosphere, cools and condenses into clouds, and falls back to the ground as precipitation.',
+            __gla_status: 'On Band', __gla_band: '4-5',
+            __gla_reasoning: 'Uses grade-appropriate science vocabulary with a clear explanatory structure suitable for grades 4\u20135.',
+            __subject_matter_knowledge_score: 'Moderately complex',
+            __subject_matter_knowledge_reasoning: 'Requires familiarity with basic Earth science concepts; grade 5 students may need prior exposure to the water cycle.',
+            __vocabulary_score: 'Moderately complex',
+            __vocabulary_reasoning: 'Contains domain-specific terms (evaporates, condenses, precipitation) that require pre-teaching for grade 5 students.',
+            __sentence_structure_score: 'Slightly complex',
+            __sentence_structure_reasoning: 'Primarily compound sentences with clear connective structure appropriate for grade 5.',
+            __conventionality_score: 'Slightly complex',
+            __conventionality_reasoning: 'Language is largely literal and explicit; no figurative or idiomatic usage that would increase comprehension demand.',
+          },
+          {
+            row_id: '2', grade: '6', source: 'science_unit_1',
+            text: 'Photosynthesis is the process by which green plants use sunlight, water and carbon dioxide to produce food and oxygen.',
+            __gla_status: 'Adjacent', __gla_band: '4-5',
+            __gla_reasoning: 'Content is accessible but slightly below typical grade 6 complexity expectations.',
+            __subject_matter_knowledge_score: 'Slightly complex',
+            __subject_matter_knowledge_reasoning: 'Core concept of photosynthesis is introduced in upper elementary science; low prior knowledge demand for grade 6.',
+            __vocabulary_score: 'Moderately complex',
+            __vocabulary_reasoning: 'Key scientific terms are present but relatively straightforward for grade 6 readers.',
+            __sentence_structure_score: 'Slightly complex',
+            __sentence_structure_reasoning: 'Single main clause with a relative clause; well within grade 6 reading ability.',
+            __conventionality_score: 'Slightly complex',
+            __conventionality_reasoning: 'Entirely literal and direct; meaning is fully transparent with no figurative language.',
+          },
+          {
+            row_id: '3', grade: '8', source: 'biology_unit_2',
+            text: 'The mitochondria, often described as the powerhouse of the cell, are organelles found in the cytoplasm of eukaryotic cells, where they generate most of the adenosine triphosphate used for cellular energy.',
+            __gla_status: 'Off Target', __gla_band: '11-CCR',
+            __gla_reasoning: 'Text uses advanced biochemical terminology (adenosine triphosphate, eukaryotic) more appropriate for upper secondary or college-level readers.',
+            __subject_matter_knowledge_score: 'Very complex',
+            __subject_matter_knowledge_reasoning: 'Assumes familiarity with cell biology, organelle function, and biochemical energy systems well beyond typical grade 8 expectations.',
+            __vocabulary_score: 'Exceedingly complex',
+            __vocabulary_reasoning: 'High density of Tier 3 domain-specific words significantly exceeds typical grade 8 vocabulary expectations.',
+            __sentence_structure_score: 'Very complex',
+            __sentence_structure_reasoning: 'Long, embedded clauses with multiple modifying phrases create significant syntactic complexity for grade 8.',
+            __conventionality_score: 'Moderately complex',
+            __conventionality_reasoning: '"Powerhouse of the cell" is a well-known metaphor but requires understanding of the underlying analogy; otherwise literal.',
+          },
+          {
+            row_id: '4', grade: '3', source: 'science_unit_3',
+            text: 'Rain falls from clouds when tiny water droplets join together and become heavy enough to fall to the ground.',
+            __gla_status: 'On Band', __gla_band: '2-3',
+            __gla_reasoning: 'Simple vocabulary and sentence structure are appropriate for grades 2\u20133.',
+            __subject_matter_knowledge_score: 'Slightly complex',
+            __subject_matter_knowledge_reasoning: 'Everyday weather phenomenon; no specialized prior knowledge required for grade 3 students.',
+            __vocabulary_score: 'Slightly complex',
+            __vocabulary_reasoning: 'Common everyday vocabulary with no domain-specific terms requiring pre-teaching.',
+            __sentence_structure_score: 'Slightly complex',
+            __sentence_structure_reasoning: 'Short simple sentences with basic connective structure.',
+            __conventionality_score: 'Slightly complex',
+            __conventionality_reasoning: 'Entirely conventional and literal; straightforward causal explanation with no figurative language.',
+          },
+          {
+            row_id: '5', grade: '9', source: 'biology_unit_1',
+            text: 'Ecosystems are communities of organisms that interact with each other and their physical environment, shaped by both biotic and abiotic factors that influence population dynamics over time.',
+            __gla_status: 'On Band', __gla_band: '9-10',
+            __gla_reasoning: 'Appropriate complexity and terminology for a grade 9\u201310 biology curriculum.',
+            __subject_matter_knowledge_score: 'Very complex',
+            __subject_matter_knowledge_reasoning: 'Requires understanding of ecological concepts (biotic/abiotic factors, population dynamics) typical of secondary-level biology coursework.',
+            __vocabulary_score: 'Very complex',
+            __vocabulary_reasoning: 'Multiple Tier 3 terms (biotic, abiotic, population dynamics) require strong background knowledge.',
+            __sentence_structure_score: 'Moderately complex',
+            __sentence_structure_reasoning: 'Compound-complex sentence with a relative clause; manageable for grade 9 readers.',
+            __conventionality_score: 'Slightly complex',
+            __conventionality_reasoning: 'Technical but literal throughout; no irony or figurative usage that would obscure meaning.',
+          },
+          {
+            row_id: '6', grade: '4', source: 'social_studies_unit_2',
+            text: 'Ancient Egyptians built pyramids as tombs for their pharaohs and used a picture-based writing system called hieroglyphics.',
+            __gla_status: 'On Band', __gla_band: '4-5',
+            __gla_reasoning: 'Vocabulary and sentence length are well-matched to grade 4\u20135 social studies content.',
+            __subject_matter_knowledge_score: 'Moderately complex',
+            __subject_matter_knowledge_reasoning: 'Ancient Egypt is a common grade 4 social studies topic; some prior exposure to civilizations is expected.',
+            __vocabulary_score: 'Moderately complex',
+            __vocabulary_reasoning: 'Domain-specific proper nouns (pharaohs, hieroglyphics) may need brief glossing.',
+            __sentence_structure_score: 'Slightly complex',
+            __sentence_structure_reasoning: 'Two coordinated independent clauses; clear and accessible structure.',
+            __conventionality_score: 'Slightly complex',
+            __conventionality_reasoning: 'Descriptive and informational; meaning is explicit and no non-literal language is used.',
+          },
+          {
+            row_id: '7', grade: '11', source: 'lit_unit_4',
+            text: 'Shakespeare\\'s use of dramatic irony in Othello functions as a mechanism of tragic inevitability, positioning the audience as unwilling witnesses to the protagonist\\'s epistemological collapse.',
+            __gla_status: 'On Band', __gla_band: '11-CCR',
+            __gla_reasoning: 'Sophisticated literary analysis vocabulary and complex syntax are well-suited to grades 11\u2013CCR.',
+            __subject_matter_knowledge_score: 'Exceedingly complex',
+            __subject_matter_knowledge_reasoning: 'Requires familiarity with Shakespearean drama, literary theory, and epistemological concepts; assumes high prior exposure to canonical literature.',
+            __vocabulary_score: 'Exceedingly complex',
+            __vocabulary_reasoning: 'Tier 3 literary and philosophical vocabulary (epistemological, dramatic irony, tragic inevitability) demands high reading proficiency.',
+            __sentence_structure_score: 'Exceedingly complex',
+            __sentence_structure_reasoning: 'Noun phrase and participial phrase stacking creates a dense, highly embedded syntactic structure.',
+            __conventionality_score: 'Very complex',
+            __conventionality_reasoning: 'Analytical prose employs abstract and figurative constructs; "epistemological collapse" and "mechanism of tragic inevitability" are non-literal formulations requiring interpretive inference.',
+          },
+          {
+            row_id: '8', grade: '7', source: 'history_unit_1',
+            text: 'The Industrial Revolution transformed European societies by shifting labor from farms to factories, driving rapid urban growth and fundamentally changing how goods were produced and traded.',
+            __gla_status: 'Adjacent', __gla_band: '9-10',
+            __gla_reasoning: 'Vocabulary and conceptual density exceed typical grade 7 expectations; better suited for grades 9\u201310.',
+            __subject_matter_knowledge_score: 'Moderately complex',
+            __subject_matter_knowledge_reasoning: 'Industrial Revolution is introduced in middle school; grade 7 students likely have foundational context, though economic concepts add demand.',
+            __vocabulary_score: 'Very complex',
+            __vocabulary_reasoning: 'Abstract economic and historical vocabulary (urban growth, fundamentally) adds significant reading demand.',
+            __sentence_structure_score: 'Moderately complex',
+            __sentence_structure_reasoning: 'Participial phrases and coordinated verb phrases add structural complexity but remain readable.',
+            __conventionality_score: 'Slightly complex',
+            __conventionality_reasoning: 'Primarily literal and informational; "transformed" is used in its conventional sense with no figurative layering.',
+          },
+        ],
+      },
+    };
+
+    // ---------------------------------------------------------------------------
+    // DATA \u2014 this line is replaced by the formatter at report generation time.
+    // When opening the template directly in a browser, MOCK_REPORT_DATA is used.
+    // ---------------------------------------------------------------------------
+    var REPORT_DATA = null; // __REPLACED_BY_FORMATTER__
+    REPORT_DATA = REPORT_DATA || MOCK_REPORT_DATA;
+
+    // ---------------------------------------------------------------------------
+    // Canonical evaluator order
+    // ---------------------------------------------------------------------------
+
+    const EVALUATOR_ORDER = [
+      'grade-level-appropriateness',
+      'subject-matter-knowledge',
+      'vocabulary',
+      'sentence-structure',
+      'conventionality',
+    ];
+
+    function evalSortIndex(id) {
+      const i = EVALUATOR_ORDER.indexOf(id);
+      return i === -1 ? 999 : i;
+    }
+
+    // Sort meta.evaluatorIds / evaluatorNames in tandem
+    const _metaPairs = REPORT_DATA.meta.evaluatorIds
+      .map((id, i) => ({ id, name: REPORT_DATA.meta.evaluatorNames[i] }))
+      .sort((a, b) => evalSortIndex(a.id) - evalSortIndex(b.id));
+    REPORT_DATA.meta.evaluatorIds   = _metaPairs.map(x => x.id);
+    REPORT_DATA.meta.evaluatorNames = _metaPairs.map(x => x.name);
+
+    // Sort complexityStats
+    REPORT_DATA.complexityStats = [...REPORT_DATA.complexityStats]
+      .sort((a, b) => evalSortIndex(a.evaluatorId) - evalSortIndex(b.evaluatorId));
+
+    // Sort complexityHeatmap evaluators and their value columns
+    const _hmPairs = REPORT_DATA.complexityHeatmap.evaluators
+      .map((name, i) => ({ name, id: REPORT_DATA.complexityHeatmap.evaluatorIds[i], i }))
+      .sort((a, b) => evalSortIndex(a.id) - evalSortIndex(b.id));
+    REPORT_DATA.complexityHeatmap.evaluators   = _hmPairs.map(x => x.name);
+    REPORT_DATA.complexityHeatmap.evaluatorIds = _hmPairs.map(x => x.id);
+    REPORT_DATA.complexityHeatmap.values = REPORT_DATA.complexityHeatmap.values
+      .map(row => _hmPairs.map(x => row[x.i]));
+
+    // Sort fullResults.complexityEvaluators
+    REPORT_DATA.fullResults.complexityEvaluators = [...REPORT_DATA.fullResults.complexityEvaluators]
+      .sort((a, b) => evalSortIndex(a.evaluatorId) - evalSortIndex(b.evaluatorId));
+
+    // ---------------------------------------------------------------------------
+    // Utilities
+    // ---------------------------------------------------------------------------
+
+    function esc(str) {
+      return String(str ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+    }
+
+    function statusBadge(status) {
+      const cls = {
+        'On Band':   'tag-on-band',
+        'Adjacent':  'tag-within-reach',
+        'Off Target':'tag-off-target',
+      }[status] || '';
+      const display = status === 'Adjacent' ? 'Within Reach' : status;
+      return \`<span class="tag \${cls}">\${esc(display)}</span>\`;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Tab switching
+    // ---------------------------------------------------------------------------
+
+    function switchTab(tab) {
+      document.querySelectorAll('.tab-btn').forEach(b =>
+        b.classList.toggle('active', b.dataset.tab === tab)
+      );
+      document.getElementById('tab-summary').classList.toggle('active', tab === 'summary');
+      document.getElementById('tab-results').classList.toggle('active', tab === 'results');
+    }
+
+    // ---------------------------------------------------------------------------
+    // Header
+    // ---------------------------------------------------------------------------
+
+    function renderHeader() {
+      const { meta } = REPORT_DATA;
+      document.getElementById('app-header').innerHTML = \`
+        <h1>Evaluation Report</h1>
+        <p class="subtitle">Generated: \${esc(meta.generatedAt)} &bull; Report ID: \${esc(meta.reportId)}</p>
+      \`;
+      document.title = \`Report: \${meta.reportId}\`;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Tab bar
+    // ---------------------------------------------------------------------------
+
+    function renderTabs() {
+      document.getElementById('tab-bar').innerHTML = \`
+        <button class="tab-btn active" data-tab="summary" onclick="switchTab('summary')">Summary</button>
+        <button class="tab-btn" data-tab="results" onclick="switchTab('results')">Full Results</button>
+      \`;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Summary tab
+    // ---------------------------------------------------------------------------
+
+    function renderSummary() {
+      const { meta, gradeLevelStats: gls, complexityStats, insights,
+              gradeBandDistribution, complexityHeatmap } = REPORT_DATA;
+
+      // \u2500\u2500 Snapshot \u2500\u2500
+      const snapshotHtml = \`
+        <div class="card">
+          <div class="card-body">
+            <div class="card-label">Snapshot</div>
+            <div style="display:flex; flex-direction:column; gap:14px;">
+              <div class="flex-col">
+                <span class="card-label-sm">Evaluators</span>
+                <div style="margin-top:6px; display:flex; flex-wrap:wrap; gap:6px;">
+                  \${meta.evaluatorNames.map(n => \`<span class="tag tag-informational">\${esc(n)}</span>\`).join('')}
+                </div>
+              </div>
+              <div style="display:grid; grid-template-columns:1fr 1fr 3fr; gap:12px 32px;">
+                <div class="flex-col">
+                  <span class="card-label-sm">Rows Processed</span>
+                  <span style="font-weight:500; margin-top:4px;">\${meta.processedRows} of \${meta.totalRows}</span>
+                </div>
+                <div class="flex-col">
+                  <span class="card-label-sm">Errors / Skipped</span>
+                  <span style="font-weight:500; margin-top:4px;">\${meta.erroredRows}</span>
+                </div>
+                <div class="flex-col">
+                  <span class="card-label-sm">Source File</span>
+                  <span style="font-size:12px; font-family:monospace; word-break:break-all; color:var(--secondary); margin-top:4px;" title="\${esc(meta.csvPath)}">\${esc(meta.csvPath)}</span>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      \`;
+
+      // \u2500\u2500 GLA stat cards \u2500\u2500
+      const glsHtml = gls.hasData ? \`
+        <div class="grid-3">
+          <div class="card gla-card on-band" style="margin-bottom:0;">
+            <div class="top-stripe"></div>
+            <div class="card-body">
+              <div class="card-label-sm">On Band</div>
+              <div class="big-num">\${gls.onBandPct}%</div>
+              <div class="desc">\${gls.onBand} of \${meta.processedRows} rows where the evaluated grade band matches intended</div>
+            </div>
+          </div>
+          <div class="card gla-card within-reach" style="margin-bottom:0;">
+            <div class="top-stripe"></div>
+            <div class="card-body">
+              <div class="card-label-sm">Within Reach</div>
+              <div class="big-num">\${gls.adjacentPct}%</div>
+              <div class="desc">\${gls.adjacent} rows where the alternative grade band aligns with intended</div>
+            </div>
+          </div>
+          <div class="card gla-card off-target" style="margin-bottom:0;">
+            <div class="top-stripe"></div>
+            <div class="card-body">
+              <div class="card-label-sm">Off Target</div>
+              <div class="big-num">\${gls.offTargetPct}%</div>
+              <div class="desc">\${gls.offTarget} rows where neither evaluated nor alternative matches intended</div>
+            </div>
+          </div>
+        </div>
+      \` : '';
+
+      // \u2500\u2500 Complexity dimension summary card \u2500\u2500
+      const cxHtml = complexityStats.length > 0 ? (() => {
+        const totalRows = meta.processedRows || meta.totalRows;
+        const items = complexityStats.map(cs => {
+          const pct = Math.round((cs.average / 4.0) * 100);
+          const labelText = cs.average > 0
+            ? \`\${esc(cs.label)} (\${cs.average.toFixed(1)} / 4.0)\`
+            : '\u2014';
+          return \`
+            <div style="display:flex; flex-direction:column; gap:8px;">
+              <span style="font-size:13px; font-weight:500; color:var(--primary);">\${esc(cs.name)}</span>
+              <div class="cx-dim-track"><div class="cx-dim-fill" style="width:\${pct}%"></div></div>
+              <span style="font-size:12px; color:var(--secondary);">\${labelText}</span>
+            </div>
+          \`;
+        }).join('');
+        return \`
+          <div class="card">
+            <div class="card-body">
+              <div class="card-label">Text Complexity Dimensions (avg. across \${totalRows} rows)</div>
+              <div style="display:grid; grid-template-columns:repeat(3,1fr); gap:16px 24px;">
+                \${items}
+              </div>
+            </div>
+          </div>
+        \`;
+      })() : '';
+
+      // \u2500\u2500 Insights \u2500\u2500
+      const insightsHtml = \`
+        <div class="card" style="display: none;">
+          <div class="card-body">
+            <div class="card-label" style="display:flex; align-items:center; gap:8px;">
+              Insights
+              <span class="tag tag-informational" style="font-size:10px; letter-spacing:0.06em; padding:2px 8px;">Early Access</span>
+            </div>
+            <div style="display:flex; flex-direction:column; gap:10px;">
+              \${insights.map((text, idx) => \`
+                <div class="insight-row">
+                  <span class="number-icon" aria-label="Insight \${idx + 1}">\${idx + 1}</span>
+                  <span class="insight-text">\${esc(text)}</span>
+                </div>
+              \`).join('')}
+            </div>
+            <p class="disclaimer">These insights are automatically generated and may not reflect the full context of your data.</p>
+          </div>
+        </div>
+      \`;
+
+      // \u2500\u2500 Grade level distribution (CSS stacked bars) \u2500\u2500
+      const distHtml = (() => {
+        const toPct = (n, total) => total > 0 ? Math.round((n / total) * 100) : 0;
+        const activeBands = gradeBandDistribution.bands.filter((_, i) => gradeBandDistribution.data[i].total > 0);
+        const activeData  = gradeBandDistribution.data.filter(d => d.total > 0);
+        if (activeBands.length === 0) return '';
+
+        const rows = activeBands.map((band, i) => {
+          const d = activeData[i];
+          const onPct  = toPct(d.onBand,   d.total);
+          const adjPct = toPct(d.adjacent,  d.total);
+          const offPct = toPct(d.offTarget, d.total);
+          const onSeg  = d.onBand   > 0 ? \`<div class="bar-seg bar-on"  style="width:\${onPct}%"  data-tip="On Band: \${d.onBand} (\${onPct}%)"></div>\`  : '';
+          const adjSeg = d.adjacent  > 0 ? \`<div class="bar-seg bar-wr" style="width:\${adjPct}%" data-tip="Within Reach: \${d.adjacent} (\${adjPct}%)"></div>\` : '';
+          const offSeg = d.offTarget > 0 ? \`<div class="bar-seg bar-off" style="width:\${offPct}%" data-tip="Off Target: \${d.offTarget} (\${offPct}%)"></div>\` : '';
+          return \`
+            <div class="dist-row">
+              <span class="band">\${esc(band)}</span>
+              <div class="bars">\${onSeg}\${adjSeg}\${offSeg}</div>
+            </div>
+          \`;
+        }).join('');
+
+        return \`
+          <div class="card">
+            <div class="card-body">
+              <div class="card-label">Grade Band Alignment by Intended Grade</div>
+              <div class="dist-chart">\${rows}</div>
+              <div class="dist-legend">
+                <span><span class="dot" style="background:var(--on-band)"></span>On Band</span>
+                <span><span class="dot" style="background:var(--within-reach)"></span>Within Reach</span>
+                <span><span class="dot" style="background:var(--off-target)"></span>Off Target</span>
+              </div>
+            </div>
+          </div>
+        \`;
+      })();
+
+      // \u2500\u2500 Heatmap \u2500\u2500
+      const heatmapHtml = complexityStats.length > 0 && complexityHeatmap.evaluators.length > 0 ? \`
+        <div class="card">
+          <div class="card-body">
+            <div class="card-label">Text Complexity Dimensions by Intended Grade</div>
+            <div style="overflow-x:auto;">
+              <table class="heatmap-table">
+                <thead>
+                  <tr>
+                    <th>Dimension</th>
+                    \${complexityHeatmap.bands.map(b => \`<th style="text-align:center; padding:8px 10px; white-space:nowrap; min-width:56px;">\${esc(b)}</th>\`).join('')}
+                  </tr>
+                </thead>
+                <tbody>
+                  \${complexityHeatmap.evaluators.map((evaluator, ei) => \`
+                    <tr>
+                      <td>\${esc(evaluator)}</td>
+                      \${complexityHeatmap.bands.map((band, bi) => {
+                        const val = complexityHeatmap.values[bi][ei];
+                        const label = val !== null ? val.toFixed(1) : '\u2014';
+                        return \`<td class="cell-num" style="padding:8px 10px;"><span class="heatmap-cell" style="padding:4px 8px;">\${label}</span></td>\`;
+                      }).join('')}
+                    </tr>
+                  \`).join('')}
+                </tbody>
+              </table>
+            </div>
+          </div>
+        </div>
+      \` : '';
+
+      document.getElementById('tab-summary').innerHTML = \`
+        <div class="tab-content">
+          \${snapshotHtml}\${glsHtml}\${cxHtml}\${insightsHtml}\${distHtml}\${heatmapHtml}
+        </div>
+      \`;
+    }
+
+    // ---------------------------------------------------------------------------
+    // Full Results tab
+    // ---------------------------------------------------------------------------
+
+    function renderResults() {
+      const { fullResults } = REPORT_DATA;
+      const { originalColumns, hasGLA, complexityEvaluators, rows } = fullResults;
+
+      const KEPT_COLS = ['row_id', 'text', 'grade'];
+      const visibleColumns = originalColumns.filter(col => KEPT_COLS.includes(col.toLowerCase()));
+      const frozenCount = 1; // only Row # is sticky
+
+      function colLabel(col) {
+        const c = col.toLowerCase();
+        if (c === 'row_id') return 'Row #';
+        if (c === 'text')   return 'Text';
+        if (c === 'grade')  return 'Grade';
+        return col;
+      }
+      function colWidth(col) {
+        const c = col.toLowerCase();
+        if (c === 'row_id') return 60;
+        if (c === 'text')   return 340;
+        if (c === 'grade')  return 70;
+        return 160;
+      }
+
+      const thOriginal = visibleColumns.map((col, i) => {
+        const isFrozen = i === 0;
+        return \`<th class="\${isFrozen ? 'frozen frozen-last' : ''}" \${isFrozen ? 'data-frozen="0" style="min-width:' + colWidth(col) + 'px; left:0; z-index:4;"' : 'style="min-width:' + colWidth(col) + 'px;"'}>\${colLabel(col)}</th>\`;
+      }).join('');
+
+      const thGLA = hasGLA ? \`
+        <th class="group-start" style="min-width:120px">Grade Level Status</th>
+        <th style="min-width:110px">GLA Grade Band</th>
+        <th style="min-width:260px">GLA Reasoning</th>
+      \` : '';
+
+      const thCX = complexityEvaluators.map(e => \`
+        <th class="group-start" style="min-width:150px">\${esc(e.name)} Score</th>
+        <th style="min-width:260px">\${esc(e.name)} Reasoning</th>
+      \`).join('');
+
+      const bodyRows = rows.map(row => {
+        const tdOriginal = visibleColumns.map((col, i) => {
+          const isFrozen = i === 0;
+          const isTextCol = col.toLowerCase() === 'text';
+          const content = isTextCol
+            ? \`<div class="cell-text-inner">\${esc(row[col])}</div>\`
+            : esc(row[col]);
+          const classes = [
+            isFrozen ? 'frozen frozen-last' : '',
+            isTextCol ? 'cell-text' : '',
+          ].filter(Boolean).join(' ');
+          const style = \`min-width:\${colWidth(col)}px;\${isFrozen ? ' left:0; z-index:2;' : ''}\`;
+          return \`<td\${classes ? \` class="\${classes}"\` : ''} \${isFrozen ? 'data-frozen="0"' : ''} style="\${style}"\${isTextCol ? \` title="\${esc(row[col])}"\` : ''}>\${content}</td>\`;
+        }).join('');
+
+        const glaStatus = row['__gla_status'] || '';
+        const tdGLA = hasGLA ? \`
+          <td class="group-start">\${statusBadge(glaStatus)}</td>
+          <td>\${esc(row['__gla_band'])}</td>
+          <td class="cell-reasoning" title="\${esc(row['__gla_reasoning'])}"><div class="cell-reasoning-inner">\${esc(row['__gla_reasoning'])}</div></td>
+        \` : '';
+
+        const tdCX = complexityEvaluators.map(e => {
+          const prefix = \`__\${e.prefix}\`;
+          return \`
+            <td class="group-start">\${esc(row[prefix + '_score'])}</td>
+            <td class="cell-reasoning" title="\${esc(row[prefix + '_reasoning'])}"><div class="cell-reasoning-inner">\${esc(row[prefix + '_reasoning'])}</div></td>
+          \`;
+        }).join('');
+
+        return \`<tr>\${tdOriginal}\${tdGLA}\${tdCX}</tr>\`;
+      }).join('');
+
+      document.getElementById('tab-results').innerHTML = \`
+        <div class="tab-content" style="max-width:100%;">
+          <div class="results-scroll">
+            <table class="data-table" id="results-table">
+              <thead><tr>\${thOriginal}\${thGLA}\${thCX}</tr></thead>
+              <tbody>\${bodyRows}</tbody>
+            </table>
+          </div>
+        </div>
+      \`;
+
+      requestAnimationFrame(() => applyFrozenOffsets('results-table', frozenCount));
+    }
+
+    /**
+     * Reads the rendered widths of frozen header cells and applies correct
+     * \`left\` offsets to all frozen <th> and <td> cells in the table.
+     */
+    function applyFrozenOffsets(tableId, frozenCount) {
+      const table = document.getElementById(tableId);
+      if (!table) return;
+
+      const headerCells = table.querySelectorAll('thead th.frozen');
+      const offsets = [];
+      let cumLeft = 0;
+      headerCells.forEach(th => {
+        offsets.push(cumLeft);
+        cumLeft += th.offsetWidth;
+      });
+
+      table.querySelectorAll('tr').forEach(row => {
+        const cells = row.querySelectorAll('td.frozen, th.frozen');
+        cells.forEach((cell, i) => {
+          if (i < frozenCount) cell.style.left = (offsets[i] ?? 0) + 'px';
+        });
+      });
+    }
+
+    // ---------------------------------------------------------------------------
+    // Bootstrap
+    // ---------------------------------------------------------------------------
+
+    renderHeader();
+    renderTabs();
+    renderSummary();
+    renderResults();
+  </script>
+</body>
+</html>
+`;
+
+// src/batch/formatters.ts
+var GLA_EVALUATOR_ID = "grade-level-appropriateness";
+var GRADE_BANDS = ["K-1", "2-3", "4-5", "6-8", "9-10", "11-CCR"];
+var COMPLEXITY_SCORE_MAP = {
+  "slightly complex": 1,
+  "moderately complex": 2,
+  "very complex": 3,
+  "exceedingly complex": 4
+};
+function evaluatorDisplayName(id) {
+  return id.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function gradeToBandIndex(grade) {
+  const g = String(grade).trim().toUpperCase().replace(/^0+/, "");
+  if (g === "K" || g === "KINDERGARTEN") return 0;
+  if (g === "1") return 0;
+  if (g === "2" || g === "3") return 1;
+  if (g === "4" || g === "5") return 2;
+  if (g === "6" || g === "7" || g === "8") return 3;
+  if (g === "9" || g === "10") return 4;
+  if (g === "11" || g === "12" || g === "CCR") return 5;
+  return -1;
+}
+function glaBandToIndex(band) {
+  return GRADE_BANDS.indexOf(band);
+}
+function getGLAStatus(inputGrade, glaBand) {
+  const inputIdx = gradeToBandIndex(inputGrade);
+  const glaIdx = glaBandToIndex(glaBand);
+  if (inputIdx === -1 || glaIdx === -1) return "off-target";
+  const diff = Math.abs(inputIdx - glaIdx);
+  if (diff === 0) return "on-band";
+  if (diff === 1) return "adjacent";
+  return "off-target";
+}
+function complexityToNumeric(score) {
+  return COMPLEXITY_SCORE_MAP[score.toLowerCase().trim()];
+}
+function complexityScoreLabel(avg) {
+  if (avg < 1.5) return "Slightly Complex";
+  if (avg < 2.5) return "Moderately Complex";
+  if (avg < 3.5) return "Very Complex";
+  return "Exceedingly Complex";
+}
+function generateInsights() {
+  return [
+    "Review texts marked as Off Target \u2014 they may need content revision or grade-level adjustment before distribution.",
+    "Texts evaluated as Adjacent may benefit from light scaffolding strategies such as vocabulary pre-teaching.",
+    "Higher grade bands tend to show greater text complexity. Consider whether complexity aligns with instructional goals."
+  ];
+}
+function groupResultsByRow(results) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const result of results) {
+    if (!grouped.has(result.rowIndex)) {
+      grouped.set(result.rowIndex, []);
+    }
+    grouped.get(result.rowIndex).push(result);
+  }
+  return grouped;
+}
+function formatEvaluatorPrefix(evaluatorId) {
+  return evaluatorId.replace(/-/g, "_");
+}
+function escapeCSV(field) {
+  if (field.includes(",") || field.includes('"') || field.includes("\n")) {
+    return `"${field.replace(/"/g, '""')}"`;
+  }
+  return field;
+}
+function formatAsCSV(output) {
+  if (output.results.length === 0) {
+    return "";
+  }
+  const groupedByRow = groupResultsByRow(output.results);
+  const evaluatorIds = Array.from(new Set(output.results.map((r) => r.evaluatorId))).sort();
+  const firstResult = output.results[0];
+  const originalColumns = Object.keys(firstResult.originalRow);
+  const evaluatorColumns = [];
+  for (const evalId of evaluatorIds) {
+    const prefix = formatEvaluatorPrefix(evalId);
+    evaluatorColumns.push(`${prefix}_score`);
+    evaluatorColumns.push(`${prefix}_reasoning`);
+    evaluatorColumns.push(`${prefix}_status`);
+  }
+  const headers = [...originalColumns, ...evaluatorColumns];
+  const rows = [];
+  const sortedRowIndices = Array.from(groupedByRow.keys()).sort((a, b) => a - b);
+  for (const rowIndex of sortedRowIndices) {
+    const resultsForRow = groupedByRow.get(rowIndex);
+    const firstResultForRow = resultsForRow[0];
+    const originalValues = originalColumns.map(
+      (col) => escapeCSV(String(firstResultForRow.originalRow[col] || ""))
+    );
+    const evaluatorValues = [];
+    for (const evalId of evaluatorIds) {
+      const result = resultsForRow.find((r) => r.evaluatorId === evalId);
+      if (result) {
+        evaluatorValues.push(result.status === "success" ? escapeCSV(result.score || "") : "");
+        evaluatorValues.push(result.status === "success" ? escapeCSV(result.reasoning || "") : escapeCSV(result.error || ""));
+        evaluatorValues.push(result.status);
+      } else {
+        evaluatorValues.push("", "", "not_run");
+      }
+    }
+    rows.push([...originalValues, ...evaluatorValues]);
+  }
+  return [headers, ...rows].map((row) => row.join(",")).join("\n");
+}
+function formatAsHTML(output, meta) {
+  const { results } = output;
+  const byRow = groupResultsByRow(results);
+  const allRowIndices = Array.from(byRow.keys()).sort((a, b) => a - b);
+  const allEvaluatorIds = Array.from(new Set(results.map((r) => r.evaluatorId))).sort();
+  const hasGLA = allEvaluatorIds.includes(GLA_EVALUATOR_ID);
+  const complexityIds = allEvaluatorIds.filter((id) => id !== GLA_EVALUATOR_ID);
+  let processedRows = 0;
+  let erroredRows = 0;
+  for (const rowResults of byRow.values()) {
+    if (rowResults.some((r) => r.status === "error")) erroredRows++;
+    else processedRows++;
+  }
+  const glaCounts = { onBand: 0, adjacent: 0, offTarget: 0 };
+  const rowGLAStatus = /* @__PURE__ */ new Map();
+  if (hasGLA) {
+    for (const [rowIndex, rowResults] of byRow) {
+      const glaResult = rowResults.find((r) => r.evaluatorId === GLA_EVALUATOR_ID);
+      if (glaResult && glaResult.status === "success" && glaResult.score) {
+        const status = getGLAStatus(glaResult.grade, glaResult.score);
+        rowGLAStatus.set(rowIndex, { status, band: glaResult.score, reasoning: glaResult.reasoning || "" });
+        if (status === "on-band") glaCounts.onBand++;
+        else if (status === "adjacent") glaCounts.adjacent++;
+        else glaCounts.offTarget++;
+      }
+    }
+  }
+  const glaTotal = glaCounts.onBand + glaCounts.adjacent + glaCounts.offTarget;
+  const pct = (n) => glaTotal > 0 ? Math.round(n / glaTotal * 100) : 0;
+  const complexityStats = complexityIds.map((evalId) => {
+    const scores = [];
+    const distribution = [0, 0, 0, 0];
+    for (const rowResults of byRow.values()) {
+      const r = rowResults.find((x) => x.evaluatorId === evalId);
+      if (r && r.status === "success" && r.score) {
+        const num = complexityToNumeric(r.score);
+        if (num !== void 0) {
+          scores.push(num);
+          distribution[num - 1]++;
+        }
+      }
+    }
+    const avg = scores.length > 0 ? scores.reduce((a, b) => a + b, 0) / scores.length : 0;
+    return {
+      evaluatorId: evalId,
+      name: evaluatorDisplayName(evalId),
+      average: Math.round(avg * 10) / 10,
+      label: avg > 0 ? complexityScoreLabel(avg) : "N/A",
+      distribution
+    };
+  });
+  const bandDist = GRADE_BANDS.map(() => ({ onBand: 0, adjacent: 0, offTarget: 0, total: 0 }));
+  for (const [rowIndex, rowResults] of byRow) {
+    const firstResult = rowResults[0];
+    if (!firstResult) continue;
+    const bandIdx = gradeToBandIndex(firstResult.grade);
+    if (bandIdx === -1) continue;
+    const glaStatus = rowGLAStatus.get(rowIndex);
+    if (glaStatus) {
+      bandDist[bandIdx].total++;
+      if (glaStatus.status === "on-band") bandDist[bandIdx].onBand++;
+      else if (glaStatus.status === "adjacent") bandDist[bandIdx].adjacent++;
+      else bandDist[bandIdx].offTarget++;
+    }
+  }
+  const hmSums = GRADE_BANDS.map(() => complexityIds.map(() => 0));
+  const hmCounts = GRADE_BANDS.map(() => complexityIds.map(() => 0));
+  for (const rowResults of byRow.values()) {
+    const firstResult = rowResults[0];
+    if (!firstResult) continue;
+    const bandIdx = gradeToBandIndex(firstResult.grade);
+    if (bandIdx === -1) continue;
+    complexityIds.forEach((evalId, evalIdx) => {
+      const r = rowResults.find((x) => x.evaluatorId === evalId);
+      if (r && r.status === "success" && r.score) {
+        const num = complexityToNumeric(r.score);
+        if (num !== void 0) {
+          hmSums[bandIdx][evalIdx] += num;
+          hmCounts[bandIdx][evalIdx]++;
+        }
+      }
+    });
+  }
+  const heatmapValues = GRADE_BANDS.map(
+    (_, bi) => complexityIds.map((_2, ei) => {
+      const count = hmCounts[bi][ei];
+      return count > 0 ? Math.round(hmSums[bi][ei] / count * 10) / 10 : null;
+    })
+  );
+  const firstRowResults = allRowIndices.length > 0 ? byRow.get(allRowIndices[0]) ?? [] : [];
+  const originalColumns = firstRowResults.length > 0 ? Object.keys(firstRowResults[0].originalRow) : [];
+  const fullResultsRows = allRowIndices.map((rowIndex) => {
+    const rowResults = byRow.get(rowIndex);
+    const firstResult = rowResults[0];
+    const row = {};
+    for (const col of originalColumns) {
+      row[col] = String(firstResult.originalRow[col] ?? "");
+    }
+    const glaStatus = rowGLAStatus.get(rowIndex);
+    const glaLabels = { "on-band": "On Band", "adjacent": "Adjacent", "off-target": "Off Target" };
+    row["__gla_status"] = glaStatus ? glaLabels[glaStatus.status] : hasGLA ? "Error" : "";
+    row["__gla_band"] = glaStatus?.band ?? "";
+    row["__gla_reasoning"] = glaStatus?.reasoning ?? "";
+    for (const evalId of complexityIds) {
+      const r = rowResults.find((x) => x.evaluatorId === evalId);
+      const prefix = `__${evalId.replace(/-/g, "_")}`;
+      row[`${prefix}_score`] = r?.status === "success" ? r.score ?? "" : r?.status === "error" ? "Error" : "";
+      row[`${prefix}_reasoning`] = r?.status === "success" ? r.reasoning ?? "" : r?.error ?? "";
+    }
+    return row;
+  });
+  const reportData = {
+    meta: {
+      reportId: meta.reportId,
+      generatedAt: meta.generatedAt.toLocaleString("en-US", {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true
+      }),
+      csvPath: meta.csvPath,
+      groupId: meta.groupId,
+      evaluatorIds: allEvaluatorIds,
+      evaluatorNames: allEvaluatorIds.map(evaluatorDisplayName),
+      totalRows: meta.totalInputRows,
+      processedRows,
+      erroredRows
+    },
+    gradeLevelStats: {
+      onBand: glaCounts.onBand,
+      adjacent: glaCounts.adjacent,
+      offTarget: glaCounts.offTarget,
+      onBandPct: pct(glaCounts.onBand),
+      adjacentPct: pct(glaCounts.adjacent),
+      offTargetPct: pct(glaCounts.offTarget),
+      hasData: glaTotal > 0
+    },
+    complexityStats,
+    gradeBandDistribution: {
+      bands: [...GRADE_BANDS],
+      data: bandDist
+    },
+    complexityHeatmap: {
+      bands: [...GRADE_BANDS],
+      evaluators: complexityIds.map(evaluatorDisplayName),
+      evaluatorIds: complexityIds,
+      values: heatmapValues
+    },
+    insights: generateInsights(),
+    fullResults: {
+      originalColumns,
+      hasGLA,
+      complexityEvaluators: complexityIds.map((id) => ({
+        evaluatorId: id,
+        name: evaluatorDisplayName(id),
+        prefix: id.replace(/-/g, "_")
+      })),
+      rows: fullResultsRows
+    }
+  };
+  const safeJson = JSON.stringify(reportData).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+  const INJECTION_MARKER = "var REPORT_DATA = null; // __REPLACED_BY_FORMATTER__";
+  if (!report_template_default.includes(INJECTION_MARKER)) {
+    throw new Error("Report template injection marker not found \u2014 template may be corrupted");
+  }
+  return report_template_default.replace(INJECTION_MARKER, `var REPORT_DATA = ${safeJson};`);
+}
+
+// src/batch/progress.ts
+var ProgressTracker = class {
+  totalTasks;
+  completed = 0;
+  successful = 0;
+  failed = 0;
+  startTime;
+  perEvaluator = /* @__PURE__ */ new Map();
+  constructor(totalTasks) {
+    this.totalTasks = totalTasks;
+    this.startTime = Date.now();
+  }
+  /**
+   * Update progress with a new result
+   */
+  update(result) {
+    this.completed++;
+    if (result.status === "success") {
+      this.successful++;
+    } else {
+      this.failed++;
+    }
+    if (!this.perEvaluator.has(result.evaluatorId)) {
+      this.perEvaluator.set(result.evaluatorId, { completed: 0, successful: 0, failed: 0 });
+    }
+    const stats = this.perEvaluator.get(result.evaluatorId);
+    stats.completed++;
+    if (result.status === "success") {
+      stats.successful++;
+    } else {
+      stats.failed++;
+    }
+  }
+  /**
+   * Get current progress percentage
+   */
+  getPercentage() {
+    return Math.round(this.completed / this.totalTasks * 100);
+  }
+  /**
+   * Get elapsed time in seconds
+   */
+  getElapsedSeconds() {
+    return Math.round((Date.now() - this.startTime) / 1e3);
+  }
+  /**
+   * Estimate remaining time in seconds
+   */
+  getEstimatedRemainingSeconds() {
+    if (this.completed === 0) return 0;
+    const elapsed = Date.now() - this.startTime;
+    const avgTimePerTask = elapsed / this.completed;
+    const remaining = this.totalTasks - this.completed;
+    return Math.round(avgTimePerTask * remaining / 1e3);
+  }
+  /**
+   * Format elapsed time as human-readable string
+   */
+  formatElapsed() {
+    const seconds = this.getElapsedSeconds();
+    if (seconds < 60) return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds}s`;
+  }
+  /**
+   * Format estimated remaining time as human-readable string
+   */
+  formatEstimatedRemaining() {
+    const seconds = this.getEstimatedRemainingSeconds();
+    if (seconds < 60) return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds}s`;
+  }
+  /**
+   * Generate progress bar
+   */
+  getProgressBar(width = 20) {
+    const percentage = this.getPercentage();
+    const filled = Math.round(percentage / 100 * width);
+    const empty = width - filled;
+    return "\u2588".repeat(filled) + "\u2591".repeat(empty);
+  }
+  /**
+   * Display progress in terminal
+   */
+  display() {
+    if (this.completed > 1) {
+      const linesToClear = 3 + this.perEvaluator.size;
+      process.stdout.write(`\x1B[${linesToClear}A`);
+      process.stdout.write("\x1B[J");
+    }
+    console.log(
+      `${this.getProgressBar()} ${this.getPercentage()}% (${this.completed}/${this.totalTasks})`
+    );
+    for (const [evalId, stats] of this.perEvaluator.entries()) {
+      const status = stats.completed === stats.successful ? "\u2713" : stats.failed > 0 ? "\u2717" : "\u23F3";
+      console.log(
+        `  ${status} ${evalId}: ${stats.successful}/${stats.completed} successful`
+      );
+    }
+    console.log(
+      `
+\u23F1  Elapsed: ${this.formatElapsed()} | Estimated remaining: ${this.formatEstimatedRemaining()}`
+    );
+  }
+  /**
+   * Display final summary
+   */
+  displaySummary() {
+    const linesToClear = 3 + this.perEvaluator.size + 1;
+    process.stdout.write(`\x1B[${linesToClear}A`);
+    process.stdout.write("\x1B[J");
+    console.log("\n\u2705 Batch evaluation completed!\n");
+    console.log(`Total tasks: ${this.totalTasks}`);
+    console.log(`Successful: ${this.successful} \u2713`);
+    console.log(`Failed: ${this.failed} \u2717`);
+    console.log(`Duration: ${this.formatElapsed()}`);
+    if (this.perEvaluator.size > 1) {
+      console.log("\nResults per evaluator:");
+      for (const [evalId, stats] of this.perEvaluator.entries()) {
+        console.log(
+          `  ${evalId}: ${stats.successful} successful, ${stats.failed} failed`
+        );
+      }
+    }
+    console.log();
+  }
+};
+
+// src/batch/cli.ts
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--concurrency" && args[i + 1]) {
+      const v = parseInt(args[++i], 10);
+      if (!isNaN(v) && v > 0) result.concurrency = v;
+    } else if (args[i] === "--max-retries" && args[i + 1]) {
+      const v = parseInt(args[++i], 10);
+      if (!isNaN(v) && v >= 0) result.maxRetries = v;
+    } else if (args[i] === "--no-telemetry") {
+      result.noTelemetry = true;
+    }
+  }
+  return result;
+}
+async function main() {
+  const cliArgs = parseArgs();
+  console.log("\n\u{1F4CA} Batch CSV Evaluator\n");
+  console.log("This tool will evaluate multiple texts using one or more evaluators.\n");
+  try {
+    let inputs = [];
+    const { csvPath } = await prompts({
+      type: "text",
+      name: "csvPath",
+      message: "Where is your CSV file?",
+      initial: "./input.csv",
+      validate: (value) => {
+        try {
+          inputs = parseCSV(value);
+          return true;
+        } catch (error) {
+          return error instanceof Error ? error.message : "Invalid CSV file";
+        }
+      }
+    });
+    if (!csvPath) {
+      console.log("No file path provided. Run the command again to start over.");
+      process.exit(0);
+    }
+    console.log(`
+\u2713 Found ${inputs.length} rows in CSV
+`);
+    const group = getAvailableGroups()[0];
+    console.log(`\u2713 Evaluator group: ${group.name}`);
+    console.log(`  ${group.description}`);
+    console.log(`  Row limit: ${group.maxInputRows}
+`);
+    if (inputs.length > group.maxInputRows) {
+      console.error(`\u274C Too many rows: ${inputs.length} (max ${group.maxInputRows} for this group)
+`);
+      console.log("Suggestions:");
+      console.log(`  \u2022 Trim the CSV to ${group.maxInputRows} rows`);
+      console.log("  \u2022 Split into multiple smaller batches\n");
+      process.exit(1);
+    }
+    let googleApiKey;
+    let openaiApiKey;
+    if (group.requiresGoogleKey) {
+      const result = await prompts({
+        type: "password",
+        name: "key",
+        message: "Google API Key:",
+        initial: process.env.GOOGLE_API_KEY || "",
+        validate: (value) => value ? true : "Google API key is required"
+      });
+      if (!result.key) {
+        console.log("Cancelled.");
+        process.exit(0);
+      }
+      googleApiKey = result.key;
+    }
+    if (group.requiresOpenAIKey) {
+      const result = await prompts({
+        type: "password",
+        name: "key",
+        message: "OpenAI API Key:",
+        initial: process.env.OPENAI_API_KEY || "",
+        validate: (value) => value ? true : "OpenAI API key is required"
+      });
+      if (!result.key) {
+        console.log("Cancelled.");
+        process.exit(0);
+      }
+      openaiApiKey = result.key;
+    }
+    const now = /* @__PURE__ */ new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    const timestamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}_${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
+    const defaultOutputDir = path.join(process.cwd(), `batch-results-${timestamp}`);
+    const { outputDir } = await prompts({
+      type: "text",
+      name: "outputDir",
+      message: "Output directory:",
+      initial: defaultOutputDir,
+      validate: (value) => {
+        const parentDir = path.dirname(value);
+        if (!fs2.existsSync(parentDir)) {
+          return `Parent directory does not exist: ${parentDir}`;
+        }
+        try {
+          const testFile = path.join(parentDir, ".write-test");
+          fs2.writeFileSync(testFile, "");
+          fs2.unlinkSync(testFile);
+          return true;
+        } catch (error) {
+          if (error instanceof Error) {
+            if (error.message.includes("EACCES")) return `No write permission for directory: ${parentDir}`;
+            if (error.message.includes("EROFS")) return `Directory is read-only: ${parentDir}`;
+            return `Cannot write to directory: ${error.message}`;
+          }
+          return "Cannot write to directory";
+        }
+      }
+    });
+    if (!outputDir) {
+      console.log("No output directory provided. Run the command again to start over.");
+      process.exit(0);
+    }
+    fs2.mkdirSync(outputDir, { recursive: true });
+    const csvBasename = path.basename(csvPath, path.extname(csvPath));
+    const reportMeta = {
+      csvPath: path.resolve(csvPath),
+      groupId: group.id,
+      reportId: `${csvBasename.replace(/[^a-zA-Z0-9]/g, "_")}_${timestamp}`,
+      generatedAt: now,
+      totalInputRows: inputs.length
+    };
+    const totalTasks = inputs.length * group.evaluatorIds.length;
+    console.log(`
+\u{1F4DD} Summary:`);
+    console.log(`  Input rows: ${inputs.length}`);
+    console.log(`  Evaluators: ${group.evaluatorIds.length}`);
+    console.log(`  Total tasks: ${totalTasks}`);
+    console.log(`  Concurrency: ${cliArgs.concurrency ?? 3}`);
+    console.log(`  Max retries: ${cliArgs.maxRetries ?? 2}`);
+    console.log(`  Output: ${outputDir}
+`);
+    const { confirm } = await prompts({
+      type: "confirm",
+      name: "confirm",
+      message: "Start batch evaluation?",
+      initial: true
+    });
+    if (!confirm) {
+      console.log("Cancelled.");
+      process.exit(0);
+    }
+    console.log("\n" + "=".repeat(60));
+    const tracker = new ProgressTracker(totalTasks);
+    const evaluationStartTime = Date.now();
+    const evaluator = new BatchEvaluator({
+      googleApiKey,
+      openaiApiKey,
+      concurrency: cliArgs.concurrency ?? 3,
+      maxRetries: cliArgs.maxRetries ?? 2,
+      telemetry: !cliArgs.noTelemetry
+    });
+    let isShuttingDown = false;
+    const handleShutdown = () => {
+      if (isShuttingDown) {
+        console.log("\n\n\u26A0\uFE0F  Force quit detected. Exiting immediately...");
+        process.exit(1);
+      }
+      isShuttingDown = true;
+      console.log("\n\n\u26A0\uFE0F  Shutdown requested. Saving partial results...");
+      console.log("   (Press Ctrl+C again to force quit)\n");
+      const partialResults = evaluator.cancel();
+      if (partialResults.length > 0) {
+        const durationMs = Date.now() - evaluationStartTime;
+        const partialOutput = {
+          results: partialResults,
+          summary: {
+            totalTasks: partialResults.length,
+            successful: partialResults.filter((r) => r.status === "success").length,
+            failed: partialResults.filter((r) => r.status === "error").length,
+            durationMs,
+            resultsPerEvaluator: {}
+          }
+        };
+        try {
+          fs2.writeFileSync(path.join(outputDir, "results-partial.csv"), formatAsCSV(partialOutput));
+          fs2.writeFileSync(path.join(outputDir, "results-partial.html"), formatAsHTML(partialOutput, reportMeta));
+          console.log(`\u2713 Saved ${partialResults.length} results to:`);
+          console.log(`  ${outputDir}/`);
+          console.log(`    \u251C\u2500\u2500 results-partial.csv`);
+          console.log(`    \u2514\u2500\u2500 results-partial.html`);
+          console.log();
+        } catch (error) {
+          console.error("\u274C Error saving partial results:", error instanceof Error ? error.message : String(error));
+        }
+      } else {
+        console.log("No results to save yet.\n");
+      }
+      process.exit(0);
+    };
+    process.on("SIGINT", handleShutdown);
+    process.on("SIGTERM", handleShutdown);
+    let output;
+    try {
+      output = await evaluator.evaluate(inputs, group.id, (result) => {
+        tracker.update(result);
+        tracker.display();
+      });
+    } finally {
+      process.off("SIGINT", handleShutdown);
+      process.off("SIGTERM", handleShutdown);
+    }
+    tracker.displaySummary();
+    try {
+      fs2.writeFileSync(path.join(outputDir, "results.csv"), formatAsCSV(output));
+      fs2.writeFileSync(path.join(outputDir, "results.html"), formatAsHTML(output, reportMeta));
+      console.log("\u{1F4C4} Output files generated:");
+      console.log(`  ${outputDir}/`);
+      console.log(`    \u251C\u2500\u2500 results.csv`);
+      console.log(`    \u2514\u2500\u2500 results.html`);
+      console.log();
+      const htmlPath = path.join(outputDir, "results.html");
+      try {
+        const cmd = process.platform === "win32" ? `start "" "${htmlPath}"` : `open "${htmlPath}"`;
+        exec(cmd);
+      } catch {
+      }
+    } catch (error) {
+      console.error("\n\u274C Error writing output files:");
+      if (error instanceof Error) console.error(`  ${error.message}`);
+      console.error("\n\u26A0\uFE0F  Evaluation completed but outputs could not be saved.");
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error("\n\u274C Error:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map