@learning-commons/evaluators 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+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
@@ -60,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
  *
@@ -202,151 +309,6 @@ declare class TimeoutError extends APIError {
     constructor(message?: string);
 }
 
-/**
- * Logging interface for the Evaluators SDK
- *
- * Provides structured logging with verbosity levels.
- * Users can inject custom loggers or use the default console logger.
- */
-/**
- * Log levels in order of verbosity
- */
-declare enum LogLevel {
-    /** Debug messages - very verbose, for development */
-    DEBUG = 0,
-    /** Informational messages - normal operations */
-    INFO = 1,
-    /** Warning messages - potentially problematic situations */
-    WARN = 2,
-    /** Error messages - errors that need attention */
-    ERROR = 3,
-    /** Silent - no logging */
-    SILENT = 4
-}
-/**
- * Context object for structured logging
- */
-interface LogContext {
-    /** Evaluator type (vocabulary, sentence-structure, etc.) */
-    evaluator?: string;
-    /** Current operation or stage */
-    operation?: string;
-    /** Error object if applicable */
-    error?: Error;
-    /** Additional metadata */
-    [key: string]: unknown;
-}
-/**
- * Logger interface
- *
- * Implement this interface to provide custom logging behavior.
- *
- * @example
- * ```typescript
- * const customLogger: Logger = {
- *   debug: (msg, ctx) => myLogger.debug(msg, ctx),
- *   info: (msg, ctx) => myLogger.info(msg, ctx),
- *   warn: (msg, ctx) => myLogger.warn(msg, ctx),
- *   error: (msg, ctx) => myLogger.error(msg, ctx),
- * };
- *
- * const evaluator = new VocabularyEvaluator({
- *   googleApiKey: '...',
- *   openaiApiKey: '...',
- *   logger: customLogger,
- *   logLevel: LogLevel.INFO,
- * });
- * ```
- */
-interface Logger {
-    /**
-     * Log debug message
-     * Used for detailed debugging information
-     */
-    debug(message: string, context?: LogContext): void;
-    /**
-     * Log informational message
-     * Used for normal operations
-     */
-    info(message: string, context?: LogContext): void;
-    /**
-     * Log warning message
-     * Used for potentially problematic situations
-     */
-    warn(message: string, context?: LogContext): void;
-    /**
-     * Log error message
-     * Used for errors that need attention
-     */
-    error(message: string, context?: LogContext): void;
-}
-
-/**
- * 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
@@ -538,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>;
 
@@ -604,257 +566,6 @@ declare const ConventionalityOutputSchema: z.ZodObject<{
 }>;
 type ConventionalityInternal = z.infer<typeof ConventionalityOutputSchema>;
 
-/**
- * Evaluation status
- */
-type EvaluationStatus = 'success' | 'error';
-/**
- * Token usage metrics from LLM providers
- */
-interface TokenUsage {
-    input_tokens: number;
-    output_tokens: number;
-}
-/**
- * Per-stage details for multi-stage evaluations
- */
-interface StageDetail {
-    /** Stage name (e.g., "background_knowledge", "complexity_evaluation") */
-    stage: string;
-    /** Provider used for this stage (e.g., "openai:gpt-4o") */
-    provider: string;
-    /** Total latency including all retries (ms) */
-    latency_ms: number;
-    /** Token usage aggregated across all attempts */
-    token_usage?: TokenUsage;
-    /**
-     * Whether schema validation failed (indicates prompt needs clearer instructions)
-     *
-     * TODO: Not currently tracked. Vercel AI SDK abstracts validation away.
-     * To implement: Add custom retry wrapper that catches validation errors.
-     */
-    schema_validation_failed?: boolean;
-}
-/**
- * Extensible metadata for telemetry events
- */
-interface TelemetryMetadata {
-    /** Detailed breakdown by stage (for multi-stage evaluations) */
-    stage_details?: StageDetail[];
-}
-/**
- * Telemetry event payload
- */
-interface TelemetryEvent {
-    timestamp: string;
-    sdk_version: string;
-    evaluator_type: string;
-    grade?: string;
-    status: EvaluationStatus;
-    error_code?: string;
-    latency_ms: number;
-    text_length_chars: number;
-    provider: string;
-    token_usage?: TokenUsage;
-    metadata?: TelemetryMetadata;
-    input_text?: string;
-}
-/**
- * Configuration for telemetry client
- */
-interface TelemetryConfig {
-    /** Analytics service endpoint URL */
-    endpoint: string;
-    /** Learning Commons partner key (optional, sent as X-API-Key header) */
-    partnerKey?: string;
-    /** Client ID for anonymous tracking (persistent UUID from ~/.config/learning-commons/config.json) */
-    clientId: string;
-    /** Enable telemetry (default: true) */
-    enabled: boolean;
-    /** Logger instance (respects the SDK's configured log level and custom logger) */
-    logger: Logger;
-}
-
-/**
- * Telemetry client for sending analytics events
- *
- * Fire-and-forget implementation that never blocks SDK operations.
- * Errors are logged but don't fail evaluations.
- */
-declare class TelemetryClient {
-    private config;
-    private logger;
-    constructor(config: TelemetryConfig);
-    /**
-     * Send telemetry event to analytics service
-     *
-     * Fire-and-forget: Errors are logged but don't throw.
-     */
-    send(event: TelemetryEvent): Promise<void>;
-}
-
-/**
- * Granular telemetry configuration options
- */
-interface TelemetryOptions {
-    /** Enable telemetry (default: true) */
-    enabled?: boolean;
-    /** Record input text in telemetry (default: false) */
-    recordInputs?: boolean;
-}
-/**
- * Base configuration for all evaluators
- */
-interface BaseEvaluatorConfig {
-    /** Google API key (for evaluators using Gemini) */
-    googleApiKey?: string;
-    /** OpenAI API key (for evaluators using GPT) */
-    openaiApiKey?: string;
-    /** Learning Commons partner key for authenticated telemetry (optional) */
-    partnerKey?: string;
-    /**
-     * Maximum number of retries for failed API calls (default: 2)
-     * Set to 0 to disable retries.
-     *
-     * Note: With maxRetries=2, a failed call will be attempted up to 3 times total
-     * (1 initial attempt + 2 retries)
-     */
-    maxRetries?: number;
-    /**
-     * Telemetry configuration (default: all enabled)
-     *
-     * Can be:
-     * - `true`: Enable with defaults (recordInputs: false)
-     * - `false`: Disable completely
-     * - `TelemetryOptions`: Granular control
-     */
-    telemetry?: boolean | TelemetryOptions;
-    /**
-     * Custom logger implementation (optional)
-     * If not provided, uses console logger with specified logLevel
-     */
-    logger?: Logger;
-    /**
-     * Log level for default console logger (default: WARN)
-     * Only used if custom logger is not provided
-     *
-     * - DEBUG: Very verbose, shows all operations
-     * - INFO: Normal operations
-     * - WARN: Warnings only (default)
-     * - ERROR: Errors only
-     * - SILENT: No logging
-     */
-    logLevel?: LogLevel;
-}
-/**
- * Evaluator metadata interface
- * Each evaluator must provide this metadata as static properties
- */
-interface EvaluatorMetadata {
-    /** Unique identifier for the evaluator (e.g., 'vocabulary', 'sentence-structure') */
-    readonly id: string;
-    /** Human-readable name (e.g., 'Vocabulary', 'Sentence Structure') */
-    readonly name: string;
-    /** Brief description of what the evaluator does */
-    readonly description: string;
-    /** Supported grade levels (e.g., ['3', '4', '5', ...]) */
-    readonly supportedGrades: readonly string[];
-    /** Whether this evaluator requires a Google API key */
-    readonly requiresGoogleKey: boolean;
-    /** Whether this evaluator requires an OpenAI API key */
-    readonly requiresOpenAIKey: boolean;
-}
-/**
- * Abstract base class for all evaluators
- *
- * Provides common functionality:
- * - Telemetry setup and event sending
- * - Text validation
- * - Grade validation (with overridable default)
- * - Metadata creation
- *
- * Concrete evaluators must implement:
- * - static metadata: Provide evaluator metadata (see EvaluatorMetadata interface)
- */
-declare abstract class BaseEvaluator {
-    protected telemetryClient?: TelemetryClient;
-    protected logger: Logger;
-    protected config: Required<Pick<BaseEvaluatorConfig, 'maxRetries'>> & {
-        telemetry: Required<TelemetryOptions>;
-    };
-    /**
-     * Static metadata for the evaluator
-     *
-     * Concrete evaluators MUST define this property.
-     *
-     * @example
-     * ```typescript
-     * class MyEvaluator extends BaseEvaluator {
-     *   static readonly metadata = {
-     *     id: 'my-evaluator',
-     *     name: 'My Evaluator',
-     *     description: 'Does something useful',
-     *     supportedGrades: ['3', '4', '5'],
-     *     requiresGoogleKey: true,
-     *     requiresOpenAIKey: false,
-     *   };
-     * }
-     * ```
-     */
-    static readonly metadata: EvaluatorMetadata;
-    constructor(config: BaseEvaluatorConfig);
-    /**
-     * Get metadata for this evaluator instance
-     * @throws {ConfigurationError} If the subclass has not defined static metadata
-     */
-    protected get metadata(): EvaluatorMetadata;
-    /**
-     * Validate that required API keys are provided based on metadata
-     * @throws {ConfigurationError} If required API keys are missing
-     */
-    private validateApiKeys;
-    /**
-     * Normalize telemetry config to standard format
-     */
-    private normalizeTelemetryConfig;
-    /**
-     * Get the evaluator type identifier from metadata
-     * @returns The evaluator type ID (e.g., "vocabulary", "sentence-structure")
-     */
-    protected getEvaluatorType(): string;
-    /**
-     * Validate text meets requirements
-     * Default implementation - can be overridden by concrete evaluators
-     *
-     * @throws {ValidationError} If text is invalid
-     */
-    protected validateText(text: string): void;
-    /**
-     * Validate grade is in supported range
-     * Default implementation - can be overridden by concrete evaluators
-     *
-     * @param grade - Grade level to validate
-     * @param validGrades - Set of valid grades for this evaluator
-     * @throws {ValidationError} If grade is invalid
-     */
-    protected validateGrade(grade: string, validGrades: Set<string>): void;
-    /**
-     * Send telemetry event to analytics service
-     * Common helper for all evaluators
-     */
-    protected sendTelemetry(params: {
-        status: 'success' | 'error';
-        latencyMs: number;
-        textLength: number;
-        grade?: string;
-        provider: string;
-        errorCode?: string;
-        tokenUsage?: TokenUsage;
-        metadata?: TelemetryMetadata;
-        inputText?: string;
-    }): Promise<void>;
-}
-
 /**
  * Vocabulary Evaluator
  *
@@ -887,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;
@@ -901,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>>;
@@ -967,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
@@ -980,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>>;
@@ -1045,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);
@@ -1056,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>>;
@@ -1104,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);
@@ -1116,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>>;
@@ -1167,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);
@@ -1179,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>>;
@@ -1250,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;
@@ -1269,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>;
@@ -1296,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()
@@ -1326,4 +1065,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, 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 };
+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 };