@tuned-tensor/cli 0.15.1 → 0.17.0

package/docs/spec-workflow.md

@@ -0,0 +1,110 @@
+# Work from the behavior spec
+
+Explore the [interactive architecture diagram](spec-architecture.html) for source
+excerpts, code structure and command examples. Open the HTML file in a browser.
+
+`tunedtensor.json` is the local recipe for the model's behavior, examples and
+training settings. Ask the agent to improve that recipe, review the proposed
+diff, approve the edit, then preview or execute a pipeline against the saved spec.
+The agent reads the actual file before proposing changes; it does not use the
+conversation transcript as a replacement for the current spec.
+
+## Review without a model call
+
+Inside the TT shell, in your project directory:
+
+```text
+/spec
+/spec validate
+/spec diff
+/spec history
+```
+
+`/spec` shows the complete current file, validation results and SHA-256.
+`/spec diff` shows pending spec edits in the current conversation; otherwise it
+shows the latest approved edit, or external changes since that revision.
+`/spec history` lists up to 50 recent revision records. These commands require
+no credentials and work before the agent is configured.
+
+Outside the shell, use `tt spec show`, `tt spec validate`, `tt spec diff`, and
+`tt spec history`. Add a workspace-relative path, for example
+`tt spec show feedback/tunedtensor.json`. For continued work on a nested
+project, `/cd feedback` makes its `tunedtensor.json` the current recipe.
+`--json` returns structured review results. `tt spec validate` exits nonzero
+for an invalid spec.
+
+## Edit, review, approve
+
+```text
+› Keep my training settings, but require a single lowercase sentiment label.
+  [agent reads the spec and proposes a diff]
+› /spec diff
+› /approve
+› /spec
+› /spec history
+```
+
+`get_local_spec` returns the document, validation diagnostics and content hash.
+`prepare_update_local_spec` requires that hash and a patch of supported fields.
+Arrays replace their whole field; `hyperparameters` and `foundation` merge by
+key. Unmentioned fields remain unchanged. Identity and engine cannot change
+through this edit tool. The full resulting document must pass the runtime's
+strict schema, readiness checks, nonblank content checks and distinct-example
+checks. Small example sets produce a warning; validation is not a claim of model
+quality or GPU readiness.
+
+Proposing an edit does not write anything. `/approve` revalidates the workspace,
+parent directory, current file bytes and proposed result, acquires the spec's
+writer lock and atomically replaces the file. `/reject` leaves it unchanged.
+If the file changes after review, prepare a fresh edit. A saved edit invalidates
+any previously prepared pipeline preview for the old spec.
+
+Secure agent edits currently require Linux filesystem handles. Reads work on
+other supported CLI platforms; edit the JSON with your editor there. Spec reads
+and edits are bounded to 200 KB. Large model-facing proposals may hit the
+agent's existing smaller review budget; split the request or use your editor.
+
+Revision records live beside the spec under `.tuned-tensor/spec-history/` and
+contain before/after snapshots and hashes. They can contain your training
+examples. They use private permissions. History records changes made through
+this edit workflow; it is not a file watcher or a complete history of external
+editor changes. A `prepared` record without an `applied` record is an incomplete
+journal entry: inspect the current file and its hash before attempting another
+edit. A crashed writer can leave `.tunedtensor-spec.lock`; after confirming no
+TT writer is still running, remove that lock manually. The lock coordinates TT
+writers; avoid concurrent external editor saves during approval.
+
+## Execute the saved recipe
+
+```bash
+tt spec validate
+tt pipeline run --spec tunedtensor.json --dry-run
+tt pipeline run --spec tunedtensor.json
+```
+
+The default pipeline derives from the current spec. An adjacent
+`tunedtensor.pipeline.json` is no longer loaded implicitly. To select an advanced
+recipe explicitly, pass `--file`; a missing explicit recipe or `--spec` file fails. Foundation
+training parameters in an explicit recipe must agree with the spec, including
+in previews and the runtime's own execution guard. Change the spec and regenerate
+the recipe when they disagree. Explicit recipes may still select supported
+stages; `--only` and `--skip` remain available.
+
+CLI planning, validation, execution and agent pipeline proposals share
+`pipelineForRunInput` in `src/pipeline.ts`. It uses the same
+`validateBehaviorSpec` rules as spec review and editing, defined beside the
+runtime parser in `src/local-runtime/local-project.ts`. The edit module only
+owns workspace access, patches and revision history.
+
+The command reads one spec snapshot for planning, hardware warnings and execution. Plan/dry-run
+JSON and final result JSON identify its path and SHA-256. The spec's compiled
+instructions and examples feed training and task evaluation; the independently
+configured general-regression suite keeps its own prompt. Provider choice and
+GPU placement remain separate runtime choices in agent configuration and
+`local-runner.json`. Evaluation policy (inference/scoring settings and the
+general-regression suite) also remains in the runner config. Moving that policy
+into the spec would be a separate schema change.
+
+Agent `/approve` for a pipeline still runs a preview only. Real training uses
+the direct command above. The spec is the behavior recipe; approval of a spec
+edit is not approval to launch training.

package/examples/local-runtime/aws-runner.json

@@ -0,0 +1,13 @@
+{
+  "artifactRoot": ".tuned-tensor/artifacts",
+  "storeRoot": ".tuned-tensor/store",
+  "gpu": {
+    "provider": "aws",
+    "profile": "research",
+    "region": "eu-west-1",
+    "instanceId": "i-0123456789abcdef0",
+    "user": "ubuntu",
+    "identityFile": "~/.ssh/research-gpu.pem",
+    "maxSeconds": 86400
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuned-tensor/cli",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Local TT agent and CUDA fine-tuning CLI for Tuned Tensor workflows",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
     "test:workflows": "vitest run src/__tests__/workflows",
     "eval:agent": "tsx scripts/eval-agent.ts",
     "test:local-runtime": "node --import tsx --test \"test/local-runtime/**/*.test.ts\"",
-    "test:python": "python3 -m unittest discover -s training/adapter/tests -p 'test_*.py' && uv run --frozen --project training/foundation python -m unittest discover -s training/foundation/tests -p 'test_*.py'",
+    "test:python": "python3 -m unittest discover -s training/adapter/tests -p 'test_*.py' && uv run --frozen --project training/foundation --group test python -m unittest discover -s training/foundation/tests -p 'test_*.py'",
     "test:watch": "vitest",
     "check": "npm run typecheck && npm test && npm run build"
   },
@@ -34,6 +34,8 @@
     "training/foundation/uv.lock",
     "training/foundation/src/*.py",
     "docs/local-runtime",
+    "docs/spec-workflow.md",
+    "docs/spec-architecture.html",
     "examples/local-runtime/*.json",
     "examples/local-runtime/*.jsonl"
   ],
@@ -53,9 +55,9 @@
     "@earendil-works/pi-agent-core": "0.84.1",
     "@earendil-works/pi-coding-agent": "0.84.1",
     "@tuned-tensor/pipeline-contract": "1.1.0",
-    "chalk": "^5.6.2",
+    "chalk": "^6.0.0",
     "cli-table3": "^0.6.5",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "open": "^10.1.0",
     "ora": "^9.3.0",
     "typebox": "1.3.7",

package/training/adapter/src/foundation_export.py

@@ -0,0 +1,81 @@
+"""Export TT FoundationGPT weights to vLLM's existing GPT-2 implementation."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+CHAT_TEMPLATE = """{%- if not messages or messages[0]['role'] != 'system' -%}
+{{- '<|system|>You are a helpful assistant.<|end|>' -}}
+{%- endif -%}
+{%- for message in messages -%}
+{%- set content = message['content'] -%}
+{%- if message['role'] == 'system' -%}
+{%- set content = (content | trim) or 'You are a helpful assistant.' -%}
+{%- endif -%}
+{%- if message['role'] not in ['system', 'user', 'assistant'] -%}
+{{- raise_exception('Foundation chat supports system, user and assistant messages only.') -}}
+{%- endif -%}
+{{- '<|' + message['role'] + '|>' + content + '<|end|>' -}}
+{%- endfor -%}
+{%- if add_generation_prompt -%}{{- '<|assistant|>' -}}{%- endif -%}"""
+
+
+def export_foundation(checkpoint: str, tokenizer_path: str, destination: Path) -> str:
+    import torch
+    from safetensors.torch import load_file, save_file
+    from tokenizers import Tokenizer
+    from transformers import GPT2Config, PreTrainedTokenizerFast
+
+    source = Path(checkpoint)
+    config = json.loads((source / 'config.json').read_text())
+    for key in ('depth', 'width', 'heads', 'vocab_size', 'sequence_length'):
+        if type(config.get(key)) is not int or config[key] <= 0:
+            raise ValueError(f'Invalid foundation config: {key}')
+    if config['width'] % config['heads']:
+        raise ValueError('Foundation width must be divisible by heads.')
+    raw_tokenizer = Tokenizer.from_file(tokenizer_path)
+    special_tokens = ['<unk>', '<pad>', '<|system|>', '<|user|>', '<|assistant|>', '<|end|>']
+    if any(raw_tokenizer.token_to_id(token) is None for token in special_tokens):
+        raise ValueError('Foundation tokenizer is missing required special tokens.')
+    tokenizer = PreTrainedTokenizerFast(tokenizer_object=raw_tokenizer,
+        unk_token='<unk>', pad_token='<pad>', eos_token='<|end|>',
+        additional_special_tokens=['<|system|>', '<|user|>', '<|assistant|>'],
+        model_max_length=config['sequence_length'], chat_template=CHAT_TEMPLATE)
+    if len(tokenizer) != config['vocab_size']:
+        raise ValueError('Foundation tokenizer vocabulary does not match the checkpoint.')
+    destination.mkdir(parents=True, exist_ok=True)
+    tokenizer.save_pretrained(destination)
+    GPT2Config(n_layer=config['depth'], n_embd=config['width'], n_head=config['heads'],
+        n_positions=config['sequence_length'], vocab_size=config['vocab_size'],
+        activation_function='gelu', layer_norm_epsilon=1e-5,
+        resid_pdrop=0.0, embd_pdrop=0.0, attn_pdrop=0.0,
+        bos_token_id=None, eos_token_id=tokenizer.eos_token_id,
+        pad_token_id=tokenizer.pad_token_id, architectures=['GPT2LMHeadModel'],
+        tie_word_embeddings=True).save_pretrained(destination)
+    weights = load_file(str(source / 'model.safetensors'))
+    exported = {}
+    def move(old, new, transpose=False):
+        tensor = weights.pop(old)
+        exported[new] = tensor.t().contiguous() if transpose else tensor
+    move('tok_emb.weight', 'transformer.wte.weight')
+    move('pos_emb.weight', 'transformer.wpe.weight')
+    head = weights.pop('lm_head.weight')
+    if not torch.equal(head, exported['transformer.wte.weight']):
+        raise ValueError('Foundation checkpoint must have tied embedding weights.')
+    for suffix in ('weight', 'bias'):
+        move('ln_f.' + suffix, 'transformer.ln_f.' + suffix)
+    for i in range(config['depth']):
+        old, new = f'blocks.{i}.', f'transformer.h.{i}.'
+        for src, dst in [('ln1', 'ln_1'), ('ln2', 'ln_2'),
+                         ('mlp.0', 'mlp.c_fc'), ('mlp.2', 'mlp.c_proj')]:
+            for suffix in ('weight', 'bias'):
+                move(old + src + '.' + suffix, new + dst + '.' + suffix,
+                     transpose=src.startswith('mlp') and suffix == 'weight')
+        for src, dst in [('attn.qkv', 'attn.c_attn'), ('attn.proj', 'attn.c_proj')]:
+            move(old + src + '.weight', new + dst + '.weight', transpose=True)
+            weight = exported[new + dst + '.weight']
+            exported[new + dst + '.bias'] = torch.zeros(weight.shape[1], dtype=weight.dtype)
+    if weights:
+        raise ValueError(f'Unexpected foundation weights: {sorted(weights)}')
+    save_file(exported, str(destination / 'model.safetensors'), metadata={'format': 'pt'})
+    return str(destination)

package/training/adapter/src/serve.py

@@ -64,9 +64,10 @@ def build_vllm_args(model_source: str, adapter_path: str | None, temp_dir: Path)
         "Qwen/Qwen3.5-2B": "qwen3_xml",
         "nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16": "qwen3_coder",
         "meta-models/Muse-Glimmer-30B": "muse_glimmer",
-    }[base]
-    args += ["--enable-auto-tool-choice", "--tool-call-parser", parser]
-    if base != "meta-models/Muse-Glimmer-30B":
+    }.get(base)
+    if parser:
+        args += ["--enable-auto-tool-choice", "--tool-call-parser", parser]
+    if parser and base != "meta-models/Muse-Glimmer-30B":
         args += ["--default-chat-template-kwargs", '{"enable_thinking":false}']
     if adapter_path:
         config = json.loads((Path(adapter_path) / "adapter_config.json").read_text())
@@ -124,11 +125,17 @@ def run_server() -> None:
     family = socket.AF_INET6 if ":" in host else socket.AF_INET
     with socket.socket(family, socket.SOCK_STREAM) as probe:
         probe.bind((host, port))
-    model_source = prepare_model_source()
     if os.environ.get("TT_API_KEY"):
         os.environ["VLLM_API_KEY"] = os.environ["TT_API_KEY"]
     with TemporaryDirectory(prefix="tt-serve-") as temp:
-        adapter = resolve_adapter_path(os.environ.get("TT_MODEL_ARTIFACT"), Path(temp))
+        if os.environ.get("TT_FOUNDATION_CHECKPOINT"):
+            from foundation_export import export_foundation
+            model_source = export_foundation(os.environ["TT_FOUNDATION_CHECKPOINT"],
+                os.environ["TT_FOUNDATION_TOKENIZER"], Path(temp) / "foundation")
+            adapter = None
+        else:
+            model_source = prepare_model_source()
+            adapter = resolve_adapter_path(os.environ.get("TT_MODEL_ARTIFACT"), Path(temp))
         args = build_vllm_args(model_source, adapter, Path(temp))
         from vllm.entrypoints.cli.main import main
         previous = sys.argv

package/training/adapter/src/train.py

@@ -282,6 +282,10 @@ def run_training(rows: list[dict[str, Any]], model_source: str) -> tuple[dict[st
         )
         result = trainer.train()
 
+    # Saved adapters must remain loadable after a local or remote staging directory is removed.
+    for adapter_config in model.peft_config.values():
+        adapter_config.base_model_name_or_path = str(hp("base_model", CERTIFIED_BASE_MODEL))
+        adapter_config.revision = hp("base_model_revision")
     model.save_pretrained(MODEL_DIR)
     tokenizer.save_pretrained(MODEL_DIR)
     return result.metrics, dtype

package/training/foundation/pyproject.toml

@@ -10,6 +10,10 @@ dependencies = [
   "torch>=2.11.0",
 ]
 
+[dependency-groups]
+# Match the pinned serving runtime for CPU export parity tests.
+test = ["transformers==5.16.1"]
+
 [tool.uv.sources]
 torch = [
   { index = "pytorch-cu130", marker = "sys_platform == 'linux'" },

package/training/foundation/src/model.py

@@ -132,6 +132,8 @@ def generate(
 def save_model(model: FoundationGPT, directory: str | Path) -> None:
     destination = ensure_private_directory(directory)
     tensors = {key: value.detach().cpu().contiguous() for key, value in model.state_dict().items()}
+    # CPU tensors can still alias the tied embedding after .cpu().
+    tensors["lm_head.weight"] = tensors["lm_head.weight"].clone()
     model_path = destination / "model.safetensors"
     save_file(tensors, str(model_path))
     make_private_file(model_path)