Predictive

Predictive Analytics Protocol

Defines predictive models and machine learning configurations for

data-driven decision making and forecasting in ObjectStack applications.

Use Cases:

Lead scoring and conversion prediction
Customer churn prediction
Sales forecasting
Demand forecasting
Anomaly detection in operational data
Customer segmentation and clustering
Price optimization
Recommendation systems

Source: packages/spec/src/ai/predictive.zod.ts

TypeScript Usage

import { EvaluationMetrics, Hyperparameters, ModelDrift, ModelFeature, PredictionRequest, PredictionResult, PredictiveModel, PredictiveModelType, TrainingConfig } from '@objectstack/spec/ai';
import type { EvaluationMetrics, Hyperparameters, ModelDrift, ModelFeature, PredictionRequest, PredictionResult, PredictiveModel, PredictiveModelType, TrainingConfig } from '@objectstack/spec/ai';

// Validate data
const result = EvaluationMetrics.parse(data);

EvaluationMetrics

Properties

Property	Type	Required	Description
accuracy	`number`	optional
precision	`number`	optional
recall	`number`	optional
f1Score	`number`	optional
auc	`number`	optional	Area Under ROC Curve
mse	`number`	optional	Mean Squared Error
rmse	`number`	optional	Root Mean Squared Error
mae	`number`	optional	Mean Absolute Error
r2Score	`number`	optional	R-squared score
silhouetteScore	`number`	optional
daviesBouldinIndex	`number`	optional
mape	`number`	optional	Mean Absolute Percentage Error
smape	`number`	optional	Symmetric MAPE
custom	`Record<string, number>`	optional

Hyperparameters

Properties

Property	Type	Required	Description
learningRate	`number`	optional	Learning rate for training
epochs	`integer`	optional	Number of training epochs
batchSize	`integer`	optional	Training batch size
maxDepth	`integer`	optional	Maximum tree depth
numTrees	`integer`	optional	Number of trees in ensemble
minSamplesSplit	`integer`	optional	Minimum samples to split node
minSamplesLeaf	`integer`	optional	Minimum samples in leaf node
hiddenLayers	`integer[]`	optional	Hidden layer sizes
activation	`string`	optional	Activation function
dropout	`number`	optional	Dropout rate
l1Regularization	`number`	optional	L1 regularization strength
l2Regularization	`number`	optional	L2 regularization strength
numClusters	`integer`	optional	Number of clusters (k-means, etc.)
seasonalPeriod	`integer`	optional	Seasonal period for time series
forecastHorizon	`integer`	optional	Number of periods to forecast
custom	`Record<string, any>`	optional	Algorithm-specific parameters

ModelDrift

Properties

Property	Type	Required	Description
modelName	`string`	✅
driftType	`Enum<'feature_drift' \| 'prediction_drift' \| 'performance_drift'>`	✅
severity	`Enum<'low' \| 'medium' \| 'high' \| 'critical'>`	✅
detectedAt	`string`	✅	ISO timestamp
metrics	`Object`	✅
recommendation	`string`	optional
autoRetrainTriggered	`boolean`	✅

ModelFeature

Properties

Property	Type	Required	Description
name	`string`	✅	Feature name (snake_case)
label	`string`	optional	Human-readable label
field	`string`	✅	Source field name
object	`string`	optional	Source object (if different from target)
dataType	`Enum<'numeric' \| 'categorical' \| 'text' \| 'datetime' \| 'boolean'>`	✅	Feature data type
transformation	`Enum<'none' \| 'normalize' \| 'standardize' \| 'one_hot_encode' \| 'label_encode' \| 'log_transform' \| 'binning' \| 'embedding'>`	✅
required	`boolean`	✅
defaultValue	`any`	optional
description	`string`	optional
importance	`number`	optional	Feature importance score (0-1)

PredictionRequest

Properties

Property	Type	Required	Description
modelName	`string`	✅	Model to use for prediction
recordIds	`string[]`	optional	Specific records to predict (if not provided, uses all)
inputData	`Record<string, any>`	optional	Direct input data (alternative to recordIds)
returnConfidence	`boolean`	✅
returnExplanation	`boolean`	✅

PredictionResult

Properties

Property	Type	Required	Description
modelName	`string`	✅
modelVersion	`string`	✅
recordId	`string`	optional
prediction	`any`	✅	The predicted value
confidence	`number`	optional	Confidence score (0-1)
probabilities	`Record<string, number>`	optional	Class probabilities (for classification)
explanation	`Object`	optional
tokens	`Object`	optional	Token usage for this prediction (if AI-powered)
cost	`number`	optional	Cost for this prediction in USD
metadata	`Object`	optional

PredictiveModel

Properties

Property	Type	Required	Description
name	`string`	✅	Model unique identifier (snake_case)
label	`string`	✅	Model display name
description	`string`	optional
type	`Enum<'classification' \| 'regression' \| 'clustering' \| 'forecasting' \| 'anomaly_detection' \| 'recommendation' \| 'ranking'>`	✅
algorithm	`string`	optional	Specific algorithm (e.g., "random_forest", "xgboost", "lstm")
objectName	`string`	✅	Target object for predictions
target	`string`	✅	Target field to predict
targetType	`Enum<'numeric' \| 'categorical' \| 'binary'>`	optional	Target field type
features	`Object[]`	✅	Input features for the model
hyperparameters	`Object`	optional
training	`Object`	optional
metrics	`Object`	optional	Evaluation metrics from last training
deploymentStatus	`Enum<'draft' \| 'training' \| 'trained' \| 'deployed' \| 'deprecated'>`	✅
version	`string`	✅
predictionField	`string`	optional	Field to store predictions
confidenceField	`string`	optional	Field to store confidence scores
updateTrigger	`Enum<'on_create' \| 'on_update' \| 'manual' \| 'scheduled'>`	✅
autoRetrain	`boolean`	✅
retrainSchedule	`string`	optional	Cron expression for auto-retraining
retrainThreshold	`number`	optional	Performance threshold to trigger retraining
enableExplainability	`boolean`	✅	Generate feature importance & explanations
enableMonitoring	`boolean`	✅
alertOnDrift	`boolean`	✅	Alert when model drift is detected
active	`boolean`	✅
owner	`string`	optional	User ID of model owner
permissions	`string[]`	optional	User/group IDs with access
tags	`string[]`	optional
category	`string`	optional	Model category (e.g., "sales", "marketing", "operations")
lastTrainedAt	`string`	optional	ISO timestamp
createdAt	`string`	optional	ISO timestamp
updatedAt	`string`	optional	ISO timestamp

PredictiveModelType

Allowed Values

classification
regression
clustering
forecasting
anomaly_detection
recommendation
ranking

TrainingConfig

Properties

Property	Type	Required	Description
trainingDataRatio	`number`	✅	Proportion of data for training
validationDataRatio	`number`	✅	Proportion for validation
testDataRatio	`number`	✅	Proportion for testing
dataFilter	`string`	optional	Formula to filter training data
minRecords	`integer`	✅	Minimum records required
maxRecords	`integer`	optional	Maximum records to use
strategy	`Enum<'full' \| 'incremental' \| 'online' \| 'transfer_learning'>`	✅
crossValidation	`boolean`	✅
folds	`integer`	✅	Cross-validation folds
earlyStoppingEnabled	`boolean`	✅
earlyStoppingPatience	`integer`	✅	Epochs without improvement before stopping
maxTrainingTime	`number`	optional	Maximum training time in seconds
gpuEnabled	`boolean`	✅
randomSeed	`integer`	optional	Random seed for reproducibility

On this page