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

# Quick Start

> Get started with Verifiers in minutes

This guide will walk you through setting up a Verifiers workspace, creating your first environment, and running evaluations.

## Prerequisites

Before starting, ensure you have Python 3.10 or later installed.

## Setup Your Workspace

<Steps>
  <Step title="Install uv and the Prime CLI">
    First, install `uv` (Python package manager) and the `prime` CLI tool:

    ```bash theme={null}
    # Install uv
    curl -LsSf https://astral.sh/uv/install.sh | sh

    # Install the Prime CLI
    uv tool install prime

    # Log in to Prime Intellect
    prime login
    ```
  </Step>

  <Step title="Initialize Your Workspace">
    Set up a new workspace for developing environments:

    ```bash theme={null}
    # Navigate to your development directory
    cd ~/dev/my-lab

    # Set up the workspace
    prime lab setup
    ```

    This command:

    * Creates a Python project (if needed)
    * Installs `verifiers`
    * Creates the recommended workspace structure
    * Downloads starter configuration files

    Your workspace structure will look like:

    ```
    configs/
    ├── endpoints.toml      # API endpoint configuration
    ├── rl/                 # Training configs
    ├── eval/               # Evaluation configs
    └── gepa/               # Prompt optimization configs
    environments/
    └── AGENTS.md           # AI agent documentation
    ```
  </Step>

  <Step title="Add to Existing Project (Optional)">
    If you already have a Python project, add Verifiers without reinitializing:

    ```bash theme={null}
    uv add verifiers && prime lab setup --skip-install
    ```
  </Step>
</Steps>

## Create Your First Environment

<Steps>
  <Step title="Initialize Environment Template">
    Create a new environment from the template:

    ```bash theme={null}
    prime env init my-env
    ```

    This creates a new module in `./environments/my_env/` with:

    ```
    environments/my_env/
    ├── my_env.py           # Main implementation
    ├── pyproject.toml      # Dependencies and metadata
    └── README.md           # Documentation
    ```
  </Step>

  <Step title="Implement Your Environment">
    Edit `environments/my_env/my_env.py` with your environment logic:

    ```python theme={null}
    import verifiers as vf
    from datasets import Dataset

    def load_environment(dataset_name: str = 'gsm8k') -> vf.Environment:
        # Load or create your dataset
        dataset = vf.load_example_dataset(dataset_name)
        
        # Define reward function
        async def correct_answer(completion, answer) -> float:
            completion_ans = completion[-1]['content']
            return 1.0 if completion_ans == answer else 0.0
        
        # Create rubric with reward functions
        rubric = vf.Rubric(funcs=[correct_answer])
        
        # Return environment instance
        env = vf.SingleTurnEnv(dataset=dataset, rubric=rubric)
        return env
    ```

    <Note>
      The `load_environment` function is the entry point for your environment. It must return an `Environment` instance and can accept custom arguments.
    </Note>
  </Step>

  <Step title="Install Your Environment">
    Install the environment module into your project:

    ```bash theme={null}
    prime env install my-env
    ```

    This makes your environment importable and runnable.
  </Step>
</Steps>

## Run Your First Evaluation

<Steps>
  <Step title="Run Local Evaluation">
    Evaluate your environment with any OpenAI-compatible model:

    ```bash theme={null}
    prime eval run my-env -m gpt-5-nano
    ```

    This will:

    * Load your environment
    * Run rollouts with the specified model
    * Calculate rewards and metrics
    * Save results locally

    <Note>
      By default, evaluations use [Prime Inference](https://docs.primeintellect.ai/inference/overview). Configure custom API endpoints in `./configs/endpoints.toml`.
    </Note>
  </Step>

  <Step title="View Results">
    Open the terminal UI to explore your evaluation results:

    ```bash theme={null}
    prime eval tui
    ```

    Navigate through:

    * Rollout samples
    * Reward distributions
    * Model completions
    * Metrics and statistics
  </Step>
</Steps>

## Working with Existing Environments

<Steps>
  <Step title="Install from Environments Hub">
    Install any environment from the community hub:

    ```bash theme={null}
    prime env install primeintellect/math-python
    ```
  </Step>

  <Step title="Run Hub Environment">
    Evaluate it directly:

    ```bash theme={null}
    prime eval run primeintellect/math-python -m gpt-4.1-mini
    ```
  </Step>
</Steps>

## Environment Types

Verifiers supports multiple environment patterns:

<CardGroup cols={2}>
  <Card title="SingleTurnEnv" icon="comment">
    Simple Q\&A tasks with a single model response

    ```python theme={null}
    vf.SingleTurnEnv(dataset=dataset, rubric=rubric)
    ```
  </Card>

  <Card title="ToolEnv" icon="wrench">
    Environments with stateless Python function tools

    ```python theme={null}
    vf.ToolEnv(
        dataset=dataset,
        tools=[calculator, search],
        rubric=rubric
    )
    ```
  </Card>

  <Card title="StatefulToolEnv" icon="database">
    Tools requiring per-rollout state (sandboxes, sessions)

    ```python theme={null}
    vf.StatefulToolEnv(
        dataset=dataset,
        tools=[file_ops],
        rubric=rubric
    )
    ```
  </Card>

  <Card title="MultiTurnEnv" icon="messages">
    Custom multi-turn interactions, games, agents

    ```python theme={null}
    class GameEnv(vf.MultiTurnEnv):
        async def env_response(self, messages, state):
            # Custom game logic
            pass
    ```
  </Card>
</CardGroup>

## Building Complex Environments

### Adding Tools

Create tool-enabled environments for agent tasks:

```python theme={null}
import verifiers as vf

def calculator(expression: str) -> str:
    """Evaluate a math expression."""
    try:
        result = eval(expression)
        return str(result)
    except Exception as e:
        return f"Error: {e}"

def load_environment():
    dataset = vf.load_example_dataset('gsm8k')
    
    async def correct_answer(completion, answer) -> float:
        response = completion[-1]['content']
        return 1.0 if answer in response else 0.0
    
    rubric = vf.Rubric(funcs=[correct_answer])
    
    return vf.ToolEnv(
        dataset=dataset,
        tools=[calculator],  # Pass Python functions
        rubric=rubric
    )
```

### Using Sandboxes

For code execution tasks, use sandboxed environments:

```python theme={null}
import verifiers as vf

def load_environment():
    dataset = vf.load_example_dataset('codegen')
    
    async def code_passes_tests(state, info) -> float:
        # Check if code execution succeeded
        return 1.0 if state.get('tests_passed') else 0.0
    
    rubric = vf.Rubric(funcs=[code_passes_tests])
    
    return vf.PythonEnv(
        dataset=dataset,
        rubric=rubric
    )
```

## Publishing Your Environment

<Steps>
  <Step title="Test Locally">
    Ensure your environment works correctly:

    ```bash theme={null}
    prime eval run my-env -n 10 -m gpt-4.1-mini
    ```
  </Step>

  <Step title="Push to Hub">
    Publish to the Environments Hub:

    ```bash theme={null}
    prime env push --path ./environments/my_env
    ```

    Your environment is now available to the community!
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Environments Guide" icon="book" href="/docs/environments">
    Learn about datasets, rubrics, and custom protocols
  </Card>

  <Card title="Evaluation Guide" icon="chart-line" href="/docs/evaluation">
    Deep dive into evaluation configurations
  </Card>

  <Card title="Training Guide" icon="brain" href="/docs/training">
    Train models with reinforcement learning
  </Card>

  <Card title="API Reference" icon="code" href="/docs/reference">
    Explore the complete API documentation
  </Card>
</CardGroup>

## Common Patterns

<AccordionGroup>
  <Accordion title="Load dataset from Hugging Face">
    ```python theme={null}
    from datasets import load_dataset

    def load_environment():
        dataset = load_dataset('gsm8k', 'main', split='train')
        # ... configure environment
    ```
  </Accordion>

  <Accordion title="Multiple reward functions">
    ```python theme={null}
    async def accuracy(completion, answer) -> float:
        return 1.0 if answer in completion[-1]['content'] else 0.0

    async def length_penalty(completion) -> float:
        length = len(completion[-1]['content'])
        return -0.01 * length  # Penalize longer responses

    rubric = vf.Rubric(funcs=[accuracy, length_penalty])
    ```
  </Accordion>

  <Accordion title="Custom system prompts">
    ```python theme={null}
    return vf.SingleTurnEnv(
        dataset=dataset,
        system_prompt="You are a helpful math tutor. Show your work.",
        rubric=rubric
    )
    ```
  </Accordion>

  <Accordion title="Using API keys">
    ```python theme={null}
    import verifiers as vf

    def load_environment():
        # Validate required API keys
        vf.ensure_keys(['OPENAI_API_KEY', 'ANTHROPIC_API_KEY'])
        
        # ... rest of environment setup
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Environment not found after install">
    Make sure you ran `prime env install <env-name>` and the environment has a valid `load_environment` function.
  </Accordion>

  <Accordion title="API endpoint errors">
    Configure your endpoints in `./configs/endpoints.toml`. See the [evaluation guide](/docs/evaluation) for details.
  </Accordion>

  <Accordion title="Import errors">
    Ensure all dependencies are listed in your environment's `pyproject.toml` and installed.
  </Accordion>
</AccordionGroup>