> ## 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.

# Configuration

> Configure evaluator constructors in the TypeScript SDK, including required API keys, modelOverride, llmProvider, and telemetry.

Import and configure the evaluator of your choice.

```typescript example.ts theme={null}
import { GradeLevelAppropriatenessEvaluator } from "@learning-commons/evaluators";

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

## Options

> [!NOTE]
>
> 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](https://docs.learningcommons.org/evaluators/text-complexity-evaluators/grade-level-appropriateness.md) 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](https://docs.learningcommons.org/evaluators/getting-started/quickstart.md#required-api-keys) when being configured (e.g., `googleApiKey`, `openaiApiKey`, etc.).
>
> We recommend using the validated provider and model, but you can override that default with the
> `modelOverride` option, or inject your own provider with `llmProvider`.

| 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` |
| `learningCommonsApiKey` v1.0.0 | `string` | [Learning Commons API key](https://platform.learningcommons.org/api-keys) ↗, **required** for all evaluators that call the [Learning Commons REST API](https://docs.learningcommons.org/api-reference/) (e.g., [Academic Standards evaluators](https://docs.learningcommons.org/evaluators/academic-standards-evaluators)) For [telemetry](#telemetry), set `learningCommonsApiKey` on the `telemetry` option instead. |
| `modelOverride` v0.5.0 | [`ModelOverride`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/typescript/src/evaluators/base.ts) | Overrides the evaluator's default provider and model. Both `provider` and `model` are required. Cannot be set together with `llmProvider`. |
| `llmProvider` | [`LLMProvider`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/typescript/src/providers/base.ts) | Inject your own LLM provider. The evaluator routes every LLM call through it and skips built-in API-key adapters. Cannot be set together with `modelOverride`. For evaluators that take images, like the [Graphics evaluators](https://docs.learningcommons.org/evaluators/graphics-evaluators/introduction.md), your provider must set `supportsAttachments` and accept image attachments (`ImageAttachment`). Otherwise, the evaluator throws a `ConfigurationError` when you create it. |
| `maxRetries` | `number` | **Default:** `2`. Maximum retry attempts for failed evaluator calls |
| `logger` | [`Logger`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/typescript/src/logger.ts) | [Custom logger](#custom-logger) for evaluator output |
| `logLevel` | [`LogLevel`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/typescript/src/logger.ts) | **Default:** `WARN`. [Logging verbosity level](#log-level) |
| `telemetry` | `boolean \|` [`TelemetryOptions`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/typescript/src/evaluators/base.ts) | **Default:** `true`. Configuration for collecting [telemetry](#telemetry). Use `{ learningCommonsApiKey }` to attribute events to your Learning Commons user; omit the key for anonymous events. |

> [!NOTE]
>
> Evaluators are validated and tested against their default models. Results with
> other models (using `modelOverride` or `llmProvider`) may vary.

### Math Standards Alignment

The [Math Standards Alignment](https://docs.learningcommons.org/evaluators/academic-standards-evaluators/math-standards-alignment.md) evaluator accepts extra options:

| Field | Type | Description |
| :- | :- | :- |
| `learningCommonsApiKey` | `string` | **Required.** Learning Commons API key used to query Knowledge Graph |
| `concurrency` | `number` | **Default:** `10`. Max concurrent LLM calls |
| `kgConcurrency` | `number` | **Default:** `20`. Max concurrent Knowledge Graph HTTP calls |
| `coarseFilterModel` | `string` | Model for the coarse pre-filter only. `modelOverride` replaces both this model and the main model. |

## Logging

Customize how your evaluator logs information.

### Log level

Control logging verbosity:

```typescript theme={null}
import {
  GradeLevelAppropriatenessEvaluator,
  LogLevel,
} from "@learning-commons/evaluators";

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

### Custom logger

You can configure your evaluator with a custom logger:

```typescript theme={null}
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](#options).

### What you'll need

> [!NOTE]
>
> While telemetry data collection is not required, we recommend enabling it so
> that we can better support your team's use cases.

Telemetry is on by default. Events are anonymous unless you set `learningCommonsApiKey` on the `telemetry` option.

To attribute events to your Learning Commons user, [generate an API key](https://platform.learningcommons.org/api-keys/) ↗ and include it in your evaluator's [configuration options](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/configuration.md#options):

```typescript theme={null}
const evaluator = new GradeLevelAppropriatenessEvaluator({
  googleApiKey: process.env.GOOGLE_API_KEY,
  telemetry: {
    enabled: true,
    learningCommonsApiKey: process.env.LEARNING_COMMONS_API_KEY,
  },
});
```

**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., `"text_complexity.ela_reading.vocabulary_complexity"`) |
| `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"`) |
| `model_override` | `true` if the caller supplied a `modelOverride`; omitted otherwise |
| `token_usage` | Total tokens consumed (input and output) |
| `metadata.stage_details` | Per-stage breakdown for multi-stage evaluators (optional) |

```json payload.json theme={null}
{
  "timestamp": "2026-02-05T19:30:00.000Z",
  "sdk_version": "0.1.0",
  "evaluator_type": "text_complexity.ela_reading.vocabulary_complexity",
  "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
        }
      }
    ]
  }
}
```

## Related topics

> [card] [Quickstart](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/quickstart.md)
>
> Install the SDK and run your first evaluator.

> [card] [Outputs](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/evaluation.md)
>
> Understand evaluator output fields and types.

> [card] [Error handling](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/error-handling.md)
>
> Handle configuration, validation, and API errors.

> [card] [Batch evaluator](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/batch-evaluator.md)
>
> Evaluate a batch of text from a CSV file using Text Complexity evaluators.