Configuration

Import and configure the evaluator of your choice.

example.ts

import { GradeLevelAppropriatenessEvaluator } from "@learning-commons/evaluators";

const evaluator = new GradeLevelAppropriatenessEvaluator({
  googleApiKey: process.env.GOOGLE_API_KEY,
});

Options

Our evaluators are validated against a particular provider and model during development. Evaluators default to that same provider and model at runtime – for example, Grade Level Appropriateness will always use Google Gemini out of the box, because it was validated against Google Gemini during development. As a result, each evaluator requires specific API keys when being configured (e.g., googleApiKey, openaiApiKey, etc.).We recommend using the validated provider and model, but the SDK does allow you to override that default with the modelOverride option.

Field	Type	Description
`googleApiKey`	`string`	Google API key, required for evaluators that default to Google models
`openaiApiKey`	`string`	OpenAI API key, required for evaluators that default to OpenAI models
`anthropicApiKey`	`string`	Anthropic API key, required for evaluators that default to Claude or when `modelOverride` is set to `Provider.Anthropic`
`modelOverride` v0.5.0	`ModelOverride`	Overrides the evaluator’s default provider and model
`maxRetries`	`number`	Default: `2`. Maximum retry attempts for failed evaluator calls
`telemetry`	`boolean \|` `TelemetryOptions`	Default: `true`. Configuration for collecting telemetry
`logger`	`Logger`	Custom logger for evaluator output
`logLevel`	`LogLevel`	Default: `WARN`. Logging verbosity level
`partnerKey`	`string`	Your Learning Commons API key, used for authenticated telemetry data collection. Create your API key on the Learning Commons Platform.

Evaluators are validated and tested against their default models. Results with other models (using modelOverride) may vary.

Logging

Customize how your evaluator logs information.

Log level

Control logging verbosity:

import {
  GradeLevelAppropriatenessEvaluator,
  LogLevel,
} from "@learning-commons/evaluators";

const evaluator = new GradeLevelAppropriatenessEvaluator({
  googleApiKey: "...",
  logLevel: LogLevel.INFO, // SILENT | ERROR | WARN | INFO | DEBUG
});

Custom logger

You can configure your evaluator with a custom logger:

import {
  GradeLevelAppropriatenessEvaluator,
  type Logger,
} from "@learning-commons/evaluators";

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 GradeLevelAppropriatenessEvaluator({
  googleApiKey: "...",
  logger: customLogger,
});

Telemetry

We collect limited usage and performance telemetry by default. This may include performance metrics (latency, token usage), technical metadata (such as SDK version and evaluator type) and related diagnostic information. This telemetry helps us improve evaluator quality, identify edge cases, and optimize performance. You can disable telemetry collection through the configuration options.

What you’ll need

While telemetry data collection is not required, we recommend enabling it so that we can better support your team’s use cases.

Create an API key in the Learning Commons Platform ↗ and include this key in your evaluator’s configuration options. We don’t collect your API keys or any user identifiers through the SDK.

What we collect

Field	Description
`timestamp`	ISO 8601 timestamp when evaluation started
`sdk_version`	SDK version (e.g., `"0.1.0"`)
`evaluator_type`	Which evaluator ran (e.g., `"vocabulary"`, `"sentence-structure"`)
`grade`	Grade level evaluated (e.g., `"5"`, `"K"`)
`status`	Evaluation outcome (`"success"` or `"error"`)
`error_code`	Error type if status is `"error"` (e.g., `"Error"`, `"TypeError"`)
`latency_ms`	Total evaluation time in milliseconds
`text_length_chars`	Length of input text in characters
`provider`	LLM provider(s) used (e.g., `"openai:gpt-4o"`, `"google:gemini-2.5-pro"`)
`token_usage`	Total tokens consumed (input and output)
`input_text` Opt in	Text being evaluated (only included if the `telemetry` configuration option is set to `{ enabled: true, recordInputs: true }`). Developers are responsible for ensuring that any content they choose to share complies with applicable law and does not include sensitive or regulated information unless they have appropriate authorization to provide it.
`metadata.stage_details`	Per-stage breakdown for multi-stage evaluators (optional)

payload.json

{
  "timestamp": "2026-02-05T19:30:00.000Z",
  "sdk_version": "0.1.0",
  "evaluator_type": "vocabulary",
  "grade": "3",
  "status": "success",
  "latency_ms": 3500,
  "text_length_chars": 456,
  "provider": "openai:gpt-4o-2024-11-20 + google:gemini-2.5-pro",
  "token_usage": {
    "input_tokens": 650,
    "output_tokens": 350
  },
  "metadata": {
    "stage_details": [
      {
        "stage": "background_knowledge",
        "provider": "openai:gpt-4o-2024-11-20",
        "latency_ms": 1200,
        "token_usage": {
          "input_tokens": 250,
          "output_tokens": 150
        }
      },
      {
        "stage": "complexity_evaluation",
        "provider": "google:gemini-2.5-pro",
        "latency_ms": 2300,
        "token_usage": {
          "input_tokens": 400,
          "output_tokens": 200
        }
      }
    ]
  }
}

Understanding evaluators

Getting started

SDK API Reference

Literacy evaluators

Feedback evaluators

Standards evaluators

Datasets

Resources

Options

Logging

Log level

Custom logger

Telemetry

What you’ll need

What we collect

​Options

​Logging

​Log level

​Custom logger

​Telemetry

​What you’ll need

​What we collect

Options

Logging

Log level

Custom logger

Telemetry

What you’ll need

What we collect