@learning-commons/evaluators 0.4.0 → 0.6.0

package/dist/batch/index.cjs

@@ -10,6 +10,7 @@ var ai = require('ai');
 var zod = require('zod');
 var nlp = require('compromise');
 var syllable = require('syllable');
+var textReadability = require('text-readability');
 var sync = require('csv-parse/sync');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -36,6 +37,7 @@ function _interopNamespace(e) {
 var pLimit__default = /*#__PURE__*/_interopDefault(pLimit);
 var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 var nlp__default = /*#__PURE__*/_interopDefault(nlp);
+var textReadability__default = /*#__PURE__*/_interopDefault(textReadability);
 
 // src/batch/evaluator.ts
 
@@ -198,8 +200,9 @@ var TimeoutError = class extends APIError {
 function parseProviderError(error) {
   if (error instanceof Error) {
     const message = error.message;
+    const err = error;
     const statusMatch = message.match(/\b(4\d{2}|5\d{2})\b/);
-    const statusCode = statusMatch ? parseInt(statusMatch[1]) : void 0;
+    const statusCode = err.statusCode ?? err.status ?? (statusMatch ? parseInt(statusMatch[1]) : void 0);
     return {
       message,
       statusCode,
@@ -212,6 +215,11 @@ function parseProviderError(error) {
 }
 function wrapProviderError(error, defaultMessage = "API request failed") {
   const { message, statusCode, code } = parseProviderError(error);
+  if (statusCode === 404 || statusCode === 400 && /\bmodel\b.*(not found|does not exist|invalid)/i.test(message)) {
+    return new ConfigurationError(
+      `Model not found or invalid: ${message}. Check the model ID passed to the provider.`
+    );
+  }
   if (statusCode === 401 || statusCode === 403) {
     return new AuthenticationError(
       message.includes("API key") ? message : "Invalid API key",
@@ -286,6 +294,111 @@ function createLogger(customLogger, level = 2 /* WARN */) {
   }
   return new ConsoleLogger(level);
 }
+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."
+      );
+    }
+    if (!config.model || config.model.trim() === "") {
+      throw new Error(
+        `model is required for VercelAIProvider (type: "${config.type}"). No default is assumed.`
+      );
+    }
+    this.model = config.model;
+    this.label = `${config.type}:${config.model}`;
+  }
+  label;
+  model;
+  /**
+   * Generate structured output using Vercel AI SDK's generateText with output
+   */
+  async generateStructured(request) {
+    const model = await this.getModel();
+    const startTime = Date.now();
+    const { output, usage } = await ai.generateText({
+      model,
+      messages: request.messages,
+      output: ai.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: this.model,
+      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 ai.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() {
+    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 } : {})(this.model);
+      }
+      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 } : {})(this.model);
+      }
+      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 } : {})(this.model);
+      }
+      default:
+        throw new Error(`Unsupported provider type: ${this.config.type}`);
+    }
+  }
+};
+function createProvider(config) {
+  if (config.type === "custom" && config.customProvider) {
+    return config.customProvider;
+  }
+  return new VercelAIProvider(config);
+}
 
 // src/evaluators/base.ts
 var VALIDATION_LIMITS = {
@@ -294,6 +407,12 @@ var VALIDATION_LIMITS = {
   /** Maximum text length in characters (100K chars ≈ 25K tokens) */
   MAX_TEXT_LENGTH: 1e5
 };
+var Provider = /* @__PURE__ */ ((Provider2) => {
+  Provider2["OpenAI"] = "openai";
+  Provider2["Google"] = "google";
+  Provider2["Anthropic"] = "anthropic";
+  return Provider2;
+})(Provider || {});
 var BaseEvaluator = class {
   telemetryClient;
   logger;
@@ -311,21 +430,35 @@ var BaseEvaluator = class {
    *     name: 'My Evaluator',
    *     description: 'Does something useful',
    *     supportedGrades: ['3', '4', '5'],
-   *     requiresGoogleKey: true,
-   *     requiresOpenAIKey: false,
+   *     defaultProviders: [Provider.Google],
    *   };
    * }
    * ```
    */
   static metadata;
+  /**
+   * @throws {ConfigurationError} If the subclass has not defined static metadata
+   * @throws {ConfigurationError} If modelOverride has an invalid provider or empty model
+   * @throws {ConfigurationError} If a required API key is missing
+   */
   constructor(config) {
     this.logger = createLogger(config.logger, config.logLevel ?? 2 /* WARN */);
+    this.validateModelOverride(config);
     this.validateApiKeys(config);
     const telemetryConfig = this.normalizeTelemetryConfig(config.telemetry);
     this.config = {
       maxRetries: config.maxRetries ?? 2,
-      telemetry: telemetryConfig
+      telemetry: telemetryConfig,
+      modelOverride: config.modelOverride,
+      googleApiKey: config.googleApiKey,
+      openaiApiKey: config.openaiApiKey,
+      anthropicApiKey: config.anthropicApiKey
     };
+    if (config.modelOverride) {
+      this.logger.warn(
+        `modelOverride is active: using ${config.modelOverride.provider}:${config.modelOverride.model} instead of the default model. Evaluation quality may differ from recommended defaults.`
+      );
+    }
     if (this.config.telemetry.enabled) {
       this.telemetryClient = new TelemetryClient({
         endpoint: "https://api.learningcommons.org/evaluators-telemetry/v1/events",
@@ -350,21 +483,62 @@ var BaseEvaluator = class {
     return meta;
   }
   /**
-   * Validate that required API keys are provided based on metadata
-   * @throws {ConfigurationError} If required API keys are missing
+   * Validate modelOverride shape: provider must be a known Provider value and
+   * model must be a non-empty string.
+   * @throws {ConfigurationError} If the override is malformed
    */
-  validateApiKeys(config) {
-    if (this.metadata.requiresGoogleKey && !config.googleApiKey) {
+  validateModelOverride(config) {
+    if (!config.modelOverride) return;
+    const validProviders = Object.values(Provider);
+    if (!validProviders.includes(config.modelOverride.provider)) {
       throw new ConfigurationError(
-        `Google API key is required for ${this.metadata.name} evaluator. Pass googleApiKey in config.`
+        `Invalid provider "${config.modelOverride.provider}" in modelOverride. Valid providers are: ${validProviders.join(", ")}.`
       );
     }
-    if (this.metadata.requiresOpenAIKey && !config.openaiApiKey) {
+    if (!config.modelOverride.model || config.modelOverride.model.trim() === "") {
       throw new ConfigurationError(
-        `OpenAI API key is required for ${this.metadata.name} evaluator. Pass openaiApiKey in config.`
+        `modelOverride.model is required. Specify the model ID for provider "${config.modelOverride.provider}".`
       );
     }
   }
+  /**
+   * Validate that the required API key is present.
+   * When modelOverride is set, checks the override provider's key.
+   * Otherwise checks the keys required by the evaluator's default providers.
+   * @throws {ConfigurationError} If a required key is missing
+   */
+  validateApiKeys(config) {
+    const keyFor = {
+      ["openai" /* OpenAI */]: config.openaiApiKey?.trim() || void 0,
+      ["google" /* Google */]: config.googleApiKey?.trim() || void 0,
+      ["anthropic" /* Anthropic */]: config.anthropicApiKey?.trim() || void 0
+    };
+    const humanName = {
+      ["openai" /* OpenAI */]: "OpenAI API key",
+      ["google" /* Google */]: "Google API key",
+      ["anthropic" /* Anthropic */]: "Anthropic API key"
+    };
+    const configKey = {
+      ["openai" /* OpenAI */]: "openaiApiKey",
+      ["google" /* Google */]: "googleApiKey",
+      ["anthropic" /* Anthropic */]: "anthropicApiKey"
+    };
+    if (config.modelOverride) {
+      if (!keyFor[config.modelOverride.provider]) {
+        throw new ConfigurationError(
+          `${humanName[config.modelOverride.provider]} is required when using modelOverride with provider "${config.modelOverride.provider}". Pass ${configKey[config.modelOverride.provider]} in config.`
+        );
+      }
+      return;
+    }
+    for (const provider of this.metadata.defaultProviders) {
+      if (!keyFor[provider]) {
+        throw new ConfigurationError(
+          `${humanName[provider]} is required for ${this.metadata.name} evaluator. Pass ${configKey[provider]} in config.`
+        );
+      }
+    }
+  }
   /**
    * Normalize telemetry config to standard format
    */
@@ -445,6 +619,33 @@ var BaseEvaluator = class {
       );
     }
   }
+  /**
+   * Create an LLM provider, honouring modelOverride if set.
+   * When override is active, the key for the override provider is resolved
+   * from the matching top-level config field (e.g. anthropicApiKey for Anthropic).
+   */
+  createConfiguredProvider(defaultType, defaultModel, defaultApiKey) {
+    const override = this.config.modelOverride;
+    if (override) {
+      const apiKeyFor = {
+        ["openai" /* OpenAI */]: this.config.openaiApiKey,
+        ["google" /* Google */]: this.config.googleApiKey,
+        ["anthropic" /* Anthropic */]: this.config.anthropicApiKey
+      };
+      return createProvider({
+        type: override.provider,
+        model: override.model,
+        apiKey: apiKeyFor[override.provider],
+        maxRetries: this.config.maxRetries
+      });
+    }
+    return createProvider({
+      type: defaultType,
+      model: defaultModel,
+      apiKey: defaultApiKey,
+      maxRetries: this.config.maxRetries
+    });
+  }
   /**
    * Send telemetry event to analytics service
    * Common helper for all evaluators
@@ -465,123 +666,12 @@ var BaseEvaluator = class {
       provider: params.provider,
       token_usage: params.tokenUsage,
       metadata: params.metadata,
+      model_override: this.config.modelOverride ? true : void 0,
       // 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 ai.generateText({
-      model,
-      messages: request.messages,
-      output: ai.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 ai.generateText({
-      model,
-      messages,
-      temperature: temperature ?? this.config.temperature ?? 0,
-      maxRetries: this.config.maxRetries ?? 0
-    });
-    return {
-      text,
-      usage: {
-        inputTokens: usage.inputTokens || 0,
-        outputTokens: usage.outputTokens || 0
-      },
-      latencyMs: Date.now() - startTime
-    };
-  }
-  /**
-   * Get the configured language model.
-   * Uses dynamic imports so consumers only need to install the provider packages they use.
-   */
-  async getModel(requestModel) {
-    const modelId = requestModel || this.config.model || this.getDefaultModel();
-    const apiKey = this.config.apiKey;
-    switch (this.config.type) {
-      case "openai": {
-        const { createOpenAI } = await import('@ai-sdk/openai').catch(() => {
-          throw new Error(
-            "To use the OpenAI provider, install its adapter: npm install @ai-sdk/openai"
-          );
-        });
-        return createOpenAI(apiKey ? { apiKey } : {})(modelId);
-      }
-      case "anthropic": {
-        const { createAnthropic } = await import('@ai-sdk/anthropic').catch(() => {
-          throw new Error(
-            "To use the Anthropic provider, install its adapter: npm install @ai-sdk/anthropic"
-          );
-        });
-        return createAnthropic(apiKey ? { apiKey } : {})(modelId);
-      }
-      case "google": {
-        const { createGoogleGenerativeAI } = await import('@ai-sdk/google').catch(() => {
-          throw new Error(
-            "To use the Google provider, install its adapter: npm install @ai-sdk/google"
-          );
-        });
-        return createGoogleGenerativeAI(apiKey ? { apiKey } : {})(modelId);
-      }
-      default:
-        throw new Error(`Unsupported provider type: ${this.config.type}`);
-    }
-  }
-  /**
-   * Get default model for the configured provider
-   */
-  getDefaultModel() {
-    const providerType = this.config.type;
-    if (providerType === "custom") {
-      throw new Error("Cannot get default model for custom provider type");
-    }
-    return DEFAULT_MODELS[providerType];
-  }
-};
-function createProvider(config) {
-  if (config.type === "custom" && config.customProvider) {
-    return config.customProvider;
-  }
-  return new VercelAIProvider(config);
-}
 var TextComplexityLevel = zod.z.enum([
   "Slightly complex",
   "Moderately complex",
@@ -783,6 +873,44 @@ function featuresToJSON(features, decimals = 1, castToInt = true) {
   }
   return JSON.stringify(payload, null, 2);
 }
+var LIBRARY_ADAPTERS = {
+  "text-readability": {
+    call(fnName, text) {
+      const fn = textReadability__default.default[fnName];
+      if (typeof fn !== "function") {
+        throw new Error(`Function "${fnName}" not found in text-readability.`);
+      }
+      return fn.call(textReadability__default.default, text);
+    }
+  }
+};
+var POST_TRANSFORMS = {
+  round(value, { precision = 0 }) {
+    const factor = 10 ** precision;
+    return Math.round(value * factor) / factor;
+  }
+};
+function runPreprocessingStep(text, impl) {
+  const adapter = LIBRARY_ADAPTERS[impl.library];
+  if (!adapter) {
+    const supported = Object.keys(LIBRARY_ADAPTERS).join(", ");
+    throw new Error(
+      `Unsupported preprocessing library "${impl.library}". Supported: ${supported}.`
+    );
+  }
+  let result = adapter.call(impl.function, text);
+  if (impl.post_transform) {
+    const transform = POST_TRANSFORMS[impl.post_transform.type];
+    if (!transform) {
+      const supported = Object.keys(POST_TRANSFORMS).join(", ");
+      throw new Error(
+        `Unsupported post_transform type "${impl.post_transform.type}". Supported: ${supported}.`
+      );
+    }
+    result = transform(result, impl.post_transform);
+  }
+  return result;
+}
 
 // ../../evals/prompts/vocabulary/background-knowledge.txt
 var background_knowledge_default = `
@@ -1088,32 +1216,28 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
     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
+    defaultProviders: ["google" /* Google */, "openai" /* OpenAI */]
   };
   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
-    });
+    this.grades34ComplexityProvider = this.createConfiguredProvider(
+      "google" /* Google */,
+      "gemini-2.5-pro",
+      config.googleApiKey
+    );
+    this.otherGradesComplexityProvider = this.createConfiguredProvider(
+      "openai" /* OpenAI */,
+      "gpt-4.1-2025-04-14",
+      config.openaiApiKey
+    );
+    this.backgroundKnowledgeProvider = this.createConfiguredProvider(
+      "openai" /* OpenAI */,
+      "gpt-4o-2024-11-20",
+      config.openaiApiKey
+    );
   }
   /**
    * Evaluate vocabulary complexity for a given text and grade level
@@ -1122,6 +1246,7 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
    * @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 {ConfigurationError} If modelOverride specifies a model ID that the provider rejects
    * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
    */
   async evaluate(text, grade) {
@@ -1133,7 +1258,9 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
     });
     const startTime = Date.now();
     const stageDetails = [];
-    const complexityProviderName = grade === "3" || grade === "4" ? "google:gemini-2.5-pro" : "openai:gpt-4.1-2025-04-14";
+    const complexityProviderLabel = grade === "3" || grade === "4" ? this.grades34ComplexityProvider.label : this.otherGradesComplexityProvider.label;
+    const backgroundProviderLabel = this.backgroundKnowledgeProvider.label;
+    const modelLabel = this.config.modelOverride ? backgroundProviderLabel : `${backgroundProviderLabel}+${complexityProviderLabel}`;
     try {
       this.validateText(text);
       this.validateGrade(grade, new Set(_VocabularyEvaluator.metadata.supportedGrades));
@@ -1144,7 +1271,7 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
       const bgResponse = await this.getBackgroundKnowledgeAssumption(text, grade);
       stageDetails.push({
         stage: "background_knowledge",
-        provider: "openai:gpt-4o-2024-11-20",
+        provider: backgroundProviderLabel,
         latency_ms: bgResponse.latencyMs,
         token_usage: {
           input_tokens: bgResponse.usage.inputTokens,
@@ -1160,7 +1287,7 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
       );
       stageDetails.push({
         stage: "complexity_evaluation",
-        provider: complexityProviderName,
+        provider: complexityProviderLabel,
         latency_ms: complexityResponse.latencyMs,
         token_usage: {
           input_tokens: complexityResponse.usage.inputTokens,
@@ -1176,8 +1303,10 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
         score: complexityResponse.data.complexity_score,
         reasoning: complexityResponse.data.reasoning,
         metadata: {
-          model: `openai:gpt-4o-2024-11-20 + ${complexityProviderName}`,
-          processingTimeMs: latencyMs
+          model: modelLabel,
+          processingTimeMs: latencyMs,
+          inputTokens: totalTokenUsage.input_tokens,
+          outputTokens: totalTokenUsage.output_tokens
         },
         _internal: complexityResponse.data
       };
@@ -1186,7 +1315,7 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
         latencyMs,
         textLength: text.length,
         grade,
-        provider: `openai:gpt-4o-2024-11-20 + ${complexityProviderName}`,
+        provider: modelLabel,
         tokenUsage: totalTokenUsage,
         metadata: {
           stage_details: stageDetails
@@ -1221,7 +1350,7 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
         latencyMs,
         textLength: text.length,
         grade,
-        provider: `openai:gpt-4o-2024-11-20 + ${complexityProviderName}`,
+        provider: modelLabel,
         tokenUsage: totalTokenUsage,
         errorCode: error instanceof Error ? error.name : "UnknownError",
         metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
@@ -1439,25 +1568,12 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
     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
+    defaultProviders: ["openai" /* OpenAI */]
   };
-  analysisProvider;
-  complexityProvider;
+  provider;
   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
-    });
+    this.provider = this.createConfiguredProvider("openai" /* OpenAI */, "gpt-4o", config.openaiApiKey);
   }
   /**
    * Evaluate sentence structure complexity for a given text and grade level
@@ -1466,6 +1582,7 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
    * @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 {ConfigurationError} If modelOverride specifies a model ID that the provider rejects
    * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
    */
   async evaluate(text, grade) {
@@ -1487,7 +1604,7 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
       const analysisResponse = await this.analyzeSentenceStructure(text);
       stageDetails.push({
         stage: "sentence_analysis",
-        provider: "openai:gpt-4o",
+        provider: this.provider.label,
         latency_ms: analysisResponse.latencyMs,
         token_usage: {
           input_tokens: analysisResponse.usage.inputTokens,
@@ -1502,7 +1619,7 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
       const complexityResponse = await this.classifyComplexity(features, grade, text);
       stageDetails.push({
         stage: "complexity_classification",
-        provider: "openai:gpt-4o",
+        provider: this.provider.label,
         latency_ms: complexityResponse.latencyMs,
         token_usage: {
           input_tokens: complexityResponse.usage.inputTokens,
@@ -1518,8 +1635,10 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
         score: complexityResponse.data.answer,
         reasoning: complexityResponse.data.reasoning,
         metadata: {
-          model: "openai:gpt-4o",
-          processingTimeMs: latencyMs
+          model: this.provider.label,
+          processingTimeMs: latencyMs,
+          inputTokens: totalTokenUsage.input_tokens,
+          outputTokens: totalTokenUsage.output_tokens
         },
         _internal: {
           sentenceAnalysis: analysisResponse.data,
@@ -1532,7 +1651,7 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
         latencyMs,
         textLength: text.length,
         grade,
-        provider: "openai:gpt-4o",
+        provider: this.provider.label,
         tokenUsage: totalTokenUsage,
         metadata: {
           stage_details: stageDetails
@@ -1567,7 +1686,7 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
         latencyMs,
         textLength: text.length,
         grade,
-        provider: "openai:gpt-4o",
+        provider: this.provider.label,
         tokenUsage: totalTokenUsage,
         errorCode: error instanceof Error ? error.name : "UnknownError",
         metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
@@ -1595,7 +1714,7 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
       `flesch_kincaid_grade: ${metrics.fleschKincaidGrade}`
     ].join("\n");
     const userPrompt = getUserPromptAnalysis(text, gtCountsStr);
-    const response = await this.analysisProvider.generateStructured({
+    const response = await this.provider.generateStructured({
       messages: [
         { role: "system", content: getSystemPromptAnalysis() },
         { role: "user", content: userPrompt }
@@ -1617,7 +1736,7 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
   async classifyComplexity(features, grade, excerpt) {
     const featuresJSON = featuresToJSON(features, 1, true);
     const userPrompt = getUserPromptComplexity(featuresJSON, grade, excerpt);
-    const response = await this.complexityProvider.generateStructured({
+    const response = await this.provider.generateStructured({
       messages: [
         { role: "system", content: getSystemPromptComplexity() },
         { role: "user", content: userPrompt }
@@ -1673,18 +1792,16 @@ var GradeLevelAppropriatenessEvaluator = class extends BaseEvaluator {
     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
+    defaultProviders: ["google" /* Google */]
   };
   provider;
   constructor(config) {
     super(config);
-    this.provider = createProvider({
-      type: "google",
-      model: "gemini-2.5-pro",
-      apiKey: config.googleApiKey,
-      maxRetries: this.config.maxRetries
-    });
+    this.provider = this.createConfiguredProvider(
+      "google" /* Google */,
+      "gemini-2.5-pro",
+      config.googleApiKey
+    );
   }
   /**
    * Evaluate grade level appropriateness for a given text
@@ -1692,6 +1809,7 @@ var GradeLevelAppropriatenessEvaluator = class extends BaseEvaluator {
    * @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 {ConfigurationError} If modelOverride specifies a model ID that the provider rejects
    * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
    */
   async evaluate(text) {
@@ -1725,8 +1843,10 @@ var GradeLevelAppropriatenessEvaluator = class extends BaseEvaluator {
         score: response.data.grade,
         reasoning: response.data.reasoning,
         metadata: {
-          model: "google:gemini-2.5-pro",
-          processingTimeMs: latencyMs
+          model: this.provider.label,
+          processingTimeMs: latencyMs,
+          inputTokens: tokenUsage.input_tokens,
+          outputTokens: tokenUsage.output_tokens
         },
         _internal: response.data
       };
@@ -1734,7 +1854,7 @@ var GradeLevelAppropriatenessEvaluator = class extends BaseEvaluator {
         status: "success",
         latencyMs,
         textLength: text.length,
-        provider: "google:gemini-2.5-pro",
+        provider: this.provider.label,
         tokenUsage,
         // No metadata.stage_details for single-stage evaluator
         inputText: text
@@ -1759,7 +1879,7 @@ var GradeLevelAppropriatenessEvaluator = class extends BaseEvaluator {
         status: "error",
         latencyMs,
         textLength: text.length,
-        provider: "google:gemini-2.5-pro",
+        provider: this.provider.label,
         errorCode: error instanceof Error ? error.name : "UnknownError",
         inputText: text
       }).catch(() => {
@@ -1870,18 +1990,16 @@ var SmkEvaluator = class _SmkEvaluator extends BaseEvaluator {
     name: "Subject Matter Knowledge",
     description: "Evaluates background knowledge demands of educational texts relative to grade level",
     supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
-    requiresGoogleKey: true,
-    requiresOpenAIKey: false
+    defaultProviders: ["google" /* Google */]
   };
   provider;
   constructor(config) {
     super(config);
-    this.provider = createProvider({
-      type: "google",
-      model: "gemini-3-flash-preview",
-      apiKey: config.googleApiKey,
-      maxRetries: this.config.maxRetries
-    });
+    this.provider = this.createConfiguredProvider(
+      "google" /* Google */,
+      "gemini-3-flash-preview",
+      config.googleApiKey
+    );
   }
   /**
    * Evaluate subject matter knowledge complexity for a given text and grade level
@@ -1890,6 +2008,7 @@ var SmkEvaluator = class _SmkEvaluator extends BaseEvaluator {
    * @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 {ConfigurationError} If modelOverride specifies a model ID that the provider rejects
    * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
    */
   async evaluate(text, grade) {
@@ -1912,7 +2031,7 @@ var SmkEvaluator = class _SmkEvaluator extends BaseEvaluator {
       const response = await this.evaluateSmk(text, grade, fkScore);
       stageDetails.push({
         stage: "smk_evaluation",
-        provider: "google:gemini-3-flash-preview",
+        provider: this.provider.label,
         latency_ms: response.latencyMs,
         token_usage: {
           input_tokens: response.usage.inputTokens,
@@ -1928,8 +2047,10 @@ var SmkEvaluator = class _SmkEvaluator extends BaseEvaluator {
         score: response.data.complexity_score,
         reasoning: response.data.reasoning,
         metadata: {
-          model: "google:gemini-3-flash-preview",
-          processingTimeMs: latencyMs
+          model: this.provider.label,
+          processingTimeMs: latencyMs,
+          inputTokens: totalTokenUsage.input_tokens,
+          outputTokens: totalTokenUsage.output_tokens
         },
         _internal: response.data
       };
@@ -1938,7 +2059,7 @@ var SmkEvaluator = class _SmkEvaluator extends BaseEvaluator {
         latencyMs,
         textLength: text.length,
         grade,
-        provider: "google:gemini-3-flash-preview",
+        provider: this.provider.label,
         tokenUsage: totalTokenUsage,
         metadata: {
           stage_details: stageDetails
@@ -1973,7 +2094,7 @@ var SmkEvaluator = class _SmkEvaluator extends BaseEvaluator {
         latencyMs,
         textLength: text.length,
         grade,
-        provider: "google:gemini-3-flash-preview",
+        provider: this.provider.label,
         tokenUsage: totalTokenUsage,
         errorCode: error instanceof Error ? error.name : "UnknownError",
         metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
@@ -2077,18 +2198,16 @@ var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvalu
     name: "Conventionality",
     description: "Evaluates how explicit, literal, and straightforward a text's meaning is relative to grade level",
     supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
-    requiresGoogleKey: true,
-    requiresOpenAIKey: false
+    defaultProviders: ["google" /* Google */]
   };
   provider;
   constructor(config) {
     super(config);
-    this.provider = createProvider({
-      type: "google",
-      model: "gemini-3-flash-preview",
-      apiKey: config.googleApiKey,
-      maxRetries: this.config.maxRetries
-    });
+    this.provider = this.createConfiguredProvider(
+      "google" /* Google */,
+      "gemini-3-flash-preview",
+      config.googleApiKey
+    );
   }
   /**
    * Evaluate conventionality complexity for a given text and grade level
@@ -2097,6 +2216,7 @@ var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvalu
    * @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 {ConfigurationError} If modelOverride specifies a model ID that the provider rejects
    * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
    */
   async evaluate(text, grade) {
@@ -2119,7 +2239,7 @@ var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvalu
       const response = await this.evaluateConventionality(text, grade, fkScore);
       stageDetails.push({
         stage: "conventionality_evaluation",
-        provider: "google:gemini-3-flash-preview",
+        provider: this.provider.label,
         latency_ms: response.latencyMs,
         token_usage: {
           input_tokens: response.usage.inputTokens,
@@ -2135,8 +2255,10 @@ var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvalu
         score: response.data.complexity_score,
         reasoning: response.data.reasoning,
         metadata: {
-          model: "google:gemini-3-flash-preview",
-          processingTimeMs: latencyMs
+          model: this.provider.label,
+          processingTimeMs: latencyMs,
+          inputTokens: totalTokenUsage.input_tokens,
+          outputTokens: totalTokenUsage.output_tokens
         },
         _internal: response.data
       };
@@ -2145,7 +2267,7 @@ var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvalu
         latencyMs,
         textLength: text.length,
         grade,
-        provider: "google:gemini-3-flash-preview",
+        provider: this.provider.label,
         tokenUsage: totalTokenUsage,
         metadata: {
           stage_details: stageDetails
@@ -2180,7 +2302,7 @@ var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvalu
         latencyMs,
         textLength: text.length,
         grade,
-        provider: "google:gemini-3-flash-preview",
+        provider: this.provider.label,
         tokenUsage: totalTokenUsage,
         errorCode: error instanceof Error ? error.name : "UnknownError",
         metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
@@ -2212,6 +2334,278 @@ var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvalu
     };
   }
 };
+var PurposeOutputSchema = zod.z.object({ "complexity_score": zod.z.enum(["slightly_complex", "moderately_complex", "very_complex", "exceedingly_complex", "more_context_needed"]).describe("The Purpose complexity level for the target grade."), "reasoning": zod.z.string().describe("A high-level summary of why the text is at this complexity level for the target grade."), "details": zod.z.object({ "detailed_summary": zod.z.array(zod.z.object({ "factor": zod.z.string().describe("The specific text complexity factor identified."), "description": zod.z.string().describe("How this factor manifests in the text."), "effect_on_complexity_dimension": zod.z.string().describe("How this factor affects the reader's ability to understand the text's specific complexity dimension.") }).strict()).describe("Individual complexity factors with descriptions and their effects."), "adjustment_and_scaffolding": zod.z.array(zod.z.object({ "scaffolding_need": zod.z.string().describe("The complexity factor that requires scaffolding."), "suggestion": zod.z.string().describe("A specific instructional strategy to support students with this factor.") }).strict()).describe("Scaffolding strategies to make the text accessible at the target grade."), "recommended_use_cases": zod.z.array(zod.z.object({ "opportunity": zod.z.string().describe("An instructional opportunity related to the text."), "suggestion": zod.z.string().describe("A specific way to leverage this text for that instructional purpose.") }).strict()).describe("Additional instructional opportunities for using this text.") }).strict().describe("Practical instructional details including scaffolding strategies and recommended use cases.") }).strict();
+
+// ../../evals/prompts/purpose/system.txt
+var system_default4 = '\n    Role\n    You are an expert reading assessment evaluator. Your task is to determine the Text Complexity of a given passage based exclusively on the Purpose dimension of the qualitative measures rubric.\n\n    Task Details\n    You will be provided with an informational or literary `text`, along with its `grade_level` and `fk_score` (Flesch-Kincaid). You must analyze the text and determine how difficult it is for a reader to identify the author\'s purpose. \n\n    Crucially, you must distinguish between the text\'s *topic* (what it is about) and its *purpose* (why the author wrote it). \n\n    Rubric: Purpose Complexity\n    Exceedingly Complex: Subtle and intricate, difficult to determine; includes many theoretical or abstract elements.\n    Very Complex: Implicit or subtle but fairly easy to infer; more theoretical or abstract than concrete.\n    Moderately Complex: Implied but easy to identify based upon context or source.\n    Slightly Complex: Explicitly stated, clear, concrete, narrowly focused.\n    More Context Needed: The text is a fragment or lacks necessary introductory context, making the true purpose impossible to determine accurately without external background knowledge.\n\n    Expert Rules for Evaluating Purpose\n    Based on expert consensus and historical grading corrections, you must apply the following heuristics:\n\n    1. The "Slightly Complex" Benchmark (Straightforward and Explicit)\n    A text is Slightly Complex if its purpose is explicitly stated or if its informative intent is straightforward, clear, concrete, and directly answers what the text is immediately about. If the text opens by clearly identifying a concrete topic (e.g., "Pins are made of either brass or iron wire") and rigidly follows through by explaining factual, practical information or a process (like manufacturing steps or geographic facts), the purpose is considered explicit and straightforward. It does *not* require a literal statement like "The purpose of this text is to..." as long as the delivery of information is direct, clear, and unadorned by persuasive elements or complex framing.\n\n    2. Moderately Complex via Guiding Questions & Inquiry Formats\n    If a text begins with a general introduction and uses guiding questions (e.g., "Have you ever wondered how clouds are formed?") to transition into an explanation, the purpose is implied rather than explicitly stated upfront. Because the reader must recognize the question as the pivot point for the author\'s intent, it is Moderately Complex.\n\n    3. Moderately Complex via Multiple Distinct Informational Goals\n    If a text covers a broad topic but jumps between several distinct scientific or informational objectives without an overarching framing device or explicit thesis (e.g., talking about measuring ice sheets, then mapping, then finding meteorites), the reader must synthesize these diverse facts to recognize the broader purpose, making it Moderately Complex.\n\n    4. Moderately Complex via Arguments Disguised as Information\n    If an author is arguing a specific point, correcting a misconception, or defending a stance, but the text could initially be mistaken by students as purely informative factual text, it is Moderately Complex. The reader must infer the persuasive intent or argumentative purpose beneath the informative tone.\n\n    5. "More Context Needed" for Fragments\n    If a text is a fragment missing a crucial introduction or context, and identifying the author\'s purpose beyond a simple surface-level description would be exceptionally difficult for a reader in the target grade level without that external background, score it as `more_context_needed`. \n\n    Output Format\n    Provide your evaluation in the following structure:\n    reasoning:\n    - Surface Analysis: Identify if the text clearly identifies its topic and delivers straightforward facts, or if it utilizes structural cues, titles, or direct thesis statements.\n    - Subtlety & Framing: Is the informative purpose straightforward and concrete? Does it use guiding questions? Is it an argument disguised as pure information? Are there multiple distinct informational goals requiring synthesis?\n    - Context Check: Is this text a fragment missing crucial context that obscures the deeper purpose for the target grade level?\n    - Rubric Alignment: Explain how the text aligns with the specific language of the rubric, explicitly referencing the expert rules above. Justify why it isn\'t one level simpler or more complex.\n\n    answer:\n    - complexity_score: (slightly_complex, moderately_complex, very_complex, exceedingly_complex, more_context_needed)\n    - reasoning: A brief summary of your final decision.\n    - details: Structured breakdown of PurposeDetails including detailed_summary, adjustment_and_scaffolding, and recommended_use_cases.\n';
+
+// ../../evals/prompts/purpose/user.txt
+var user_default4 = "Analyze:\nText: {text}\nGrade: {grade_level}\nFK Score: {fk_score}";
+
+// ../../evals/prompts/purpose/config.json
+var config_default = {
+  evaluator: {
+    id: "literacy.gla.purpose",
+    name: "Purpose Dimension Text Complexity Evaluator",
+    description: "Evaluates the Purpose dimension of qualitative text complexity for K-12 reading assessment, producing a 5-level rubric rating with structured pedagogical detail."
+  },
+  preprocessing: [
+    {
+      id: "fk_score",
+      kind: "flesch_kincaid_grade",
+      description: "Compute the Flesch-Kincaid Grade Level for the input text and bind it to {fk_score} in the prompt.",
+      input: "text",
+      output: "fk_score",
+      implementation: {
+        python: {
+          library: "textstat",
+          function: "flesch_kincaid_grade",
+          post_transform: {
+            type: "round",
+            precision: 2
+          }
+        },
+        typescript: {
+          library: "text-readability",
+          function: "fleschKincaidGrade",
+          post_transform: {
+            type: "round",
+            precision: 2
+          }
+        }
+      }
+    }
+  ],
+  steps: [
+    {
+      id: "evaluate_purpose",
+      description: "Single-call LLM step that produces the EvaluatorOutput JSON.",
+      prompt: {
+        type: "chat",
+        messages: [
+          {
+            role: "system",
+            source_path: "system.txt",
+            sha256: "745b95b7d54dc845b99363c9d3360355381883c22a5f6a0f305d7349cae38a54"
+          },
+          {
+            role: "user",
+            source_path: "user.txt",
+            sha256: "cd8e6347db1a55d104e34436f8f66e833bd6583645d4786a554aaefdd26479b2"
+          }
+        ],
+        placeholders: {
+          text: {
+            required: true,
+            source: "input"
+          },
+          grade_level: {
+            required: true,
+            source: "input"
+          },
+          fk_score: {
+            required: true,
+            source: "preprocessing.fk_score"
+          }
+        }
+      },
+      model: {
+        provider: "google",
+        name: "gemini-3-flash-preview"
+      },
+      generation: {
+        temperature: 0
+      },
+      parser: {
+        kind: "structured_output"
+      },
+      output_binding: "formatted_output"
+    }
+  ]};
+
+// src/prompts/purpose/index.ts
+var STEP_ID = `evaluate_${config_default.evaluator.id.split(".").pop()}`;
+var _step = config_default.steps.find((s) => s.id === STEP_ID);
+if (!_step) throw new Error(`Step "${STEP_ID}" not found in purpose config.json`);
+var PLACEHOLDER_KEYS = Object.keys(_step.prompt.placeholders);
+function applyPlaceholders(template, inputs) {
+  return PLACEHOLDER_KEYS.reduce(
+    (text, key) => key in inputs ? text.replaceAll(`{${key}}`, inputs[key]) : text,
+    template
+  );
+}
+function getSystemPrompt5(inputs) {
+  return applyPlaceholders(system_default4, inputs);
+}
+function getUserPrompt5(inputs) {
+  return applyPlaceholders(user_default4, inputs);
+}
+
+// ../../evals/prompts/purpose/input_schema.json
+var input_schema_default = {
+  properties: {
+    grade_level: {
+      minimum: 3,
+      maximum: 12}
+  }
+};
+
+// src/evaluators/purpose.ts
+var STEP_ID2 = `evaluate_${config_default.evaluator.id.split(".").pop()}`;
+var _step2 = config_default.steps.find((s) => s.id === STEP_ID2);
+if (!_step2) throw new Error(`Step "${STEP_ID2}" not found in purpose config.json`);
+var STEP = _step2;
+var GRADE_MIN = input_schema_default.properties.grade_level.minimum;
+var GRADE_MAX = input_schema_default.properties.grade_level.maximum;
+var SUPPORTED_GRADES = Array.from({ length: GRADE_MAX - GRADE_MIN + 1 }, (_, i) => String(GRADE_MIN + i));
+var COMPLEXITY_SCORE_DISPLAY = {
+  "slightly_complex": "Slightly complex",
+  "moderately_complex": "Moderately complex",
+  "very_complex": "Very complex",
+  "exceedingly_complex": "Exceedingly complex",
+  "more_context_needed": "More context needed"
+};
+var PurposeEvaluator = class _PurposeEvaluator extends BaseEvaluator {
+  static metadata = {
+    id: config_default.evaluator.id,
+    name: config_default.evaluator.name,
+    description: config_default.evaluator.description,
+    supportedGrades: SUPPORTED_GRADES,
+    defaultProviders: ["google" /* Google */]
+  };
+  static TEMPERATURE = STEP.generation.temperature;
+  static computeFkScore(text) {
+    const fkStep = config_default.preprocessing.find((p) => p.id === "fk_score");
+    if (!fkStep) throw new Error("fk_score preprocessing step not found in purpose config.json");
+    return runPreprocessingStep(text, fkStep.implementation.typescript);
+  }
+  provider;
+  constructor(config) {
+    super(config);
+    this.provider = this.createConfiguredProvider(
+      "google" /* Google */,
+      STEP.model.name,
+      config.googleApiKey
+    );
+  }
+  /**
+   * Evaluate purpose 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 {ConfigurationError} If modelOverride specifies a model ID that the provider rejects
+   * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+   */
+  async evaluate(text, grade) {
+    this.logger.info("Starting Purpose evaluation", {
+      evaluator: _PurposeEvaluator.metadata.id,
+      operation: "evaluate",
+      grade,
+      textLength: text.length
+    });
+    const startTime = Date.now();
+    const stageDetails = [];
+    try {
+      this.validateText(text);
+      const gradeNum = this.parseAndValidateGrade(grade);
+      const fkScore = _PurposeEvaluator.computeFkScore(text);
+      const inputs = {
+        text,
+        grade_level: String(gradeNum),
+        fk_score: String(fkScore)
+      };
+      const response = await this.callLLM(inputs);
+      const latencyMs = Date.now() - startTime;
+      const tokenUsage = {
+        input_tokens: response.usage.inputTokens,
+        output_tokens: response.usage.outputTokens
+      };
+      stageDetails.push({
+        stage: STEP.id,
+        provider: this.provider.label,
+        latency_ms: response.latencyMs,
+        token_usage: tokenUsage
+      });
+      const result = {
+        score: COMPLEXITY_SCORE_DISPLAY[response.data.complexity_score],
+        reasoning: response.data.reasoning,
+        metadata: {
+          model: this.provider.label,
+          processingTimeMs: latencyMs,
+          inputTokens: tokenUsage.input_tokens,
+          outputTokens: tokenUsage.output_tokens
+        },
+        _internal: response.data
+      };
+      this.sendTelemetry({
+        status: "success",
+        latencyMs,
+        textLength: text.length,
+        grade: String(gradeNum),
+        provider: this.provider.label,
+        tokenUsage,
+        metadata: { stage_details: stageDetails },
+        inputText: text
+      }).catch(() => void 0);
+      this.logger.info("Purpose evaluation completed successfully", {
+        evaluator: _PurposeEvaluator.metadata.id,
+        operation: "evaluate",
+        grade: gradeNum,
+        score: result.score,
+        processingTimeMs: latencyMs
+      });
+      return result;
+    } catch (error) {
+      const latencyMs = Date.now() - startTime;
+      this.logger.error("Purpose evaluation failed", {
+        evaluator: _PurposeEvaluator.metadata.id,
+        operation: "evaluate",
+        grade,
+        error: error instanceof Error ? error : void 0,
+        processingTimeMs: latencyMs
+      });
+      const tokenUsage = stageDetails.length > 0 ? {
+        input_tokens: stageDetails.reduce((s, d) => s + (d.token_usage?.input_tokens ?? 0), 0),
+        output_tokens: stageDetails.reduce((s, d) => s + (d.token_usage?.output_tokens ?? 0), 0)
+      } : void 0;
+      this.sendTelemetry({
+        status: "error",
+        latencyMs,
+        textLength: text.length,
+        grade: String(grade),
+        provider: this.provider.label,
+        tokenUsage,
+        errorCode: error instanceof Error ? error.name : "UnknownError",
+        metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
+        inputText: text
+      }).catch(() => void 0);
+      if (error instanceof ValidationError) throw error;
+      throw wrapProviderError(error, "Purpose evaluation failed");
+    }
+  }
+  parseAndValidateGrade(grade) {
+    const num = Number(grade.trim());
+    if (!Number.isInteger(num) || num < GRADE_MIN || num > GRADE_MAX) {
+      throw new ValidationError(
+        `Invalid grade "${grade}". Purpose evaluator supports integer grades ${GRADE_MIN}\u2013${GRADE_MAX}.`
+      );
+    }
+    return num;
+  }
+  async callLLM(inputs) {
+    const response = await this.provider.generateStructured({
+      messages: [
+        { role: "system", content: getSystemPrompt5(inputs) },
+        { role: "user", content: getUserPrompt5(inputs) }
+      ],
+      schema: PurposeOutputSchema,
+      temperature: _PurposeEvaluator.TEMPERATURE
+    });
+    return { data: response.data, usage: response.usage, latencyMs: response.latencyMs };
+  }
+};
 
 // src/batch/evaluator.ts
 var EVALUATOR_MAP = /* @__PURE__ */ new Map([
@@ -2219,19 +2613,21 @@ var EVALUATOR_MAP = /* @__PURE__ */ new Map([
   [SmkEvaluator.metadata.id, SmkEvaluator],
   [VocabularyEvaluator.metadata.id, VocabularyEvaluator],
   [SentenceStructureEvaluator.metadata.id, SentenceStructureEvaluator],
-  [ConventionalityEvaluator.metadata.id, ConventionalityEvaluator]
+  [ConventionalityEvaluator.metadata.id, ConventionalityEvaluator],
+  [PurposeEvaluator.metadata.id, PurposeEvaluator]
 ]);
 var EVALUATOR_GROUPS = [
   {
     id: "text-complexity",
     name: "Text Complexity Analysis",
-    description: "Evaluates vocabulary complexity, sentence structure, subject matter knowledge, conventionality, and grade-level appropriateness",
+    description: "Evaluates all dimensions of the Qualitative Text Complexity rubric",
     evaluatorIds: [
       GradeLevelAppropriatenessEvaluator.metadata.id,
       SmkEvaluator.metadata.id,
       VocabularyEvaluator.metadata.id,
       SentenceStructureEvaluator.metadata.id,
-      ConventionalityEvaluator.metadata.id
+      ConventionalityEvaluator.metadata.id,
+      PurposeEvaluator.metadata.id
     ],
     requiresGoogleKey: true,
     requiresOpenAIKey: true,
@@ -2252,6 +2648,7 @@ var BatchEvaluator = class {
       concurrency: 3,
       maxRetries: 2,
       telemetry: false,
+      bypassRowLimit: false,
       ...config
     };
     this.limit = pLimit__default.default(this.config.concurrency);
@@ -2405,9 +2802,9 @@ var BatchEvaluator = class {
         `Unknown evaluator group: "${groupId}". Available: ${EVALUATOR_GROUPS.map((g) => g.id).join(", ")}`
       );
     }
-    if (inputs.length > group.maxInputRows) {
+    if (!this.config.bypassRowLimit && inputs.length > group.maxInputRows) {
       throw new Error(
-        `Input exceeds limit for "${group.id}": ${inputs.length} rows (max ${group.maxInputRows}). Split into smaller batches.`
+        `Input exceeds limit for "${group.id}": ${inputs.length} rows (max ${group.maxInputRows}). Split into smaller batches, or pass { bypassRowLimit: true } in BatchConfig to bypass (use --bypass-row-limit on the CLI).`
       );
     }
     this.isCancelled = false;
@@ -3322,6 +3719,8 @@ var COMPLEXITY_SCORE_MAP = {
   "moderately complex": 2,
   "very complex": 3,
   "exceedingly complex": 4
+  // 'more context needed' has no numeric equivalent — rows with this score appear as N/A
+  // in individual results and are excluded from aggregate stats, same as failed evaluations.
 };
 function evaluatorDisplayName(id) {
   return id.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
@@ -3376,7 +3775,8 @@ function groupResultsByRow(results) {
   return grouped;
 }
 function formatEvaluatorPrefix(evaluatorId) {
-  return evaluatorId.replace(/-/g, "_");
+  const slug = evaluatorId.includes(".") ? evaluatorId.split(".").pop() : evaluatorId;
+  return slug.replace(/-/g, "_");
 }
 function escapeCSV(field) {
   if (field.includes(",") || field.includes('"') || field.includes("\n")) {