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

# Neptune Scale Migration

> How to migrate from Neptune Scale to Pluto with zero code changes using the compatibility layer.

We've created a Neptune Scale compatibility layer that enables dual-logging to both Neptune Scale and Pluto simultaneously. This allows you to gradually migrate your experiment tracking without disrupting existing workflows.

<Note>
  The compatibility layer targets [Neptune Scale](https://github.com/neptune-ai/neptune-client-scale) (`neptune-scale` package), **not** the legacy Neptune client (`neptune` package). If you are still on the legacy Neptune client, you will need to [migrate to Neptune Scale](https://docs.neptune.ai/migration_neptune/) first.
</Note>

<Note>
  We are working on a tool to migrate your existing runs from Neptune to Pluto. Interested? Please contact us at [founders@trainy.ai](mailto:founders@trainy.ai)
</Note>

## Quick Start

Enable dual-logging by adding a single import to your existing Neptune Scale scripts:

```python theme={null}
import pluto.compat.neptune  # Add this line
from neptune_scale import Run  # Your existing Neptune Scale import

# Your existing Neptune Scale code works unchanged
run = Run(experiment_name="my-experiment")
run.log_configs({"lr": 0.001, "batch_size": 32})
run.log_metrics({"train/loss": 0.5}, step=0)
run.close()
```

That's it. Your metrics will now log to both Neptune Scale and Pluto.

## Configuration

### Required Environment Variable

| Variable        | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `PLUTO_PROJECT` | Master switch that enables dual-logging. Set to your Pluto project name. |

```bash theme={null}
export PLUTO_PROJECT="my-pluto-project"
```

### Optional Environment Variables

| Variable                  | Description                                                          |
| ------------------------- | -------------------------------------------------------------------- |
| `PLUTO_API_KEY`           | Authentication credentials. Falls back to keyring if not set.        |
| `PLUTO_URL_APP`           | App endpoint for self-hosted instances                               |
| `PLUTO_URL_API`           | API endpoint for self-hosted instances                               |
| `PLUTO_URL_INGEST`        | Ingest endpoint for self-hosted instances                            |
| `DISABLE_NEPTUNE_LOGGING` | Set to `true` to disable Neptune logging entirely (post-sunset mode) |

## Supported Operations

The compatibility layer wraps Neptune Scale API calls and translates them to the equivalent pluto calls. Below are the Neptune Scale `Run` APIs and the corresponding `pluto` API we monkeypatch against.

<Note>
  `import pluto.compat.neptune` should be sufficient for sending data to both Neptune Scale and Pluto. The information below is purely informational about which APIs we have wrapped.
</Note>

<Note>
  The compatibility layer is tested against **Neptune Scale 3** (`neptune-scale>=0.30.0`).
</Note>

### Initialization

| Neptune Scale                          | pluto                              |
| -------------------------------------- | ---------------------------------- |
| `Run(experiment_name="my-experiment")` | `pluto.init(name="my-experiment")` |

### Configs

| Neptune Scale                    | pluto                              |
| :------------------------------- | :--------------------------------- |
| `run.log_configs({"lr": 0.001})` | `run.update_config({"lr": 0.001})` |

### Metric Logging

| Neptune Scale                                    | pluto                                    |
| ------------------------------------------------ | ---------------------------------------- |
| `run.log_metrics({"train/loss": 0.5}, step=0)`   | `run.log({"train/loss": 0.5}, step=0)`   |
| `run.log_metrics({"train/loss": 0.5}, step=100)` | `run.log({"train/loss": 0.5}, step=100)` |

### File and Image Logging

| Neptune Scale                                                | pluto                                                    |
| ------------------------------------------------------------ | -------------------------------------------------------- |
| `run.assign_files({"images": File("path/to/image.png")})`    | `run.log({"images": pluto.Image("path/to/image.png")})`  |
| `run.log_files({"artifacts": File("path/to/file")}, step=0)` | `run.log({"artifacts": pluto.Artifact("path/to/file")})` |

### Tags

| Neptune Scale                          | pluto                             |
| -------------------------------------- | --------------------------------- |
| `run.add_tags(tags=["experiment-v1"])` | `run.add_tags(["experiment-v1"])` |

Tags are synchronized to the Pluto server and can be used to filter and organize runs in the dashboard.

### Histograms

| Neptune Scale                                                           | pluto                                                      |
| ----------------------------------------------------------------------- | ---------------------------------------------------------- |
| `run.log_histograms({"distributions/weights": Histogram(...)}, step=0)` | `run.log({"distributions/weights": pluto.Histogram(...)})` |

## Post-Sunset Mode

When you're ready to stop sending data to Neptune Scale, set the kill switch:

```bash theme={null}
export DISABLE_NEPTUNE_LOGGING=true
```

This converts your code to Pluto-only mode without requiring any code changes. All Neptune Scale API calls will be intercepted and redirected to Pluto.