@learning-commons/evaluators 0.1.0 → 0.3.0

package/README.md

@@ -117,19 +117,18 @@ await evaluator.evaluate(text: string, grade: string)
 
 ---
 
-### 3. Text Complexity Evaluator
+### 3. Subject Matter Knowledge (SMK) Evaluator
 
-Composite evaluator that analyzes both vocabulary and sentence structure complexity in parallel.
+Evaluates the background knowledge demands of educational texts relative to grade level. Determines how much prior subject knowledge a student needs to comprehend the text, based on the Common Core Qualitative Text Complexity Rubric.
 
 **Supported Grades:** 3-12
 
-**Uses:** Google Gemini 2.5 Pro + OpenAI GPT-4o (composite)
+**Uses:** Google Gemini 3 Flash Preview
 
 **Constructor:**
 ```typescript
-const evaluator = new TextComplexityEvaluator({
+const evaluator = new SmkEvaluator({
   googleApiKey?: string;  // Google API key (required by this evaluator)
-  openaiApiKey?: string;  // OpenAI API key (required by this evaluator)
   maxRetries?: number;    // Optional - Max retry attempts (default: 2)
   telemetry?: boolean | TelemetryOptions; // Optional (default: true)
   logger?: Logger;        // Optional - Custom logger
@@ -145,23 +144,169 @@ await evaluator.evaluate(text: string, grade: string)
 **Returns:**
 ```typescript
 {
-  score: {
-    overall: string;           // Overall complexity (highest of the two)
-    vocabulary: string;        // Vocabulary complexity score
-    sentenceStructure: string; // Sentence structure complexity score
+  score: 'Slightly complex' | 'Moderately complex' | 'Very complex' | 'Exceedingly complex';
+  reasoning: string;
+  metadata: {
+    model: string;
+    processingTimeMs: number;
   };
-  reasoning: string;  // Combined reasoning from both evaluators
-  metadata: EvaluationMetadata;
   _internal: {
-    vocabulary: EvaluationResult | { error: Error };
-    sentenceStructure: EvaluationResult | { error: Error };
+    identified_topics: string[];
+    curriculum_check: string;
+    assumptions_and_scaffolding: string;
+    friction_analysis: string;
+    complexity_score: 'Slightly complex' | 'Moderately complex' | 'Very complex' | 'Exceedingly complex';
+    reasoning: string;
   };
 }
 ```
 
+**Example:**
+```typescript
+import { SmkEvaluator } from '@learning-commons/evaluators';
+
+const evaluator = new SmkEvaluator({
+  googleApiKey: process.env.GOOGLE_API_KEY,
+});
+
+const result = await evaluator.evaluate(
+  "Hydraulic propulsion works by sucking water at the bow and forcing it sternward.",
+  "10"
+);
+console.log(result.score);          // "Very complex"
+console.log(result.reasoning);
+console.log(result._internal.identified_topics); // ["hydraulics", "propulsion", "physics"]
+```
+
+---
+
+### 4. 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.
+
+**Supported Grades:** 3-12
+
+**Uses:** Google Gemini 3 Flash Preview
+
+**Constructor:**
+```typescript
+const evaluator = new ConventionalityEvaluator({
+  googleApiKey?: string;  // Google API key (required by this evaluator)
+  maxRetries?: number;    // Optional - Max retry attempts (default: 2)
+  telemetry?: boolean | TelemetryOptions; // Optional (default: true)
+  logger?: Logger;        // Optional - Custom logger
+  logLevel?: LogLevel;    // Optional - Logging verbosity (default: WARN)
+});
+```
+
+**API:**
+```typescript
+await evaluator.evaluate(text: string, grade: string)
+```
+
+**Returns:**
+```typescript
+{
+  score: 'Slightly complex' | 'Moderately complex' | 'Very complex' | 'Exceedingly complex';
+  reasoning: string;
+  metadata: {
+    model: string;
+    processingTimeMs: number;
+  };
+  _internal: {
+    conventionality_features: string[];
+    grade_context: string;
+    instructional_insights: string;
+    complexity_score: 'Slightly complex' | 'Moderately complex' | 'Very complex' | 'Exceedingly complex';
+    reasoning: string;
+  };
+}
+```
+
+**Example:**
+```typescript
+import { ConventionalityEvaluator } from '@learning-commons/evaluators';
+
+const evaluator = new ConventionalityEvaluator({
+  googleApiKey: process.env.GOOGLE_API_KEY,
+});
+
+const result = await evaluator.evaluate(
+  "The author uses sustained irony to critique societal norms throughout the passage.",
+  "10"
+);
+console.log(result.score);          // "Very complex"
+console.log(result.reasoning);
+console.log(result._internal.conventionality_features); // ["sustained irony", ...]
+```
+
+---
+
+### 5. Text Complexity Evaluator
+
+Composite evaluator that analyzes vocabulary, sentence structure, subject matter knowledge, and conventionality complexity in parallel.
+
+**Supported Grades:** 3-12
+
+**Uses:** Google Gemini 2.5 Pro + Google Gemini 3 Flash Preview + OpenAI GPT-4o (composite)
+
+**Constructor:**
+```typescript
+const evaluator = new TextComplexityEvaluator({
+  googleApiKey?: string;  // Google API key (required by this evaluator)
+  openaiApiKey?: string;  // OpenAI API key (required by this evaluator)
+  maxRetries?: number;    // Optional - Max retry attempts (default: 2)
+  telemetry?: boolean | TelemetryOptions; // Optional (default: true)
+  logger?: Logger;        // Optional - Custom logger
+  logLevel?: LogLevel;    // Optional - Logging verbosity (default: WARN)
+});
+```
+
+**API:**
+```typescript
+await evaluator.evaluate(text: string, grade: string)
+```
+
+**Returns:**
+```typescript
+{
+  vocabulary: EvaluationResult<TextComplexityLevel> | { error: Error };
+  sentenceStructure: EvaluationResult<TextComplexityLevel> | { error: Error };
+  subjectMatterKnowledge: EvaluationResult<TextComplexityLevel> | { error: Error };
+  conventionality: EvaluationResult<TextComplexityLevel> | { error: Error };
+}
+```
+
+Each sub-evaluator result is either a full `EvaluationResult` or `{ error: Error }` if that evaluator failed. An error is only thrown if all four fail.
+
+**Example:**
+```typescript
+import { TextComplexityEvaluator } from '@learning-commons/evaluators';
+
+const evaluator = new TextComplexityEvaluator({
+  googleApiKey: process.env.GOOGLE_API_KEY,
+  openaiApiKey: process.env.OPENAI_API_KEY,
+});
+
+const result = await evaluator.evaluate("Your text here", "6");
+
+if (!('error' in result.vocabulary)) {
+  console.log('Vocabulary:', result.vocabulary.score);
+}
+if (!('error' in result.sentenceStructure)) {
+  console.log('Sentence structure:', result.sentenceStructure.score);
+}
+if (!('error' in result.subjectMatterKnowledge)) {
+  console.log('Subject matter knowledge:', result.subjectMatterKnowledge.score);
+}
+if (!('error' in result.conventionality)) {
+  console.log('Conventionality:', result.conventionality.score);
+}
+```
+
 ---
 
-### 4. Grade Level Appropriateness Evaluator
+### 6. Grade Level Appropriateness Evaluator
 
 Determines appropriate grade level for text.
 
@@ -308,6 +453,8 @@ interface BaseEvaluatorConfig {
 **Note:** Which API keys are required depends on the evaluator. The SDK validates required keys at runtime based on the evaluator's metadata:
 - **Vocabulary**: Requires both `googleApiKey` and `openaiApiKey`
 - **Sentence Structure**: Requires `openaiApiKey` only
+- **Subject Matter Knowledge**: Requires `googleApiKey` only
+- **Conventionality**: Requires `googleApiKey` only
 - **Text Complexity**: Requires both `googleApiKey` and `openaiApiKey`
 - **Grade Level Appropriateness**: Requires `googleApiKey` only