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

# Evaluation

> Reference for TypeScript SDK evaluator input and output fields across Text Complexity, Feedback, Academic Standards, and Graphics.

Once you've configured your evaluator, you can start evaluating text inputs for grade level appropriateness:

```typescript example.ts theme={null}
const evaluator = new GradeLevelAppropriatenessEvaluator({
  googleApiKey: process.env.GOOGLE_API_KEY,
});

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

## Inputs

> [!WARNING]
>
> Inputs must be de-identified. Do not submit students' Personally
> Identifiable Information (PII) or any regulated or sensitive personal
> information.

Each evaluator requires different input fields when invoking `evaluate()`.

### [Text Complexity evaluators](https://docs.learningcommons.org/evaluators/text-complexity-evaluators/introduction.md)

> [tab] Grade Level Appropriateness
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `text` | `string` | Informational text to evaluate (10–10,000 characters) |

> [tab] Others
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `text` | `string` | Informational text to evaluate. Length limits vary by evaluator (typically 1–10,000 characters) |
> | `grade_level` | `"3" \| "4" \| "5" \| "6" \| "7" \| "8" \| "9" \| "10" \| "11" \| "12"` | Target student grade as a string literal. A number or a word like `"fifth"` does not compile; a string from a form or database needs narrowing before you pass it |
>
> ```typescript theme={null}
> import { VocabularyComplexityEvaluator } from "@learning-commons/evaluators";
>
> const evaluator = new VocabularyComplexityEvaluator({
>   openaiApiKey: process.env.OPENAI_API_KEY,
>   googleApiKey: process.env.GOOGLE_API_KEY,
> });
>
> await evaluator.evaluate({
>   text: "The cat's out of the bag now.",
>   grade_level: "5",
> });
> ```

### [Graphics evaluators](https://docs.learningcommons.org/evaluators/graphics-evaluators/introduction.md)

v1.2.0

See [`InputValidationError`](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/error-handling#inputvalidationerror) to debug instances where an image fails a check before the model call.

> [tab] Graphics Accuracy
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `image_paths` | `string[]` | Local path to the image to check, as a one-item array. PNG, JPEG, or WebP, 64 bytes to 5 MB, with width and height each 16–2,560 pixels |
> | `claim` | `string` | What the image should show: a statement about the image, or a question with its expected answer. 1–12,000 characters |
>
> ```typescript theme={null}
> import {
>   GraphicsAccuracyEvaluator,
>   composeGraphicsAccuracyClaim, // Produces the exact wording the evaluator was tested with
> } from "@learning-commons/evaluators";
>
> const evaluator = new GraphicsAccuracyEvaluator({
>   googleApiKey: process.env.GOOGLE_API_KEY,
> });
>
> await evaluator.evaluate({
>   image_paths: ["figures/apples.png"],
>   claim: composeGraphicsAccuracyClaim(
>     "How many apples do all the trees have together?",
>     "9",
>   ),
> });
> ```

> [tab] Graphics Complexity
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `text` | `string` | Informational text that the graphics accompany. 1–10,000 characters |
> | `grade_level` | `"3" \| "4" \| "5" \| "6" \| "7" \| "8" \| "9" \| "10" \| "11" \| "12"` | Target student grade as a string literal |
> | `image_paths` | `string[]` | Local paths to the passage's graphics, one per graphic, in reading order. 1–5 images. PNG, JPEG, or WebP, 64 bytes to 2.5 MB, with width and height each 16–8,000 pixels |
> | `figure_labels` | `string` | Optional. Comma-separated labels in the same order as `image_paths` (e.g., `"Figure 1, Figure 2"`). Defaults to `Image 1`, `Image 2`, and so on |
>
> ```typescript theme={null}
> import { GraphicsComplexityEvaluator } from "@learning-commons/evaluators";
>
> const evaluator = new GraphicsComplexityEvaluator({
>   googleApiKey: process.env.GOOGLE_API_KEY,
> });
>
> await evaluator.evaluate({
>   text: "Beekeepers in the United States report losing hives at rates they have not seen before.",
>   grade_level: "5",
>   image_paths: ["figures/hive-losses.png"],
>   figure_labels: "Figure 1",
> });
> ```

### [Feedback evaluators](https://docs.learningcommons.org/evaluators/feedback-evaluators/introduction.md)

| Field | Type | Description |
| :- | :- | :- |
| `student_text` | `string` | Student's written response. 1–10,000 characters |
| `feedback_text` | `string` | Teacher or AI feedback to evaluate. 1–10,000 characters |

### [Academic Standards evaluators](https://docs.learningcommons.org/evaluators/academic-standards-evaluators/introduction.md)

The Academic Standards evaluators have 2 entry points, depending on how the standard is named:

* `evaluateByUuid()` - By the standard's CASE UUID
* `evaluate()` - By the standard's code. `evaluateByCode()` is the same call

> [tab] evaluateByUuid()
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `question` | `string` | Math assessment question to evaluate. 1–10,000 characters |
> | `case_identifier_uuid` | `string` | CASE Network UUID of the math standard — the Knowledge Graph's `caseIdentifierUUID` |
>
> ```typescript theme={null}
> import { MathStandardsAlignmentEvaluator } from "@learning-commons/evaluators";
>
> const evaluator = new MathStandardsAlignmentEvaluator({
>   anthropicApiKey: process.env.ANTHROPIC_API_KEY,
>   learningCommonsApiKey: process.env.LEARNING_COMMONS_API_KEY,
> });
>
> await evaluator.evaluateByUuid({
>   question: "What is 3/4 + 1/8?",
>   case_identifier_uuid: "6ba25656-d7cc-11e8-824f-0242ac160002",
> });
> ```

> [tab] evaluate()
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `question` | `string` | Math assessment question to evaluate. 1–10,000 characters |
> | `statement_code` | `string` | Math standard code, spelled as its jurisdiction spells it (e.g., `"3.MD.C.7.d"`, `"K.CC.A.1"`). 1–50 characters |
> | `jurisdiction` | [`Jurisdiction`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/typescript/src/knowledge-graph/types.ts) ↗ | Whose framework the code belongs to ([`JurisdictionENUM`](https://docs.learningcommons.org/knowledge-graph/schemas/enums-and-formats#jurisdictionenum)). Use `Jurisdiction.MultiState`, which is CCSS (Common Core State Standards) |
>
> ```typescript theme={null}
> import {
>   Jurisdiction,
>   MathStandardsAlignmentEvaluator,
> } from "@learning-commons/evaluators";
>
> const evaluator = new MathStandardsAlignmentEvaluator({
>   anthropicApiKey: process.env.ANTHROPIC_API_KEY,
>   learningCommonsApiKey: process.env.LEARNING_COMMONS_API_KEY,
> });
>
> await evaluator.evaluate({
>   question: "A playground is shaped like an L. What is its area?",
>   statement_code: "3.MD.C.7.d",
>   jurisdiction: Jurisdiction.MultiState,
> });
> ```

[Math Standards Alignment](https://docs.learningcommons.org/evaluators/academic-standards-evaluators/math-standards-alignment.md) also supports bulk methods:

* `evaluateItems` for question–standard pairs
* `evaluateByGradeLevel` for a question bank against every standard in a grade

## Output

All evaluators return the following fields:

| Field | Type | Description |
| :- | :- | :- |
| `evaluator` | `string` | Registry ID for the evaluator used |
| `result` | Unique to each evaluator See "Output" for each evaluator (e.g., for [Grade Level Appropriateness](https://docs.learningcommons.org/evaluators/text-complexity-evaluators/grade-level-appropriateness.md#output)) | Detailed internal analysis data specific to each evaluator |
| `metadata` | [`EvaluationMetadata`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/typescript/src/schemas/outputs.ts) ↗ | Includes model used to generate the evaluation, total evaluation processing time in milliseconds, input tokens, and output tokens |

## Related topics

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

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

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