@simulatte/doppler 0.1.9 → 0.2.0

package/src/adapters/adapter-manifest.d.ts

@@ -1,290 +0,0 @@
-/**
- * Adapter Manifest Format Definition
- *
- * Defines the JSON schema and TypeScript types for adapter manifests.
- * This enables self-describing adapters with versioning, checksum validation,
- * and compatibility checking.
- *
- * @module adapters/adapter-manifest
- */
-
-import type { LoRAModuleName } from '../inference/pipelines/text/lora-types.js';
-
-export declare const DEFAULT_ADAPTER_MANIFEST_DEFAULTS: {
-  readonly version: '1.0.0';
-  readonly checksumAlgorithm: 'sha256';
-  readonly weightsFormat: 'safetensors';
-  readonly tensorDtype: 'f32';
-};
-
-/**
- * JSON Schema for adapter manifests.
- * Can be used with JSON Schema validators like Ajv.
- */
-export declare const ADAPTER_MANIFEST_SCHEMA: {
-  readonly $schema: 'http://json-schema.org/draft-07/schema#';
-  readonly $id: 'https://doppler.dev/schemas/adapter-manifest.json';
-  readonly title: 'Adapter Manifest';
-  readonly description: 'Schema for LoRA adapter manifests in Doppler';
-  readonly type: 'object';
-  readonly required: readonly ['id', 'name', 'baseModel', 'rank', 'alpha', 'targetModules'];
-  readonly properties: {
-    readonly id: {
-      readonly type: 'string';
-      readonly description: 'Unique identifier for the adapter (UUID or slug)';
-      readonly pattern: '^[a-zA-Z0-9_-]+$';
-    };
-    readonly name: {
-      readonly type: 'string';
-      readonly description: 'Human-readable name for the adapter';
-      readonly minLength: 1;
-      readonly maxLength: 256;
-    };
-    readonly version: {
-      readonly type: 'string';
-      readonly description: 'Semantic version of the adapter';
-      readonly pattern: '^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?$';
-      readonly default: '1.0.0';
-    };
-    readonly description: {
-      readonly type: 'string';
-      readonly description: 'Detailed description of the adapter purpose';
-      readonly maxLength: 4096;
-    };
-    readonly baseModel: {
-      readonly type: 'string';
-      readonly description: 'Identifier of the base model this adapter is trained for';
-      readonly examples: readonly ['gemma-3-1b', 'llama-3-8b'];
-    };
-    readonly rank: {
-      readonly type: 'integer';
-      readonly description: 'LoRA rank (dimensionality of the low-rank matrices)';
-      readonly minimum: 1;
-      readonly maximum: 1024;
-    };
-    readonly alpha: {
-      readonly type: 'number';
-      readonly description: 'LoRA alpha scaling factor';
-      readonly minimum: 0.1;
-    };
-    readonly targetModules: {
-      readonly type: 'array';
-      readonly description: 'List of modules this adapter modifies';
-      readonly items: {
-        readonly type: 'string';
-        readonly enum: readonly ['q_proj', 'k_proj', 'v_proj', 'o_proj', 'gate_proj', 'up_proj', 'down_proj', 'gate_up_proj'];
-      };
-      readonly minItems: 1;
-      readonly uniqueItems: true;
-    };
-    readonly checksum: {
-      readonly type: 'string';
-      readonly description: 'SHA-256 or BLAKE3 hash of the weight file for integrity verification';
-      readonly pattern: '^[a-fA-F0-9]{64}$';
-    };
-    readonly checksumAlgorithm: {
-      readonly type: 'string';
-      readonly description: 'Algorithm used for checksum';
-      readonly enum: readonly ['sha256', 'blake3'];
-      readonly default: 'sha256';
-    };
-    readonly weightsFormat: {
-      readonly type: 'string';
-      readonly description: 'Format of the weight tensors';
-      readonly enum: readonly ['safetensors', 'npz', 'json', 'binary'];
-      readonly default: 'safetensors';
-    };
-    readonly weightsPath: {
-      readonly type: 'string';
-      readonly description: 'Path or URL to the weights file (relative to manifest)';
-    };
-    readonly weightsSize: {
-      readonly type: 'integer';
-      readonly description: 'Size of the weights file in bytes';
-      readonly minimum: 0;
-    };
-    readonly tensors: {
-      readonly type: 'array';
-      readonly description: 'Inline tensor specifications (for small adapters)';
-      readonly items: {
-        readonly type: 'object';
-        readonly required: readonly ['name', 'shape'];
-        readonly properties: {
-          readonly name: { readonly type: 'string' };
-          readonly shape: {
-            readonly type: 'array';
-            readonly items: { readonly type: 'integer' };
-            readonly minItems: 2;
-            readonly maxItems: 2;
-          };
-          readonly dtype: {
-            readonly type: 'string';
-            readonly enum: readonly ['f32', 'f16', 'bf16'];
-            readonly default: 'f32';
-          };
-          readonly data: {
-            readonly type: 'array';
-            readonly items: { readonly type: 'number' };
-          };
-          readonly base64: { readonly type: 'string' };
-          readonly opfsPath: { readonly type: 'string' };
-          readonly url: { readonly type: 'string' };
-        };
-      };
-    };
-    readonly metadata: {
-      readonly type: 'object';
-      readonly description: 'Additional metadata about the adapter';
-      readonly properties: {
-        readonly author: { readonly type: 'string' };
-        readonly license: { readonly type: 'string' };
-        readonly tags: {
-          readonly type: 'array';
-          readonly items: { readonly type: 'string' };
-        };
-        readonly trainedOn: { readonly type: 'string' };
-        readonly epochs: { readonly type: 'number' };
-        readonly learningRate: { readonly type: 'number' };
-        readonly createdAt: { readonly type: 'string'; readonly format: 'date-time' };
-        readonly updatedAt: { readonly type: 'string'; readonly format: 'date-time' };
-      };
-      readonly additionalProperties: true;
-    };
-  };
-  readonly additionalProperties: false;
-};
-
-/**
- * Tensor specification for inline weight data.
- */
-export interface AdapterTensorSpec {
-  /** Tensor name following pattern: layer.{N}.{module}.lora_{a|b} */
-  name: string;
-  /** Shape as [rows, cols] */
-  shape: [number, number];
-  /** Data type (default: f32) */
-  dtype?: 'f32' | 'f16' | 'bf16';
-  /** Inline data as number array */
-  data?: number[];
-  /** Base64-encoded binary data */
-  base64?: string;
-  /** Path in OPFS storage */
-  opfsPath?: string;
-  /** URL to fetch tensor data from */
-  url?: string;
-}
-
-/**
- * Adapter metadata for tracking provenance.
- */
-export interface AdapterMetadata {
-  /** Author or organization */
-  author?: string;
-  /** License identifier (e.g., 'MIT', 'Apache-2.0') */
-  license?: string;
-  /** Tags for categorization */
-  tags?: string[];
-  /** Description of training data */
-  trainedOn?: string;
-  /** Number of training epochs */
-  epochs?: number;
-  /** Training learning rate */
-  learningRate?: number;
-  /** Creation timestamp (ISO 8601) */
-  createdAt?: string;
-  /** Last update timestamp (ISO 8601) */
-  updatedAt?: string;
-  /** Additional custom metadata */
-  [key: string]: unknown;
-}
-
-/**
- * Full adapter manifest structure.
- * This is the primary type for adapter definitions.
- */
-export interface AdapterManifest {
-  /** Unique identifier (UUID or slug) */
-  id: string;
-  /** Human-readable name */
-  name: string;
-  /** Semantic version (default: '1.0.0') */
-  version?: string;
-  /** Detailed description */
-  description?: string;
-  /** Base model identifier this adapter is compatible with */
-  baseModel: string;
-  /** LoRA rank (dimensionality) */
-  rank: number;
-  /** LoRA alpha scaling factor */
-  alpha: number;
-  /** List of modules this adapter modifies */
-  targetModules: LoRAModuleName[];
-  /** Content checksum for integrity verification */
-  checksum?: string;
-  /** Algorithm used for checksum */
-  checksumAlgorithm?: 'sha256' | 'blake3';
-  /** Format of weight tensors */
-  weightsFormat?: 'safetensors' | 'npz' | 'json' | 'binary';
-  /** Path or URL to weights file */
-  weightsPath?: string;
-  /** Size of weights file in bytes */
-  weightsSize?: number;
-  /** Inline tensor specifications */
-  tensors?: AdapterTensorSpec[];
-  /** Additional metadata */
-  metadata?: AdapterMetadata;
-}
-
-/**
- * Minimal adapter manifest with only required fields.
- */
-export type MinimalAdapterManifest = Pick<
-  AdapterManifest,
-  'id' | 'name' | 'baseModel' | 'rank' | 'alpha' | 'targetModules'
->;
-
-/**
- * Adapter manifest validation result.
- */
-export interface ManifestValidationResult {
-  valid: boolean;
-  errors: ManifestValidationError[];
-}
-
-/**
- * Validation error details.
- */
-export interface ManifestValidationError {
-  field: string;
-  message: string;
-  value?: unknown;
-}
-
-/**
- * Validates an adapter manifest against the schema.
- */
-export declare function validateManifest(manifest: unknown): ManifestValidationResult;
-
-export declare function applyAdapterManifestDefaults<T extends Record<string, unknown>>(manifest: T): T;
-
-/**
- * Parses and validates a manifest from JSON string.
- */
-export declare function parseManifest(json: string): AdapterManifest;
-
-/**
- * Serializes an adapter manifest to JSON string.
- */
-export declare function serializeManifest(manifest: AdapterManifest, pretty?: boolean): string;
-
-/**
- * Creates a minimal valid manifest with defaults.
- */
-export declare function createManifest(
-  options: MinimalAdapterManifest & Partial<AdapterManifest>
-): AdapterManifest;
-
-/**
- * Computes the expected scale factor from rank and alpha.
- */
-export declare function computeLoRAScale(rank: number, alpha: number): number;

package/src/adapters/adapter-manifest.js

@@ -1,320 +0,0 @@
-
-
-import {
-  VALID_LORA_TARGET_MODULES,
-  DEFAULT_ADAPTER_VALIDATION_CONFIG,
-} from '../config/schema/index.js';
-
-export const DEFAULT_ADAPTER_MANIFEST_DEFAULTS = {
-  version: '1.0.0',
-  checksumAlgorithm: 'sha256',
-  weightsFormat: 'safetensors',
-  tensorDtype: 'f32',
-};
-
-// ============================================================================
-// JSON Schema Definition (as TypeScript const for runtime validation)
-// ============================================================================
-
-
-export const ADAPTER_MANIFEST_SCHEMA = {
-  $schema: 'http://json-schema.org/draft-07/schema#',
-  $id: 'https://doppler.dev/schemas/adapter-manifest.json',
-  title: 'Adapter Manifest',
-  description: 'Schema for LoRA adapter manifests in Doppler',
-  type: 'object',
-  required: ['id', 'name', 'baseModel', 'rank', 'alpha', 'targetModules'],
-  properties: {
-    id: {
-      type: 'string',
-      description: 'Unique identifier for the adapter (UUID or slug)',
-      pattern: '^[a-zA-Z0-9_-]+$',
-    },
-    name: {
-      type: 'string',
-      description: 'Human-readable name for the adapter',
-      minLength: 1,
-      maxLength: DEFAULT_ADAPTER_VALIDATION_CONFIG.maxNameLength,
-    },
-    version: {
-      type: 'string',
-      description: 'Semantic version of the adapter',
-      pattern: '^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?$',
-      default: DEFAULT_ADAPTER_MANIFEST_DEFAULTS.version,
-    },
-    description: {
-      type: 'string',
-      description: 'Detailed description of the adapter purpose',
-      maxLength: DEFAULT_ADAPTER_VALIDATION_CONFIG.maxDescriptionLength,
-    },
-    baseModel: {
-      type: 'string',
-      description: 'Identifier of the base model this adapter is trained for',
-      examples: ['gemma-3-1b', 'llama-3-8b'],
-    },
-    rank: {
-      type: 'integer',
-      description: 'LoRA rank (dimensionality of the low-rank matrices)',
-      minimum: DEFAULT_ADAPTER_VALIDATION_CONFIG.minRank,
-      maximum: DEFAULT_ADAPTER_VALIDATION_CONFIG.maxRank,
-    },
-    alpha: {
-      type: 'number',
-      description: 'LoRA alpha scaling factor',
-      minimum: DEFAULT_ADAPTER_VALIDATION_CONFIG.minAlpha,
-    },
-    targetModules: {
-      type: 'array',
-      description: 'List of modules this adapter modifies',
-      items: {
-        type: 'string',
-        enum: VALID_LORA_TARGET_MODULES,
-      },
-      minItems: 1,
-      uniqueItems: true,
-    },
-    checksum: {
-      type: 'string',
-      description: 'SHA-256 or BLAKE3 hash of the weight file for integrity verification',
-      pattern: '^[a-fA-F0-9]{64}$',
-    },
-    checksumAlgorithm: {
-      type: 'string',
-      description: 'Algorithm used for checksum',
-      enum: ['sha256', 'blake3'],
-      default: DEFAULT_ADAPTER_MANIFEST_DEFAULTS.checksumAlgorithm,
-    },
-    weightsFormat: {
-      type: 'string',
-      description: 'Format of the weight tensors',
-      enum: ['safetensors', 'npz', 'json', 'binary'],
-      default: DEFAULT_ADAPTER_MANIFEST_DEFAULTS.weightsFormat,
-    },
-    weightsPath: {
-      type: 'string',
-      description: 'Path or URL to the weights file (relative to manifest)',
-    },
-    weightsSize: {
-      type: 'integer',
-      description: 'Size of the weights file in bytes',
-      minimum: 0,
-    },
-    tensors: {
-      type: 'array',
-      description: 'Inline tensor specifications (for small adapters)',
-      items: {
-        type: 'object',
-        required: ['name', 'shape'],
-        properties: {
-          name: { type: 'string' },
-          shape: {
-            type: 'array',
-            items: { type: 'integer' },
-            minItems: 2,
-            maxItems: 2,
-          },
-          dtype: {
-            type: 'string',
-            enum: ['f32', 'f16', 'bf16'],
-            default: DEFAULT_ADAPTER_MANIFEST_DEFAULTS.tensorDtype,
-          },
-          data: {
-            type: 'array',
-            items: { type: 'number' },
-          },
-          base64: { type: 'string' },
-          opfsPath: { type: 'string' },
-          url: { type: 'string' },
-        },
-      },
-    },
-    metadata: {
-      type: 'object',
-      description: 'Additional metadata about the adapter',
-      properties: {
-        author: { type: 'string' },
-        license: { type: 'string' },
-        tags: {
-          type: 'array',
-          items: { type: 'string' },
-        },
-        trainedOn: { type: 'string' },
-        epochs: { type: 'number' },
-        learningRate: { type: 'number' },
-        createdAt: { type: 'string', format: 'date-time' },
-        updatedAt: { type: 'string', format: 'date-time' },
-      },
-      additionalProperties: true,
-    },
-  },
-  additionalProperties: false,
-};
-
-// ============================================================================
-// Validation Functions
-// ============================================================================
-
-
-export function validateManifest(manifest) {
-  const errors = [];
-
-  if (!manifest || typeof manifest !== 'object') {
-    return { valid: false, errors: [{ field: 'root', message: 'Manifest must be an object' }] };
-  }
-
-  const m = manifest;
-
-  // Required fields
-  if (!m.id || typeof m.id !== 'string') {
-    errors.push({ field: 'id', message: 'id is required and must be a string', value: m.id });
-  } else if (!/^[a-zA-Z0-9_-]+$/.test(m.id)) {
-    errors.push({ field: 'id', message: 'id must only contain alphanumeric characters, underscores, and hyphens', value: m.id });
-  }
-
-  if (!m.name || typeof m.name !== 'string') {
-    errors.push({ field: 'name', message: 'name is required and must be a string', value: m.name });
-  } else if (m.name.length > 256) {
-    errors.push({ field: 'name', message: 'name must not exceed 256 characters', value: m.name });
-  }
-
-  if (!m.baseModel || typeof m.baseModel !== 'string') {
-    errors.push({ field: 'baseModel', message: 'baseModel is required and must be a string', value: m.baseModel });
-  }
-
-  const { minRank, maxRank, minAlpha } = DEFAULT_ADAPTER_VALIDATION_CONFIG;
-
-  if (typeof m.rank !== 'number' || !Number.isInteger(m.rank) || m.rank < minRank || m.rank > maxRank) {
-    errors.push({ field: 'rank', message: `rank must be an integer between ${minRank} and ${maxRank}`, value: m.rank });
-  }
-
-  if (typeof m.alpha !== 'number' || m.alpha < minAlpha) {
-    errors.push({ field: 'alpha', message: `alpha must be a number >= ${minAlpha}`, value: m.alpha });
-  }
-
-  if (!Array.isArray(m.targetModules) || m.targetModules.length === 0) {
-    errors.push({ field: 'targetModules', message: 'targetModules must be a non-empty array', value: m.targetModules });
-  } else {
-    const uniqueModules = new Set();
-    for (const mod of m.targetModules) {
-      if (!VALID_LORA_TARGET_MODULES.includes(mod)) {
-        errors.push({ field: 'targetModules', message: `Invalid target module: ${mod}`, value: mod });
-      }
-      if (uniqueModules.has(mod)) {
-        errors.push({ field: 'targetModules', message: `Duplicate target module: ${mod}`, value: mod });
-      }
-      uniqueModules.add(mod);
-    }
-  }
-
-  // Optional fields validation
-  if (m.version !== undefined && typeof m.version === 'string') {
-    if (!/^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/.test(m.version)) {
-      errors.push({ field: 'version', message: 'version must follow semantic versioning', value: m.version });
-    }
-  }
-
-  if (m.checksum !== undefined && typeof m.checksum === 'string') {
-    if (!/^[a-fA-F0-9]{64}$/.test(m.checksum)) {
-      errors.push({ field: 'checksum', message: 'checksum must be a 64-character hex string', value: m.checksum });
-    }
-  }
-
-  if (m.checksumAlgorithm !== undefined) {
-    if (m.checksumAlgorithm !== 'sha256' && m.checksumAlgorithm !== 'blake3') {
-      errors.push({ field: 'checksumAlgorithm', message: 'checksumAlgorithm must be sha256 or blake3', value: m.checksumAlgorithm });
-    }
-  }
-
-  if (m.weightsFormat !== undefined) {
-    const validFormats = ['safetensors', 'npz', 'json', 'binary'];
-    if (!validFormats.includes(m.weightsFormat)) {
-      errors.push({ field: 'weightsFormat', message: `weightsFormat must be one of: ${validFormats.join(', ')}`, value: m.weightsFormat });
-    }
-  }
-
-  if (m.tensors !== undefined && Array.isArray(m.tensors)) {
-    for (let i = 0; i < m.tensors.length; i++) {
-      const tensor = m.tensors[i];
-      if (!tensor.name || typeof tensor.name !== 'string') {
-        errors.push({ field: `tensors[${i}].name`, message: 'tensor name is required', value: tensor.name });
-      }
-      if (!Array.isArray(tensor.shape) || tensor.shape.length !== 2) {
-        errors.push({ field: `tensors[${i}].shape`, message: 'tensor shape must be [rows, cols]', value: tensor.shape });
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-export function applyAdapterManifestDefaults(manifest) {
-  if (!manifest || typeof manifest !== 'object') {
-    throw new Error('Adapter manifest must be an object');
-  }
-
-  const merged = { ...manifest };
-  if (!merged.version) {
-    merged.version = DEFAULT_ADAPTER_MANIFEST_DEFAULTS.version;
-  }
-  if (!merged.checksumAlgorithm) {
-    merged.checksumAlgorithm = DEFAULT_ADAPTER_MANIFEST_DEFAULTS.checksumAlgorithm;
-  }
-  if (!merged.weightsFormat) {
-    merged.weightsFormat = DEFAULT_ADAPTER_MANIFEST_DEFAULTS.weightsFormat;
-  }
-
-  if (Array.isArray(merged.tensors)) {
-    merged.tensors = merged.tensors.map((tensor) => {
-      if (tensor && typeof tensor === 'object' && !tensor.dtype) {
-        return { ...tensor, dtype: DEFAULT_ADAPTER_MANIFEST_DEFAULTS.tensorDtype };
-      }
-      return tensor;
-    });
-  }
-
-  return merged;
-}
-
-
-export function parseManifest(json) {
-  let parsed;
-  try {
-    parsed = JSON.parse(json);
-  } catch (e) {
-    throw new Error(`Invalid JSON: ${e.message}`);
-  }
-
-  const validation = validateManifest(parsed);
-  if (!validation.valid) {
-    const errorMessages = validation.errors.map(e => `${e.field}: ${e.message}`).join('; ');
-    throw new Error(`Manifest validation failed: ${errorMessages}`);
-  }
-
-  return parsed;
-}
-
-
-export function serializeManifest(manifest, pretty = false) {
-  const validation = validateManifest(manifest);
-  if (!validation.valid) {
-    const errorMessages = validation.errors.map(e => `${e.field}: ${e.message}`).join('; ');
-    throw new Error(`Cannot serialize invalid manifest: ${errorMessages}`);
-  }
-
-  return JSON.stringify(manifest, null, pretty ? 2 : undefined);
-}
-
-
-export function createManifest(options) {
-  return {
-    version: '1.0.0',
-    checksumAlgorithm: 'sha256',
-    weightsFormat: 'safetensors',
-    ...options,
-  };
-}
-
-
-export function computeLoRAScale(rank, alpha) {
-  return rank > 0 ? alpha / rank : 1;
-}