nextron-cloud 0.1.0rc1__py3-none-any.whl

nextron_cloud/__init__.py

@@ -0,0 +1,10 @@
+"""Python client for the NexTron Cloud fine-tuning API."""
+from ._client import APIError, NexTron, NexTronError
+from ._version import __version__
+from .data import CheckResult, check_file, to_messages, write_jsonl
+from .types import (Account, Billing, Checkpoint, CheckpointFile, Dataset, Estimate, Event, Job, Layout, LogLine, MetricPoint,
+                    ModelInfo, ModelLayout, ModelMethod, Org, Progress, TrainingParams, Wandb)
+
+__all__ = ["NexTron", "NexTronError", "APIError", "Account", "Org", "Layout", "Dataset", "Job", "Estimate",
+           "MetricPoint", "LogLine", "Event", "Progress", "Billing", "ModelInfo", "ModelMethod", "ModelLayout", "Checkpoint", "CheckpointFile", "TrainingParams", "Wandb",
+           "CheckResult", "check_file", "to_messages", "write_jsonl", "__version__"]

nextron_cloud/_client.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import httpx
+
+from ._version import __version__
+from .types import Account, Layout, ModelInfo
+
+DEFAULT_BASE_URL = "https://nextron.physionlabs.ai"
+RETRY_STATUS = (429, 502, 503, 504)
+T = TypeVar("T")
+
+
+class NexTronError(Exception):
+    pass
+
+
+class APIError(NexTronError):
+    """A 4xx or 5xx answer. `code` is the server's short error name when it gives one."""
+
+    def __init__(self, status_code: int, message: str, code: str | None = None, body: Any = None):
+        super().__init__(f"{status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+        self.code = code
+        self.body = body
+
+
+def _api_error(r: httpx.Response) -> APIError:
+    try:
+        body = r.json()
+    except ValueError:
+        return APIError(r.status_code, r.text or r.reason_phrase)
+    if not isinstance(body, dict):
+        return APIError(r.status_code, str(body), body=body)
+    detail = body.get("detail")
+    code = body.get("error")
+    message = detail if isinstance(detail, str) else str(detail or code or r.reason_phrase)
+    return APIError(r.status_code, message, code, body)
+
+
+class NexTron:
+    """Client for the NexTron Cloud API. The key comes from `api_key` or NEXTRON_API_KEY."""
+
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None, org: str | None = None,
+                 timeout: float = 60.0, max_retries: int = 3):
+        api_key = api_key or os.environ.get("NEXTRON_API_KEY")
+        if not api_key:
+            raise NexTronError("no API key: pass api_key or set NEXTRON_API_KEY")
+        headers = {"Authorization": f"Bearer {api_key}", "User-Agent": f"nextron-cloud-python/{__version__}"}
+        if org:
+            headers["X-Nextron-Org"] = org
+        base_url = base_url or os.environ.get("NEXTRON_BASE_URL") or DEFAULT_BASE_URL
+        url = httpx.URL(base_url)
+        if url.scheme != "https" and url.host not in ("localhost", "127.0.0.1", "::1"):
+            raise NexTronError(f"refusing to send the API key over {url.scheme}://; use https")
+        self._http = httpx.Client(base_url=base_url, headers=headers, timeout=timeout)
+        self.max_retries = max_retries
+
+        from .datasets import Datasets
+        from .jobs import Jobs
+        self.datasets = Datasets(self)
+        self.jobs = Jobs(self)
+
+    def me(self) -> Account:
+        """The account the key belongs to, with its balance and the price list."""
+        return Account.model_validate(self._get("/v1/me"))
+
+    def models(self) -> list[ModelInfo]:
+        """Every model a job can train, live: methods, longest sample, price, GPU setups and whether one is free now."""
+        return [ModelInfo.model_validate(x) for x in self._get("/v1/models")]
+
+    def layouts(self) -> list[Layout]:
+        """The GPU setups, the models each trains, and whether one is free now."""
+        return [Layout.model_validate(x) for x in self._get("/v1/layouts")]
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> NexTron:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, *, retry: bool | None = None, **kwargs: Any) -> httpx.Response:
+        """Send one request. GETs, and POSTs the caller marks safe to repeat, are retried on a dropped connection or a
+        429/502/503/504."""
+        if retry is None:
+            retry = method == "GET"
+        attempts = self.max_retries + 1 if retry else 1
+        for attempt in range(attempts):
+            last = attempt == attempts - 1
+            try:
+                r = self._http.request(method, path, **kwargs)
+            except httpx.TransportError:
+                if last:
+                    raise
+                time.sleep(2**attempt)
+                continue
+            if r.status_code in RETRY_STATUS and not last:
+                time.sleep(float(r.headers.get("Retry-After", 2**attempt)))
+                continue
+            if r.is_error:
+                raise _api_error(r)
+            return r
+        raise AssertionError("unreachable")
+
+    def _get(self, path: str, **kwargs: Any) -> Any:
+        return self._request("GET", path, **kwargs).json()
+
+    def _post(self, path: str, body: Any = None, **kwargs: Any) -> Any:
+        return self._request("POST", path, json=body, **kwargs).json()
+
+
+def poll(get: Callable[[], T], done: Callable[[T], bool], timeout: float | None, interval: float) -> T:
+    """Call `get` every `interval` seconds until `done` holds; TimeoutError after `timeout` seconds."""
+    deadline = None if timeout is None else time.monotonic() + timeout
+    while True:
+        value = get()
+        if done(value):
+            return value
+        if deadline is not None and time.monotonic() + interval > deadline:
+            raise TimeoutError(f"still not done after {timeout} s")
+        time.sleep(interval)

nextron_cloud/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0rc1"

nextron_cloud/cli.py

@@ -0,0 +1,272 @@
+"""`nextron-cloud`: the SDK from a shell. Every command prints JSON."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from ._client import APIError, NexTron, NexTronError
+from . import experiments
+from .data import check_file, prepare_file
+from .types import TrainingParams, Wandb
+
+
+def _print(value: Any) -> None:
+    if isinstance(value, BaseModel):
+        value = value.model_dump(mode="json")
+    elif isinstance(value, list):
+        value = [v.model_dump(mode="json") if isinstance(v, BaseModel) else v for v in value]
+    print(json.dumps(value, indent=2, ensure_ascii=False))
+
+
+def _value(text: str) -> Any:
+    """A value that parses as JSON (numbers, true/false) is taken as that, else as text."""
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text
+
+
+def _params(pairs: list[str]) -> TrainingParams:
+    """`key=value` pairs."""
+    params: dict[str, Any] = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep:
+            raise SystemExit(f"--param takes key=value, got {pair!r}")
+        params[key] = _value(value)
+    return params  # type: ignore[return-value]
+
+
+def _draft(args: argparse.Namespace) -> dict[str, Any]:
+    return {"model": args.model, "dataset_id": args.dataset, "layout": args.layout, "params": _params(args.param)}
+
+
+def _grid(pairs: list[str]) -> dict[str, list[Any]]:
+    """`key=v1,v2,...` per axis, each value parsed like --param."""
+    axes = {}
+    for pair in pairs:
+        key, sep, values = pair.partition("=")
+        if not sep:
+            raise SystemExit(f"--grid takes key=v1,v2,..., got {pair!r}")
+        axes[key] = [_value(value) for value in values.split(",")]
+    return axes
+
+
+def _sweep(client: NexTron, args: argparse.Namespace) -> Any:
+    rows = experiments.sweep(client, name=args.name, model=args.model, dataset_id=args.dataset, axes=_grid(args.grid),
+                             params=_params(args.param), layout=args.layout, start=args.yes)
+    if args.yes:
+        return {"tag": experiments.sweep_tag(args.name), "jobs": rows}
+    unpriced = [row["name"] for row in rows if row["estimate"]["credits"] is None]
+    total = None if unpriced else sum(row["estimate"]["credits"] for row in rows)
+    _print({"jobs": rows, "total_credits": total, "unpriced": unpriced, "created": False,
+            "next": "show the total to the owner; rerun with --yes to start every job"})
+    sys.exit(3)
+
+
+def _report(client: NexTron, args: argparse.Namespace) -> Any:
+    if not args.tag and not args.job_id:
+        raise SystemExit("report needs --tag or job ids")
+    rows = experiments.report(client, tag=args.tag, job_ids=args.job_id)
+    if not args.table:
+        return rows
+    columns = ["id", "name", "state", "steps", "loss", "best_val_loss", "best_val_step", "tokens_trained", "charged_credits",
+               "training_minutes", "checkpoint_ready"]
+    print("\t".join(columns))
+    for row in rows:
+        print("\t".join("" if row[c] is None else str(row[c]) for c in columns))
+    return None
+
+
+def _create(client: NexTron, args: argparse.Namespace) -> Any:
+    draft = _draft(args)
+    if not args.yes:
+        estimate = client.jobs.estimate(**draft)
+        _print({"estimate": estimate.model_dump(mode="json"), "created": False,
+                "next": "show the cost to the owner; rerun with --yes to start the job"})
+        sys.exit(3)
+    wandb: Wandb | None = None
+    if args.wandb_project:
+        if not os.environ.get("WANDB_API_KEY"):
+            raise SystemExit("--wandb-project needs WANDB_API_KEY in the environment")
+        wandb = {"api_key": os.environ["WANDB_API_KEY"], "project": args.wandb_project}
+        if args.wandb_run_name:
+            wandb["run_name"] = args.wandb_run_name
+    return client.jobs.create(**draft, name=args.name, tags=args.tag or None, wandb=wandb, idempotency_key=args.idempotency_key)
+
+
+def _guide_dir() -> Path:
+    """The guide inside the installed package, or in the repository for a development install."""
+    packaged = Path(__file__).parent / "guide"
+    return packaged if packaged.exists() else Path(__file__).parents[2] / "skills" / "nextron-cloud"
+
+
+def _guide(args: argparse.Namespace) -> tuple[None, int]:
+    root = _guide_dir()
+    path = root / "SKILL.md" if not args.topic else root / "references" / f"{args.topic}.md"
+    if not path.exists():
+        topics = sorted(p.stem for p in (root / "references").glob("*.md"))
+        raise SystemExit(f"no guide topic {args.topic!r}; topics: {', '.join(topics)}")
+    print(path.read_text(encoding="utf-8"))
+    return None, 0
+
+
+def _events(client: NexTron, args: argparse.Namespace) -> None:
+    for event in client.jobs.events(args.job_id, after=args.after, follow=args.follow, until=args.until):
+        print(json.dumps(event.model_dump(mode="json"), ensure_ascii=False), flush=True)
+
+
+def _logs(client: NexTron, args: argparse.Namespace) -> None:
+    for line in client.jobs.logs(args.job_id, follow=args.follow):
+        print(line.line, flush=True)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="nextron-cloud", description="NexTron Cloud from the shell. Reads NEXTRON_API_KEY.")
+    groups = parser.add_subparsers(dest="group", required=True)
+
+    cmd = groups.add_parser("guide", help="how to run experiments: read this first (no key needed)")
+    cmd.add_argument("topic", nargs="?", help="data, training, monitoring, checkpoints or api")
+    cmd.set_defaults(run=None, local=_guide)
+    groups.add_parser("me", help="account, balance (US cents), price list").set_defaults(run=lambda c, a: c.me())
+    groups.add_parser("models", help="models a job can train, live").set_defaults(run=lambda c, a: c.models())
+    groups.add_parser("layouts", help="GPU setups").set_defaults(run=lambda c, a: c.layouts())
+
+    datasets = groups.add_parser("datasets", help="upload, import, check and list training data").add_subparsers(dest="cmd", required=True)
+    datasets.add_parser("list").set_defaults(run=lambda c, a: c.datasets.list())
+    cmd = datasets.add_parser("get")
+    cmd.add_argument("dataset_id")
+    cmd.set_defaults(run=lambda c, a: c.datasets.get(a.dataset_id))
+    cmd = datasets.add_parser("check", help="the server's format check, locally; no key needed")
+    cmd.add_argument("path")
+    cmd.set_defaults(run=None, local=lambda a: _checked(check_file(a.path)))
+    cmd = datasets.add_parser("prepare", help="convert a .jsonl/.json/.csv file to train.jsonl and val.jsonl; no key needed")
+    cmd.add_argument("path")
+    cmd.add_argument("--out-dir", default=".")
+    cmd.add_argument("--val-fraction", type=float, default=0.1)
+    cmd.add_argument("--seed", type=int, default=0)
+    cmd.add_argument("--prompt-column", action="append", help="the user message's column (with --response-column); "
+                     "repeat to join several, e.g. instruction and context")
+    cmd.add_argument("--response-column", help="the assistant message's column")
+    cmd.add_argument("--system", help="a system message for every sample")
+    cmd.set_defaults(run=None, local=lambda a: (prepare_file(
+        a.path, a.out_dir, val_fraction=a.val_fraction, seed=a.seed, prompt_column=a.prompt_column,
+        response_column=a.response_column, system=a.system), 0))
+    cmd = datasets.add_parser("upload", help="check, upload and wait for the server's check")
+    cmd.add_argument("path")
+    cmd.add_argument("--name")
+    cmd.set_defaults(run=lambda c, a: c.datasets.wait(c.datasets.upload(a.path, name=a.name).id))
+    cmd = datasets.add_parser("splits", help="a Hugging Face dataset's configs and splits")
+    cmd.add_argument("url")
+    cmd.set_defaults(run=lambda c, a: c.datasets.huggingface_splits(a.url))
+    cmd = datasets.add_parser("import", help="import a Hugging Face split and wait for its check")
+    cmd.add_argument("url")
+    cmd.add_argument("--config", default="default")
+    cmd.add_argument("--split", default="train")
+    cmd.add_argument("--name")
+    cmd.set_defaults(run=lambda c, a: c.datasets.wait(
+        c.datasets.import_huggingface(a.url, config=a.config, split=a.split, name=a.name).id))
+    cmd = datasets.add_parser("download-url")
+    cmd.add_argument("dataset_id")
+    cmd.set_defaults(run=lambda c, a: {"url": c.datasets.download_url(a.dataset_id)})
+    cmd = datasets.add_parser("delete")
+    cmd.add_argument("dataset_id")
+    cmd.set_defaults(run=lambda c, a: c.datasets.delete(a.dataset_id))
+
+    jobs = groups.add_parser("jobs", help="estimate, start and watch training jobs").add_subparsers(dest="cmd", required=True)
+    for name in ("estimate", "create"):
+        cmd = jobs.add_parser(name, help="cost of a job" if name == "estimate" else "estimate, then start with --yes")
+        cmd.add_argument("--model", required=True)
+        cmd.add_argument("--dataset", required=True, help="dataset id")
+        cmd.add_argument("--layout", default="auto")
+        cmd.add_argument("--param", action="append", default=[], metavar="KEY=VALUE", help="a training param; repeat")
+        if name == "estimate":
+            cmd.set_defaults(run=lambda c, a: c.jobs.estimate(**_draft(a)))
+            continue
+        cmd.add_argument("--yes", action="store_true", help="start the job; without it only the estimate is printed")
+        cmd.add_argument("--name", help="your label for the job")
+        cmd.add_argument("--tag", action="append", help="a tag to group jobs by; repeat")
+        cmd.add_argument("--idempotency-key", help="the same key never starts a second job")
+        cmd.add_argument("--wandb-project", help="log to this W&B project; the key comes from WANDB_API_KEY")
+        cmd.add_argument("--wandb-run-name")
+        cmd.set_defaults(run=_create)
+    cmd = jobs.add_parser("list")
+    cmd.add_argument("--tag")
+    cmd.set_defaults(run=lambda c, a: c.jobs.list(tag=a.tag))
+    for name, run in (("get", lambda c, a: c.jobs.get(a.job_id)), ("wait", lambda c, a: c.jobs.wait(a.job_id)),
+                      ("wait-checkpoint", lambda c, a: c.jobs.wait_checkpoint(a.job_id)),
+                      ("progress", lambda c, a: c.jobs.progress(a.job_id)), ("billing", lambda c, a: c.jobs.billing(a.job_id)),
+                      ("metrics", lambda c, a: c.jobs.metrics(a.job_id)), ("cancel", lambda c, a: c.jobs.cancel(a.job_id)),
+                      ("checkpoint", lambda c, a: c.jobs.checkpoint(a.job_id))):
+        cmd = jobs.add_parser(name)
+        cmd.add_argument("job_id")
+        cmd.set_defaults(run=run)
+    cmd = jobs.add_parser("events", help="the job's events as JSON lines")
+    cmd.add_argument("job_id")
+    cmd.add_argument("--after", type=int, default=0, help="the last seq already read")
+    cmd.add_argument("--follow", action="store_true", help="keep reading until training is over")
+    cmd.add_argument("--until", choices=["training", "checkpoint"], default="training")
+    cmd.set_defaults(run=_events)
+    cmd = jobs.add_parser("logs")
+    cmd.add_argument("job_id")
+    cmd.add_argument("--follow", action="store_true", help="keep reading until the job ends")
+    cmd.set_defaults(run=_logs)
+    cmd = jobs.add_parser("download", help="download the checkpoint and check every file's sha256")
+    cmd.add_argument("job_id")
+    cmd.add_argument("dest")
+    cmd.add_argument("--include", action="append", metavar="GLOB", help="only files matching this pattern; repeat")
+    cmd.set_defaults(run=lambda c, a: {"path": str(c.jobs.download_checkpoint(a.job_id, a.dest, include=a.include))})
+    cmd = jobs.add_parser("export", help="save the job record as a zip")
+    cmd.add_argument("job_id")
+    cmd.add_argument("dest")
+    cmd.set_defaults(run=lambda c, a: {"path": str(c.jobs.export(a.job_id, a.dest))})
+
+    cmd = groups.add_parser("sweep", help="one job per combination of --grid values; estimates, then starts with --yes")
+    cmd.add_argument("--name", required=True, help="the sweep's name; its jobs are tagged sweep:<name>")
+    cmd.add_argument("--model", required=True)
+    cmd.add_argument("--dataset", required=True, help="dataset id")
+    cmd.add_argument("--layout", default="auto")
+    cmd.add_argument("--param", action="append", default=[], metavar="KEY=VALUE", help="a param every job gets; repeat")
+    cmd.add_argument("--grid", action="append", required=True, metavar="KEY=V1,V2", help="values to sweep; repeat")
+    cmd.add_argument("--yes", action="store_true", help="start the jobs; without it only the estimates are printed")
+    cmd.set_defaults(run=_sweep)
+    cmd = groups.add_parser("report", help="compare jobs: settings, losses, tokens, time")
+    cmd.add_argument("job_id", nargs="*")
+    cmd.add_argument("--tag", help="every job with this tag, e.g. sweep:<name>")
+    cmd.add_argument("--table", action="store_true", help="tab-separated text instead of JSON")
+    cmd.set_defaults(run=_report)
+    return parser
+
+
+def _checked(result: Any) -> tuple[dict[str, Any], int]:
+    return {"ok": result.ok, "samples": result.samples, "chars": result.chars, "errors": result.errors}, 0 if result.ok else 1
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parser().parse_args(argv)
+    if args.run is None:
+        output, code = args.local(args)
+        if output is not None:
+            _print(output)
+        sys.exit(code)
+    try:
+        with NexTron() as client:
+            result = args.run(client, args)
+    except APIError as error:
+        _print({"error": error.code, "status": error.status_code, "message": error.message})
+        sys.exit(1)
+    except NexTronError as error:
+        _print({"error": str(error)})
+        sys.exit(1)
+    if result is not None:
+        _print(result)
+
+
+if __name__ == "__main__":
+    main()

nextron_cloud/data.py

@@ -0,0 +1,227 @@
+"""Training data: the sample format, conversion from common formats, and the server's format check run locally.
+
+A dataset is a JSONL file, one sample per line, text only:
+
+    {"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."},
+                  {"role": "assistant", "content": "..."}]}
+
+At least one assistant message is needed, and a system message may only come first. These formats are converted to it
+(here by `to_messages`, and by the server on upload):
+
+    {"conversations" | "conversation": [{"from"|"role": ..., "value"|"content": ...}]}   ShareGPT, LMSYS
+    {"instruction": ..., "input" | "context": ..., "output" | "response": ...}       Alpaca, Dolly
+    {"prompt": ..., "completion" | "response": ...}                                  prompt / completion
+    {"query" | "question": ..., "response" | "answer": ...}                          question / answer (OpenOrca)
+    {"problem": ..., "solution": ...}, {"input": ..., "output": ...}                 problem / solution
+    "content": [{"type": "text", "text": ...}, ...]                                   OpenAI content parts, text only
+
+An optional top-level "system" or "system_prompt" string becomes the system message.
+"""
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+Message = dict[str, str]
+
+ROLES = ("system", "user", "assistant")
+SHAREGPT_ROLES = {"human": "user", "user": "user", "gpt": "assistant", "assistant": "assistant", "model": "assistant",
+                  "system": "system"}
+PAIRS = (("prompt", "completion"), ("prompt", "response"), ("query", "response"), ("question", "answer"), ("question", "response"),
+         ("problem", "solution"), ("input", "output"))
+MEDIA_FIELDS = ("image", "images", "video", "videos", "audio", "audios")
+MEDIA_ERROR = "has an image, audio or video part; NexTron Cloud trains on text only for now"
+MAX_LINE_BYTES = 4 << 20
+MAX_FILE_BYTES = 5 * 1000**3
+MAX_ERRORS = 5  # the server also reports only the first five
+
+
+def _text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list) and all(isinstance(p, dict) for p in content):
+        if any(p.get("type") != "text" for p in content):
+            raise ValueError(MEDIA_ERROR)
+        return "".join(str(p.get("text", "")) for p in content)
+    raise ValueError('every message needs a text "content"')
+
+
+def to_messages(sample: Any) -> list[Message]:
+    """The sample as chat messages. ValueError says why it cannot be trained on."""
+    if isinstance(sample, list):
+        raise ValueError("is a JSON array; upload JSONL: one JSON object per line")
+    if not isinstance(sample, dict):
+        raise ValueError("is not a JSON object")
+    if any(sample.get(f) for f in MEDIA_FIELDS):
+        raise ValueError(MEDIA_ERROR)
+    given = next((sample[k] for k in ("system", "system_prompt") if isinstance(sample.get(k), str) and sample[k]), None)
+    system = [{"role": "system", "content": given}] if given else []
+    if "messages" in sample:
+        source = sample["messages"]
+        if not isinstance(source, list) or not source:
+            raise ValueError('needs a non-empty "messages" list')
+        messages = []
+        for m in source:
+            if not isinstance(m, dict) or m.get("role") not in ROLES:
+                raise ValueError('every message needs a "role" (system, user or assistant)')
+            messages.append({"role": m["role"], "content": _text(m.get("content"))})
+    elif "conversations" in sample or "conversation" in sample:
+        turns = sample.get("conversations", sample.get("conversation"))
+        if not isinstance(turns, list) or not turns:
+            raise ValueError('needs a non-empty "conversations" list')
+        messages = []
+        for t in turns:
+            role = SHAREGPT_ROLES.get(str(t.get("from", t.get("role", ""))).lower()) if isinstance(t, dict) else None
+            if role is None:
+                raise ValueError('every turn needs "from" (human, gpt or system) and "value"')
+            messages.append({"role": role, "content": _text(t.get("value", t.get("content")))})
+    elif "instruction" in sample and ("output" in sample or "response" in sample):
+        answer = "output" if "output" in sample else "response"
+        prompt = "\n\n".join(str(sample[k]) for k in ("instruction", "input", "context") if sample.get(k))
+        messages = [{"role": "user", "content": prompt}, {"role": "assistant", "content": _text(sample[answer])}]
+    else:
+        pair = next((p for p in PAIRS if p[0] in sample and p[1] in sample), None)
+        if pair is None:
+            raise ValueError('is not a format we know: use "messages", or one of conversations, instruction/output, '
+                             "instruction/response, prompt/completion, query/response, question/answer, problem/solution, input/output")
+        messages = [{"role": "user", "content": _text(sample[pair[0]])}, {"role": "assistant", "content": _text(sample[pair[1]])}]
+    if not any(m["role"] == "assistant" and m["content"] for m in messages):
+        raise ValueError("needs at least one non-empty assistant message to learn from")
+    messages = system + messages
+    if any(m["role"] == "system" for m in messages[1:]):
+        raise ValueError("has a system message that is not the first message; a sample can have one, first")
+    return messages
+
+
+def write_jsonl(samples: Iterable[Any], path: str | os.PathLike[str]) -> int:
+    """Write samples in any format above as a "messages" JSONL file; returns how many. Raises on the first bad one."""
+    count = 0
+    with Path(path).open("w", encoding="utf-8") as out:
+        for number, sample in enumerate(samples, 1):
+            try:
+                messages = to_messages(sample)
+            except ValueError as error:
+                raise ValueError(f"sample {number}: {error}") from None
+            out.write(json.dumps({"messages": messages}, ensure_ascii=False) + "\n")
+            count += 1
+    return count
+
+
+@dataclass
+class CheckResult:
+    samples: int = 0
+    chars: int = 0  # message text; a token is roughly 3-4 characters of English
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def check_file(path: str | os.PathLike[str]) -> CheckResult:
+    """Run the server's format check on a local JSONL file. Token counts per model come from the server after upload."""
+    path = Path(path)
+    result = CheckResult()
+    if path.stat().st_size > MAX_FILE_BYTES:
+        result.errors.append(f"the file is over {MAX_FILE_BYTES // 1000**3} GB")
+        return result
+    with path.open("rb") as f:
+        for number, raw in enumerate(f, 1):
+            if len(raw) > MAX_LINE_BYTES:
+                _note(result, f"line {number}: longer than {MAX_LINE_BYTES >> 20} MB")
+                continue
+            if number == 1:
+                raw = raw.removeprefix(b"\xef\xbb\xbf")
+            try:
+                line = raw.decode("utf-8").strip()
+            except UnicodeDecodeError:
+                _note(result, f"line {number}: not UTF-8 text; save the file as UTF-8")
+                continue
+            if not line:
+                continue
+            try:
+                messages = to_messages(json.loads(line))
+            except json.JSONDecodeError as error:
+                _note(result, f"line {number}: not valid JSON ({error.msg})")
+                continue
+            except ValueError as error:
+                _note(result, f"line {number}: {error}")
+                continue
+            result.samples += 1
+            result.chars += sum(len(m["content"]) for m in messages)
+    if not result.errors and not result.samples:
+        result.errors.append("the file has no samples")
+    return result
+
+
+def _note(result: CheckResult, error: str) -> None:
+    if len(result.errors) < MAX_ERRORS:
+        result.errors.append(error)
+
+
+VAL_MAX_SAMPLES = 5000  # the most a validation set may have
+
+
+def read_rows(path: str | os.PathLike[str]) -> list[Any]:
+    """Rows of a .jsonl, .json (a list) or .csv file, as parsed values (CSV rows as dicts of strings)."""
+    path = Path(path)
+    if path.suffix == ".csv":
+        import csv
+        with path.open(newline="", encoding="utf-8-sig") as f:
+            return list(csv.DictReader(f))
+    if path.suffix == ".json":
+        rows = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(rows, list):
+            raise ValueError(f"{path.name} is not a JSON list of samples")
+        return rows
+    with path.open(encoding="utf-8-sig") as f:
+        return [json.loads(line) for line in f if line.strip()]
+
+
+def prepare_file(path: str | os.PathLike[str], out_dir: str | os.PathLike[str] = ".", *, val_fraction: float = 0.1,
+                 seed: int = 0, prompt_column: str | list[str] | None = None, response_column: str | None = None,
+                 system: str | None = None) -> dict[str, Any]:
+    """Convert a file to train.jsonl and val.jsonl in `out_dir`: rows in any accepted format, or user and assistant
+    columns (`prompt_column`, several joined by a blank line when non-empty; `response_column`), e.g. of a CSV. Rows that cannot be trained on are left out
+    and counted. Shuffled with `seed`; the validation set is `val_fraction` of the rows, at most 5,000."""
+    import random
+
+    if not 0 <= val_fraction < 1:
+        raise ValueError("val_fraction must be at least 0 and below 1")
+    rows = read_rows(path)
+    prompt_columns = [prompt_column] if isinstance(prompt_column, str) else prompt_column or []
+    if prompt_columns and response_column and rows:
+        missing = [c for c in (*prompt_columns, response_column) if c not in rows[0]]
+        if missing:
+            raise ValueError(f"{Path(path).name} has no column {', '.join(missing)}; it has {', '.join(rows[0])}")
+    samples: list[dict[str, Any]] = []
+    errors: list[str] = []
+    skipped = 0
+    for number, row in enumerate(rows, 1):
+        if prompt_columns and response_column:
+            prompt = "\n\n".join(str(row[c]) for c in prompt_columns if row[c])
+            row = {"prompt": prompt, "completion": row[response_column]}
+        if system:
+            row = dict(row, system=system)
+        try:
+            samples.append({"messages": to_messages(row)})
+        except ValueError as error:
+            skipped += 1
+            if len(errors) < MAX_ERRORS:
+                errors.append(f"row {number}: {error}")
+    random.Random(seed).shuffle(samples)
+    n_val = min(round(len(samples) * val_fraction), VAL_MAX_SAMPLES) if val_fraction else 0
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    report: dict[str, Any] = {"skipped": skipped, "errors": errors}
+    for name, part in (("train", samples[n_val:]), ("val", samples[:n_val])):
+        target = out / f"{name}.jsonl"
+        target.unlink(missing_ok=True)  # never leave an earlier run's file behind to be uploaded by mistake
+        if part:
+            write_jsonl(part, target)
+            report[name] = {"path": str(target), "samples": len(part)}
+    return report