# Neptune Exporter Compatibility (GoodSeed 0.2.5+)

This document tracks compatibility between upstream `neptune-exporter` GoodSeed loader and current GoodSeed SDK APIs, plus the patched loader in this repository.

## Verdict

Status:
- Upstream `main`: `broken` against current GoodSeed SDK.
- Local patched copy (`archive/neptune-exporter`): constructor/method compatibility fixed and supports both local + remote target modes.

## Compatibility Matrix

| Exporter expectation | Current GoodSeed API | Result | Impact |
|---|---|---|---|
| `goodseed.Run(experiment_name=..., run_name=..., project=..., goodseed_home=..., created_at=...)` | `goodseed.Run(name=..., run_id=..., project=..., goodseed_home=..., created_at=...)` | **Hard fail** | `TypeError` on first run import attempt |
| `run.log_string_series({...}, step=...)` | `run.log_strings({...}, step=...)` | **Hard fail** (after constructor is fixed) | string series import crashes |
| `run.log_metrics({...}, step=...)` | `run.log_metrics({...}, step=...)` | Compatible | metrics can import |
| `run.log_configs({...})` | `run.log_configs({...})` | Compatible | configs can import |
| `goodseed.config.get_run_db_path(project, run_name, home_override)` | `get_run_db_path(project, run_name, home_override)` | Compatible (naming only) | dedupe check path still resolves |
| String step conversion to int (`int(float(step) * multiplier)`) | GoodSeed accepts numeric steps | Behavioral drift | decimal precision is truncated by exporter |
| `string_set` joined into comma-separated string | GoodSeed supports `string_set` configs | Behavioral drift | lossy transformation |
| Files/histograms skipped by loader | GoodSeed local storage has no direct file/histogram import in this path | Intentional limitation | partial data migration |

## Upstream First Failing Call

In upstream `neptune_exporter/loaders/goodseed_loader.py`, run creation currently uses:

- `goodseed.Run(experiment_name=..., run_name=...)`

Current GoodSeed constructor does not accept `experiment_name` or `run_name`, so the load flow fails before data is written.

## Compatibility Fix Scope Applied

1. Updated run construction:
   - `experiment_name` -> `name`
   - `run_name` -> `run_id`
2. Updated string-series logging:
   - `log_string_series(...)` -> `log_strings(...)`
3. Added GoodSeed remote mode:
   - remote API-key ingest path,
   - import-target project ensure in default workspace,
   - foreign workspace remap rule: `Y/abc -> <defaultWorkspace>/Y_abc` with warning.
4. Added compatibility integration test guard in `tests/test_neptune_exporter_e2e.py`.

## Local and CI Execution

The E2E test is optional by default (dependency heavy). Enable it explicitly:

```bash
GOODSEED_RUN_NEPTUNE_EXPORTER_E2E=1 pytest tests/test_neptune_exporter_e2e.py -v
```

Useful overrides:

- `NEPTUNE_EXPORTER_DIR=/path/to/neptune-exporter` to use a specific checkout
- default exporter location is `archive/neptune-exporter` in this repository

The test:

1. Uses a local neptune-exporter checkout.
2. Runs `uv sync --extra goodseed` in exporter repo.
3. Runs exporter with local GoodSeed using `uv run --with-editable <local-goodseed> ...`.
4. Generates deterministic parquet export fixtures in exporter schema format.
5. Runs `uv run neptune-exporter load --loader goodseed`.
6. Asserts successful import by validating the resulting GoodSeed SQLite data.
