# Hello World

Start building reproducible ML experiments in minutes. This guide walks you through creating and running your first Valohai execution with the help of the `valohai-utils` library.

## Prerequisites

* Python 3.9 or later
* A Valohai account ([create one free](https://app.valohai.com))

## Install the CLI

Get the Valohai CLI and utilities for experiment tracking:

```shell
pip install valohai-cli
```

> **Tip:** Use `pipx install valohai-cli` to avoid dependency conflicts.

## Login

```shell
vh login
```

<details>

<summary><strong>Using SSO or self-hosted Valohai?</strong></summary>

**SSO Users (Azure, Google, SAML)**

Generate a personal access token:

1. Go to **Hi, \[username]** → **My Profile** → **Authentication**
2. Click **Manage Tokens** → **Create a new personal token**
3. Save the token securely (shown only once)

```shell
vh login --token <your-token>
```

**Self-Hosted Installations**

```shell
vh login --host https://your-company.valohai.io
```

> 💡 Combine options: `vh login --host https://your-company.valohai.io --token <token>`

</details>

## Create Your First Project

Set up a project directory and connect it to Valohai:

```shell
mkdir my-ml-project
cd my-ml-project
vh project create --name my-ml-project
```

This links your local directory to Valohai for experiment tracking.

> **Already have a project?** Link to it with `vh project link` and select from the list.

## Write Your Training Script

Save this as `train.py`:

```python
import valohai
import json

# Define hyperparameters with automatic tracking
params = {
    "learning_rate": valohai.parameters("learning_rate").value,
    "epochs": valohai.parameters("epochs").value,
}

print(f"Training with lr={params['learning_rate']} for {params['epochs']} epochs")

# Simulate training (replace with your model code)
for epoch in range(params["epochs"]):
    accuracy = 0.85 + (epoch * 0.02)  # Mock improving accuracy
    valohai.log_metric("accuracy", accuracy, step=epoch)
    print(f"Epoch {epoch}: accuracy={accuracy:.3f}")

# Save model or results
output_path = valohai.outputs().path("model_results.json")
with open(output_path, "w") as f:
    json.dump(
        {
            "final_accuracy": accuracy,
            "parameters": params,
            "model_version": "1.0",
        },
        f,
    )

print(f"Results saved to {output_path}")
print("Training complete!")
```

## Configure Your Execution Environment

Create `valohai.yaml` to define how your code runs:

```yaml
- step:
    name: train
    image: python:3.9
    command:
    - pip install valohai-utils
    - python train.py
    parameters:
      - name: learning_rate
        type: float
        default: 0.001
      - name: epochs
        type: integer
        default: 10
```

### About Docker Images

The `image` field specifies your execution environment. Think of it as a clean environment with only the software you specify. For example:

* **Python**: `python:3.9`, `python:3.11`
* **TensorFlow**: `tensorflow/tensorflow:2.13.0`
* **PyTorch**: `pytorch/pytorch:2.0.0-cuda11.7-cudnn8-runtime`
* **R**: `r-base:4.3.0`
* **Custom**: Your own Docker images with specific dependencies

> **Note:** The Docker image can different from your local Python version. Valohai runs your code in this isolated environment for reproducibility.

## Run Your First Execution

Submit the job and watch logs in real-time:

```shell
vh execution run train --adhoc --watch
```

What happens:

* `--adhoc` uploads your current code without pushing to Git (great for testing)
* `--watch` streams logs to your terminal
* Valohai tracks all inputs, outputs, and parameters automatically

## View Results in the UI

Open your execution in the browser:

```shell
vh execution open
```

The UI shows:

* Real-time logs and metrics charts
* Parameter values and configuration
* Output files (downloadable)
* Full reproducibility information

## What's Next?

You've successfully run your first Valohai execution! Here's where to go next:

**🎓** [**Valohai Academy**](https://learn.valohai.academy)\
Free courses on MLOps best practices and advanced Valohai features

[**Working with Data**](https://docs.valohai.com/data)\
Upload datasets and connect them to executions

[**Building Pipelines**](https://docs.valohai.com/getting-started/intro/pipelines)\
Chain multiple steps for end-to-end ML workflows

[**Using Git Integration**](https://docs.valohai.com/git-integration)\
Connect repositories for production-ready experiments

***

### Troubleshooting

<details>

<summary><strong>Command 'vh' not found</strong></summary>

The CLI isn't in your system PATH. Fix it:

**macOS/Linux:**

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**Windows:** Add the Python Scripts folder to your PATH environment variable.

**Alternative:** Run with `python -m valohai_cli` instead of `vh`.

</details>

<details>

<summary><strong>Project not linked</strong></summary>

Run `vh project link` to connect your directory to an existing Valohai project.

</details>

<details>

<summary><strong>Import error for valohai module</strong></summary>

Install the Valohai utilities as a part of your step in `valohai.yaml`:

```shell
pip install valohai-utils
```

</details>