Tuned Tensor

tunedtensor.json

tunedtensor.json is the source-controlled behaviour spec. It describes what the model should do, which base model to start from, and the examples that teach and evaluate the behaviour.

Mental model

Treat the spec file as the product brief for your fine-tuned model. A good spec answers four questions:

  • What role should the model play?
  • What rules should it follow every time?
  • What should it avoid?
  • What are concrete examples of good inputs and ideal outputs?

Local runs read the file directly from disk. Keeping it in version control makes behaviour changes reviewable and repeatable.

Create your first spec

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

A minimal useful spec

{
  "name": "Customer Support Bot",
  "description": "Answers billing, account, and troubleshooting questions.",
  "base_model": "Qwen/Qwen3.5-2B",
  "system_prompt": "You are a calm, concise support agent for Acme SaaS.",
  "guidelines": [
    "Acknowledge the user concern before giving instructions.",
    "Use short bullets for multi-step answers.",
    "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": "I can help with that. Go to Settings > Billing > Cancel Plan, then follow the confirmation steps."
    },
    {
      "input": "I was charged twice this month.",
      "output": "I am sorry about the duplicate charge. Please contact billing@acme.com with the invoice IDs so the billing team can investigate."
    }
  ]
}

Core fields

FieldRequiredHow to use it
nameYesA short human name for the behaviour you are training.
descriptionNoA plain-English note about the use case, audience, or scope.
base_modelRecommendedThe open-weight model to fine-tune. Default for tt init is Qwen/Qwen3.5-2B.
system_promptNoThe role, tone, and persistent instruction used as the system message during training and local serving.
guidelinesNoPositive rules the model should follow. Keep each item specific and testable.
constraintsNoNegative rules or boundaries, such as topics to refuse or facts not to invent.
examplesYes for inline-example runsInput/output pairs. These become training rows and evaluation prompts unless you provide a prebuilt dataset.

Writing good examples

Examples are the most important part of the file. Each example should show a realistic user input and the exact kind of output you want.

  • Cover normal cases, edge cases, and refusal or escalation cases.
  • Make outputs complete enough to teach style, format, and boundaries.
  • Use the same output format you want at inference time, including JSON if the task needs JSON.
  • Avoid near-duplicates. Diversity usually helps more than repeating the same pattern.
  • 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 --config local-runner.json
tt models prefetch tunedtensor.json --config local-runner.json
tt run tunedtensor.json --config local-runner.json

The local workflow also understands dataset_prebuilt and hyperparameters.

Local extensions

SFT with a prebuilt dataset

If your training set is already in chat JSONL, keep representative evaluation examples in the spec and point local training at the dataset:

{
  "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
  }
}

Supported base models

Local training currently certifies:

  • 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 --config local-runner.json

Validation catches missing required fields, unsupported models, empty examples, and dataset shape mismatches before a run spends GPU time.

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.
  • Changing base_model between continued fine-tuning runs.
  • Using a prebuilt dataset without held-out validation or test rows.

Next steps