> ## 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 Python SDK evaluator input and output fields across Text Complexity, Feedback, and Academic Standards.

export const PiiWarning = () => {
  return <Warning>
      Inputs must be de-identified. Do not submit students' Personally
      Identifiable Information (PII) or any regulated or sensitive personal
      information.
    </Warning>;
};

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

```python example.py theme={null}
from learning_commons_evaluators import (
  GradeLevelAppropriatenessEvaluator,
  GradeLevelAppropriatenessInput,
)

evaluator = GradeLevelAppropriatenessEvaluator(google_api_key="your-google-key")

result = evaluator.evaluate_sync(
  GradeLevelAppropriatenessInput(text="The cat's out of the bag now.")
)
```

## Inputs

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

### Text Complexity

[Grade Level Appropriateness](/evaluators/text-complexity-evaluators/grade-level-appropriateness) takes `{ text }`:

| Field | Type | Description |
| :- | :- | :- |
| `text` | `string` | Informational text to evaluate. 10–10,000 characters |

All other Text Complexity evaluators take `{ text, grade_level }`:

| Field | Type | Description |
| :- | :- | :- |
| `text` | `string` | Informational text to evaluate. Length limits vary by evaluator (typically 1–10,000 characters) |
| `grade_level` | `int` | Target student grade, 3–12. Passed as an integer |

```python theme={null}
from learning_commons_evaluators import (
  VocabularyComplexityEvaluator,
  VocabularyComplexityInput,
)

evaluator = VocabularyComplexityEvaluator(
  openai_api_key="your-openai-key",
  google_api_key="your-google-key",
)

result = evaluator.evaluate_sync(
  VocabularyComplexityInput(text="The cat's out of the bag now.", grade_level=5)
)
```

### Feedback

<PiiWarning />

[Feedback](/evaluators/feedback-evaluators/introduction) evaluators take `{ student_text, feedback_text }`:

| 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

<PiiWarning />

[Math Standards Alignment](/evaluators/academic-standards-evaluators/math-standards-alignment) has two entry points, depending on how you name the standard.

#### evaluate() — by CASE UUID

| 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` |

```python theme={null}
from learning_commons_evaluators import MathStandardsAlignmentEvaluator

evaluator = MathStandardsAlignmentEvaluator(
  anthropic_api_key="your-anthropic-key",
  learning_commons_api_key="your-learning-commons-key",
)

result = evaluator.evaluate_sync(
  question="What is 3/4 + 1/8?",
  case_identifier_uuid="6ba25656-d7cc-11e8-824f-0242ac160002",
)
```

#### evaluate\_by\_code() — by standard code

Only `question` and `statement_code` are required.

| 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/python/src/learning_commons_evaluators/schemas/kg_taxonomy.py) ↗ | Optional. Whose framework the code belongs to ([`JurisdictionENUM`](/knowledge-graph/schema-reference/enums-and-formats#jurisdictionenum)). Defaults to `Jurisdiction.MULTI_STATE`, which is <Tooltip tip="Common Core State Standards">CCSS</Tooltip> |
| `grade_level` | `string` | Optional, `"K"` through `"12"`. Only consulted when a code names more than one standard, which happens when a framework reuses codes across courses |

```python theme={null}
import asyncio

from learning_commons_evaluators import MathStandardsAlignmentEvaluator

evaluator = MathStandardsAlignmentEvaluator(
  anthropic_api_key="your-anthropic-key",
  learning_commons_api_key="your-learning-commons-key",
)

result = asyncio.run(
  evaluator.evaluate_by_code(
    question="What is 3/4 + 1/8?",
    statement_code="5.NF.A.1",
  )
)
```

## Output

All [Text Complexity](/evaluators/text-complexity-evaluators/introduction), [Feedback](/evaluators/feedback-evaluators/introduction), and [Academic Standards](/evaluators/academic-standards-evaluators/introduction) evaluators have the following output fields:

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

## Related topics

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/evaluators/getting-started/quickstart#sdk">
    Install the SDK and run your first evaluator.
  </Card>

  <Card title="Configuration" icon="gear" href="/evaluators/sdk-api-reference/python/configuration">
    Configure evaluators, including API keys and options.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/evaluators/sdk-api-reference/python/error-handling">
    Handle configuration, validation, and API errors.
  </Card>
</CardGroup>