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

# Run evaluators with Python notebooks

> Learn how to set up a local Python environment and run evaluators using Jupyter notebooks.

To use an evaluator, you need to:

1. Set up your environment. (below)
2. [Download examples](https://github.com/learning-commons-org/evaluators/tree/main/evals) ↗.
3. [Work through the tutorial](/evaluators/getting-started/tutorial-evaluating-grade-level-appropriateness).
4. Build it into your app or process.

## What you'll need

We rely on the Python interpreter to power the evaluators. All examples and tutorials are provided as Python code snippets.

## Steps

<Tabs>
  <Tab title="Mac/Linux set up">
    You’ll need Python 3.10 or newer. To verify your version of Python, run the following code in the terminal.

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

    ### STEP 1: Create a virtual environment

    Creating an isolated environment is a best practice that 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
    ```

    Remember to activate the virtual environment for each new shell session when working with Evaluators.

    ### STEP 2: Install dependencies

    The list of required packages is provided in the [requirements.txt](https://github.com/learning-commons-org/evaluators/blob/main/evals/requirements.txt) ↗ file.

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

    ### STEP 3: Set your API keys

    We are using **both** OpenAI and <kbd>Google Gemini</kbd>

    for different evaluators. You need API keys from both platforms:

    * OpenAI: [https://platform.openai.com/](https://platform.openai.com/) ↗
    * Gemini: [https://aistudio.google.com/](https://aistudio.google.com/) ↗

    Set the 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"
    </Tab>
    <Tab title="Windows set up">
    You’ll need Python 3.10 or newer. To verify your version of Python, run the following code in the terminal:

    ```shell
    python --version
    ````
  </Tab>

  <Tab title="Windows set up">
    ### STEP 1: Create a virtual environment

    Open a Command Prompt and run:

    ```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 when working with Evaluators.

    ### STEP 2: Install dependencies

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

    ### STEP 3: Set your API keys

    Get your API keys from:

    * OpenAI: [https://platform.openai.com/](https://platform.openai.com/)
    * Gemini: [https://aistudio.google.com/](https://aistudio.google.com/)

    Set the key(s) as environment variables:

    In Command Prompt:

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

    In PowerShell:

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

### STEP 4: Run an evaluator

You are now ready to run the evaluator examples, like the [Sentence Structure Evaluator.](https://github.com/learning-commons-org/evaluators/blob/main/evals/sentence_structure_evaluator.ipynb) ↗ We recommend using a Jupyter Notebook for interactive exploration.

1. Start Jupyter Notebook.

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

Jupyter will open in your web browser (usually at `http://localhost:8888`).

2. Create a new notebook by clicking the **Notebook: Python 3 (ipykernel)** tile in the Jupyter Lab launcher. Alternatively, navigate to the menu and select **File > New > Notebook > Python 3 (ipykernel)**.
3. You can now copy the code from our Python examples into the cells of your new notebook to run an evaluator.

   If you prefer using an IDE with Python and Jupyter Notebook support, such as VS Code with Microsoft's Python and Jupyter extensions, please refer to Microsoft's instructions for installation and configuration.