Create Dataset imports and Evaluation Tasks through explicit state transitions

Authentication and scope#

These are workspace endpoints, not an anonymous public ingestion service. The caller must have an authenticated GenMedia session and the MLOpt capability required for the target operation. Project, Dataset, Protocol, storage ownership, and task access are checked again on the server.

The current contract does not advertise external API keys. Browser session authentication and same-origin request rules remain authoritative until a separately scoped machine credential product is shipped.

Create and upload#

The create request records the Dataset name, description, purpose, retention, filename patterns, content warnings, upload mode, sourceLanguage, and targetLanguages. Operators should send both language fields explicitly. The API defaults an omitted sourceLanguage to en and an omitted targetLanguages to an empty list; the browser importer explicitly starts with tr-tr selected. targetLanguages accepts an explicit list of up to eight supported language tags. Media modality is inferred only after byte validation. Folder mode returns a file-registration endpoint; archive mode returns one short-lived bundle target.

Folder files are registered just in time in batches of at most three, matching upload concurrency so every two-hour creation token is used immediately. Each response contains a signed token scoped to one fixed private object; the resulting resumable upload URL remains valid for up to 24 hours. Upload bytes only to the returned object target. Never place bearer tokens, provider credentials, or secret configuration in Dataset files.

Folder mode accepts 10 GiB total, 5 GiB per file, 5,000 files, and 2,000 sources. Archive mode accepts .zip, .tar, .tar.gz, .tgz, and prompt-only .csv with a 200 MiB compressed, 192 MiB expanded, and 64 MiB per-entry limit. Multi-gigabyte archives and URL manifests are not supported.

Finalize and poll#

Finalize checks the caller, import ownership, object metadata, archive limits, path safety, config schema, media modality, anchors, group parameters, and marker bounds. It is idempotent: retrying the same finalized import returns its durable result instead of creating another Dataset version.

Poll the import status until it is ready or failed. Once a Dataset version exists, the response also includes its safe localization summary or null when the optional projection is temporarily unavailable. Dataset readiness and localization readiness are separate: publication is fail-open, while source analysis and selected translations continue in their retryable queue. The status response is deliberately sanitized and does not return storage paths, signed URLs, provider details, job IDs, or raw secret-bearing config. A failed import reports bounded validation categories and can be replaced by another import.

Localization readiness and retry#

The Dataset detail page lets an MLOpt operator update target languages and shows each active language as ready or processing, item counts per language, aggregate processing and failure counts, and a Retry failed action when exhausted jobs exist. The settings update commits the active language set and durable queue rows together, then starts one bounded background dispatch. A target becomes selectable for a new Session only when every exact Dataset item is ready. Legacy Dataset versions without localization metadata retain their raw-source compatibility path.

GET or PATCH /api/datasets/{datasetId}/languages reads or replaces the active target-language set. PATCH requires a same-origin MLOpt session and JSON targetLocales. It never edits Dataset version settings or content hashes; it returns only safe aggregate counts and language tags.

A signed-in MLOpt operator can call GET /api/datasets/localizations/status?datasetVersionId={versionId}. The response contains a localization projection with configured, sourceLocale, targetLocales, translationVersion, itemCount, expectedJobs, counts, readyLocales, and localeReadyCounts. counts groups queued, running, retry_wait, complete, and failed jobs. The route also idempotently restores any missing jobs for the immutable version without exposing source text, provider responses, errors, or credentials.

POST /api/datasets/localizations/dispatch accepts JSON with datasetVersionId and an optional targetLocale. It requires a same-origin MLOpt session, requeues only failed matching jobs, runs a bounded dispatch, and returns requeued, dispatched, and the updated localization summary. Successful immutable copies are not replaced.

GET on the dispatch route is the one-minute internal Cron worker. It requires CRON_SECRET and claims at most two jobs per invocation. It is operational infrastructure, not a browser-session or external API-key endpoint.

Task creation remains a separate operation#

Publishing a Dataset does not create an Evaluation Task. A task binds one published Dataset version, an available Experiment type, reviewer instructions, a Protocol and Sampling Plan, model or treatment identities, an audience, and an optional staffing Job.

For a finished-media Dataset request, send schema genmedia-dataset-task-v1, dataset_version_id, and language to /api/tasks/import. The language field sets the Task default. Before a Session starts, the evaluator may choose any configured locale whose exact copy and important-part analysis are ready for every Dataset item; the server validates and pins that choice transactionally. The import response localization summary describes the default legacy presentation created with the Task.

Use /api/tasks/import when candidate media already exists. Use /api/tasks/generate when supported fal endpoints should produce the conditions. Both paths validate the same task contract before the task becomes available to reviewers.

Evaluation Session actions#

The authenticated /api/evaluation-session endpoint accepts an explicit action. prerequisites returns the caller’s answer-free Reviewer Practice and Golden Control readiness. start validates those prerequisites, the reviewer brief acknowledgement, the current preflight, account eligibility, staffing, and risk state before returning the first opaque assignment. next resumes the same durable Session.

playback records one ordered sample for one presented candidate and returns creditedSeconds, requiredSeconds, and complete. submit accepts win, tie, skip, or rating and returns an idempotent receipt plus the next assignment. finish closes a Session only after its configured minimum decision count. Every response is private and no-store; model identity, storage paths, private answer keys, device digests, and risk details are not part of the browser contract.

Each assignment uses the exact language pinned to its Evaluation Session. Its localization metadata identifies the requested and resolved locale, whether the displayed copy is localized or source, the translation contract version, and whether that copy is ready. Resume and operator replay resolve the same immutable localization id. Important spans apply only to the exact prompt string returned with that assignment.

Account-free Evaluation links#

An authorized task operator can create an expiring guest link with separate maximum-start and reserved-completion limits. The full 256-bit URL secret is returned once; later list responses expose only a short hint and aggregate usage. Link creation is rejected for tasks with a pinned rater pool, Reviewer Practice, or Golden Control prerequisite because a generic link must not bypass staffing or qualification gates.

Production guest entry requires Cloudflare Turnstile bound to the exact GenMedia hostname and the guest_evaluation_entry action, plus a short-lived, one-use first-party challenge. A successful exchange creates a synthetic, task-scoped identity. Its signed browser marker, persistent device binding, account lifetime, link state, exact task, Session binding, risk state, and media assignment are rechecked on the server and in database RPCs. A copied JWT or guessed media slot is not sufficient authority.

A completed guest may create a deterministic, same-browser claim ticket that remains usable for its advertised lifetime even if the distribution link later expires. Claiming never changes the immutable evaluator or event owner. An unclaimed guest and a verified account awaiting approval earn no reward. After activation as Standard, only a fully accepted terminal behavior-quality state can award the task-pinned value exactly once. A degraded positive analysis weight still earns zero, but the claim and save operation can succeed. Discarding explicitly revokes the guest identity and releases an unused completion reservation.

• Strict shared-device policy

  By default, a second browser identity with the same link, network, and browser profile is rejected. Operators may explicitly allow shared office or lab networks; this permits multiple guests to complete and save but only the first task plus network and user-agent anonymous cohort can contribute provisional guest evidence. Device binding, Turnstile, rate limits, and task scoping remain active.

• Silent cutoff

  Guest attention failures, severe automation evidence, anomalous speed, and blind-slot patterns use a private risk boundary. A cutoff stops further assignments, can reduce official influence to zero, and prevents reward without exposing the score, threshold, or signal.

• No public ingestion authority

  Guest endpoints can evaluate only the one ready task named by their server-side link. They cannot list Projects, Datasets, model identities, results, or operator APIs.