@iota-big3/sdk-gateway

/** * AI & Machine Learning Type Definitions * * @module ai-ml-types * @description Comprehensive types for AI/ML operations including: * - Model definitions and lifecycle * - Training configurations and datasets * - Inference and predictions * - Feature engineering * - Experiment tracking * - Model monitoring and drift detection * - AI assistants and agents * - Prompt engineering * * Designed for maximum AI/debugging friendliness */ import type { Brand, MonetaryAmount, Result } from './index'; /** Unique model identifier */ export type ModelId = Brand<string, 'ModelId'>; /** Model version identifier */ export type ModelVersion = Brand<string, 'ModelVersion'>; /** Dataset identifier */ export type DatasetId = Brand<string, 'DatasetId'>; /** Experiment identifier */ export type ExperimentId = Brand<string, 'ExperimentId'>; /** Training run identifier */ export type TrainingRunId = Brand<string, 'TrainingRunId'>; /** Feature identifier */ export type FeatureId = Brand<string, 'FeatureId'>; /** Prompt template identifier */ export type PromptTemplateId = Brand<string, 'PromptTemplateId'>; /** * Machine Learning Model Definition * Central record for all model information */ export interface MLModel { readonly modelId: ModelId; readonly name: string; readonly description: string; readonly type: ModelType; readonly framework: MLFramework; readonly architecture: ModelArchitecture; readonly version: ModelVersion; readonly created: { readonly at: string; readonly by: string; }; readonly status: ModelStatus; readonly metadata: ModelMetadata; readonly performance?: ModelPerformance; readonly deployment?: ModelDeployment; } /** * Types of ML models */ export declare enum ModelType { Classification = "CLASSIFICATION", Regression = "REGRESSION", Clustering = "CLUSTERING", DimensionalityReduction = "DIMENSIONALITY_REDUCTION", AnomalyDetection = "ANOMALY_DETECTION", RecommendationSystem = "RECOMMENDATION_SYSTEM", CNN = "CNN",// Convolutional Neural Network RNN = "RNN",// Recurrent Neural Network LSTM = "LSTM",// Long Short-Term Memory GRU = "GRU",// Gated Recurrent Unit Transformer = "TRANSFORMER", GAN = "GAN",// Generative Adversarial Network VAE = "VAE",// Variational Autoencoder NLP = "NLP",// Natural Language Processing ComputerVision = "COMPUTER_VISION", TimeSeries = "TIME_SERIES", ReinforcementLearning = "REINFORCEMENT_LEARNING", GraphNeural = "GRAPH_NEURAL", LLM = "LLM",// Large Language Model VisionLanguageModel = "VISION_LANGUAGE_MODEL", SpeechModel = "SPEECH_MODEL", MultiModal = "MULTI_MODAL" } /** * ML frameworks */ export declare enum MLFramework { TensorFlow = "TENSORFLOW", PyTorch = "PYTORCH", ScikitLearn = "SCIKIT_LEARN", XGBoost = "XGBOOST", LightGBM = "LIGHTGBM", Keras = "KERAS", JAX = "JAX", ONNX = "ONNX", HuggingFace = "HUGGING_FACE", OpenAI = "OPENAI", Anthropic = "ANTHROPIC", Custom = "CUSTOM" } /** * Model architecture details */ export interface ModelArchitecture { readonly baseModel?: string; readonly layers?: LayerDefinition[]; readonly parameters: { readonly total: number; readonly trainable: number; readonly frozen?: number; }; readonly inputShape?: number[]; readonly outputShape?: number[]; readonly config?: Record<string, unknown>; } /** * Neural network layer definition */ export interface LayerDefinition { readonly name: string; readonly type: string; readonly parameters: number; readonly config: Record<string, unknown>; readonly activation?: string; } /** * Model status in lifecycle */ export declare enum ModelStatus { Draft = "DRAFT", Training = "TRAINING", Evaluating = "EVALUATING", Validated = "VALIDATED", Deployed = "DEPLOYED", Deprecated = "DEPRECATED", Archived = "ARCHIVED" } /** * Model metadata */ export interface ModelMetadata { readonly task: string; readonly domain: string; readonly tags: readonly string[]; readonly language?: string[]; readonly license?: string; readonly citations?: string[]; readonly ethicalConsiderations?: string; readonly limitations?: string[]; readonly intendedUse?: string; } /** * Model training configuration */ export interface TrainingConfig { readonly experimentId: ExperimentId; readonly runId: TrainingRunId; readonly model: { readonly architecture: ModelArchitecture; readonly hyperparameters: Hyperparameters; }; readonly data: { readonly trainDataset: DatasetId; readonly validationDataset?: DatasetId; readonly testDataset?: DatasetId; readonly preprocessing: PreprocessingStep[]; readonly augmentation?: DataAugmentation[]; }; readonly training: { readonly epochs?: number; readonly batchSize: number; readonly learningRate: number | LearningRateSchedule; readonly optimizer: OptimizerConfig; readonly loss: LossFunction; readonly metrics: string[]; readonly callbacks?: TrainingCallback[]; readonly earlyStopping?: EarlyStoppingConfig; }; readonly resources: { readonly gpu?: GPUConfig; readonly distributed?: DistributedConfig; readonly timeout?: number; readonly checkpointing: CheckpointConfig; }; } /** * Model hyperparameters */ export interface Hyperparameters { readonly [key: string]: HyperparameterValue; } /** * Hyperparameter value types */ export type HyperparameterValue = number | string | boolean | number[] | string[] | { min: number; max: number; step?: number; } | { choices: readonly (string | number)[]; }; /** * Learning rate schedule */ export interface LearningRateSchedule { readonly initial: number; readonly schedule: 'constant' | 'exponential' | 'step' | 'cosine' | 'cyclic' | 'custom'; readonly parameters?: Record<string, number>; } /** * Optimizer configuration */ export interface OptimizerConfig { readonly type: 'sgd' | 'adam' | 'adamw' | 'rmsprop' | 'adagrad' | 'custom'; readonly parameters?: Record<string, number>; readonly momentum?: number; readonly weightDecay?: number; } /** * Loss function configuration */ export interface LossFunction { readonly type: string; readonly parameters?: Record<string, unknown>; readonly weights?: number[]; } /** * Training callback */ export interface TrainingCallback { readonly type: 'checkpoint' | 'tensorboard' | 'wandb' | 'custom'; readonly config?: Record<string, unknown>; } /** * Early stopping configuration */ export interface EarlyStoppingConfig { readonly monitor: string; readonly patience: number; readonly minDelta: number; readonly mode: 'min' | 'max'; } /** * GPU configuration */ export interface GPUConfig { readonly deviceIds?: number[]; readonly memoryLimit?: number; readonly allowGrowth?: boolean; readonly mixedPrecision?: boolean; } /** * Distributed training configuration */ export interface DistributedConfig { readonly strategy: 'data_parallel' | 'model_parallel' | 'pipeline_parallel'; readonly nodes: number; readonly gpusPerNode: number; readonly backend?: 'nccl' | 'gloo' | 'mpi'; } /** * Checkpoint configuration */ export interface CheckpointConfig { readonly frequency: 'epoch' | 'step' | 'time'; readonly interval: number; readonly keepBest: number; readonly keepLast: number; readonly savePath: string; } /** * Dataset definition */ export interface Dataset { readonly datasetId: DatasetId; readonly name: string; readonly description: string; readonly type: DatasetType; readonly format: DataFormat; readonly size: DatasetSize; readonly schema?: DataSchema; readonly source: DataSource; readonly quality: DataQuality; readonly splits?: DatasetSplits; readonly version: string; readonly created: { readonly at: string; readonly by: string; }; readonly privacy: { readonly containsPII: boolean; readonly anonymized: boolean; readonly consentObtained?: boolean; }; } /** * Dataset types */ export declare enum DatasetType { Tabular = "TABULAR", Text = "TEXT", Image = "IMAGE", Audio = "AUDIO", Video = "VIDEO", TimeSeries = "TIME_SERIES", Graph = "GRAPH", MultiModal = "MULTI_MODAL" } /** * Data formats */ export declare enum DataFormat { CSV = "CSV", JSON = "JSON", Parquet = "PARQUET", TFRecord = "TFRECORD", ImageFolder = "IMAGE_FOLDER", COCO = "COCO", YOLO = "YOLO", HuggingFaceDataset = "HUGGING_FACE_DATASET", Custom = "CUSTOM" } /** * Dataset size information */ export interface DatasetSize { readonly samples: number; readonly features?: number; readonly sizeInBytes: number; readonly compressed?: boolean; } /** * Data schema definition */ export interface DataSchema { readonly features: Feature[]; readonly target?: Feature; readonly metadata?: Record<string, unknown>; } /** * Feature definition */ export interface Feature { readonly featureId: FeatureId; readonly name: string; readonly type: FeatureType; readonly dtype: DataType; readonly shape?: number[]; readonly nullable: boolean; readonly statistics?: FeatureStatistics; readonly importance?: number; } /** * Feature types */ export declare enum FeatureType { Numeric = "NUMERIC", Categorical = "CATEGORICAL", Text = "TEXT", DateTime = "DATETIME", Binary = "BINARY", Embedding = "EMBEDDING", Image = "IMAGE", Audio = "AUDIO", Video = "VIDEO" } /** * Data types */ export declare enum DataType { Int8 = "INT8", Int16 = "INT16", Int32 = "INT32", Int64 = "INT64", Float16 = "FLOAT16", Float32 = "FLOAT32", Float64 = "FLOAT64", String = "STRING", Boolean = "BOOLEAN", Bytes = "BYTES" } /** * Feature statistics */ export interface FeatureStatistics { readonly count: number; readonly missing: number; readonly unique?: number; readonly numeric?: { readonly mean: number; readonly std: number; readonly min: number; readonly max: number; readonly quantiles?: Record<string, number>; }; readonly categorical?: { readonly categories: string[]; readonly frequencies: Record<string, number>; }; } /** * Data source information */ export interface DataSource { readonly type: 'database' | 'file' | 'api' | 'stream' | 'synthetic'; readonly location: string; readonly credentials?: string; readonly query?: string; readonly refreshSchedule?: string; } /** * Data quality metrics */ export interface DataQuality { readonly completeness: number; readonly accuracy?: number; readonly consistency?: number; readonly timeliness?: string; readonly validity?: number; readonly uniqueness?: number; readonly issues?: DataQualityIssue[]; } /** * Data quality issue */ export interface DataQualityIssue { readonly type: 'missing' | 'outlier' | 'duplicate' | 'inconsistent' | 'invalid'; readonly severity: 'low' | 'medium' | 'high'; readonly affectedFeatures: string[]; readonly description: string; readonly suggestedFix?: string; } /** * Dataset splits */ export interface DatasetSplits { readonly train: number; readonly validation?: number; readonly test: number; readonly method: 'random' | 'stratified' | 'temporal' | 'custom'; readonly seed?: number; } /** * Data preprocessing step */ export interface PreprocessingStep { readonly type: PreprocessingType; readonly parameters?: Record<string, unknown>; readonly applyTo?: string[]; } /** * Preprocessing types */ export declare enum PreprocessingType { Normalize = "NORMALIZE", Standardize = "STANDARDIZE", MinMaxScale = "MIN_MAX_SCALE", RobustScale = "ROBUST_SCALE", LogTransform = "LOG_TRANSFORM", OneHotEncode = "ONE_HOT_ENCODE", LabelEncode = "LABEL_ENCODE", TargetEncode = "TARGET_ENCODE", Tokenize = "TOKENIZE", Lowercase = "LOWERCASE", RemoveStopwords = "REMOVE_STOPWORDS", Stemming = "STEMMING", Lemmatization = "LEMMATIZATION", ImputeMissing = "IMPUTE_MISSING", RemoveOutliers = "REMOVE_OUTLIERS", FeatureEngineering = "FEATURE_ENGINEERING" } /** * Data augmentation */ export interface DataAugmentation { readonly type: string; readonly probability: number; readonly parameters?: Record<string, unknown>; } /** * Training run record */ export interface TrainingRun { readonly runId: TrainingRunId; readonly experimentId: ExperimentId; readonly modelId: ModelId; readonly config: TrainingConfig; readonly status: TrainingStatus; readonly started: string; readonly completed?: string; readonly duration?: number; readonly metrics: TrainingMetrics; readonly artifacts: TrainingArtifacts; readonly cost?: MonetaryAmount; } /** * Training status */ export declare enum TrainingStatus { Pending = "PENDING", Running = "RUNNING", Completed = "COMPLETED", Failed = "FAILED", Cancelled = "CANCELLED", Paused = "PAUSED" } /** * Training metrics */ export interface TrainingMetrics { readonly epochs: EpochMetrics[]; readonly best: { readonly metric: string; readonly value: number; readonly epoch: number; }; readonly final: Record<string, number>; readonly history: Record<string, number[]>; } /** * Metrics for single epoch */ export interface EpochMetrics { readonly epoch: number; readonly train: Record<string, number>; readonly validation?: Record<string, number>; readonly learningRate: number; readonly duration: number; } /** * Training artifacts */ export interface TrainingArtifacts { readonly modelPath: string; readonly checkpoints?: string[]; readonly logs?: string; readonly visualizations?: string[]; readonly configPath: string; } /** * ML Experiment tracking */ export interface Experiment { readonly experimentId: ExperimentId; readonly name: string; readonly description: string; readonly hypothesis?: string; readonly objective: string; readonly metrics: string[]; readonly created: { readonly at: string; readonly by: string; }; readonly runs: TrainingRunId[]; readonly bestRun?: TrainingRunId; readonly conclusions?: string; readonly tags: string[]; } /** * Model performance metrics */ export interface ModelPerformance { readonly evaluated: string; readonly testDataset: DatasetId; readonly metrics: PerformanceMetrics; readonly confusionMatrix?: number[][]; readonly classificationReport?: ClassificationReport; readonly featureImportance?: Record<string, number>; readonly examples?: PredictionExample[]; } /** * Performance metrics by task type */ export interface PerformanceMetrics { readonly accuracy?: number; readonly precision?: number; readonly recall?: number; readonly f1Score?: number; readonly auc?: number; readonly mse?: number; readonly mae?: number; readonly rmse?: number; readonly r2?: number; readonly perplexity?: number; readonly bleu?: number; readonly customMetrics?: Record<string, number>; } /** * Classification report */ export interface ClassificationReport { readonly classes: string[]; readonly perClass: Record<string, { readonly precision: number; readonly recall: number; readonly f1Score: number; readonly support: number; }>; readonly average: { readonly micro: PerformanceMetrics; readonly macro: PerformanceMetrics; readonly weighted: PerformanceMetrics; }; } /** * Prediction example for debugging */ export interface PredictionExample { readonly input: unknown; readonly predicted: unknown; readonly actual?: unknown; readonly confidence?: number; readonly explanation?: string; } /** * Model inference request */ export interface InferenceRequest { readonly requestId: Brand<string, 'InferenceRequestId'>; readonly modelId: ModelId; readonly version?: ModelVersion; readonly input: InferenceInput; readonly options?: InferenceOptions; readonly timestamp: string; readonly source?: string; } /** * Inference input types */ export type InferenceInput = { type: 'single'; data: unknown; } | { type: 'batch'; data: unknown[]; } | { type: 'stream'; data: AsyncIterable<unknown>; }; /** * Inference options */ export interface InferenceOptions { readonly timeout?: number; readonly temperature?: number; readonly topK?: number; readonly topP?: number; readonly maxTokens?: number; readonly stopSequences?: string[]; readonly returnProbabilities?: boolean; readonly explainPrediction?: boolean; } /** * Model inference response */ export interface InferenceResponse { readonly requestId: Brand<string, 'InferenceRequestId'>; readonly predictions: Prediction[]; readonly modelVersion: ModelVersion; readonly latency: number; readonly tokensUsed?: { readonly input: number; readonly output: number; }; readonly cost?: MonetaryAmount; } /** * Individual prediction */ export interface Prediction { readonly value: unknown; readonly confidence?: number; readonly probabilities?: Record<string, number>; readonly explanation?: PredictionExplanation; readonly metadata?: Record<string, unknown>; } /** * Prediction explanation */ export interface PredictionExplanation { readonly method: 'shap' | 'lime' | 'attention' | 'gradcam' | 'custom'; readonly featureImportance?: Record<string, number>; readonly visualization?: string; readonly textual?: string; } /** * Model deployment configuration */ export interface ModelDeployment { readonly deploymentId: Brand<string, 'DeploymentId'>; readonly modelId: ModelId; readonly version: ModelVersion; readonly environment: DeploymentEnvironment; readonly endpoint: ModelEndpoint; readonly scaling: ScalingConfig; readonly monitoring: MonitoringConfig; readonly status: DeploymentStatus; readonly deployed: { readonly at: string; readonly by: string; }; } /** * Deployment environments */ export declare enum DeploymentEnvironment { Development = "DEVELOPMENT", Staging = "STAGING", Production = "PRODUCTION", Edge = "EDGE", Mobile = "MOBILE" } /** * Model endpoint configuration */ export interface ModelEndpoint { readonly url: string; readonly protocol: 'rest' | 'grpc' | 'websocket'; readonly authentication: 'api-key' | 'oauth' | 'jwt' | 'none'; readonly rateLimit?: { readonly requestsPerMinute: number; readonly burstLimit: number; }; readonly cors?: string[]; } /** * Auto-scaling configuration */ export interface ScalingConfig { readonly minInstances: number; readonly maxInstances: number; readonly targetCPU?: number; readonly targetMemory?: number; readonly targetLatency?: number; readonly scaleDownDelay?: number; } /** * Model monitoring configuration */ export interface MonitoringConfig { readonly metrics: string[]; readonly dataQuality: boolean; readonly modelDrift: boolean; readonly performanceDrift: boolean; readonly alerts: MonitoringAlert[]; readonly logging: { readonly predictions: boolean; readonly errors: boolean; readonly metadata: boolean; }; } /** * Monitoring alert configuration */ export interface MonitoringAlert { readonly name: string; readonly metric: string; readonly threshold: number; readonly comparison: 'gt' | 'lt' | 'eq' | 'gte' | 'lte'; readonly window: number; readonly actions: string[]; } /** * Deployment status */ export declare enum DeploymentStatus { Pending = "PENDING", Deploying = "DEPLOYING", Running = "RUNNING", Updating = "UPDATING", Scaling = "SCALING", Failed = "FAILED", Stopped = "STOPPED" } /** * Model drift detection */ export interface ModelDrift { readonly modelId: ModelId; readonly type: DriftType; readonly detected: string; readonly severity: 'low' | 'medium' | 'high' | 'critical'; readonly metrics: DriftMetrics; readonly recommendation: string; readonly requiresRetraining: boolean; } /** * Types of model drift */ export declare enum DriftType { DataDrift = "DATA_DRIFT",// Input distribution change ConceptDrift = "CONCEPT_DRIFT",// Relationship change PredictionDrift = "PREDICTION_DRIFT",// Output distribution change PerformanceDrift = "PERFORMANCE_DRIFT" } /** * Drift metrics */ export interface DriftMetrics { readonly baseline: Record<string, number>; readonly current: Record<string, number>; readonly change: Record<string, number>; readonly pValue?: number; readonly divergence?: number; } /** * AI Assistant configuration */ export interface AIAssistant { readonly assistantId: Brand<string, 'AssistantId'>; readonly name: string; readonly description: string; readonly capabilities: AICapability[]; readonly personality?: AssistantPersonality; readonly knowledge: KnowledgeBase; readonly tools?: AITool[]; readonly constraints?: string[]; readonly ethics?: EthicalGuidelines; } /** * AI capabilities */ export declare enum AICapability { TextGeneration = "TEXT_GENERATION", CodeGeneration = "CODE_GENERATION", QuestionAnswering = "QUESTION_ANSWERING", Summarization = "SUMMARIZATION", Translation = "TRANSLATION", SentimentAnalysis = "SENTIMENT_ANALYSIS", ImageGeneration = "IMAGE_GENERATION", ImageAnalysis = "IMAGE_ANALYSIS", SpeechRecognition = "SPEECH_RECOGNITION", SpeechSynthesis = "SPEECH_SYNTHESIS", ReasoningChain = "REASONING_CHAIN", ToolUse = "TOOL_USE" } /** * Assistant personality traits */ export interface AssistantPersonality { readonly tone: 'professional' | 'friendly' | 'casual' | 'formal'; readonly verbosity: 'concise' | 'balanced' | 'detailed'; readonly creativity: number; readonly helpfulness: number; readonly humor?: boolean; } /** * Knowledge base for AI */ export interface KnowledgeBase { readonly sources: KnowledgeSource[]; readonly updateFrequency?: string; readonly vectorStore?: VectorStoreConfig; readonly factChecking?: boolean; } /** * Knowledge source */ export interface KnowledgeSource { readonly type: 'documents' | 'database' | 'api' | 'web'; readonly location: string; readonly format?: string; readonly filters?: Record<string, unknown>; readonly priority: number; } /** * Vector store configuration */ export interface VectorStoreConfig { readonly provider: 'pinecone' | 'weaviate' | 'qdrant' | 'custom'; readonly dimensions: number; readonly similarity: 'cosine' | 'euclidean' | 'dot_product'; readonly indexType?: string; } /** * AI tool definition */ export interface AITool { readonly name: string; readonly description: string; readonly parameters: ToolParameter[]; readonly returns: string; readonly examples?: ToolExample[]; } /** * Tool parameter */ export interface ToolParameter { readonly name: string; readonly type: string; readonly description: string; readonly required: boolean; readonly default?: unknown; readonly validation?: string; } /** * Tool usage example */ export interface ToolExample { readonly input: Record<string, unknown>; readonly output: unknown; readonly explanation?: string; } /** * Ethical guidelines for AI */ export interface EthicalGuidelines { readonly principles: string[]; readonly restrictions: string[]; readonly biasMetrics?: Record<string, number>; readonly fairnessConstraints?: string[]; readonly transparencyLevel: 'low' | 'medium' | 'high'; } /** * Prompt template */ export interface PromptTemplate { readonly templateId: PromptTemplateId; readonly name: string; readonly description: string; readonly template: string; readonly variables: PromptVariable[]; readonly model?: string; readonly version: string; readonly performance?: PromptPerformance; readonly examples?: PromptExample[]; } /** * Prompt variable */ export interface PromptVariable { readonly name: string; readonly type: 'string' | 'number' | 'boolean' | 'object' | 'array'; readonly description: string; readonly required: boolean; readonly default?: unknown; readonly validation?: string; } /** * Prompt example */ export interface PromptExample { readonly variables: Record<string, unknown>; readonly output: string; readonly rating?: number; readonly feedback?: string; } /** * Prompt performance metrics */ export interface PromptPerformance { readonly avgRating: number; readonly successRate: number; readonly avgLatency: number; readonly tokenEfficiency: number; readonly costPerUse: MonetaryAmount; } /** * Validate model readiness for production */ export declare function validateModelProduction(model: MLModel, performance: ModelPerformance): Result<boolean, string[]>; /** * Calculate model complexity score */ export declare function calculateModelComplexity(architecture: ModelArchitecture): number; /** * Estimate training time */ export declare function estimateTrainingTime(modelComplexity: number, datasetSize: number, config: TrainingConfig): number; export declare const aiMLTypes: { ModelType: typeof ModelType; MLFramework: typeof MLFramework; ModelStatus: typeof ModelStatus; DatasetType: typeof DatasetType; DataFormat: typeof DataFormat; FeatureType: typeof FeatureType; DataType: typeof DataType; PreprocessingType: typeof PreprocessingType; TrainingStatus: typeof TrainingStatus; DeploymentEnvironment: typeof DeploymentEnvironment; DeploymentStatus: typeof DeploymentStatus; DriftType: typeof DriftType; AICapability: typeof AICapability; validateModelProduction: typeof validateModelProduction; calculateModelComplexity: typeof calculateModelComplexity; estimateTrainingTime: typeof estimateTrainingTime; }; //# sourceMappingURL=ai-ml-types.d.ts.map