@tuned-tensor/local 0.1.0

package/dist/store.js

@@ -0,0 +1,327 @@
+import { appendFile, copyFile, mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+export function defaultLocalHome() {
+    return resolve(process.env.TT_LOCAL_HOME ?? join(homedir(), ".tuned-tensor-local"));
+}
+export function localStorePaths(root) {
+    return {
+        root,
+        specsDir: join(root, "specs"),
+        runsDir: join(root, "runs"),
+        modelsDir: join(root, "models"),
+        datasetsDir: join(root, "datasets"),
+        catalogDir: join(root, "catalog"),
+        runsCatalog: join(root, "catalog", "runs.jsonl"),
+        specsCatalog: join(root, "catalog", "specs.jsonl"),
+        modelsCatalog: join(root, "catalog", "models.jsonl"),
+        datasetsCatalog: join(root, "catalog", "datasets.jsonl"),
+    };
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeJsonAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await rename(tmp, path);
+}
+async function readJson(path) {
+    return JSON.parse(await readFile(path, "utf8"));
+}
+async function appendJsonl(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, `${JSON.stringify(value)}\n`, "utf8");
+}
+async function readJsonlLatestById(path) {
+    if (!(await exists(path)))
+        return [];
+    const rows = (await readFile(path, "utf8"))
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+    return [...new Map(rows.map((row) => [row.id, row])).values()];
+}
+async function readJsonl(path) {
+    if (!(await exists(path)))
+        return [];
+    return (await readFile(path, "utf8"))
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+async function copyIfExists(from, to) {
+    if (!(await exists(from)))
+        return;
+    await mkdir(dirname(to), { recursive: true });
+    await copyFile(from, to);
+}
+export function createLocalStore(root = defaultLocalHome()) {
+    const resolvedRoot = resolve(root);
+    const paths = localStorePaths(resolvedRoot);
+    const runDir = (id) => join(paths.runsDir, id);
+    const runStatePath = (id) => join(runDir(id), "state.json");
+    const runEventsPath = (id) => join(runDir(id), "progress.jsonl");
+    const runRequestPath = (id) => join(runDir(id), "request.json");
+    const runReportPath = (id) => join(runDir(id), "run-report.json");
+    const specDir = (id) => join(paths.specsDir, id);
+    const specPath = (id) => join(specDir(id), "spec.json");
+    const modelPath = (id) => join(paths.modelsDir, id, "model.json");
+    async function ensure() {
+        await Promise.all([
+            mkdir(paths.specsDir, { recursive: true }),
+            mkdir(paths.runsDir, { recursive: true }),
+            mkdir(paths.modelsDir, { recursive: true }),
+            mkdir(paths.datasetsDir, { recursive: true }),
+            mkdir(paths.catalogDir, { recursive: true }),
+        ]);
+    }
+    async function writeRunState(state) {
+        await writeJsonAtomic(runStatePath(state.id), state);
+        await appendJsonl(paths.runsCatalog, { ...state, catalog_updated_at: new Date().toISOString() });
+        return state;
+    }
+    async function appendRunEvent(state, event) {
+        const row = {
+            id: randomUUID(),
+            run_id: state.id,
+            occurred_at: new Date().toISOString(),
+            ...event,
+        };
+        await appendJsonl(runEventsPath(state.id), row);
+        await appendJsonl(join(state.artifact_dir, "progress.jsonl"), {
+            at: row.occurred_at,
+            stage: row.stage,
+            status: row.status,
+            message: row.message,
+            ...(row.details ? { details: row.details } : {}),
+        });
+    }
+    async function resolveRunId(id) {
+        if (await exists(runStatePath(id)))
+            return id;
+        const records = await readJsonlLatestById(paths.runsCatalog);
+        const record = records.find((row) => row.id === id || row.id.startsWith(id));
+        if (!record)
+            throw new Error(`Run not found: ${id}`);
+        return record.id;
+    }
+    async function getRun(id) {
+        return readJson(runStatePath(await resolveRunId(id)));
+    }
+    return {
+        root: resolvedRoot,
+        paths,
+        ensure,
+        async importSpec(specId, spec) {
+            await ensure();
+            const now = new Date().toISOString();
+            const existingRecord = (await readJsonlLatestById(paths.specsCatalog))
+                .find((row) => row.id === specId);
+            const record = {
+                id: specId,
+                name: spec.name,
+                base_model: spec.base_model,
+                path: specPath(specId),
+                created_at: existingRecord?.created_at ?? now,
+                updated_at: now,
+            };
+            await writeJsonAtomic(specPath(specId), spec);
+            await appendJsonl(paths.specsCatalog, record);
+            return record;
+        },
+        async listSpecs() {
+            await ensure();
+            return (await readJsonlLatestById(paths.specsCatalog))
+                .sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+        },
+        async getSpec(id) {
+            const records = await this.listSpecs();
+            const record = records.find((row) => row.id === id || row.id.startsWith(id));
+            if (!record)
+                throw new Error(`Spec not found: ${id}`);
+            return { ...record, spec: await readJson(record.path) };
+        },
+        async startRun({ request, artifactDir }) {
+            await ensure();
+            await this.importSpec(request.behavior_spec_id, request.spec_snapshot);
+            const now = new Date().toISOString();
+            const state = {
+                id: request.run_id,
+                behavior_spec_id: request.behavior_spec_id,
+                user_id: request.user_id,
+                run_number: request.run_number,
+                status: "queued",
+                current_stage: "queued",
+                status_message: "Run queued.",
+                artifact_dir: artifactDir,
+                base_model: request.spec_snapshot.base_model,
+                spec_name: request.spec_snapshot.name,
+                created_at: now,
+                updated_at: now,
+                started_at: now,
+            };
+            await writeJsonAtomic(runRequestPath(request.run_id), request);
+            await writeRunState(state);
+            await appendRunEvent(state, { stage: "queued", status: "queued", message: "Run queued." });
+            return state;
+        },
+        async updateRun({ runId, status, stage, message, details }) {
+            const previous = await getRun(runId);
+            const state = {
+                ...previous,
+                status,
+                current_stage: stage,
+                status_message: message,
+                updated_at: new Date().toISOString(),
+            };
+            await writeRunState(state);
+            await appendRunEvent(state, { stage, status: status === "completed" ? "completed" : "running", message, details });
+            return state;
+        },
+        async completeRun(report, artifactDir, reportPath) {
+            const previous = await getRun(report.run_id);
+            const modelId = `local-${report.run_id}`;
+            const completedAt = report.created_at ?? new Date().toISOString();
+            const state = {
+                ...previous,
+                status: "completed",
+                current_stage: "completed",
+                status_message: "Run completed successfully.",
+                report_path: reportPath,
+                model_id: modelId,
+                completed_at: completedAt,
+                updated_at: completedAt,
+            };
+            await writeRunState(state);
+            await copyIfExists(reportPath, runReportPath(report.run_id));
+            await appendRunEvent(state, {
+                stage: "completed",
+                status: "completed",
+                message: "Run completed successfully.",
+                details: { report_path: reportPath, model_id: modelId },
+            });
+            const model = {
+                id: modelId,
+                run_id: report.run_id,
+                behavior_spec_id: report.behavior_spec_id,
+                name: `${report.run_metadata?.base_model ?? report.base_model} (${report.run_id.slice(0, 8)})`,
+                provider: "local-uv",
+                base_model: report.base_model,
+                artifact_uri: report.fine_tuned_model_id,
+                artifact_dir: artifactDir,
+                metrics: report.training.metrics,
+                created_at: completedAt,
+            };
+            await writeJsonAtomic(modelPath(model.id), model);
+            await appendJsonl(paths.modelsCatalog, model);
+            return state;
+        },
+        async failRun(runId, error) {
+            const previous = await getRun(runId);
+            const now = new Date().toISOString();
+            const state = {
+                ...previous,
+                status: "failed",
+                current_stage: "failed",
+                status_message: error,
+                error,
+                completed_at: now,
+                updated_at: now,
+            };
+            await writeRunState(state);
+            await appendRunEvent(state, { stage: "failed", status: "failed", message: error });
+            return state;
+        },
+        async cancelRun(runId) {
+            const state = await getRun(runId);
+            await writeFile(join(runDir(state.id), "cancel.requested"), `${new Date().toISOString()}\n`, "utf8");
+            const updated = {
+                ...state,
+                status: "cancelled",
+                current_stage: "cancel_requested",
+                status_message: "Cancellation requested.",
+                updated_at: new Date().toISOString(),
+            };
+            await writeRunState(updated);
+            await appendRunEvent(updated, { stage: "cancel_requested", status: "cancelled", message: "Cancellation requested." });
+        },
+        async listRuns() {
+            await ensure();
+            return (await readJsonlLatestById(paths.runsCatalog))
+                .sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+        },
+        getRun,
+        async getRunEvents(id) {
+            const state = await getRun(id);
+            return readJsonl(runEventsPath(state.id));
+        },
+        async getRunReport(id) {
+            const state = await getRun(id);
+            if (state.report_path && await exists(state.report_path)) {
+                return readJson(state.report_path);
+            }
+            const copiedReportPath = runReportPath(state.id);
+            if (await exists(copiedReportPath))
+                return readJson(copiedReportPath);
+            throw new Error(`Run has no report yet: ${id}`);
+        },
+        async listModels() {
+            await ensure();
+            return (await readJsonlLatestById(paths.modelsCatalog))
+                .sort((a, b) => b.created_at.localeCompare(a.created_at));
+        },
+        async getModel(id) {
+            const models = await this.listModels();
+            const record = models.find((row) => row.id === id || row.id.startsWith(id));
+            if (!record)
+                throw new Error(`Model not found: ${id}`);
+            return record;
+        },
+        async rebuildIndexes() {
+            await ensure();
+            const runRecords = [];
+            for (const entry of await readdir(paths.runsDir, { withFileTypes: true }).catch(() => [])) {
+                if (!entry.isDirectory())
+                    continue;
+                const statePath = runStatePath(entry.name);
+                if (await exists(statePath)) {
+                    const state = await readJson(statePath);
+                    runRecords.push({ ...state, catalog_updated_at: new Date().toISOString() });
+                }
+            }
+            const specRecords = [];
+            for (const entry of await readdir(paths.specsDir, { withFileTypes: true }).catch(() => [])) {
+                if (!entry.isDirectory())
+                    continue;
+                const path = specPath(entry.name);
+                if (await exists(path)) {
+                    const spec = await readJson(path);
+                    const now = new Date().toISOString();
+                    specRecords.push({ id: entry.name, name: spec.name, base_model: spec.base_model, path, created_at: now, updated_at: now });
+                }
+            }
+            const modelRecords = [];
+            for (const entry of await readdir(paths.modelsDir, { withFileTypes: true }).catch(() => [])) {
+                if (!entry.isDirectory())
+                    continue;
+                const path = modelPath(entry.name);
+                if (await exists(path))
+                    modelRecords.push(await readJson(path));
+            }
+            await writeFile(paths.runsCatalog, runRecords.map((row) => JSON.stringify(row)).join("\n") + (runRecords.length ? "\n" : ""), "utf8");
+            await writeFile(paths.specsCatalog, specRecords.map((row) => JSON.stringify(row)).join("\n") + (specRecords.length ? "\n" : ""), "utf8");
+            await writeFile(paths.modelsCatalog, modelRecords.map((row) => JSON.stringify(row)).join("\n") + (modelRecords.length ? "\n" : ""), "utf8");
+            await writeFile(paths.datasetsCatalog, "", "utf8");
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,109 @@
+# Architecture
+
+Tuned Tensor Local is organized around a small set of replaceable local
+adapters. The first implementation targets a single Linux GPU host and is
+packaged as a standalone CLI.
+
+## Subsystems
+
+- Local orchestrator: runs the workflow states in-process and records progress
+  to local files.
+- Local project spec: `tt-local init` creates a local `tunedtensor.json`, and
+  `tt-local run` converts that spec into the same run request contract used by
+  compatible hosted exports.
+- Artifact store: writes datasets, logs, model outputs, and reports beneath a
+  configured local artifact root.
+- Local state store: persists specs, runs, progress events, reports, and model
+  records as JSON/JSONL under a configured `storeRoot` for the dashboard and CLI.
+- Training adapter: launches a uv-managed Python process with local input,
+  model cache, and output directories passed through environment variables.
+- Evaluation adapter: runs local Hugging Face/PEFT inference for baseline and
+  candidate evaluation. Evaluation can also use an OpenRouter LLM judge to score
+  locally generated outputs.
+- Report writer: emits structured JSON reports that are portable across local
+  and hosted environments.
+- Dashboard/API server: serves local run/model/spec metadata from the local
+  state store and accepts local run submissions.
+
+## Repository Boundary
+
+This repository should remain a clean open-source implementation. Private
+deployment code, proprietary provider adapters, account projection code, and
+billing integrations stay out of this project.
+
+The hosted Tuned Tensor CLI can keep cloud-specific workflows such as auth,
+accounts, billing, and managed runs. `tt-local` must be useful on its own: local
+spec creation, validation, execution, run tracking, model inspection, and the
+dashboard should not depend on the hosted CLI.
+
+## First Milestone
+
+The first runnable milestone should support:
+
+- one local run at a time;
+- one GPU device;
+- local filesystem artifacts;
+- local file-backed run/model/spec tracking;
+- standalone `tt-local init`, `validate`, `run`, `serve`, and inspection
+  commands;
+- uv-based training;
+- native Transformers/PEFT evaluation with optional OpenRouter judge scoring;
+- local dashboard and CLI inspection commands;
+- a tiny smoke-run fixture that finishes quickly.
+
+## Configuration Shape
+
+The public runner should accept a plain JSON run request and a local runner
+configuration. The run request describes the behavior spec, base model,
+examples, and hyperparameters. The local runner configuration describes artifact
+paths, store paths, uv entrypoint settings, model cache paths, OpenRouter judge
+settings, and timeout limits.
+
+## Evaluation Loop
+
+The local loop intentionally compares like-for-like model artifacts:
+
+- baseline loads the original Hugging Face base model from the behavior spec;
+- training writes a Hugging Face/PEFT artifact under the run directory;
+- candidate evaluation loads the same base model plus that fine-tuned artifact;
+- the report compares the two eval reports and stores generated outputs.
+
+The first native backend is `transformers`. `llama.cpp`/GGUF conversion is not
+part of the default path because conversion would make the baseline/candidate
+comparison less direct.
+
+## Local State Layout
+
+The local store is intentionally transparent and easy to back up:
+
+- `specs/<spec-id>/spec.json`
+- `runs/<run-id>/request.json`
+- `runs/<run-id>/state.json`
+- `runs/<run-id>/progress.jsonl`
+- `runs/<run-id>/run-report.json`
+- `models/<model-id>/model.json`
+- `catalog/*.jsonl`
+
+Catalog files are append-only indexes for fast listing. `tt-local store
+rebuild-index` can reconstruct them from the canonical per-object files.
+
+## Dashboard API
+
+The local server is a lightweight Node HTTP server, not a separate database.
+Current endpoints include:
+
+- `GET /api/health`
+- `GET /api/runs`, `GET /api/runs/:id`, `GET /api/runs/:id/events`
+- `GET /api/runs/:id/events/stream`
+- `GET /api/runs/:id/report`
+- `POST /api/runs`
+- `POST /api/runs/:id/cancel`
+- `GET /api/models`, `GET /api/models/:id`
+- `GET /api/specs`, `GET /api/specs/:id`
+
+## Failure Handling
+
+The orchestrator should fail fast when prerequisites are missing. Common checks
+include uv availability, Python dependency resolution, GPU visibility, model
+cache permissions, artifact directory writability, and dataset size limits for
+the selected model.

package/docs/spark.md

@@ -0,0 +1,86 @@
+# Running On DGX Spark
+
+Tuned Tensor Local expects the Spark to behave like a single Linux GPU host:
+uv must be installed, Python dependencies must resolve, and CUDA/PyTorch must be
+able to see the GPU.
+
+## Host Checks
+
+Run these on the Spark host:
+
+```bash
+nvidia-smi
+uv --version
+uv run python --version
+```
+
+If uv is missing, install it with the official standalone installer:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Open a new shell or source the installer-updated profile before rerunning
+`uv --version`.
+
+Then run the project doctor command:
+
+```bash
+npm run build
+tt-local doctor --config examples/local-runner.json
+```
+
+## Dry Run
+
+The example config uses `dryRun: true`, so it validates orchestration, dataset
+compilation, artifact writing, and report generation without launching training:
+
+```bash
+tt-local run examples/smoke-run-request.json --config examples/local-runner.json
+```
+
+## Real Training
+
+For real training, set `dryRun: false` and configure the uv training entrypoint:
+
+```json
+{
+  "artifactRoot": "/home/eve/tt-local-artifacts",
+  "dryRun": false,
+  "training": {
+    "backend": "uv",
+    "project": "training/sft-local",
+    "script": "training/sft-local/src/train.py"
+  },
+  "paths": {
+    "modelCache": "/home/eve/.cache/huggingface"
+  }
+}
+```
+
+The runner sets:
+
+- `SM_CHANNEL_TRAINING` to the local chat JSONL training directory;
+- `TT_HYPERPARAMETERS_PATH` to the generated hyperparameter JSON file;
+- `SM_OUTPUT_DIR` to the local training output directory;
+- `SM_MODEL_DIR` to the local model output directory;
+- `SM_CHANNEL_BASE_MODEL` when a local base-model artifact path is configured;
+- `HF_HOME` when `paths.modelCache` is configured.
+
+Real runs also use the Transformers/PEFT evaluator by default. Baseline
+evaluation loads the original Hugging Face model, and candidate evaluation loads
+that same base model plus the fine-tuned artifact from the run directory. Set
+`paths.modelCache` to a persistent Spark-local cache so training and evaluation
+reuse downloads.
+
+The included first-pass SFT script can be run by the local runner through uv:
+
+```bash
+tt-local run examples/smoke-run-request.json --config examples/local-runner.json
+```
+
+The SFT uv project currently points Linux installs at the PyTorch CUDA 13.0
+wheel index. If PyTorch does not publish a compatible wheel for the Spark's
+architecture, use `training.env`, `training.project`, or the SFT
+`pyproject.toml` to point uv at the NVIDIA/PyTorch package source that matches
+the host.

package/examples/local-runner.json

@@ -0,0 +1,14 @@
+{
+  "artifactRoot": ".tt-local/artifacts",
+  "storeRoot": ".tt-local/store",
+  "dryRun": true,
+  "training": {
+    "backend": "uv",
+    "project": "training/sft-local",
+    "script": "training/sft-local/src/train.py"
+  },
+  "evaluation": {
+    "mode": "heuristic",
+    "maxExamples": 2
+  }
+}

package/examples/smoke-run-request.json

@@ -0,0 +1,34 @@
+{
+  "run_id": "11111111-1111-4111-8111-111111111111",
+  "user_id": "local-user",
+  "behavior_spec_id": "22222222-2222-4222-8222-222222222222",
+  "run_number": 1,
+  "spec_snapshot": {
+    "name": "Local Smoke Assistant",
+    "description": "Tiny local runner smoke test.",
+    "system_prompt": "Answer in a concise, literal style.",
+    "guidelines": [
+      "Prefer the expected label when the input is a label request."
+    ],
+    "constraints": [
+      "Do not include extra commentary."
+    ],
+    "base_model": "Qwen/Qwen3.5-2B",
+    "examples": [
+      {
+        "input": "Classify sentiment: I love this product.",
+        "output": "positive"
+      },
+      {
+        "input": "Classify sentiment: This was disappointing.",
+        "output": "negative"
+      }
+    ]
+  },
+  "hyperparameters": {
+    "n_epochs": 1,
+    "augment": false,
+    "use_llm_judge": false,
+    "save_adapter_only": true
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@tuned-tensor/local",
+  "version": "0.1.0",
+  "description": "Local, cloud-independent fine-tuning runner for Tuned Tensor behavior specs.",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "tt-local": "dist/index.js",
+    "tuned-tensor-local": "dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "training",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test \"test/**/*.test.ts\""
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}

package/training/sft-local/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "tuned-tensor-local-sft"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+  "accelerate>=1.0.0",
+  "peft>=0.13.0",
+  "safetensors>=0.4.5",
+  "torch>=2.11.0",
+  "transformers>=4.46.0",
+]
+
+[tool.uv.sources]
+torch = [
+  { index = "pytorch-cu130", marker = "sys_platform == 'linux'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-cu130"
+url = "https://download.pytorch.org/whl/cu130"
+explicit = true
+
+[tool.uv]
+package = false