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

> Learn the common workflow for running any evaluator: choose content, run the evaluator, and review results.

export const EarlyAccessCallout = ({children}) => <div className="eyebrow-callout not-prose rounded-xl border border-gray-200/80 p-5 dark:border-white/10" style={{
  marginBottom: "1rem",
  borderRadius: "4px"
}}>
    <div className="mb-3">
      <Badge color="green" size="md" icon="flask">
        Early access
      </Badge>
    </div>
    <div className="callout-body text-[15px] leading-relaxed text-gray-700 dark:text-gray-300">{children}</div>
    <style>{`.callout-body a { text-decoration: underline; text-decoration-color: #178251; }`}</style>
  </div>;

## What you'll need

To run our evaluators using any of our available methods, you must have:

* Text you want to evaluate
* Grade level of the intended audience
* API keys required by the evaluators you want to use

### 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)                                                               |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [Grade Level Appropriateness](/evaluators/literacy-evaluators/grade-level-appropriateness) ↗ | [Google](https://aistudio.google.com/)                                            |
| [Subject Matter Knowledge](/evaluators/literacy-evaluators/subject-matter-knowledge) ↗       | [Google](https://aistudio.google.com/)                                            |
| [Vocabulary](/evaluators/literacy-evaluators/vocabulary) ↗                                   | [Google](https://aistudio.google.com/) and [OpenAI](https://platform.openai.com/) |
| [Sentence Structure](/evaluators/literacy-evaluators/sentence-structure) ↗                   | [OpenAI](https://platform.openai.com/)                                            |
| [Conventionality](/evaluators/literacy-evaluators/conventionality) ↗                         | [Google](https://aistudio.google.com/)                                            |
| [Purpose](/evaluators/literacy-evaluators/purpose) ↗                                         | [Google](https://aistudio.google.com/)                                            |

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

## Running evaluators

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

### Evaluators Playground

The Evaluators Playground on the [Learning Commons Platform](https://platform.learningcommons.org) ↗ is the easiest way to see our evaluators in action.

It evaluates text using all our [literacy evaluators](/evaluators/literacy-evaluators/introduction), and provides an output to help you:

* Understand the pedagogical attributes of your text
* Assess the performance of different prompts
* Compare models for any AI-generated content in your products

The Evaluators Playground is primarily an introductory demo – we recommend the [SDK](#sdk) or [Python notebooks](#python-notebooks) when implementing evaluators into your automated processes.

### SDK

<EarlyAccessCallout>
  This functionality is actively evolving. Changes may occur as we expand
  capabilities and improve accuracy and reliability. Email
  [support@learningcommons.org](mailto:support@learningcommons.org) ↗ with your
  feedback or issues.
</EarlyAccessCallout>

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

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

Next, import evaluators to start evaluating text in your project:

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

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

  const result = await evaluator.evaluate("The cat's out of the bag now.");
  console.log(result.score); // 4-5
  ```

  ```python Python theme={null}
  import logging
  from learning_commons_evaluators import (
      ConventionalityEvaluator,
      ConventionalityEvaluationInput,
      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 ConventionalityEvaluator with created config
  evaluator = ConventionalityEvaluator(config)

  # Evaluate some text for 5th grade
  result = evaluator.evaluate_sync(
    ConventionalityEvaluationInput(text="The cat's out of the bag now.", grade=5)
  )

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

  ```
</CodeGroup>

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

### 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>
  <Tab title="Mac/Linux">
    Install Python 3.10 or newer. To verify your version of Python:

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

    <Steps>
      <Step title="STEP 1: 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="STEP 2: 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="STEP 3: 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="STEP 4: Run an evaluator">
        Start a Jupyter Notebook in your web browser (usually at `http://localhost:8888`):

        ```shell 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="STEP 1: 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="STEP 2: 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="STEP 3: 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="STEP 4: Run an evaluator">
        Start a Jupyter Notebook in your web browser (usually at `http://localhost:8888`):

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