@learning-commons/evaluators 0.1.0

package/dist/index.js

@@ -0,0 +1,1866 @@
+import { z } from 'zod';
+import { randomUUID } from 'crypto';
+import { readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { generateText, Output } from 'ai';
+import nlp from 'compromise';
+import { syllable } from 'syllable';
+import pLimit from 'p-limit';
+
+// src/schemas/outputs.ts
+var TextComplexityLevel = z.enum([
+  "Slightly complex",
+  "Moderately complex",
+  "Very complex",
+  "Exceedingly complex"
+]);
+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")
+});
+
+// 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 LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  LogLevel2[LogLevel2["SILENT"] = 4] = "SILENT";
+  return LogLevel2;
+})(LogLevel || {});
+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);
+}
+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
+});
+
+// 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 path of possiblePaths) {
+    try {
+      const pkg = JSON.parse(readFileSync(path, "utf-8"));
+      cachedVersion = pkg.version || "0.0.0";
+      return cachedVersion;
+    } catch {
+      continue;
+    }
+  }
+  cachedVersion = "0.0.0";
+  return cachedVersion;
+}
+
+// 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) - parseInt(b);
+      }).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 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
+    };
+  }
+};
+async function evaluateVocabulary(text, grade, config) {
+  const evaluator = new VocabularyEvaluator(config);
+  return evaluator.evaluate(text, grade);
+}
+
+// ../../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
+    };
+  }
+};
+async function evaluateSentenceStructure(text, grade, config) {
+  const evaluator = new SentenceStructureEvaluator(config);
+  return evaluator.evaluate(text, 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");
+    }
+  }
+};
+async function evaluateGradeLevelAppropriateness(text, config) {
+  const evaluator = new GradeLevelAppropriatenessEvaluator(config);
+  return evaluator.evaluate(text);
+}
+var TextComplexityEvaluator = class _TextComplexityEvaluator extends BaseEvaluator {
+  static metadata = {
+    id: "text-complexity",
+    name: "Text Complexity",
+    description: "Composite evaluator analyzing vocabulary and sentence structure complexity",
+    supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
+    requiresGoogleKey: true,
+    requiresOpenAIKey: true
+  };
+  vocabularyEvaluator;
+  sentenceStructureEvaluator;
+  limit;
+  constructor(config) {
+    super(config);
+    this.vocabularyEvaluator = new VocabularyEvaluator(config);
+    this.sentenceStructureEvaluator = new SentenceStructureEvaluator(config);
+    this.limit = pLimit(3);
+  }
+  /**
+   * Evaluate text complexity for a given text and grade level
+   *
+   * Runs vocabulary and sentence structure evaluations in parallel with concurrency control.
+   * If both sub-evaluators fail, throws an error. Otherwise returns a result map where
+   * failed sub-evaluators are represented as `{ error: Error }`.
+   *
+   * @param text - The text to evaluate
+   * @param grade - The target grade level (3-12)
+   * @returns Map of sub-evaluator results
+   * @throws {ValidationError} If text is empty or grade is invalid
+   * @throws {Error} If all sub-evaluators fail
+   */
+  async evaluate(text, grade) {
+    this.logger.info("Starting text complexity evaluation", {
+      evaluator: "text-complexity",
+      operation: "evaluate",
+      grade,
+      textLength: text.length
+    });
+    this.validateText(text);
+    this.validateGrade(grade, new Set(_TextComplexityEvaluator.metadata.supportedGrades));
+    const startTime = Date.now();
+    const [vocabResult, sentenceResult] = await Promise.all([
+      this.limit(() => this.runSubEvaluator(this.vocabularyEvaluator, text, grade)),
+      this.limit(() => this.runSubEvaluator(this.sentenceStructureEvaluator, text, grade))
+    ]);
+    const latencyMs = Date.now() - startTime;
+    const vocabFailed = "error" in vocabResult;
+    const sentenceFailed = "error" in sentenceResult;
+    const hasFailures = vocabFailed || sentenceFailed;
+    if (hasFailures) {
+      const errors = [];
+      if (vocabFailed) errors.push(`Vocabulary: ${vocabResult.error.message}`);
+      if (sentenceFailed) errors.push(`Sentence structure: ${sentenceResult.error.message}`);
+      this.logger.error("Text complexity evaluation completed with errors", {
+        evaluator: "text-complexity",
+        operation: "evaluate",
+        grade,
+        errors,
+        processingTimeMs: latencyMs
+      });
+      if (vocabFailed && sentenceFailed) {
+        throw new Error(`Text complexity evaluation failed: ${errors.join("; ")}`);
+      }
+    }
+    this.sendTelemetry({
+      status: hasFailures ? "error" : "success",
+      latencyMs,
+      textLength: text.length,
+      grade,
+      provider: "composite:google+openai",
+      errorCode: hasFailures ? "PartialFailure" : void 0,
+      inputText: text
+    }).catch(() => {
+    });
+    this.logger.info("Text complexity evaluation completed", {
+      evaluator: "text-complexity",
+      operation: "evaluate",
+      grade,
+      processingTimeMs: latencyMs,
+      hasFailures
+    });
+    return { vocabulary: vocabResult, sentenceStructure: sentenceResult };
+  }
+  /**
+   * Run a sub-evaluator with error handling.
+   * Returns the evaluation result or `{ error: Error }` if the evaluator throws.
+   */
+  async runSubEvaluator(evaluator, text, grade) {
+    try {
+      return await evaluator.evaluate(text, grade);
+    } catch (error) {
+      return { error: error instanceof Error ? error : new Error(String(error)) };
+    }
+  }
+};
+async function evaluateTextComplexity(text, grade, config) {
+  const evaluator = new TextComplexityEvaluator(config);
+  return evaluator.evaluate(text, grade);
+}
+
+export { APIError, AuthenticationError, ComplexityClassificationSchema, ConfigurationError, EvaluatorError, GradeBand, GradeLevelAppropriatenessEvaluator, GradeLevelAppropriatenessSchema, LogLevel, NetworkError, RateLimitError, SentenceAnalysisSchema, SentenceStructureEvaluator, TextComplexityEvaluator, TextComplexityLevel, TimeoutError, ValidationError, VocabularyEvaluator, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateGradeLevelAppropriateness, evaluateSentenceStructure, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map