@learning-commons/evaluators 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -580,6 +580,30 @@ declare const SmkOutputSchema: z.ZodObject<{
 }>;
 type SmkInternal = z.infer<typeof SmkOutputSchema>;
 
+/**
+ * Conventionality evaluation output schema
+ */
+declare const ConventionalityOutputSchema: z.ZodObject<{
+    conventionality_features: z.ZodArray<z.ZodString, "many">;
+    grade_context: z.ZodString;
+    instructional_insights: z.ZodString;
+    complexity_score: z.ZodEnum<["Slightly complex", "Moderately complex", "Very complex", "Exceedingly complex"]>;
+    reasoning: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reasoning: string;
+    complexity_score: "Slightly complex" | "Moderately complex" | "Very complex" | "Exceedingly complex";
+    conventionality_features: string[];
+    grade_context: string;
+    instructional_insights: string;
+}, {
+    reasoning: string;
+    complexity_score: "Slightly complex" | "Moderately complex" | "Very complex" | "Exceedingly complex";
+    conventionality_features: string[];
+    grade_context: string;
+    instructional_insights: string;
+}>;
+type ConventionalityInternal = z.infer<typeof ConventionalityOutputSchema>;
+
 /**
  * Evaluation status
  */
@@ -1114,6 +1138,69 @@ declare class SmkEvaluator extends BaseEvaluator {
  */
 declare function evaluateSmk(text: string, grade: string, config: BaseEvaluatorConfig): Promise<EvaluationResult<TextComplexityLevel, SmkInternal>>;
 
+/**
+ * Conventionality Evaluator
+ *
+ * Evaluates how explicit, literal, and straightforward a text's meaning is versus
+ * how abstract, ironic, figurative, or archaic it is for the target grade level.
+ *
+ * Based on the Common Core Qualitative Text Complexity Rubric with 4 levels:
+ * - Slightly complex
+ * - Moderately complex
+ * - Very complex
+ * - Exceedingly complex
+ *
+ * @example
+ * ```typescript
+ * const evaluator = new ConventionalityEvaluator({
+ *   googleApiKey: process.env.GOOGLE_API_KEY
+ * });
+ *
+ * const result = await evaluator.evaluate(text, "6");
+ * console.log(result.score); // "Moderately complex"
+ * console.log(result.reasoning);
+ * ```
+ */
+declare class ConventionalityEvaluator extends BaseEvaluator {
+    static readonly metadata: {
+        id: string;
+        name: string;
+        description: string;
+        supportedGrades: readonly ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
+        requiresGoogleKey: boolean;
+        requiresOpenAIKey: boolean;
+    };
+    private provider;
+    constructor(config: BaseEvaluatorConfig);
+    /**
+     * Evaluate conventionality complexity for a given text and grade level
+     *
+     * @param text - The text to evaluate
+     * @param grade - The target grade level (3-12)
+     * @returns Evaluation result with complexity score and detailed analysis
+     * @throws {ValidationError} If text is empty, too short/long, or grade is invalid
+     * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+     */
+    evaluate(text: string, grade: string): Promise<EvaluationResult<TextComplexityLevel, ConventionalityInternal>>;
+    /**
+     * Run the Conventionality evaluation LLM call
+     */
+    private evaluateConventionality;
+}
+/**
+ * Functional API for Conventionality evaluation
+ *
+ * @example
+ * ```typescript
+ * const result = await evaluateConventionality(
+ *   "The author uses sustained irony to critique societal norms.",
+ *   "10",
+ *   { googleApiKey: process.env.GOOGLE_API_KEY }
+ * );
+ * ```
+ */
+declare function evaluateConventionality(text: string, grade: string, config: BaseEvaluatorConfig): Promise<EvaluationResult<TextComplexityLevel, ConventionalityInternal>>;
+
 /**
  * Result map returned by TextComplexityEvaluator.
  * Each key holds the full evaluation result from its sub-evaluator, or an error if it failed.
@@ -1128,17 +1215,21 @@ interface TextComplexityResult {
     subjectMatterKnowledge: EvaluationResult<TextComplexityLevel, SmkInternal> | {
         error: Error;
     };
+    conventionality: EvaluationResult<TextComplexityLevel, ConventionalityInternal> | {
+        error: Error;
+    };
 }
 /**
  * Text Complexity Evaluator
  *
- * Composite evaluator that analyzes vocabulary, sentence structure, and subject matter knowledge.
+ * Composite evaluator that analyzes vocabulary, sentence structure, subject matter knowledge, and conventionality.
  * Runs all evaluations in parallel with concurrency control to avoid rate limiting.
  *
  * Uses:
  * - VocabularyEvaluator (Google Gemini 2.5 Pro + OpenAI GPT-4o)
  * - SentenceStructureEvaluator (OpenAI GPT-4o)
  * - SmkEvaluator (Google Gemini 3 Flash Preview)
+ * - ConventionalityEvaluator (Google Gemini 3 Flash Preview)
  *
  * @example
  * ```typescript
@@ -1165,6 +1256,7 @@ declare class TextComplexityEvaluator extends BaseEvaluator {
     private vocabularyEvaluator;
     private sentenceStructureEvaluator;
     private smkEvaluator;
+    private conventionalityEvaluator;
     private limit;
     constructor(config: BaseEvaluatorConfig);
     /**
@@ -1234,4 +1326,4 @@ declare function addEngineeredFeatures(analysis: SentenceAnalysis): SentenceFeat
  */
 declare function featuresToJSON(features: SentenceFeatures, decimals?: number, castToInt?: boolean): string;
 
-export { APIError, AuthenticationError, type BaseEvaluatorConfig, type ComplexityClassification, ComplexityClassificationSchema, ConfigurationError, type EvaluationError, type EvaluationMetadata, type EvaluationResult, EvaluatorError, type EvaluatorMetadata, GradeBand, GradeLevelAppropriatenessEvaluator, type GradeLevelAppropriatenessInternal, GradeLevelAppropriatenessSchema, type LLMProvider, type LLMRequest, type LLMResponse, type LogContext, LogLevel, type Logger, type Message, NetworkError, type ProviderConfig, RateLimitError, type ReadabilityMetrics, type SentenceAnalysis, SentenceAnalysisSchema, type SentenceFeatures, SentenceStructureEvaluator, type SentenceStructureInternal, SmkEvaluator, type SmkInternal, type TelemetryOptions, TextComplexityEvaluator, TextComplexityLevel, type TextComplexityResult, type TextGenerationResponse, TimeoutError, ValidationError, VocabularyEvaluator, type VocabularyInternal, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateGradeLevelAppropriateness, evaluateSentenceStructure, evaluateSmk, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };
+export { APIError, AuthenticationError, type BaseEvaluatorConfig, type ComplexityClassification, ComplexityClassificationSchema, ConfigurationError, ConventionalityEvaluator, type ConventionalityInternal, type EvaluationError, type EvaluationMetadata, type EvaluationResult, EvaluatorError, type EvaluatorMetadata, GradeBand, GradeLevelAppropriatenessEvaluator, type GradeLevelAppropriatenessInternal, GradeLevelAppropriatenessSchema, type LLMProvider, type LLMRequest, type LLMResponse, type LogContext, LogLevel, type Logger, type Message, NetworkError, type ProviderConfig, RateLimitError, type ReadabilityMetrics, type SentenceAnalysis, SentenceAnalysisSchema, type SentenceFeatures, SentenceStructureEvaluator, type SentenceStructureInternal, SmkEvaluator, type SmkInternal, type TelemetryOptions, TextComplexityEvaluator, TextComplexityLevel, type TextComplexityResult, type TextGenerationResponse, TimeoutError, ValidationError, VocabularyEvaluator, type VocabularyInternal, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateConventionality, evaluateGradeLevelAppropriateness, evaluateSentenceStructure, evaluateSmk, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };

package/dist/index.d.ts

@@ -580,6 +580,30 @@ declare const SmkOutputSchema: z.ZodObject<{
 }>;
 type SmkInternal = z.infer<typeof SmkOutputSchema>;
 
+/**
+ * Conventionality evaluation output schema
+ */
+declare const ConventionalityOutputSchema: z.ZodObject<{
+    conventionality_features: z.ZodArray<z.ZodString, "many">;
+    grade_context: z.ZodString;
+    instructional_insights: z.ZodString;
+    complexity_score: z.ZodEnum<["Slightly complex", "Moderately complex", "Very complex", "Exceedingly complex"]>;
+    reasoning: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reasoning: string;
+    complexity_score: "Slightly complex" | "Moderately complex" | "Very complex" | "Exceedingly complex";
+    conventionality_features: string[];
+    grade_context: string;
+    instructional_insights: string;
+}, {
+    reasoning: string;
+    complexity_score: "Slightly complex" | "Moderately complex" | "Very complex" | "Exceedingly complex";
+    conventionality_features: string[];
+    grade_context: string;
+    instructional_insights: string;
+}>;
+type ConventionalityInternal = z.infer<typeof ConventionalityOutputSchema>;
+
 /**
  * Evaluation status
  */
@@ -1114,6 +1138,69 @@ declare class SmkEvaluator extends BaseEvaluator {
  */
 declare function evaluateSmk(text: string, grade: string, config: BaseEvaluatorConfig): Promise<EvaluationResult<TextComplexityLevel, SmkInternal>>;
 
+/**
+ * Conventionality Evaluator
+ *
+ * Evaluates how explicit, literal, and straightforward a text's meaning is versus
+ * how abstract, ironic, figurative, or archaic it is for the target grade level.
+ *
+ * Based on the Common Core Qualitative Text Complexity Rubric with 4 levels:
+ * - Slightly complex
+ * - Moderately complex
+ * - Very complex
+ * - Exceedingly complex
+ *
+ * @example
+ * ```typescript
+ * const evaluator = new ConventionalityEvaluator({
+ *   googleApiKey: process.env.GOOGLE_API_KEY
+ * });
+ *
+ * const result = await evaluator.evaluate(text, "6");
+ * console.log(result.score); // "Moderately complex"
+ * console.log(result.reasoning);
+ * ```
+ */
+declare class ConventionalityEvaluator extends BaseEvaluator {
+    static readonly metadata: {
+        id: string;
+        name: string;
+        description: string;
+        supportedGrades: readonly ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
+        requiresGoogleKey: boolean;
+        requiresOpenAIKey: boolean;
+    };
+    private provider;
+    constructor(config: BaseEvaluatorConfig);
+    /**
+     * Evaluate conventionality complexity for a given text and grade level
+     *
+     * @param text - The text to evaluate
+     * @param grade - The target grade level (3-12)
+     * @returns Evaluation result with complexity score and detailed analysis
+     * @throws {ValidationError} If text is empty, too short/long, or grade is invalid
+     * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+     */
+    evaluate(text: string, grade: string): Promise<EvaluationResult<TextComplexityLevel, ConventionalityInternal>>;
+    /**
+     * Run the Conventionality evaluation LLM call
+     */
+    private evaluateConventionality;
+}
+/**
+ * Functional API for Conventionality evaluation
+ *
+ * @example
+ * ```typescript
+ * const result = await evaluateConventionality(
+ *   "The author uses sustained irony to critique societal norms.",
+ *   "10",
+ *   { googleApiKey: process.env.GOOGLE_API_KEY }
+ * );
+ * ```
+ */
+declare function evaluateConventionality(text: string, grade: string, config: BaseEvaluatorConfig): Promise<EvaluationResult<TextComplexityLevel, ConventionalityInternal>>;
+
 /**
  * Result map returned by TextComplexityEvaluator.
  * Each key holds the full evaluation result from its sub-evaluator, or an error if it failed.
@@ -1128,17 +1215,21 @@ interface TextComplexityResult {
     subjectMatterKnowledge: EvaluationResult<TextComplexityLevel, SmkInternal> | {
         error: Error;
     };
+    conventionality: EvaluationResult<TextComplexityLevel, ConventionalityInternal> | {
+        error: Error;
+    };
 }
 /**
  * Text Complexity Evaluator
  *
- * Composite evaluator that analyzes vocabulary, sentence structure, and subject matter knowledge.
+ * Composite evaluator that analyzes vocabulary, sentence structure, subject matter knowledge, and conventionality.
  * Runs all evaluations in parallel with concurrency control to avoid rate limiting.
  *
  * Uses:
  * - VocabularyEvaluator (Google Gemini 2.5 Pro + OpenAI GPT-4o)
  * - SentenceStructureEvaluator (OpenAI GPT-4o)
  * - SmkEvaluator (Google Gemini 3 Flash Preview)
+ * - ConventionalityEvaluator (Google Gemini 3 Flash Preview)
  *
  * @example
  * ```typescript
@@ -1165,6 +1256,7 @@ declare class TextComplexityEvaluator extends BaseEvaluator {
     private vocabularyEvaluator;
     private sentenceStructureEvaluator;
     private smkEvaluator;
+    private conventionalityEvaluator;
     private limit;
     constructor(config: BaseEvaluatorConfig);
     /**
@@ -1234,4 +1326,4 @@ declare function addEngineeredFeatures(analysis: SentenceAnalysis): SentenceFeat
  */
 declare function featuresToJSON(features: SentenceFeatures, decimals?: number, castToInt?: boolean): string;
 
-export { APIError, AuthenticationError, type BaseEvaluatorConfig, type ComplexityClassification, ComplexityClassificationSchema, ConfigurationError, type EvaluationError, type EvaluationMetadata, type EvaluationResult, EvaluatorError, type EvaluatorMetadata, GradeBand, GradeLevelAppropriatenessEvaluator, type GradeLevelAppropriatenessInternal, GradeLevelAppropriatenessSchema, type LLMProvider, type LLMRequest, type LLMResponse, type LogContext, LogLevel, type Logger, type Message, NetworkError, type ProviderConfig, RateLimitError, type ReadabilityMetrics, type SentenceAnalysis, SentenceAnalysisSchema, type SentenceFeatures, SentenceStructureEvaluator, type SentenceStructureInternal, SmkEvaluator, type SmkInternal, type TelemetryOptions, TextComplexityEvaluator, TextComplexityLevel, type TextComplexityResult, type TextGenerationResponse, TimeoutError, ValidationError, VocabularyEvaluator, type VocabularyInternal, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateGradeLevelAppropriateness, evaluateSentenceStructure, evaluateSmk, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };
+export { APIError, AuthenticationError, type BaseEvaluatorConfig, type ComplexityClassification, ComplexityClassificationSchema, ConfigurationError, ConventionalityEvaluator, type ConventionalityInternal, type EvaluationError, type EvaluationMetadata, type EvaluationResult, EvaluatorError, type EvaluatorMetadata, GradeBand, GradeLevelAppropriatenessEvaluator, type GradeLevelAppropriatenessInternal, GradeLevelAppropriatenessSchema, type LLMProvider, type LLMRequest, type LLMResponse, type LogContext, LogLevel, type Logger, type Message, NetworkError, type ProviderConfig, RateLimitError, type ReadabilityMetrics, type SentenceAnalysis, SentenceAnalysisSchema, type SentenceFeatures, SentenceStructureEvaluator, type SentenceStructureInternal, SmkEvaluator, type SmkInternal, type TelemetryOptions, TextComplexityEvaluator, TextComplexityLevel, type TextComplexityResult, type TextGenerationResponse, TimeoutError, ValidationError, VocabularyEvaluator, type VocabularyInternal, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateConventionality, evaluateGradeLevelAppropriateness, evaluateSentenceStructure, evaluateSmk, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };

package/dist/index.js

@@ -1999,11 +1999,222 @@ async function evaluateSmk(text, grade, config) {
   const evaluator = new SmkEvaluator(config);
   return evaluator.evaluate(text, grade);
 }
+var ConventionalityOutputSchema = z.object({
+  conventionality_features: z.array(z.string()).describe("The specific language features driving the complexity (e.g., literal narrative, concrete actions, sustained irony, abstract qualities) with direct quotes from the text."),
+  grade_context: z.string().describe("How the conventionality demands compare to general expectations for the provided target grade."),
+  instructional_insights: z.string().describe("Actionable pedagogical suggestions for scaffolding the conventionality features in the classroom."),
+  complexity_score: TextComplexityLevel.describe("The conventionality complexity level of the text"),
+  reasoning: z.string().describe("A detailed explanation of the rating, citing specific features in the text and referencing the expert guardrails.")
+});
+
+// ../../evals/prompts/conventionality/system.txt
+var system_default3 = `Role
+You are an expert reading teacher and text complexity evaluator. Your task is to evaluate the "Conventionality" of a text and assign it a complexity level based on a 4-point scale, carefully factoring in the target grade level.
+
+Objective
+Measure how explicit, literal, and straightforward the text's meaning is, versus how abstract, ironic, figurative, or archaic it is. Focus on the hiddenness of the meaning, the use of conceptual framing, the reliance on abstract reasoning, and the familiarity of the expression for the target grade.
+
+Complexity Levels
+- Slightly Complex: Explicit, literal, straightforward, easy to understand. Meaning is entirely on the surface. The language is concrete, and the meaning is clear and procedural, mostly referring to observable materials and actions. Contains no symbolic or ironic language, and conceptual interpretation is not required. Contains limited figurative language that is common and easy to comprehend at the target grade level.
+- Moderately Complex: Largely explicit and easy to understand with some occasions for more complex meaning. May contain a noticeable amount of archaic/dated phrasing, formal historical prose, vocabulary demands, background knowledge requirements, or expressions that are less familiar to the target grade level, which might make the text feel vague or slightly challenging.
+- Very Complex: Fairly complex; contains sustained abstract language, conceptual framing, rhetorical idealization, ironic comparisons, or central metaphors that drive the meaning of the text. Addresses concepts, beliefs, and abstract qualities rather than just concrete objects. The tone or underlying message requires interpretation, even if the surface message is clear.
+- Exceedingly Complex: Dense and complex; contains considerable abstract, ironic, and/or figurative language. Meaning is heavily hidden, deeply conceptual, or relies heavily on complex rhetorical devices.
+
+Essential Evaluation Rules
+1. Concrete & Procedural Texts: Texts that are highly concrete, clear, and procedural (e.g., describing observable materials, mechanical processes, or physical actions) should typically be rated "Slightly Complex."
+
+2. Grade-Level Anchoring and Vague Narratives: Always consider the target grade. A literal historical narrative that might be straightforward for older students can be "Moderately Complex" for younger students (e.g., 4th graders) if it involves less familiar expressions, older contexts (e.g., wagon loads, traveling by horseback), vocabulary demands, and background knowledge requirements that make the text feel vague or slightly demanding for that age group.
+
+3. Rhetorical Idealization and Abstract Qualities: If an entire argument or narrative is built around abstract qualities (e.g., national character, bravery, liberty) and uses repeated figurative language or personification to portray a subject in a certain idealized way, rate the text as "Very Complex." Even if the figurative language is easy to interpret, the need to interpret the rhetorical tone and sustained abstract focus elevates the complexity beyond level two.
+
+4. Common Idioms and Grade-Level Appropriateness: Do NOT elevate a text to "Moderately Complex" simply because it contains a few common idiomatic expressions. If these expressions are widely known and easy for the target grade to understand without making the text feel vague, the text remains "Slightly Complex."
+
+5. Conversational and Hypothetical Framing: Using a second-person conversational hook (e.g., "Imagine you are...") to explain a concept is a standard, literal device for engaging readers. It does not constitute complex conceptual framing.
+
+6. Sustained vs. Occasional Impact: If abstract language, figurative phrasing, irony, or conceptual framing is sustained throughout the text and central to the argument/meaning, the text is Very Complex. Reserve Moderately Complex for texts where the explicit meaning dominates but the expression, vocabulary, or archaic language provides a moderate conventionality challenge.
+
+7. Central Metaphors and Conceptual Framing: When an author uses a central metaphor to explain a concept or uses figurative phrasing to explain how things "work," this abstract reasoning drives the meaning, elevating the text to Very Complex.
+
+8. Irony and Abstract Comparisons: Texts that rely on sustained irony, especially through comparative arguments, are inherently Very Complex for younger students.
+
+9. Isolate Conventionality from Vocabulary: Do not inflate the Conventionality score just because the text uses archaic, dated, or highly academic vocabulary. 
+
+Input Format
+You will receive:
+- text: The passage to evaluate.
+- grade_level: The target student grade level.
+- fk_score: The Flesch-Kincaid readability score.
+
+Output Format
+Provide a JSON object containing ONLY the following keys:
+- complexity_score: (String) One of the 4 scale levels exactly as formatted: 'slightly_complex', 'moderately_complex', 'very_complex', or 'exceedingly_complex'.
+- reasoning: (String) A detailed explanation of the rating, citing specific features in the text and referencing the expert guardrails (e.g., noting if the text relies on abstract qualities/rhetorical idealization, if vocabulary/background knowledge demands make a literal text vague for the grade level, or if it is strictly concrete/procedural).
+- conventionality_features: (List of Strings) The specific language features driving the complexity (e.g., literal narrative, concrete actions, less familiar expressions, sustained irony, abstract qualities, rhetorical idealization, archaic phrasing) with direct quotes from the text.
+- grade_context: (String) How the conventionality demands compare to general expectations for the provided target grade.
+- instructional_insights: (String) Actionable pedagogical suggestions for scaffolding the conventionality features in the classroom.`;
+
+// ../../evals/prompts/conventionality/user.txt
+var user_default3 = "Analyze:\nText: {text}\nGrade: {grade}\nFK Score: {fk_score}";
+
+// src/prompts/conventionality/index.ts
+function getSystemPrompt4() {
+  return system_default3;
+}
+function getUserPrompt4(text, grade, fkScore) {
+  return user_default3.replaceAll("{text}", text).replaceAll("{grade}", grade).replaceAll("{fk_score}", fkScore.toString());
+}
+
+// src/evaluators/conventionality.ts
+var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvaluator {
+  static metadata = {
+    id: "conventionality",
+    name: "Conventionality",
+    description: "Evaluates how explicit, literal, and straightforward a text's meaning is relative to grade level",
+    supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
+    requiresGoogleKey: true,
+    requiresOpenAIKey: false
+  };
+  provider;
+  constructor(config) {
+    super(config);
+    this.provider = createProvider({
+      type: "google",
+      model: "gemini-3-flash-preview",
+      apiKey: config.googleApiKey,
+      maxRetries: this.config.maxRetries
+    });
+  }
+  /**
+   * Evaluate conventionality complexity for a given text and grade level
+   *
+   * @param text - The text to evaluate
+   * @param grade - The target grade level (3-12)
+   * @returns Evaluation result with complexity score and detailed analysis
+   * @throws {ValidationError} If text is empty, too short/long, or grade is invalid
+   * @throws {APIError} If LLM API calls fail (includes AuthenticationError, RateLimitError, NetworkError, TimeoutError)
+   */
+  async evaluate(text, grade) {
+    this.logger.info("Starting Conventionality evaluation", {
+      evaluator: "conventionality",
+      operation: "evaluate",
+      grade,
+      textLength: text.length
+    });
+    const startTime = Date.now();
+    const stageDetails = [];
+    try {
+      this.validateText(text);
+      this.validateGrade(grade, new Set(_ConventionalityEvaluator.metadata.supportedGrades));
+      this.logger.debug("Evaluating conventionality complexity", {
+        evaluator: "conventionality",
+        operation: "conventionality_evaluation"
+      });
+      const fkScore = calculateFleschKincaidGrade(text);
+      const response = await this.evaluateConventionality(text, grade, fkScore);
+      stageDetails.push({
+        stage: "conventionality_evaluation",
+        provider: "google:gemini-3-flash-preview",
+        latency_ms: response.latencyMs,
+        token_usage: {
+          input_tokens: response.usage.inputTokens,
+          output_tokens: response.usage.outputTokens
+        }
+      });
+      const latencyMs = Date.now() - startTime;
+      const totalTokenUsage = {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      };
+      const result = {
+        score: response.data.complexity_score,
+        reasoning: response.data.reasoning,
+        metadata: {
+          model: "google:gemini-3-flash-preview",
+          processingTimeMs: latencyMs
+        },
+        _internal: response.data
+      };
+      this.sendTelemetry({
+        status: "success",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: "google:gemini-3-flash-preview",
+        tokenUsage: totalTokenUsage,
+        metadata: {
+          stage_details: stageDetails
+        },
+        inputText: text
+      }).catch(() => {
+      });
+      this.logger.info("Conventionality evaluation completed successfully", {
+        evaluator: "conventionality",
+        operation: "evaluate",
+        grade,
+        score: result.score,
+        processingTimeMs: latencyMs
+      });
+      return result;
+    } catch (error) {
+      const latencyMs = Date.now() - startTime;
+      this.logger.error("Conventionality evaluation failed", {
+        evaluator: "conventionality",
+        operation: "evaluate",
+        grade,
+        error: error instanceof Error ? error : void 0,
+        processingTimeMs: latencyMs,
+        completedStages: stageDetails.length
+      });
+      const totalTokenUsage = stageDetails.length > 0 ? {
+        input_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.input_tokens || 0), 0),
+        output_tokens: stageDetails.reduce((sum, s) => sum + (s.token_usage?.output_tokens || 0), 0)
+      } : void 0;
+      this.sendTelemetry({
+        status: "error",
+        latencyMs,
+        textLength: text.length,
+        grade,
+        provider: "google:gemini-3-flash-preview",
+        tokenUsage: totalTokenUsage,
+        errorCode: error instanceof Error ? error.name : "UnknownError",
+        metadata: stageDetails.length > 0 ? { stage_details: stageDetails } : void 0,
+        inputText: text
+      }).catch(() => {
+      });
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+      throw wrapProviderError(error, "Conventionality evaluation failed");
+    }
+  }
+  /**
+   * Run the Conventionality evaluation LLM call
+   */
+  async evaluateConventionality(text, grade, fkScore) {
+    const response = await this.provider.generateStructured({
+      messages: [
+        { role: "system", content: getSystemPrompt4() },
+        { role: "user", content: getUserPrompt4(text, grade, fkScore) }
+      ],
+      schema: ConventionalityOutputSchema,
+      temperature: 0
+    });
+    return {
+      data: response.data,
+      usage: response.usage,
+      latencyMs: response.latencyMs
+    };
+  }
+};
+async function evaluateConventionality(text, grade, config) {
+  const evaluator = new ConventionalityEvaluator(config);
+  return evaluator.evaluate(text, grade);
+}
 var TextComplexityEvaluator = class _TextComplexityEvaluator extends BaseEvaluator {
   static metadata = {
     id: "text-complexity",
     name: "Text Complexity",
-    description: "Composite evaluator analyzing vocabulary, sentence structure, and subject matter knowledge complexity",
+    description: "Composite evaluator analyzing vocabulary, sentence structure, subject matter knowledge, and conventionality complexity",
     supportedGrades: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
     requiresGoogleKey: true,
     requiresOpenAIKey: true
@@ -2011,12 +2222,14 @@ var TextComplexityEvaluator = class _TextComplexityEvaluator extends BaseEvaluat
   vocabularyEvaluator;
   sentenceStructureEvaluator;
   smkEvaluator;
+  conventionalityEvaluator;
   limit;
   constructor(config) {
     super(config);
     this.vocabularyEvaluator = new VocabularyEvaluator(config);
     this.sentenceStructureEvaluator = new SentenceStructureEvaluator(config);
     this.smkEvaluator = new SmkEvaluator(config);
+    this.conventionalityEvaluator = new ConventionalityEvaluator(config);
     this.limit = pLimit(3);
   }
   /**
@@ -2042,21 +2255,24 @@ var TextComplexityEvaluator = class _TextComplexityEvaluator extends BaseEvaluat
     this.validateText(text);
     this.validateGrade(grade, new Set(_TextComplexityEvaluator.metadata.supportedGrades));
     const startTime = Date.now();
-    const [vocabResult, sentenceResult, smkResult] = await Promise.all([
+    const [vocabResult, sentenceResult, smkResult, conventionalityResult] = await Promise.all([
       this.limit(() => this.runSubEvaluator(this.vocabularyEvaluator, text, grade)),
       this.limit(() => this.runSubEvaluator(this.sentenceStructureEvaluator, text, grade)),
-      this.limit(() => this.runSubEvaluator(this.smkEvaluator, text, grade))
+      this.limit(() => this.runSubEvaluator(this.smkEvaluator, text, grade)),
+      this.limit(() => this.runSubEvaluator(this.conventionalityEvaluator, text, grade))
     ]);
     const latencyMs = Date.now() - startTime;
     const vocabFailed = "error" in vocabResult;
     const sentenceFailed = "error" in sentenceResult;
     const smkFailed = "error" in smkResult;
-    const hasFailures = vocabFailed || sentenceFailed || smkFailed;
+    const conventionalityFailed = "error" in conventionalityResult;
+    const hasFailures = vocabFailed || sentenceFailed || smkFailed || conventionalityFailed;
     if (hasFailures) {
       const errors = [];
       if (vocabFailed) errors.push(`Vocabulary: ${vocabResult.error.message}`);
       if (sentenceFailed) errors.push(`Sentence structure: ${sentenceResult.error.message}`);
       if (smkFailed) errors.push(`Subject matter knowledge: ${smkResult.error.message}`);
+      if (conventionalityFailed) errors.push(`Conventionality: ${conventionalityResult.error.message}`);
       this.logger.error("Text complexity evaluation completed with errors", {
         evaluator: "text-complexity",
         operation: "evaluate",
@@ -2064,7 +2280,7 @@ var TextComplexityEvaluator = class _TextComplexityEvaluator extends BaseEvaluat
         errors,
         processingTimeMs: latencyMs
       });
-      if (vocabFailed && sentenceFailed && smkFailed) {
+      if (vocabFailed && sentenceFailed && smkFailed && conventionalityFailed) {
         throw new Error(`Text complexity evaluation failed: ${errors.join("; ")}`);
       }
     }
@@ -2085,7 +2301,7 @@ var TextComplexityEvaluator = class _TextComplexityEvaluator extends BaseEvaluat
       processingTimeMs: latencyMs,
       hasFailures
     });
-    return { vocabulary: vocabResult, sentenceStructure: sentenceResult, subjectMatterKnowledge: smkResult };
+    return { vocabulary: vocabResult, sentenceStructure: sentenceResult, subjectMatterKnowledge: smkResult, conventionality: conventionalityResult };
   }
   /**
    * Run a sub-evaluator with error handling.
@@ -2104,6 +2320,6 @@ async function evaluateTextComplexity(text, grade, config) {
   return evaluator.evaluate(text, grade);
 }
 
-export { APIError, AuthenticationError, ComplexityClassificationSchema, ConfigurationError, EvaluatorError, GradeBand, GradeLevelAppropriatenessEvaluator, GradeLevelAppropriatenessSchema, LogLevel, NetworkError, RateLimitError, SentenceAnalysisSchema, SentenceStructureEvaluator, SmkEvaluator, TextComplexityEvaluator, TextComplexityLevel, TimeoutError, ValidationError, VocabularyEvaluator, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateGradeLevelAppropriateness, evaluateSentenceStructure, evaluateSmk, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };
+export { APIError, AuthenticationError, ComplexityClassificationSchema, ConfigurationError, ConventionalityEvaluator, EvaluatorError, GradeBand, GradeLevelAppropriatenessEvaluator, GradeLevelAppropriatenessSchema, LogLevel, NetworkError, RateLimitError, SentenceAnalysisSchema, SentenceStructureEvaluator, SmkEvaluator, TextComplexityEvaluator, TextComplexityLevel, TimeoutError, ValidationError, VocabularyEvaluator, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateConventionality, evaluateGradeLevelAppropriateness, evaluateSentenceStructure, evaluateSmk, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map