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

# Quickstart

> Install the @learning-commons/evaluators npm package and the provider adapters it needs, then run the Grade Level Appropriateness evaluator in TypeScript.

The TypeScript SDK lets you use evaluators in your own project:

* Configure and run evaluators
* Understand their outputs
* Evaluate text in batches
* Customize logging and handle errors

> [!NOTE]
>
> [Contact us](mailto:support@learningcommons.org) ↗ to request additional
> SDK language support. You can also [sign up for a Platform
> account](http://platform.learningcommons.org/) ↗ to receive updates on
> availability.

## Install the SDK

| | Latest release |
| - | - |
| [GitHub](https://github.com/learning-commons-org/evaluators/tree/main/sdks/typescript#dependencies) ↗ | [![npm version](https://img.shields.io/npm/v/@learning-commons/evaluators)](https://www.npmjs.com/package/@learning-commons/evaluators) |

Install the SDK from the package registry rather than cloning the [evaluators repository](https://github.com/learning-commons-org/evaluators) ↗. The published package is versioned, so you can pick up fixes and new evaluators with a standard package update:

```bash theme={null}
npm install @learning-commons/evaluators@latest

# Then the provider adapter for the evaluators you use. These are optional peer
# dependencies, so npm does not install them for you.
npm install @ai-sdk/google    # Text Complexity evaluators (except Sentence Structure) and Graphics evaluators
npm install @ai-sdk/openai    # Feedback evaluators, Sentence Structure, Vocabulary Complexity
npm install @ai-sdk/anthropic # Math Standards Alignment
```

Vocabulary Complexity uses two models, so it needs both `@ai-sdk/google` and `@ai-sdk/openai`.

> [!NOTE]
>
> Each evaluator calls the provider it was validated against. Without that
> provider's adapter installed you'll see `ConfigurationError: To use the   <provider> provider, install its adapter`.

## Run an evaluator

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

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

const { result } = await evaluator.evaluate({
  text: "The cat's out of the bag now.",
});

console.log(result.grade_band); // e.g. 2-3
```

## Related topics

> [card] [Supported evaluators](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/supported-evaluators.md)
>
> See which evaluators the TypeScript SDK includes, and which API keys they
> need.

> [card] [Configuration](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/configuration.md)
>
> Configure evaluators, including API keys and options.

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

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