# Datasets_GetPreparation

`GET /v1/accounts/{account}/datasets/{dataset}/preparation`

What the newest prepare run did to an upload (every upload is prepared
after it lands): the Task it matched and applied, or the Task it drafted;
the takes it split; the dataset's own task names and the decisions a
person made on them. A dataset with no run (a merged dataset, an upload
before preparation existed) answers state NONE.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header

## Parameters

- `account` (path, string, required): The account id.
- `dataset` (path, string, required): The dataset id.

## Responses

- `200` OK: `application/json` `qualia.v1.Preparation`
- `default` Default error response: `application/json` `google.rpc.Status`

## Schemas

```yaml
qualia.v1.Preparation:
  type: object
  properties:
    name:
      type: string
      description: accounts/{account}/datasets/{dataset}/preparation
    state:
      readOnly: true
      enum:
        - STATE_UNSPECIFIED
        - NONE
        - QUEUED
        - RUNNING
        - SUCCEEDED
        - FAILED
        - SKIPPED
      type: string
      description: Where the newest run is.
      format: enum
    runId:
      readOnly: true
      type: string
      description: The newest run's id.
    version:
      readOnly: true
      type: string
      description: The dataset version the run read.
    createTime:
      readOnly: true
      type: string
      description: When the run was queued.
      format: date-time
    updateTime:
      readOnly: true
      type: string
      description: When the run last changed.
      format: date-time
    error:
      readOnly: true
      type: string
      description: Why the run failed.
    taskMatch:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Preparation_TaskMatch"
      description: |-
        The matched or drafted Task. Unset for a run that discovery split into
        tasks: each has its own Task, in discovery.
    cuts:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Preparation_Cuts"
      description: The takes it split.
    taskStrings:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Preparation_TaskStrings"
      description: The dataset's own task names.
    discovery:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Preparation_Discovery"
      description: The tasks discovery found; unset on runs from before discovery.
    unpublishedAnnotationCount:
      readOnly: true
      type: integer
      description: |-
        Takes without a published annotation. Above zero, the run is partial: the
        other takes' annotations stand.
      format: int32
    unpublishedAnnotations:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.Preparation_UnpublishedAnnotation"
      description: The first 100 of those takes, each with why.
    warnings:
      readOnly: true
      type: array
      items:
        type: string
      description: |-
        What the run flagged without failing, one sentence each: a model that
        answered in place of the one asked for ("3 reads answered by a fallback
        model instead of Qualia VLM", Qualia names only), whose labels may be
        weaker. A read is a reply whose model was checked, not a label. A
        SUCCEEDED run whose task discovery failed says so here in one fixed
        sentence ("Task discovery did not finish, so the takes were prepared as
        one task for the whole dataset."), or "... prepared as a task per
        instruction they carry." when the takes' own task strings gave the tasks
        (discovery.task_strings_fallback), or, for a failed re-run that left
        earlier tasks standing, "Finding the tasks again did not finish; the
        tasks found before stand."; the reason is in discovery.reason. Empty
        when none.
  description: |-
    What the newest prepare run did to an upload. Its splits make the next
    version's episodes (v0 keeps the takes as uploaded); the rest is a proposal
    or a flag, and no Task was published.
qualia.v1.Preparation_TaskMatch:
  type: object
  properties:
    matched:
      type: boolean
      description: True when a published Task matched; false when the run drafted one.
    task:
      type: string
      description: "tasks/{task}: the matched Task, or the draft."
    revision:
      type: integer
      description: The matched revision; 0 for a draft.
      format: int32
    score:
      type: number
      description: Match score, 0 to 1 (0 for a draft).
      format: double
    basis:
      type: string
      description: One line on what the score rests on.
    candidates:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.TaskMatch_Candidate"
      description: The top candidates, best first (at most 5).
    event:
      type: string
      description: The TASK_ASSIGNED event that applied the match; empty when not applied.
    assignedCount:
      type: integer
      description: How many episodes the match was applied to.
      format: int32
    undone:
      type: boolean
      description: True once that event was undone.
    revertingEvent:
      type: string
      description: The event that undid it.
    displayName:
      type: string
      description: The Task's name.
  description: The Task the run matched and applied, or the one it drafted.
qualia.v1.TaskMatch_Candidate:
  type: object
  properties:
    task:
      type: string
      description: tasks/{task}
    displayName:
      type: string
      description: The Task's name.
    score:
      type: number
      description: Match score, 0 to 1.
      format: double
  description: Another Task the match scored.
qualia.v1.Preparation_Cuts:
  type: object
  properties:
    takes:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.Cuts_Take"
      description: Only takes split into two or more pieces.
    skippedCount:
      type: integer
      description: Takes the run left whole or could not split.
      format: int32
  description: The takes the run split.
qualia.v1.Cuts_Take:
  type: object
  properties:
    episode:
      type: string
      description: The as-uploaded (v0) episode.
    durationS:
      type: number
      description: The take's duration in seconds.
      format: double
    spans:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.Cuts_Span"
      description: The windows kept as pieces.
    idle:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.Cuts_Span"
      description: The idle stretches the cut found.
    children:
      type: array
      items:
        type: string
      description: The pieces, in span order, in the version the split made.
    event:
      type: string
      description: The split event.
  description: One take the run split into pieces.
qualia.v1.Cuts_Span:
  type: object
  properties:
    startS:
      type: number
      description: Start, seconds from the take's start.
      format: double
    endS:
      type: number
      description: End, seconds from the take's start.
      format: double
  description: A window of a take, in take time.
qualia.v1.Preparation_TaskStrings:
  type: object
  properties:
    state:
      type: string
      description: none, outcome_split, single, too_many, sparse, codes or informative.
    reason:
      type: string
      description: One line on why.
    offered:
      type: boolean
      description: The rule offers the names (informative).
    confirmable:
      type: boolean
      description: A person may confirm them (informative, sparse).
    candidates:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.TaskStrings_Candidate"
      description: One per distinct name, most episodes first.
  description: The dataset's own task names (from its metadata) and the decisions on them.
qualia.v1.TaskStrings_Candidate:
  type: object
  properties:
    key:
      type: string
      description: ts_<sha12> of the normalised string.
    text:
      type: string
      description: The string as the dataset gives it.
    episodeCount:
      type: integer
      description: Episodes that carry it.
      format: int32
    looksLikeCode:
      type: boolean
      description: It looks like a rig or session code.
    blocked:
      type: boolean
      description: It can never be confirmed (see blocked_reason).
    confirmation:
      allOf:
        - $ref: "#/components/schemas/qualia.v1.TaskStrings_Confirmation"
      description: The person's decision; unset when nobody decided.
    blockedReason:
      type: string
      description: "Why it is blocked: outcome words, a code, already a task label."
  description: One distinct task name.
qualia.v1.TaskStrings_Confirmation:
  type: object
  properties:
    displayName:
      type: string
      description: The task name the person gave it.
    confirmed:
      type: boolean
      description: "True: use it as a task. False: a person said no."
    actor:
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Actor"
      description: Who decided.
    decideTime:
      type: string
      description: When.
      format: date-time
  description: A person's decision on one name.
qualia.v1.Actor:
  type: object
  properties:
    kind:
      readOnly: true
      enum:
        - KIND_UNSPECIFIED
        - PERSON
        - VALIDATION
        - RULE
        - MODEL
        - OPERATOR
        - SYSTEM
      type: string
      description: What kind of actor it is.
      format: enum
    user:
      readOnly: true
      type: string
      description: The person's user id when `kind` is PERSON; empty otherwise.
    displayName:
      readOnly: true
      type: string
      description: The person's display name at the time, for rendering without a lookup.
    agent:
      readOnly: true
      type: string
      description: |-
        The rule code, or for a MODEL the Qualia model tier (e.g. "qualia-vlm";
        "qualia" for any other model), when not a person.
    run:
      readOnly: true
      type: string
      description: The run a model or rule finding came from, when it has one.
    apiKey:
      readOnly: true
      type: string
      description: |-
        The API key's id when a person acted through one; empty for a session.
        Never the key itself.
    attribution:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Attribution"
      description: |-
        Signed identity evidence recorded with the change, kept apart from the
        principal above. Unset on older records and wherever none was signed.
  description: Who did something. Every decision, issue and reply names one.
qualia.v1.Attribution:
  type: object
  properties:
    authentication:
      readOnly: true
      enum:
        - AUTHENTICATION_UNSPECIFIED
        - SESSION
        - API_KEY
        - SERVICE
      type: string
      description: How the principal authenticated.
      format: enum
    initiator:
      readOnly: true
      type: string
      description: |-
        The user id of a person verified as starting the work: the person of a
        session, or the person a trusted service's signed job record names.
        Empty when nobody was verified.
    initiatorDisplayName:
      readOnly: true
      type: string
      description: The initiator's display name at the time, never their email.
    credentialCreator:
      readOnly: true
      type: string
      description: The user id of the key's creator at the time. Not who used the key.
    credentialOwner:
      readOnly: true
      enum:
        - CREDENTIAL_OWNER_UNSPECIFIED
        - PERSON
        - SPACE
      type: string
      description: Who owned the key at the time.
      format: enum
    credentialOwnerSpace:
      readOnly: true
      type: string
      description: |-
        The owning space's id (a workspace or the organization) when
        `credential_owner` is SPACE.
  description: |-
    How a change was authenticated and who verifiably started it.
    Only the trusted mesh signs it. It never authorizes anything, and a key's
    creator or owner is never the person who used the key.
qualia.v1.Preparation_Discovery:
  type: object
  properties:
    status:
      enum:
        - STATUS_UNSPECIFIED
        - RUNNING
        - DONE
        - FAILED
        - FALLBACK
      type: string
      description: Where discovery is.
      format: enum
    tasks:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.Discovery_Task"
      description: The tasks, by task_key.
    unsortedCount:
      type: integer
      description: "Takes no task holds (their map failed): not linked, not checked."
      format: int32
    reason:
      type: string
      description: Why discovery fell back or failed; empty otherwise.
    recommendation:
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Discovery_Recommendation"
      description: Unset when the upload's task names were not assessed (a fallback).
    taskStringsFallback:
      type: boolean
      description: |-
        FAILED or FALLBACK, and the tasks are the episodes' own task strings
        (their task label, else their instruction), one per distinct string,
        each with its own Task; takes without a string are unsorted.
  description: |-
    Task discovery: the upload's takes sorted into tasks, each with its own
    matched Task or draft.
qualia.v1.Discovery_Task:
  type: object
  properties:
    taskId:
      type: string
      description: The matched Task or the draft's id; empty when no draft was made.
    taskKey:
      type: string
      description: sha256 of the task's sorted member take ids.
    name:
      type: string
      description: |-
        The task's name: its Task's name when it has one (as the Task's page
        shows it), else the name discovery gave it.
    episodeCount:
      type: integer
      description: Takes in the task.
      format: int32
    healthFlag:
      type: string
      description: |-
        The task's health: ok, or the reasons it may hold more than one task,
        comma-separated (inverse, margin), or flagged without one.
    referenceEpisodeIds:
      type: array
      items:
        type: string
      description: The picked reference takes' ids, best first.
  description: One discovered task.
qualia.v1.Discovery_Recommendation:
  type: object
  properties:
    recommended:
      type: boolean
      description: |-
        The names are offered, the discovered tasks disagree with them, and
        none is confirmed yet.
    warning:
      type: string
      description: The sentence that says how they disagree; empty when they agree.
  description: |-
    Whether confirming the upload's own task names should be a person's
    first step (task-strings-recommend-v1).
qualia.v1.Preparation_UnpublishedAnnotation:
  type: object
  properties:
    episode:
      type: string
      description: accounts/{account}/datasets/{dataset}/episodes/{episode}
    reason:
      type: string
      description: Why, as the run recorded it.
  description: A take whose proposed annotation did not publish.
google.rpc.Status:
  oneOf:
    - $ref: "#/components/schemas/ApiError"
    - $ref: "#/components/schemas/GatewayError"
  description: "The body of a failed call: one of the two shapes below."
ApiError:
  title: API error
  type: object
  required:
    - code
    - message
    - retryable
    - details
  properties:
    code:
      type: string
      description: The gRPC code name in upper case, e.g. `NOT_FOUND`.
    message:
      type: string
    retryable:
      type: boolean
      description: Whether the same call may succeed if retried.
    details:
      type: array
      items:
        type: object
      description: "Empty, except when a dataset copy or move is refused: then one `google.rpc.ErrorInfo` with the refusal's `reason` code, its `domain` and, in `metadata`, the datasets it names."
  description: A refusal from the API itself.
GatewayError:
  title: Gateway error
  type: object
  required:
    - detail
  properties:
    detail:
      type: string
      description: What went wrong.
  description: A refusal from the gateway before the call reaches the API, for example `401` bad or missing API key, `403` key lacks the scope or environment closed, `413` body too large.
```