openapi: 3.1.0
info:
  title: ScalarLM API
  version: '1.151'
  summary: Unified LLM inference and training API from the ScalarLM stack, maintained and sponsored by
    TensorWave.
  description: 'ScalarLM is TensorWave''s open-source (CC0-1.0) unified training and inference stack.
    A single deployment exposes an OpenAI-compatible inference endpoint backed by vLLM, a queue-backed
    batch generate surface, a Megatron-LM training surface dispatched through Slurm, and health/observability
    endpoints.


    PROVENANCE: this document is DERIVED by API Evangelist from the first-party FastAPI source in github.com/tensorwavecloud/ScalarLM.
    Every path, method, parameter and schema below was read from the committed route decorators and Pydantic
    models listed in info.x-evidence.sources. TensorWave does not publish a static OpenAPI document; a
    live ScalarLM deployment serves FastAPI''s own generated spec at /openapi.json. This is not a provider-published
    artifact, and the operationIds here are API Evangelist naming rather than FastAPI''s generated ids.'
  license:
    name: CC0-1.0
    url: https://creativecommons.org/publicdomain/zero/1.0/
  contact:
    name: TensorWave
    url: https://tensorwave.com/connect
  x-evidence:
    method: derived
    derived_from: source-code
    derived_on: '2026-08-02'
    repository: https://github.com/tensorwavecloud/ScalarLM
    repository_license: CC0-1.0
    sources:
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/main.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/openai_v1_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/megatron_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/health_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/generate_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/slurm_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/request_types/
    note: Route table read from the FastAPI APIRouter prefixes in main.py (openai_v1_router, megatron_router
      '/megatron', health_router '/health' and generate_router '/generate' are all mounted under '/v1';
      slurm_router '/slurm' is mounted at the app root). Schemas transcribed from the Pydantic models
      under routers/request_types/. CompletionRequest and ChatCompletionRequest are vLLM types re-exported
      by ScalarLM and are modelled as open objects rather than reproduced field by field.
    live_spec_hint: <deployment>/openapi.json (FastAPI generated)
    documented_deployment:
      url: https://gpt-oss.cray-lm.com
      source: https://www.scalarlm.com/inference/
      probed: '2026-08-02'
      http_status: 530
      note: Documented demo deployment; origin unreachable (Cloudflare 530) at probe time.
servers:
- url: https://gpt-oss.cray-lm.com
  description: Public ScalarLM demo deployment documented at scalarlm.com/inference (origin returned HTTP
    530 when probed 2026-08-02).
- url: http://localhost:8000
  description: Local development server started by ./scalarlm up.
tags:
- name: OpenAI
  description: OpenAI-compatible inference endpoints proxied to vLLM.
- name: Generate
  description: Queue-backed batch inference and worker coordination.
- name: Training
  description: Megatron-LM training jobs, chunked dataset upload, checkpoints and Hugging Face publishing.
- name: Slurm
  description: Slurm scheduler status and job control.
- name: Health
  description: Health checks, service logs and metrics.
paths:
  /v1/models:
    get:
      operationId: listModels
      summary: List available models
      tags:
      - OpenAI
      description: Proxies the upstream vLLM server's /v1/models. Returns the OpenAI model list envelope.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: &id001
                type: object
                additionalProperties: true
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/completions:
    post:
      operationId: createCompletion
      summary: Create a completion
      tags:
      - OpenAI
      description: OpenAI-compatible text completion. Proxied to the vLLM server; the request body is
        a vLLM CompletionRequest (OpenAI completions schema). Responses stream as text/event-stream.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: Server-sent event stream of completion chunks.
          content:
            text/event-stream:
              schema:
                type: string
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create a chat completion
      tags:
      - OpenAI
      description: OpenAI-compatible chat completion. When stream is true the request is proxied straight
        to vLLM as an SSE stream; when false it is admitted to the queue-backed path (admission control
        -> coalescer -> SQLite inference work queue -> worker -> result router) and answered with a whitespace-heartbeat
        chunked JSON response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Chat completion, streamed (SSE) or chunked JSON.
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate:
    post:
      operationId: generate
      summary: Submit a batch of prompts to the inference queue
      tags:
      - Generate
      description: 'Enqueues a batch of independent inference requests. Each prompt entry is a bare string,
        a {prompt: ...} object, or a {messages: [...]} object rendered with the model chat template at
        enqueue time.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/get_results:
    post:
      operationId: getResults
      summary: Fetch results for queued request ids
      tags:
      - Generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetResultsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/get_work:
    post:
      operationId: getWork
      summary: Pull work items from the inference queue
      tags:
      - Generate
      description: 'Worker-facing: claims up to batch_size queued requests plus any new adaptors.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetWorkRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWorkResponses'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/finish_work:
    post:
      operationId: finishWork
      summary: Return completed work to the queue
      tags:
      - Generate
      description: 'Worker-facing: acknowledges one or more claimed requests with their response, error
        and token/flop accounting.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinishWorkRequests'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/upload:
    post:
      operationId: uploadGenerateData
      summary: Upload inference payload data
      tags:
      - Generate
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResult'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/download:
    post:
      operationId: downloadGenerateData
      summary: Download the payload for a request id
      tags:
      - Generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/clear_queue:
    post:
      operationId: clearQueue
      summary: Clear the inference work queue
      tags:
      - Generate
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/get_adaptors:
    post:
      operationId: getAdaptors
      summary: List adaptors newer than the caller's loaded set
      tags:
      - Generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAdaptorsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAdaptorsResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/metrics:
    get:
      operationId: getGenerateMetrics
      summary: Inference queue metrics
      tags:
      - Generate
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/list_requests:
    get:
      operationId: listRequests
      summary: List recent inference requests
      tags:
      - Generate
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: number
        description: Opaque timestamp cursor for pagination.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
        description: Page size.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/request/{request_id}:
    get:
      operationId: getRequestDetail
      summary: Get one inference request
      tags:
      - Generate
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/endpoints:
    get:
      operationId: listGenerateEndpoints
      summary: List routes registered on the generate router
      tags:
      - Generate
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train:
    post:
      operationId: submitTrainingJob
      summary: Submit a training job
      tags:
      - Training
      description: Accepts a streamed upload of training data plus a job config and launches a Slurm training
        job.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/upload/init:
    post:
      operationId: initChunkedUpload
      summary: Begin a chunked training-data upload
      tags:
      - Training
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadInitRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadInitResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/upload/chunk:
    post:
      operationId: uploadChunk
      summary: Upload one chunk of training data
      tags:
      - Training
      description: Chunk metadata travels in headers, the chunk bytes in the body.
      parameters:
      - name: X-Upload-Id
        in: header
        required: true
        schema:
          type: string
        description: Upload id from initChunkedUpload.
      - name: X-Chunk-Index
        in: header
        required: true
        schema:
          type: integer
        description: Zero-based chunk index.
      - name: X-Chunk-Hash
        in: header
        required: true
        schema:
          type: string
        description: Hash of this chunk.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadChunkResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/upload/finalize:
    post:
      operationId: finalizeChunkedUpload
      summary: Finalize a chunked upload and launch training
      tags:
      - Training
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadFinalizeRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/{job_hash}:
    get:
      operationId: getTrainingJob
      summary: Get training job info
      tags:
      - Training
      parameters:
      - &id002
        name: job_hash
        in: path
        required: true
        schema:
          type: string
        description: Training job hash returned by the train operation.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/{job_hash}/dataset:
    get:
      operationId: getTrainingDataset
      summary: Page through a job's training dataset
      tags:
      - Training
      parameters:
      - *id002
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Free-text filter.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/{job_hash}/dataset/download:
    get:
      operationId: downloadTrainingDataset
      summary: Download a job's dataset.jsonlines
      tags:
      - Training
      description: Streams the dataset verbatim as an attachment. Omit limit for the whole file.
      parameters:
      - *id002
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: First N rows only.
      responses:
        '200':
          description: The job's dataset.jsonlines.
          content:
            application/x-ndjson:
              schema:
                type: string
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/{job_hash}/checkpoints:
    get:
      operationId: listCheckpoints
      summary: List checkpoints written by a training job
      tags:
      - Training
      parameters:
      - *id002
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/{job_hash}/publish:
    post:
      operationId: publishToHuggingFace
      summary: Publish a checkpoint to Hugging Face Hub
      tags:
      - Training
      description: Submits a Slurm publish job and returns immediately with the publish job id; poll getPublishStatus
        for progress. The Hugging Face token is forwarded to sbatch via env var and is never written to
        disk or argv on the API pod.
      parameters:
      - *id002
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/{job_hash}/publish/status:
    get:
      operationId: getPublishStatus
      summary: Latest publish status for a training job
      tags:
      - Training
      parameters:
      - *id002
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/{job_hash}/publish/cancel:
    post:
      operationId: cancelPublish
      summary: Cancel an in-flight publish job
      tags:
      - Training
      description: scancels the publish job and returns the resulting status.
      parameters:
      - *id002
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/{job_hash}/publish/logs:
    get:
      operationId: getPublishLogs
      summary: Tail the publish job logs
      tags:
      - Training
      parameters:
      - *id002
      - name: starting_line_number
        in: query
        required: false
        schema:
          type: integer
          default: 0
      - name: starting_byte_offset
        in: query
        required: false
        schema:
          type: integer
      - name: tail
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/train/logs/{model_name}:
    get:
      operationId: getTrainingLogs
      summary: Stream training logs for a model
      tags:
      - Training
      parameters:
      - name: model_name
        in: path
        required: true
        schema:
          type: string
      - name: starting_line_number
        in: query
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Server-sent event stream of training log lines.
          content:
            text/event-stream:
              schema:
                type: string
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/cancel/{job_hash}:
    post:
      operationId: cancelTrainingJob
      summary: Cancel a training job
      tags:
      - Training
      parameters:
      - *id002
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/restart/{job_hash}:
    post:
      operationId: restartTrainingJob
      summary: Restart a training job
      tags:
      - Training
      parameters:
      - *id002
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/delete/{job_hash}:
    post:
      operationId: deleteTrainingJob
      summary: Delete a training job
      tags:
      - Training
      parameters:
      - *id002
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/list_models:
    get:
      operationId: listDeployedModels
      summary: List models deployed in this ScalarLM instance
      tags:
      - Training
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/squeue:
    get:
      operationId: getMegatronSqueue
      summary: Slurm queue as seen by the training API
      tags:
      - Training
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SqueueResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/gpu_count:
    get:
      operationId: getGpuCount
      summary: Number of GPUs visible to the deployment
      tags:
      - Training
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGPUCountResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/node_count:
    get:
      operationId: getNodeCount
      summary: Number of nodes visible to the deployment
      tags:
      - Training
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNodeCountResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/megatron/endpoints:
    get:
      operationId: listMegatronEndpoints
      summary: List routes registered on the training router
      tags:
      - Training
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/health:
    get:
      operationId: checkHealth
      summary: Service health
      tags:
      - Health
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/health/keepalive:
    get:
      operationId: keepalive
      summary: Liveness probe
      tags:
      - Health
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/health/logs/{service_name}:
    get:
      operationId: getServiceLogs
      summary: Tail logs for one service
      tags:
      - Health
      parameters:
      - name: service_name
        in: path
        required: true
        schema:
          type: string
      - name: starting_line_number
        in: query
        required: false
        schema:
          type: integer
          default: 0
      - name: starting_byte_offset
        in: query
        required: false
        schema:
          type: integer
      - name: tail
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/health/endpoints:
    get:
      operationId: listHealthEndpoints
      summary: List routes registered on the health router
      tags:
      - Health
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/metrics:
    get:
      operationId: getPrometheusMetrics
      summary: Prometheus metrics exposition
      tags:
      - Health
      responses:
        '200':
          description: Prometheus text exposition format.
          content:
            text/plain:
              schema:
                type: string
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slurm/status:
    get:
      operationId: getSlurmStatus
      summary: Slurm cluster status
      tags:
      - Slurm
      description: Queue information plus GPU and node counts.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slurm/squeue:
    get:
      operationId: getSlurmSqueue
      summary: Slurm queue information
      tags:
      - Slurm
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SqueueResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slurm/cancel/{job_id}:
    post:
      operationId: cancelSlurmJob
      summary: Cancel a Slurm job by id
      tags:
      - Slurm
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /slurm/endpoints:
    get:
      operationId: listSlurmEndpoints
      summary: List routes registered on the Slurm router
      tags:
      - Slurm
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: *id001
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    GenerateRequest:
      type: object
      required:
      - prompts
      properties:
        model:
          type:
          - string
          - 'null'
        prompts:
          type: array
          description: 'Batch of independent inference requests. Each entry is a bare string, a {prompt:
            ...} object, or a {messages: [...]} object.'
          items:
            oneOf:
            - type: string
            - type: object
        max_tokens:
          type:
          - integer
          - 'null'
          default: 16
        temperature:
          type:
          - number
          - 'null'
          default: 0.0
        tools:
          type:
          - array
          - 'null'
          items: {}
        tool_choice:
          oneOf:
          - type: string
          - type: object
          - type: 'null'
    Result:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
        response:
          oneOf:
          - type: string
          - type: array
            items:
              type: number
          - type: 'null'
        error:
          type:
          - string
          - 'null'
    GenerateResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
    GetResultsRequest:
      type: object
      required:
      - request_ids
      properties:
        request_ids:
          type: array
          items:
            type: string
    GetWorkRequest:
      type: object
      required:
      - batch_size
      - loaded_adaptor_count
      properties:
        batch_size:
          type: integer
        loaded_adaptor_count:
          type: integer
    GetWorkResponse:
      type: object
      required:
      - prompt
      - request_id
      - request_type
      properties:
        prompt:
          oneOf:
          - type: string
          - type: object
        request_id:
          type: string
        request_type:
          type: string
        model:
          type:
          - string
          - 'null'
        max_tokens:
          type:
          - integer
          - 'null'
    GetWorkResponses:
      type: object
      required:
      - requests
      - new_adaptors
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/GetWorkResponse'
        new_adaptors:
          $ref: '#/components/schemas/GetAdaptorsResponse'
    FinishWorkRequest:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
        response:
          oneOf:
          - type: string
          - type: array
            items:
              type: number
          - type: 'null'
        error:
          type:
          - string
          - 'null'
        token_count:
          type:
          - integer
          - 'null'
        prompt_tokens:
          type:
          - integer
          - 'null'
        completion_tokens:
          type:
          - integer
          - 'null'
        flop_count:
          type:
          - integer
          - 'null'
    FinishWorkRequests:
      type: object
      required:
      - requests
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/FinishWorkRequest'
    GetAdaptorsRequest:
      type: object
      required:
      - loaded_adaptor_count
      properties:
        loaded_adaptor_count:
          type: integer
    GetAdaptorsResponse:
      type: object
      required:
      - new_adaptors
      properties:
        new_adaptors:
          type: array
          items:
            type: string
    DownloadRequest:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
    UploadResult:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
        error:
          type:
          - string
          - 'null'
    MetricsResponse:
      type: object
      required:
      - queue_depth
      - total_completed_requests
      - total_completed_tokens
      - total_completed_response_time
      - tokens_per_second
      - requests_per_second
      - flops_per_second
      properties:
        queue_depth:
          type: integer
        total_completed_requests:
          type: integer
        total_completed_tokens:
          type: integer
        total_completed_response_time:
          type: number
        tokens_per_second:
          type: number
        requests_per_second:
          type: number
        flops_per_second:
          type: number
    TrainResponse:
      type: object
      required:
      - job_status
      - job_config
      properties:
        job_status:
          type: object
          additionalProperties: true
        job_config:
          type: object
          additionalProperties: true
        deployed:
          type:
          - boolean
          - 'null'
          default: false
    UploadInitRequest:
      type: object
      required:
      - total_size
      - total_hash
      - chunk_size
      - num_chunks
      - params
      properties:
        total_size:
          type: integer
        total_hash:
          type: string
        chunk_size:
          type: integer
        num_chunks:
          type: integer
        compressed:
          type: boolean
          default: true
        params:
          type: object
          additionalProperties: true
    UploadInitResponse:
      type: object
      required:
      - upload_id
      properties:
        upload_id:
          type: string
        received_chunks:
          type: array
          items:
            type: integer
          default: []
    UploadChunkResponse:
      type: object
      required:
      - upload_id
      - chunk_index
      - received
      - bytes_written
      properties:
        upload_id:
          type: string
        chunk_index:
          type: integer
        received:
          type: boolean
        bytes_written:
          type: integer
    UploadFinalizeRequest:
      type: object
      required:
      - upload_id
      properties:
        upload_id:
          type: string
    PublishRequest:
      type: object
      required:
      - repo_id
      - hf_token
      properties:
        mode:
          type: string
          default: merged
          description: merged to fold LoRA into base, adapter for a PEFT-format adapter repo.
        repo_id:
          type: string
          description: HuggingFace repo to push to (owner/name).
        private:
          type: boolean
          default: false
          description: Create the repo as private if it doesn't exist.
        hf_token:
          type: string
          description: HuggingFace access token with write permission.
        checkpoint:
          type:
          - string
          - 'null'
          description: Basename of checkpoint_<step>.pt to publish. Defaults to latest.
        lora_alpha:
          type:
          - integer
          - 'null'
          description: Override the lora_alpha used at merge time.
        commit_message:
          type:
          - string
          - 'null'
          description: HF commit message; auto-generated if omitted.
    ListModelsResponse:
      type: object
      required:
      - models
      properties:
        models:
          type: array
          items:
            type: object
            additionalProperties: true
    SqueueResponse:
      type: object
      properties:
        squeue_output:
          type:
          - string
          - 'null'
        error_message:
          type:
          - string
          - 'null'
    GetGPUCountResponse:
      type: object
      required:
      - gpu_count
      properties:
        gpu_count:
          type: integer
    GetNodeCountResponse:
      type: object
      required:
      - node_count
      properties:
        node_count:
          type: integer
    CompletionRequest:
      type: object
      required:
      - prompt
      description: vLLM's OpenAI-compatible CompletionRequest, imported by the router from vllm.entrypoints.openai.completion.protocol.
        The authoritative field list is vLLM's, not ScalarLM's; only the fields on the router's allow-list
        are forwarded upstream.
      properties:
        model:
          type: string
        prompt:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        max_tokens:
          type: integer
        temperature:
          type: number
        stream:
          type: boolean
      additionalProperties: true
    ChatCompletionRequest:
      type: object
      required:
      - messages
      description: vLLM's OpenAI-compatible ChatCompletionRequest, imported by the router from vllm.entrypoints.openai.chat_completion.protocol.
        The authoritative field list is vLLM's, not ScalarLM's. stream selects the direct SSE proxy path
        vs the queue-backed path.
      properties:
        model:
          type: string
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        max_tokens:
          type: integer
        temperature:
          type: number
        stream:
          type: boolean
        tools:
          type: array
          items:
            type: object
      additionalProperties: true
    ChatMessage:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          type: string
    ValidationError:
      type: object
      required:
      - loc
      - msg
      - type
      properties:
        loc:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
        msg:
          type: string
        type:
          type: string
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'