@kaminos/webgpu-inference-kit 0.1.0

package/src/sharp-route.js

@@ -0,0 +1,87 @@
+import { defineWebGpuRoute } from './route-boundary.js';
+import {
+  createKernelProfileMetadata,
+  createRouteKernelProfileMetadata,
+} from './kernel-profile.js';
+import {
+  createRouteReceiptArtifacts,
+  createRouteReceiptInputArtifact,
+  createWebGpuRouteReceiptFromArtifacts,
+} from './route-receipt-helper.js';
+
+export const SHARP_IMAGE_TO_SPLAT_ROUTE_ID = 'sharp.image-to-splat.webgpu-local.v0';
+const SHARP_MODEL_ID = 'apple/ml-sharp';
+const DEFAULT_KERNEL_PROFILE = 'spn-dinov2l16-monodepth-gaussian-ply';
+const REQUIRED_STAGES = ['spn', 'monodepth', 'gaussian-decoder', 'compose-ply', 'output-capture'];
+const OUTPUT_ROLES = [
+  { key: 'splat', role: 'splat-candidate', required: true },
+  { key: 'depthMap', role: 'depth-map', required: true },
+  { key: 'metadata', role: 'sharp-webgpu-metadata', required: true },
+  { key: 'autoCropEvidence', role: 'splat-autocrop-evidence', required: false },
+];
+
+export function createSharpImageToSplatRouteReceipt(input) {
+  if (!input || typeof input !== 'object') throw new Error('input must be an object');
+  if (!input.input?.artifactId || !input.input?.sha256) {
+    throw new Error('input image artifactId and sha256 are required');
+  }
+  if (!input.outputs?.splat) throw new Error('splat output is required');
+  if (!input.outputs?.depthMap) throw new Error('depthMap output is required');
+  if (!input.outputs?.metadata) throw new Error('metadata output is required');
+
+  return createWebGpuRouteReceiptFromArtifacts({
+    requestedRouteId: SHARP_IMAGE_TO_SPLAT_ROUTE_ID,
+    effectiveRouteId: input.effectiveRouteId || SHARP_IMAGE_TO_SPLAT_ROUTE_ID,
+    status: input.status || (input.fallbackReason ? 'fallback' : 'real'),
+    fallbackReason: input.fallbackReason || null,
+    backend: input.backend,
+    model: {
+      id: SHARP_MODEL_ID,
+      revision: input.model?.revision,
+      weightsHash: input.model?.weightsHash,
+      dtype: input.model?.dtype || 'fp16',
+    },
+    kernel: createKernelProfileMetadata(input.kernel, { requireProfile: true }),
+    inputs: [
+      createRouteReceiptInputArtifact('source-image', input.input),
+    ],
+    outputs: createRouteReceiptArtifacts({ artifacts: input.outputs, roles: OUTPUT_ROLES }),
+    profile: input.profile,
+  });
+}
+
+export function createSharpImageToSplatRouteDefinition(input = {}) {
+  const routeMetadata = createRouteKernelProfileMetadata(input, {
+    defaultProfile: DEFAULT_KERNEL_PROFILE,
+    requiredStages: REQUIRED_STAGES,
+    timingSource: 'adapter-phase-wall-clock',
+  });
+
+  return defineWebGpuRoute({
+    routeId: SHARP_IMAGE_TO_SPLAT_ROUTE_ID,
+    backendKind: 'webgpu-local',
+    model: {
+      id: SHARP_MODEL_ID,
+      revision: input.model?.revision || 'local-sharp-webgpu',
+      dtype: input.model?.dtype || 'fp16',
+    },
+    kernel: routeMetadata.kernel,
+    inputs: [
+      { role: 'source-image', required: true, artifactRequired: true, hashRequired: true },
+    ],
+    outputs: [
+      { role: 'splat-candidate', required: true, artifactRequired: true, hashRequired: true, shape: [1179648, 14] },
+      { role: 'depth-map', required: true, artifactRequired: true, hashRequired: true, shape: [768, 768, 4] },
+      { role: 'sharp-webgpu-metadata', required: true, artifactRequired: true, hashRequired: true, shape: [1] },
+      { role: 'splat-autocrop-evidence', required: false, artifactRequired: true, hashRequired: true, shape: [1] },
+    ],
+    requiredFeatures: input.requiredFeatures || [],
+    requiredStages: routeMetadata.requiredStages,
+    timingSource: routeMetadata.timingSource,
+    worker: input.worker || {
+      exportName: 'runSharpImageToSplatRoute',
+      adapterReportSchema: 'kaminos.sharp-webgpu-adapter-report.v0',
+      pipelineRouteId: 'adapter.sharp-image-to-splat-live.v0',
+    },
+  });
+}

package/src/staged-profile.js

@@ -0,0 +1,87 @@
+const PROFILE_SCHEMA = 'kaminos.webgpu-staged-profile.v0';
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function roundMs(value) {
+  return Math.round(value * 10) / 10;
+}
+
+export function createStagedSubmitProfile(input = {}) {
+  return {
+    schema: PROFILE_SCHEMA,
+    route: input.route || 'staged-submits',
+    timingSource: input.timingSource || 'queue-submit-wait',
+    timestampQueryValidatedAgainstStaged: !!input.timestampQueryValidatedAgainstStaged,
+    requiredStages: Array.isArray(input.requiredStages) ? [...input.requiredStages] : [],
+    stages: [],
+  };
+}
+
+export function addStagedSubmitStage(profile, stage) {
+  if (!profile || typeof profile !== 'object') throw new Error('profile must be an object');
+  if (!isNonEmptyString(stage?.name)) throw new Error('stage.name must be a non-empty string');
+  if (!Number.isFinite(stage.ms) || stage.ms < 0) throw new Error('stage.ms must be a finite non-negative number');
+  if (!Array.isArray(profile.stages)) profile.stages = [];
+
+  profile.stages.push({
+    name: stage.name,
+    ms: roundMs(stage.ms),
+    shape: Array.isArray(stage.shape) ? [...stage.shape] : undefined,
+    metadata: stage.metadata ? JSON.parse(JSON.stringify(stage.metadata)) : undefined,
+  });
+  return profile;
+}
+
+export function finishStagedSubmitProfile(profile) {
+  if (!profile || typeof profile !== 'object') throw new Error('profile must be an object');
+  const stages = Array.isArray(profile.stages) ? profile.stages : [];
+  const totalMs = roundMs(stages.reduce((sum, stage) => sum + (Number.isFinite(stage.ms) ? stage.ms : 0), 0));
+
+  return {
+    ...profile,
+    schema: profile.schema || PROFILE_SCHEMA,
+    stages,
+    stageNames: stages.map(stage => stage.name),
+    totalMs,
+  };
+}
+
+export function validateStagedSubmitProfile(profile) {
+  const errors = [];
+
+  if (!profile || typeof profile !== 'object') {
+    return { ok: false, errors: ['profile must be an object'] };
+  }
+  if (profile.schema !== PROFILE_SCHEMA) errors.push(`schema must be ${PROFILE_SCHEMA}`);
+  if (!isNonEmptyString(profile.route)) errors.push('route must be a non-empty string');
+  if (!isNonEmptyString(profile.timingSource)) errors.push('timingSource must be a non-empty string');
+  if (!Array.isArray(profile.stages) || profile.stages.length === 0) {
+    errors.push('stages must be a non-empty array');
+  }
+  if (!Number.isFinite(profile.totalMs) || profile.totalMs < 0) {
+    errors.push('totalMs must be a finite non-negative number');
+  }
+
+  const stageNames = new Set();
+  if (Array.isArray(profile.stages)) {
+    profile.stages.forEach((stage, index) => {
+      if (!isNonEmptyString(stage.name)) errors.push(`stages[${index}].name must be a non-empty string`);
+      if (!Number.isFinite(stage.ms) || stage.ms < 0) errors.push(`stages[${index}].ms must be a finite non-negative number`);
+      if (isNonEmptyString(stage.name)) stageNames.add(stage.name);
+    });
+  }
+
+  if (Array.isArray(profile.requiredStages)) {
+    for (const required of profile.requiredStages) {
+      if (!stageNames.has(required)) errors.push(`missing required stage ${required}`);
+    }
+  }
+
+  if (profile.timingSource === 'timestamp-query' && profile.timestampQueryValidatedAgainstStaged !== true) {
+    errors.push('timestamp-query profile must be validated against staged-submit timings');
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/src/tensor-manifest.js

@@ -0,0 +1,81 @@
+const MANIFEST_SCHEMA = 'kaminos.tensor-manifest.v0';
+
+const BYTES_PER_ELEMENT = new Map([
+  ['fp32', 4],
+  ['f32', 4],
+  ['fp16', 2],
+  ['f16', 2],
+  ['u32', 4],
+  ['i32', 4],
+  ['u8', 1],
+]);
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function tensorElements(shape) {
+  if (!Array.isArray(shape) || shape.length === 0 || !shape.every(Number.isInteger)) {
+    return null;
+  }
+  if (shape.some(dim => dim <= 0)) return null;
+  return shape.reduce((product, dim) => product * dim, 1);
+}
+
+export function defineTensorManifest(input) {
+  const tensors = (input.tensors || []).map(tensor => {
+    const elements = tensorElements(tensor.shape);
+    const bytesPerElement = BYTES_PER_ELEMENT.get(tensor.dtype) || null;
+    return {
+      ...tensor,
+      elements,
+      bytesPerElement,
+    };
+  });
+
+  return {
+    schema: MANIFEST_SCHEMA,
+    modelId: input.modelId,
+    revision: input.revision,
+    weightFormat: input.weightFormat || MANIFEST_SCHEMA,
+    tensors,
+  };
+}
+
+export function validateTensorManifest(manifest) {
+  const errors = [];
+
+  if (!manifest || typeof manifest !== 'object') {
+    return { ok: false, errors: ['manifest must be an object'] };
+  }
+
+  if (manifest.schema !== MANIFEST_SCHEMA) {
+    errors.push(`schema must be ${MANIFEST_SCHEMA}`);
+  }
+  if (!isNonEmptyString(manifest.modelId)) errors.push('modelId must be a non-empty string');
+  if (!isNonEmptyString(manifest.revision)) errors.push('revision must be a non-empty string');
+  if (!Array.isArray(manifest.tensors) || manifest.tensors.length === 0) {
+    errors.push('tensors must be a non-empty array');
+  }
+
+  if (Array.isArray(manifest.tensors)) {
+    manifest.tensors.forEach((tensor, index) => {
+      if (!isNonEmptyString(tensor.name)) errors.push(`tensors[${index}].name must be a non-empty string`);
+      if (!BYTES_PER_ELEMENT.has(tensor.dtype)) errors.push(`tensors[${index}] unsupported dtype ${tensor.dtype}`);
+      const elements = tensorElements(tensor.shape);
+      if (elements == null) errors.push(`tensors[${index}].shape must contain positive integer dimensions`);
+      if (!Number.isInteger(tensor.byteOffset) || tensor.byteOffset < 0) {
+        errors.push(`tensors[${index}].byteOffset must be a non-negative integer`);
+      }
+      if (!Number.isInteger(tensor.byteLength) || tensor.byteLength < 0) {
+        errors.push(`tensors[${index}].byteLength must be a non-negative integer`);
+      }
+      const bytesPerElement = BYTES_PER_ELEMENT.get(tensor.dtype);
+      if (elements != null && bytesPerElement != null && tensor.byteLength !== elements * bytesPerElement) {
+        errors.push(`tensors[${index}].byteLength must equal shape elements * dtype size`);
+      }
+    });
+  }
+
+  return { ok: errors.length === 0, errors };
+}