---
title: "Fine-tuning"
canonical: https://docs.qvac.tether.io/sdk/v0.23/ai-capabilities/fine-tuning/
collection: "SDK"
package: "@qvac/sdk"
line: v0.23
current_line: false
---

# Fine-tuning (/sdk/v0.23/ai-capabilities/fine-tuning)



## Overview

Fine-tuning trains a [LoRA](https://arxiv.org/abs/2106.09685) (Low-Rank Adaptation) adapter on top of an LLM base model, to be used at inference time with [completion](/sdk/v0.23/ai-capabilities/text-generation).

Load any supported LLM using `modelType: "llm"`. Then call `finetune()` with the dataset and training settings. Training can be done in two modes:

* [SFT](#sft): chat-based; enable with `assistantLossOnly: true`.
* [Causal](#causal): raw text; default (`assistantLossOnly: false`).

The output is a small `.gguf` adapter file that you can pass to `completion()` via `modelConfig.lora`.

## Functions

Use the following sequence of function calls:

1. [`loadModel()`](/sdk/v0.23/reference/api#loadmodel)
2. [`finetune()`](/sdk/v0.23/reference/api#finetune)
3. [`unloadModel()`](/sdk/v0.23/reference/api#unloadmodel)

For how to use each function, see [SDK — API reference](/sdk/v0.23/reference/api/).

## Models

You can load any `llama.cpp`-compatible [text-generation/chat](/sdk/v0.23/ai-capabilities/text-generation) model that meets the following criteria:

* **File format:** `*.gguf` (or use constants)
* **Architecture:** `qwen3`, `gemma3`, or `bitnet`
* **Quantization:** `F32`, `F16`, `Q4_0`, `Q8_0`, `TQ1_0`, or `TQ2_0`

<Callout type="info">
  In QVAC, not every model compatible with text generation/chat is also compatible with fine-tuning. Only those that meet all the criteria above are.
</Callout>

For models available as constants, see [SDK — Models](/sdk/v0.23/#models). Note that not every model constant is fine-tunable: for example, many Qwen3-4B/8B constants are `Q4_K_M`. Check a model's quantization with [`getModelInfo()`](/sdk/v0.23/reference/api#getmodelinfo) before training.

## Training

### SFT

Supervised fine-tuning (SFT) teaches the model how to respond to prompts. Use it for chat tuning, instruction following, or any task where you want to shape assistant responses.

**Dataset format:** JSONL where each line is a JSON object with a `messages` array. Supported roles: `system`, `user`, `assistant`, and `tool`. Example:

```jsonl
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"},{"role":"assistant","content":"2+2 equals 4."}]}
{"messages":[{"role":"user","content":"What is the capital of France?"},{"role":"assistant","content":"The capital of France is Paris."}]}
```

### Causal

Causal fine-tuning adapts the model to a domain by training on raw text. Use it for domain adaptation, style transfer, or tasks where you want the model to better reflect specialized vocabulary, patterns, or tone.

**Dataset format:** plain text file. Example:

```
This is sample training text.
Another paragraph of content.
```

## Example

The example trains on a small SFT dataset with a separate eval file. Save both next to the example, as `train.jsonl` and `eval.jsonl`, then swap in your own data — the example reads whatever those two files contain.

<Tabs>
  <Tab value="train" label="train.jsonl" default>
    <WrapCode>
      ```jsonl file=<rootDir>/packages/sdk/examples/finetune/train.jsonl title="train.jsonl" lineNumbers
      {"messages":[{"role":"system","content":"Answer in one short sentence."},{"role":"user","content":"What is the capital of Japan?"},{"role":"assistant","content":"Tokyo is the capital of Japan."}]}
      {"messages":[{"role":"system","content":"Answer in one short sentence."},{"role":"user","content":"How many continents are there?"},{"role":"assistant","content":"There are seven continents."}]}
      {"messages":[{"role":"user","content":"At what temperature does water boil at sea level?"},{"role":"assistant","content":"Water boils at 100 degrees Celsius at sea level."}]}
      {"messages":[{"role":"user","content":"Which planet is closest to the Sun?"},{"role":"assistant","content":"Mercury is the planet closest to the Sun."}]}
      {"messages":[{"role":"user","content":"What is the largest ocean on Earth?"},{"role":"assistant","content":"The Pacific is the largest ocean on Earth."}]}
      {"messages":[{"role":"user","content":"How many bones are in the adult human body?"},{"role":"assistant","content":"An adult human body has 206 bones."}]}
      {"messages":[{"role":"user","content":"What gas do plants absorb from the air?"},{"role":"assistant","content":"Plants absorb carbon dioxide from the air."}]}
      {"messages":[{"role":"user","content":"What is the chemical symbol for iron?"},{"role":"assistant","content":"The chemical symbol for iron is Fe."}]}
      {"messages":[{"role":"user","content":"Which river is the longest in Africa?"},{"role":"assistant","content":"The Nile is the longest river in Africa."}]}
      {"messages":[{"role":"user","content":"How many sides does a hexagon have?"},{"role":"assistant","content":"A hexagon has six sides."}]}
      {"messages":[{"role":"user","content":"What is the speed of light in a vacuum?"},{"role":"assistant","content":"Light travels at about 300,000 kilometres per second in a vacuum."}]}
      {"messages":[{"role":"user","content":"Which metal is liquid at room temperature?"},{"role":"assistant","content":"Mercury is liquid at room temperature."}]}
      {"messages":[{"role":"user","content":"What is the smallest prime number?"},{"role":"assistant","content":"Two is the smallest prime number."}]}
      {"messages":[{"role":"user","content":"How long does the Earth take to orbit the Sun?"},{"role":"assistant","content":"The Earth takes about 365 days to orbit the Sun."}]}
      {"messages":[{"role":"user","content":"What is the hardest natural substance?"},{"role":"assistant","content":"Diamond is the hardest natural substance."}]}
      {"messages":[{"role":"user","content":"Which organ pumps blood through the body?"},{"role":"assistant","content":"The heart pumps blood through the body."}]}
      {"messages":[{"role":"user","content":"What is the main gas in the Earth's atmosphere?"},{"role":"assistant","content":"Nitrogen is the main gas in the Earth's atmosphere."}]}
      {"messages":[{"role":"user","content":"How many degrees are in a right angle?"},{"role":"assistant","content":"A right angle has 90 degrees."}]}
      {"messages":[{"role":"user","content":"Which country has the largest population?"},{"role":"assistant","content":"India has the largest population."}]}
      {"messages":[{"role":"user","content":"What is the freezing point of water in Fahrenheit?"},{"role":"assistant","content":"Water freezes at 32 degrees Fahrenheit."}]}
      {"messages":[{"role":"user","content":"What does DNA stand for?"},{"role":"assistant","content":"DNA stands for deoxyribonucleic acid."}]}
      {"messages":[{"role":"user","content":"Which mountain is the tallest above sea level?"},{"role":"assistant","content":"Mount Everest is the tallest mountain above sea level."}]}
      {"messages":[{"role":"user","content":"How many players are on a football team on the pitch?"},{"role":"assistant","content":"A football team fields eleven players."}]}
      {"messages":[{"role":"user","content":"What is the currency of the United Kingdom?"},{"role":"assistant","content":"The currency of the United Kingdom is the pound sterling."}]}
      ```
    </WrapCode>
  </Tab>

  <Tab value="eval" label="eval.jsonl">
    <WrapCode>
      ```jsonl file=<rootDir>/packages/sdk/examples/finetune/eval.jsonl title="eval.jsonl" lineNumbers
      {"messages":[{"role":"system","content":"Answer in one short sentence."},{"role":"user","content":"What is the capital of Brazil?"},{"role":"assistant","content":"Brasília is the capital of Brazil."}]}
      {"messages":[{"role":"user","content":"Which planet has the most moons?"},{"role":"assistant","content":"Saturn has the most moons."}]}
      {"messages":[{"role":"user","content":"What is the chemical symbol for gold?"},{"role":"assistant","content":"The chemical symbol for gold is Au."}]}
      {"messages":[{"role":"user","content":"How many millilitres are in a litre?"},{"role":"assistant","content":"A litre contains 1,000 millilitres."}]}
      {"messages":[{"role":"user","content":"Which desert is the largest hot desert?"},{"role":"assistant","content":"The Sahara is the largest hot desert."}]}
      {"messages":[{"role":"user","content":"What organ filters blood in the human body?"},{"role":"assistant","content":"The kidneys filter blood in the human body."}]}
      {"messages":[{"role":"user","content":"How many strings does a standard guitar have?"},{"role":"assistant","content":"A standard guitar has six strings."}]}
      {"messages":[{"role":"user","content":"What is the largest mammal?"},{"role":"assistant","content":"The blue whale is the largest mammal."}]}
      ```
    </WrapCode>
  </Tab>
</Tabs>

The following script loads an LLM, runs fine-tuning on that dataset, and optionally demonstrates pause/resume when invoked with `--pause-resume`. The adapter and its checkpoints land in `./finetune-output`:

<Tabs>
  <Tab value="js" label="JavaScript" default>
    <WrapCode>
      ```js file=<rootDir>/packages/sdk/dist/examples/finetune/llamacpp-finetune.js title="llamacpp-finetune.js" lineNumbers
      import path from 'node:path';
      import { fileURLToPath } from 'node:url';
      import { finetune, loadModel, QWEN3_600M_INST_Q4, unloadModel } from '@qvac/sdk';
      const pauseResumeEnabled = process.argv.includes('--pause-resume');
      // The worker resolves dataset paths against the process working directory, so
      // derive them from this file's own folder instead.
      const datasetDir = path.dirname(fileURLToPath(import.meta.url));
      let modelId;
      let exitCode = 0;
      async function readProgress(handle, onTick) {
          for await (const tick of handle.progressStream) {
              const phase = tick.is_train ? 'train' : 'val';
              console.log(`▸ epoch=${tick.current_epoch + 1} step=${tick.global_steps} batch=${tick.current_batch}/${tick.total_batches} ${phase} loss=${tick.loss?.toFixed(4)} acc=${tick.accuracy?.toFixed(4)} eta=${Math.round(tick.eta_ms / 1000)}s`);
              onTick(tick.global_steps);
          }
      }
      try {
          modelId = await loadModel({
              modelSrc: QWEN3_600M_INST_Q4,
              modelConfig: {
                  device: 'gpu',
                  ctx_size: 512
              }
          });
          console.log(`▸ Model loaded with ID: ${modelId}`);
          const loadedModelId = modelId;
          const finetuneParams = {
              modelId: loadedModelId,
              options: {
                  trainDatasetDir: path.join(datasetDir, 'train.jsonl'),
                  validation: {
                      type: 'dataset',
                      path: path.join(datasetDir, 'eval.jsonl')
                  },
                  numberOfEpochs: 2,
                  learningRate: 1e-4,
                  lrMin: 1e-8,
                  loraModules: 'attn_q,attn_k,attn_v,attn_o,ffn_gate,ffn_up,ffn_down',
                  assistantLossOnly: true,
                  checkpointSaveSteps: 2,
                  checkpointSaveDir: './finetune-output/checkpoints',
                  outputParametersDir: './finetune-output'
              }
          };
          const handle = finetune(finetuneParams);
          let pauseRequested = false;
          let pauseResultPromise;
          const progressTask = readProgress(handle, (globalSteps) => {
              if (pauseResumeEnabled && !pauseRequested && globalSteps >= 10) {
                  pauseRequested = true;
                  console.log('▸ Requesting a pause so the run can be resumed...');
                  pauseResultPromise = finetune({
                      modelId: loadedModelId,
                      operation: 'pause'
                  });
              }
          });
          const initialResult = await handle.result;
          await progressTask;
          if (pauseResultPromise) {
              await pauseResultPromise;
          }
          console.log('▸ Initial finetune result:', initialResult);
          if (pauseResumeEnabled && initialResult.status === 'PAUSED') {
              console.log('▸ Resuming from the saved checkpoint...');
              const resumedHandle = finetune({
                  ...finetuneParams,
                  operation: 'resume'
              });
              const resumedProgressTask = readProgress(resumedHandle, function () { });
              const resumedResult = await resumedHandle.result;
              await resumedProgressTask;
              console.log('▸ Resumed finetune result:', resumedResult);
          }
      }
      catch (error) {
          console.error('✖', error);
          exitCode = 1;
      }
      finally {
          if (modelId) {
              await unloadModel({ modelId, clearStorage: false });
          }
      }
      process.exit(exitCode);
      ```
    </WrapCode>
  </Tab>

  <Tab value="ts" label="TypeScript">
    <WrapCode>
      ```ts file=<rootDir>/packages/sdk/examples/finetune/llamacpp-finetune.ts title="llamacpp-finetune.ts" lineNumbers
      import path from 'node:path'
      import { fileURLToPath } from 'node:url'
      import {
        finetune,
        loadModel,
        QWEN3_600M_INST_Q4,
        unloadModel,
        type FinetuneHandle,
        type FinetuneResult,
        type FinetuneRunParams
      } from '@qvac/sdk'

      const pauseResumeEnabled = process.argv.includes('--pause-resume')

      // The worker resolves dataset paths against the process working directory, so
      // derive them from this file's own folder instead.
      const datasetDir = path.dirname(fileURLToPath(import.meta.url))

      let modelId: string | undefined
      let exitCode = 0

      async function readProgress(handle: FinetuneHandle, onTick: (globalSteps: number) => void) {
        for await (const tick of handle.progressStream) {
          const phase = tick.is_train ? 'train' : 'val'
          console.log(
            `▸ epoch=${tick.current_epoch + 1} step=${tick.global_steps} batch=${tick.current_batch}/${tick.total_batches} ${phase} loss=${tick.loss?.toFixed(4)} acc=${tick.accuracy?.toFixed(4)} eta=${Math.round(tick.eta_ms / 1000)}s`
          )

          onTick(tick.global_steps)
        }
      }

      try {
        modelId = await loadModel({
          modelSrc: QWEN3_600M_INST_Q4,
          modelConfig: {
            device: 'gpu',
            ctx_size: 512
          }
        })

        console.log(`▸ Model loaded with ID: ${modelId}`)
        const loadedModelId = modelId

        const finetuneParams: FinetuneRunParams = {
          modelId: loadedModelId,
          options: {
            trainDatasetDir: path.join(datasetDir, 'train.jsonl'),
            validation: {
              type: 'dataset',
              path: path.join(datasetDir, 'eval.jsonl')
            },
            numberOfEpochs: 2,
            learningRate: 1e-4,
            lrMin: 1e-8,
            loraModules: 'attn_q,attn_k,attn_v,attn_o,ffn_gate,ffn_up,ffn_down',
            assistantLossOnly: true,
            checkpointSaveSteps: 2,
            checkpointSaveDir: './finetune-output/checkpoints',
            outputParametersDir: './finetune-output'
          }
        }

        const handle = finetune(finetuneParams)
        let pauseRequested = false
        let pauseResultPromise: Promise<FinetuneResult> | undefined

        const progressTask = readProgress(handle, (globalSteps) => {
          if (pauseResumeEnabled && !pauseRequested && globalSteps >= 10) {
            pauseRequested = true
            console.log('▸ Requesting a pause so the run can be resumed...')
            pauseResultPromise = finetune({
              modelId: loadedModelId,
              operation: 'pause'
            })
          }
        })

        const initialResult = await handle.result
        await progressTask

        if (pauseResultPromise) {
          await pauseResultPromise
        }

        console.log('▸ Initial finetune result:', initialResult)

        if (pauseResumeEnabled && initialResult.status === 'PAUSED') {
          console.log('▸ Resuming from the saved checkpoint...')

          const resumedHandle = finetune({
            ...finetuneParams,
            operation: 'resume'
          })
          const resumedProgressTask = readProgress(resumedHandle, function () {})

          const resumedResult = await resumedHandle.result
          await resumedProgressTask

          console.log('▸ Resumed finetune result:', resumedResult)
        }
      } catch (error) {
        console.error('✖', error)
        exitCode = 1
      } finally {
        if (modelId) {
          await unloadModel({ modelId, clearStorage: false })
        }
      }

      process.exit(exitCode)
      ```
    </WrapCode>
  </Tab>

  <Tab value="python" label="Python">
    <WrapCode>
      ```python file=<rootDir>/packages/sdk-python/examples/finetune.py title="finetune.py" lineNumbers
      """Python port of packages/sdk/examples/finetune/llamacpp-finetune.ts.

      LoRA fine-tuning on a chat dataset with a separate eval file, printing every
      progress tick. Pass `--pause-resume` to pause the run mid-training and resume
      it from the last checkpoint.

      `finetune_with_progress` is a server-stream: it yields `FinetuneProgressResponse`
      ticks and ends with the terminal `FinetuneResponse`. A pause is a separate unary
      `finetune` call carrying `operation="pause"`, sent while that stream is open.

      `train.jsonl` and `eval.jsonl` must sit next to this file. The adapter and its
      checkpoints are written under `./finetune-output`, relative to the directory you
      run from.

      RUN: python examples/finetune.py [--pause-resume]
      """

      from __future__ import annotations

      import asyncio
      import sys
      from pathlib import Path

      from tetherto.qvac_sdk import (
          Client,
          FinetuneRequest,
          finetune,
          finetune_with_progress,
          load_model,
          unload_model,
      )
      from tetherto.qvac_sdk.models import QWEN3_600M_INST_Q4

      # The worker resolves dataset paths against the process working directory, so
      # derive them from this file's own folder instead.
      DATASET_DIR = Path(__file__).parent
      RESULTS_DIR = "./finetune-output"


      def tick_line(tick) -> str:
          """One progress tick, train or validation."""
          phase = "train" if tick.is_train else "val"
          # loss and accuracy are absent on some ticks, so guard the formatting.
          loss = f"{tick.loss:.4f}" if tick.loss is not None else "-"
          accuracy = f"{tick.accuracy:.4f}" if tick.accuracy is not None else "-"
          return (
              f"▸ epoch={tick.current_epoch + 1} step={tick.global_steps}"
              f" batch={tick.current_batch}/{tick.total_batches} {phase}"
              f" loss={loss} acc={accuracy} eta={round(tick.eta_ms / 1000)}s"
          )


      async def read_progress(t, request, on_tick=None):
          """Print each tick as it arrives; return the terminal result."""
          result = None
          async for frame in finetune_with_progress(t, request):
              if frame.type == "finetune":
                  result = frame
                  continue
              print(tick_line(frame))
              if on_tick is not None:
                  on_tick(frame.global_steps)
          return result


      async def main() -> int:
          pause_resume_enabled = "--pause-resume" in sys.argv

          async with Client() as client:
              t = client.transport
              model_id = None
              try:
                  model_id = await load_model(
                      t,
                      model_src=QWEN3_600M_INST_Q4,
                      model_config={"device": "gpu", "ctx_size": 512},
                  )
                  print(f"▸ Model loaded with ID: {model_id}")

                  finetune_params = {
                      "type": "finetune",
                      "modelId": model_id,
                      "options": {
                          "trainDatasetDir": str(DATASET_DIR / "train.jsonl"),
                          "validation": {
                              "type": "dataset",
                              "path": str(DATASET_DIR / "eval.jsonl"),
                          },
                          "numberOfEpochs": 2,
                          "learningRate": 1e-4,
                          "lrMin": 1e-8,
                          "loraModules": "attn_q,attn_k,attn_v,attn_o,ffn_gate,ffn_up,ffn_down",
                          "assistantLossOnly": True,
                          "checkpointSaveSteps": 2,
                          "checkpointSaveDir": f"{RESULTS_DIR}/checkpoints",
                          "outputParametersDir": RESULTS_DIR,
                      },
                  }

                  pause_task = None

                  def request_pause(global_steps) -> None:
                      nonlocal pause_task
                      if not pause_resume_enabled or pause_task is not None:
                          return
                      if global_steps >= 10:
                          print("▸ Requesting a pause so the run can be resumed...")
                          # Fired as a task: the progress stream above is still being
                          # drained, and the pause reply arrives on its own call.
                          pause_task = asyncio.create_task(
                              finetune(
                                  t,
                                  FinetuneRequest.model_validate(
                                      {
                                          "type": "finetune",
                                          "modelId": model_id,
                                          "operation": "pause",
                                      }
                                  ),
                              )
                          )

                  initial_result = await read_progress(
                      t,
                      FinetuneRequest.model_validate(finetune_params),
                      request_pause,
                  )

                  if pause_task is not None:
                      await pause_task

                  print(f"▸ Initial finetune result: {initial_result}")

                  # `status` is a generated enum, so compare its `.value`.
                  if (
                      pause_resume_enabled
                      and initial_result is not None
                      and initial_result.status.value == "PAUSED"
                  ):
                      print("▸ Resuming from the saved checkpoint...")
                      resumed_result = await read_progress(
                          t,
                          FinetuneRequest.model_validate(
                              {**finetune_params, "operation": "resume"}
                          ),
                      )
                      print(f"▸ Resumed finetune result: {resumed_result}")
              except Exception as error:
                  print(f"✖ {error}", file=sys.stderr)
                  return 1
              finally:
                  if model_id is not None:
                      await unload_model(t, model_id)
          return 0


      if __name__ == "__main__":
          sys.exit(asyncio.run(main()))
      ```
    </WrapCode>
  </Tab>

  <Tab value="kotlin" label="Kotlin">
    <WrapCode>
      ```kotlin file=<rootDir>/packages/sdk-kotlin/examples/src/Finetune.kt title="Finetune.kt" lineNumbers
      // Kotlin port of packages/sdk/examples/finetune/llamacpp-finetune.ts.
      //
      // LoRA fine-tuning on a chat dataset with a separate eval file, printing every
      // progress tick. Pass `--pause-resume` to pause the run mid-training and resume
      // it from the last checkpoint.
      //
      // `client.training.progress()` is a server stream: a `Flow` of
      // `QvacProgressEvent`s, `Progress` for each `FinetuneProgressResponse` tick and
      // `Result` for the terminal `FinetuneResponse`. A pause is a separate unary
      // `client.training.execute()` call carrying a `FinetuneStopRequest` with
      // `operation = PAUSE`, sent from a child coroutine while that stream is open.
      //
      // The request is the generated typed `FinetuneRunRequest`: the validation mode
      // is a sealed arm (`Dataset`, `Split`, `None`), operations and the result
      // `status` are enums, and resuming is a `copy(operation = RESUME)` of the same
      // request. Set `withProgress = true` on the request to receive the ticks.
      //
      // The datasets are the `train.jsonl` and `eval.jsonl` in the examples
      // directory, where `run` executes; pass another directory as an argument to use
      // your own. The worker resolves dataset paths against its own working
      // directory, so they are made absolute first. The adapter and its checkpoints
      // are written under `./finetune-output`.
      //
      // RUN: ./gradlew -p examples run -Pexample=Finetune --args="[--pause-resume] [<dataset dir>]"

      import io.tether.qvac.sdk.QvacClient
      import io.tether.qvac.sdk.QvacProgressEvent
      import io.tether.qvac.sdk.generated.Models
      import io.tether.qvac.sdk.generated.schema.FinetuneProgressResponse
      import io.tether.qvac.sdk.generated.schema.FinetuneProgressResponseAccuracy
      import io.tether.qvac.sdk.generated.schema.FinetuneProgressResponseLoss
      import io.tether.qvac.sdk.generated.schema.FinetuneRequest
      import io.tether.qvac.sdk.generated.schema.FinetuneResponse
      import io.tether.qvac.sdk.generated.schema.FinetuneResponseStatus
      import io.tether.qvac.sdk.generated.schema.FinetuneRunRequest
      import io.tether.qvac.sdk.generated.schema.FinetuneRunRequestOperation
      import io.tether.qvac.sdk.generated.schema.FinetuneRunRequestOptions
      import io.tether.qvac.sdk.generated.schema.FinetuneRunRequestOptionsValidation
      import io.tether.qvac.sdk.generated.schema.FinetuneRunRequestOptionsValidationDataset
      import io.tether.qvac.sdk.generated.schema.FinetuneStopRequest
      import io.tether.qvac.sdk.generated.schema.FinetuneStopRequestOperation
      import io.tether.qvac.sdk.jvm.JvmBareKitTransport
      import io.tether.qvac.sdk.models
      import io.tether.qvac.sdk.training
      import java.nio.file.Path
      import kotlin.math.roundToLong
      import kotlinx.coroutines.Deferred
      import kotlinx.coroutines.async
      import kotlinx.coroutines.runBlocking
      import kotlinx.serialization.json.buildJsonObject
      import kotlinx.serialization.json.put

      // Relative to the directory `./gradlew run` executes in (packages/sdk-kotlin/examples).
      private const val DEFAULT_DATASET_DIR = "."
      private const val RESULTS_DIR = "./finetune-output"

      /** One progress tick, train or validation. */
      private fun tickLine(tick: FinetuneProgressResponse): String {
          val phase = if (tick.is_train) "train" else "val"
          // loss and accuracy are absent on some ticks, so guard the formatting.
          val loss = (tick.loss as? FinetuneProgressResponseLoss.Variant1)?.let { "%.4f".format(it.value) } ?: "-"
          val accuracy = (tick.accuracy as? FinetuneProgressResponseAccuracy.Variant1)?.let { "%.4f".format(it.value) }
              ?: "-"
          return "▸ epoch=${tick.current_epoch + 1} step=${tick.global_steps}" +
              " batch=${tick.current_batch}/${tick.total_batches} $phase" +
              " loss=$loss acc=$accuracy eta=${(tick.eta_ms / 1000).roundToLong()}s"
      }

      /** Print each tick as it arrives; return the terminal result. */
      private suspend fun QvacClient.readProgress(
          request: FinetuneRunRequest,
          onTick: (Long) -> Unit = {},
      ): FinetuneResponse? {
          var result: FinetuneResponse? = null
          training.progress(FinetuneRequest.FinetuneRunRequest(request)).collect { event ->
              when (event) {
                  is QvacProgressEvent.Progress -> {
                      println(tickLine(event.value))
                      onTick(event.value.global_steps)
                  }
                  is QvacProgressEvent.Result -> result = event.value
              }
          }
          return result
      }

      fun main(args: Array<String>): Unit = runBlocking {
          val pauseResumeEnabled = "--pause-resume" in args
          val datasetDir = Path.of(args.firstOrNull { !it.startsWith("--") } ?: DEFAULT_DATASET_DIR)
              .toAbsolutePath()
              .normalize()

          val client = QvacClient(JvmBareKitTransport.connect())
          var modelId: String? = null
          try {
              val model = Models.QWEN3_600M_INST_Q4
              val loaded = client.models.load(
                  source = model.src,
                  modelType = model.engine,
                  modelName = model.name,
                  modelConfig = buildJsonObject {
                      put("device", "gpu")
                      put("ctx_size", 512)
                  },
              )
              val id = loaded.modelId ?: error(loaded.error ?: "loadModel failed")
              modelId = id
              println("▸ Model loaded with ID: $id")

              val finetuneRequest = FinetuneRunRequest(
                  modelId = id,
                  withProgress = true,
                  options = FinetuneRunRequestOptions(
                      trainDatasetDir = datasetDir.resolve("train.jsonl").toString(),
                      validation = FinetuneRunRequestOptionsValidation.Dataset(
                          FinetuneRunRequestOptionsValidationDataset(path = datasetDir.resolve("eval.jsonl").toString()),
                      ),
                      numberOfEpochs = 2,
                      learningRate = 1e-4,
                      lrMin = 1e-8,
                      loraModules = "attn_q,attn_k,attn_v,attn_o,ffn_gate,ffn_up,ffn_down",
                      assistantLossOnly = true,
                      checkpointSaveSteps = 2,
                      checkpointSaveDir = "$RESULTS_DIR/checkpoints",
                      outputParametersDir = RESULTS_DIR,
                  ),
              )

              var pauseCall: Deferred<FinetuneResponse>? = null

              val initialResult = client.readProgress(finetuneRequest) { globalSteps ->
                  if (pauseResumeEnabled && pauseCall == null && globalSteps >= 10) {
                      println("▸ Requesting a pause so the run can be resumed...")
                      // A child coroutine: the progress stream is still being
                      // collected, and the pause reply arrives on its own call.
                      pauseCall = async {
                          client.training.execute(
                              FinetuneRequest.FinetuneStopRequest(
                                  FinetuneStopRequest(modelId = id, operation = FinetuneStopRequestOperation.PAUSE),
                              ),
                          )
                      }
                  }
              }

              pauseCall?.await()

              println("▸ Initial finetune result: $initialResult")

              if (pauseResumeEnabled && initialResult?.status == FinetuneResponseStatus.PAUSED) {
                  println("▸ Resuming from the saved checkpoint...")
                  val resumedResult = client.readProgress(
                      finetuneRequest.copy(operation = FinetuneRunRequestOperation.RESUME),
                  )
                  println("▸ Resumed finetune result: $resumedResult")
              }
          } finally {
              modelId?.let { client.models.unload(it) }
              client.close()
          }
      }
      ```
    </WrapCode>
  </Tab>
</Tabs>

<Callout type="success">
  **Tip:** all examples throughout this documentation are self-contained and runnable. For instructions on how to run them, see the [JS/TS quickstart](/sdk/v0.23/js-ts-sdk#quickstart), the [Python quickstart](/sdk/v0.23/python-sdk#quickstart), or the [Kotlin quickstart](/sdk/v0.23/kotlin-sdk#quickstart).
</Callout>
