@learning-commons/evaluators 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to the `@learning-commons/evaluators` TypeScript SDK will be documented in this file.
 
+## [0.6.0](https://github.com/learning-commons-org/evaluators/compare/sdks-typescript-v0.5.0...sdks-typescript-v0.6.0) (2026-05-22)
+
+
+### Features
+
+* **ts-sdk:** add bypassRowLimit option for batch evaluator ([#77](https://github.com/learning-commons-org/evaluators/issues/77)) ([902a60f](https://github.com/learning-commons-org/evaluators/commit/902a60fc934372a151f1d40c0b49ef3313d12609))
+* **ts-sdk:** expose per-call token usage on EvaluationMetadata ([#59](https://github.com/learning-commons-org/evaluators/issues/59)) ([3c8fa0f](https://github.com/learning-commons-org/evaluators/commit/3c8fa0fd8e2389fc902c9cf1f63985b40d2e4b2c))
+
 ## [0.5.0](https://github.com/learning-commons-org/evaluators/compare/sdks-typescript-v0.4.0...sdks-typescript-v0.5.0) (2026-05-07)
 
 

package/README.md

@@ -70,6 +70,8 @@ await evaluator.evaluate(text: string, grade: string)
   metadata: {
     model: string;
     processingTimeMs: number;
+    inputTokens: number;
+    outputTokens: number;
   };
   _internal: VocabularyInternal; // Detailed analysis
 }
@@ -110,6 +112,8 @@ await evaluator.evaluate(text: string, grade: string)
   metadata: {
     model: string;
     processingTimeMs: number;
+    inputTokens: number;
+    outputTokens: number;
   };
   _internal: {
     sentenceAnalysis: SentenceAnalysis;
@@ -154,6 +158,8 @@ await evaluator.evaluate(text: string, grade: string)
   metadata: {
     model: string;
     processingTimeMs: number;
+    inputTokens: number;
+    outputTokens: number;
   };
   _internal: {
     identified_topics: string[];
@@ -218,6 +224,8 @@ await evaluator.evaluate(text: string, grade: string)
   metadata: {
     model: string;
     processingTimeMs: number;
+    inputTokens: number;
+    outputTokens: number;
   };
   _internal: {
     conventionality_features: string[];
@@ -346,6 +354,8 @@ await evaluator.evaluate(text: string)
   metadata: {
     model: string;
     processingTimeMs: number;
+    inputTokens: number;
+    outputTokens: number;
   };
   _internal: {
     grade: string;
@@ -391,6 +401,8 @@ await evaluator.evaluate(text: string, grade: string)
   metadata: {
     model: string;
     processingTimeMs: number;
+    inputTokens: number;
+    outputTokens: number;
   };
   _internal: {
     complexity_score: 'slightly_complex' | 'moderately_complex' | 'very_complex' | 'exceedingly_complex' | 'more_context_needed';

package/dist/batch/cli.js

@@ -1279,7 +1279,9 @@ var VocabularyEvaluator = class _VocabularyEvaluator extends BaseEvaluator {
         reasoning: complexityResponse.data.reasoning,
         metadata: {
           model: modelLabel,
-          processingTimeMs: latencyMs
+          processingTimeMs: latencyMs,
+          inputTokens: totalTokenUsage.input_tokens,
+          outputTokens: totalTokenUsage.output_tokens
         },
         _internal: complexityResponse.data
       };
@@ -1609,7 +1611,9 @@ var SentenceStructureEvaluator = class _SentenceStructureEvaluator extends BaseE
         reasoning: complexityResponse.data.reasoning,
         metadata: {
           model: this.provider.label,
-          processingTimeMs: latencyMs
+          processingTimeMs: latencyMs,
+          inputTokens: totalTokenUsage.input_tokens,
+          outputTokens: totalTokenUsage.output_tokens
         },
         _internal: {
           sentenceAnalysis: analysisResponse.data,
@@ -1815,7 +1819,9 @@ var GradeLevelAppropriatenessEvaluator = class extends BaseEvaluator {
         reasoning: response.data.reasoning,
         metadata: {
           model: this.provider.label,
-          processingTimeMs: latencyMs
+          processingTimeMs: latencyMs,
+          inputTokens: tokenUsage.input_tokens,
+          outputTokens: tokenUsage.output_tokens
         },
         _internal: response.data
       };
@@ -2017,7 +2023,9 @@ var SmkEvaluator = class _SmkEvaluator extends BaseEvaluator {
         reasoning: response.data.reasoning,
         metadata: {
           model: this.provider.label,
-          processingTimeMs: latencyMs
+          processingTimeMs: latencyMs,
+          inputTokens: totalTokenUsage.input_tokens,
+          outputTokens: totalTokenUsage.output_tokens
         },
         _internal: response.data
       };
@@ -2223,7 +2231,9 @@ var ConventionalityEvaluator = class _ConventionalityEvaluator extends BaseEvalu
         reasoning: response.data.reasoning,
         metadata: {
           model: this.provider.label,
-          processingTimeMs: latencyMs
+          processingTimeMs: latencyMs,
+          inputTokens: totalTokenUsage.input_tokens,
+          outputTokens: totalTokenUsage.output_tokens
         },
         _internal: response.data
       };
@@ -2498,7 +2508,9 @@ var PurposeEvaluator = class _PurposeEvaluator extends BaseEvaluator {
         reasoning: response.data.reasoning,
         metadata: {
           model: this.provider.label,
-          processingTimeMs: latencyMs
+          processingTimeMs: latencyMs,
+          inputTokens: tokenUsage.input_tokens,
+          outputTokens: tokenUsage.output_tokens
         },
         _internal: response.data
       };
@@ -2611,6 +2623,7 @@ var BatchEvaluator = class {
       concurrency: 3,
       maxRetries: 2,
       telemetry: false,
+      bypassRowLimit: false,
       ...config
     };
     this.limit = pLimit(this.config.concurrency);
@@ -2764,9 +2777,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;
@@ -4099,6 +4112,8 @@ function parseArgs() {
       if (!isNaN(v) && v >= 0) result.maxRetries = v;
     } else if (args[i] === "--no-telemetry") {
       result.noTelemetry = true;
+    } else if (args[i] === "--bypass-row-limit") {
+      result.bypassRowLimit = true;
     }
   }
   return result;
@@ -4132,16 +4147,22 @@ async function main() {
 `);
     const group = getAvailableGroups()[0];
     console.log(`\u2713 Evaluator group: ${group.name}`);
-    console.log(`  ${group.description}`);
-    console.log(`  Row limit: ${group.maxInputRows}
+    console.log(`  ${group.description}
 `);
     if (inputs.length > group.maxInputRows) {
-      console.error(`\u274C Too many rows: ${inputs.length} (max ${group.maxInputRows} for this group)
+      if (cliArgs.bypassRowLimit) {
+        console.warn(`\u26A0\uFE0F  Row limit bypassed: ${inputs.length} rows (default max ${group.maxInputRows}).`);
+        console.warn(`   Expect longer runtime and possible provider throttling.
 `);
-      console.log("Suggestions:");
-      console.log(`  \u2022 Trim the CSV to ${group.maxInputRows} rows`);
-      console.log("  \u2022 Split into multiple smaller batches\n");
-      process.exit(1);
+      } else {
+        console.error(`\u274C Too many rows: ${inputs.length} (max ${group.maxInputRows} for this group)
+`);
+        console.log("Suggestions:");
+        console.log(`  \u2022 Trim the CSV to ${group.maxInputRows} rows`);
+        console.log("  \u2022 Split into multiple smaller batches");
+        console.log("  \u2022 Re-run with --bypass-row-limit to skip this check (use with caution)\n");
+        process.exit(1);
+      }
     }
     let googleApiKey;
     let openaiApiKey;
@@ -4218,7 +4239,7 @@ async function main() {
     const totalTasks = inputs.length * group.evaluatorIds.length;
     console.log(`
 \u{1F4DD} Summary:`);
-    console.log(`  Input rows: ${inputs.length}`);
+    console.log(`  Input rows: ${inputs.length}${cliArgs.bypassRowLimit ? " (row limit bypassed)" : ""}`);
     console.log(`  Evaluators: ${group.evaluatorIds.length}`);
     console.log(`  Total tasks: ${totalTasks}`);
     console.log(`  Concurrency: ${cliArgs.concurrency ?? 3}`);
@@ -4243,7 +4264,8 @@ async function main() {
       openaiApiKey,
       concurrency: cliArgs.concurrency ?? 3,
       maxRetries: cliArgs.maxRetries ?? 2,
-      telemetry: !cliArgs.noTelemetry
+      telemetry: !cliArgs.noTelemetry,
+      bypassRowLimit: cliArgs.bypassRowLimit ?? false
     });
     let isShuttingDown = false;
     const handleShutdown = () => {