@simulatte/doppler 0.1.4 → 0.1.6

package/src/training/distillation/index.d.ts

@@ -0,0 +1,29 @@
+export {
+  normalizeDistillationPair,
+  normalizeTranslationPairRow,
+  loadCanonicalTranslationDataset,
+  buildFrozenSubset,
+} from './dataset.js';
+export {
+  createDistillationRunArtifacts,
+  writeDistillStageManifest,
+  writeDistillCheckpointMetadata,
+  writeDistillCheckpointComplete,
+  writeDistillEvalReport,
+  writeDistillCompareReport,
+  writeDistillQualityGateReport,
+  buildDistillArtifactBase,
+} from './artifacts.js';
+export { appendDistillationScoreboardRow } from './scoreboard.js';
+export {
+  buildDistillationTrainingConfigFromWorkload,
+  resolveInternalDistillStage,
+} from './runtime.js';
+export {
+  evaluateDistillationModel,
+  evaluateDistillationCheckpoint,
+  readDistillCheckpointMarker,
+} from './eval.js';
+export { runDistillationStage, runDistillationStageA } from './stage-a.js';
+export { runDistillationStageB } from './stage-b.js';
+export { watchDistillationCheckpoints } from './checkpoint-watch.js';

package/src/training/distillation/index.js

@@ -0,0 +1,29 @@
+export {
+  normalizeDistillationPair,
+  normalizeTranslationPairRow,
+  loadCanonicalTranslationDataset,
+  buildFrozenSubset,
+} from './dataset.js';
+export {
+  createDistillationRunArtifacts,
+  writeDistillStageManifest,
+  writeDistillCheckpointMetadata,
+  writeDistillCheckpointComplete,
+  writeDistillEvalReport,
+  writeDistillCompareReport,
+  writeDistillQualityGateReport,
+  buildDistillArtifactBase,
+} from './artifacts.js';
+export { appendDistillationScoreboardRow } from './scoreboard.js';
+export {
+  buildDistillationTrainingConfigFromWorkload,
+  resolveInternalDistillStage,
+} from './runtime.js';
+export {
+  evaluateDistillationModel,
+  evaluateDistillationCheckpoint,
+  readDistillCheckpointMarker,
+} from './eval.js';
+export { runDistillationStage, runDistillationStageA } from './stage-a.js';
+export { runDistillationStageB } from './stage-b.js';
+export { watchDistillationCheckpoints } from './checkpoint-watch.js';

package/src/training/distillation/runtime.d.ts

@@ -0,0 +1,20 @@
+import type { LoadedTrainingWorkload, DistillStagePlanEntry } from '../workloads.js';
+
+export declare function resolveInternalDistillStage(
+  stageEntry: DistillStagePlanEntry | Record<string, unknown>
+): 'stage_a' | 'stage_b';
+
+export declare function buildDistillationTrainingConfigFromWorkload(
+  loadedWorkload: LoadedTrainingWorkload,
+  stageEntry: DistillStagePlanEntry | Record<string, unknown>,
+  options?: {
+    datasetPath?: string | null;
+    artifactDir?: string | null;
+    stageAArtifact?: string | null;
+    stageAArtifactHash?: string | null;
+  }
+): {
+  internalStage: 'stage_a' | 'stage_b';
+  trainingConfig: Record<string, unknown>;
+  trainingConfigHash: string;
+};

package/src/training/distillation/runtime.js

@@ -0,0 +1,121 @@
+import { createTrainingConfig } from '../../config/training-defaults.js';
+import { sha256Hex } from '../../utils/sha256.js';
+
+function stableSortObject(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => stableSortObject(entry));
+  }
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+  const sorted = {};
+  for (const key of Object.keys(value).sort()) {
+    sorted[key] = stableSortObject(value[key]);
+  }
+  return sorted;
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableSortObject(value));
+}
+
+function normalizeStageLabel(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[\s-]+/g, '_');
+  return normalized;
+}
+
+export function resolveInternalDistillStage(stageEntry) {
+  const trainingStage = normalizeStageLabel(stageEntry?.trainingStage || stageEntry?.id || '');
+  const objective = normalizeStageLabel(stageEntry?.objective || '');
+  if (trainingStage === 'sft' || objective === 'sft') {
+    throw new Error(
+      'Distillation workload stage uses "sft", but the current JS distill runner only supports the KD-oriented stage_a contract. Use objective="kd" / trainingStage="stage_a" explicitly.'
+    );
+  }
+  if (
+    trainingStage === 'stage_b'
+    || trainingStage === 'post_sft_distill'
+    || trainingStage === 'post_sft_triplet'
+    || objective === 'triplet'
+  ) {
+    return 'stage_b';
+  }
+  if (
+    trainingStage === 'stage_a'
+    || trainingStage === 'kd'
+    || objective === 'kd'
+    || objective === 'cross_entropy'
+  ) {
+    return 'stage_a';
+  }
+  throw new Error(
+    `Unsupported distillation stage "${stageEntry?.trainingStage || stageEntry?.id || 'unknown'}".`
+  );
+}
+
+export function buildDistillationTrainingConfigFromWorkload(loadedWorkload, stageEntry, options = {}) {
+  const workload = loadedWorkload.workload;
+  if (workload.kind !== 'distill') {
+    throw new Error('buildDistillationTrainingConfigFromWorkload requires a distill workload.');
+  }
+  const internalStage = resolveInternalDistillStage(stageEntry);
+  const distillTraining = {
+    enabled: true,
+    stage: internalStage,
+    teacherModelId: workload.teacherModelId,
+    studentModelId: workload.studentModelId,
+    datasetId: workload.datasetId,
+    datasetPath: options.datasetPath || workload.datasetPath,
+    sourceLangs: workload.pipeline.sourceLangs,
+    targetLangs: workload.pipeline.targetLangs,
+    pairAllowlist: workload.pipeline.pairAllowlist,
+    strictPairContract: workload.pipeline.strictPairContract === true,
+    stageAArtifact: options.stageAArtifact || null,
+    stageAArtifactHash: options.stageAArtifactHash || null,
+    artifactDir: options.artifactDir || null,
+    temperature: workload.pipeline.temperature,
+    alphaKd: workload.pipeline.alphaKd,
+    alphaCe: workload.pipeline.alphaCe,
+    tripletMargin: workload.pipeline.tripletMargin,
+    studentGraphMode: workload.pipeline.studentGraphMode,
+  };
+  if (internalStage === 'stage_b') {
+    distillTraining.freeze = {
+      encoder: true,
+      prior: true,
+      decoder: true,
+      base: false,
+      lora: false,
+    };
+  }
+  const trainingConfig = createTrainingConfig({
+    training: {
+      enabled: true,
+      optimizer: {
+        type: workload.training.optimizer.type,
+        lr: workload.training.optimizer.lr,
+        beta1: workload.training.optimizer.beta1,
+        beta2: workload.training.optimizer.beta2,
+        eps: workload.training.optimizer.eps,
+        weightDecay: workload.training.optimizer.weightDecay,
+        scheduler: workload.training.optimizer.scheduler,
+      },
+      gradient: {
+        maxNorm: workload.training.gradientClipping.maxNorm,
+      },
+      precision: workload.training.precision,
+      distill: distillTraining,
+    },
+  });
+  return {
+    internalStage,
+    trainingConfig,
+    trainingConfigHash: sha256Hex(stableJson({
+      workloadConfigHash: workload.configHash,
+      stageEntry,
+      datasetPath: options.datasetPath || workload.datasetPath,
+      stageAArtifact: options.stageAArtifact || null,
+      stageAArtifactHash: options.stageAArtifactHash || null,
+    })),
+  };
+}

package/src/training/distillation/scoreboard.d.ts

@@ -0,0 +1,6 @@
+export declare function appendDistillationScoreboardRow(
+  layout: Record<string, string>,
+  stageId: string,
+  row: Record<string, unknown>,
+  options?: { selectionMetric?: string | null; selectionGoal?: string | null }
+): Promise<{ rowsPath: string; summaryPath: string }>;

package/src/training/distillation/scoreboard.js

@@ -0,0 +1,8 @@
+import { join } from 'node:path';
+
+import { appendScoreboardRow } from '../operator-scoreboard.js';
+
+export async function appendDistillationScoreboardRow(layout, stageId, row, options = {}) {
+  const scoreboardDir = join(layout.scoreboard, String(stageId || 'stage'));
+  return appendScoreboardRow(scoreboardDir, row, options);
+}

package/src/training/distillation/stage-a.d.ts

@@ -0,0 +1,45 @@
+import type { LoadedTrainingWorkload, DistillStagePlanEntry } from '../workloads.js';
+
+export declare function runDistillationStage(options: {
+  loadedWorkload: LoadedTrainingWorkload;
+  stageEntry: DistillStagePlanEntry;
+  layout: Record<string, string>;
+  datasetPath?: string | null;
+  stageAArtifact?: string | null;
+  stageAArtifactHash?: string | null;
+  legacyArtifactDir?: string | null;
+  timestamp?: string | Date | null;
+  parentArtifacts?: Array<Record<string, unknown>>;
+}): Promise<{
+  stageId: string;
+  trainingStage: 'stage_a' | 'stage_b';
+  metrics: Record<string, unknown>[];
+  checkpointArtifacts: Array<Record<string, unknown>>;
+  evalReports: Array<Record<string, unknown>>;
+  bestReport: Record<string, unknown> | null;
+  stageManifestPath: string;
+  legacyArtifact: Record<string, unknown> | null;
+  lastCheckpoint: Record<string, unknown> | null;
+}>;
+
+export declare function runDistillationStageA(options: {
+  loadedWorkload: LoadedTrainingWorkload;
+  stageEntry: DistillStagePlanEntry;
+  layout: Record<string, string>;
+  datasetPath?: string | null;
+  stageAArtifact?: string | null;
+  stageAArtifactHash?: string | null;
+  legacyArtifactDir?: string | null;
+  timestamp?: string | Date | null;
+  parentArtifacts?: Array<Record<string, unknown>>;
+}): Promise<{
+  stageId: string;
+  trainingStage: 'stage_a' | 'stage_b';
+  metrics: Record<string, unknown>[];
+  checkpointArtifacts: Array<Record<string, unknown>>;
+  evalReports: Array<Record<string, unknown>>;
+  bestReport: Record<string, unknown> | null;
+  stageManifestPath: string;
+  legacyArtifact: Record<string, unknown> | null;
+  lastCheckpoint: Record<string, unknown> | null;
+}>;

package/src/training/distillation/stage-a.js

@@ -0,0 +1,338 @@
+import { mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { AdamOptimizer } from '../optimizer.js';
+import { crossEntropyLoss } from '../loss.js';
+import { clipGradients } from '../clip.js';
+import { TrainingRunner } from '../runner.js';
+import {
+  createDistillRuntimeContext,
+  createDistillStudentRuntimeModelFixture,
+  loadDistillDatasetFromJsonl,
+  resolveDistillDataScope,
+} from '../suite.js';
+import { loadCanonicalTranslationDataset } from './dataset.js';
+import { evaluateDistillationModel } from './eval.js';
+import {
+  buildDistillArtifactBase,
+  writeDistillCheckpointComplete,
+  writeDistillCheckpointMetadata,
+  writeDistillStageManifest,
+} from './artifacts.js';
+import { appendDistillationScoreboardRow } from './scoreboard.js';
+import { buildDistillationTrainingConfigFromWorkload } from './runtime.js';
+
+function padStep(step) {
+  return String(step).padStart(6, '0');
+}
+
+function resolveComparableMetric(report, metric) {
+  if (!report || typeof report !== 'object') return null;
+  const direct = report[metric];
+  if (typeof direct === 'number' && Number.isFinite(direct)) {
+    return direct;
+  }
+  const metrics = report.metrics && typeof report.metrics === 'object' ? report.metrics : null;
+  const nested = metrics?.[metric];
+  if (typeof nested === 'number' && Number.isFinite(nested)) {
+    return nested;
+  }
+  if (metrics?.[metric]?.score != null && Number.isFinite(metrics[metric].score)) {
+    return metrics[metric].score;
+  }
+  return null;
+}
+
+function selectBestReport(reports, metric, goal) {
+  const normalizedGoal = String(goal || 'max').trim();
+  let best = null;
+  let bestValue = null;
+  for (const report of reports) {
+    const value = resolveComparableMetric(report, metric);
+    if (!Number.isFinite(value)) continue;
+    if (best === null) {
+      best = report;
+      bestValue = value;
+      continue;
+    }
+    const better = normalizedGoal === 'min'
+      ? value < bestValue
+      : value > bestValue;
+    if (better) {
+      best = report;
+      bestValue = value;
+    }
+  }
+  return best;
+}
+
+function shouldEvalOnCheckpoint(stageEntry) {
+  const schedule = String(stageEntry?.evalSchedule || 'on_checkpoint').trim();
+  return schedule === 'on_checkpoint';
+}
+
+function shouldEvalAtEnd(stageEntry) {
+  const schedule = String(stageEntry?.evalSchedule || 'on_checkpoint').trim();
+  return schedule === 'final';
+}
+
+export async function runDistillationStage(options) {
+  const loadedWorkload = options.loadedWorkload;
+  const workload = loadedWorkload.workload;
+  const stageEntry = options.stageEntry;
+  const datasetPath = options.datasetPath || workload.datasetPath;
+  const legacyArtifactDir = options.legacyArtifactDir || resolve(options.layout.runRoot, 'legacy-stage-artifacts');
+  if (workload.training.batchSize !== 1) {
+    throw new Error('Distillation stage currently requires training.batchSize=1.');
+  }
+  if (workload.training.accumSteps !== 1) {
+    throw new Error('Distillation stage currently requires training.accumSteps=1.');
+  }
+  const configBundle = buildDistillationTrainingConfigFromWorkload(loadedWorkload, stageEntry, {
+    datasetPath,
+    artifactDir: legacyArtifactDir,
+    stageAArtifact: options.stageAArtifact || null,
+    stageAArtifactHash: options.stageAArtifactHash || null,
+  });
+  const distillDataScope = resolveDistillDataScope({
+    distillSourceLangs: workload.pipeline.sourceLangs,
+    distillTargetLangs: workload.pipeline.targetLangs,
+    distillPairAllowlist: workload.pipeline.pairAllowlist,
+    strictPairContract: workload.pipeline.strictPairContract === true,
+  }, configBundle.trainingConfig.training);
+  const distillDatasetReport = await loadDistillDatasetFromJsonl(datasetPath, distillDataScope);
+  if (!distillDatasetReport) {
+    throw new Error(`Unable to resolve distillation dataset "${datasetPath}".`);
+  }
+  const canonicalDataset = await loadCanonicalTranslationDataset(datasetPath, {
+    strictPairContract: workload.pipeline.strictPairContract === true,
+    sourceLangs: workload.pipeline.sourceLangs,
+    targetLangs: workload.pipeline.targetLangs,
+    pairAllowlist: workload.pipeline.pairAllowlist,
+  });
+  const distillRuntime = await createDistillRuntimeContext({
+    teacherModelId: workload.teacherModelId,
+    studentModelId: workload.studentModelId,
+    trainingStage: configBundle.internalStage,
+    studentGraphMode: workload.pipeline.studentGraphMode,
+  }, configBundle.trainingConfig.training);
+  let fixture = null;
+  try {
+    fixture = await createDistillStudentRuntimeModelFixture({
+      training: configBundle.trainingConfig.training,
+    }, {
+      distillRuntime,
+      studentGraphMode: workload.pipeline.studentGraphMode,
+    });
+    const stageId = stageEntry.id;
+    const stageCheckpointsDir = resolve(options.layout.checkpoints, stageId);
+    await mkdir(stageCheckpointsDir, { recursive: true });
+    const dataset = distillDatasetReport.createDataset({
+      batchSize: workload.training.batchSize,
+      shuffle: false,
+      seed: workload.seed,
+      distillRuntime,
+    });
+    const checkpointArtifacts = [];
+    const evalReports = [];
+    const runner = new TrainingRunner(fixture.config, {
+      optimizer: new AdamOptimizer(fixture.config),
+      crossEntropyLoss,
+      clipGradients,
+      resolveCheckpointKey({ step }) {
+        const checkpointId = `checkpoint-${padStep(step)}`;
+        return resolve(stageCheckpointsDir, checkpointId, 'state.json');
+      },
+      onCheckpoint: async (checkpoint) => {
+        const checkpointId = `checkpoint-${padStep(checkpoint.step)}`;
+        const checkpointBase = buildDistillArtifactBase(loadedWorkload, {
+          prefix: 'dst_ckpt',
+          artifactType: 'training_checkpoint',
+          datasetPath: distillDatasetReport.absolutePath,
+          datasetHash: canonicalDataset.canonicalHash,
+          stage: stageId,
+          checkpointStep: checkpoint.step,
+          configHash: configBundle.trainingConfigHash,
+          parentArtifacts: options.parentArtifacts || [],
+        });
+        const metadataPayload = {
+          ...checkpointBase,
+          checkpointId,
+          checkpointPath: checkpoint.path,
+          step: checkpoint.step,
+          epoch: checkpoint.epoch,
+          batch: checkpoint.batch,
+          optimizerStatePresent: true,
+          schedulerStatePresent: workload.training.optimizer.scheduler.enabled === true,
+          stageArtifact: options.stageAArtifact || null,
+          resumeLineage: checkpoint.metadata?.lineage || null,
+        };
+        const metadataFile = await writeDistillCheckpointMetadata(
+          options.layout,
+          stageId,
+          checkpointId,
+          metadataPayload
+        );
+        const completeFile = await writeDistillCheckpointComplete(
+          options.layout,
+          stageId,
+          checkpointId,
+          {
+            ...metadataPayload,
+            metadataPath: metadataFile.path,
+            finalized: true,
+          }
+        );
+        checkpointArtifacts.push({
+          checkpointId,
+          checkpointPath: checkpoint.path,
+          metadataPath: metadataFile.path,
+          completePath: completeFile.path,
+          step: checkpoint.step,
+        });
+        if (!shouldEvalOnCheckpoint(stageEntry)) {
+          return;
+        }
+        const reports = await evaluateDistillationModel({
+          loadedWorkload,
+          layout: options.layout,
+          stageId,
+          checkpointId,
+          checkpointStep: checkpoint.step,
+          checkpointPath: checkpoint.path,
+          distillRuntime,
+          model: fixture.model,
+          configHash: configBundle.trainingConfigHash,
+          parentArtifacts: [{
+            artifactType: 'training_checkpoint',
+            path: metadataFile.path,
+            checkpointId,
+          }],
+        });
+        for (const report of reports) {
+          evalReports.push(report);
+          await appendDistillationScoreboardRow(options.layout, stageId, {
+            artifactType: 'training_scoreboard',
+            schemaVersion: 1,
+            generatedAt: new Date().toISOString(),
+            stage: stageId,
+            checkpointId,
+            checkpointStep: checkpoint.step,
+            evalDatasetId: report.evalDatasetId,
+            selectionMetric: stageEntry.selectionMetric,
+            selectionGoal: stageEntry.selectionGoal,
+            primaryMetric: report.primaryMetric,
+            primaryScore: report.primaryScore,
+            bleu: report.bleu,
+            chrf: report.chrf,
+            reportPath: report.reportPath || null,
+            metrics: {
+              bleu: report.bleu,
+              chrf: report.chrf,
+              primaryScore: report.primaryScore,
+            },
+          }, {
+            selectionMetric: stageEntry.selectionMetric,
+            selectionGoal: stageEntry.selectionGoal,
+          });
+        }
+      },
+    });
+    const metrics = await runner.run(fixture.model, dataset, {
+      epochs: 1,
+      batchSize: workload.training.batchSize,
+      shuffle: false,
+      maxSteps: stageEntry.steps,
+      checkpointEvery: stageEntry.checkpointEvery,
+      modelId: workload.studentModelId,
+      trainingStage: configBundle.internalStage,
+      runtimePreset: null,
+      command: 'distill',
+      surface: 'node',
+      timestamp: options.timestamp || null,
+      distillArtifactDir: legacyArtifactDir,
+      stageAArtifact: options.stageAArtifact || null,
+      stageAArtifactHash: options.stageAArtifactHash || null,
+      teacherModelId: workload.teacherModelId,
+      studentModelId: workload.studentModelId,
+      distillDatasetId: workload.datasetId,
+      distillDatasetPath: distillDatasetReport.absolutePath,
+      distillSourceLangs: workload.pipeline.sourceLangs,
+      distillTargetLangs: workload.pipeline.targetLangs,
+      distillPairAllowlist: workload.pipeline.pairAllowlist,
+      strictPairContract: workload.pipeline.strictPairContract === true,
+    });
+    if (shouldEvalAtEnd(stageEntry) && runner.lastCheckpoint) {
+      const finalCheckpointId = `checkpoint-${padStep(runner.lastCheckpoint.step)}`;
+      const reports = await evaluateDistillationModel({
+        loadedWorkload,
+        layout: options.layout,
+        stageId,
+        checkpointId: finalCheckpointId,
+        checkpointStep: runner.lastCheckpoint.step,
+        checkpointPath: runner.lastCheckpoint.path || null,
+        distillRuntime,
+        model: fixture.model,
+        configHash: configBundle.trainingConfigHash,
+      });
+      evalReports.push(...reports);
+    }
+    const bestReport = selectBestReport(
+      evalReports,
+      stageEntry.selectionMetric,
+      stageEntry.selectionGoal
+    );
+    const stageManifestPayload = {
+      ...buildDistillArtifactBase(loadedWorkload, {
+        prefix: 'dst_stage',
+        artifactType: 'distill_stage_manifest',
+        datasetPath: distillDatasetReport.absolutePath,
+        datasetHash: canonicalDataset.canonicalHash,
+        stage: stageId,
+        checkpointStep: runner.lastCheckpoint?.step ?? null,
+        configHash: configBundle.trainingConfigHash,
+        parentArtifacts: options.parentArtifacts || [],
+      }),
+      stageId,
+      trainingStage: configBundle.internalStage,
+      objective: stageEntry.objective,
+      stagePlanEntry: stageEntry,
+      stepCount: Array.isArray(metrics) ? metrics.length : 0,
+      checkpointCount: checkpointArtifacts.length,
+      bestCheckpointId: bestReport?.checkpointId || null,
+      selectionMetric: stageEntry.selectionMetric,
+      selectionGoal: stageEntry.selectionGoal,
+      checkpointArtifacts,
+      evalReports: evalReports.map((report) => ({
+        checkpointId: report.checkpointId,
+        evalDatasetId: report.evalDatasetId,
+        reportPath: report.reportPath || null,
+        primaryMetric: report.primaryMetric,
+        primaryScore: report.primaryScore,
+        bleu: report.bleu,
+        chrf: report.chrf,
+      })),
+      legacyArtifact: runner.lastArtifact || null,
+      lastCheckpoint: runner.lastCheckpoint || null,
+    };
+    const stageManifest = await writeDistillStageManifest(options.layout, stageManifestPayload);
+    return {
+      stageId,
+      trainingStage: configBundle.internalStage,
+      metrics,
+      checkpointArtifacts,
+      evalReports,
+      bestReport,
+      stageManifestPath: stageManifest.path,
+      legacyArtifact: runner.lastArtifact || null,
+      lastCheckpoint: runner.lastCheckpoint || null,
+    };
+  } finally {
+    fixture?.cleanup?.();
+    await distillRuntime.cleanup();
+  }
+}
+
+export async function runDistillationStageA(options) {
+  return runDistillationStage(options);
+}

package/src/training/distillation/stage-b.d.ts

@@ -0,0 +1,24 @@
+import type { LoadedTrainingWorkload, DistillStagePlanEntry } from '../workloads.js';
+
+export declare function runDistillationStageB(options: {
+  loadedWorkload: LoadedTrainingWorkload;
+  stageEntry: DistillStagePlanEntry;
+  layout: Record<string, string>;
+  datasetPath?: string | null;
+  stageAArtifact?: string | null;
+  stageAArtifactHash?: string | null;
+  legacyArtifactDir?: string | null;
+  timestamp?: string | Date | null;
+  parentArtifacts?: Array<Record<string, unknown>>;
+  priorStageResult?: Record<string, unknown> | null;
+}): Promise<{
+  stageId: string;
+  trainingStage: 'stage_a' | 'stage_b';
+  metrics: Record<string, unknown>[];
+  checkpointArtifacts: Array<Record<string, unknown>>;
+  evalReports: Array<Record<string, unknown>>;
+  bestReport: Record<string, unknown> | null;
+  stageManifestPath: string;
+  legacyArtifact: Record<string, unknown> | null;
+  lastCheckpoint: Record<string, unknown> | null;
+}>;

package/src/training/distillation/stage-b.js

@@ -0,0 +1,20 @@
+import { resolve } from 'node:path';
+
+import { runDistillationStage } from './stage-a.js';
+
+export async function runDistillationStageB(options) {
+  const priorStage = options.priorStageResult || null;
+  const stageAArtifact = options.stageAArtifact
+    || priorStage?.legacyArtifact?.manifestPath
+    || null;
+  if (!stageAArtifact) {
+    throw new Error('Distillation stage-b requires a Stage A artifact path.');
+  }
+  return runDistillationStage({
+    ...options,
+    stageAArtifact: resolve(String(stageAArtifact)),
+    stageAArtifactHash: options.stageAArtifactHash
+      || priorStage?.legacyArtifact?.manifestHash
+      || null,
+  });
+}

package/src/training/index.d.ts

@@ -10,6 +10,15 @@ export { exportLoRAAdapter } from './export.js';
 export { DynamicLossScaler, detectOverflow } from './loss-scaling.js';
 export { TrainingRunner, runTraining } from './runner.js';
 export { runTrainingSuite, runTrainingBenchSuite, trainingHarness } from './suite.js';
+export { runTrainingOperatorCommand } from './operator-command.js';
+export {
+  runLoraPipeline,
+  evaluateLoraCheckpoint,
+  exportLoraCheckpoint,
+  watchLoraCheckpoints,
+  compareLoraRun,
+  qualityGateLoraRun,
+} from './lora-pipeline.js';
 export type {
   TrainingObjective,
   TrainingObjectiveContext,
@@ -31,6 +40,7 @@ export type {
   DistillArtifactSession,
   DistillArtifactFinalizeResult,
 } from './artifacts.js';
+export * as distillation from './distillation/index.js';
 export {
   createDistillArtifactSession,
   resolveDistillTrainingContract,