tunedtensor.json

Keep your behaviour spec in tunedtensor.json alongside the project code. It defines the model's instructions, base model, and training data.

What the spec describes

Write the model's role and instructions, the constraints it should follow, and examples of inputs and expected outputs. Local runs read the file directly from disk without a TT account. Commit it to version control so you can review changes alongside the code that uses the model.

Create your first spec

mkdir support-bot
cd support-bot
tt init --name "Customer Support Bot" --model Qwen/Qwen3.5-2B

Set system_prompt to your model's instructions and replace the generated examples with your own before running training. On DGX Spark, add --profile spark to create a local-runner.json configuration for that host.

Minimal spec

{
  "name": "Customer Support Bot",
  "description": "Answers billing, account, and troubleshooting questions.",
  "base_model": "Qwen/Qwen3.5-2B",
  "system_prompt": "You provide technical support for Acme SaaS.",
  "guidelines": [
    "Give the user a concrete next step.",
    "Use short bullets for answers with several steps.",
    "Ask for missing account details instead of guessing."
  ],
  "constraints": [
    "Do not promise refunds.",
    "Do not invent pricing, policy, or outage details."
  ],
  "examples": [
    {
      "input": "How do I cancel my subscription?",
      "output": "Go to Settings > Billing > Cancel Plan, then follow the confirmation steps."
    },
    {
      "input": "I was charged twice this month.",
      "output": "Contact billing@example.com with both invoice IDs so the billing team can investigate the duplicate charge."
    }
  ]
}

This file contains two examples to illustrate the format. Add more cases for training and evaluation before judging the model's performance.

Core fields

Field	Required	How to use it
`name`	Yes	A short name for the model's task.
`description`	No	A description of the use case, audience, or scope.
`base_model`	Yes for adapter runs	The model to fine-tune. `tt init` defaults to `Qwen/Qwen3.5-2B`.
`system_prompt`	No	The role and instructions used to build the system message for training and inference.
`guidelines`	No	Positive rules the model should follow. Keep each item specific and testable.
`constraints`	No	Restrictions, such as topics to refuse or facts the model must not invent.
`examples`	Yes when using inline examples	Input and output pairs. Local adapter runs need at least two distinct inputs and set aside some examples for evaluation. With a prebuilt dataset, training and evaluation use the supplied files.

Writing good examples

Each example should show a realistic input and the output you want the model to produce. Include the formats and cases your application handles.

Cover normal cases, edge cases, and refusal or escalation cases.
Write complete outputs that follow your instructions and constraints.
Use the same output format you want at inference time, including JSON if the task needs JSON.
Use distinct inputs and cover different cases.
Include examples that exercise each important guideline or constraint.

Structured JSON output

{
  "input": "Subject: Invoice overdue\nBody: Payment failed yesterday.",
  "output": "{\"category\":\"billing\",\"priority\":\"high\",\"action\":\"contact_billing\"}"
}

Validate and run

tt validate tunedtensor.json
tt models prefetch tunedtensor.json
tt pipeline run --spec tunedtensor.json

TT uses local-runner.json next to the spec when it exists. To use another configuration file, add --config <path>. The spec also accepts dataset_prebuilt and hyperparameters for local adapter runs.

Local extensions

SFT with a prebuilt dataset

If your data is already in chat JSONL, provide a training file and a separate validation or test file. TT evaluates the validation split when present, otherwise the test split. Inline spec examples are not used for evaluation in this mode.

{
  "name": "Email Triage",
  "base_model": "Qwen/Qwen3.5-2B",
  "system_prompt": "Return compact email triage JSON.",
  "examples": [
    { "input": "Subject: build failed", "output": "{\"team\":\"eng\",\"priority\":\"high\"}" }
  ],
  "dataset_prebuilt": {
    "training": "file:///data/email-train.chat.jsonl",
    "validation": "file:///data/email-validation.chat.jsonl",
    "format": "chat_jsonl"
  },
  "hyperparameters": {
    "n_epochs": 3,
    "lora_rank": 16
  }
}

Training and evaluation inputs must be distinct. Relative paths are resolved from the spec's directory. Keep any system messages in the JSONL consistent with the spec's prompt, guidelines, and constraints.

Supported base models

The local adapter runtime supports these checkpoints:

Qwen/Qwen3.5-2B
nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16
meta-models/Muse-Glimmer-30B

See Model recommendations.

Validate before you run

tt validate tunedtensor.json

Validation checks required fields, model support, examples, and dataset structure before you start training. It also checks for overlapping training and evaluation inputs.

Common mistakes

Leaving placeholder examples from tt init unchanged.
Putting policy only in examples when it should be a guideline or constraint.
Using broad examples that do not show the desired output format.
Using an adapter with a different base model from the one it was trained on.
Reusing training inputs in the validation or test data.

Next steps

Quickstart: create and run your first spec.
Local training: GPU setup, activation, and serving.
TT CLI: command reference.