@simulatte/doppler 0.1.5 → 0.1.7

package/tools/doppler-cli.js

@@ -22,8 +22,6 @@ const DEFAULT_CLI_POLICY = {
       allowed: ['auto', 'node', 'browser'],
     },
     bench: {
-      modelId: 'gemma-3-270m-it-wf16-ef16-hf16',
-      surface: 'browser',
       cacheMode: 'warm',
     },
     cacheMode: null,
@@ -66,6 +64,8 @@ function usage() {
     '  doppler debug --config <path.json|json> [--runtime-config <path|url|json>] [--surface auto|node|browser]',
     '  doppler bench --config <path.json|json> [--runtime-config <path|url|json>] [--surface auto|node|browser]',
     '  doppler verify --config <path.json|json> [--runtime-config <path|url|json>] [--surface auto|node|browser]',
+    '  doppler lora --config <path.json|json> [--surface auto|node]',
+    '  doppler distill --config <path.json|json> [--surface auto|node]',
     '',
     'Flags:',
     '  --config <path|json>            Required command config payload (file path or JSON object string).',
@@ -80,7 +80,7 @@ function usage() {
     '    - run: CLI-only run controls (surface, browser options, and bench save/compare/manifest settings).',
     '',
     'Example:',
-    '  doppler verify --config \'{"request":{"suite":"inference","modelId":"gemma-3-270m-it-wf16-ef16-hf16"}}\' --json',
+    '  doppler verify --config \'{"request":{"suite":"inference","modelId":"gemma-3-270m-it-f16-af32"}}\' --json',
   ].join('\n');
 }
 
@@ -337,7 +337,89 @@ function resolveStaticRootDir(browserOptions = {}) {
   return process.cwd();
 }
 
-async function resolveBrowserModelUrl(request, browserOptions = {}) {
+function resolveRdrrRoot(options = {}) {
+  return path.resolve(asStringOrNull(options.rdrrRoot) || DEFAULT_EXTERNAL_RDRR_ROOT);
+}
+
+async function findResolvableModelCandidate(candidates) {
+  const discoveredManifestCandidates = [];
+
+  for (const candidate of candidates) {
+    if (!await pathExists(candidate.manifestPath)) {
+      continue;
+    }
+    discoveredManifestCandidates.push(candidate);
+
+    const modelDir = path.dirname(candidate.manifestPath);
+    try {
+      const files = await fs.readdir(modelDir, { withFileTypes: true });
+      const hasShards = files.some((entry) =>
+        entry.isFile() && /^shard_\d+\.bin$/u.test(entry.name)
+      );
+      if (hasShards) {
+        return { candidate, discoveredManifestCandidates };
+      }
+    } catch {
+      return { candidate, discoveredManifestCandidates };
+    }
+  }
+
+  return { candidate: null, discoveredManifestCandidates };
+}
+
+async function resolveExternalModelDirectory(rdrrRoot, modelId) {
+  const directModelDir = path.join(rdrrRoot, modelId);
+  const directManifestPath = path.join(directModelDir, 'manifest.json');
+  if (await pathExists(directManifestPath)) {
+    return {
+      modelDir: directModelDir,
+      manifestPath: directManifestPath,
+    };
+  }
+
+  let entries = [];
+  try {
+    entries = await fs.readdir(rdrrRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const matches = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const manifestPath = path.join(rdrrRoot, entry.name, 'manifest.json');
+    if (!await pathExists(manifestPath)) {
+      continue;
+    }
+    let manifest = null;
+    try {
+      manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (manifest?.modelId !== modelId) {
+      continue;
+    }
+    matches.push({
+      modelDir: path.join(rdrrRoot, entry.name),
+      manifestPath,
+    });
+  }
+
+  if (matches.length > 1) {
+    const matchPaths = matches.map((match) => match.modelDir).join(', ');
+    throw new Error(
+      `Model "${modelId}" matched multiple external directories. ` +
+      `Disambiguate by setting request.modelUrl in --config. Matches: ${matchPaths}`
+    );
+  }
+
+  return matches[0] || null;
+}
+
+export async function resolveBrowserModelUrl(request, browserOptions = {}) {
   if (request.modelUrl || !request.modelId) {
     return request;
   }
@@ -353,49 +435,28 @@ async function resolveBrowserModelUrl(request, browserOptions = {}) {
   }
 
   const staticRootDir = resolveStaticRootDir(browserOptions);
-  const curatedCandidate = {
-    modelUrl: `/models/curated/${encodedModelId}`,
-    manifestPath: path.join(staticRootDir, 'models', 'curated', modelId, 'manifest.json'),
-  };
-  const localCandidate = {
+  const externalModel = await resolveExternalModelDirectory(resolveRdrrRoot(browserOptions), modelId);
+  const candidates = [
+    {
     modelUrl: `/models/local/${encodedModelId}`,
     manifestPath: path.join(staticRootDir, 'models', 'local', modelId, 'manifest.json'),
-  };
-  const legacyCandidate = {
+    },
+    {
     modelUrl: `/models/${encodedModelId}`,
     manifestPath: path.join(staticRootDir, 'models', modelId, 'manifest.json'),
-  };
-  const candidates = [
-    curatedCandidate,
-    localCandidate,
-    legacyCandidate,
+    },
+    {
+      modelUrl: `/models/external/${encodeURIComponent(path.basename(externalModel?.modelDir || modelId))}`,
+      manifestPath: externalModel?.manifestPath || path.join(resolveRdrrRoot(browserOptions), modelId, 'manifest.json'),
+    },
   ];
-  const discoveredManifestCandidates = [];
-
-  for (const candidate of candidates) {
-    if (!await pathExists(candidate.manifestPath)) {
-      continue;
-    }
-    discoveredManifestCandidates.push(candidate);
 
-    const modelDir = path.dirname(candidate.manifestPath);
-    try {
-      const files = await fs.readdir(modelDir, { withFileTypes: true });
-      const hasShards = files.some((entry) =>
-        entry.isFile() && /^shard_\d+\.bin$/u.test(entry.name)
-      );
-      if (hasShards) {
-        return {
-          ...request,
-          modelUrl: candidate.modelUrl,
-        };
-      }
-    } catch {
-      return {
-        ...request,
-        modelUrl: candidate.modelUrl,
-      };
-    }
+  const { candidate, discoveredManifestCandidates } = await findResolvableModelCandidate(candidates);
+  if (candidate) {
+    return {
+      ...request,
+      modelUrl: candidate.modelUrl,
+    };
   }
 
   if (discoveredManifestCandidates.length > 0) {
@@ -421,13 +482,13 @@ export async function resolveNodeModelUrl(request, options = {}) {
   }
 
   const modelId = String(request.modelId);
-  const rdrrRoot = path.resolve(asStringOrNull(options.rdrrRoot) || DEFAULT_EXTERNAL_RDRR_ROOT);
-  const manifestPath = path.join(rdrrRoot, modelId, 'manifest.json');
-  if (!await pathExists(manifestPath)) {
+  const rdrrRoot = resolveRdrrRoot(options);
+  const externalModel = await resolveExternalModelDirectory(rdrrRoot, modelId);
+  if (!externalModel) {
     return request;
   }
 
-  const modelDir = path.dirname(manifestPath);
+  const modelDir = externalModel.modelDir;
   try {
     const files = await fs.readdir(modelDir, { withFileTypes: true });
     const hasShards = files.some((entry) =>
@@ -461,6 +522,9 @@ function parseSurface(value, command, policy = DEFAULT_CLI_POLICY) {
   if (command === 'convert' && normalized === 'browser') {
     throw new Error('convert is not supported on browser relay. Use --surface node or --surface auto.');
   }
+  if ((command === 'lora' || command === 'distill') && normalized === 'browser') {
+    throw new Error(`${command} is not supported on browser relay. Use --surface node or --surface auto.`);
+  }
   return normalized;
 }
 
@@ -520,13 +584,10 @@ function resolveBenchRunOptions(runConfig, policy = DEFAULT_CLI_POLICY) {
 function resolveSurfaceForCommand(command, parsed, runConfig, policy = DEFAULT_CLI_POLICY) {
   const fromCli = asStringOrNull(parsed.flags.surface);
   const fromRun = asStringOrNull(runConfig?.surface);
-  const fromPolicy = command === 'bench'
-    ? asStringOrNull(policy?.defaults?.bench?.surface)
-    : null;
-  return parseSurface(fromCli ?? fromRun ?? fromPolicy, command, policy);
+  return parseSurface(fromCli ?? fromRun ?? null, command, policy);
 }
 
-async function buildRequest(parsed, policy = DEFAULT_CLI_POLICY) {
+export async function buildRequest(parsed, policy = DEFAULT_CLI_POLICY) {
   const command = parsed.command;
   if (!command || !TOOLING_COMMANDS.includes(command)) {
     throw new Error(`Unsupported command "${command || ''}"`);
@@ -545,21 +606,15 @@ async function buildRequest(parsed, policy = DEFAULT_CLI_POLICY) {
   }
   requestInput.command = command;
 
-  if (command === 'bench' && !asStringOrNull(requestInput.modelId) && !asStringOrNull(requestInput.modelUrl)) {
-    const benchDefaultModelId = asStringOrNull(policy?.defaults?.bench?.modelId);
-    if (benchDefaultModelId) {
-      requestInput.modelId = benchDefaultModelId;
-    }
-  }
-
   applyRuntimeFlagOverride(requestInput, runtimeOverride);
 
   const surfaceFromCli = asStringOrNull(parsed.flags.surface) !== null;
+  const surface = resolveSurfaceForCommand(command, parsed, envelope.run, policy);
 
   return {
     request: normalizeToolingCommandRequest(requestInput),
     runConfig: envelope.run,
-    surface: resolveSurfaceForCommand(command, parsed, envelope.run, policy),
+    surface,
     surfaceFromCli,
     benchRunOptions: resolveBenchRunOptions(envelope.run, policy),
   };
@@ -593,10 +648,18 @@ function buildBrowserRunOptions(runConfig, jsonOutput, request = {}) {
     executablePath: asStringOrNull(browser.executablePath),
     runnerPath: asStringOrNull(browser.runnerPath),
     staticRootDir: asStringOrNull(browser.staticRootDir),
+    rdrrRoot: asStringOrNull(browser.rdrrRoot),
     baseUrl: asStringOrNull(browser.baseUrl),
     browserArgs: parseBrowserArgs(browser.browserArgs),
     headless: headed ? false : (explicitHeadless ?? true),
   };
+  const rdrrRoot = resolveRdrrRoot(options);
+  options.staticMounts = [
+    {
+      urlPrefix: '/models/external',
+      rootDir: rdrrRoot,
+    },
+  ];
 
   const port = parseNumberFlag(browser.port, 'run.browser.port');
   if (port !== null) {
@@ -644,9 +707,36 @@ function isNodeWebGPUFallbackCandidate(error, fallbackPolicy = DEFAULT_CLI_POLIC
 function isTrainingCommandFlow(request) {
   if (!request || typeof request !== 'object') return false;
   if (request.suite === 'training') return true;
+  if (request.command === 'lora' || request.command === 'distill') return true;
   return request.command === 'bench' && request.workloadType === 'training';
 }
 
+function resolveErrorSurface(error, fallbackSurface = null) {
+  return (
+    asStringOrNull(fallbackSurface)
+    || asStringOrNull(error?.surface)
+    || asStringOrNull(error?.details?.surface)
+    || null
+  );
+}
+
+export function createCliToolingErrorEnvelope(error, context = {}) {
+  return createToolingErrorEnvelope(error, {
+    surface: resolveErrorSurface(error, context.surface),
+    request: context.request ?? null,
+  });
+}
+
+export function finalizeCliCommandResponse(response, request) {
+  if (!isPlainObject(response) || !Object.prototype.hasOwnProperty.call(response, 'request')) {
+    return response;
+  }
+  return {
+    ...response,
+    request,
+  };
+}
+
 async function runCommandOnSurface(request, surface, runConfig, jsonOutput) {
   if (surface === 'node') {
     const nodeRequest = await resolveNodeModelUrl(request);
@@ -656,7 +746,8 @@ async function runCommandOnSurface(request, surface, runConfig, jsonOutput) {
         console.error(`[surface] node resolved modelUrl=${nodeRequest.modelUrl}`);
       }
     }
-    return runNodeCommand(nodeRequest, buildNodeRunOptions(jsonOutput));
+    const response = await runNodeCommand(nodeRequest, buildNodeRunOptions(jsonOutput));
+    return finalizeCliCommandResponse(response, request);
   }
 
   const browserOptions = buildBrowserRunOptions(runConfig, jsonOutput, request);
@@ -670,7 +761,8 @@ async function runCommandOnSurface(request, surface, runConfig, jsonOutput) {
     }
   }
 
-  return runBrowserCommandInNode(browserRequest, browserOptions);
+  const response = await runBrowserCommandInNode(browserRequest, browserOptions);
+  return finalizeCliCommandResponse(response, request);
 }
 
 async function runWithAutoSurface(request, runConfig, jsonOutput, policy = DEFAULT_CLI_POLICY) {
@@ -687,9 +779,12 @@ async function runWithAutoSurface(request, runConfig, jsonOutput, policy = DEFAU
     }
     if (isTrainingCommandFlow(request)) {
       const downgradeError = new Error(
-        'Training command auto-surface downgrade is blocked. Re-run with --surface node after fixing Node WebGPU support, or explicitly choose --surface browser.'
+        (request.command === 'lora' || request.command === 'distill')
+          ? 'Training command auto-surface downgrade is blocked. Re-run with --surface node after fixing Node WebGPU support.'
+          : 'Training command auto-surface downgrade is blocked. Re-run with --surface node after fixing Node WebGPU support, or explicitly choose --surface browser.'
       );
       downgradeError.code = 'training_surface_downgrade_blocked';
+      downgradeError.surface = 'node';
       downgradeError.command = request.command;
       downgradeError.suite = request.suite;
       downgradeError.workloadType = request.workloadType || null;
@@ -726,6 +821,13 @@ function toSummary(result) {
     return `converted ${result.manifest.modelId} (${result.tensorCount} tensors, ${result.shardCount} shards)${contractStatus}${graphStatus}`;
   }
 
+  if (result.kind === 'lora' || result.kind === 'distill') {
+    const workloadId = result.workloadId || 'unknown';
+    const action = result.action || 'run';
+    const runRoot = result.runRoot || 'n/a';
+    return `${result.kind} ${action} workload=${workloadId} runRoot=${runRoot}`;
+  }
+
   const suite = result.suite || result.report?.suite || 'suite';
   const modelId = result.modelId || result.report?.modelId || 'unknown';
   const passed = Number.isFinite(result.passed) ? result.passed : null;
@@ -938,7 +1040,7 @@ async function runManifestSweep(manifest, commandContext, jsonOutput, policy = D
       results.push({
         label,
         response: null,
-        error: createToolingErrorEnvelope(error, {
+        error: createCliToolingErrorEnvelope(error, {
           surface: surface === 'auto' ? null : surface,
           request,
         }),
@@ -1122,6 +1224,20 @@ function printConvertReportSummary(result) {
 
 function printMetricsSummary(result) {
   if (!result || typeof result !== 'object') return;
+  if (result.kind === 'distill') {
+    const stageCount = Array.isArray(result.stageResults) ? result.stageResults.length : 0;
+    console.log(
+      `[metrics] kind=distill action=${result.action || 'run'} stages=${stageCount} runRoot=${quoteOneLine(result.runRoot)}`
+    );
+    return;
+  }
+  if (result.kind === 'lora') {
+    const exportCount = Array.isArray(result.exports) ? result.exports.length : 0;
+    console.log(
+      `[metrics] kind=lora action=${result.action || 'run'} exports=${exportCount} runRoot=${quoteOneLine(result.runRoot)}`
+    );
+    return;
+  }
   const suite = String(result.suite || '');
   const metrics = result.metrics;
   if (!metrics || typeof metrics !== 'object') return;
@@ -1307,7 +1423,7 @@ async function main() {
     printMetricsSummary(response.result);
   } catch (error) {
     if (jsonOutputRequested) {
-      console.log(JSON.stringify(createToolingErrorEnvelope(error, errorContext), null, 2));
+      console.log(JSON.stringify(createCliToolingErrorEnvelope(error, errorContext), null, 2));
       process.exitCode = 1;
       return;
     }