Tuned Tensor

tunedtensor.json

tunedtensor.json is the source-controlled behavior spec file used by both cloud runs with tt and local runs with tt-local. It describes what the model should do, which base model to start from, and the examples that teach and evaluate the behavior.

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?

Cloud runs snapshot the spec when you push and start a run. Local runs read the same file directly from disk. Keeping it in version control makes behavior changes reviewable and repeatable.

Create Your First Spec

Start in a project folder. The CLI scaffolds a starter file named tunedtensor.json:

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

For local-only workflows, use the same shape with tt-local:

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

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 behavior you are training.
descriptionNoA plain-English note about the use case, audience, or scope.
base_modelRecommendedThe open-weight model to fine-tune. If omitted in cloud API creation, the default 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 locally.

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

Document or Image Inputs

Local multimodal workflows can attach image assets to examples. Use a supported image-text base model such as Qwen/Qwen3-VL-2B-Instruct.

{
  "input": "Extract invoice number, vendor, and total as JSON.",
  "input_assets": [
    { "type": "image", "path": "./examples/invoice-page-1.png" }
  ],
  "output": "{\"invoice_number\":\"INV-1007\",\"vendor\":\"Acme Supplies\",\"total\":\"$421.50\"}",
  "modality": "document_ocr"
}

Cloud and Local Use

The core fields above are shared. A single file can drive both cloud and local workflows:

# Cloud workflow
tt eval
tt push
tt runs start <spec-id>

# Local workflow
tt-local validate tunedtensor.json --config local-runner.json
tt-local models prefetch tunedtensor.json --config local-runner.json
tt-local run tunedtensor.json --config local-runner.json

Cloud API spec creation accepts the core behavior fields. tt-local also understands local-run fields such as training_method, dataset_prebuilt, hyperparameters, user_id, run_number, and artifacts.

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,
    "save_adapter_only": true
  }
}

DPO Preference Training

For local DPO, set training_method to dpo and provide preference JSONL rows with prompt, chosen, and rejected fields.

{
  "name": "Preference Trainer",
  "training_method": "dpo",
  "base_model": "Qwen/Qwen3.5-2B",
  "dataset_prebuilt": {
    "training": "file:///data/preferences.jsonl",
    "test": "file:///data/dpo-eval.chat.jsonl",
    "format": "preference_jsonl"
  },
  "hyperparameters": {
    "n_epochs": 1,
    "dpo_beta": 0.1
  }
}

Supported Base Models

Use one of the supported base models unless you are running a custom local command backend:

  • google/gemma-4-E2B-it
  • google/gemma-4-E4B-it
  • Qwen/Qwen3.5-2B
  • Qwen/Qwen3-VL-2B-Instruct
  • Qwen/Qwen3.5-4B
  • meta-llama/Llama-3.2-3B-Instruct
  • microsoft/Phi-4-mini-instruct
  • ibm-granite/granite-3.3-2b-instruct
  • bigcode/starcoder2-3b

Validate Before You Run

tt eval
tt-local validate tunedtensor.json --config local-runner.json

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

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.
  • Expecting cloud API spec creation to accept every local-only key.

Next Steps