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

> Run your first Literacy evaluator on text using the Evaluators playground, TypeScript or Python SDK, or a Python notebook, then review results.

export const EarlyAccess = ({isBreaking = true}) => {
  return <div className="eyebrow-callout not-prose rounded-xl border border-gray-200/80 p-5 dark:border-white/10 flex gap-5 items-center" style={{
    marginBottom: "1rem",
    borderRadius: "4px"
  }}>
      <div className="mb-3">
        <Badge color="green" size="md" icon="flask">
          <span className="whitespace-nowrap">Early access</span>
        </Badge>
      </div>
      <div className="callout-body text-[15px] leading-relaxed text-gray-700 dark:text-gray-300">
        This functionality is actively evolving.{" "}
        {isBreaking ? "Breaking changes" : "Changes"} may occur as we expand
        capabilities and improve accuracy and reliability. Email{" "}
        <a href="mailto:support@learningcommons.org">
          support@learningcommons.org
        </a>{" "}
        ↗ with your feedback or issues.
      </div>
      <style>{`.callout-body a { text-decoration: underline; text-decoration-color: #178251; }`}</style>
    </div>;
};

## What you'll do

Run our [Student-Facing Text evaluators](/evaluators/student-facing-text-evaluators/introduction) on some text to evaluate it for a given grade level.

| Method                                          | When to use                                         |
| :---------------------------------------------- | :-------------------------------------------------- |
| [Evaluators playground](#evaluators-playground) | For a quick demo of how evaluators work             |
| [SDK](#sdk)                                     | To integrate into your TypeScript or Python project |
| [Python notebook](#python-notebooks)            | For quick prototyping                               |

## What you'll need

* Text you want to evaluate
* Grade level of the intended audience
* API keys required by the evaluators you want to use <Badge>Not required for [Evaluators playground](#evaluators-playground)</Badge>

### Required API keys

By default, each evaluator uses a provider and model that we have tested for reliability for that task.

As a result, different evaluators require different API keys.

| Evaluator                                                                                                                                                                                                                                                                                     | Required API key(s)                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [Student-Facing Text evaluators](/evaluators/student-facing-text-evaluators/introduction)<br />(except for [Vocabulary Complexity](/evaluators/student-facing-text-evaluators/vocabulary-complexity) and [Sentence Structure](/evaluators/student-facing-text-evaluators/sentence-structure)) | [Google](https://aistudio.google.com/)                                            |
|      [Vocabulary Complexity](/evaluators/student-facing-text-evaluators/vocabulary-complexity)                                                                                                                                                                                                | [Google](https://aistudio.google.com/) and [OpenAI](https://platform.openai.com/) |
|      [Sentence Structure](/evaluators/student-facing-text-evaluators/sentence-structure)                                                                                                                                                                                                      | [OpenAI](https://platform.openai.com/)                                            |
| [Feedback evaluators](/evaluators/feedback-evaluators)                                                                                                                                                                                                                                        | [OpenAI](https://platform.openai.com/)                                            |
| [Academic Standards evaluators](/evaluators/academic-standards-evaluators/introduction)                                                                                                                                                                                                       | [Anthropic](https://claude.ai/)                                                   |

<Note>
  You can override our evaluators' defaults with any
  [Google](https://aistudio.google.com/),
  [OpenAI](https://platform.openai.com/), or [Anthropic](https://claude.ai/)
  model. When overriding with an Anthropic model, an Anthropic API key is
  required.
</Note>

## Steps

<Tabs>
  <Tab title="Evaluators playground">
    <span id="evaluators-playground" />

    The [Evaluators playground](https://platform.learningcommons.org/apps/evaluators/playground) ↗ is the easiest way to see our evaluators in action.

    <Steps>
      <Step title="Select evaluator family">
        Choose the evaluators you want to run on your input (e.g. [Student-Facing Text evaluators](/evaluators/student-facing-text-evaluators/introduction) or [feedback evaluators](/evaluators/feedback-evaluators/introduction)).
      </Step>

      <Step title="Provide inputs">
        **Student-Facing Text evaluators**: Choose the grade level of your intended audience, and copy and paste the content you want to evaluate.

        **Feedback evaluators**: Copy and paste the student text and the feedback text you want to evaluate.
      </Step>

      <Step title="Run the evaluators">
        Click **Evaluate** to run our [Student-Facing Text evaluators](/evaluators/student-facing-text-evaluators/introduction) or [Feedback evaluators](/evaluators/feedback-evaluators/introduction) on your input.
      </Step>

      <Step title="View results">
        Expand each evaluator's results to see its score and reasoning.
      </Step>
    </Steps>

    The Evaluators playground is primarily a demo. Check out the [SDK](#sdk) or [Python notebooks](#python-notebooks) when implementing evaluators into your automated processes.
  </Tab>

  <Tab title="SDK">
    <span id="sdk" />

    <EarlyAccess isBreaking={false} />

    <Steps>
      <Step title="Install the SDK">
        Run evaluators from your project by installing the SDK of your choice.

        | Language   | Installation                                                                                          | Latest version                                                                                                                                                                        |
        | ---------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | TypeScript | [GitHub](https://github.com/learning-commons-org/evaluators/tree/main/sdks/typescript#installation) ↗ | [        <img src="https://img.shields.io/npm/v/@learning-commons/evaluators" alt="npm version" style={{ margin: 0 }} />](https://www.npmjs.com/package/@learning-commons/evaluators) |
        | Python     | [GitHub](https://github.com/learning-commons-org/evaluators/tree/main/sdks/python#installation) ↗     | [        <img src="https://img.shields.io/pypi/v/learning-commons-evaluators" alt="PyPI version" style={{ margin: 0 }} />](https://pypi.org)                                          |

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

        ```bash Update to the latest version theme={null} theme={null} theme={null}
        # TypeScript
        npm install @learning-commons/evaluators@latest

        # Python
        pip install --upgrade learning-commons-evaluators
        ```

        <Note>
          [Contact us](mailto:support@learningcommons.org) ↗ to request additional SDK
          language support. You can also [sign up on the Learning Commons
          Platform](http://platform.learningcommons.org/) ↗
          for updates on availability.
        </Note>
      </Step>

      <Step title="Import and run evaluators">
        Import evaluators to start evaluating text in your project:

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

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

          const text = "The cat's out of the bag now.";

          const result = await evaluator.evaluate(text);
          console.log(result.score); // 4-5
          ```

          ```python Python theme={null} theme={null} theme={null}
          import logging
          from learning_commons_evaluators import (
              GradeLevelAppropriateness,
              GradeLevelAppropriatenessEvaluationInput,
              GoogleLLMProviderConfig,
              create_config_no_telemetry,
          )

          # Logger
          logging.basicConfig(level=logging.INFO)

          # Config with Google API key
          config = create_config_no_telemetry(
            google_llm_provider_config=GoogleLLMProviderConfig(api_key="your-google-key"),
          )

          # Instantiate GradeLevelAppropriatenessEvaluator with created config
          evaluator = GradeLevelAppropriatenessEvaluator(config)

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

          print(result.answer.label) # e.g. "Moderately complex"
          print(result.explanation.summary) # Reasoning for the score

          ```
        </CodeGroup>
      </Step>
    </Steps>

    See the [SDK API reference](/evaluators/sdk-api-reference/overview) for more implementation details.
  </Tab>

  <Tab title="Python notebooks">
    <span id="python-notebooks" />

    <Note>
      The Python interpreter powers our evaluators. All [downloadable
      examples](https://github.com/learning-commons-org/evaluators/tree/main/evals) ↗
      and tutorials are provided as Python snippets.
    </Note>

    <Tabs sync={false}>
      <Tab title="Mac/Linux">
        Install Python 3.10 or newer. To verify your version of Python:

        ```shell theme={null}
        python3 --version
        ```

        <Steps>
          <Step title="Create a virtual environment">
            Creating an isolated environment prevents conflicts between Python packages used in this project and others on your system:

            ```shell theme={null}
            python3 -m venv .venv

            source .venv/bin/activate # Activates environment
            ```

            Remember to activate the virtual environment for each new shell session.
          </Step>

          <Step title="Install dependencies">
            Install all required packages listed in [`requirements.txt`](https://github.com/learning-commons-org/evaluators/blob/main/evals/requirements.txt) ↗:

            ```shell theme={null}
            pip install -r evals/requirements.txt
            ```
          </Step>

          <Step title="Set your API keys">
            Set your API keys as environment variables in your shell session:

            ```shell theme={null}
            export OPENAI_API_KEY="sk-your-key-here"
            export GOOGLE_API_KEY="your-key-here"
            ```
          </Step>

          <Step title="Run an evaluator">
            Start a Jupyter Notebook in your web browser (usually at `http://localhost:8888`):

            ```shell theme={null} theme={null} theme={null}
            jupyter lab
            ```

            Create a new notebook by clicking the **Notebook: Python 3 (ipykernel)** tile in the Jupyter Lab launcher. Alternatively, select **File > New > Notebook > Python 3 (ipykernel)** in the menu.

            Run an evaluator by copying the code from our [
            examples](https://github.com/learning-commons-org/evaluators/tree/main/evals) ↗ into the cells of your notebook.

            <Note>
              You can also use an IDE with Python and Jupyter Notebook support (e.g. VS Code
              with Microsoft's
              [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
              and
              [Jupyter](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter)
              extensions).
            </Note>
          </Step>
        </Steps>
      </Tab>

      <Tab title="Windows">
        Install Python 3.10 or newer. To verify your version of Python:

        ```shell theme={null}
        python3 --version
        ```

        <Steps>
          <Step title="Create a virtual environment">
            In Command Prompt:

            ```shell theme={null}
            python -m venv .venv
            .venv\Scripts\activate
            ```

            Or in PowerShell:

            ```shell theme={null}
            python -m venv .venv

            .venv\Scripts\Activate.ps1
            ```

            Remember to activate the virtual environment for each new shell session.
          </Step>

          <Step title="Install dependencies">
            Install all required packages listed in [`requirements.txt`](https://github.com/learning-commons-org/evaluators/blob/main/evals/requirements.txt) ↗:

            ```shell theme={null}
            pip install -r evals/requirements.txt
            ```
          </Step>

          <Step title="Set your API keys">
            Set your API keys as environment variables in Command Prompt:

            ```shell theme={null}
            export OPENAI_API_KEY="sk-your-key-here"
            export GOOGLE_API_KEY="your-key-here"
            ```

            Or in PowerShell:

            ```shell theme={null}
            $env:OPENAI_API_KEY="sk-your-key-here"
            $env:GOOGLE_API_KEY="your-key-here"
            ```
          </Step>

          <Step title="Run an evaluator">
            Start a Jupyter Notebook in your web browser (usually at `http://localhost:8888`):

            ```shell theme={null} theme={null} theme={null}
            jupyter lab
            ```

            Create a new notebook by clicking the **Notebook: Python 3 (ipykernel)** tile in the Jupyter Lab launcher. Alternatively, select **File > New > Notebook > Python 3 (ipykernel)** in the menu.

            Run an evaluator by copying the code from our [
            examples](https://github.com/learning-commons-org/evaluators/tree/main/evals) ↗ into the cells of your notebook.

            <Note>
              You can also use an IDE with Python and Jupyter Notebook support (e.g. VS Code
              with Microsoft's
              [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
              and
              [Jupyter](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter)
              extensions).
            </Note>
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Related topics

<CardGroup cols={2}>
  <Card title="Core concepts" icon="lightbulb" href="/evaluators/understanding-evaluators/core-concepts">
    Learn how dimensions, rubrics, and accuracy shape evaluator results.
  </Card>

  <Card title="SDK API reference" icon="code" href="/evaluators/sdk-api-reference/overview">
    Configure evaluators, interpret outputs, and handle errors in your project.
  </Card>
</CardGroup>