feat(nucleus): Add NucleusClient.merge_model_runs()

[luke-e-schaefer]

Adds NucleusClient.merge_model_runs(model_run_ids, name, *, model_id=None, metadata=None), wrapping POST /v1/nucleus/modelRun/merge.

Requires scaleapi PR https://github.com/scaleapi/scaleapi/pull/156919, which adds the endpoint.

Why

A benchmark evaluation names a single model run, and a benchmark's items may span several datasets. A model whose predictions were uploaded as separate runs — one per dataset, or one per inference batch — has no single run covering the benchmark, so every uncovered item scores as a false negative. Merge first, then pass the new run to create_benchmark_evaluation_v2().

merged = client.merge_model_runs(
    ["run_abc", "run_def", "run_ghi"],
    name="v3 — all benchmark datasets",
)
evaluation = client.create_benchmark_evaluation_v2(
    benchmark_id, merged["model_run_id"]
)

Semantics

Full union — predictions are copied, never deduplicated, and the source runs are left untouched. If two source runs predict on the same item with the same annotation_id, the colliding id is rewritten rather than dropped. The response reports predictions_copied, predictions_ignored and annotation_ids_rewritten so nothing is lost silently.

Verification

The test suite requires live API keys (conftest.py hard-asserts on NUCLEUS_PYTEST_API_KEY), so it could not be run locally, and there is no local backend to exercise the round trip against. Verified offline that the method builds the exact payload the server's Joi schema accepts (model_run_ids, name, optional model_id / metadata), posts to modelRun/merge, and raises on fewer than two distinct run ids before making a request.

Note on the version bump

Bumped to 0.21.0. PR #473 also bumps pyproject.toml / CHANGELOG.md; whichever lands second will need a trivial rebase on those two files.

🤖 Generated with Claude Code

Greptile Summary

Adds NucleusClient.merge_model_runs() to combine predictions from multiple model runs through the new merge endpoint.

• Validates that at least two distinct source run IDs are supplied.
• Sends the source IDs, name, and optional model ID and metadata to POST /v1/nucleus/modelRun/merge.
• Adds the corresponding payload constant, changelog entry, and minor-version bump.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete client-side defects identified in the new wrapper.

The method follows existing request conventions, resolves to the intended POST endpoint, constructs the documented optional payload fields, and returns the decoded API response without changing existing interfaces.

Important Files Changed

Filename	Overview
nucleus/init.py	Adds the public merge wrapper with minimum-distinct-ID validation, optional fields, documentation, and standard request dispatch.
nucleus/constants.py	Adds the model_run_ids request-key constant used by the new wrapper.
pyproject.toml	Bumps the package version from 0.20.0 to 0.21.0 for the new API feature.
CHANGELOG.md	Documents the merge operation, its benchmark use case, and full-union semantics.

_{Reviews (1): Last reviewed commit: "feat: add NucleusClient.merge_model_runs..." | Re-trigger Greptile}