> ## Documentation Index
> Fetch the complete documentation index at: https://dcpma.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with OASIS-LLM

> Install OASIS-LLM, configure your provider API key, and launch a 100-trial pilot rating run against a vision-language model in minutes.

OASIS-LLM is a research harness that submits the 900 OASIS affective images to vision-language models and records their valence and arousal ratings for comparison against human norms. This guide takes you from a fresh clone to a running pilot in a few minutes.

## Prerequisites

Before you start, make sure you have:

* **Python 3.12 or later** — check with `python --version`
* **[uv](https://docs.astral.sh/uv/)** — the package manager used to install and run OASIS-LLM
* **An API key** for at least one supported provider (OpenRouter, OpenAI, Anthropic, or Google), or a local [Ollama](https://ollama.com) installation

<Steps>
  <Step title="Clone the repository">
    Clone the repository and change into the project directory:

    ```bash theme={null}
    git clone https://github.com/DCPMA/AI-Psy.git
    cd AI-Psy
    ```
  </Step>

  <Step title="Create your environment file">
    Copy the example environment file:

    ```bash theme={null}
    cp .env.example .env
    ```

    Open `.env` and fill in the key for the provider you want to use. You only need to set one.

    <CodeGroup>
      ```bash OpenRouter theme={null}
      OPENROUTER_API_KEY=your_key_here
      ```

      ```bash OpenAI theme={null}
      OPENAI_API_KEY=your_key_here
      ```

      ```bash Anthropic theme={null}
      ANTHROPIC_API_KEY=your_key_here
      ```

      ```bash Google theme={null}
      GOOGLE_API_KEY=your_key_here
      ```
    </CodeGroup>

    <Note>
      OpenRouter gives you access to hundreds of models — including free-tier models — under a single key. It is the easiest way to get started if you do not already have a direct provider key.
    </Note>
  </Step>

  <Step title="Install dependencies">
    Run `uv sync` to install all dependencies from the lockfile:

    ```bash theme={null}
    uv sync
    ```
  </Step>

  <Step title="Download the OASIS images">
    The 900 OASIS images are licensed under **CC BY-NC-SA 4.0** by the original authors and are not bundled with this repository. Download them from [osf.io/6pnd7](https://osf.io/6pnd7) and unpack the archive into the `OASIS/images/` directory:

    ```
    OASIS/
    └── images/
        ├── OASIS_1.jpg
        ├── OASIS_2.jpg
        └── ...
    ```

    <Warning>
      The harness cannot submit images to a model if the `OASIS/images/` directory is missing or empty. The smoke test and pilot commands will fail until the images are in place.
    </Warning>
  </Step>

  <Step title="Smoke test your setup">
    Before committing to a full run, verify that your API key and image path are working correctly:

    ```bash theme={null}
    uv run oasis-llm smoke configs/runs/smoke-openrouter-gemma4.yaml
    ```

    This sends 3 images through the pipeline with a single valence rating each and prints the results to the terminal. It takes under a minute and costs a fraction of a cent.

    <Tip>
      Always run `oasis-llm smoke` with your chosen config before launching a pilot. It catches misconfigured keys, missing images, and model connectivity problems early.
    </Tip>
  </Step>

  <Step title="Launch the dashboard">
    Open the Streamlit dashboard to browse the image set, design experiments, and monitor runs:

    ```bash theme={null}
    uv run oasis-llm dashboard
    ```

    The dashboard opens at `http://localhost:8501`. From there you can inspect the OASIS image set, create datasets, and preview cost estimates before running anything from the CLI.
  </Step>

  <Step title="Run a pilot from the CLI">
    Launch a 30-image pilot run using one of the example configs. Pick the config that matches your provider:

    <CodeGroup>
      ```bash OpenRouter — Gemma 4 theme={null}
      uv run oasis-llm run configs/runs/pilot-gemma4-31b.yaml
      ```

      ```bash OpenRouter — Gemini 3.1 Pro theme={null}
      uv run oasis-llm run configs/runs/pilot-gemini-31-pro.yaml
      ```

      ```bash OpenRouter — Qwen 3.6 Plus theme={null}
      uv run oasis-llm run configs/runs/pilot-qwen36-plus.yaml
      ```

      ```bash Local Ollama — Qwen 3.5 theme={null}
      uv run oasis-llm run configs/runs/pilot30-qwen35-local.yaml
      ```
    </CodeGroup>

    Each pilot config targets 30 stratified images × 5 samples per image (150 trials) on both valence and arousal dimensions. The run is idempotent — if it is interrupted you can re-run the same command and it will resume from where it left off.
  </Step>

  <Step title="Check run status">
    While a run is in progress, or after it completes, check status across all runs:

    ```bash theme={null}
    uv run oasis-llm status
    ```

    To inspect a specific run by its ID:

    ```bash theme={null}
    uv run oasis-llm status <run_id>
    ```

    The table shows counts of `done`, `pending`, and `failed` trials, along with cumulative cost in USD.
  </Step>

  <Step title="Export results">
    Export the completed trials for a run to a CSV file:

    ```bash theme={null}
    uv run oasis-llm export <run_id> outputs/<run_id>.csv
    ```

    Replace `<run_id>` with the identifier shown in `oasis-llm status` — for example, `pilot-gemma4-31b`. The `outputs/` directory is created automatically if it does not exist.
  </Step>
</Steps>

## Next steps

With your first pilot complete, you can open the dashboard's **Analysis** page to compare the model's ratings against the human norms, or read [Configuration](/configuration) to learn how to customise run parameters like `samples_per_image`, `max_concurrency`, and prompt settings.