feat: async + multi-source create_benchmark - #470

Stacked on #467.

What & why

Brings the SDK's create_benchmark() in line with two server changes to POST /nucleus/benchmarks:

1. Async — the server creates the benchmark in a "building" state and streams members in via a background job, responding 202 { benchmark_id, job_id } (removes the old ~50k item cap on slice/dataset-sourced benchmarks).
2. Multi-source — members can come from any combination of item ids, slices, and datasets, unioned + de-duped server-side.

Changes

Async

• create_benchmark() POSTs, reads { benchmark_id, job_id }, and by default blocks on the build job (reusing the existing AsyncJob poller) then returns the completed "ready" benchmark. Return type unchanged, so existing blocking callers are unaffected. A failed build raises JobError (the poller already treats Errored_Server/Errored_User/etc. as terminal).
• wait_for_completion=False returns the "building" benchmark immediately for callers who poll themselves; verbose controls poll logging.
• Benchmark gains a status field ("building" / "ready" / "failed"), parsed in from_json.

Multi-source

• Adds plural slice_ids and dataset_ids params alongside the singular slice_id/dataset_id/item_ids/items. All sources combine (unioned + de-duped server-side).
• Requirement relaxed from "exactly one source" to "at least one source".

Meta

• Version → 0.20.0; CHANGELOG entry (Added: multi-source; Changed: async).
• Tests (mock-based, no live API): async poll-then-fetch flow, wait_for_completion=False, status parsing, multi-source payload, and at-least-one-source validation.

Notes

• black/pre-commit/pytest weren't run locally (not installed in this env); CI's format/lint/test jobs are the authority.

🤖 Generated with Claude Code

Greptile Summary

This PR updates create_benchmark() to match two server-side changes: the endpoint now responds 202 with {benchmark_id, job_id} (async build), and it accepts members from multiple sources in a single call. The client adapts by polling the build job via the existing AsyncJob poller before returning the completed benchmark, with a wait_for_completion=False escape hatch for non-blocking callers.

• Async flow: create_benchmark POSTs, receives {benchmark_id, job_id}, blocks on AsyncJob.sleep_until_complete() by default, then re-fetches the benchmark. A missing job_id with wait_for_completion=True now raises ValueError explicitly (previously discussed thread already addressed).
• Multi-source: adds slice_ids and dataset_ids list params alongside the singular equivalents; validation relaxed from "exactly one" to "at least one" source; all sources unioned server-side.
• Benchmark dataclass: gains a status field ("building" / "ready" / "failed"), populated in from_json using a hardcoded "status" string instead of the existing STATUS_KEY constant.

sequenceDiagram
    participant Caller
    participant NucleusClient
    participant Server
    participant AsyncJob

    Caller->>NucleusClient: "create_benchmark(name, slice_ids=[...], wait_for_completion=True)"
    NucleusClient->>NucleusClient: validate at least one source
    NucleusClient->>Server: "POST /benchmarks {name, slice_ids, ...}"
    Server-->>NucleusClient: "202 {benchmark_id, job_id}"
    NucleusClient->>AsyncJob: get_job(job_id).sleep_until_complete()
    loop poll until terminal state
        AsyncJob->>Server: "GET /jobs/{job_id}"
        Server-->>AsyncJob: "status (building → ready | failed)"
    end
    AsyncJob-->>NucleusClient: job complete
    NucleusClient->>Server: "GET /benchmarks/{benchmark_id}"
    Server-->>NucleusClient: "Benchmark (status="ready")"
    NucleusClient-->>Caller: "Benchmark(status="ready")"

    Note over Caller,NucleusClient: wait_for_completion=False skips polling,<br/>goes straight to GET /benchmarks/{id}

_{Reviews (6): Last reviewed commit: "P1" | Re-trigger Greptile}