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

> Understand input & output fields returned by Python SDK Student-Facing Text evaluators.

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,
  GradeLevelAppropriatenessEvaluationInput,
  GooglePromptProviderConfig,
  create_config,
)

# Create evaluator config
# NOTE: Telemetry is not yet implemented in v0.2.0
config = create_config(
  google_llm_provider_config=GooglePromptProviderConfig(api_key="your-google-key"),
  telemetry_partner_id="your-learning-commons-api-key",
)

# Instantiate evaluator
evaluator = GradeLevelAppropriatenessEvaluator(config)

# Evaluate text for grade level appropriateness
result = evaluator.evaluate(
  GradeLevelAppropriatenessEvaluationInput(text="The cat's out of the bag now.")
)
```

## Inputs

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

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

All other Student-Facing Text 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` | `"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 |

```python theme={null}
result = evaluator.evaluate(
  VocabularyEvaluationInput(text="The cat's out of the bag now.", grade=5)
)
```

## Output

[Student-Facing Text](/evaluators/student-facing-text-evaluators/introduction) evaluators have the following output fields:

| Field         | Type                                                                                                                                                       | Description                                                                                                |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
| `answer`      | [`EvaluationAnswer`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/python/src/learning_commons_evaluators/schemas/evaluator.py) ↗      | Complexity score returned by the evaluation                                                                |
| `explanation` | [`EvaluationExplanation`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/python/src/learning_commons_evaluators/schemas/evaluator.py) ↗ | Reasoning for the complexity score and evaluator-specific fields (`explanation.details` – see table below) |
| `metadata`    | [`EvaluationMetadata`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/python/src/learning_commons_evaluators/schemas/metadata.py) ↗     | Evaluation run metadata like timing, status, token usage, and per-step details                             |

The `explanation.details` field includes detailed internal analysis data specific to that evaluator.

| Evaluator                                                                                                                                  | `explanation.details` description                                                              | `explanation.details` type                                                                                                                                                             |
| :----------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Grade Level Appropriateness](/evaluators/student-facing-text-evaluators/grade-level-appropriateness)  <Badge color="green">v0.2.0</Badge> | [Output fields](/evaluators/student-facing-text-evaluators/grade-level-appropriateness#output) | [`GradeLevelAppropriatenessOutput`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/python/src/learning_commons_evaluators/schemas/grade_level_appropriateness.py) ↗ |
| [Vocabulary Complexity](/evaluators/student-facing-text-evaluators/vocabulary-complexity)                                                  | [Output fields](/evaluators/student-facing-text-evaluators/vocabulary-complexity#output)       | [`VocabularyComplexityOutput`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/python/src/learning_commons_evaluators/schemas/vocabulary.py)                         |
| [Meaning Directness](/evaluators/student-facing-text-evaluators/meaning-directness)                                                        | [Output fields](/evaluators/student-facing-text-evaluators/meaning-directness#output)          | [`ConventionalityOutput`](https://github.com/learning-commons-org/evaluators/blob/main/sdks/python/src/learning_commons_evaluators/schemas/conventionality.py)                         |

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