@learning-commons/evaluators 0.3.0 → 0.5.0

package/dist/batch/index.d.cts

@@ -0,0 +1,146 @@
+import { T as TelemetryOptions } from '../base-DKcAYXfb.cjs';
+import 'zod';
+
+/**
+ * Batch evaluation types
+ */
+
+/**
+ * Input row from CSV
+ */
+interface BatchInput {
+    text: string;
+    grade: string;
+    rowIndex: number;
+    originalRow: Record<string, unknown>;
+}
+/**
+ * Result from a single evaluation
+ */
+interface BatchResult {
+    rowIndex: number;
+    text: string;
+    grade: string;
+    evaluatorId: string;
+    status: 'success' | 'error';
+    score?: string;
+    reasoning?: string;
+    error?: string;
+    processingTimeMs: number;
+    originalRow: Record<string, unknown>;
+}
+/**
+ * Summary statistics for batch evaluation
+ */
+interface BatchSummary {
+    totalTasks: number;
+    successful: number;
+    failed: number;
+    durationMs: number;
+    resultsPerEvaluator: Record<string, {
+        successful: number;
+        failed: number;
+    }>;
+}
+/**
+ * Complete batch evaluation output
+ */
+interface BatchOutput {
+    results: BatchResult[];
+    summary: BatchSummary;
+}
+/**
+ * A named group of evaluators that run together and share an HTML report format.
+ * This is the unit of selection exposed to users.
+ */
+interface EvaluatorGroup {
+    id: string;
+    name: string;
+    description: string;
+    /** IDs of the evaluators that belong to this group */
+    evaluatorIds: readonly string[];
+    requiresGoogleKey: boolean;
+    requiresOpenAIKey: boolean;
+    /** Maximum number of input rows allowed for this group */
+    maxInputRows: number;
+}
+/**
+ * Configuration for batch evaluation
+ */
+interface BatchConfig {
+    googleApiKey?: string;
+    openaiApiKey?: string;
+    concurrency?: number;
+    maxRetries?: number;
+    telemetry?: boolean | TelemetryOptions;
+}
+
+/**
+ * Returns the available evaluator groups.
+ */
+declare function getAvailableGroups(): EvaluatorGroup[];
+/**
+ * Batch evaluator class
+ *
+ * Processes multiple texts in parallel using all evaluators in a group.
+ */
+declare class BatchEvaluator {
+    private config;
+    private limit;
+    private evaluatorInstances;
+    private isCancelled;
+    private completedResults;
+    constructor(config: BatchConfig);
+    /**
+     * Cancel ongoing evaluation.
+     * Returns partial results collected so far.
+     */
+    cancel(): BatchResult[];
+    /**
+     * Initialize evaluator instances for the given IDs
+     */
+    private initializeEvaluators;
+    /**
+     * Create tasks from inputs and evaluator IDs
+     */
+    private createTasks;
+    /**
+     * Execute a single evaluation task
+     */
+    private executeTask;
+    /**
+     * Calculate summary statistics
+     */
+    private calculateSummary;
+    /**
+     * Run batch evaluation for an evaluator group.
+     *
+     * @param inputs - Array of input rows
+     * @param groupId - The evaluator group to run (see getAvailableGroups())
+     * @param onProgress - Optional callback invoked after each task completes
+     * @returns Batch evaluation results and summary
+     */
+    evaluate(inputs: BatchInput[], groupId: string, onProgress?: (result: BatchResult) => void): Promise<BatchOutput>;
+}
+
+/**
+ * Parse a CSV file into BatchInput rows.
+ *
+ * Requires columns named "text" and "grade" (case-insensitive, whitespace-trimmed).
+ * Rows missing either value are silently skipped.
+ *
+ * @throws {Error} If the file does not exist, is empty, or is missing required columns
+ */
+declare function parseCSV(csvPath: string): BatchInput[];
+
+declare function formatAsCSV(output: BatchOutput): string;
+interface ReportMeta {
+    csvPath: string;
+    groupId: string;
+    reportId: string;
+    generatedAt: Date;
+    totalInputRows: number;
+}
+declare function formatAsHTML(output: BatchOutput, meta: ReportMeta): string;
+
+export { type BatchConfig, BatchEvaluator, type BatchInput, type BatchOutput, type BatchResult, type BatchSummary, type EvaluatorGroup, type ReportMeta, formatAsCSV, formatAsHTML, getAvailableGroups, parseCSV };

package/dist/batch/index.d.ts

@@ -0,0 +1,146 @@
+import { T as TelemetryOptions } from '../base-DKcAYXfb.js';
+import 'zod';
+
+/**
+ * Batch evaluation types
+ */
+
+/**
+ * Input row from CSV
+ */
+interface BatchInput {
+    text: string;
+    grade: string;
+    rowIndex: number;
+    originalRow: Record<string, unknown>;
+}
+/**
+ * Result from a single evaluation
+ */
+interface BatchResult {
+    rowIndex: number;
+    text: string;
+    grade: string;
+    evaluatorId: string;
+    status: 'success' | 'error';
+    score?: string;
+    reasoning?: string;
+    error?: string;
+    processingTimeMs: number;
+    originalRow: Record<string, unknown>;
+}
+/**
+ * Summary statistics for batch evaluation
+ */
+interface BatchSummary {
+    totalTasks: number;
+    successful: number;
+    failed: number;
+    durationMs: number;
+    resultsPerEvaluator: Record<string, {
+        successful: number;
+        failed: number;
+    }>;
+}
+/**
+ * Complete batch evaluation output
+ */
+interface BatchOutput {
+    results: BatchResult[];
+    summary: BatchSummary;
+}
+/**
+ * A named group of evaluators that run together and share an HTML report format.
+ * This is the unit of selection exposed to users.
+ */
+interface EvaluatorGroup {
+    id: string;
+    name: string;
+    description: string;
+    /** IDs of the evaluators that belong to this group */
+    evaluatorIds: readonly string[];
+    requiresGoogleKey: boolean;
+    requiresOpenAIKey: boolean;
+    /** Maximum number of input rows allowed for this group */
+    maxInputRows: number;
+}
+/**
+ * Configuration for batch evaluation
+ */
+interface BatchConfig {
+    googleApiKey?: string;
+    openaiApiKey?: string;
+    concurrency?: number;
+    maxRetries?: number;
+    telemetry?: boolean | TelemetryOptions;
+}
+
+/**
+ * Returns the available evaluator groups.
+ */
+declare function getAvailableGroups(): EvaluatorGroup[];
+/**
+ * Batch evaluator class
+ *
+ * Processes multiple texts in parallel using all evaluators in a group.
+ */
+declare class BatchEvaluator {
+    private config;
+    private limit;
+    private evaluatorInstances;
+    private isCancelled;
+    private completedResults;
+    constructor(config: BatchConfig);
+    /**
+     * Cancel ongoing evaluation.
+     * Returns partial results collected so far.
+     */
+    cancel(): BatchResult[];
+    /**
+     * Initialize evaluator instances for the given IDs
+     */
+    private initializeEvaluators;
+    /**
+     * Create tasks from inputs and evaluator IDs
+     */
+    private createTasks;
+    /**
+     * Execute a single evaluation task
+     */
+    private executeTask;
+    /**
+     * Calculate summary statistics
+     */
+    private calculateSummary;
+    /**
+     * Run batch evaluation for an evaluator group.
+     *
+     * @param inputs - Array of input rows
+     * @param groupId - The evaluator group to run (see getAvailableGroups())
+     * @param onProgress - Optional callback invoked after each task completes
+     * @returns Batch evaluation results and summary
+     */
+    evaluate(inputs: BatchInput[], groupId: string, onProgress?: (result: BatchResult) => void): Promise<BatchOutput>;
+}
+
+/**
+ * Parse a CSV file into BatchInput rows.
+ *
+ * Requires columns named "text" and "grade" (case-insensitive, whitespace-trimmed).
+ * Rows missing either value are silently skipped.
+ *
+ * @throws {Error} If the file does not exist, is empty, or is missing required columns
+ */
+declare function parseCSV(csvPath: string): BatchInput[];
+
+declare function formatAsCSV(output: BatchOutput): string;
+interface ReportMeta {
+    csvPath: string;
+    groupId: string;
+    reportId: string;
+    generatedAt: Date;
+    totalInputRows: number;
+}
+declare function formatAsHTML(output: BatchOutput, meta: ReportMeta): string;
+
+export { type BatchConfig, BatchEvaluator, type BatchInput, type BatchOutput, type BatchResult, type BatchSummary, type EvaluatorGroup, type ReportMeta, formatAsCSV, formatAsHTML, getAvailableGroups, parseCSV };