Download, warm, and chat with a local model on Understudy Desktop

arazzo: 1.0.1
info:
  title: Download, warm, and chat with a local model on Understudy Desktop
  version: 1.0.0
  summary: The core Understudy Desktop journey over the loopback Agent API - pick a model from the catalog, start and track its download, add a residency slot, assign and warm the model in the slot, then send a conversation turn and stream the run's events.
  x-realizes-capability-ids:
  - BC-610.60
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-610.60
      capability_name: Artificial Intelligence Management
      spec: understudy-labs-models-api-openapi.yml
      confidence: 0.7
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: conversationsApi
  url: ../openapi/understudy-labs-conversations-api-openapi.yml
  type: openapi
- name: downloadsApi
  url: ../openapi/understudy-labs-downloads-api-openapi.yml
  type: openapi
- name: modelsApi
  url: ../openapi/understudy-labs-models-api-openapi.yml
  type: openapi
- name: residencyApi
  url: ../openapi/understudy-labs-residency-api-openapi.yml
  type: openapi
- name: runsApi
  url: ../openapi/understudy-labs-runs-api-openapi.yml
  type: openapi
workflows:
- workflowId: download-warm-and-chat
  summary: From catalog to a locally-served conversation turn.
  description: All calls target the authenticated loopback API described by the desktop capability file. Nothing leaves the machine unless a remote route is explicitly selected.
  inputs:
    type: object
    properties:
      model_id:
        type: string
        description: Catalog model to download and serve (e.g. understudy-small).
      session_id:
        type: string
        description: Conversation session identifier.
      prompt:
        type: string
        description: First user message for the warmed model.
  steps:
  - stepId: browseCatalog
    description: List downloadable models and confirm the target model exists.
    operationId: desktopModelCatalog
    successCriteria:
    - condition: $statusCode == 200
  - stepId: startDownload
    description: Start downloading the chosen model.
    operationId: desktopDownloadStart
    requestBody:
      contentType: application/json
      payload:
        model: $inputs.model_id
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      download_id: $response.body#/download_id
  - stepId: pollDownload
    description: Poll the download until it completes.
    operationId: desktopDownloadStatus
    parameters:
    - name: download_id
      in: path
      value: $steps.startDownload.outputs.download_id
    successCriteria:
    - condition: $statusCode == 200
  - stepId: addSlot
    description: Add a residency slot to hold the model.
    operationId: desktopResidencyAddSlot
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      slot_id: $response.body#/slot_id
  - stepId: assignModel
    description: Assign the downloaded model to the slot.
    operationId: desktopResidencyAssign
    requestBody:
      contentType: application/json
      payload:
        slot_id: $steps.addSlot.outputs.slot_id
        model: $inputs.model_id
    successCriteria:
    - condition: $statusCode == 200
  - stepId: warmSlot
    description: Warm the slot so the model is resident and ready.
    operationId: desktopResidencyWarm
    requestBody:
      contentType: application/json
      payload:
        slot_id: $steps.addSlot.outputs.slot_id
    successCriteria:
    - condition: $statusCode == 200
  - stepId: sendTurn
    description: Send the first conversation turn to the warmed model.
    operationId: conversationTurn
    parameters:
    - name: session_id
      in: path
      value: $inputs.session_id
    requestBody:
      contentType: application/json
      payload:
        message: $inputs.prompt
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      run_id: $response.body#/run_id
  - stepId: streamRunEvents
    description: Stream the canonical ConversationRuntime events for the run.
    operationId: conversationRunEvents
    parameters:
    - name: run_id
      in: path
      value: $steps.sendTurn.outputs.run_id
    successCriteria:
    - condition: $statusCode == 200
  outputs:
    run_id: $steps.sendTurn.outputs.run_id