---
name: valcairn
description: Post-train a model the user owns with Valcairn and prove it got better. Use when the user wants to check a JSONL training file, start or follow a training run on their devices, compare a tuned model with the original on frozen evaluation cases, or verify a signed Valcairn record. Uses the `valcairn` command-line tool or the Valcairn MCP tools.
---

# Working with Valcairn

Valcairn post-trains a model the user owns, on hardware they already have, and proves it got better. You act
through the `valcairn` command-line tool (add `--json` to every command) or the Valcairn MCP tools, which do the same
things. Both sign in with a workspace API key the user created on the workspace's API keys page.

## Before anything: sign-in

- Check with `valcairn runs --json`. A `No valid API key` or `No workspace` error means the user must run
  `valcairn login --url <their Valcairn site> --workspace <workspace id>` themselves. Never ask them to paste a key
  into the chat.
- A read-only key can check, read and verify. Starting a run needs a full key; if you get `api_key_read_only`, tell
  the user and stop.

## The order of steps

1. **Check the file locally.** `valcairn check train.jsonl --json` (MCP: `check_training_file`). Free, offline.
   Fix every reported line, or tell the user which lines will be skipped. Training needs at least 5 distinct examples;
   about one in ten is held out for evaluation.
2. **Find the dataset.** Training uses a frozen, approved dataset version in a project, not the local file. List
   projects with `list_projects` (or ask the user). If the data is not uploaded and approved yet, the user does that
   in the web app; you cannot.
3. **Plan, ask, then start.** `valcairn start --method lora --model <id> --dataset <project id> --json`
   (MCP: `start_training` without `confirmation`). Nothing starts. Show the user the plan: model, method, dataset
   versions, machines, time estimate and credit cost. **Ask the user and wait for a clear yes.** Then repeat the
   identical command with `--request-key <requestKey> --confirm <code>` (MCP: same arguments plus `requestKey` and
   `confirmation`). The code expires after 10 minutes; if it does, plan again and ask again.
4. **Follow the run.** `valcairn status <run id> --json` (MCP: `get_run_status`). Poll no more than every 15 seconds.
5. **Compare.** When the user has answers from both models on a frozen evaluation version:
   `valcairn compare --project <id> --set <id> --version <id> --baseline <batch> --candidate <batch> --json`
   (MCP: `compare_models`). It runs no model and spends nothing, but it saves a comparison record; say so.
6. **Verify a record.** `valcairn verify export.json --key <public key> --json` (MCP: `verify_record`). Offline.

## When to ask the user first

- Always before starting a run, and before a second attempt after a failure.
- Always when the plan shows a credit cost (`computeScope: public_pool`) or machines other than the user's own.
- Before linking a machine (`valcairn link`): it pairs this computer with their workspace.
- Never send a confirmation code the user did not approve, never invent one, and never reuse one for a changed request.

## Training file format

One JSON object per line, in one of three shapes:

```jsonl
{"messages": [{"role": "system", "content": "Be brief."}, {"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello."}]}
{"prompt": "What is 2+2?", "completion": "4"}
{"prompt": "Summarize this.", "chosen": "A good summary.", "rejected": "A worse one."}
```

A conversation must end with the assistant answer and have a non-empty user turn before it. In a preference row,
`chosen` and `rejected` must differ.

## Reading results

- **Check:** `ok` means no problems; `trainable` means training can start even though some lines would be skipped.
  `problems` lists `{ line, message }`.
- **Status:** `status` is `running`, `paused`, `succeeded`, `failed` or `stopped`. On `failed`, `failure` holds the
  recorded reason; report it as given, do not guess another.
- **Compare:** `wins` are cases the tuned model now passes, `losses` cases it no longer passes, `ties` the rest.
  `decision` is the workspace's acceptance rule (`pass`, `fail` or `insufficient_evidence`) and `reasons` say why.
  Report losses even when the decision passes.
- **Verify:** `ok: true` proves the evidence chain matches the approved content hash and that the key signed it. It
  does not prove which inputs a run really used or that the model is good. Without `--key`, it only shows the file is
  self-consistent.
- **Errors:** every error has an `error` sentence you can show the user as is. `429` means wait the `Retry-After`
  seconds. `404` on a workspace means the key belongs to another workspace.
