Evaluation

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

example.ts

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

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

Inputs

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

Grade Level Appropriateness
Others

Field	Type	Description
`text`	`string`	Informational text to evaluate (10–10,000 characters)

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

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

v1.2.0 See InputValidationError to debug instances where an image fails a check before the model call.

Graphics Accuracy
Graphics Complexity

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

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",
  ),
});

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

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

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

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

evaluateByUuid()
evaluate()

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`

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",
});

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` ↗	Whose framework the code belongs to (`JurisdictionENUM`). Use `Jurisdiction.MultiState`, which is

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 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)	Detailed internal analysis data specific to each evaluator
`metadata`	`EvaluationMetadata` ↗	Includes model used to generate the evaluation, total evaluation processing time in milliseconds, input tokens, and output tokens

Quickstart

Install the SDK and run your first evaluator.

Configuration

Configure evaluators, including API keys and options.

Error handling

Handle configuration, validation, and API errors.

Batch evaluator

Evaluate a batch of text from a CSV file using Text Complexity evaluators.

Understanding evaluators

Getting started

SDK API reference

Text Complexity evaluators

Graphics evaluators

Feedback evaluators

Academic standards evaluators

Durable skills evaluators

Datasets

Resources

Inputs

Text Complexity evaluators

Graphics evaluators

Feedback evaluators

Academic Standards evaluators

Output

Quickstart

Configuration

Error handling

Batch evaluator

​Inputs

​Text Complexity evaluators

​Graphics evaluators

​Feedback evaluators

​Academic Standards evaluators

​Output

​Related topics

Quickstart

Configuration

Error handling

Batch evaluator

Inputs

Text Complexity evaluators

Graphics evaluators

Feedback evaluators

Academic Standards evaluators

Output

Related topics