Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.learningcommons.org/llms.txt

Use this file to discover all available pages before exploring further.

Import and configure the evaluator of your choice.
example.ts
import { VocabularyEvaluator } from "@learning-commons/evaluators";

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

​
Options

All evaluators accept some base configuration options.
Get the Required API keys for the evaluators you want to use.
FieldTypeDescription
googleApiKeystringGoogle API key, required for evaluators that default to Google models
openaiApiKeystringOpenAI API key, required for evaluators that default to OpenAI models
anthropicApiKeystringAnthropic API key, required for evaluators that default to Claude or when modelOverride is set to Provider.Anthropic
modelOverrideModelOverrideOverrides the evaluator’s default provider and model
maxRetriesnumberDefault: 2. Maximum retry attempts for failed evaluator calls
telemetryboolean | TelemetryOptionsDefault: true. Configuration for collecting telemetry
loggerLoggerCustom logger for evaluator output
logLevelLogLevelDefault: WARN. Logging verbosity level
partnerKeystringYour 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 { VocabularyEvaluator, LogLevel } from "@learning-commons/evaluators";

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

​
Custom logger

You can configure your evaluator with a custom logger: 
import 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 VocabularyEvaluator({
  googleApiKey: "...",
  openaiApiKey: "...",
  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

FieldDescription
timestampISO 8601 timestamp when evaluation started
sdk_versionSDK version (e.g., "0.1.0")
evaluator_typeWhich evaluator ran (e.g., "vocabulary", "sentence-structure")
gradeGrade level evaluated (e.g., "5", "K")
statusEvaluation outcome ("success" or "error")
error_codeError type if status is "error" (e.g., "Error", "TypeError")
latency_msTotal evaluation time in milliseconds
text_length_charsLength of input text in characters
providerLLM provider(s) used (e.g., "openai:gpt-4o", "google:gemini-2.5-pro")
token_usageTotal tokens consumed (input and output)
input_text Opt inText 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_detailsPer-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
        }
      }
    ]
  }
}