@tuned-tensor/cli 0.13.1-beta.6 → 0.13.1

package/docs/local-runtime/architecture.md

@@ -43,9 +43,9 @@ resource defaults, data contract, and real CUDA acceptance test.
 TT Local currently ships two such methods:
 
 - **Adapter** (`training/adapter`): certified Transformers checkpoints and
-  PEFT LoRA SFT. Driven by `tt run` and adapter pipelines.
+  PEFT LoRA SFT. Driven by `tt pipeline run`.
 - **Foundation** (`training/foundation`): a from-scratch BPE tokenizer and GPT
-  with no Transformers/PEFT. Driven only by `tt pipeline` from a foundation
+  with no Transformers/PEFT. Driven by `tt pipeline run` from a foundation
   `tunedtensor.json`. Pretrain, SFT, and RL require CUDA. Tokenizer training
   and the CPU unit tests do not. The current runtime is single-process and
   rejects `nproc_per_node` values above 1 and unsupported steps such as
@@ -68,6 +68,20 @@ held-out model capability.
 Do not mix those lockfiles. Each engine hashes its own `pyproject.toml` and
 `uv.lock` into a distinct cache environment.
 
+## Spec-driven instruction contract
+
+Adapter and foundation specs extend one engine-neutral behavior schema:
+`name`, `description`, `system_prompt`, `guidelines`, `constraints`, and
+`examples`. Node compiles the three instruction fields into one canonical
+system message. The adapter dataset compiler and every foundation stage use
+that same compiler, so tokenizer input, pretraining smoke data, chat SFT, RL,
+and evaluation all receive guidelines and constraints consistently.
+
+Engine-specific fields control execution only. Adapter specs add `base_model`,
+LoRA hyperparameters, and optional prebuilt datasets. Foundation specs add
+`engine: "foundation"` and the `foundation` training configuration. The
+behavioral instruction remains the shared source of truth.
+
 ## Python boundary
 
 Node owns input validation, state, process lifecycle, manifests, and reports.

package/docs/local-runtime/spark.md

@@ -108,7 +108,7 @@ tt doctor tunedtensor.json
 tt validate tunedtensor.json
 tt models prefetch tunedtensor.json
 tt models verify-base tunedtensor.json
-tt run tunedtensor.json
+tt pipeline run --spec tunedtensor.json --config local-runner.json
 ```
 
 `doctor` resolves the same bundled project and paths the run will use, imports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuned-tensor/cli",
-  "version": "0.13.1-beta.6",
+  "version": "0.13.1",
   "description": "Local TT agent and CUDA fine-tuning CLI for Tuned Tensor workflows",
   "repository": {
     "type": "git",

package/training/foundation/src/data.py

@@ -105,6 +105,13 @@ def iter_corpus_documents(path: str | Path, max_chars: int | None = None) -> Ite
                     yield text
 
 
+def instruction_corpus_documents(system_prompt: str, documents: Iterable[str]) -> Iterator[str]:
+    instruction = system_prompt.strip()
+    if instruction:
+        yield instruction
+    yield from documents
+
+
 def corpus_documents_hash(documents: Iterable[str]) -> tuple[str, int]:
     digest = hashlib.sha256()
     chars = 0
@@ -141,6 +148,52 @@ def encode_ids(tokenizer: Tokenizer, text: str) -> list[int]:
     return list(tokenizer.encode(text).ids)
 
 
+def encode_prompt_ids(
+    tokenizer: Tokenizer,
+    system_prompt: str,
+    user: str,
+    max_tokens: int,
+) -> list[int]:
+    """Keep the complete spec instruction and trim only user content."""
+    full_ids = encode_ids(tokenizer, format_prompt(system_prompt, user))
+    if len(full_ids) <= max_tokens:
+        return full_ids
+    system = system_prompt.strip() or "You are a helpful assistant."
+    prefix_ids = encode_ids(tokenizer, f"{SYSTEM}{system}{END}{USER}")
+    suffix_ids = encode_ids(tokenizer, f"{END}{ASSISTANT}")
+    if len(prefix_ids) + len(suffix_ids) > max_tokens:
+        raise ValueError(
+            "Compiled spec instruction exceeds the foundation model context; "
+            "increase foundation.sequence_length or shorten the spec instruction."
+        )
+    user_ids = encode_ids(tokenizer, user)
+    user_budget = max_tokens - len(prefix_ids) - len(suffix_ids)
+    retained_user_ids = user_ids[-user_budget:] if user_budget > 0 else []
+    return prefix_ids + retained_user_ids + suffix_ids
+
+
+def encode_generation_prompt(
+    tokenizer: Tokenizer,
+    system_prompt: str,
+    user: str,
+    context_length: int,
+    requested_completion_tokens: int,
+) -> tuple[list[int], int]:
+    """Reserve completion space without rejecting an instruction that can fit."""
+    completion_tokens = min(requested_completion_tokens, max(1, context_length // 2))
+    try:
+        prompt_ids = encode_prompt_ids(
+            tokenizer,
+            system_prompt,
+            user,
+            context_length - completion_tokens,
+        )
+    except ValueError:
+        prompt_ids = encode_prompt_ids(tokenizer, system_prompt, user, context_length - 1)
+        completion_tokens = context_length - len(prompt_ids)
+    return prompt_ids, completion_tokens
+
+
 def decode_ids(tokenizer: Tokenizer, ids: list[int]) -> str:
     return tokenizer.decode(ids, skip_special_tokens=False)
 
@@ -168,9 +221,18 @@ def encode_sft_example(
     full_ids = encode_ids(tokenizer, format_chat(system_prompt, user, assistant))
     model_tokens = sequence_length + 1
     if len(full_ids) > model_tokens:
-        overflow = len(full_ids) - model_tokens
-        prefix_ids = prefix_ids[overflow:] if overflow < len(prefix_ids) else []
-        full_ids = full_ids[-model_tokens:]
+        assistant_ids = encode_ids(tokenizer, f"{assistant}{END}")
+        reserved_assistant_tokens = min(2, len(assistant_ids))
+        prefix_ids = encode_prompt_ids(
+            tokenizer,
+            system_prompt,
+            user,
+            model_tokens - reserved_assistant_tokens,
+        )
+        assistant_budget = model_tokens - len(prefix_ids)
+        if len(assistant_ids) > assistant_budget:
+            assistant_ids = assistant_ids[:assistant_budget - 1] + assistant_ids[-1:]
+        full_ids = prefix_ids + assistant_ids
     input_ids = pad_or_trim(full_ids[:-1], sequence_length, pad_id)
     target_ids = full_ids[1:]
     first_assistant_target = max(0, min(len(prefix_ids) - 1, len(target_ids)))

package/training/foundation/src/evaluate.py

@@ -8,7 +8,7 @@ from tokenizers import Tokenizer
 from torch.nn import functional as F
 
 from common import load_config, write_json
-from data import END, decoded_byte_count, encode_ids, example_pairs, format_prompt, iter_corpus_documents, smoke_corpus, window_tokens
+from data import END, decoded_byte_count, encode_generation_prompt, example_pairs, iter_corpus_documents, smoke_corpus, window_tokens
 from model import bits_per_byte, generate, load_model
 
 
@@ -45,12 +45,19 @@ def evaluate_chat(
     correct = 0
     model.eval()
     for example in examples:
-        prompt_ids = encode_ids(tokenizer, format_prompt(system_prompt, example["input"])) or [0]
+        context_length = int(model.config["sequence_length"])
+        prompt_ids, completion_tokens = encode_generation_prompt(
+            tokenizer,
+            system_prompt,
+            example["input"],
+            context_length,
+            32,
+        )
         tokens = torch.tensor([prompt_ids], dtype=torch.long, device=device)
         generated = generate(
             model,
             tokens,
-            max_new_tokens=32,
+            max_new_tokens=completion_tokens,
             stop_token_id=tokenizer.token_to_id(END),
         )[0].tolist()[len(prompt_ids):]
         text = tokenizer.decode(generated).split(END)[0].strip()
@@ -65,14 +72,27 @@ def evaluate_chat(
     }
 
 
-def evaluate_inference(model, tokenizer: Tokenizer, prompt: str, device: torch.device) -> dict[str, float | int | str]:
-    prompt_ids = encode_ids(tokenizer, prompt) or [0]
-    tokens = torch.tensor([prompt_ids[: min(16, len(prompt_ids))]], dtype=torch.long, device=device)
+def evaluate_inference(
+    model,
+    tokenizer: Tokenizer,
+    system_prompt: str,
+    user_prompt: str,
+    device: torch.device,
+) -> dict[str, float | int | str]:
+    context_length = int(model.config["sequence_length"])
+    prompt_ids, completion_tokens = encode_generation_prompt(
+        tokenizer,
+        system_prompt,
+        user_prompt,
+        context_length,
+        32,
+    )
+    tokens = torch.tensor([prompt_ids], dtype=torch.long, device=device)
     if device.type == "cuda":
         torch.cuda.reset_peak_memory_stats(device)
         torch.cuda.synchronize()
     started = time.perf_counter()
-    generated = generate(model, tokens, max_new_tokens=32)
+    generated = generate(model, tokens, max_new_tokens=completion_tokens)
     if device.type == "cuda":
         torch.cuda.synchronize()
     elapsed = max(time.perf_counter() - started, 1e-6)
@@ -112,7 +132,13 @@ def main(argv: list[str] | None = None) -> None:
         metrics.update(evaluate_chat(model, tokenizer, str(config.get("system_prompt") or ""), examples, device))
     elif evaluator == "inference":
         prompt = examples[0]["input"] if examples else "hello"
-        metrics.update(evaluate_inference(model, tokenizer, prompt, device))
+        metrics.update(evaluate_inference(
+            model,
+            tokenizer,
+            str(config.get("system_prompt") or ""),
+            prompt,
+            device,
+        ))
     else:
         raise SystemExit(f"Unknown foundation evaluator: {evaluator}")
     write_json(output_dir / "metrics.json", metrics)

package/training/foundation/src/pretrain.py

@@ -16,7 +16,15 @@ from torch.nn import functional as F
 
 from checkpoint import CheckpointManager
 from common import append_jsonl, ensure_private_directory, load_config, make_private_file, require_cuda, write_json
-from data import END, corpus_hash, corpus_manifest, example_pairs, iter_corpus_documents, smoke_corpus
+from data import (
+    END,
+    corpus_hash,
+    corpus_manifest,
+    example_pairs,
+    instruction_corpus_documents,
+    iter_corpus_documents,
+    smoke_corpus,
+)
 from model import FoundationGPT, model_config_from_depth, param_count, save_model
 
 
@@ -37,10 +45,12 @@ def file_sha256(path: str | Path) -> str:
 def source_signature(config: dict[str, Any]) -> dict[str, Any]:
     corpus_path = config.get("corpus_path")
     if corpus_path:
+        instruction = str(config.get("system_prompt") or "").strip()
         return {
             "kind": "files",
             "manifest": corpus_manifest(corpus_path),
             "max_chars": int(config.get("max_chars") or 0),
+            "instruction_sha256": corpus_hash(instruction),
         }
     examples = example_pairs(config.get("examples") or [])
     corpus = smoke_corpus(
@@ -142,7 +152,10 @@ def prepare_token_cache(
             recorded_bytes = 0
     corpus_path = config.get("corpus_path")
     if corpus_path:
-        documents = iter_corpus_documents(corpus_path, int(config.get("max_chars") or 0))
+        documents = instruction_corpus_documents(
+            str(config.get("system_prompt") or ""),
+            iter_corpus_documents(corpus_path, int(config.get("max_chars") or 0)),
+        )
     else:
         examples = example_pairs(config.get("examples") or [])
         documents = iter([smoke_corpus(

package/training/foundation/src/rl.py

@@ -7,7 +7,7 @@ from tokenizers import Tokenizer
 from torch.nn import functional as F
 
 from common import load_config, require_cuda, write_json
-from data import END, encode_ids, example_pairs, format_prompt, numeric_reward
+from data import END, encode_generation_prompt, example_pairs, numeric_reward
 from model import FoundationGPT, load_model, param_count, save_model
 
 
@@ -73,10 +73,18 @@ def main(argv: list[str] | None = None) -> None:
     last_loss = 0.0
     for step in range(steps):
         example = examples[step % len(examples)]
-        prompt_ids = encode_ids(tokenizer, format_prompt(str(config.get("system_prompt") or ""), example["input"]))
+        context_length = int(model.config["sequence_length"])
+        prompt_ids, completion_tokens = encode_generation_prompt(
+            tokenizer,
+            str(config.get("system_prompt") or ""),
+            example["input"],
+            context_length,
+            24,
+        )
         prompt_ids, completion_tokens = bounded_rollout(
             prompt_ids,
-            int(model.config["sequence_length"]),
+            context_length,
+            completion_tokens,
         )
         prompt = torch.tensor([prompt_ids], dtype=torch.long, device=device)
         sampled = sample_rollout(

package/training/foundation/src/train_tokenizer.py

@@ -6,6 +6,7 @@ from data import (
     corpus_hash,
     corpus_manifest,
     example_pairs,
+    instruction_corpus_documents,
     iter_corpus_documents,
     smoke_corpus,
     train_tokenizer,
@@ -20,9 +21,17 @@ def main(argv: list[str] | None = None) -> None:
     corpus_path = config.get("corpus_path")
     if corpus_path:
         manifest_before = corpus_manifest(corpus_path)
-        corpus_sha256, corpus_chars = corpus_documents_hash(iter_corpus_documents(corpus_path, max_chars))
+        system_prompt = str(config.get("system_prompt") or "")
+
+        def documents():
+            return instruction_corpus_documents(
+                system_prompt,
+                iter_corpus_documents(corpus_path, max_chars),
+            )
+
+        corpus_sha256, corpus_chars = corpus_documents_hash(documents())
         tokenizer = train_tokenizer(
-            iter_corpus_documents(corpus_path, max_chars),
+            documents(),
             int(config.get("vocab_size") or 256),
         )
         if corpus_manifest(corpus_path) != manifest_before: