@nice2dev/ui-tools 1.0.10

package/dist/model-registry.d.ts

@@ -0,0 +1,740 @@
+/**
+ * @file model-registry.ts
+ * @module @nice2dev/ui-tools
+ * @description PRO-18.3 — Model Registry
+ *
+ * Types for ML model registry: versioning, artifacts, lineage,
+ * approval workflows, A/B testing, model cards, fairness/explainability.
+ */
+/** Model stage */
+export type ModelStage = 'none' | 'staging' | 'production' | 'archived';
+/** Model status */
+export type ModelRegistryStatus = 'draft' | 'pending_review' | 'approved' | 'rejected' | 'deprecated';
+/** Model format */
+export type ModelFormat = 'pytorch' | 'tensorflow_savedmodel' | 'keras' | 'onnx' | 'torchscript' | 'sklearn' | 'xgboost' | 'lightgbm' | 'catboost' | 'huggingface' | 'coreml' | 'tflite' | 'custom';
+/** Model registry config */
+export interface ModelRegistryConfig {
+    /** Theme */
+    theme?: RegistryTheme;
+    /** Features */
+    features?: RegistryFeatures;
+    /** Storage */
+    storage?: RegistryStorage;
+    /** Approval workflow */
+    approval?: ApprovalConfig;
+    /** Governance */
+    governance?: GovernanceConfig;
+}
+/** Registry theme */
+export interface RegistryTheme {
+    name?: string;
+    colors?: RegistryColors;
+}
+/** Registry colors */
+export interface RegistryColors {
+    primary?: string;
+    staging?: string;
+    production?: string;
+    archived?: string;
+}
+/** Registry features */
+export interface RegistryFeatures {
+    versioning?: boolean;
+    lineage?: boolean;
+    approval?: boolean;
+    abTesting?: boolean;
+    modelCards?: boolean;
+    fairness?: boolean;
+    explainability?: boolean;
+    monitoring?: boolean;
+}
+/** Registry storage */
+export interface RegistryStorage {
+    type: 's3' | 'gcs' | 'azure' | 'mlflow' | 'custom';
+    bucket?: string;
+    prefix?: string;
+    credentials?: StorageCredentials;
+}
+/** Storage credentials */
+export interface StorageCredentials {
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    region?: string;
+    [key: string]: unknown;
+}
+/** Approval config */
+export interface ApprovalConfig {
+    enabled?: boolean;
+    requireReview?: boolean;
+    minReviewers?: number;
+    autoApprove?: AutoApproveRule[];
+    stages?: StageApproval[];
+}
+/** Auto approve rule */
+export interface AutoApproveRule {
+    condition: 'metric_threshold' | 'test_pass' | 'no_regression';
+    config: Record<string, unknown>;
+}
+/** Stage approval */
+export interface StageApproval {
+    stage: ModelStage;
+    approvers?: string[];
+    checks?: ApprovalCheck[];
+}
+/** Approval check */
+export interface ApprovalCheck {
+    type: 'metric' | 'test' | 'security' | 'fairness' | 'custom';
+    name: string;
+    config?: Record<string, unknown>;
+}
+/** Governance config */
+export interface GovernanceConfig {
+    requireModelCard?: boolean;
+    requireFairnessReport?: boolean;
+    retentionPolicy?: RetentionPolicy;
+    accessControl?: AccessControlConfig;
+}
+/** Retention policy */
+export interface RetentionPolicy {
+    maxVersions?: number;
+    maxAge?: number;
+    keepStages?: ModelStage[];
+}
+/** Access control config */
+export interface AccessControlConfig {
+    publicModels?: boolean;
+    defaultPermissions?: ModelPermissions;
+}
+/** Model permissions */
+export interface ModelPermissions {
+    read?: string[];
+    write?: string[];
+    deploy?: string[];
+    admin?: string[];
+}
+/** Registered model */
+export interface RegisteredModel {
+    id: string;
+    name: string;
+    description?: string;
+    latestVersion?: ModelVersion;
+    versions: ModelVersion[];
+    tags?: string[];
+    labels?: Record<string, string>;
+    owners?: string[];
+    permissions?: ModelPermissions;
+    metadata?: RegisteredModelMetadata;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+/** Model version */
+export interface ModelVersion {
+    version: string;
+    modelId: string;
+    stage: ModelStage;
+    status: ModelRegistryStatus;
+    source: ModelSource;
+    artifacts: ModelArtifact[];
+    signature?: ModelSignature;
+    metrics?: ModelMetrics;
+    lineage?: ModelLineage;
+    modelCard?: ModelCard;
+    approvals?: ModelApproval[];
+    tags?: string[];
+    labels?: Record<string, string>;
+    description?: string;
+    createdAt: Date;
+    createdBy?: string;
+    promotedAt?: Date;
+    promotedBy?: string;
+}
+/** Model source */
+export interface ModelSource {
+    type: 'run' | 'upload' | 'import' | 'conversion';
+    runId?: string;
+    experimentId?: string;
+    uri?: string;
+    framework?: string;
+    frameworkVersion?: string;
+}
+/** Model artifact */
+export interface ModelArtifact {
+    id: string;
+    name: string;
+    type: ModelArtifactType;
+    format: ModelFormat;
+    path: string;
+    size: number;
+    checksum?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Model artifact type */
+export type ModelArtifactType = 'model' | 'weights' | 'config' | 'tokenizer' | 'preprocessor' | 'postprocessor' | 'custom';
+/** Model signature */
+export interface ModelSignature {
+    inputs: SignatureSchema[];
+    outputs: SignatureSchema[];
+    params?: SignatureParam[];
+}
+/** Signature schema */
+export interface SignatureSchema {
+    name: string;
+    dtype: string;
+    shape: (number | string)[];
+    description?: string;
+}
+/** Signature param */
+export interface SignatureParam {
+    name: string;
+    dtype: string;
+    default?: unknown;
+    description?: string;
+}
+/** Model metrics */
+export interface ModelMetrics {
+    training?: Record<string, number>;
+    validation?: Record<string, number>;
+    test?: Record<string, number>;
+    custom?: Record<string, number>;
+}
+/** Model approval */
+export interface ModelApproval {
+    id: string;
+    stage: ModelStage;
+    status: 'pending' | 'approved' | 'rejected';
+    reviewer?: string;
+    reviewedAt?: Date;
+    comments?: string;
+    checks?: ApprovalCheckResult[];
+}
+/** Approval check result */
+export interface ApprovalCheckResult {
+    check: ApprovalCheck;
+    passed: boolean;
+    details?: string;
+}
+/** Registered model metadata */
+export interface RegisteredModelMetadata {
+    task?: string;
+    domain?: string;
+    framework?: string;
+    language?: string[];
+    license?: string;
+    paperUrl?: string;
+    codeUrl?: string;
+    datasetUrl?: string;
+    custom?: Record<string, unknown>;
+}
+/** Model lineage */
+export interface ModelLineage {
+    modelId: string;
+    version: string;
+    training: TrainingLineage;
+    data: DataLineage;
+    code: CodeLineage;
+    environment: EnvironmentLineage;
+    parent?: ParentLineage;
+}
+/** Training lineage */
+export interface TrainingLineage {
+    runId: string;
+    experimentId?: string;
+    experimentName?: string;
+    hyperparameters?: Record<string, unknown>;
+    metrics?: Record<string, number>;
+    startTime?: Date;
+    endTime?: Date;
+}
+/** Data lineage */
+export interface DataLineage {
+    datasets: DatasetReference[];
+    preprocessing?: PreprocessingLineage[];
+    features?: FeatureLineage[];
+}
+/** Dataset reference */
+export interface DatasetReference {
+    id: string;
+    name: string;
+    version?: string;
+    split?: string;
+    samples?: number;
+    path?: string;
+}
+/** Preprocessing lineage */
+export interface PreprocessingLineage {
+    step: string;
+    params?: Record<string, unknown>;
+}
+/** Feature lineage */
+export interface FeatureLineage {
+    name: string;
+    source?: string;
+    transformation?: string;
+}
+/** Code lineage */
+export interface CodeLineage {
+    repository?: string;
+    branch?: string;
+    commit?: string;
+    path?: string;
+    entryPoint?: string;
+}
+/** Environment lineage */
+export interface EnvironmentLineage {
+    python?: string;
+    framework?: string;
+    frameworkVersion?: string;
+    cuda?: string;
+    packages?: PackageInfo[];
+    docker?: string;
+    hardware?: HardwareInfo;
+}
+/** Package info */
+export interface PackageInfo {
+    name: string;
+    version: string;
+}
+/** Hardware info */
+export interface HardwareInfo {
+    cpu?: string;
+    memory?: number;
+    gpu?: string;
+    gpuCount?: number;
+}
+/** Parent lineage */
+export interface ParentLineage {
+    modelId: string;
+    version: string;
+    relationship: 'fine_tuned' | 'distilled' | 'pruned' | 'quantized' | 'merged';
+}
+/** Model card */
+export interface ModelCard {
+    modelId: string;
+    version: string;
+    overview: ModelOverview;
+    intendedUse: IntendedUse;
+    factors: ModelFactors;
+    metrics: ModelCardMetrics;
+    trainingData: TrainingDataInfo;
+    evaluationData?: EvaluationDataInfo;
+    ethicalConsiderations?: EthicalConsiderations;
+    caveatsRecommendations?: CaveatsRecommendations;
+    quantitativeAnalysis?: QuantitativeAnalysis;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+/** Model overview */
+export interface ModelOverview {
+    name: string;
+    description: string;
+    version: string;
+    developers?: string[];
+    releaseDate?: Date;
+    modelType?: string;
+    architecture?: string;
+    framework?: string;
+    license?: string;
+    citation?: string;
+}
+/** Intended use */
+export interface IntendedUse {
+    primaryUses: string[];
+    primaryUsers?: string[];
+    outOfScopeUses?: string[];
+}
+/** Model factors */
+export interface ModelFactors {
+    relevantFactors?: RelevantFactor[];
+    evaluationFactors?: EvaluationFactor[];
+}
+/** Relevant factor */
+export interface RelevantFactor {
+    name: string;
+    description: string;
+    groups?: string[];
+}
+/** Evaluation factor */
+export interface EvaluationFactor {
+    name: string;
+    description: string;
+    disaggregation?: string[];
+}
+/** Model card metrics */
+export interface ModelCardMetrics {
+    performanceMetrics: PerformanceMetric[];
+    decisionThresholds?: DecisionThreshold[];
+    variationApproaches?: string[];
+}
+/** Performance metric */
+export interface PerformanceMetric {
+    name: string;
+    value: number;
+    confidence?: number;
+    slice?: string;
+    description?: string;
+}
+/** Decision threshold */
+export interface DecisionThreshold {
+    metric: string;
+    threshold: number;
+    rationale?: string;
+}
+/** Training data info */
+export interface TrainingDataInfo {
+    datasets?: DatasetInfo[];
+    preprocessing?: string[];
+    dataAugmentation?: string[];
+}
+/** Dataset info */
+export interface DatasetInfo {
+    name: string;
+    url?: string;
+    description?: string;
+    size?: number;
+    splits?: Record<string, number>;
+    demographics?: Record<string, number>;
+}
+/** Evaluation data info */
+export interface EvaluationDataInfo {
+    datasets?: DatasetInfo[];
+    evaluationProcess?: string;
+}
+/** Ethical considerations */
+export interface EthicalConsiderations {
+    concerns?: string[];
+    mitigations?: string[];
+    tradeoffs?: string[];
+}
+/** Caveats recommendations */
+export interface CaveatsRecommendations {
+    caveats?: string[];
+    recommendations?: string[];
+}
+/** Quantitative analysis */
+export interface QuantitativeAnalysis {
+    unitaryResults?: UnitaryResult[];
+    intersectionalResults?: IntersectionalResult[];
+}
+/** Unitary result */
+export interface UnitaryResult {
+    factor: string;
+    group: string;
+    metrics: Record<string, number>;
+}
+/** Intersectional result */
+export interface IntersectionalResult {
+    factors: string[];
+    groups: string[];
+    metrics: Record<string, number>;
+}
+/** Model experiment */
+export interface ModelABExperiment {
+    id: string;
+    name: string;
+    description?: string;
+    status: ABExperimentStatus;
+    config: ABExperimentConfig;
+    variants: ABVariant[];
+    results?: ABExperimentResults;
+    createdAt: Date;
+    startedAt?: Date;
+    endedAt?: Date;
+}
+/** AB experiment status */
+export type ABExperimentStatus = 'draft' | 'running' | 'paused' | 'completed' | 'stopped';
+/** AB experiment config */
+export interface ABExperimentConfig {
+    metric: ABMetric;
+    hypothesis?: string;
+    trafficAllocation: TrafficAllocation;
+    duration?: number;
+    minSampleSize?: number;
+    confidenceLevel?: number;
+    earlyStop?: EarlyStopConfig;
+}
+/** AB metric */
+export interface ABMetric {
+    name: string;
+    type: 'conversion' | 'revenue' | 'latency' | 'custom';
+    goal: 'increase' | 'decrease';
+}
+/** Traffic allocation */
+export interface TrafficAllocation {
+    type: 'fixed' | 'dynamic' | 'multi_armed_bandit';
+    weights?: Record<string, number>;
+}
+/** Early stop config */
+export interface EarlyStopConfig {
+    enabled: boolean;
+    minRuntime?: number;
+    checkInterval?: number;
+    threshold?: number;
+}
+/** AB variant */
+export interface ABVariant {
+    id: string;
+    name: string;
+    modelId: string;
+    modelVersion: string;
+    trafficPercent: number;
+    isControl?: boolean;
+}
+/** AB experiment results */
+export interface ABExperimentResults {
+    summary: ABResultsSummary;
+    variants: ABVariantResult[];
+    timeline?: ABTimeline;
+    confidence?: ConfidenceAnalysis;
+}
+/** AB results summary */
+export interface ABResultsSummary {
+    winner?: string;
+    significance: boolean;
+    pValue?: number;
+    uplift?: number;
+    sampleSize: number;
+}
+/** AB variant result */
+export interface ABVariantResult {
+    variantId: string;
+    sampleSize: number;
+    conversions?: number;
+    conversionRate?: number;
+    mean?: number;
+    std?: number;
+    confidence?: ConfidenceInterval;
+}
+/** Confidence interval */
+export interface ConfidenceInterval {
+    lower: number;
+    upper: number;
+    level: number;
+}
+/** AB timeline */
+export interface ABTimeline {
+    timestamps: Date[];
+    metrics: Record<string, number[]>;
+}
+/** Confidence analysis */
+export interface ConfidenceAnalysis {
+    method: 'frequentist' | 'bayesian';
+    pValue?: number;
+    posteriorProbability?: number;
+    credibleInterval?: ConfidenceInterval;
+}
+/** Shadow deployment */
+export interface ShadowDeployment {
+    id: string;
+    name: string;
+    description?: string;
+    status: ShadowStatus;
+    config: ShadowConfig;
+    results?: ShadowResults;
+    createdAt: Date;
+    startedAt?: Date;
+    endedAt?: Date;
+}
+/** Shadow status */
+export type ShadowStatus = 'pending' | 'running' | 'completed' | 'stopped';
+/** Shadow config */
+export interface ShadowConfig {
+    productionModel: ModelReference;
+    shadowModel: ModelReference;
+    trafficPercent: number;
+    comparisonMetrics: string[];
+    duration?: number;
+    logPredictions?: boolean;
+}
+/** Model reference */
+export interface ModelReference {
+    modelId: string;
+    version: string;
+}
+/** Shadow results */
+export interface ShadowResults {
+    requestCount: number;
+    comparisonSummary: ComparisonSummary[];
+    predictionDiffs?: PredictionDiff[];
+    latencyComparison?: LatencyComparison;
+}
+/** Comparison summary */
+export interface ComparisonSummary {
+    metric: string;
+    production: number;
+    shadow: number;
+    diff: number;
+    diffPercent: number;
+}
+/** Prediction diff */
+export interface PredictionDiff {
+    requestId: string;
+    input: unknown;
+    productionOutput: unknown;
+    shadowOutput: unknown;
+    agreementScore?: number;
+}
+/** Latency comparison */
+export interface LatencyComparison {
+    production: LatencyStats;
+    shadow: LatencyStats;
+}
+/** Latency stats */
+export interface LatencyStats {
+    mean: number;
+    p50: number;
+    p90: number;
+    p99: number;
+}
+/** Fairness report */
+export interface FairnessReport {
+    modelId: string;
+    version: string;
+    timestamp: Date;
+    sensitiveAttributes: SensitiveAttribute[];
+    metrics: FairnessMetric[];
+    sliceAnalysis: SliceAnalysis[];
+    biasDetection?: BiasDetection[];
+    recommendations?: FairnessRecommendation[];
+}
+/** Sensitive attribute */
+export interface SensitiveAttribute {
+    name: string;
+    type: 'binary' | 'categorical' | 'continuous';
+    groups: string[];
+    privilegedGroup?: string;
+}
+/** Fairness metric */
+export interface FairnessMetric {
+    name: FairnessMetricType;
+    attribute: string;
+    overall: number;
+    byGroup: Record<string, number>;
+    threshold?: number;
+    passed?: boolean;
+}
+/** Fairness metric type */
+export type FairnessMetricType = 'demographic_parity' | 'equalized_odds' | 'equal_opportunity' | 'predictive_parity' | 'calibration' | 'disparate_impact' | 'treatment_equality';
+/** Slice analysis */
+export interface SliceAnalysis {
+    slice: Record<string, string>;
+    sampleSize: number;
+    metrics: Record<string, number>;
+}
+/** Bias detection */
+export interface BiasDetection {
+    type: BiasType;
+    severity: 'low' | 'medium' | 'high';
+    description: string;
+    affectedAttribute: string;
+    evidence: BiasEvidence;
+}
+/** Bias type */
+export type BiasType = 'historical' | 'representation' | 'measurement' | 'aggregation' | 'evaluation' | 'deployment';
+/** Bias evidence */
+export interface BiasEvidence {
+    metric?: string;
+    value?: number;
+    threshold?: number;
+    samples?: unknown[];
+}
+/** Fairness recommendation */
+export interface FairnessRecommendation {
+    issue: string;
+    action: string;
+    priority: 'low' | 'medium' | 'high';
+}
+/** Explainability report */
+export interface ExplainabilityReport {
+    modelId: string;
+    version: string;
+    timestamp: Date;
+    globalExplanations: GlobalExplanation[];
+    localExplanations?: LocalExplanation[];
+    interpretability?: InterpretabilityScore;
+}
+/** Global explanation */
+export interface GlobalExplanation {
+    method: ExplainabilityMethod;
+    featureImportance: FeatureImportanceScore[];
+    interactionEffects?: InteractionEffect[];
+    partialDependence?: PartialDependencePlot[];
+}
+/** Explainability method */
+export type ExplainabilityMethod = 'shap' | 'lime' | 'permutation' | 'integrated_gradients' | 'attention' | 'counterfactual' | 'anchors';
+/** Feature importance score */
+export interface FeatureImportanceScore {
+    feature: string;
+    importance: number;
+    std?: number;
+    direction?: 'positive' | 'negative' | 'mixed';
+}
+/** Interaction effect */
+export interface InteractionEffect {
+    features: string[];
+    strength: number;
+}
+/** Partial dependence plot */
+export interface PartialDependencePlot {
+    feature: string;
+    values: number[];
+    predictions: number[];
+    ice?: number[][];
+}
+/** Local explanation */
+export interface LocalExplanation {
+    sampleId: string;
+    input: Record<string, unknown>;
+    prediction: unknown;
+    confidence?: number;
+    contributions: FeatureContribution[];
+    counterfactuals?: Counterfactual[];
+}
+/** Feature contribution */
+export interface FeatureContribution {
+    feature: string;
+    value: unknown;
+    contribution: number;
+    baseValue?: number;
+}
+/** Counterfactual */
+export interface Counterfactual {
+    changes: FeatureChange[];
+    newPrediction: unknown;
+    distance: number;
+}
+/** Feature change */
+export interface FeatureChange {
+    feature: string;
+    originalValue: unknown;
+    newValue: unknown;
+}
+/** Interpretability score */
+export interface InterpretabilityScore {
+    overall: number;
+    complexity: number;
+    transparency: number;
+    simulatability: number;
+}
+/** Rollback request */
+export interface RollbackRequest {
+    id: string;
+    modelId: string;
+    fromVersion: string;
+    toVersion: string;
+    reason: string;
+    requestedBy: string;
+    requestedAt: Date;
+    status: RollbackStatus;
+    approvals?: RollbackApproval[];
+    executedAt?: Date;
+}
+/** Rollback status */
+export type RollbackStatus = 'pending' | 'approved' | 'rejected' | 'executing' | 'completed' | 'failed';
+/** Rollback approval */
+export interface RollbackApproval {
+    approver: string;
+    status: 'approved' | 'rejected';
+    timestamp: Date;
+    comments?: string;
+}
+//# sourceMappingURL=model-registry.d.ts.map