@reicek/neataptic-ts 0.1.25 → 0.1.26

package/scripts/export-onnx.ts

@@ -0,0 +1,223 @@
+/**
+ * Minimal CLI to export a JSON ONNX model from a serialized network state.
+ *
+ * Usage:
+ *   npm run onnx:export -- --in network.json --out model.onnx.json [--metadata] [--batch] [--legacy] [--partial] [--mixed]
+ *
+ * This stays intentionally lightweight. For larger automation flows, prefer
+ * calling the ONNX export API directly from application code.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const PRIMARY_ONNX_MODULE_PATH = path.resolve(
+  'dist',
+  'architecture',
+  'onnx.js',
+);
+const FALLBACK_ONNX_MODULE_PATH = path.resolve(
+  'dist',
+  'architecture',
+  'network',
+  'network.onnx.js',
+);
+const NETWORK_MODULE_PATH = path.resolve('dist', 'architecture', 'network.js');
+
+interface ExportOnnxOptions {
+  includeMetadata: boolean;
+  batchDimension: boolean;
+  legacyNodeOrdering: boolean;
+  allowPartialConnectivity: boolean;
+  allowMixedActivations: boolean;
+}
+
+interface NetworkLike {
+  toJSON?: () => unknown;
+}
+
+interface NetworkFactory<TNetwork extends NetworkLike> {
+  fromJSON(raw: unknown): TNetwork;
+}
+
+interface OnnxExportModule<TNetwork extends NetworkLike> {
+  exportToONNX: (network: TNetwork, options: ExportOnnxOptions) => unknown;
+}
+
+interface DistDependencies<TNetwork extends NetworkLike> {
+  Network: NetworkFactory<TNetwork>;
+  exportToONNX: OnnxExportModule<TNetwork>['exportToONNX'];
+}
+
+interface ParsedCliOptions extends ExportOnnxOptions {
+  inputFile: string;
+  outputFile: string;
+}
+
+/**
+ * Runs the ONNX export CLI.
+ *
+ * @returns Promise resolved when export succeeds.
+ */
+async function main(): Promise<void> {
+  const rawArguments = process.argv.slice(2);
+  if (hasFlag(rawArguments, '--help') || hasFlag(rawArguments, '-h')) {
+    printUsage();
+    return;
+  }
+
+  const cliOptions = parseCliOptions(rawArguments);
+  const { Network, exportToONNX } = await loadDistDependencies<NetworkLike>();
+  const networkJson = readJsonFile(cliOptions.inputFile);
+  const network = Network.fromJSON(networkJson);
+  const onnxJson = exportToONNX(network, cliOptions);
+
+  fs.writeFileSync(
+    path.resolve(cliOptions.outputFile),
+    `${JSON.stringify(onnxJson, null, 2)}\n`,
+    'utf8',
+  );
+  console.log(`ONNX JSON written to ${cliOptions.outputFile}`);
+}
+
+/**
+ * Parses CLI options from raw process arguments.
+ *
+ * @param rawArguments - CLI arguments after the script path.
+ * @returns Parsed and validated CLI options.
+ */
+function parseCliOptions(rawArguments: readonly string[]): ParsedCliOptions {
+  const inputFile = resolveOptionValue(rawArguments, '--in');
+  const outputFile = resolveOptionValue(rawArguments, '--out');
+
+  if (!inputFile || !outputFile) {
+    printUsageAndExit('Error: --in and --out are required.');
+  }
+
+  return {
+    inputFile,
+    outputFile,
+    includeMetadata: hasFlag(rawArguments, '--metadata'),
+    batchDimension: hasFlag(rawArguments, '--batch'),
+    legacyNodeOrdering: hasFlag(rawArguments, '--legacy'),
+    allowPartialConnectivity: hasFlag(rawArguments, '--partial'),
+    allowMixedActivations: hasFlag(rawArguments, '--mixed'),
+  };
+}
+
+/**
+ * Resolves one option value from `--name value` or `--name=value` syntax.
+ *
+ * @param rawArguments - CLI arguments after the script path.
+ * @param optionName - Long option name including leading dashes.
+ * @returns Option value when present.
+ */
+function resolveOptionValue(
+  rawArguments: readonly string[],
+  optionName: string,
+): string | undefined {
+  const exactIndex = rawArguments.indexOf(optionName);
+  if (exactIndex >= 0) {
+    return rawArguments[exactIndex + 1];
+  }
+
+  const inlineArgument = rawArguments.find((argument) =>
+    argument.startsWith(`${optionName}=`),
+  );
+  return inlineArgument?.slice(optionName.length + 1);
+}
+
+/**
+ * Checks whether a boolean flag is present.
+ *
+ * @param rawArguments - CLI arguments after the script path.
+ * @param optionName - Flag name including leading dashes.
+ * @returns `true` when the flag is present.
+ */
+function hasFlag(rawArguments: readonly string[], optionName: string): boolean {
+  return rawArguments.includes(optionName);
+}
+
+/**
+ * Loads the built network and ONNX export modules from `dist/`.
+ *
+ * @returns The built network constructor and ONNX export function.
+ */
+async function loadDistDependencies<TNetwork extends NetworkLike>(): Promise<
+  DistDependencies<TNetwork>
+> {
+  const onnxModule = (await importModuleWithFallback<
+    Partial<OnnxExportModule<TNetwork>>
+  >(PRIMARY_ONNX_MODULE_PATH, FALLBACK_ONNX_MODULE_PATH)) as Partial<
+    OnnxExportModule<TNetwork>
+  >;
+  const networkModule = (await import(
+    pathToFileURL(NETWORK_MODULE_PATH).href
+  )) as { default?: NetworkFactory<TNetwork> };
+
+  if (!networkModule.default || typeof onnxModule.exportToONNX !== 'function') {
+    throw new Error(
+      'Failed to load built ONNX export dependencies from dist/.',
+    );
+  }
+
+  return {
+    Network: networkModule.default,
+    exportToONNX: onnxModule.exportToONNX,
+  };
+}
+
+/**
+ * Imports the primary built module, falling back to a secondary path when the
+ * public layout has shifted.
+ *
+ * @param primaryModulePath - Preferred built module path.
+ * @param fallbackModulePath - Fallback built module path.
+ * @returns Imported module namespace.
+ */
+async function importModuleWithFallback<TModule>(
+  primaryModulePath: string,
+  fallbackModulePath: string,
+): Promise<TModule> {
+  try {
+    return (await import(pathToFileURL(primaryModulePath).href)) as TModule;
+  } catch {
+    return (await import(pathToFileURL(fallbackModulePath).href)) as TModule;
+  }
+}
+
+/**
+ * Reads and parses one JSON file.
+ *
+ * @param filePath - Source JSON file path.
+ * @returns Parsed JSON value.
+ */
+function readJsonFile(filePath: string): unknown {
+  return JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8')) as unknown;
+}
+
+/** Prints CLI usage text. */
+function printUsage(): void {
+  console.log(
+    'Usage: npm run onnx:export -- --in network.json --out model.onnx.json [--metadata] [--batch] [--legacy] [--partial] [--mixed]',
+  );
+}
+
+/**
+ * Prints CLI usage text and exits the process with failure.
+ *
+ * @param message - Error message shown before usage text.
+ * @returns Never returns.
+ */
+function printUsageAndExit(message: string): never {
+  console.error(message);
+  printUsage();
+  process.exit(1);
+}
+
+main().catch((error: unknown) => {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  console.error('Export failed:', errorMessage);
+  process.exit(1);
+});

package/scripts/generate-bench-tables.ts

@@ -14,46 +14,336 @@
  *  - Gracefully degrades when fields missing (older artifact schema).
  *  - Extend later for variance/regression annotation summaries.
  */
-import fs from 'fs';
-import path from 'path';
+import fs from 'node:fs';
+import path from 'node:path';
 
+/** Canonical benchmark artifact consumed by the table generator. */
+const BENCHMARK_ARTIFACT_PATH = path.resolve(
+  'test/benchmarks/benchmark.results.json',
+);
+
+/** Metrics shown in the variant delta table. */
+const DELTA_METRICS = ['buildMs', 'fwdAvgMs', 'bytesPerConn'] as const;
+
+/** Metrics shown in the heap and resident-set table. */
+const HEAP_METRICS = ['heapUsed', 'rss'] as const;
+
+/** Full metric set recognized across both current and legacy artifact schemas. */
+const AGGREGATED_METRICS = [...DELTA_METRICS, ...HEAP_METRICS] as const;
+
+/** Benchmark variant identifiers emitted by the build-variant suite. */
+type BenchmarkMode = 'src' | 'dist';
+
+/** Metric names that participate in src-vs-dist regression comparison. */
+type DeltaMetricName = (typeof DELTA_METRICS)[number];
+
+/** Metric names that participate in the heap summary table. */
+type HeapMetricName = (typeof HEAP_METRICS)[number];
+
+/** All metric names recognized by the script. */
+type BenchmarkMetricName = (typeof AGGREGATED_METRICS)[number];
+
+/** Legacy flat-artifact key names such as `buildMsMean`. */
+type LegacyMeanMetricKey = `${BenchmarkMetricName}Mean`;
+
+/**
+ * Aggregate statistics for one benchmark metric.
+ *
+ * The current table generator only consumes `mean`, but the wider schema can
+ * also carry percentile and spread values that may be used by later reports.
+ */
 interface AggregatedMetric {
-  mean: number;
-  p50: number;
-  p95: number;
-  std: number;
+  mean?: number;
+  p50?: number;
+  p95?: number;
+  std?: number;
 }
 
-/** Pad / truncate value to fixed width for monospace block. */
-function cell(v: any, w: number): string {
+/**
+ * Scenario-level metrics under one size bucket.
+ *
+ * The script currently reads the `all` scenario, but the normalized shape keeps
+ * the scenario layer so future reporting can distinguish specialized runs.
+ */
+type AggregatedScenarioBucket = Partial<
+  Record<BenchmarkMetricName, AggregatedMetric>
+>;
+
+/**
+ * Size bucket keyed by scenario name.
+ *
+ * Example: `1024 -> all -> buildMs -> { mean: ... }`.
+ */
+type AggregatedSizeBucket = Record<
+  string,
+  AggregatedScenarioBucket | undefined
+> & {
+  all?: AggregatedScenarioBucket;
+};
+
+/** Aggregated metrics keyed by benchmark size. */
+type AggregatedModeBucket = Record<string, AggregatedSizeBucket>;
+
+/** Fully normalized aggregated results keyed by build variant. */
+interface NormalizedAggregatedResults {
+  src: AggregatedModeBucket;
+  dist: AggregatedModeBucket;
+}
+
+/** Minimal artifact contract needed by this script. */
+interface BenchmarkArtifact {
+  aggregated?: unknown;
+}
+
+/**
+ * Legacy array-based aggregated entry shape.
+ *
+ * Older benchmark artifacts stored one flat record per `(mode, size)` pair
+ * using `fooMean` properties instead of the nested scenario bucket structure.
+ */
+interface LegacyAggregatedEntry extends Partial<
+  Record<LegacyMeanMetricKey, number>
+> {
+  mode: BenchmarkMode;
+  size: number | string;
+}
+
+/**
+ * Pads or truncates a value to fixed width for the fenced monospace tables.
+ *
+ * @param v - Cell value to render.
+ * @param w - Target cell width.
+ * @returns Fixed-width cell content.
+ */
+function cell(v: string | number | undefined | null, w: number): string {
   const s = String(v ?? '');
   return s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length);
 }
 
-/** Format number with trimmed trailing zeros. */
-function fmtNum(n: any, digits = 4): string {
-  if (typeof n !== 'number' || !isFinite(n)) return '';
+/**
+ * Formats a numeric value with trimmed trailing zeros.
+ *
+ * This keeps markdown tables compact without losing the ability to request
+ * higher precision for smaller benchmark values.
+ *
+ * @param n - Candidate numeric value.
+ * @param digits - Maximum fixed decimal precision.
+ * @returns Formatted number or an empty string when the input is not finite.
+ */
+function fmtNum(n: number | undefined, digits = 4): string {
+  if (typeof n !== 'number' || !Number.isFinite(n)) return '';
   return n.toFixed(digits).replace(/0+$/, '').replace(/\.$/, '');
 }
 
-function loadArtifact(): any | null {
-  const file = path.resolve('test/benchmarks/benchmark.results.json');
-  if (!fs.existsSync(file)) {
-    console.error('[bench:tables] Artifact not found:', file);
+/**
+ * Loads the benchmark artifact from disk.
+ *
+ * @returns Parsed artifact when present and readable, otherwise `null`.
+ */
+function loadArtifact(): BenchmarkArtifact | null {
+  if (!fs.existsSync(BENCHMARK_ARTIFACT_PATH)) {
+    console.error(
+      '[bench:tables] Artifact not found:',
+      BENCHMARK_ARTIFACT_PATH,
+    );
     return null;
   }
+
   try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch (e) {
-    console.error('[bench:tables] Parse error', e);
+    return JSON.parse(
+      fs.readFileSync(BENCHMARK_ARTIFACT_PATH, 'utf8'),
+    ) as BenchmarkArtifact;
+  } catch (error) {
+    console.error('[bench:tables] Parse error', error);
     return null;
   }
 }
 
-function buildVariantDeltaTable(artifact: any): string {
-  const agg = artifact.aggregated || {};
-  const sizes = new Set<string>(Object.keys(agg.src || {}));
-  const ordered = Array.from(sizes).sort((a, b) => parseInt(a) - parseInt(b));
+/**
+ * Normalizes the artifact's aggregated payload into one stable nested shape.
+ *
+ * The benchmark pipeline has emitted both nested and legacy flat array schemas.
+ * Folding both into the same mode/size/scenario/metric structure keeps the
+ * table builders simple and resilient.
+ *
+ * @param artifact - Parsed benchmark artifact.
+ * @returns Normalized aggregated result buckets.
+ */
+function normalizeAggregated(
+  artifact: BenchmarkArtifact,
+): NormalizedAggregatedResults {
+  if (Array.isArray(artifact.aggregated)) {
+    return normalizeLegacyAggregated(artifact.aggregated);
+  }
+
+  if (!isRecord(artifact.aggregated)) {
+    return createEmptyAggregatedResults();
+  }
+
+  return {
+    src: normalizeModeBucket(artifact.aggregated.src),
+    dist: normalizeModeBucket(artifact.aggregated.dist),
+  };
+}
+
+/**
+ * Converts the older flat array schema into the normalized nested shape.
+ *
+ * @param rawEntries - Legacy aggregated entries.
+ * @returns Normalized aggregated result buckets.
+ */
+function normalizeLegacyAggregated(
+  rawEntries: readonly unknown[],
+): NormalizedAggregatedResults {
+  const aggregatedResults = createEmptyAggregatedResults();
+
+  for (const rawEntry of rawEntries) {
+    if (!isLegacyAggregatedEntry(rawEntry)) {
+      continue;
+    }
+
+    const sizeKey = String(rawEntry.size);
+    const scenarioBucket = ensureAllScenarioBucket(
+      aggregatedResults[rawEntry.mode],
+      sizeKey,
+    );
+
+    for (const metricName of AGGREGATED_METRICS) {
+      const meanKey = `${metricName}Mean` as const;
+      const meanValue = rawEntry[meanKey];
+      if (typeof meanValue === 'number' && Number.isFinite(meanValue)) {
+        scenarioBucket[metricName] = { mean: meanValue };
+      }
+    }
+  }
+
+  return aggregatedResults;
+}
+
+/**
+ * Normalizes one top-level mode bucket such as `src` or `dist`.
+ *
+ * @param rawModeBucket - Unknown raw mode payload.
+ * @returns Normalized size buckets.
+ */
+function normalizeModeBucket(rawModeBucket: unknown): AggregatedModeBucket {
+  if (!isRecord(rawModeBucket)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(rawModeBucket).map(([sizeKey, rawSizeBucket]) => [
+      sizeKey,
+      normalizeSizeBucket(rawSizeBucket),
+    ]),
+  );
+}
+
+/**
+ * Normalizes one size bucket keyed by scenario names.
+ *
+ * @param rawSizeBucket - Unknown raw size payload.
+ * @returns Normalized scenario buckets.
+ */
+function normalizeSizeBucket(rawSizeBucket: unknown): AggregatedSizeBucket {
+  if (!isRecord(rawSizeBucket)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(rawSizeBucket).map(([scenarioName, rawScenarioBucket]) => [
+      scenarioName,
+      normalizeScenarioBucket(rawScenarioBucket),
+    ]),
+  ) as AggregatedSizeBucket;
+}
+
+/**
+ * Normalizes one scenario bucket keyed by metric name.
+ *
+ * Invalid or incomplete metric objects are dropped rather than guessed.
+ *
+ * @param rawScenarioBucket - Unknown raw scenario payload.
+ * @returns Normalized metric bucket.
+ */
+function normalizeScenarioBucket(
+  rawScenarioBucket: unknown,
+): AggregatedScenarioBucket {
+  if (!isRecord(rawScenarioBucket)) {
+    return {};
+  }
+
+  const normalizedEntries = AGGREGATED_METRICS.flatMap((metricName) => {
+    const rawMetric = rawScenarioBucket[metricName];
+    if (!isRecord(rawMetric)) {
+      return [];
+    }
+
+    const meanValue = rawMetric.mean;
+    if (typeof meanValue !== 'number' || !Number.isFinite(meanValue)) {
+      return [];
+    }
+
+    return [[metricName, { mean: meanValue }] as const];
+  });
+
+  return Object.fromEntries(normalizedEntries) as AggregatedScenarioBucket;
+}
+
+/**
+ * Ensures the `all` scenario exists for one `(mode, size)` pair.
+ *
+ * @param modeBucket - Normalized mode bucket.
+ * @param sizeKey - Size identifier.
+ * @returns Mutable `all` scenario bucket.
+ */
+function ensureAllScenarioBucket(
+  modeBucket: AggregatedModeBucket,
+  sizeKey: string,
+): AggregatedScenarioBucket {
+  modeBucket[sizeKey] ??= {};
+  modeBucket[sizeKey].all ??= {};
+  return modeBucket[sizeKey].all!;
+}
+
+/**
+ * Creates an empty normalized results shell.
+ *
+ * @returns Empty `src` and `dist` mode buckets.
+ */
+function createEmptyAggregatedResults(): NormalizedAggregatedResults {
+  return {
+    src: {},
+    dist: {},
+  };
+}
+
+/**
+ * Resolves size keys in ascending numeric order.
+ *
+ * @param aggregatedResults - Normalized aggregated result buckets.
+ * @returns Ordered size keys.
+ */
+function resolveOrderedSizes(
+  aggregatedResults: NormalizedAggregatedResults,
+): string[] {
+  return [...new Set(Object.keys(aggregatedResults.src))].toSorted(
+    compareNumericSizeKeys,
+  );
+}
+
+/**
+ * Builds the variant delta table comparing `src` and `dist` means.
+ *
+ * The result is tuned for markdown fenced blocks rather than GFM pipe tables,
+ * which keeps wide benchmark rows easier to scan in docs and pull requests.
+ *
+ * @param artifact - Parsed benchmark artifact.
+ * @returns Monospace markdown table body.
+ */
+function buildVariantDeltaTable(artifact: BenchmarkArtifact): string {
+  const aggregatedResults = normalizeAggregated(artifact);
+  const orderedSizes = resolveOrderedSizes(aggregatedResults);
   const rows: string[] = [];
   rows.push(
     'Size    Metric            Src Mean      Dist Mean     Δ Abs         Δ %        Flag          Result',
@@ -61,13 +351,10 @@ function buildVariantDeltaTable(artifact: any): string {
   rows.push(
     '------  ----------------- ------------- ------------- ------------- ---------- ------------- ------------------------------------------------------------',
   );
-  const metrics = ['buildMs', 'fwdAvgMs', 'bytesPerConn'];
-  for (const size of ordered) {
-    for (const metric of metrics) {
-      const srcAgg: AggregatedMetric | undefined =
-        agg.src?.[size]?.all?.[metric];
-      const distAgg: AggregatedMetric | undefined =
-        agg.dist?.[size]?.all?.[metric];
+  for (const size of orderedSizes) {
+    for (const metric of DELTA_METRICS) {
+      const srcAgg = aggregatedResults.src[size]?.all?.[metric];
+      const distAgg = aggregatedResults.dist[size]?.all?.[metric];
       const sMean = srcAgg?.mean;
       const dMean = distAgg?.mean;
       let dAbs: number | undefined;
@@ -123,10 +410,15 @@ function buildVariantDeltaTable(artifact: any): string {
   return rows.join('\n');
 }
 
-function buildHeapTable(artifact: any): string {
-  const agg = artifact.aggregated || {};
-  const sizes = new Set<string>(Object.keys(agg.src || {}));
-  const ordered = Array.from(sizes).sort((a, b) => parseInt(a) - parseInt(b));
+/**
+ * Builds the heap and RSS comparison table.
+ *
+ * @param artifact - Parsed benchmark artifact.
+ * @returns Monospace markdown table body.
+ */
+function buildHeapTable(artifact: BenchmarkArtifact): string {
+  const aggregatedResults = normalizeAggregated(artifact);
+  const orderedSizes = resolveOrderedSizes(aggregatedResults);
   const rows: string[] = [];
   rows.push(
     'Size    Metric         Src Bytes    Dist Bytes    Src MB    Dist MB   Δ Bytes      Δ %     Note',
@@ -134,10 +426,10 @@ function buildHeapTable(artifact: any): string {
   rows.push(
     '------  -------------- ------------ ------------ --------- --------- ----------- ------- -------------------------------------------------',
   );
-  for (const size of ordered) {
-    for (const metric of ['heapUsed', 'rss']) {
-      const s = agg.src?.[size]?.all?.[metric]?.mean;
-      const d = agg.dist?.[size]?.all?.[metric]?.mean;
+  for (const size of orderedSizes) {
+    for (const metric of HEAP_METRICS) {
+      const s = aggregatedResults.src[size]?.all?.[metric]?.mean;
+      const d = aggregatedResults.dist[size]?.all?.[metric]?.mean;
       if (typeof s !== 'number' || typeof d !== 'number') continue;
       const dBytes = d - s;
       const dPct = s === 0 ? 0 : (dBytes / s) * 100;
@@ -165,6 +457,55 @@ function buildHeapTable(artifact: any): string {
   return rows.join('\n');
 }
 
+/**
+ * Compares size keys numerically, falling back to lexical comparison.
+ *
+ * @param left - Left size key.
+ * @param right - Right size key.
+ * @returns Standard comparator delta.
+ */
+function compareNumericSizeKeys(left: string, right: string): number {
+  const leftValue = Number.parseInt(left, 10);
+  const rightValue = Number.parseInt(right, 10);
+
+  if (Number.isNaN(leftValue) || Number.isNaN(rightValue)) {
+    return left.localeCompare(right);
+  }
+
+  return leftValue - rightValue || left.localeCompare(right);
+}
+
+/**
+ * Narrows an unknown value to the legacy flat aggregated entry shape.
+ *
+ * @param value - Candidate legacy entry.
+ * @returns `true` when the value matches the legacy schema.
+ */
+function isLegacyAggregatedEntry(
+  value: unknown,
+): value is LegacyAggregatedEntry {
+  return (
+    isRecord(value) &&
+    (value.mode === 'src' || value.mode === 'dist') &&
+    (typeof value.size === 'number' || typeof value.size === 'string')
+  );
+}
+
+/**
+ * Narrows an unknown value to a plain object record.
+ *
+ * @param value - Candidate value.
+ * @returns `true` when the value is a non-array object.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Runs the artifact load and emits both markdown tables to standard output.
+ *
+ * @returns Nothing.
+ */
 function main() {
   const artifact = loadArtifact();
   if (!artifact) process.exit(1);