@learning-commons/evaluators 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { B as BaseEvaluator, a as BaseEvaluatorConfig } from './base-Ced9oKKa.js';
-export { E as EvaluatorMetadata, b as LogContext, c as LogLevel, L as Logger, T as TelemetryOptions } from './base-Ced9oKKa.js';
+import { B as BaseEvaluator, P as Provider, a as BaseEvaluatorConfig } from './base-DKcAYXfb.js';
+export { E as EvaluatorMetadata, L as LLMProvider, b as LLMRequest, c as LLMResponse, d as LogContext, e as LogLevel, f as Logger, M as Message, g as ModelOverride, h as ProviderConfig, i as Providers, T as TelemetryOptions, j as TextGenerationResponse } from './base-DKcAYXfb.js';
 
 /**
  * Shared complexity levels used across all text complexity evaluators
@@ -62,6 +62,111 @@ declare const GradeLevelAppropriatenessSchema: z.ZodObject<{
 }>;
 type GradeLevelAppropriatenessInternal = z.infer<typeof GradeLevelAppropriatenessSchema>;
 
+declare const PurposeOutputSchema: z.ZodObject<{
+    complexity_score: z.ZodEnum<["slightly_complex", "moderately_complex", "very_complex", "exceedingly_complex", "more_context_needed"]>;
+    reasoning: z.ZodString;
+    details: z.ZodObject<{
+        detailed_summary: z.ZodArray<z.ZodObject<{
+            factor: z.ZodString;
+            description: z.ZodString;
+            effect_on_complexity_dimension: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            factor: string;
+            description: string;
+            effect_on_complexity_dimension: string;
+        }, {
+            factor: string;
+            description: string;
+            effect_on_complexity_dimension: string;
+        }>, "many">;
+        adjustment_and_scaffolding: z.ZodArray<z.ZodObject<{
+            scaffolding_need: z.ZodString;
+            suggestion: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            scaffolding_need: string;
+            suggestion: string;
+        }, {
+            scaffolding_need: string;
+            suggestion: string;
+        }>, "many">;
+        recommended_use_cases: z.ZodArray<z.ZodObject<{
+            opportunity: z.ZodString;
+            suggestion: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            suggestion: string;
+            opportunity: string;
+        }, {
+            suggestion: string;
+            opportunity: string;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        detailed_summary: {
+            factor: string;
+            description: string;
+            effect_on_complexity_dimension: string;
+        }[];
+        adjustment_and_scaffolding: {
+            scaffolding_need: string;
+            suggestion: string;
+        }[];
+        recommended_use_cases: {
+            suggestion: string;
+            opportunity: string;
+        }[];
+    }, {
+        detailed_summary: {
+            factor: string;
+            description: string;
+            effect_on_complexity_dimension: string;
+        }[];
+        adjustment_and_scaffolding: {
+            scaffolding_need: string;
+            suggestion: string;
+        }[];
+        recommended_use_cases: {
+            suggestion: string;
+            opportunity: string;
+        }[];
+    }>;
+}, "strict", z.ZodTypeAny, {
+    reasoning: string;
+    complexity_score: "slightly_complex" | "moderately_complex" | "very_complex" | "exceedingly_complex" | "more_context_needed";
+    details: {
+        detailed_summary: {
+            factor: string;
+            description: string;
+            effect_on_complexity_dimension: string;
+        }[];
+        adjustment_and_scaffolding: {
+            scaffolding_need: string;
+            suggestion: string;
+        }[];
+        recommended_use_cases: {
+            suggestion: string;
+            opportunity: string;
+        }[];
+    };
+}, {
+    reasoning: string;
+    complexity_score: "slightly_complex" | "moderately_complex" | "very_complex" | "exceedingly_complex" | "more_context_needed";
+    details: {
+        detailed_summary: {
+            factor: string;
+            description: string;
+            effect_on_complexity_dimension: string;
+        }[];
+        adjustment_and_scaffolding: {
+            scaffolding_need: string;
+            suggestion: string;
+        }[];
+        recommended_use_cases: {
+            suggestion: string;
+            opportunity: string;
+        }[];
+    };
+}>;
+type PurposeInternal = z.infer<typeof PurposeOutputSchema>;
+
 /**
  * Custom error types for the Evaluators SDK
  *
@@ -204,72 +309,6 @@ declare class TimeoutError extends APIError {
     constructor(message?: string);
 }
 
-/**
- * Message format for LLM conversations
- */
-interface Message {
-    role: 'system' | 'user' | 'assistant';
-    content: string;
-}
-/**
- * Request configuration for structured LLM generation
- */
-interface LLMRequest<T> {
-    messages: Message[];
-    schema: z.ZodSchema<T>;
-    temperature?: number;
-    maxTokens?: number;
-    model?: string;
-}
-/**
- * Response from LLM with usage metadata
- */
-interface LLMResponse<T> {
-    data: T;
-    model: string;
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-    };
-    latencyMs: number;
-}
-/**
- * Response from plain text generation
- */
-interface TextGenerationResponse {
-    text: string;
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-    };
-    latencyMs: number;
-}
-/**
- * Base interface for LLM provider implementations
- */
-interface LLMProvider {
-    /**
-     * Generate structured output from LLM using Zod schema
-     */
-    generateStructured<T>(request: LLMRequest<T>): Promise<LLMResponse<T>>;
-    /**
-     * Generate plain text from LLM
-     */
-    generateText(messages: Message[], temperature?: number): Promise<TextGenerationResponse>;
-}
-/**
- * Configuration for LLM provider
- */
-interface ProviderConfig {
-    type: 'openai' | 'anthropic' | 'google' | 'custom';
-    apiKey?: string;
-    model?: string;
-    temperature?: number;
-    baseURL?: string;
-    customProvider?: LLMProvider;
-    maxRetries?: number;
-}
-
 /**
  * Stage 1: Detailed sentence analysis output (40+ metrics)
  * Ported from Python SentenceAnalysesEvaluatorOutput
@@ -461,18 +500,18 @@ declare const VocabularyComplexitySchema: z.ZodObject<{
     reasoning: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     reasoning: string;
+    complexity_score: "Slightly complex" | "Moderately complex" | "Very complex" | "Exceedingly complex";
     tier_2_words: string;
     tier_3_words: string;
     archaic_words: string;
     other_complex_words: string;
-    complexity_score: "Slightly complex" | "Moderately complex" | "Very complex" | "Exceedingly complex";
 }, {
     reasoning: string;
+    complexity_score: "Slightly complex" | "Moderately complex" | "Very complex" | "Exceedingly complex";
     tier_2_words: string;
     tier_3_words: string;
     archaic_words: string;
     other_complex_words: string;
-    complexity_score: "Slightly complex" | "Moderately complex" | "Very complex" | "Exceedingly complex";
 }>;
 type VocabularyInternal = z.infer<typeof VocabularyComplexitySchema>;
 
@@ -559,8 +598,7 @@ declare class VocabularyEvaluator extends BaseEvaluator {
         name: string;
         description: string;
         supportedGrades: readonly ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
-        requiresGoogleKey: boolean;
-        requiresOpenAIKey: boolean;
+        defaultProviders: readonly [Provider.Google, Provider.OpenAI];
     };
     private grades34ComplexityProvider;
     private otherGradesComplexityProvider;
@@ -573,6 +611,7 @@ declare 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)
      */
     evaluate(text: string, grade: string): Promise<EvaluationResult<TextComplexityLevel, VocabularyInternal>>;
@@ -639,11 +678,9 @@ declare class SentenceStructureEvaluator extends BaseEvaluator {
         name: string;
         description: string;
         supportedGrades: readonly ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
-        requiresGoogleKey: boolean;
-        requiresOpenAIKey: boolean;
+        defaultProviders: readonly [Provider.OpenAI];
     };
-    private analysisProvider;
-    private complexityProvider;
+    private provider;
     constructor(config: BaseEvaluatorConfig);
     /**
      * Evaluate sentence structure complexity for a given text and grade level
@@ -652,6 +689,7 @@ declare class SentenceStructureEvaluator 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)
      */
     evaluate(text: string, grade: string): Promise<EvaluationResult<TextComplexityLevel, SentenceStructureInternal>>;
@@ -717,8 +755,7 @@ declare class GradeLevelAppropriatenessEvaluator extends BaseEvaluator {
         name: string;
         description: string;
         supportedGrades: readonly [];
-        requiresGoogleKey: boolean;
-        requiresOpenAIKey: boolean;
+        defaultProviders: readonly [Provider.Google];
     };
     private provider;
     constructor(config: BaseEvaluatorConfig);
@@ -728,6 +765,7 @@ declare class GradeLevelAppropriatenessEvaluator 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)
      */
     evaluate(text: string): Promise<EvaluationResult<GradeBand, GradeLevelAppropriatenessInternal>>;
@@ -776,8 +814,7 @@ declare class SmkEvaluator extends BaseEvaluator {
         name: string;
         description: string;
         supportedGrades: readonly ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
-        requiresGoogleKey: boolean;
-        requiresOpenAIKey: boolean;
+        defaultProviders: readonly [Provider.Google];
     };
     private provider;
     constructor(config: BaseEvaluatorConfig);
@@ -788,6 +825,7 @@ declare 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)
      */
     evaluate(text: string, grade: string): Promise<EvaluationResult<TextComplexityLevel, SmkInternal>>;
@@ -839,8 +877,7 @@ declare class ConventionalityEvaluator extends BaseEvaluator {
         name: string;
         description: string;
         supportedGrades: readonly ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
-        requiresGoogleKey: boolean;
-        requiresOpenAIKey: boolean;
+        defaultProviders: readonly [Provider.Google];
     };
     private provider;
     constructor(config: BaseEvaluatorConfig);
@@ -851,6 +888,7 @@ declare class ConventionalityEvaluator 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)
      */
     evaluate(text: string, grade: string): Promise<EvaluationResult<TextComplexityLevel, ConventionalityInternal>>;
@@ -922,8 +960,7 @@ declare class TextComplexityEvaluator extends BaseEvaluator {
         name: string;
         description: string;
         supportedGrades: readonly ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
-        requiresGoogleKey: boolean;
-        requiresOpenAIKey: boolean;
+        defaultProviders: readonly [Provider.Google, Provider.OpenAI];
     };
     private vocabularyEvaluator;
     private sentenceStructureEvaluator;
@@ -941,7 +978,8 @@ declare class TextComplexityEvaluator extends BaseEvaluator {
      * @param text - The text to evaluate
      * @param grade - The target grade level (3-12)
      * @returns Map of sub-evaluator results
-     * @throws {ValidationError} If text is empty or grade is invalid
+     * @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 {Error} If all sub-evaluators fail
      */
     evaluate(text: string, grade: string): Promise<TextComplexityResult>;
@@ -968,6 +1006,35 @@ declare class TextComplexityEvaluator extends BaseEvaluator {
  */
 declare function evaluateTextComplexity(text: string, grade: string, config: BaseEvaluatorConfig): Promise<TextComplexityResult>;
 
+type PurposeComplexityLevel = TextComplexityLevel | 'More context needed';
+declare class PurposeEvaluator extends BaseEvaluator {
+    static readonly metadata: {
+        id: string;
+        name: string;
+        description: string;
+        supportedGrades: string[];
+        defaultProviders: readonly [Provider.Google];
+    };
+    private static readonly TEMPERATURE;
+    private static computeFkScore;
+    private provider;
+    constructor(config: BaseEvaluatorConfig);
+    /**
+     * 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)
+     */
+    evaluate(text: string, grade: string): Promise<EvaluationResult<PurposeComplexityLevel, PurposeInternal>>;
+    private parseAndValidateGrade;
+    private callLLM;
+}
+declare function evaluatePurpose(text: string, grade: string, config: BaseEvaluatorConfig): Promise<EvaluationResult<PurposeComplexityLevel, PurposeInternal>>;
+
 /**
  * Calculate Flesch-Kincaid Grade Level
  * Equivalent to Python's textstat.flesch_kincaid_grade()
@@ -998,4 +1065,4 @@ declare function addEngineeredFeatures(analysis: SentenceAnalysis): SentenceFeat
  */
 declare function featuresToJSON(features: SentenceFeatures, decimals?: number, castToInt?: boolean): string;
 
-export { APIError, AuthenticationError, BaseEvaluatorConfig, type ComplexityClassification, ComplexityClassificationSchema, ConfigurationError, ConventionalityEvaluator, type ConventionalityInternal, type EvaluationError, type EvaluationMetadata, type EvaluationResult, EvaluatorError, GradeBand, GradeLevelAppropriatenessEvaluator, type GradeLevelAppropriatenessInternal, GradeLevelAppropriatenessSchema, type LLMProvider, type LLMRequest, type LLMResponse, type Message, NetworkError, type ProviderConfig, RateLimitError, type ReadabilityMetrics, type SentenceAnalysis, SentenceAnalysisSchema, type SentenceFeatures, SentenceStructureEvaluator, type SentenceStructureInternal, SmkEvaluator, type SmkInternal, TextComplexityEvaluator, TextComplexityLevel, type TextComplexityResult, type TextGenerationResponse, TimeoutError, ValidationError, VocabularyEvaluator, type VocabularyInternal, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateConventionality, evaluateGradeLevelAppropriateness, evaluateSentenceStructure, evaluateSmk, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };
+export { APIError, AuthenticationError, BaseEvaluatorConfig, type ComplexityClassification, ComplexityClassificationSchema, ConfigurationError, ConventionalityEvaluator, type ConventionalityInternal, type EvaluationError, type EvaluationMetadata, type EvaluationResult, EvaluatorError, GradeBand, GradeLevelAppropriatenessEvaluator, type GradeLevelAppropriatenessInternal, GradeLevelAppropriatenessSchema, NetworkError, Provider, type PurposeComplexityLevel, PurposeEvaluator, type PurposeInternal, RateLimitError, type ReadabilityMetrics, type SentenceAnalysis, SentenceAnalysisSchema, type SentenceFeatures, SentenceStructureEvaluator, type SentenceStructureInternal, SmkEvaluator, type SmkInternal, TextComplexityEvaluator, TextComplexityLevel, type TextComplexityResult, TimeoutError, ValidationError, VocabularyEvaluator, type VocabularyInternal, addEngineeredFeatures, calculateFleschKincaidGrade, calculateReadabilityMetrics, evaluateConventionality, evaluateGradeLevelAppropriateness, evaluatePurpose, evaluateSentenceStructure, evaluateSmk, evaluateTextComplexity, evaluateVocabulary, featuresToJSON };